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

state

package
v0.170.2 Latest Latest
Warning

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

 Go to latest Published: Oct 23, 2026 License: Apache-2.0 Imports: 18 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 (
	NoteDecision = "decision"
	NoteLogin    = "login"
)

The kinds of a note.

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 release's first refused save after a newer one wrote the state.

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"`
	// Undelivered is why agents start delivered no turn of the agent's
	// task, which waits until agents wake delivers one; empty: delivered.
	Undelivered string `json:"undelivered,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"`
	// GH is the gh the agent's shell resolves outside the sandbox, read at
	// its registration and each session start; GHAt when. Empty: not read.
	GH   string    `json:"gh,omitempty"`
	GHAt time.Time `json:"ghAt,omitzero"`
	// 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 App added in v0.120.0 

type App struct {
	// Name is the App's name as its consent page titles it ("Authorize
	// <name>" on GitHub).
	Name string `json:"name"`
	// ClientID is the OAuth client id the consent URL carries, "" for a
	// record without a consent.
	ClientID string `json:"clientID"`
	// Callbacks are the hosts the consent page's redirect may go to: the
	// callback URLs' hosts of the App's declaration; none for a record
	// without a consent.
	Callbacks []string `json:"callbacks"`
	// Org is the organisation whose settings pages the record covers: the
	// owner of the declaring repository.
	Org string `json:"org,omitempty"`
	// Permission is the one change of the App's permissions the person
	// asked for, "<scope>: <level>" ("Members: Read-only"); "" for a record
	// without one.
	Permission string `json:"permission,omitempty"`
	// CallbackURL is the one callback URL the person asked to add to the
	// App's settings, on a callback host its manifest declares; "" for a
	// record without one.
	CallbackURL string `json:"callbackURL,omitempty"`
	// Delete says the person asked for the App's deletion: the hook answers
	// its Advanced page's Delete GitHub App and the confirmation.
	Delete bool `json:"delete,omitempty"`
	// Google says the App is a Google OAuth client of the person's: the
	// hook answers its consent on Google's sign-in, by the callback hosts
	// the person named.
	Google bool `json:"google,omitempty"`
	// Account is the Google account a Google OAuth client's sign-in
	// chooses: the hook answers no other account on Google's chooser; of a
	// third party's OAuth client, the account the consent is given as.
	Account string `json:"account,omitempty"`
	// GitLab is the host of the self-hosted GitLab whose OAuth application
	// of the person's this is: the hook answers its authorize page there,
	// by the callback hosts the person named; "" for any other record.
	GitLab string `json:"gitlab,omitempty"`
	// OAuth is the sign-in host of a third party's OAuth client the
	// person consents to as their Account there: the hook answers that
	// client's consent page on that host; "" for any other record.
	OAuth string `json:"oauth,omitempty"`
	// Slack is the workspace host (<workspace>.slack.com) of a Slack app of
	// the person's whose install consent the hook answers there, SlackApp
	// its app id and WebhookChannel the channel its webhook posts to, which
	// the install keeps (lower case, without "#"; "" for an app without
	// one); Slack is "" for any other record.
	Slack          string `json:"slack,omitempty"`
	SlackApp       string `json:"slackApp,omitempty"`
	WebhookChannel string `json:"webhookChannel,omitempty"`
	// Declared is where the organisation declares the App:
	// <repo>@<commit>:<manifest path>, the local manifest of an App on the
	// person's own account or of a deletion, or the person's own
	// declaration of a GitLab application's client id.
	Declared string `json:"declared"`
	// Word is the person's words that asked for the grant.
	Word string    `json:"word"`
	By   Party     `json:"by"`
	At   time.Time `json:"at"`
	// contains filtered or unexported fields
}

App is an App the person owns and asked a consent, or one change of its permissions, for, on their word: the hook answers the consent click on its page, and the navigation to its permissions page and the clicks of that change, itself (guard.Click, guard.Navigation).

func (App) MarshalJSON added in v0.120.0 

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

func (*App) UnmarshalJSON added in v0.120.0 

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

type AppCreated added in v0.133.0 

type AppCreated struct {
	Name string `json:"name"`
	Slug string `json:"slug"`
	ID   int64  `json:"id"`
	// Org is the organisation the App was created for.
	Org      string `json:"org"`
	Declared string `json:"declared"`
	// Stored is where its credentials went (a vault item, a SOPS file), ""
	// for nowhere.
	Stored string    `json:"stored,omitempty"`
	By     Party     `json:"by"`
	At     time.Time `json:"at"`
	// contains filtered or unexported fields
}

