Help us shape the future of Go! Take the 2026 Go Developer Survey

state

package
v0.92.1-rc.4 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package state is beekeeper's shared memory on the machine: the supervisor and its relay, grants, holds, registered agents, notes, timers and session records, one JSON document read and rewritten under an exclusive file lock, plus an append-only event log of every change and of every build run. It outlives any session: a restarted supervisor or its successor reads what the previous one knew instead of rebuilding it from prose.

Index

Constants

View Source 
const (
	RepeatDaily    = "daily"
	RepeatWeekdays = "weekdays"
	RepeatWeekly   = "weekly"
)

The values of Timer.Repeat.

View Source 
const (
	Waiting  = "waiting"
	Running  = "running"
	Settling = "settling"
)

The phases of a Merge.

View Source 
const ModeBypass = "bypassPermissions"

ModeBypass is Claude Code's bypassPermissions mode.

View Source 
const VerbStaleWriter = "state.stale-writer"

VerbStaleWriter is the event of an older beekeeper's first save after a newer one's.

Variables

View Source 
var Repeats = []string{RepeatDaily, RepeatWeekdays, RepeatWeekly}

Repeats are the values of Timer.Repeat.

Functions

func Due added in v0.9.0 

func Due(due, fired, now time.Time) bool

Due reports whether a watch has yet to report something due by now.

func Weekend added in v0.91.0 

func Weekend(t time.Time) bool

Weekend reports whether t falls on a Saturday or a Sunday.

Types

type Agent 

type Agent struct {
	Party
	Registered time.Time `json:"registered"`
	Task       string    `json:"task,omitempty"`
	AssignedAt time.Time `json:"assignedAt,omitzero"`
	IdleSince  time.Time `json:"idleSince,omitzero"`
	LastTask   string    `json:"lastTask,omitempty"`
	// Keep marks an idle entry kept on purpose (agents keep): the doctor
	// never removes it for staleness nor archives its desktop session.
	Keep *Keep `json:"keep,omitempty"`
	// Park marks an agent that keeps its task but waits on a note, a pull
	// request or a person without holding a busy slot (agents park).
	Park *Park `json:"park,omitempty"`
	// Done says the agent reported its work finished (agents idle --done):
	// the doctor takes it off the roster and archives its desktop session
	// once its CLI is idle.
	Done bool `json:"done,omitempty"`
	// DesktopTurn is when the agent asked for a desktop turn (agents
	// desktop, agents start --desktop): the import or reopen after its
	// headless turn shows it in the desktop without waiting for the
	// desktop's window to lose the focus. Zero: none asked, or the desktop
	// was given it.
	DesktopTurn time.Time `json:"desktopTurn,omitzero"`
	// Import is the wait of the reopen that shows the agent in the desktop,
	// while it waits; nil: none waits.
	Import *ImportWait `json:"import,omitempty"`
	// ResumedWait is when the reopen after a headless turn that ended on a
	// background wait, its task open, resumed the agent headless (once per
	// task), and ResumedOn the wait it named; zero: never.
	ResumedWait time.Time `json:"resumedWait,omitzero"`
	ResumedOn   string    `json:"resumedOn,omitempty"`
	// Conversation is klaus-gateway's conversation the agent holds with its
	// person, a Slack thread; empty: none is open.
	Conversation string `json:"conversation,omitempty"`
	// contains filtered or unexported fields
}

Agent is an empty session registered as spare capacity.

func (Agent) MarshalJSON added in v0.73.0 

func (v Agent) MarshalJSON() ([]byte, error)

func (*Agent) UnmarshalJSON added in v0.73.0 

func (v *Agent) UnmarshalJSON(b []byte) error

type AlertOwner added in v0.68.0 

type AlertOwner struct {
	// Alert is the alert's key in the alert baseline (fingerprint@start).
	Alert string    `json:"alert"`
	Name  string    `json:"name"`
	By    Party     `json:"by"`
	At    time.Time `json:"at"`
	// Ended is when a watch saw the owner's session gone.
	Ended time.Time `json:"ended,omitzero"`
	// contains filtered or unexported fields
}

AlertOwner is the session that owns a firing alert (alerts own), until the session ends or the alert resolves. A party without a session id is a person, who owns it until it resolves.

func (AlertOwner) MarshalJSON added in v0.73.0 

func (v AlertOwner) MarshalJSON() ([]byte, error)

func (AlertOwner) Person added in v0.68.0 

func (o AlertOwner) Person() bool

Person reports whether the owner is a person rather than a session.

func (*AlertOwner) UnmarshalJSON added in v0.73.0 

func (v *AlertOwner) UnmarshalJSON(b []byte) error

type Archive added in v0.63.0 

type Archive struct {
	// Party is the agent that left the roster.
	Party
	// Host is its desktop session.
	Host  string    `json:"host"`
	Since time.Time `json:"since"`
	// Why says why it stayed the last time.
	Why string `json:"why"`
	// Tries counts the stewards' turns asked for it, Tried the last.
	Tries int       `json:"tries,omitempty"`
	Tried time.Time `json:"tried,omitzero"`
	// contains filtered or unexported fields
}

