Documentation
¶
Index ¶
- Constants
- type ArtifactRef
- type DerivedStatus
- type Endpoint
- type EndpointRole
- type EndpointSpec
- type EndpointState
- type ErrorCode
- type Event
- type EventCursor
- type EventReplayState
- type EventType
- type GatewayCandidate
- type Host
- type IdempotencyRecord
- type Lease
- type LeaseRecord
- type LeaseSpec
- type Limits
- type MemoryStore
- func (s *MemoryStore) AppendEvent(sessionID string, event Event) (Event, error)
- func (s *MemoryStore) AppendEventBatch(sessionID string, batch []Event) ([]Event, error)
- func (s *MemoryStore) CancelTask(sessionID, taskID, reason, idempotencyKey string) (Task, Event, error)
- func (s *MemoryStore) CloseSession(sessionID string) (Session, Event, error)
- func (s *MemoryStore) CompactEvents(sessionID string, snapshotSeq uint64) error
- func (s *MemoryStore) CompleteTask(sessionID, taskID string, result map[string]any) (Task, Event, error)
- func (s *MemoryStore) CreateSession(spec SessionSpec) (Session, error)
- func (s *MemoryStore) EventsAfter(sessionID string, cursor EventCursor, limit int) ([]Event, Lease, EventReplayState, error)
- func (s *MemoryStore) EventsAfterForAgent(sessionID string, afterSeq uint64, limit int) ([]Event, EventReplayState, error)
- func (s *MemoryStore) Hosts() []Host
- func (s *MemoryStore) JoinByCode(joinCode string, spec EndpointSpec) (Session, Endpoint, Lease, []Event, error)
- func (s *MemoryStore) JoinSession(sessionID string, spec EndpointSpec) (Session, Endpoint, Lease, error)
- func (s *MemoryStore) MarkTaskRunning(sessionID, taskID string) (Task, error)
- func (s *MemoryStore) PeekEventsAfter(sessionID string, cursor EventCursor, limit int) ([]Event, Lease, EventReplayState, error)
- func (s *MemoryStore) RenameHost(hostID, displayName string) (Host, error)
- func (s *MemoryStore) RestoreSnapshot(snapshot Snapshot) error
- func (s *MemoryStore) ResumeTask(sessionID, taskID, checkpointID, idempotencyKey string) (Task, Event, error)
- func (s *MemoryStore) RevokeSession(sessionID string) (Session, Event, error)
- func (s *MemoryStore) Session(sessionID string) (Session, error)
- func (s *MemoryStore) SetEventHook(hook func(sessionID string, event Event, notifyURL string))
- func (s *MemoryStore) SetSessionNotifyURL(sessionID, notifyURL string) (Session, error)
- func (s *MemoryStore) Snapshot() Snapshot
- func (s *MemoryStore) SubmitTask(sessionID string, spec TaskSpec) (Task, Event, error)
- func (s *MemoryStore) UpsertArtifact(sessionID string, ref ArtifactRef) (ArtifactRef, Event, error)
- func (s *MemoryStore) UpsertHostLocked(session Session, endpoint Endpoint, now time.Time)
- func (s *MemoryStore) ValidateLease(sessionID, endpointID, secret string) error
- type ProtocolError
- type Session
- type SessionSnapshot
- type SessionSpec
- type SessionStatus
- type Snapshot
- type StatusSummary
- type TargetSelector
- type Task
- type TaskRecord
- type TaskSpec
- type TaskStatus
- type Transport
Constants ¶
const ( SessionSchemaVersion = "rdev.session.v1" EndpointSchemaVersion = "rdev.endpoint.v1" LeaseSchemaVersion = "rdev.lease.v1" EventSchemaVersion = "rdev.event.v1" TaskSchemaVersion = "rdev.task.v1" ArtifactRefSchemaVersion = "rdev.artifact-ref.v1" ErrorSchemaVersion = "rdev.error.v1" )
const HostSchemaVersion = "rdev.host.v1"
const (
MaxHostDisplayNameLength = 64
)
const SnapshotSchemaVersion = "rdev.control-plane-snapshot.v1"
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ArtifactRef ¶
type ArtifactRef struct {
SchemaVersion string `json:"schema_version"`
ID string `json:"id"`
SessionID string `json:"session_id"`
TaskID string `json:"task_id"`
Kind string `json:"kind"`
Name string `json:"name"`
SizeBytes int64 `json:"size_bytes"`
SHA256 string `json:"sha256"`
ContentType string `json:"content_type"`
UploadOffset int64 `json:"upload_offset"`
Complete bool `json:"complete"`
}
type DerivedStatus ¶
type DerivedStatus string
const ( StatusJoining DerivedStatus = "joining" StatusHelperDownloading DerivedStatus = "helper-downloading" StatusHelperVerifying DerivedStatus = "helper-verifying" StatusGatewaySwitching DerivedStatus = "gateway-switching" StatusOnline DerivedStatus = "online" StatusBusy DerivedStatus = "busy" StatusTransportDegraded DerivedStatus = "transport-degraded" StatusReconnecting DerivedStatus = "reconnecting" StatusRecovered DerivedStatus = "recovered" StatusWaiting DerivedStatus = "waiting" StatusFailed DerivedStatus = "failed" StatusClosed DerivedStatus = "closed" )
type Endpoint ¶
type Endpoint struct {
SchemaVersion string `json:"schema_version"`
ID string `json:"id"`
SessionID string `json:"session_id"`
Role EndpointRole `json:"role"`
Name string `json:"name"`
Platform string `json:"platform"`
IdentityFingerprint string `json:"identity_fingerprint"`
Capabilities []string `json:"capabilities"`
State EndpointState `json:"state"`
Transport Transport `json:"transport"`
ReceivedSeq uint64 `json:"received_seq"`
ProcessedSeq uint64 `json:"processed_seq"`
LastSeenAt time.Time `json:"last_seen_at"`
HostVersion string `json:"host_version,omitempty"`
HostCommit string `json:"host_commit,omitempty"`
}
type EndpointRole ¶
type EndpointRole string
const ( EndpointRoleTarget EndpointRole = "target" EndpointRoleAgent EndpointRole = "agent" EndpointRoleOperator EndpointRole = "operator" EndpointRoleGateway EndpointRole = "gateway" EndpointRoleWorker EndpointRole = "worker" EndpointRoleWorkspace EndpointRole = "workspace" EndpointRoleAdapter EndpointRole = "adapter" )
type EndpointSpec ¶
type EndpointSpec struct {
EndpointID string `json:"endpoint_id"`
Role EndpointRole `json:"role"`
Name string `json:"name"`
Platform string `json:"platform"`
IdentityFingerprint string `json:"identity_fingerprint"`
Capabilities []string `json:"capabilities"`
Transport Transport `json:"transport"`
LeaseTTLMS int `json:"lease_ttl_ms"`
RenewAfterMS int `json:"renew_after_ms"`
RetryAfterMS int `json:"retry_after_ms"`
PreviousLeaseSecret string `json:"previous_lease_secret"`
// HostVersion and HostCommit report the connector build that joined. The
// control plane surfaces them on the endpoint so operators can verify a
// remote host update by comparing them against the promoted release.
HostVersion string `json:"host_version,omitempty"`
HostCommit string `json:"host_commit,omitempty"`
}
type EndpointState ¶
type EndpointState string
const ( EndpointStateJoining EndpointState = "joining" EndpointStateOnline EndpointState = "online" EndpointStateBusy EndpointState = "busy" EndpointStateDegraded EndpointState = "degraded" EndpointStateReconnecting EndpointState = "reconnecting" EndpointStateOffline EndpointState = "offline" EndpointStateClosed EndpointState = "closed" EndpointStateRevoked EndpointState = "revoked" )
type ErrorCode ¶
type ErrorCode string
const ( ErrInvalidJoinCode ErrorCode = "invalid_join_code" ErrJoinPolicyRejected ErrorCode = "join_policy_rejected" ErrLeaseExpired ErrorCode = "lease_expired" ErrStaleReplica ErrorCode = "stale_replica" ErrSnapshotRequired ErrorCode = "snapshot_required" ErrPayloadTooLarge ErrorCode = "payload_too_large" ErrTooManyEvents ErrorCode = "too_many_events" ErrArtifactOffsetMismatch ErrorCode = "artifact_offset_mismatch" ErrChecksumMismatch ErrorCode = "checksum_mismatch" ErrInvalidTask ErrorCode = "invalid_task" ErrTaskNotFound ErrorCode = "task_not_found" ErrTaskAlreadyTerminal ErrorCode = "task_already_terminal" ErrSessionClosed ErrorCode = "session_closed" ErrAuthorityMismatch ErrorCode = "authority_mismatch" ErrIdempotencyConflict ErrorCode = "idempotency_conflict" ErrEndpointNotFound ErrorCode = "endpoint_not_found" ErrStaleCursor ErrorCode = "stale_cursor" ErrTerminalSession ErrorCode = "terminal_session" )
type Event ¶
type Event struct {
SchemaVersion string `json:"schema_version"`
ID string `json:"id"`
SessionID string `json:"session_id"`
Seq uint64 `json:"seq"`
Type EventType `json:"type"`
FromEndpointID string `json:"from_endpoint_id"`
ToEndpointID string `json:"to_endpoint_id"`
TaskID string `json:"task_id"`
IdempotencyKey string `json:"idempotency_key"`
Payload map[string]any `json:"payload,omitempty"`
CreatedAt time.Time `json:"created_at"`
}
type EventCursor ¶
type EventCursor struct {
EndpointID string `json:"endpoint_id"`
LeaseSecret string `json:"lease_secret"`
AfterSeq uint64 `json:"after_seq"`
ReceivedSeq uint64 `json:"received_seq"`
ProcessedSeq uint64 `json:"processed_seq"`
VisibleRole EndpointRole `json:"visible_role"`
EndpointState EndpointState `json:"endpoint_state"`
}
type EventReplayState ¶
type EventType ¶
type EventType string
const ( EventTypeHello EventType = "hello" EventTypeHelper EventType = "helper" EventTypeGateway EventType = "gateway" EventTypeTransport EventType = "transport" EventTypeStatus EventType = "status" EventTypeTask EventType = "task" EventTypeTaskProgress EventType = "task.progress" EventTypeTaskResult EventType = "task.result" EventTypeArtifact EventType = "artifact" EventTypeInterrupt EventType = "interrupt" EventTypeClose EventType = "close" )
type GatewayCandidate ¶
type Host ¶
type Host struct {
SchemaVersion string `json:"schema_version"`
HostID string `json:"host_id"`
IdentityFingerprint string `json:"identity_fingerprint"`
DisplayName string `json:"display_name"`
Platform string `json:"platform"`
Capabilities []string `json:"capabilities,omitempty"`
State EndpointState `json:"state"`
FirstSeenAt time.Time `json:"first_seen_at"`
LastSeenAt time.Time `json:"last_seen_at"`
LastSessionID string `json:"last_session_id,omitempty"`
LastEndpointID string `json:"last_endpoint_id,omitempty"`
}
Host is the durable directory record for a target identity. The registry is keyed by the host's identity fingerprint so reconnects and new sessions keep one stable directory entry. DisplayName is operator-controlled and is never overwritten by a rejoin; the connector-provided name only seeds a new record.
type IdempotencyRecord ¶
type Lease ¶
type Lease struct {
SchemaVersion string `json:"schema_version"`
ID string `json:"id"`
SessionID string `json:"session_id"`
EndpointID string `json:"endpoint_id"`
Generation int `json:"generation"`
Secret string `json:"secret"`
Transport Transport `json:"transport"`
SelectedGatewayURL string `json:"selected_gateway_url"`
RenewAfter time.Time `json:"renew_after"`
ExpiresAt time.Time `json:"expires_at"`
ServerTime time.Time `json:"server_time"`
LeaseTTLMS int `json:"lease_ttl_ms"`
RenewAfterMS int `json:"renew_after_ms"`
RetryAfterMS int `json:"retry_after_ms"`
}
type LeaseRecord ¶
type Limits ¶
type Limits struct {
EventPayloadBytes int `json:"event_payload_bytes"`
EventBatch int `json:"event_batch"`
ArtifactChunkBytes int `json:"artifact_chunk_bytes"`
InlineTaskSummaryBytes int `json:"inline_task_result_summary_bytes"`
TerminalGraceMillis int `json:"terminal_grace_ms,omitempty"`
IdempotencyRetentionSeq int `json:"idempotency_retention_seq,omitempty"`
}
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
func NewMemoryStore ¶
func NewMemoryStore(clock func() time.Time) *MemoryStore
func (*MemoryStore) AppendEvent ¶
func (s *MemoryStore) AppendEvent(sessionID string, event Event) (Event, error)
func (*MemoryStore) AppendEventBatch ¶
func (s *MemoryStore) AppendEventBatch(sessionID string, batch []Event) ([]Event, error)
func (*MemoryStore) CancelTask ¶
func (s *MemoryStore) CancelTask(sessionID, taskID, reason, idempotencyKey string) (Task, Event, error)
func (*MemoryStore) CloseSession ¶
func (s *MemoryStore) CloseSession(sessionID string) (Session, Event, error)
func (*MemoryStore) CompactEvents ¶
func (s *MemoryStore) CompactEvents(sessionID string, snapshotSeq uint64) error
func (*MemoryStore) CompleteTask ¶
func (*MemoryStore) CreateSession ¶
func (s *MemoryStore) CreateSession(spec SessionSpec) (Session, error)
func (*MemoryStore) EventsAfter ¶
func (s *MemoryStore) EventsAfter(sessionID string, cursor EventCursor, limit int) ([]Event, Lease, EventReplayState, error)
func (*MemoryStore) EventsAfterForAgent ¶
func (s *MemoryStore) EventsAfterForAgent(sessionID string, afterSeq uint64, limit int) ([]Event, EventReplayState, error)
func (*MemoryStore) Hosts ¶
func (s *MemoryStore) Hosts() []Host
Hosts returns the durable directory, newest last-seen first.
func (*MemoryStore) JoinByCode ¶
func (s *MemoryStore) JoinByCode(joinCode string, spec EndpointSpec) (Session, Endpoint, Lease, []Event, error)
func (*MemoryStore) JoinSession ¶
func (s *MemoryStore) JoinSession(sessionID string, spec EndpointSpec) (Session, Endpoint, Lease, error)
func (*MemoryStore) MarkTaskRunning ¶
func (s *MemoryStore) MarkTaskRunning(sessionID, taskID string) (Task, error)
func (*MemoryStore) PeekEventsAfter ¶
func (s *MemoryStore) PeekEventsAfter(sessionID string, cursor EventCursor, limit int) ([]Event, Lease, EventReplayState, error)
PeekEventsAfter validates the endpoint lease and returns visible events without renewing the lease or mutating endpoint cursor state.
func (*MemoryStore) RenameHost ¶
func (s *MemoryStore) RenameHost(hostID, displayName string) (Host, error)
RenameHost sets the operator-controlled display name for one host record.
func (*MemoryStore) RestoreSnapshot ¶
func (s *MemoryStore) RestoreSnapshot(snapshot Snapshot) error
func (*MemoryStore) ResumeTask ¶
func (s *MemoryStore) ResumeTask(sessionID, taskID, checkpointID, idempotencyKey string) (Task, Event, error)
func (*MemoryStore) RevokeSession ¶
func (s *MemoryStore) RevokeSession(sessionID string) (Session, Event, error)
func (*MemoryStore) SetEventHook ¶
func (s *MemoryStore) SetEventHook(hook func(sessionID string, event Event, notifyURL string))
SetEventHook installs a per-appended-event callback. Nil disables it.
func (*MemoryStore) SetSessionNotifyURL ¶
func (s *MemoryStore) SetSessionNotifyURL(sessionID, notifyURL string) (Session, error)
SetSessionNotifyURL updates the event push webhook for a session. An empty URL disables push notifications.
func (*MemoryStore) Snapshot ¶
func (s *MemoryStore) Snapshot() Snapshot
func (*MemoryStore) SubmitTask ¶
func (*MemoryStore) UpsertArtifact ¶
func (s *MemoryStore) UpsertArtifact(sessionID string, ref ArtifactRef) (ArtifactRef, Event, error)
func (*MemoryStore) UpsertHostLocked ¶
func (s *MemoryStore) UpsertHostLocked(session Session, endpoint Endpoint, now time.Time)
UpsertHostLocked records or refreshes the directory entry for a joining target. Callers must hold the store mutex. The operator-set DisplayName is preserved across rejoins; only a fresh record adopts the connector name.
func (*MemoryStore) ValidateLease ¶
func (s *MemoryStore) ValidateLease(sessionID, endpointID, secret string) error
type ProtocolError ¶
type ProtocolError struct {
SchemaVersion string `json:"schema_version"`
Code ErrorCode `json:"code"`
Message string `json:"message"`
Recoverable bool `json:"recoverable"`
RetryAfterMS int `json:"retry_after_ms"`
UserSummary string `json:"user_summary"`
AgentNextAction string `json:"agent_next_action"`
Details map[string]any `json:"details,omitempty"`
}
func InvalidJoinCodeError ¶
func InvalidJoinCodeError() ProtocolError
func (ProtocolError) Error ¶
func (e ProtocolError) Error() string
func (ProtocolError) Is ¶
func (e ProtocolError) Is(target error) bool
type Session ¶
type Session struct {
SchemaVersion string `json:"schema_version"`
ID string `json:"id"`
JoinCode string `json:"join_code"`
Profile string `json:"profile"`
Status SessionStatus `json:"status"`
Reason string `json:"reason"`
Capabilities []string `json:"capabilities"`
JoinPolicy string `json:"join_policy"`
GatewayCandidates []GatewayCandidate `json:"gateway_candidates"`
SelectedGatewayURL string `json:"selected_gateway_url"`
Endpoints []Endpoint `json:"endpoints"`
Tasks []Task `json:"tasks,omitempty"`
Artifacts []ArtifactRef `json:"artifacts,omitempty"`
LastSeq uint64 `json:"last_seq"`
SnapshotSeq uint64 `json:"snapshot_seq"`
AuthorityID string `json:"authority_id"`
Limits Limits `json:"limits"`
ReconnectGraceMS int `json:"reconnect_grace_ms"`
RetryAfterMS int `json:"retry_after_ms"`
NotifyURL string `json:"notify_url,omitempty"`
NotifySecret string `json:"-"`
LatestEvent Event `json:"latest_event,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
ExpiresAt time.Time `json:"expires_at"`
}
func NewSession ¶
func NewSession(spec SessionSpec, now time.Time) (Session, error)
func (Session) DeriveStatus ¶
func (s Session) DeriveStatus() StatusSummary
func (Session) Snapshot ¶
func (s Session) Snapshot() SessionSnapshot
func (Session) WithEndpoint ¶
type SessionSnapshot ¶
type SessionSnapshot struct {
Session Session `json:"session"`
Endpoints []Endpoint `json:"endpoints"`
Tasks []Task `json:"tasks"`
Artifacts []ArtifactRef `json:"artifacts"`
Status StatusSummary `json:"status"`
GatewayCandidates []GatewayCandidate `json:"gateway_candidates"`
SelectedGatewayURL string `json:"selected_gateway_url"`
Limits Limits `json:"limits"`
ReconnectGraceMS int `json:"reconnect_grace_ms"`
RetryAfterMS int `json:"retry_after_ms"`
}
type SessionSpec ¶
type SessionSpec struct {
Profile string `json:"profile"`
Reason string `json:"reason"`
Capabilities []string `json:"capabilities"`
JoinPolicy string `json:"join_policy"`
GatewayCandidates []GatewayCandidate `json:"gateway_candidates"`
SelectedGatewayURL string `json:"selected_gateway_url"`
AuthorityID string `json:"authority_id"`
Limits Limits `json:"limits"`
ReconnectGraceMS int `json:"reconnect_grace_ms"`
RetryAfterMS int `json:"retry_after_ms"`
SnapshotSeq uint64 `json:"snapshot_seq"`
ExpiresAt time.Time `json:"expires_at"`
// NotifyURL receives a POST for every session event (host up/down, task
// lifecycle, artifacts). HTTPS only; empty means no push notifications.
NotifyURL string `json:"notify_url,omitempty"`
}
type SessionStatus ¶
type SessionStatus string
const ( SessionStatusCreated SessionStatus = "created" SessionStatusJoining SessionStatus = "joining" SessionStatusOnline SessionStatus = "online" SessionStatusBusy SessionStatus = "busy" SessionStatusWaiting SessionStatus = "waiting" SessionStatusDegraded SessionStatus = "degraded" SessionStatusReconnecting SessionStatus = "reconnecting" SessionStatusRecovered SessionStatus = "recovered" SessionStatusClosed SessionStatus = "closed" SessionStatusFailed SessionStatus = "failed" SessionStatusRevoked SessionStatus = "revoked" )
type Snapshot ¶
type Snapshot struct {
SchemaVersion string `json:"schema_version"`
Sessions []Session `json:"sessions"`
Events map[string][]Event `json:"events"`
Idempotency []IdempotencyRecord `json:"idempotency,omitempty"`
TaskIdempotency map[string]TaskRecord `json:"task_idempotency,omitempty"`
CancelIdempotency map[string]TaskRecord `json:"cancel_idempotency,omitempty"`
ResultIdempotency map[string]TaskRecord `json:"result_idempotency,omitempty"`
Leases map[string]LeaseRecord `json:"leases,omitempty"`
TerminalAt map[string]time.Time `json:"terminal_at,omitempty"`
Hosts []Host `json:"hosts,omitempty"`
}
type StatusSummary ¶
type StatusSummary struct {
Status DerivedStatus `json:"status"`
UserSummary string `json:"user_summary"`
AgentNextAction string `json:"agent_next_action"`
SelectedGatewayURL string `json:"selected_gateway_url"`
Transport Transport `json:"transport"`
LastSeq uint64 `json:"last_seq"`
SnapshotSeq uint64 `json:"snapshot_seq"`
LatestEvent Event `json:"latest_event,omitempty"`
Recoverable bool `json:"recoverable"`
RetryAfterMS int `json:"retry_after_ms"`
Online bool `json:"online"`
}
type TargetSelector ¶
type TargetSelector struct {
Role EndpointRole `json:"role,omitempty"`
Platform string `json:"platform,omitempty"`
Capabilities []string `json:"capabilities,omitempty"`
}
type Task ¶
type Task struct {
SchemaVersion string `json:"schema_version"`
ID string `json:"id"`
SessionID string `json:"session_id"`
TargetEndpointID string `json:"target_endpoint_id"`
TargetSelector TargetSelector `json:"target_selector"`
Adapter string `json:"adapter"`
Intent string `json:"intent"`
Capabilities []string `json:"capabilities"`
Payload map[string]any `json:"payload,omitempty"`
Limits map[string]any `json:"limits,omitempty"`
AttemptID string `json:"attempt_id"`
IdempotencyKey string `json:"idempotency_key"`
Status TaskStatus `json:"status"`
CreatedAt time.Time `json:"created_at"`
StartedAt *time.Time `json:"started_at,omitempty"`
EndedAt *time.Time `json:"ended_at,omitempty"`
}
func (Task) Transition ¶
type TaskRecord ¶
type TaskSpec ¶
type TaskSpec struct {
TargetEndpointID string `json:"target_endpoint_id"`
TargetSelector TargetSelector `json:"target_selector"`
Adapter string `json:"adapter"`
Intent string `json:"intent"`
Capabilities []string `json:"capabilities"`
Payload map[string]any `json:"payload"`
Limits map[string]any `json:"limits"`
AttemptID string `json:"attempt_id"`
IdempotencyKey string `json:"idempotency_key"`
}
type TaskStatus ¶
type TaskStatus string
const ( TaskStatusQueued TaskStatus = "queued" TaskStatusOffered TaskStatus = "offered" TaskStatusRunning TaskStatus = "running" TaskStatusPaused TaskStatus = "paused" TaskStatusSucceeded TaskStatus = "succeeded" TaskStatusFailed TaskStatus = "failed" TaskStatusCanceled TaskStatus = "canceled" )