AppCreated is an App `beekeeper app create` created: beekeeper's ledger of its own Apps. The hook answers its Install click, and the deletion of one whose credentials were stored nowhere.

func (AppCreated) MarshalJSON added in v0.133.0 

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

func (*AppCreated) UnmarshalJSON added in v0.133.0 

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

type AppRun added in v0.133.0 

type AppRun struct {
	Name string `json:"name"`
	// Org is the account the App is created for: an organisation, or a
	// personal account (app create --manifest --user).
	Org string `json:"org"`
	// Declared is where the App is declared: its manifest in the
	// organisation's repository, or the local manifest file.
	Declared string `json:"declared"`
	// Listener is the run's loopback address, host:port.
	Listener string    `json:"listener"`
	PID      int       `json:"pid"`
	By       Party     `json:"by"`
	At       time.Time `json:"at"`
	// contains filtered or unexported fields
}

AppRun is a running `beekeeper app create`: the App it creates, the loopback listener its manifest page and GitHub's redirect go to, and its process. The hook answers GitHub's Create click on the manifest page and the App's Install click while the listener answers.

func (AppRun) MarshalJSON added in v0.133.0 

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

func (*AppRun) UnmarshalJSON added in v0.133.0 

func (v *AppRun) 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"`
	// Looked is the last doctor's run that found no steward to ask.
	Looked time.Time `json:"looked,omitzero"`
	// Warmed is when the desktop was last made to warm the session's own
	// CLI to archive itself: the watch leaves that CLI running a while.
	Warmed time.Time `json:"warmed,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"`
	// GraphQL is the last reading of the GraphQL limit; nil before the
	// first.
	GraphQL *GraphQL `json:"graphql,omitempty"`
	// 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"`
	// Subject is the issue or pull request the event concerns, owner/repo#n,
	// on the events the sink may dispatch (config.SinkVerbs); empty on the
	// rest.
	Subject string `json:"subject,omitempty"`
}

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 Failed added in v0.123.0 

type Failed struct {
	Repo   string    `json:"repo"`
	PR     int       `json:"pr"`
	Lane   string    `json:"lane"`
	By     Party     `json:"by"`
	At     time.Time `json:"at"`
	Exit   int       `json:"exit"`
	Reason string    `json:"reason,omitempty"`
	// contains filtered or unexported fields
}

Failed is a gated merge's run that merged nothing: when, devctl's exit code and its reason (the verdict and the failed checks), for whoever it ran for.

func (Failed) Key added in v0.123.0 

func (f Failed) Key() string

Key is the failed merge's owner/repo#n, or owner/repo promote.

func (Failed) MarshalJSON added in v0.123.0 

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

func (*Failed) UnmarshalJSON added in v0.123.0 

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

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, saving as this binary's version.

func OpenVersion added in v0.108.0 

func OpenVersion(dir, version string) (*FileStore, error)

OpenVersion is Open saving as version: a release stamps the state and is refused by a newer one's, a build without a release version does neither.

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) Exclusive added in v0.145.2 

func (s *FileStore) Exclusive(fn func() error) error

Exclusive runs fn under the exclusive state lock, writing nothing: what must not happen while a process holds the lock, freezing a session's processes for one.

func (*FileStore) Follow added in v0.107.0 

func (s *FileStore) Follow(name string, keep func(Event) bool) ([]Event, error)

Follow returns every event keep accepts, oldest first. It remembers under name how far it read and what it kept, and reads only the lines appended since: a watch that follows the log every poll parses each line once. A log that was replaced or shrank is read again from its start.

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) Record added in v0.104.0 

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

Record appends events that change no state and must not be lost, a secret call's audit entry for one, under the state lock, waiting for it as an update does: a busy lock delays the entry, and a lock busy past lockWait fails the call instead of dropping it.

func (*FileStore) RecordWithin added in v0.145.3 

func (s *FileStore) RecordWithin(wait time.Duration, events ...Event) error

RecordWithin is Record waiting at most wait for the lock.

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, nor when a newer release wrote the state (StaleWriterError).

func (*FileStore) UpdateWithin added in v0.145.2 

func (s *FileStore) UpdateWithin(wait time.Duration, fn func(*State) ([]Event, error)) error

