state

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package state is the record of one app on disk: state.json holds a record per copy (its process, port, start time, crash history and the time it began to drain), the app's revision, and the settings the copies were started from. Files are replaced whole and never edited in place, and Lock serializes the cycle, the exit-watchers and the handlers that read and write one.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Lock

func Lock(path string) (unlock func())

Lock takes the lock for path and returns the matching unlock. Hold it across the whole Load → decide → act → Save cycle, not just the Save — the point is that nobody else's decision gets made on state this caller is about to change. Not reentrant: a caller already holding it must not call anything that takes it again.

func Save

func Save(path string, state State) error

Save writes state to path atomically (see atomicfile.Write): a crash or a concurrent reader mid-write sees the old document or the new one, never a truncated half — which Load would otherwise reject on every tick from then on, permanently wedging reconciliation for that app with no way out short of deleting the file by hand.

Types

type AppState

type AppState struct {
	Name string `json:"name"`
	PID  int    `json:"pid"`

	// Port is the port the process listens on. For a copy (Copy >= 1) it is
	// an internal port on 127.0.0.1, behind the load balancer that holds the
	// app's own port. A record without a copy number was written by a build
	// before the load balancer, and its process holds the app's port itself
	// (see reconcile.DecideCopies' upgrade).
	Port int `json:"port"`

	// Copy numbers the app's processes from 1. Zero marks a record from
	// before the load balancer.
	Copy           int       `json:"copy,omitempty"`
	EntrypointFile string    `json:"entrypoint-file"`
	StartedAt      time.Time `json:"started-at"`
	CrashCount     int       `json:"crash-count"`
	LastExitAt     time.Time `json:"last-exit-at"`
	LastExitFailed bool      `json:"last-exit-failed"`

	// StartedFrom is manifest.AppSpec.StartFields() at the time the process
	// was started: the settings that shaped it beyond the typed fields
	// above. A key that is absent means unknown, not changed (records from
	// before the key existed have no such key), so it never triggers a
	// restart.
	StartedFrom map[string]string `json:"started-from,omitempty"`

	// Revision is State.Revision when this copy was started. A copy whose
	// revision is below the state's runs code from before the last restart.
	// Absent means 0.
	Revision int `json:"revision,omitempty"`

	// DrainingSince is when the copy began draining: it gets no new visitors
	// and keeps the ones it has until their sessions end or the app's
	// drain-timeout passes, and it is never started again. Zero means it is
	// not draining.
	DrainingSince time.Time `json:"draining-since,omitzero"`

	// SkipDrain says the copy stops instead of draining when it is replaced
	// or already draining: set by apply or restart with --now on the copies
	// running then, so the switch, which comes later, still knows.
	SkipDrain bool `json:"skip-drain,omitempty"`
}

AppState is what shinyctl-api last recorded about one app's process: identity (PID, name, port, entrypoint, when it was started), the rest of the manifest it was started from, plus the crash history the reconcile loop's backoff and restart-policy decisions are made from.

type State

type State struct {
	AppGroup string `json:"app-group"`

	// Revision is raised by restart. Absent means 0. A copy that was started
	// at a lower revision is outdated.
	Revision int `json:"revision,omitempty"`

	Apps []AppState `json:"apps"`
}

State is the on-disk shape of one app's state.json.

Apps holds one record per copy of the app, sorted by copy number. A file from a build before several copies (one record, copy 1, no revision) reads as copy 1 at revision 0 under a state at revision 0, so nothing needs migrating. A record with copy 0 is from before the load balancer, and is only ever the sole record.

A record without draining-since or skip-drain is a copy that is not draining and has no mark, which is every record written before them.

func Load

func Load(path string) (State, error)

Load reads the state file at path. A missing file is an empty State, not an error — it's what a never-started app looks like.

func (State) Copies

func (s State) Copies() []AppState

Copies returns the records sorted by copy number, as a new slice.

func (State) Copy

func (s State) Copy(n int) (AppState, bool)

Copy returns the record of copy n.

func (*State) Put

func (s *State) Put(a AppState)

Put replaces the record with a's copy number, or adds it, keeping the records sorted.

func (*State) Remove

func (s *State) Remove(n int)

Remove drops the record of copy n, if there is one.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL