status

status

import "github.com/agentstation/starmap/runtime/status"

Package status owns the observable vocabulary of a connected catalog runtime. It holds the status report, the health and freshness grades, the source kinds, and the sanitized source chain hop.

The package is a leaf. It reads no catalog source and opens no connection. A server that renders runtime status therefore depends on this vocabulary alone. It never depends on the attested source machinery that the runtime package carries.

Index

• type Freshness
  • func (f Freshness) String() string
• type Health
  • func (h Health) String() string
• type Publication
• type RetentionStatus
• type SourceHop
• type SourceKind
  • func SourceKinds() []SourceKind
  • func (k SourceKind) Custom() bool
  • func (k SourceKind) String() string
  • func (k SourceKind) Valid() bool
• type Status

type Freshness

Freshness is the evaluated age of one observed timestamp.

type Freshness string

const (
    // FreshnessUnknown means no observation supports an evaluation yet.
    FreshnessUnknown Freshness = "unknown"

    // FreshnessCurrent means the age is inside every threshold.
    FreshnessCurrent Freshness = "current"

    // FreshnessWarn means the age passed the warning threshold.
    FreshnessWarn Freshness = "warn"

    // FreshnessCritical means the age passed the critical threshold.
    FreshnessCritical Freshness = "critical"
)

func (Freshness) String

func (f Freshness) String() string

String returns the wire value of the freshness level.

type Health

Health is the operator-facing state of one runtime component.

type Health string

const (
    // HealthUnknown means the component has not reported yet.
    HealthUnknown Health = "unknown"

    // HealthOK means the component reached its last objective.
    HealthOK Health = "ok"

    // HealthDegraded means the component works with reduced evidence.
    HealthDegraded Health = "degraded"

    // HealthUnavailable means the component cannot reach its dependency.
    HealthUnavailable Health = "unavailable"
)

func (Health) String

func (h Health) String() string

String returns the wire value of the health state.

type Publication

Publication summarizes verified run evidence without copying source or review lists.

type Publication struct {
    RunID            string
    ReceiptChecksum  string
    SourceCommit     string
    GenerationID     string
    CompletedAt      time.Time
    FreshAcquisition bool
    SourceCount      int
    ReviewCount      int
}

type RetentionStatus

RetentionStatus reports the last runtime collection pass without reading storage. Counts and bytes exclude backend replication and filesystem overhead.

type RetentionStatus struct {
    Enabled               bool
    Interval              time.Duration
    MaxGenerations        int
    MaxBytes              int64
    ScanEntries           int
    InputMaxBytes         int64
    AttemptedAt           time.Time
    SucceededAt           time.Time
    Health                Health
    Reason                string
    GenerationCollection  string
    Generations           int
    GenerationBytes       int64
    ProtectedGenerations  int
    ProtectedBytes        int64
    RemovedGenerations    int
    ScannedInputs         int
    InputBytes            int64
    RemovedInputs         int
    OverLimit             bool
    PublicationAccounting bool
    Publications          storage.PublicationRetentionReport
}

type SourceHop

SourceHop is one sanitized entry in an upstream source chain. A hop names the reporting identity and its health, never an address.

type SourceHop struct {
    Identity    string
    Health      Health
    PublishedAt time.Time
    ObservedAt  time.Time
}

type SourceKind

SourceKind names one supported upstream catalog source. Selection is terminal: a deployment that names a custom source never falls back to the public GitHub channel.

type SourceKind string

const (
    // SourcePublic reads the attested public GitHub catalog channel of the
    // Starmap project. It is the default.
    SourcePublic SourceKind = "public"

    // SourceGitHub reads an attested catalog channel from a named repository.
    SourceGitHub SourceKind = "github"

    // SourceStarmap reads from another Starmap runtime. The cascade client is
    // an injected composition, because the root package holds no HTTP client.
    SourceStarmap SourceKind = "starmap"

    // SourceFile reads one immutable generation from a local path.
    SourceFile SourceKind = "file"

    // SourceEmbedded pins the runtime to the verified embedded bootstrap and
    // contacts no external system.
    SourceEmbedded SourceKind = "embedded"
)

func SourceKinds

func SourceKinds() []SourceKind

SourceKinds returns a caller-owned copy of every accepted source name.

func (SourceKind) Custom

func (k SourceKind) Custom() bool

Custom reports whether the kind names a deployment-owned source. A custom source never falls back to the public channel.

func (SourceKind) String

func (k SourceKind) String() string

String returns the wire value of the source kind.

func (SourceKind) Valid

func (k SourceKind) Valid() bool

Valid reports whether the kind is one of the accepted source names.

type Status

Status is the operator-facing state of one connected runtime. It keeps usability, freshness, fallback, direct source health, and upstream-reported health as five independent values, so a warning on one never hides another.

