state

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2026 License: LGPL-2.1 Imports: 14 Imported by: 0

README

mod/state

mod/state holds the process-local runtime snapshot: key availability, latest versions, source classification, diagnostics, content checksum, and small serving metadata. It is rebuilt from config and storage during runtime and is not the durable source of truth.

Place in the runtime

flowchart TB
  rescan["mod/rescan"] --> state["mod/state"]
  storage["mod/storage"] --> state
  server["mod/server"] --> state
  state --> snapshots["immutable snapshots"]

Responsibilities

  • Keep fast read snapshots for server handlers.
  • Track key state, availability, source class, latest version, and version count.
  • Track active diagnostics and recent dropped diagnostics.
  • Publish freshness changes for metadata ETags.
  • Provide concurrency-safe reads without exposing mutable internal maps.

Contracts

  • Storage remains durable truth. State can be rebuilt.
  • Writers update state through methods that publish snapshots atomically. One internal mutex serializes all mutations and snapshot publication.
  • Reads are lock-free: public read methods load immutable snapshots through an atomic pointer.
  • Readers receive copies or immutable values and must not mutate internal maps.
  • Diagnostic messages are user-facing and must be in English.
  • The diagnostic registry is capped at 4096 records. On overflow, the oldest deactivated record is evicted in O(1); active diagnostics are never evicted. If the registry is full of active records, the new diagnostic is dropped and the dropped counter is incremented.
  • Deactivated diagnostics keep first-seen, last-seen, and count data until evicted by registry pressure.
  • ClearVersionDiagnostics is intentionally cheap when there is nothing to clear: it must not publish a new snapshot or bump the generation in that case.

Important files

  • obj.go: public types, state object, and internal mutable record types.
  • init.go: construction from config and initial snapshot publication.
  • method.go: key-domain mutations and mirror statistics.
  • registry.go: diagnostic registry, key/version diagnostic clearing, and O(1) inactive eviction.
  • availability.go: upstream availability transitions.
  • checksum.go: content checksum publication.
  • snapshot.go: lock-free reads and snapshot construction.
  • helper.go: validation, key index construction, and snapshot publication helpers.
  • metrics.go: state-related metrics.

Operational notes

State updates should be cheap. Expensive work such as storage scans, archive checks, and artifact builds belongs in mod/rescan or mod/storage; state should only publish the resulting facts.

Full snapshot rebuilds happen on structural diagnostic changes. Key mutations use incremental snapshot publication and are gated on actual state changes; no-op clears and repeated unchanged writes should not advance Generation.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AvailabilityUpdateObj 

type AvailabilityUpdateObj struct {
	Key       string
	Available bool
	Present   bool
	ScanAt    time.Time
}

AvailabilityUpdateObj is one upstream availability scan result.

type ChecksumSetObj 

type ChecksumSetObj struct {
	Content core.HashObj
}

ChecksumSetObj carries the content checksum — the cross-key page-freshness fingerprint (ETags).

type DiagnosticKeyObj 

type DiagnosticKeyObj struct {
	Code    string
	Scope   stcode.LogScopeType
	Key     string
	Version string
}

DiagnosticKeyObj identifies a diagnostic for ClearDiagnostic without aggregate or message fields.

type DiagnosticObj 

type DiagnosticObj struct {
	Code    string
	Scope   stcode.LogScopeType
	Impact  stcode.OperationalStatusType
	Reason  stcode.LogReasonType
	Key     string
	Version string
	Message string
}

DiagnosticObj is the input for RaiseDiagnostic. Identity is code/scope/key/version; Impact and Reason affect health.

type DiagnosticViewObj 

type DiagnosticViewObj struct {
	Code      string
	Scope     stcode.LogScopeType
	Impact    stcode.OperationalStatusType
	Reason    stcode.LogReasonType
	Key       string
	Version   string
	Message   string
	FirstSeen time.Time
	LastSeen  time.Time
	Count     uint64
}

DiagnosticViewObj is the public snapshot of an active diagnostic with first/last-seen counters.

