sessionrecord

package
v0.0.7 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package sessionrecord records the hub's proxy sessions durably (Task 20383): the git proxy's lease-path and workspace sessions, the Kubernetes monitor's sessions and every run's egress session, in statedb's proxy_sessions (migrations/0058_proxy_sessions.sql), so the hub process that adopts a run after the one serving it stops can restore them; and the CI relay's sessions, in ci_sessions (migrations/0060_ci_sessions.sql, Task 20390), so the hub process that receives a job's next call after the one serving it stops can restore the job's session.

It is the seam between three registries that must not know about the database — pkg/gitproxy, pkg/kubeguard, pkg/egressbroker each define a SessionStore — and the table. Each store writes as the hub process its Holder names, the cluster member id the run's lease is recorded under, and every write after the insert is fenced on it: a session another process took over with its run is that process's to extend, checkpoint and close.

What goes in a row is what the registries keep in memory instead of a credential: the SHA-256 of the token a sandbox presents, and the scope the session enforces. The record types it is handed have no field a credential could travel in, and tests/security scans the table after a realistic run for anything that did.

Index

Constants

This section is empty.

Variables

View Source
var ErrNoHolder = errors.New("this hub process has no cluster member id to record sessions under")

ErrNoHolder: the process has no cluster member id to record a session under, so nothing could take it over.

Functions

func EgressCounters

EgressCounters decodes an egress row's counters, zero when they do not parse.

func EgressRecord

EgressRecord reads a row back into what egressbroker.Broker.RestoreSession takes.

func GitRecord

GitRecord reads a row back into what gitproxy.Registry.Restore takes.

func KubeRecord

KubeRecord reads a row back into what kubeguard.Registry.Restore takes.

Types

type CIProvenance

type CIProvenance struct {
	RuleName   string          `json:"rule_name,omitempty"`
	Project    string          `json:"project,omitempty"`
	Subject    string          `json:"subject,omitempty"`
	Repository string          `json:"repository,omitempty"`
	Ref        string          `json:"ref,omitempty"`
	Workflow   string          `json:"workflow,omitempty"`
	Actor      string          `json:"actor,omitempty"`
	RunID      string          `json:"run_id,omitempty"`
	RunURL     string          `json:"run_url,omitempty"`
	Claims     json.RawMessage `json:"claims,omitempty"`
}

CIProvenance is a CI relay session's provenance_json (Task 20390): which pipeline its rule admitted. Claims is the verified payload of the OIDC token the session was minted for — the job's identity, not a credential: the token's signature is not kept, so nothing here can be exchanged again.

func CIRecord

CIRecord reads a row back into what claudeproxy.Registry.Restore takes, and its provenance.

type CIStore

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

CIStore is a claudeproxy.SessionStore over the control plane's database, recording CI relay sessions in ci_sessions (Task 20390). Its writes after the insert are fenced on the holder, like the other stores'.

func NewCIStore

func NewCIStore(db *statedb.DB, holder func() string, instance string,
	onError func(kind, id, what string, err error)) CIStore

NewCIStore returns a store writing as holder, for the hub instance named instance.

func (CIStore) CheckpointSession

func (c CIStore) CheckpointSession(id string, u claudeproxy.Usage, lastUsed time.Time) error

CheckpointSession implements claudeproxy.SessionStore. A checkpoint that lands on no row is an error, so the registry writes it again next time rather than believing the record holds it.

func (CIStore) CloseSession

func (c CIStore) CloseSession(id, reason string, at time.Time, u claudeproxy.Usage) error

CloseSession implements claudeproxy.SessionStore.

func (CIStore) SaveSession

func (c CIStore) SaveSession(rec claudeproxy.SessionRecord) error

SaveSession implements claudeproxy.SessionStore.

type EgressScope

type EgressScope struct {
	Grant  egressbroker.Grant `json:"grant"`
	Labels map[string]string  `json:"labels,omitempty"`
}

EgressScope is an egress session's scope_json.