UpdateWithin is Update waiting at most wait for the lock.

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 GraphQL added in v0.97.1 

type GraphQL struct {
	Remaining int `json:"remaining"`
	Limit     int `json:"limit"`
	// Reset is when a refusal ends; zero when GitHub named no time.
	Reset time.Time `json:"reset,omitzero"`
	// Refused is GitHub's words while it refused GraphQL calls.
	Refused   string    `json:"refused,omitempty"`
	Secondary bool      `json:"secondary,omitempty"`
	At        time.Time `json:"at"`
	// contains filtered or unexported fields
}

GraphQL is one reading of the GitHub GraphQL limit.

func (*GraphQL) Blocks added in v0.97.1 

func (g *GraphQL) Blocks(now time.Time) bool

Blocks says the reading's refusal still holds at now: one without a reset holds until a reading says otherwise.

func (GraphQL) MarshalJSON added in v0.97.1 

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

func (*GraphQL) UnmarshalJSON added in v0.97.1 

func (v *GraphQL) 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"`
	// ExceptSession is the session (by name) a merge hold lets through: its
	// merges and promotes run, a line's promoter promoting while the hold
	// keeps every other session's merges off the line.
	ExceptSession string `json:"exceptSession,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 (0 for a promotion), ToolMerged whether it merged and
	// ToolRelease the release it produced. The window closes once its pull
	// request merged (or its promotion runs) and the tool reports another
	// version than ToolFrom (ToolRelease once known), also while the merge's
	// devctl still waits for the release workflow, or once its merge ended
	// with nothing merged, no release warranted or only a release candidate.
	// ToolUpdated is when beekeeper last ran the tool's update for the
	// window, ToolFailed that update's failure ("" when it ran clean: the
	// release's binary did not verify, or no newer one is published yet),
	// ToolChecked when a gate or the watch last claimed the read of the
	// window's state (the tool's version, its pull request), which they share.
	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"`
	ToolFailed  string    `json:"toolFailed,omitempty"`
	ToolChecked time.Time `json:"toolChecked,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) Admits added in v0.157.0 

func (h Hold) Admits(session string) bool

Admits reports whether the hold lets the session named session through.

func (Hold) AwaitsOwnRelease added in v0.148.0 

func (h Hold) AwaitsOwnRelease() bool

AwaitsOwnRelease reports whether the hold is a repository's whose lift probe waits on that repository's release or tag: only the repository's own promote cuts it, so the hold lets that promote through.

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 ItemHold added in v0.150.0 

type ItemHold struct {
	Ref    string `json:"ref"`
	Status string `json:"status"`
	Was    string `json:"was"`
}

ItemHold is a board item a decision holds on its person: the issue, the Status the hold set and the Status it had before, which its release sets back.

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 LockBusyError added in v0.145.2 

type LockBusyError struct {
	PID     int
	Command string
	Since   time.Time
	Waited  time.Duration
}

LockBusyError is a wait for the state lock that ended before its holder released it: who holds it, since when, as the holder recorded it; PID 0 is a holder without a record (a reader, or an older beekeeper).

func (*LockBusyError) Error added in v0.145.2 

func (e *LockBusyError) Error() string

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"`
	// Run is the files' base of a queued merge's own run (the gate under
	// --queued and its merge-child), whose merge-child owes the outcome to
	// the owner: a run cut before that merge-child wrote its exit code
	// leaves the outcome to the watch. Cleared once the cut is owed.
	Run string `json:"run,omitempty"`
	// Output is the file the gate's stdout writes to, a background task's
	// output file: a TaskStop naming that task stops the merge.
	Output string `json:"output,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.
	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"`
	// Candidate is the release candidate a promotion (PR 0) was queued for,
	// the newest one at queue time, empty when there was none: its turn
	// refuses when the newest candidate is another by then.
	Candidate string `json:"candidate,omitempty"`
	// Release is the tag the merge released, empty when unknown.
	Release string `json:"release,omitempty"`
	// ReleaseFailed marks a merge whose release failed (devctl exit 6): its
	// auto-release run or tag pipeline failed, nothing rolls, and the lane
	// settles at once.
	ReleaseFailed bool `json:"releaseFailed,omitempty"`
	// HandCut is the merge's base branch when no Auto-release run tags a
	// merge into it (its tags are cut by hand): devctl awaits no release and
	// the merge leaves its lane once merged.
	HandCut string `json:"handCut,omitempty"`
	// Roll names the HelmReleases (namespace/name) that must reach Release
	// before the lane frees.
	Roll []string `json:"roll,omitempty"`
	// Reset is the GitHub budget reset a merge queued under the floor waits
	// for: for merge.resetFirst from then it goes before the waits, and the
	// older such merges before it. Its start clears it.
	Reset time.Time `json:"reset,omitzero"`
	// 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) 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 NoteDecision for a question that waits on a person or
	// NoteLogin for a sign-in the watch closes once Until, a shell command,
	// exits 0.
	Kind  string `json:"kind,omitempty"`
	Until string `json:"until,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, unless a closing keyword closed one and the note's
	// worker has not ended its task (Kept). Without refs the note is linked
	// to its filing session, and closes once that session is archived.
	Refs []string `json:"refs,omitempty"`
	// TaskEnded is when the worker that filed the note reported its task
	// over (agents idle): from then on its settled refs overtake the note,
	// a closing keyword's close included. Zero for a note no worker filed
	// or whose worker still runs.
	TaskEnded time.Time `json:"taskEnded,omitzero"`
	// Kept is why the watch keeps the note open although every ref is
	// closed or merged, said once per reason (NOTE KEPT).
	Kept string `json:"kept,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"`
	// Held is the board item the decision holds (note add --holds), its
	// first --ref, and AlsoHeld those of its further --ref: each one's
	// Status set to Blocked / Waiting until the decision closes, then set
	// back. nil and empty for a note that holds nothing.
	Held     *ItemHold  `json:"held,omitempty"`
	AlsoHeld []ItemHold `json:"alsoHeld,omitempty"`
	// Central is the muster context of the central instance that holds
	// the note, as a machine lists it beside its own; empty for the
	// machine's own note, and never stored.
	Central string `json:"central,omitempty"`
	// contains filtered or unexported fields
}

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

func (*Note) HoldOf added in v0.155.6 

func (n *Note) HoldOf(ref string) *ItemHold

HoldOf is n's hold of the board item ref; nil when n holds no such item.

func (*Note) Holds added in v0.155.6 

func (n *Note) Holds() []ItemHold

Holds are the board items n holds: Held, then AlsoHeld.

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 Owed added in v0.140.1 

type Owed struct {
	Owner   Party     `json:"owner"`
	Line    string    `json:"line"`
	Ask     bool      `json:"ask,omitempty"`
	Repo    string    `json:"repo,omitempty"`
	PR      int       `json:"pr,omitempty"`
	Command string    `json:"command,omitempty"`
	Stop    string    `json:"stop,omitempty"`
	Gate    int       `json:"gate,omitempty"`
	Child   int       `json:"child"`
	Heard   string    `json:"heard,omitempty"`
	Since   time.Time `json:"since"`
	Tried   time.Time `json:"tried,omitzero"`
	Why     string    `json:"why,omitempty"`
	// contains filtered or unexported fields
}

Owed is a detached run's outcome its owner has not heard: recorded by the run's merge-child before it hands the outcome over, so a merge-child stopped or killed on the way (a desktop restart, its user manager stopping) leaves it to the watch. Gate and Child are the pids of the run's gate and merge-child, which hand it over while either runs; Heard is the gate's heard marker, which says its caller heard it. Line is the outcome; Ask marks a merge stopped before devctl reported its end, whose outcome is its pull request's state on GitHub (Repo, PR), Command and Stop naming the command and its stop. Tried is when a hand-over was last claimed, Why why the last one failed.

func (Owed) Key added in v0.140.1 

func (o Owed) Key() string

Key tells owed outcomes apart: the merge-child that owes it and when.

func (Owed) MarshalJSON added in v0.140.1 

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

func (*Owed) UnmarshalJSON added in v0.140.1 

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

type Pair added in v0.156.0 

type Pair struct {
	// Keys are the two merges, owner/repo#n each.
	Keys []string  `json:"keys"`
	By   Party     `json:"by"`
	At   time.Time `json:"at"`
	// Ready is when each merge's gate last found only the pair holding it
	// back, by key.
	Ready map[string]time.Time `json:"ready,omitempty"`
	// Started is the merge that started first; its sibling then starts
	// outside merge.cap and merge.sessionCap, the slot taken for both.
	Started string `json:"started,omitempty"`
	// Refused is why one of the two was refused, RefusedKey which: the
	// other's gate refuses it with the same reason.
	Refused    string `json:"refused,omitempty"`
	RefusedKey string `json:"refusedKey,omitempty"`
	// contains filtered or unexported fields
}

Pair is two merges that must land together, a change split over two repositories: the gate holds the first at its turn until the other is next in its lane too, then starts both, and a refusal of either refuses both with one reason.

func (Pair) MarshalJSON added in v0.156.0 

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

func (Pair) Sibling added in v0.156.0 

func (p Pair) Sibling(key string) string

Sibling is the pair's other merge than key, "" when key is not in it.

func (*Pair) UnmarshalJSON added in v0.156.0 

func (v *Pair) 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"`
	// Told is when the supervisor's watch said the park waits on a person;
	// zero: not yet, or it waits on no person.
	Told time.Time `json:"told,omitzero"`
	// 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. AskingFrom is the
	// muster context of the central instance that holds it, empty for the
	// machine's own.
	Asking     int    `json:"asking,omitempty"`
	AskingFrom string `json:"askingFrom,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) LocalAsking added in v0.165.1 

func (r Role) LocalAsking() int

LocalAsking is the machine's own note the guide asks now, 0 when it asks none or a central instance's.

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 RoleLine added in v0.139.2 

type RoleLine struct {
	Role string    `json:"role"`
	Line string    `json:"line"`
	At   time.Time `json:"at"`
	// contains filtered or unexported fields
}

RoleLine is a line for the holder of a role (supervisor, guide) that no session held, or whose holder could not be told, when it was said: the answer to a note a run of the role filed.

func (RoleLine) MarshalJSON added in v0.139.2 

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

func (*RoleLine) UnmarshalJSON added in v0.139.2 

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

type StaleWriterError added in v0.108.0 

type StaleWriterError struct {
	PID     int
	Command string
	// Version is this binary's, Newer the one that wrote the state.
	Version, Newer string
	// Load is why the state does not decode, nil for a refused save.
	Load error
}

StaleWriterError is a save refused because a newer release wrote the state, or a state a newer release wrote that this binary does not load (Load): this binary would save it by rules that release changed (a watch, a start's reopen or a gate call left running by an install). The state stays as it is; the process ends or is restarted, and the installed beekeeper runs its command.

func (*StaleWriterError) Error added in v0.108.0 

func (e *StaleWriterError) Error() string

func (*StaleWriterError) Unwrap added in v0.151.0 

func (e *StaleWriterError) Unwrap() 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"`
	// Model is the model the session was started on (--model, as its first
	// reply names it), which its turns keep; empty: none was chosen.
	Model string `json:"model,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"`
	// Defaulted are the decisions closed by their default within the last
	// day: an answer that arrives meanwhile replaces the default.
	Defaulted []Note  `json:"defaulted,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"`
	// Apps are the Apps the person owns and asked a consent for, what the
	// hook answers a consent click for.
	Apps []App `json:"apps,omitempty"`
	// AppRuns are the running `beekeeper app create` commands.
	AppRuns []AppRun `json:"appRuns,omitempty"`
	// AppsCreated are the Apps `beekeeper app create` created.
	AppsCreated []AppCreated `json:"appsCreated,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"`
	// DoneSeeded says the doctor owed those archives again, of the agents
	// that reported done and the relieved role runs no person typed in, once
	// a finished session's own warmed CLI archived it.
	DoneSeeded bool `json:"doneSeeded,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"`
	// Failed are the gated merges whose last run merged nothing, one per
	// pull request, shown on their lane until its next attempt joins it.
	Failed []Failed `json:"failed,omitempty"`
	// Owed are the outcomes of detached runs their owners have not heard
	// yet, until the watch hands each over.
	Owed []Owed `json:"owed,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"`
	// WorkerReports are the reports workers finished with (agents idle
	// --done) that the supervisor's watch has not printed yet.
	WorkerReports []WorkerReport `json:"workerReports,omitempty"`
	// Urgent are the merges marked urgent (lanes urgent): waiting for their
	// gate, or run under the GitHub budget floor in a reset window that has
	// not ended.
	Urgent []Urgent `json:"urgent,omitempty"`
	// Pairs are the merges declared to land together (the gate's --pair):
	// neither starts unless the other is next in its lane.
	Pairs []Pair `json:"pairs,omitempty"`
	// RoleLines are lines for a role's holder that found none to tell: the
	// role's next start says them.
	RoleLines []RoleLine `json:"roleLines,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) BypassStartOf added in v0.150.0 

func (st *State) BypassStartOf(p Party) (Start, bool)

BypassStartOf returns the start of p when beekeeper started it in bypassPermissions, matched by its CLI session id or its desktop host id: the desktop gives a session's restarted CLI a new session id and keeps its host id.

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) PairOf added in v0.156.0 

func (s *State) PairOf(key string) int

PairOf is the index of the pair key is in, -1 when none.

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) StartIndex added in v0.150.0 

func (st *State) StartIndex(p Party) int

StartIndex is the index in Starts of p's start in any mode, matched as BypassStartOf matches; -1 when beekeeper did not start it.

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
	// UpdateWithin is Update for a caller that must not wait long, a
	// session's start for one: a lock busy past wait fails it.
	UpdateWithin(wait time.Duration, fn func(*State) ([]Event, error)) error
	// Exclusive runs fn while no other process holds the state, writing
	// nothing.
	Exclusive(fn func() error) error
	// Log appends events that change no state, giving up on a busy lock.
	Log(events ...Event) error
	// Record appends events that change no state and must not be lost,
	// waiting for the lock as an update does.
	Record(events ...Event) error
	// RecordWithin is Record for a caller that must not wait long, an
	// agent's hand-over note for one: a lock busy past wait fails it with
	// a LockBusyError, the events not appended.
	RecordWithin(wait time.Duration, events ...Event) error
	// Events returns the last n events keep accepts, oldest first.
	Events(n int, keep func(Event) bool) ([]Event, error)
	// Follow returns every event keep accepts, oldest first, as Events(0,
	// keep); a reader that calls it again under the same name, with the
	// same keep, may be handed what it read before and only what was logged
	// since read.
	Follow(name string, 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, Reason
	// why: what the reference says, or why it could not be read
	// (Unreadable).
	Checked    time.Time `json:"checked,omitzero"`
	Reason     string    `json:"reason,omitempty"`
	Unreadable bool      `json:"unreadable,omitempty"`
	// Since is the first check that found the condition not holding; Stuck
	// is set once the watch said it has not held for a day.
	Since time.Time `json:"since,omitzero"`
	Stuck bool      `json:"stuck,omitempty"`
	// 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 Urgent added in v0.110.0 

type Urgent struct {
	Repo string `json:"repo"`
	PR   int    `json:"pr"`
	// By is who asked for it, Reason why.
	By     Party     `json:"by"`
	Reason string    `json:"reason"`
	At     time.Time `json:"at"`
	// Window is the reset of the budget window the merge ran under the
	// floor in; zero while it waits for its gate.
	Window time.Time `json:"window,omitzero"`
	// Remaining is the budget when it ran, Spent what its run drew from
	// it: nil while it runs, -1 unread.
	Remaining int  `json:"remaining,omitempty"`
	Spent     *int `json:"spent,omitempty"`
	// contains filtered or unexported fields
}

Urgent is a merge marked urgent, a privacy or security fix's: under the GitHub budget floor it runs, once per reset window, while the budget keeps github.urgentBound for it.

func (Urgent) Key added in v0.110.0 

func (u Urgent) Key() string

Key is the urgent merge's owner/repo#n.

func (Urgent) MarshalJSON added in v0.110.0 

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

func (Urgent) Ran added in v0.110.0 

func (u Urgent) Ran() bool

Ran says whether the merge ran under the floor in the window that resets at Window.

func (*Urgent) UnmarshalJSON added in v0.110.0 

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

type WorkerReport added in v0.93.0 

type WorkerReport struct {
	By       Party     `json:"by"`
	At       time.Time `json:"at"`
	Task     string    `json:"task,omitempty"`
	Text     string    `json:"text"`
	Problems []string  `json:"problems,omitempty"`
	// contains filtered or unexported fields
}

WorkerReport is the report a worker finished its task with: what it delivered and the problems it found (broken functions, ways around them, follow-ups). The supervisor's watch prints it once and drops it; the event log keeps it (agents.report, agents.problem).

func (WorkerReport) MarshalJSON added in v0.93.0 

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

func (*WorkerReport) UnmarshalJSON added in v0.93.0 

func (v *WorkerReport) 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.