Documentation
¶
Overview ¶
Package offline owns runner-local containment and replay state. It never grants authority: the organisation supplies every lease and pending action.
Index ¶
- func SetAsidePrevious(ctx context.Context, stateDir string, runnerID uuid.UUID, ...) error
- type Clock
- type Manager
- func (m *Manager) AdmitResident(runID uuid.UUID) error
- func (m *Manager) AfterRefCall(ctx context.Context, method, ref, execID string, generation uuid.UUID) error
- func (m *Manager) AgentExited(ctx context.Context, id uuid.UUID, localRef string, code int) error
- func (m *Manager) BeforeCreate(ctx context.Context, spec runner.SandboxSpec) error
- func (m *Manager) BeforeReady(ctx context.Context, peer *runnerwire.Peer, _ bool) error
- func (m *Manager) BeforeRefCall(ctx context.Context, method, ref string, generation uuid.UUID) error
- func (m *Manager) CheckLapses(ctx context.Context) error
- func (m *Manager) CheckSelftest(ctx context.Context, ref string, generation uuid.UUID) error
- func (m *Manager) Clock(h runnerwire.Hello, received time.Time) error
- func (m *Manager) Close() error
- func (m *Manager) CreateFailed(ctx context.Context, spec runner.SandboxSpec) error
- func (m *Manager) Created(ctx context.Context, spec runner.SandboxSpec, localRef string) error
- func (m *Manager) EvidenceRunIDs() []uuid.UUID
- func (m *Manager) ExecutionResult(ctx context.Context, ref string, generation uuid.UUID) (runnerwire.ExecutionResult, error)
- func (m *Manager) HoldsSandbox(localRef string) bool
- func (m *Manager) IsRevoked() bool
- func (m *Manager) Lease(ctx context.Context, l runnerwire.Lease) error
- func (m *Manager) LoadEvidence(runID uuid.UUID) ([]byte, error)
- func (m *Manager) MutationFinished(ctx context.Context, method, ref string, runID, generation uuid.UUID, ...) error
- func (m *Manager) ObserveProxies(ctx context.Context) error
- func (m *Manager) Offline(context.Context)
- func (m *Manager) Online(peer *runnerwire.Peer)
- func (m *Manager) Pending(ctx context.Context, peer *runnerwire.Peer, actions []runnerwire.PendingAction) error
- func (m *Manager) ProvisionalDeadlines()
- func (m *Manager) ProxyExited(runID uuid.UUID, evidence string) error
- func (m *Manager) ReleaseSettledOutput(release func(runID uuid.UUID, ref string) error)
- func (m *Manager) Replay(ctx context.Context, peer *runnerwire.Peer) error
- func (m *Manager) Revoked(ctx context.Context) error
- func (m *Manager) Run(ctx context.Context) error
- func (m *Manager) SaveEvidence(runID uuid.UUID, b []byte) error
- func (m *Manager) SetOptions(o Options) error
- func (m *Manager) SinkRunIDs() []uuid.UUID
- func (m *Manager) StatePages(ctx context.Context, send func(runnerwire.StatePage) error) error
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SetAsidePrevious ¶ added in v0.9.3
func SetAsidePrevious(ctx context.Context, stateDir string, runnerID uuid.UUID, sub substrate.Substrate, expectedRef func(uuid.UUID) string) error
SetAsidePrevious moves the run state an earlier registration left in stateDir (its offline state, spools and output) into stateDir/previous/<its runner id>, once the proxy of every run that state still holds is stopped, for each sandbox the substrate proves that registration created. The organisation binds each of those runs to the earlier runner, so no action for them can ever reach this one, and New refuses state another runner wrote. State this runner wrote, or none, is left as it is. The caller holds the serve lock.
Types ¶
type Clock ¶
type Clock struct {
// contains filtered or unexported fields
}
Clock maps org wall timestamps onto elapsed local monotonic time. Receipt times must come directly from time.Now, retaining their monotonic component.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager contains only local containment and evidence state. It cannot mint credentials or grant authority, and never chooses a run's terminal state.
func New ¶
func New(stateDir string, runnerID uuid.UUID, sub substrate.Substrate, expectedRef func(uuid.UUID) string, outputSettled func(context.Context, uuid.UUID, string) (int64, bool, error), eraseOutput func(uuid.UUID) error) (*Manager, error)
New recovers local state. Run must start before connecting: a restart cannot reconstruct a monotonic deadline, so existing proxies are contained until an authenticated fresh lease establishes one. eraseOutput deletes one run's retained output; the manager calls it only for an org-erased (asserted) run's quarantined evidence at its retention ceiling.
func (*Manager) AdmitResident ¶ added in v0.9.3
AdmitResident binds a runner_resident delivery to a run this runner may still create: online, not revoked, a live initial lease and no creation intent yet (the Lease and BeforeCreate predicates). Lock order: Resident calls this while holding its own mutex, so Resident.mu is always taken before m.mu. The manager never calls into Resident; the revoke hook runs Revoked, which has released m.mu, and only then the resident erase.
func (*Manager) AfterRefCall ¶
func (m *Manager) AfterRefCall(ctx context.Context, method, ref, execID string, generation uuid.UUID) error
AfterRefCall records real substrate changes before the org receives success. A durable-state failure contains the proxy even when the wire call was lost.
func (*Manager) AgentExited ¶
AgentExited records exit before reporting it. Only org reconciliation may decide whether a kept headless run becomes terminal.
func (*Manager) BeforeCreate ¶
BeforeCreate commits a creation intent before any substrate side effect.
func (*Manager) BeforeReady ¶
BeforeReady enables admission only after pending actions and fresh replay. It does not write to peer; resumed peers have not started their read loop.
func (*Manager) BeforeRefCall ¶
func (m *Manager) BeforeRefCall(ctx context.Context, method, ref string, generation uuid.UUID) error
BeforeRefCall refuses any start, revive or agent execution without the authenticated connection's live lease. Containment never needs permission.
func (*Manager) CheckLapses ¶
CheckLapses stops only proxies, never the agent or its files. It is also a deterministic fake-clock test seam; failed containment is retried on every tick.
func (*Manager) CheckSelftest ¶ added in v0.9.3
CheckSelftest admits a BYOI selftest on ref only under the live lease an Exec would need, and only while its generation is the lease's and not yet attempted. It records nothing: the selftest is not that execution.
func (*Manager) Clock ¶
Clock anchors a newly authenticated connection without extending deadlines already running on the local monotonic clock.
func (*Manager) CreateFailed ¶
CreateFailed retains the durable intent and contains even ambiguous partial provisioning immediately. StopProxy cannot prove the agent absent, so this callback never authorizes deleting output or retrying the same run creation.
func (*Manager) Created ¶
Created durably binds the substrate ref before the dispatcher acknowledges creation. Wire cancellation cannot discard a successfully provisioned ref.
func (*Manager) EvidenceRunIDs ¶ added in v0.9.3
EvidenceRunIDs lists the unretired runs holding a substrate evidence record, for the relay's fence replay: a fence is dropped with the run's offline state at retirement.
func (*Manager) ExecutionResult ¶
func (m *Manager) ExecutionResult(ctx context.Context, ref string, generation uuid.UUID) (runnerwire.ExecutionResult, error)
ExecutionResult reads only the exact durable intent requested by the org. An attempted intent without a handle is ambiguous and must never run again.
func (*Manager) HoldsSandbox ¶
HoldsSandbox reports whether localRef is a sandbox this runner created and has not retired.
func (*Manager) Lease ¶
Lease is checked synchronously before a subsequent CreateSandbox CALL. The org must send the initial lease first; no token is parsed without verification.
func (*Manager) LoadEvidence ¶ added in v0.9.3
LoadEvidence returns a run's substrate evidence record (nil when none).
func (*Manager) MutationFinished ¶
func (m *Manager) MutationFinished(ctx context.Context, method, ref string, runID, generation uuid.UUID, cause error) error
MutationFinished releases the exact admitted mutation only after its safety follow-up. A failed substrate call may have taken effect and cannot clear the attempted intent or rely on a fresh lease instead of containment.
func (*Manager) ObserveProxies ¶ added in v0.9.3
ObserveProxies lists every held run's proxy in one call and records a ProxyExited obligation for each that is Failed, Succeeded, NotFound or Pending past its start timeout. A Running proxy, or one Pending within its timeout, records nothing.
func (*Manager) Offline ¶
Offline preserves agents and files. Run independently owns the safety timer; the connection's already-cancelled context cannot cancel containment.
func (*Manager) Online ¶
func (m *Manager) Online(peer *runnerwire.Peer)
Online permits new audit frames only after transport resume has replayed its old frames and started the peer. BeforeReady independently admits incoming RPCs.
func (*Manager) Pending ¶
func (m *Manager) Pending(ctx context.Context, peer *runnerwire.Peer, actions []runnerwire.PendingAction) error
Pending applies the org's durable queue in supplied order, before STATE and replay. A failed ACK retains the local result, so retry cannot repeat a destructive action against a later incarnation of the sandbox.
func (*Manager) ProvisionalDeadlines ¶ added in v0.9.3
func (m *Manager) ProvisionalDeadlines()
ProvisionalDeadlines gives each held run with no deadline and no obligation the provisional cleanup deadline restart + RunTokenTTL (design K1 §6.2 "After a restart"). The org's next lease replaces it.
func (*Manager) ProxyExited ¶ added in v0.9.3
ProxyExited records the durable obligation that a run's proxy will not serve again: on the proxy's validated lapsed frame, or an observed terminal phase or missing pod. A sink session ending is not evidence. CheckLapses contains the obligation; a NotFound records it but never ends it, since ProxyStoppedAt still needs completion evidence.
func (*Manager) ReleaseSettledOutput ¶
ReleaseSettledOutput sets the hook that deletes a retired run's output. The hook must refuse output that is not settled (complete and fully acknowledged). Without it, retirement keeps all output.
func (*Manager) Replay ¶
Replay uses only the authenticated runner peer; expired run tokens are never involved. Spool ACKs and durable exit results survive reconnect and restart.
func (*Manager) Revoked ¶
Revoked latches the durable refusal before stopping every governed proxy. The organisation owns the pending terminal-state decision and cascade.
func (*Manager) Run ¶
Run owns containment independently of connection cancellation and replay IO. The caller supplies daemon lifetime, retaining it across reconnect attempts.
func (*Manager) SaveEvidence ¶ added in v0.9.3
SaveEvidence writes a run's substrate evidence record with the state's atomic write and fsync. A run the runner holds no record of (a lost identity met by the sweep) gets a containment-only record, which CheckLapses contains.
func (*Manager) SetOptions ¶ added in v0.9.3
SetOptions applies Options before Run starts. ProxySelfLapses needs a substrate that observes its proxies, and gives every run that has no deadline yet (a restart) a provisional one, restart + RunTokenTTL: a cleanup bound, never sent to the proxy, which never clears an obligation. Call ObserveProxies first, so a run whose proxy already exited or is still Pending past its start timeout gets its obligation instead (P4).
func (*Manager) SinkRunIDs ¶ added in v0.9.3
SinkRunIDs lists the runs whose decision sink is registered again at startup: those holding a substrate evidence record that are neither retired nor erased, so a spool is never reopened.
func (*Manager) StatePages ¶
StatePages snapshots identities, then queries and emits bounded ordered pages. The fresh-session caller must keep execution admission closed until Final.
type Options ¶ added in v0.9.3
type Options struct {
// ProxySelfLapses: the substrate's proxies lapse themselves (design K1 §6.2); the substrate must
// implement runner.ProxyObserver.
ProxySelfLapses bool
// Tick runs first on each containment tick, before lapses and retirement: the k8s runner's
// decision sink regrants and retries loss rows there.
Tick func(context.Context)
}
Options are the manager's substrate-specific behaviours.
Source Files