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

peercoord

package
v0.2.11 Latest Latest
Warning

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

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

Documentation

Overview

Package peercoord defines the versioned, messages-only coordination protocol. Display names are not addresses or authority. The server binds every endpoint and execution to an authenticated peer registration.

Index

Constants

View Source
const LeaseDuration = 30 * time.Second
View Source
const MaxAgents = 100
View Source
const MaxPendingTasks = 500
View Source
const MaxText = 16384
View Source
const Version = 1

Variables

This section is empty.

Functions

func Active

func Active(state string) bool

func Apply

func Apply(original Store, a Auth, r Request, now time.Time) (Store, Response, []Event, error)

Apply is a deterministic transition over a copy. Failed requests cannot mutate the original, and persistence/commit ordering belongs to the server transaction.

func Fail

func Fail(code, format string, args ...any) error

func HashToken

func HashToken(s string) string

func ReadOnlyOp

func ReadOnlyOp(op string) bool

func Terminal

func Terminal(state string) bool

func ValidID

func ValidID(s string) bool

func ValidName

func ValidName(s string) bool

func VerifyPeer

func VerifyPeer(store Store, auth Auth, req Request) error

VerifyPeer is also checked before returning a cached mutation receipt, so a revoked registration cannot regain access through request replay.

Types

type Agent

type Agent struct {
	ID           string   `json:"id"`
	PeerID       string   `json:"peer_id"`
	Name         string   `json:"name"`
	Label        string   `json:"label"`
	Role         string   `json:"role"`
	Runner       string   `json:"runner"`
	Projects     []string `json:"projects"`
	Capabilities []string `json:"capabilities"`
	MaxActive    int      `json:"max_active"`
	Ready        bool     `json:"ready"`
}

type Attempt

type Attempt struct {
	ID          string          `json:"id"`
	Number      int             `json:"number"`
	AgentID     string          `json:"agent_id"`
	ExecutionID string          `json:"execution_id,omitempty"`
	Incarnation string          `json:"incarnation,omitempty"`
	State       string          `json:"state"`
	LeaseUntil  time.Time       `json:"lease_until"`
	PaneID      string          `json:"pane_id,omitempty"`
	StartedAt   *time.Time      `json:"started_at,omitempty"`
	EndedAt     *time.Time      `json:"ended_at,omitempty"`
	Result      json.RawMessage `json:"result,omitempty"`
	Detail      string          `json:"detail,omitempty"`
}

type Auth

type Auth struct {
	UserID         string
	WorkspaceRole  string
	PeerToken      string
	ExecutionToken string
}

Auth is supplied by the HTTP/daemon boundary, never decoded from Request.

type Error

type Error struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

func (*Error) Error

func (e *Error) Error() string

type Event

type Event struct {
	SchemaVersion int       `json:"schema_version"`
	ID            string    `json:"id"`
	Sequence      int64     `json:"sequence"`
	Kind          string    `json:"kind"`
	SenderID      string    `json:"sender_id,omitempty"`
	RecipientID   string    `json:"recipient_id,omitempty"`
	TaskID        string    `json:"task_id,omitempty"`
	AttemptID     string    `json:"attempt_id,omitempty"`
	ThreadID      string    `json:"thread_id,omitempty"`
	Text          string    `json:"text"`
	CreatedAt     time.Time `json:"created_at"`
}

type Leadership

type Leadership struct {
	AgentID      string    `json:"agent_id"`
	Term         int64     `json:"term"`
	LeaseUntil   time.Time `json:"lease_until"`
	Standbys     []string  `json:"standbys"`
	AutoFailover bool      `json:"auto_failover"`
}

type Page

type Page struct {
	Events  []Event `json:"events"`
	Next    int64   `json:"next"`
	HasMore bool    `json:"has_more"`
}

type Peer

type Peer struct {
	ID          string    `json:"id"`
	UserID      string    `json:"user_id"`
	SessionID   string    `json:"session_id"`
	SessionName string    `json:"session_name"`
	Incarnation string    `json:"incarnation"`
	LastSeen    time.Time `json:"last_seen"`
	LeaseUntil  time.Time `json:"lease_until"`
	State       string    `json:"state"`
}

type Request