Archive is the desktop session of an agent that left the roster while its archive could not be done (its CLI ran a turn, no steward recorded it): the doctor asks for it again until the desktop records it.

func (Archive) MarshalJSON added in v0.73.0 

func (v Archive) MarshalJSON() ([]byte, error)

func (*Archive) UnmarshalJSON added in v0.73.0 

func (v *Archive) UnmarshalJSON(b []byte) error

type Budget added in v0.6.0 

type Budget struct {
	Remaining int       `json:"remaining"`
	Limit     int       `json:"limit"`
	Reset     time.Time `json:"reset"`
	At        time.Time `json:"at"`
	// contains filtered or unexported fields
}

Budget is one reading of the GitHub core budget.

func (Budget) MarshalJSON added in v0.73.0 

func (v Budget) MarshalJSON() ([]byte, error)

func (*Budget) UnmarshalJSON added in v0.73.0 

func (v *Budget) UnmarshalJSON(b []byte) error

type CLI added in v0.14.1 

type CLI struct {
	Supervisor Party     `json:"supervisor"`
	Since      time.Time `json:"since"`
	PID        int       `json:"pid,omitempty"`
	Gone       time.Time `json:"gone,omitzero"`
	// contains filtered or unexported fields
}

CLI is what beekeeper saw of the supervisor's CLI process in the term Supervisor and Since name: the PID it ran as and since when it has been gone. A CLI back under the same session within supervisor.restartGrace of Gone is a restart; the grant rule holds whether it comes back or not.

func (CLI) MarshalJSON added in v0.73.0 

func (v CLI) MarshalJSON() ([]byte, error)

func (*CLI) Of added in v0.14.1 

func (c *CLI) Of(sup *Supervisor) bool

Of reports whether the record is about sup's current term.

func (*CLI) UnmarshalJSON added in v0.73.0 

func (v *CLI) UnmarshalJSON(b []byte) error

type Decline added in v0.91.1 

type Decline struct {
	Host string    `json:"host"`
	At   time.Time `json:"at"`
	Why  string    `json:"why"`
	// contains filtered or unexported fields
}

Decline is a steward's answer to an archive request that archived nothing: its desktop session, when, and the first line of its reply.

func (Decline) MarshalJSON added in v0.91.1 

func (v Decline) MarshalJSON() ([]byte, error)

func (*Decline) UnmarshalJSON added in v0.91.1 

func (v *Decline) UnmarshalJSON(b []byte) error

type Event 

type Event struct {
	At     time.Time `json:"at"`
	By     Party     `json:"by"`
	Verb   string    `json:"verb"`
	Detail string    `json:"detail"`
}

Event is one line of events.jsonl. At is written in UTC (RFC 3339 with a trailing Z), so a reader can compare it as a string.

type FileStore added in v0.74.0 

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

FileStore is the Store in a directory of the machine: state.json under a flock, events.jsonl beside it.

func Open 

func Open(dir string) (*FileStore, error)

Open returns the file store in dir, creating the directory.

func (*FileStore) Dir added in v0.74.0 

func (s *FileStore) Dir() string

Dir is the store's directory.

func (*FileStore) Events added in v0.74.0 

func (s *FileStore) Events(n int, keep func(Event) bool) ([]Event, error)

Events returns the last n events keep accepts, oldest first (all when n <= 0, every event when keep is nil).

func (*FileStore) Log added in v0.74.0 

func (s *FileStore) Log(events ...Event) error

Log appends events that change no state, a build's run for one, under the state lock. It waits at most logWait for the lock, so that a caller on every build's path never queues behind a slow update.

func (*FileStore) Peek added in v0.74.0 

func (s *FileStore) Peek() (*State, error)

Peek returns the current state without taking the lock, for a caller that must never wait on it (a permission hook): a write replaces the file in one rename, so the document read is always a whole one.

func (*FileStore) Read added in v0.74.0 

func (s *FileStore) Read() (*State, error)

Read returns the current state under a shared lock.

func (*FileStore) ReadFile added in v0.74.0 

func (s *FileStore) ReadFile(name string, v any) (found bool, err error)

ReadFile decodes a JSON side file of the store (the last snapshot); found is false when it does not exist yet.

func (*FileStore) Update added in v0.74.0 

func (s *FileStore) Update(fn func(*State) ([]Event, error)) error

Update runs fn on the state under the exclusive lock and writes the result back atomically together with the events fn returns. When fn fails nothing is written.

func (*FileStore) WriteFile added in v0.74.0 

func (s *FileStore) WriteFile(name string, v any) error

WriteFile atomically replaces a JSON side file of the store.

type Grant 

type Grant struct {
	Resource string    `json:"resource"`
	To       Party     `json:"to"`
	By       Party     `json:"by"`
	At       time.Time `json:"at"`
	// UpgradeUnblock is why the supervisor granted a claim that the
	// resource's upgrade hold admits: the work that unblocks the upgrade.
	UpgradeUnblock string `json:"upgradeUnblock,omitempty"`
	// contains filtered or unexported fields
}

Grant is the supervisor's word that a session may claim a resource.

func (Grant) MarshalJSON added in v0.73.0 

func (v Grant) MarshalJSON() ([]byte, error)

func (*Grant) UnmarshalJSON added in v0.73.0 

func (v *Grant) UnmarshalJSON(b []byte) error

type Hold 

type Hold struct {
	Target string    `json:"target"`
	Reason string    `json:"reason"`
	By     Party     `json:"by"`
	At     time.Time `json:"at"`
	Until  time.Time `json:"until,omitzero"`
	// Except is what a merge hold lets through: a repository (the tool's own
	// during a tool-release window) or one pull request, owner/repo#n.
	Except string `json:"except,omitempty"`
	// Tool is the binary whose release window this hold is, ToolFrom the
	// version it reported when the window opened, ToolPR the pull request
	// that opened it, ToolMerged whether it merged and ToolRelease the release
	// it produced. The window closes once the tool reports another version
	// than ToolFrom and no merge of its repository runs, or once its merge
	// ended with nothing merged or no release warranted. ToolUpdated is when
	// beekeeper last ran the tool's update for a merged window.
	Tool        string    `json:"tool,omitempty"`
	ToolFrom    string    `json:"toolFrom,omitempty"`
	ToolPR      int       `json:"toolPR,omitempty"`
	ToolMerged  bool      `json:"toolMerged,omitempty"`
	ToolRelease string    `json:"toolRelease,omitempty"`
	ToolUpdated time.Time `json:"toolUpdated,omitzero"`
	// LiftWhen is a shell command on this machine; the watch lifts the hold
	// once it exits 0.
	LiftWhen string `json:"liftWhen,omitempty"`
	// UpgradeTo is the target release of the upgrade an automatic upgrade
	// hold stands for.
	UpgradeTo string `json:"upgradeTo,omitempty"`
	// LiftedBy and LiftedAt record the lift of an upgrade hold: the watch
	// keeps a lifted hold, inactive, for as long as its upgrade runs.
	LiftedBy *Party    `json:"liftedBy,omitempty"`
	LiftedAt time.Time `json:"liftedAt,omitzero"`
	// contains filtered or unexported fields
}