type EgressStore

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

EgressStore is an egressbroker.SessionStore over the control plane's database.

func NewEgressStore

func NewEgressStore(db *statedb.DB, holder func() string, onError func(kind, id, what string, err error)) EgressStore

NewEgressStore returns a store writing as holder.

func (EgressStore) CheckpointSession

func (e EgressStore) CheckpointSession(id string, c egressbroker.SessionCounters) error

CheckpointSession implements egressbroker.SessionStore. A checkpoint that lands on no row is an error, so the broker writes it again next time rather than believing the record holds it.

func (EgressStore) CloseSession

func (e EgressStore) CloseSession(id, reason string, at time.Time, c egressbroker.SessionCounters) error

CloseSession implements egressbroker.SessionStore.

func (EgressStore) ExtendSession

func (e EgressStore) ExtendSession(id string, expiresAt time.Time) error

ExtendSession implements egressbroker.SessionStore.

func (EgressStore) RelabelSession added in v0.0.7

func (e EgressStore) RelabelSession(id string, labels map[string]string) error

RelabelSession implements egressbroker.SessionLabelStore: the record's labels become the session's executor's new ones (Task 20432), so a process restoring it judges its grant as this one does. A rewrite that lands on no row is an error, as a checkpoint's is.

func (EgressStore) SaveSession

func (e EgressStore) SaveSession(rec egressbroker.SessionRecord) error

SaveSession implements egressbroker.SessionStore.

type GitScope

type GitScope struct {
	RepoPath     string   `json:"repo_path,omitempty"`
	RepoPatterns []string `json:"repo_patterns,omitempty"`
	Upstream     string   `json:"upstream"`
	// ForgeHost is the forge host the session's credential is good against
	// (Task 20423). Absent from a record written before hosts were recorded,
	// which gitproxy reads as github.com for a scoped session and the
	// upstream's host for a pinned one.
	ForgeHost string          `json:"forge_host,omitempty"`
	Policy    gitproxy.Policy `json:"policy"`
}

GitScope is a git session's scope_json.

func GitScopeOf

func GitScopeOf(row statedb.ProxySessionRow) (GitScope, error)

GitScopeOf decodes a git row's scope.

type GitStore

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

GitStore is a gitproxy.SessionStore over the control plane's database.

func NewGitStore

func NewGitStore(db *statedb.DB, holder func() string, onError func(kind, id, what string, err error)) GitStore

NewGitStore returns a store writing as holder.

func (GitStore) CloseSession

func (g GitStore) CloseSession(id, reason string, at time.Time) error

CloseSession implements gitproxy.SessionStore.

func (GitStore) RenewSession added in v0.0.6

func (g GitStore) RenewSession(id string, expiresAt, renewedAt time.Time) error

RenewSession implements gitproxy.SessionStore.

func (GitStore) SaveSession

func (g GitStore) SaveSession(rec gitproxy.SessionRecord) error

SaveSession implements gitproxy.SessionStore.

type KubeScope

type KubeScope struct {
	ClusterURL string           `json:"cluster_url"`
	Context    string           `json:"context,omitempty"`
	Policy     kubeguard.Policy `json:"policy"`
}

KubeScope is a Kubernetes monitor session's scope_json.

func KubeScopeOf

func KubeScopeOf(row statedb.ProxySessionRow) (KubeScope, error)

KubeScopeOf decodes a kube row's scope.

type KubeStore

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

KubeStore is a kubeguard.SessionStore over the control plane's database.

func NewKubeStore

func NewKubeStore(db *statedb.DB, holder func() string, onError func(kind, id, what string, err error)) KubeStore

NewKubeStore returns a store writing as holder.

func (KubeStore) CloseSession

func (k KubeStore) CloseSession(id, reason string, at time.Time) error

CloseSession implements kubeguard.SessionStore.

func (KubeStore) SaveSession

func (k KubeStore) SaveSession(rec kubeguard.SessionRecord) error

