Documentation
¶
Overview ¶
Package codexinstance publishes and discovers live, attachable Codex instances.
A registry is scoped to a private runtime directory. Descriptor filenames are derived from both the canonical Intercom broker socket and the validated peer name, so independent brokers and peers can safely share one registry. Publish is a cross-process claim operation: a different live owner is never overwritten, while an owner whose PID no longer exists is replaced. A repeated publish with the same instance nonce is an idempotent owner update.
Remove is similarly ownership-aware. It removes a descriptor only while its nonce still matches, under the same lock used by Publish. Cleanup from an old instance therefore cannot unlink a concurrently published replacement.
Index ¶
- Constants
- Variables
- func CanonicalBrokerSocket(path string) (string, error)
- func CanonicalCWD(path string) (string, error)
- func CanonicalUnixEndpoint(endpoint string) (string, error)
- func NewNonce() (string, error)
- type AlreadyLiveError
- type Descriptor
- type ExecutionPolicy
- type Registry
- func (r *Registry) Dir() string
- func (r *Registry) Load(brokerSocket, peer string) (*Descriptor, error)
- func (r *Registry) Path(brokerSocket, peer string) (string, error)
- func (r *Registry) Publish(d Descriptor) (string, error)
- func (r *Registry) Remove(brokerSocket, peer, nonce string) (bool, error)
- type StaleError
Constants ¶
const SchemaVersion = 2
SchemaVersion is the only descriptor schema this package currently accepts.
Variables ¶
var ( // ErrAlreadyLive identifies a Publish failure caused by a different // descriptor owner whose recorded PID still exists. ErrAlreadyLive = errors.New("codex instance is already live") // ErrStale identifies a descriptor that is structurally valid but whose // recorded owner PID no longer exists. ErrStale = errors.New("codex instance descriptor is stale") )
Functions ¶
func CanonicalBrokerSocket ¶
CanonicalBrokerSocket resolves path against the current working directory and returns the clean absolute socket identity used in descriptor keys.
func CanonicalCWD ¶
CanonicalCWD resolves path against the current working directory and returns its clean absolute spelling. It intentionally does not resolve symlinks: the Codex thread identity uses the lexical absolute cwd supplied at startup.
func CanonicalUnixEndpoint ¶
CanonicalUnixEndpoint validates endpoint and returns its normalized unix:///absolute/path spelling. Host, user info, query, and fragment components are forbidden.
Types ¶
type AlreadyLiveError ¶
type AlreadyLiveError struct {
Existing Descriptor
}
AlreadyLiveError reports the descriptor that prevented a new owner from claiming the same broker-and-peer key.
func (*AlreadyLiveError) Error ¶
func (e *AlreadyLiveError) Error() string
func (*AlreadyLiveError) Unwrap ¶
func (e *AlreadyLiveError) Unwrap() error
type Descriptor ¶
type Descriptor struct {
SchemaVersion int `json:"schemaVersion"`
Peer string `json:"peer"`
CWD string `json:"cwd"`
BrokerSocketIdentity string `json:"brokerSocketIdentity"`
DownstreamUnixEndpoint string `json:"downstreamUnixEndpoint"`
ThreadID string `json:"threadId"`
PID int `json:"pid"`
InstanceNonce string `json:"instanceNonce"`
CodexVersion string `json:"codexVersion"`
ExecutionPolicy ExecutionPolicy `json:"executionPolicy"`
}
Descriptor is the complete discovery record for one live Codex instance. CWD and BrokerSocketIdentity are canonical absolute filesystem paths. DownstreamUnixEndpoint is the canonical unix:///absolute/path form.
func (Descriptor) Validate ¶
func (d Descriptor) Validate() error
Validate checks descriptor compatibility, identity fields, and canonical path/endpoint representation. It does not probe the process or either Unix socket; those are lifecycle concerns handled by the publisher and attacher.
type ExecutionPolicy ¶ added in v0.2.2
type ExecutionPolicy string
const ( ExecutionWorkspaceWrite ExecutionPolicy = "workspace-write" ExecutionDangerFullAccess ExecutionPolicy = "danger-full-access" )
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry stores live descriptors in one mode-0700 directory. Registry values are safe for concurrent goroutines and cooperating processes.
func New ¶
New creates or opens liveDir and forces its mode to 0700. The final path component must be a real directory, not a symlink. Later operations reject a directory whose type or permissions have changed.
func (*Registry) Load ¶
func (r *Registry) Load(brokerSocket, peer string) (*Descriptor, error)
Load returns the strictly validated, live descriptor for brokerSocket and peer. It returns nil, nil when no descriptor currently exists and ErrStale when a valid descriptor's PID no longer exists. Loads need no lock: Publish uses rename, so a reader observes either a complete old descriptor or a complete new one.
func (*Registry) Path ¶
Path returns the deterministic descriptor path for brokerSocket and peer. The full SHA-256 digest of the canonical broker-and-peer key makes cross-broker filename collisions negligible; the validated peer prefix keeps directory listings intelligible.
func (*Registry) Publish ¶
func (r *Registry) Publish(d Descriptor) (string, error)
Publish atomically claims or updates d's broker-and-peer key and returns its descriptor path. It behaves as follows while holding a cross-process lock:
- no prior descriptor: publish d;
- the same instance nonce: atomically update the owner's descriptor;
- a different nonce whose PID no longer exists: replace the stale record;
- a different nonce whose PID exists: return ErrAlreadyLive unchanged.
A malformed or insecure prior descriptor is never silently discarded. If publication reaches rename but the following directory sync fails, Publish removes the renamed descriptor only while d's nonce still owns it.
func (*Registry) Remove ¶
Remove deletes the descriptor only if nonce still owns it. The bool reports whether a file was removed. A missing descriptor or a nonce mismatch returns false, nil, making shutdown cleanup idempotent and safe after stale-record replacement. The nonce comparison and unlink occur under the Publish lock.
type StaleError ¶
type StaleError struct {
Descriptor Descriptor
}
StaleError reports the no-longer-live descriptor found by Load. Callers can use errors.As to include its PID or endpoint in a diagnostic. Publish, rather than Load, owns stale-record replacement.
func (*StaleError) Error ¶
func (e *StaleError) Error() string
func (*StaleError) Unwrap ¶
func (e *StaleError) Unwrap() error
Source Files