Hold stops work on a target (a repository's merges, "github" for every GitHub call) until it is lifted or Until passes.

func (Hold) Active 

func (h Hold) Active(now time.Time) bool

Active reports whether the hold still applies at now.

func (Hold) Excepts added in v0.8.0 

func (h Hold) Excepts(repo string, pr int) bool

Excepts reports whether the hold lets a merge of repo#pr through.

func (Hold) Expired added in v0.25.10 

func (h Hold) Expired(now time.Time) bool

Expired reports whether the hold's time has passed at now.

func (Hold) MarshalJSON added in v0.73.0 

func (v Hold) MarshalJSON() ([]byte, error)

func (*Hold) UnmarshalJSON added in v0.73.0 

func (v *Hold) UnmarshalJSON(b []byte) error

type ImportWait added in v0.71.0 

type ImportWait struct {
	On    string    `json:"on"`
	Since time.Time `json:"since"`
	Until time.Time `json:"until"`
	// contains filtered or unexported fields
}

ImportWait is a reopen waiting to show a session in the desktop: what holds it, since when, and its bound.

func (ImportWait) MarshalJSON added in v0.73.0 

func (v ImportWait) MarshalJSON() ([]byte, error)

func (*ImportWait) Pending added in v0.71.0 

func (w *ImportWait) Pending(now time.Time) bool

Pending reports whether the wait still runs at now: a reopen that died leaves its record behind, past its bound.

func (*ImportWait) UnmarshalJSON added in v0.73.0 

func (v *ImportWait) UnmarshalJSON(b []byte) error

type Keep added in v0.71.0 

type Keep struct {
	By     Party     `json:"by"`
	At     time.Time `json:"at"`
	Until  time.Time `json:"until,omitzero"`
	Reason string    `json:"reason,omitempty"`
	// contains filtered or unexported fields
}

Keep is a roster entry's keep marker: who set it, when, why, and until when (zero: until lifted).

func (*Keep) Holds added in v0.71.0 

func (k *Keep) Holds(now time.Time) bool

Holds reports whether the marker still keeps its entry at now.

func (Keep) MarshalJSON added in v0.73.0 

func (v Keep) MarshalJSON() ([]byte, error)

func (*Keep) UnmarshalJSON added in v0.73.0 

func (v *Keep) UnmarshalJSON(b []byte) error

type Merge added in v0.6.0 

type Merge struct {
	Repo string `json:"repo"`
	PR   int    `json:"pr"`
	Lane string `json:"lane"`
	By   Party  `json:"by"`
	PID  int    `json:"pid"`
	// Child is a running merge's devctl, in a session of its own: it merges
	// on when the gate's caller, or the gate, is gone.
	Child int    `json:"child,omitempty"`
	Phase string `json:"phase"`
	// Joined orders the queue; a rerun within the queue TTL keeps it.
	Joined  time.Time `json:"joined"`
	Seen    time.Time `json:"seen"`
	Started time.Time `json:"started,omitzero"`
	// Finished and Exit are when and how the merge's run ended; on a
	// waiting merge, the failed attempt whose place it keeps (Retrying).
	Finished time.Time `json:"finished,omitzero"`
	Exit     int       `json:"exit,omitempty"`
	// Seeded marks a place queued on a session's behalf (lanes queue): it
	// survives refusals and keeps the seed TTL until the merge runs.
	Seeded bool `json:"seeded,omitempty"`
	// Outside marks a merge run outside the gate (lanes settle): waiting, it
	// heads its lane until its own devctl pr merge runs or GitHub reports it
	// merged; merged, it settles its lane like a gated merge.
	Outside bool `json:"outside,omitempty"`
	// Checked is when GitHub last reported an outside merge not merged yet.
	Checked time.Time `json:"checked,omitzero"`
	// Release is the tag the merge released, empty when unknown.
	Release string `json:"release,omitempty"`
	// Roll names the HelmReleases (namespace/name) that must reach Release
	// before the lane frees.
	Roll []string `json:"roll,omitempty"`
	// contains filtered or unexported fields
}

Merge is one devctl pr merge the gate holds in its lane's queue.

func (Merge) Key added in v0.6.0 

func (m Merge) Key() string

Key is the merge's repository and number, owner/repo#n, or owner/repo promote for a promotion (PR 0).

func (Merge) MarshalJSON added in v0.73.0 

func (v Merge) MarshalJSON() ([]byte, error)

func (Merge) Retrying added in v0.13.2 

func (m Merge) Retrying() bool

Retrying says whether a waiting merge is a failed attempt that keeps its place for its session's retry of the same pull request.

func (*Merge) UnmarshalJSON added in v0.73.0 

func (v *Merge) UnmarshalJSON(b []byte) error

type Note 

type Note struct {
	ID   int       `json:"id"`
	For  string    `json:"for,omitempty"`
	Text string    `json:"text"`
	Due  time.Time `json:"due,omitzero"`
	// Default is what happens when nobody answers by Due.
	Default string    `json:"default,omitempty"`
	By      Party     `json:"by"`
	At      time.Time `json:"at"`
	// Fired is when a watch reported the note due; it reports it once.
	Fired time.Time `json:"fired,omitzero"`
	// Kind is "decision" for a note that waits on a person, "memo" for a
	// session's own record, "login" for a sign-in the watch closes once
	// Until, a shell command, exits 0; a note filed before kinds has none.
	Kind  string `json:"kind,omitempty"`
	Until string `json:"until,omitempty"`
	// Pinned is a standing instruction: every hand-over carries it until it
	// is unpinned or done.
	Pinned bool `json:"pinned,omitempty"`
	// Refs are the issues and pull requests (owner/repo#n) the note asks
	// about: once every one is closed or merged, the watch closes the note
	// as overtaken. Without refs the note is linked to its filing session,
	// and closes once that session is archived.
	Refs []string `json:"refs,omitempty"`
	// Question, StatusQuo, Options ("<label>: <consequence>" each) and
	// Recommend (the recommended option, 1-based) are a decision's parts as
	// its message renders them; Text joins them for the terminal.
	Question  string   `json:"question,omitempty"`
	StatusQuo string   `json:"statusQuo,omitempty"`
	Options   []string `json:"options,omitempty"`
	Recommend int      `json:"recommend,omitempty"`
	// Posted is the gateway's handle on the decision's message, once posted.
	Posted string `json:"posted,omitempty"`
	// contains filtered or unexported fields
}

Note is an open item: a question for a person, a deadline.

func (Note) MarshalJSON added in v0.73.0 

func (v Note) MarshalJSON() ([]byte, error)

func (*Note) Option added in v0.77.0 

func (n *Note) Option(i int) (label, consequence string, ok bool)

Option is a decision's option i (1-based) split into its label and its consequence; ok is false for none.

func (*Note) UnmarshalJSON added in v0.73.0 

func (v *Note) UnmarshalJSON(b []byte) error

type Park added in v0.82.0 

type Park struct {
	By    Party     `json:"by"`
	At    time.Time `json:"at"`
	On    string    `json:"on,omitempty"`
	Waits string    `json:"waits"`
	// Resumable is when the watch saw On settle; Answer is what settled it,
	// a person's answer word for word or the pull request's state.
	Resumable time.Time `json:"resumable,omitzero"`
	Answer    string    `json:"answer,omitempty"`
	// contains filtered or unexported fields
}

Park is an agent's park: what it waits for, on which note (#<id>) or issue or pull request (owner/repo#n), and once that settled, since when it is resumable and the words its resume carries.

func (Park) MarshalJSON added in v0.82.0 

func (v Park) MarshalJSON() ([]byte, error)

func (*Park) UnmarshalJSON added in v0.82.0 

func (v *Park) UnmarshalJSON(b []byte) error

type Party 

type Party struct {
	// Session is the Claude Code session id (CLAUDE_CODE_SESSION_ID).
	Session string `json:"session,omitempty"`
	// HostSession is the desktop app's id for it (local_…); it survives a
	// CLI restart that changes Session.
	HostSession string `json:"hostSession,omitempty"`
	Name        string `json:"name"`
	// Person is whose agent the party is: a verified email, stable across
	// identity providers.
	Person string `json:"person,omitempty"`
	// Team is the person's team.
	Team string `json:"team,omitempty"`
	// Host is the machine or installation the party runs on.
	Host string `json:"host,omitempty"`
}

Party names a session (or a person) in the state.

func (Party) Is 

func (p Party) Is(o Party) bool

Is reports whether p and o name the same session or person. Parties of two people, or on two hosts, are never the same, whatever their names.

func (Party) Owner added in v0.74.0 

func (p Party) Owner() string

Owner names whose agent the party is, of which team, on which host ("timo@example.com, team bumblebee, on lab"); empty when none is known.

type Record added in v0.9.0 

type Record struct {
	Session Party     `json:"session"`
	Issue   string    `json:"issue"`
	Waits   string    `json:"waits,omitempty"`
	By      Party     `json:"by"`
	At      time.Time `json:"at"`
	// Ended is when a watch saw the session's CLI gone; it reports it once.
	Ended time.Time `json:"ended,omitzero"`
	// contains filtered or unexported fields
}

Record is what a session serves: the issue or epic (owner/repo#n) and what it waits on. Any session can have one, registered agent or not.

func (Record) MarshalJSON added in v0.73.0 

func (v Record) MarshalJSON() ([]byte, error)

func (*Record) UnmarshalJSON added in v0.73.0 

func (v *Record) UnmarshalJSON(b []byte) error

type Relay added in v0.10.0 

type Relay struct {
	From    Party     `json:"from"`
	To      Party     `json:"to"`
	At      time.Time `json:"at"`
	Expires time.Time `json:"expires"`
	// Taken is when the successor took the role; the record stays so the
	// outgoing supervisor learns it has been relieved.
	Taken time.Time `json:"taken,omitzero"`
	// Reported is when a watch said the relay was taken or expired; it says
	// it once.
	Reported time.Time `json:"reported,omitzero"`
	// contains filtered or unexported fields
}

Relay is the supervisor naming its successor: the successor's `supervisor start` takes the role and the grants until Expires; the outgoing supervisor keeps both meanwhile.

func (Relay) MarshalJSON added in v0.73.0 

func (v Relay) MarshalJSON() ([]byte, error)

func (*Relay) Open added in v0.10.0 

func (r *Relay) Open(now time.Time) bool

Open reports whether the relay can still be taken at now.

func (*Relay) UnmarshalJSON added in v0.73.0 

func (v *Relay) UnmarshalJSON(b []byte) error

type RelayDue added in v0.16.0 

type RelayDue struct {
	Supervisor Party     `json:"supervisor"`
	Since      time.Time `json:"since"`
	Reported   time.Time `json:"reported"`
	// Context is the supervisor's context in tokens when it was reported.
	Context int64 `json:"contextTokens"`
	// RelayAt is the relayAt in tokens it was reported at.
	RelayAt int64 `json:"relayAt,omitempty"`
	// contains filtered or unexported fields
}

RelayDue is the watch's memory that it reported the relay due to the supervisor's term Supervisor and Since at RelayAt: a relay cancelled or expired removes it, so the next quiet moment reports it again, and a changed relayAt reports it anew.

func (*RelayDue) At added in v0.91.1 

func (r *RelayDue) At(sup *Supervisor, relayAt int64) bool

At reports whether the record is about sup's current term at relayAt.

func (RelayDue) MarshalJSON added in v0.73.0 

func (v RelayDue) MarshalJSON() ([]byte, error)

func (*RelayDue) Of added in v0.16.0 

func (r *RelayDue) Of(sup *Supervisor) bool

Of reports whether the record is about sup's current term.

func (*RelayDue) UnmarshalJSON added in v0.73.0 

func (v *RelayDue) UnmarshalJSON(b []byte) error

type Relief added in v0.14.1 

type Relief struct {
	Party Party `json:"party"`
	// By is the successor whose start took the relay, At when the relay
	// was opened and Taken when it was taken.
	By    Party     `json:"by"`
	At    time.Time `json:"at"`
	Taken time.Time `json:"taken"`
	// contains filtered or unexported fields
}

Relief records a supervisor a relay relieved, so that its `supervisor status` keeps saying so after the successor relays onward, cancels a relay or is relieved in turn.

func (Relief) MarshalJSON added in v0.73.0 

func (v Relief) MarshalJSON() ([]byte, error)

func (*Relief) UnmarshalJSON added in v0.73.0 

func (v *Relief) UnmarshalJSON(b []byte) error

type Report added in v0.26.0 

type Report struct {
	Party
	// Unit is the transient user unit its turn runs in.
	Unit string `json:"unit"`
	// Slot is the start of the interval it reports on.
	Slot    time.Time `json:"slot"`
	Started time.Time `json:"started"`
	// Ended is when beekeeper took it off the roster; zero while it runs.
	Ended time.Time `json:"ended,omitzero"`
	// Outcome is posted, timeout or failed: <why>; empty while it runs.
	Outcome string `json:"outcome,omitempty"`
	// Skipped is the latest slot skipped while it ran.
	Skipped time.Time `json:"skipped,omitzero"`
	// contains filtered or unexported fields
}

Report is one run of the scheduled status reporter: the session the standby watch started for an interval's slot, until it posted, timed out or failed to start.

func (Report) MarshalJSON added in v0.73.0 

func (v Report) MarshalJSON() ([]byte, error)

func (*Report) Running added in v0.26.0 

func (r *Report) Running() bool

Running reports whether the reporter has yet to end.

func (*Report) UnmarshalJSON added in v0.73.0 

func (v *Report) UnmarshalJSON(b []byte) error

type ReportPause added in v0.28.0 

type ReportPause struct {
	Final time.Time `json:"final,omitzero"`
	Since time.Time `json:"since,omitzero"`
	By    Party     `json:"by"`
	// contains filtered or unexported fields
}

ReportPause pauses the scheduled reporter until it is resumed: from Since, or, while Final is set, from the start of one final report due then.

func (*ReportPause) FinalDue added in v0.28.0 

func (p *ReportPause) FinalDue(now time.Time) bool

FinalDue reports whether the final report is due at now.

func (ReportPause) MarshalJSON added in v0.73.0 

func (v ReportPause) MarshalJSON() ([]byte, error)

func (*ReportPause) Paused added in v0.28.0 

func (p *ReportPause) Paused() bool

Paused reports whether no scheduled report starts.

func (*ReportPause) UnmarshalJSON added in v0.73.0 

func (v *ReportPause) UnmarshalJSON(b []byte) error

type ReportThread added in v0.82.0 

type ReportThread struct {
	// Report is the reporter's name.
	Report  string    `json:"report"`
	Channel string    `json:"channel"`
	TS      string    `json:"ts"`
	Posted  time.Time `json:"posted"`
	// Seen is the ts of the last reply delivered.
	Seen string `json:"seen,omitempty"`
	// contains filtered or unexported fields
}

ReportThread is the Slack thread of a posted status report, whose replies by the report's author the feedback watch delivers.

func (ReportThread) MarshalJSON added in v0.82.0 

func (v ReportThread) MarshalJSON() ([]byte, error)

func (*ReportThread) UnmarshalJSON added in v0.82.0 

func (v *ReportThread) UnmarshalJSON(b []byte) error

type Role added in v0.20.0 

type Role struct {
	Holder   *Supervisor `json:"holder,omitempty"`
	Relay    *Relay      `json:"relay,omitempty"`
	Relieved []Relief    `json:"relieved,omitempty"`
	CLI      *CLI        `json:"cli,omitempty"`
	RelayDue *RelayDue   `json:"relayDue,omitempty"`
	// Fed are the keys of what the guide's feed reported: the open notes
	// for a person and the sessions waiting on one, each said once.
	Fed []string `json:"fed,omitempty"`
	// Run is the highest run of the role numbered: "<Role> run <Run>".
	Run int `json:"run,omitempty"`
	// Asking is the note the guide asks its person now (beekeeper guide
	// next): served again until it is answered or done.
	Asking int `json:"asking,omitempty"`
	// contains filtered or unexported fields
}

Role is a relayed role's record: its holder and term, its last relay, the holders relays relieved, what beekeeper saw of its CLI and the relay due the watch reported. The supervisor's lives in State's own fields (SupervisorRole), the guide's in Guide.

func (Role) MarshalJSON added in v0.73.0 

func (v Role) MarshalJSON() ([]byte, error)

func (*Role) UnmarshalJSON added in v0.73.0 

func (v *Role) UnmarshalJSON(b []byte) error

type StaleWriter added in v0.73.0 

type StaleWriter struct {
	PID     int    `json:"pid"`
	Command string `json:"command"`
	Version string `json:"version"`
	// Newer is the version of the writer it followed.
	Newer string    `json:"newer"`
	At    time.Time `json:"at"`
	// contains filtered or unexported fields
}

StaleWriter is a process of an older beekeeper that saved the state after a newer one had: it keeps the fields it does not know, yet it acts on the state by its older rules until it is restarted.

func (StaleWriter) MarshalJSON added in v0.73.0 

func (v StaleWriter) MarshalJSON() ([]byte, error)

func (StaleWriter) String added in v0.73.0 

func (w StaleWriter) String() string

String names the process and its versions.

func (*StaleWriter) UnmarshalJSON added in v0.73.0 

func (v *StaleWriter) UnmarshalJSON(b []byte) error

type Start added in v0.22.0 

type Start struct {
	Party
	Mode string    `json:"mode"`
	Dir  string    `json:"dir"`
	By   Party     `json:"by"`
	At   time.Time `json:"at"`
	// Harness is the agent harness started: "" for Claude Code, "omp".
	Harness string `json:"harness,omitempty"`
	// contains filtered or unexported fields
}

Start is a session `beekeeper agents start` started: the id beekeeper chose and the permission mode it passed, recorded before the session existed. A session cannot add itself: its id is only ever written here by the start that created it.

func (Start) MarshalJSON added in v0.73.0 

func (v Start) MarshalJSON() ([]byte, error)

func (*Start) UnmarshalJSON added in v0.73.0 

func (v *Start) UnmarshalJSON(b []byte) error

type State 

type State struct {
	Supervisor *Supervisor `json:"supervisor,omitempty"`
	// Relay is the supervisor's last relay: open, taken or expired.
	Relay *Relay `json:"relay,omitempty"`
	// Relieved are the supervisors relays relieved, one per party.
	Relieved []Relief `json:"relieved,omitempty"`
	// SupervisorCLI is what beekeeper saw of the supervisor's CLI.
	SupervisorCLI *CLI `json:"supervisorCLI,omitempty"`
	// SupervisorRun is the highest supervisor run numbered.
	SupervisorRun int `json:"supervisorRun,omitempty"`
	// RelayDue is the relay due the watch reported to the supervisor.
	RelayDue *RelayDue `json:"relayDue,omitempty"`
	// Guide is the guide's role, the supervisor's counterpart for the
	// person's decisions.
	Guide *Role `json:"guide,omitempty"`
	// Grants are queued per resource in the order given.
	Grants []Grant `json:"grants,omitempty"`
	// Released is when each resource was last released; a grant's TTL runs
	// from the later of it and the grant.
	Released  map[string]time.Time `json:"released,omitempty"`
	Holds     []Hold               `json:"holds,omitempty"`
	Agents    []Agent              `json:"agents,omitempty"`
	Notes     []Note               `json:"notes,omitempty"`
	NextNote  int                  `json:"nextNote,omitempty"`
	Timers    []Timer              `json:"timers,omitempty"`
	NextTimer int                  `json:"nextTimer,omitempty"`
	// Records say which session serves which issue.
	Records []Record `json:"records,omitempty"`
	// Starts are the sessions beekeeper started, what the permission hook
	// answers for.
	Starts []Start `json:"starts,omitempty"`
	// Archives are the desktop sessions of agents off the roster the
	// doctor still owes an archive.
	Archives []Archive `json:"archives,omitempty"`
	// ArchivesSeeded says the doctor owed the archives of the finished
	// workers whose desktop CLI ran on before it kept Archives.
	ArchivesSeeded bool `json:"archivesSeeded,omitempty"`
	// FinishedSeeded says the doctor owed the archives of all finished
	// workers whose desktop record stayed unarchived, a CLI running or not.
	FinishedSeeded bool `json:"finishedSeeded,omitempty"`
	// Declines are the stewards that declined an archive request, which
	// the doctor asks for none for a while.
	Declines []Decline `json:"declines,omitempty"`
	// BudgetETag makes the budget probe a conditional request (a 304
	// costs no budget).
	BudgetETag string `json:"budgetETag,omitempty"`
	// Budget is the last reading of the GitHub core budget.
	Budget *Budget `json:"budget,omitempty"`
	// Merges are the wrapped devctl pr merge runs, per lane: waiting in join
	// order, running, and settling until the lane's installation rolled them.
	Merges []Merge `json:"merges,omitempty"`
	// Report is the scheduled status reporter's current or last run.
	Report *Report `json:"report,omitempty"`
	// ReportThreads are the posted reports' Slack threads the feedback
	// watch reads, while feedback.window lasts.
	ReportThreads []ReportThread `json:"reportThreads,omitempty"`
	// AlertOwners are the owners of the firing alerts, one per alert.
	AlertOwners []AlertOwner `json:"alertOwners,omitempty"`
	// ReportPause pauses the scheduled reporter, after one final report.
	ReportPause *ReportPause `json:"reportPause,omitempty"`
	// Writer is the newest beekeeper that saved the state.
	Writer *Writer `json:"writer,omitempty"`
	// StaleWriters are the processes of an older beekeeper seen saving the
	// state after a newer one, one per process while it runs.
	StaleWriters []StaleWriter `json:"staleWriters,omitempty"`
	// contains filtered or unexported fields
}

State is the whole document.

func (*State) BypassStart added in v0.22.0 

func (st *State) BypassStart(session string) (Start, bool)

BypassStart returns the start of session when beekeeper started it in bypassPermissions.

func (*State) GuideRole added in v0.20.0 

func (st *State) GuideRole() Role

GuideRole is the guide's record.

func (*State) Knows added in v0.70.1 

func (st *State) Knows(p Party) bool

Knows reports whether p is a session beekeeper started (any mode), holds the supervisor's or the guide's role, or is an agent on the roster: the sessions the hooks act in wherever they run.

func (State) MarshalJSON added in v0.9.0 

func (v State) MarshalJSON() ([]byte, error)

func (*State) SetGuideRole added in v0.20.0 

func (st *State) SetGuideRole(r Role)

SetGuideRole stores the guide's record, none when it is empty.

func (*State) SetSupervisorRole added in v0.20.0 

func (st *State) SetSupervisorRole(r Role)

SetSupervisorRole stores the supervisor's record.

func (*State) SupervisorRole added in v0.20.0 

func (st *State) SupervisorRole() Role

SupervisorRole is the supervisor's record.

func (*State) UnmarshalJSON added in v0.9.0 

func (v *State) UnmarshalJSON(b []byte) error

type Store 

type Store interface {
	// Dir is the machine-local directory beside the state: the merge
	// gate's and the timers' side files.
	Dir() string
	// Read returns the current state.
	Read() (*State, error)
	// Peek returns the current state without waiting on a writer.
	Peek() (*State, error)
	// Update runs fn on the state and saves the result together with the
	// events fn returns; when fn fails nothing is saved.
	Update(fn func(*State) ([]Event, error)) error
	// Log appends events that change no state.
	Log(events ...Event) error
	// Events returns the last n events keep accepts, oldest first.
	Events(n int, keep func(Event) bool) ([]Event, error)
	// ReadFile decodes a JSON side file; found is false when it is missing.
	ReadFile(name string, v any) (found bool, err error)
	// WriteFile replaces a JSON side file.
	WriteFile(name string, v any) error
}

Store is the seam every command reads and changes the state through.

type Supervisor 

type Supervisor struct {
	Party
	Since time.Time `json:"since"`
	// contains filtered or unexported fields
}

Supervisor is the session holding the watch.

func (Supervisor) MarshalJSON added in v0.73.0 

func (v Supervisor) MarshalJSON() ([]byte, error)

func (*Supervisor) UnmarshalJSON added in v0.73.0 

func (v *Supervisor) UnmarshalJSON(b []byte) error

type Timer added in v0.9.0 

type Timer struct {
	ID   int       `json:"id"`
	Due  time.Time `json:"due"`
	What string    `json:"what"`
	By   Party     `json:"by"`
	At   time.Time `json:"at"`
	// Fired is when a watch reported the timer; it reports it once.
	Fired time.Time `json:"fired,omitzero"`
	// When is a typed condition (pr-merged owner/repo#n, …) and Probe a
	// shell command that exits 0 once its condition holds: from Due, the
	// watch checks it every Every and fires the timer once it holds.
	When  string        `json:"when,omitempty"`
	Probe string        `json:"probe,omitempty"`
	Every time.Duration `json:"every,omitempty"`
	// Checked is when a watch last found the condition not holding.
	Checked time.Time `json:"checked,omitzero"`
	// Until is the end of the wait: past it the timer fires as timed out,
	// or closes unfired when Expire is set.
	Until  time.Time `json:"until,omitzero"`
	Expire bool      `json:"expire,omitempty"`
	// Wake is the agent the firing wakes with What; Run a shell command it
	// runs, its exit code logged. Without either the watch's line says it.
	Wake string `json:"wake,omitempty"`
	Run  string `json:"run,omitempty"`
	// Repeat re-arms a timer that wakes or runs at the same local time:
	// daily, weekdays (Monday to Friday) or weekly. Such a timer stays open
	// until marked done.
	Repeat string `json:"repeat,omitempty"`
	// contains filtered or unexported fields
}

Timer is a point in time the supervisor has to look at something ("check the rollout after 22:55").

func (Timer) Auto added in v0.56.0 

func (t Timer) Auto() bool

Auto reports whether the watch acts on the timer itself and closes it when it fires: a condition to wait on, an agent to wake or a command to run. A plain timer stays open until marked done.

func (Timer) Conditional added in v0.56.0 

func (t Timer) Conditional() bool

Conditional reports whether the timer waits on a condition.

func (Timer) Looked added in v0.56.0 

func (t Timer) Looked(now time.Time) bool

Looked reports whether someone has to look at the timer by now: a plain timer whose time has come. An auto timer is the watch's to act on.

func (Timer) MarshalJSON added in v0.73.0 

func (v Timer) MarshalJSON() ([]byte, error)

func (Timer) Next added in v0.91.0 

func (t Timer) Next(now time.Time) time.Time

Next is the first time after now the repeating timer is due again, at its local time of day: a day or a week on, a weekday timer skipping the weekend.

func (*Timer) UnmarshalJSON added in v0.73.0 

func (v *Timer) UnmarshalJSON(b []byte) error

type Writer added in v0.73.0 

type Writer struct {
	Version string `json:"version"`
	// contains filtered or unexported fields
}

Writer is the version of the newest beekeeper that saved the state.

func (Writer) MarshalJSON added in v0.73.0 

func (v Writer) MarshalJSON() ([]byte, error)

func (*Writer) UnmarshalJSON added in v0.73.0 

func (v *Writer) UnmarshalJSON(b []byte) error

Source Files

View all Source files

Directories

Path Synopsis
Package kube is the Kubernetes store of `beekeeper serve`: the shared state of the Giant Swarm installations as custom resources of beekeeper.giantswarm.io instead of one document under a file lock.
 Package kube is the Kubernetes store of `beekeeper serve`: the shared state of the Giant Swarm installations as custom resources of beekeeper.giantswarm.io instead of one document under a file lock.

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.