SaveSession implements kubeguard.SessionStore.

type ModelCounters added in v0.0.7

type ModelCounters struct {
	Usage claudeproxy.Usage `json:"usage"`
	Spend ModelSpend        `json:"spend"`
}

ModelCounters is a model relay session's counters_json.

func ModelCountersOf added in v0.0.7

func ModelCountersOf(row statedb.ProxySessionRow) (ModelCounters, error)

ModelCountersOf decodes a model row's counters; an empty document is zero.

type ModelScope added in v0.0.7

type ModelScope struct {
	Policy       claudeproxy.Policy `json:"policy"`
	UpstreamKind string             `json:"upstream_kind"`
	Payer        string             `json:"payer,omitempty"`
	Run          json.RawMessage    `json:"run,omitempty"`
}

ModelScope is a model relay session's scope_json (Task 20435): the model policy it enforces, the kind of credential it spends — never the credential, which the process restoring it re-derives from the lease the session stands on — the identity its spend is charged to, and the hub's own account of the run it serves, opaque here.

func ModelScopeOf added in v0.0.7

func ModelScopeOf(row statedb.ProxySessionRow) (ModelScope, error)

ModelScopeOf decodes a model row's scope.

type ModelSpend added in v0.0.7

type ModelSpend struct {
	USD    float64                `json:"usd"`
	Models map[string]ModelTokens `json:"models,omitempty"`
}

ModelSpend is what a session has spent, priced, per model — the account the hub charged to its payer as each response arrived, recorded so a process adopting the run carries it on.

func ModelRecord added in v0.0.7

ModelRecord reads a row back into what claudeproxy.Registry.Restore takes, and the spend its counters recorded. The run binding comes back as the record's Claims.

func (ModelSpend) Clone added in v0.0.7

func (s ModelSpend) Clone() ModelSpend

Clone copies s.

type ModelStore added in v0.0.7

type ModelStore struct {

	// Spend reports what a session has spent, per model, for its counters:
	// the hub keeps that account, the registry keeps only token totals. Nil
	// records none.
	Spend func(id string) ModelSpend
	// contains filtered or unexported fields
}

ModelStore is a claudeproxy.SessionStore over the control plane's database, recording run relay sessions in proxy_sessions with kind "model". Its writes after the insert are fenced on the holder, like the other stores'.

func NewModelStore added in v0.0.7

func NewModelStore(db *statedb.DB, holder func() string, spend func(id string) ModelSpend,
	onError func(kind, id, what string, err error)) ModelStore

NewModelStore returns a store writing as holder.

func (ModelStore) CheckpointSession added in v0.0.7

func (m ModelStore) CheckpointSession(id string, u claudeproxy.Usage, _ time.Time) error

CheckpointSession implements claudeproxy.SessionStore. A checkpoint that lands on no row reports claudeproxy.ErrRecordGone, so the registry stops serving a session another process holds now or a revocation closed.

func (ModelStore) CloseSession added in v0.0.7

func (m ModelStore) CloseSession(id, reason string, at time.Time, u claudeproxy.Usage) error

CloseSession implements claudeproxy.SessionStore.

func (ModelStore) RenewSession added in v0.0.7

func (m ModelStore) RenewSession(id string, expiresAt, renewedAt time.Time) error

RenewSession implements claudeproxy.SessionRenewer.

func (ModelStore) SaveSession added in v0.0.7

func (m ModelStore) SaveSession(rec claudeproxy.SessionRecord) error

SaveSession implements claudeproxy.SessionStore.

type ModelTokens added in v0.0.7

type ModelTokens struct {
	Input      int64 `json:"input_tokens"`
	Output     int64 `json:"output_tokens"`
	CacheRead  int64 `json:"cache_read_input_tokens,omitempty"`
	CacheWrite int64 `json:"cache_creation_input_tokens,omitempty"`
}

ModelTokens is what one model spent through a session.

Jump to

Keyboard shortcuts

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