type Status struct {
    // RecoveryBaselineSHA256 identifies an explicit retained recovery baseline.
    RecoveryBaselineSHA256 string `json:"recovery_baseline_sha256,omitempty"`
    // UpstreamPublication summarizes run evidence independently of catalog and channel age.
    UpstreamPublication *Publication
    // Retention reports collection capability, bounded usage, and the last maintenance outcome.
    Retention RetentionStatus

    // Usable reports whether the catalog can serve new work under the startup policy.
    // An internal authority also requires a retained, current permission receipt.
    Usable bool

    // CatalogAvailable reports metadata availability independently of permission.
    CatalogAvailable bool
    // AuthorityRequired reports whether an internal authority controls catalog use.
    AuthorityRequired bool
    // AuthorityReady reports whether the active catalog enforces the required revision.
    AuthorityReady bool
    // PermissionValid reports whether the retained receipt currently permits new work.
    PermissionValid bool
    // RequiredPermissionRevision is the highest authenticated requirement.
    RequiredPermissionRevision string
    // EnforcedPermissionRevision is the active catalog's permission revision.
    EnforcedPermissionRevision string
    // PermissionValidUntil is the confirmed receipt's expiry before the runtime subtracts clock uncertainty.
    PermissionValidUntil time.Time

    // GenerationPin is the retained generation selected by configuration.
    GenerationPin string

    // GenerationID identifies the served catalog generation.
    GenerationID string

    // PayloadChecksum is the digest of the served catalog payload.
    PayloadChecksum string

    // CatalogAge is the age of the served generation.
    CatalogAge time.Duration

    // Freshness grades the age of the served generation.
    Freshness Freshness

    // ChannelUpdatedAt is the origin publication time that the upstream chain
    // propagated. Every hop carries the same value, so a downstream grades the
    // age of the origin channel and not only its own check.
    ChannelUpdatedAt time.Time

    // ChannelAge is the age of the propagated origin publication time.
    ChannelAge time.Duration

    // ChannelFreshness grades the age of the propagated origin publication
    // time. A cascade that stalls at any hop degrades every hop below it.
    ChannelFreshness Freshness

    // SourceCheckAge is the age of the last upstream check.
    SourceCheckAge time.Duration

    // SourceCheckFreshness grades the age of the last upstream check.
    SourceCheckFreshness Freshness

    // AcquisitionAge is the age of the last acquisition success.
    AcquisitionAge time.Duration

    // AcquisitionFreshness grades the age of the last acquisition success.
    AcquisitionFreshness Freshness

    // Fallback reports whether the runtime serves the embedded catalog because
    // no upstream generation is active.
    Fallback bool

    // FallbackReason names why the runtime fell back.
    FallbackReason string

    // SourceHealth is what this runtime observed while it read its own source.
    SourceHealth Health

    // SourceReason is the safe reason code of the last source failure.
    SourceReason string

    // UpstreamHealth is the health the upstream reported about itself. It stays
    // independent of SourceHealth, so a healthy transfer of a degraded upstream
    // catalog still reports the degradation.
    UpstreamHealth Health

    // AcquisitionHealth is the state of the last acquisition run.
    AcquisitionHealth Health

    // InstanceIdentity is the stable identity of this runtime inside a fleet.
    // A downstream compares it against a served source chain, so a cascade
    // rejects a self reference that URL comparison cannot detect.
    InstanceIdentity string

    // SourceIdentity is the safe identity of the selected source.
    SourceIdentity string

    // SourceKind names the selected source.
    SourceKind SourceKind

    // Chain is the sanitized upstream source chain, nearest hop first.
    Chain []SourceHop

    // Lease reports the runtime lease state.
    Lease string

    // LastRunID identifies the last refresh run.
    LastRunID string

    // Providers holds one terminal attempt per provider or binding of the last run.
    Providers []sources.ProviderAttempt

    // AcceptedAcquisitionSources identifies local acquisition evidence in the active generation.
    // It excludes distribution baseline receipts and is independent of the last attempt.
    AcceptedAcquisitionSources []sources.ID `json:"accepted_acquisition_sources"`

    // SourceObservations holds the last non-provider acquisition receipts.
    SourceObservations []catalogs.SourceObservationLink

    // SourceConfiguration holds the passive composition and configured selection.
    SourceConfiguration []sources.SourceActivity `json:"source_configuration"`

    // SourceActivities holds activity from the last acquisition run.
    SourceActivities []sources.SourceActivity `json:"source_activities,omitempty"`

    // StartedAt is when the runtime opened.
    StartedAt time.Time

    // ObservedAt is when the runtime built this report.
    ObservedAt time.Time
}

Generated by gomarkdoc