type Request struct {
	SchemaVersion     int             `json:"schema_version"`
	ID                string          `json:"id"`
	Op                string          `json:"op"`
	PeerID            string          `json:"peer_id,omitempty"`
	AgentID           string          `json:"agent_id,omitempty"`
	SessionID         string          `json:"session_id,omitempty"`
	SessionName       string          `json:"session_name,omitempty"`
	Incarnation       string          `json:"incarnation,omitempty"`
	Name              string          `json:"name,omitempty"`
	Role              string          `json:"role,omitempty"`
	Runner            string          `json:"runner,omitempty"`
	Projects          []string        `json:"projects,omitempty"`
	Capabilities      []string        `json:"capabilities,omitempty"`
	MaxActive         int             `json:"max_active,omitempty"`
	Ready             bool            `json:"ready,omitempty"`
	ActiveAgents      []string        `json:"active_agents,omitempty"`
	Running           []string        `json:"running,omitempty"`
	ConfirmStopped    bool            `json:"confirm_stopped,omitempty"`
	Target            string          `json:"target,omitempty"`
	Term              int64           `json:"term,omitempty"`
	TaskID            string          `json:"task_id,omitempty"`
	AttemptID         string          `json:"attempt_id,omitempty"`
	TaskVersion       int64           `json:"task_version,omitempty"`
	ExecutionID       string          `json:"execution_id,omitempty"`
	PaneID            string          `json:"pane_id,omitempty"`
	Text              string          `json:"text,omitempty"`
	Criteria          string          `json:"criteria,omitempty"`
	Project           string          `json:"project,omitempty"`
	Base              string          `json:"base,omitempty"`
	Dependencies      []string        `json:"dependencies,omitempty"`
	MaxRuntimeSeconds int             `json:"max_runtime_seconds,omitempty"`
	Result            json.RawMessage `json:"result,omitempty"`
	Standbys          []string        `json:"standbys,omitempty"`
	AutoFailover      bool            `json:"auto_failover,omitempty"`
	Paused            bool            `json:"paused,omitempty"`
}

type Response

type Response struct {
	SchemaVersion int         `json:"schema_version"`
	Peer          *Peer       `json:"peer,omitempty"`
	Agent         *Agent      `json:"agent,omitempty"`
	Task          *Task       `json:"task,omitempty"`
	Leadership    *Leadership `json:"leadership,omitempty"`
	Event         *Event      `json:"event,omitempty"`
	Replayed      bool        `json:"replayed"`
	ServerTime    time.Time   `json:"server_time"`
}

type State

type State struct {
	SchemaVersion int               `json:"schema_version"`
	Enabled       bool              `json:"enabled"`
	Paused        bool              `json:"paused"`
	OperatorID    string            `json:"operator_id"`
	Leadership    Leadership        `json:"leadership"`
	Peers         map[string]*Peer  `json:"peers"`
	Agents        map[string]*Agent `json:"agents"`
	Tasks         map[string]*Task  `json:"tasks"`
	NextTask      int64             `json:"next_task"`
	ServerTime    time.Time         `json:"server_time"`
}

func (State) ResolveAgent

func (s State) ResolveAgent(ref string) (*Agent, error)

func (State) ResolveTask

func (s State) ResolveTask(ref string) (*Task, error)

type Store

type Store struct {
	State            State             `json:"state"`
	PeerSecrets      map[string]string `json:"peer_secrets"`
	ExecutionSecrets map[string]string `json:"execution_secrets"`
}

Store includes authentication material that must never be returned by a read API.

func NewStore

func NewStore() Store

type Task

type Task struct {
	ID                string    `json:"id"`
	Number            int64     `json:"number"`
	ThreadID          string    `json:"thread_id"`
	Objective         string    `json:"objective"`
	Criteria          string    `json:"criteria"`
	Project           string    `json:"project"`
	Base              string    `json:"base,omitempty"`
	Runner            string    `json:"runner"`
	AgentID           string    `json:"agent_id"`
	LeaderID          string    `json:"leader_id"`
	LeaderTerm        int64     `json:"leader_term"`
	Version           int64     `json:"version"`
	State             string    `json:"state"`
	Dependencies      []string  `json:"dependencies"`
	MaxRuntimeSeconds int       `json:"max_runtime_seconds"`
	CreatedAt         time.Time `json:"created_at"`
	UpdatedAt         time.Time `json:"updated_at"`
	Attempts          []Attempt `json:"attempts"`
}

func (*Task) Current

func (t *Task) Current() *Attempt

func (Task) Label

func (t Task) Label() string

Jump to

Keyboard shortcuts

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