type HealthViewObj 

type HealthViewObj struct {
	Status             stcode.OperationalStatusType
	Reasons            []stcode.LogReasonType
	DiagnosticsCount   uint64
	DroppedDiagnostics uint64
}

HealthViewObj exposes aggregate node health, reasons, and diagnostic counters.

type KeyStateObj 

type KeyStateObj struct {
	Key               string
	Status            stcode.OperationalStatusType
	Classification    stcode.SourceClassType
	Classified        bool
	SourceURL         string
	BrotherURL        string
	RemoteKey         string
	Availability      stcode.AvailabilityStatusType
	UnavailableCycles uint32
	LastScan          time.Time
	UpstreamPresent   bool
	LatestVersion     string
	VersionCount      uint64
	LastPublishTS     time.Time
}

KeyStateObj is the public state snapshot for one mirror. It includes classification, upstream availability, last scan, and version statistics.

type MirrorStatsObj 

type MirrorStatsObj struct {
	Key           string
	LatestVersion string
	VersionCount  uint64
	LastPublishTS time.Time
}

MirrorStatsObj carries mirror statistics from rescan.

type Obj 

type Obj struct {
	// contains filtered or unexported fields
}

Obj holds mirror state and diagnostics. All mutations are serialized by lockObj; reads stay lock-free through the atomic SnapshotObj. Inactive diagnostics live in an intrusive list: an entry is in the list iff !active.

func New 

func New(configObj *stcfg.ConfigObj) (*Obj, error)

New builds a registry from validated config. It seeds release_mirrors, initializes the instance checksum, and publishes the first snapshot.

func (*Obj) ActiveDiagnostics 

func (obj *Obj) ActiveDiagnostics() []DiagnosticViewObj

ActiveDiagnostics returns active diagnostics from the current snapshot, sorted by LastSeen desc.

func (*Obj) ApplyAvailabilityBatch 

func (obj *Obj) ApplyAvailabilityBatch(updateArr []AvailabilityUpdateObj) error

ApplyAvailabilityBatch applies availability updates atomically and publishes one snapshot. Stale scans are ignored; duplicate keys in the batch are rejected.

func (*Obj) Checksums 

func (obj *Obj) Checksums() ChecksumSetObj

Checksums returns checksums from the current snapshot.

func (*Obj) ClearAllDiagnostics 

func (obj *Obj) ClearAllDiagnostics()

ClearAllDiagnostics deactivates all active diagnostics in the registry.

func (*Obj) ClearDiagnostic 

func (obj *Obj) ClearDiagnostic(diagnosticObj DiagnosticKeyObj) error

ClearDiagnostic deactivates one diagnostic by identity; the record remains until eviction.

func (*Obj) ClearKeyDiagnostics 

func (obj *Obj) ClearKeyDiagnostics(key string) error

ClearKeyDiagnostics deactivates all active diagnostics for a key through the key index.

func (*Obj) ClearVersionDiagnostics 

func (obj *Obj) ClearVersionDiagnostics(key string, version string) error

ClearVersionDiagnostics deactivates active diagnostics for one key version.

func (*Obj) Generation 

func (obj *Obj) Generation() uint64

Generation returns the monotonic snapshot generation number.

func (*Obj) Health 

func (obj *Obj) Health() HealthViewObj

Health returns health from the current snapshot.

func (*Obj) KeyState 

func (obj *Obj) KeyState(key string) (KeyStateObj, bool)

KeyState returns key state from the current snapshot; ok=false for unknown keys.

func (*Obj) KeyStates 

func (obj *Obj) KeyStates() []KeyStateObj

KeyStates returns a copy of all key states from the current snapshot.

func (*Obj) MarkAvailable 

func (obj *Obj) MarkAvailable(key string, present bool, scanAt time.Time) error

MarkAvailable records an available upstream scan and resets the unavailable counter.

func (*Obj) MarkUnavailable 

func (obj *Obj) MarkUnavailable(key string, scanAt time.Time) error

MarkUnavailable records an unavailable upstream scan and switches to permanent-down after the configured limit.

func (*Obj) RaiseDiagnostic 

func (obj *Obj) RaiseDiagnostic(diagnosticObj DiagnosticObj) error

RaiseDiagnostic creates or updates a diagnostic. Repeating the same active diagnostic bumps count/lastSeen in place and republishes a rebuilt, LastSeen-sorted snapshot. A full registry with no inactive record to evict returns an error and increments dropped diagnostics.

func (*Obj) RegisterMetrics 

func (obj *Obj) RegisterMetrics(meterObj metric.Meter) error

RegisterMetrics publishes errors group metrics from the Error Registry: 

diagnostics_active: active diagnostic count (gauge);
recent_error{code,scope,impact,reason,key,version}: one series per recent diagnostic with value=count,
  capped by metrics.errors.recent_buffer to limit cardinality.

ActiveDiagnostics sorts by LastSeen descending, so the buffer keeps the newest records. A nil meter is a no-op; state depends only on neutral otel/metric and attribute types.

func (*Obj) SetClassification 

func (obj *Obj) SetClassification(key string, classObj stcode.SourceClassType, sourceURL string, brotherURL string) error

SetClassification records a key source type and URL. Reclassification is blocked until permanent-down recovery allows it, and it changes Instance.

func (*Obj) SetContentChecksum 

func (obj *Obj) SetContentChecksum(contentObj core.HashObj)

SetContentChecksum updates the content checksum: the cross-key page-freshness fingerprint used in ETags.

func (*Obj) SetLastRescan 

func (obj *Obj) SetLastRescan(ts time.Time)

SetLastRescan records the last rescan time used for metadata TTL and Cache-Control.

func (*Obj) SetMirrorStats 

func (obj *Obj) SetMirrorStats(statsObj MirrorStatsObj) error

SetMirrorStats updates statistics for one mirror through SetMirrorStatsBatch.

func (*Obj) SetMirrorStatsBatch 

func (obj *Obj) SetMirrorStatsBatch(statsArr []MirrorStatsObj) error

SetMirrorStatsBatch applies mirror statistics atomically and publishes one snapshot. Duplicate keys in the batch are rejected.

func (*Obj) SetRemoteKey 

func (obj *Obj) SetRemoteKey(key string, remoteKey string) error

SetRemoteKey stores the remote key for a brother source. Empty remoteKey normalizes to the local key for root-form compatibility; the call is idempotent.

func (*Obj) Snapshot 

func (obj *Obj) Snapshot() SnapshotObj

Snapshot returns the current immutable snapshot without locking. Nil, copied and unpublished registries yield a zero SnapshotObj.

type SnapshotObj 

type SnapshotObj struct {
	Checksums  ChecksumSetObj
	LastRescan time.Time
	Generation uint64
	// contains filtered or unexported fields
}

SnapshotObj is an immutable state snapshot published atomically. It is never mutated after publication; collection getters return copies.

func (SnapshotObj) ActiveDiagnostics 

func (obj SnapshotObj) ActiveDiagnostics() []DiagnosticViewObj

ActiveDiagnostics returns a copy of active diagnostics, sorted by LastSeen desc.

func (SnapshotObj) Health 

func (obj SnapshotObj) Health() HealthViewObj

Health returns snapshot health and copies Reasons to avoid sharing the immutable slice.

func (SnapshotObj) KeyState 

func (obj SnapshotObj) KeyState(key string) (KeyStateObj, bool)

KeyState returns key state from the snapshot; ok=false for unknown keys.

func (SnapshotObj) KeyStates 

func (obj SnapshotObj) KeyStates() []KeyStateObj

KeyStates returns a copy of all key states.

func (SnapshotObj) RecentDiagnostics 

func (obj SnapshotObj) RecentDiagnostics(limit int) []DiagnosticViewObj

RecentDiagnostics returns a copy of at most limit newest active diagnostics. Only the result is copied to bound hot-read path cost.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.