service

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 4, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

Package service validates and coordinates standalone SecondBox authority.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ContextWithRequestID 

func ContextWithRequestID(ctx context.Context, requestID string) context.Context

ContextWithRequestID binds one validated transport correlation identifier to service work.

func NewCredentialMaterial 

func NewCredentialMaterial() string

NewCredentialMaterial returns high-entropy plaintext used exactly once.

func NewOpaqueID 

func NewOpaqueID(prefix string) string

NewOpaqueID returns a random, prefix-qualified public identifier.

func SystemClock 

func SystemClock() time.Time

SystemClock returns the current time for production control-plane wiring.

Types

type ActivityStore 

type ActivityStore interface {
	GetSandboxLifecyclePolicy(ctx context.Context, tenantRef, subjectRef, sandboxID string) (contracts.LifecyclePolicy, contracts.RetentionPolicy, error)
	SetSandboxDesiredState(ctx context.Context, input ports.LifecycleIntentInput) (contracts.Operation, error)
	AcquireLease(ctx context.Context, input ports.LeaseInput) (contracts.Lease, error)
	GetLeaseByID(ctx context.Context, tenantRef, subjectRef, leaseID string) (contracts.Lease, error)
	RenewLease(ctx context.Context, input ports.LeaseInput) (contracts.Lease, error)
	ReleaseLease(ctx context.Context, input ports.LeaseInput) (contracts.Lease, error)
	PingGuest(ctx context.Context, input ports.GenerationInput, serviceAccountID string) (contracts.Instance, error)
	ReadSandboxInspection(ctx context.Context, input ports.GenerationInput) (contracts.SandboxInspection, error)
	TouchActivity(ctx context.Context, input ports.ActivityInput) (time.Time, error)
	OpenActivitySession(ctx context.Context, input ports.ActivityInput) (contracts.ActivitySession, error)
	CloseActivitySession(ctx context.Context, input ports.ActivityInput) (contracts.ActivitySession, error)
}

ActivityStore owns lifecycle intent, leases, and useful-activity evidence.

type ArtifactStore 

type ArtifactStore interface {
	StageArtifact(ctx context.Context, input ports.ArtifactPublicationInput) (contracts.Artifact, error)
	PublishArtifact(ctx context.Context, input ports.ArtifactPublicationInput, now time.Time) (contracts.Artifact, error)
	ListArtifacts(ctx context.Context, tenantRef, subjectRef, sandboxID string, limit int, cursor string, now time.Time) (contracts.ArtifactPage, error)
	GetArtifactObject(ctx context.Context, tenantRef, subjectRef, artifactID string, now time.Time) (ports.ArtifactObject, error)
	EndArtifactRetention(ctx context.Context, input ports.ArtifactRetentionInput) error
}

ArtifactStore owns immutable artifact publication and retention.

type ArtifactUpload 

type ArtifactUpload struct {
	Name         string
	MediaType    string
	SHA256       string
	Metadata     map[string]string
	Content      artifactReadSeekCloser
	SizeBytes    int64
	ActualSHA256 string
}

ArtifactUpload is one validated multipart Artifact publication request.

type ControlPlaneConfig 

type ControlPlaneConfig struct {
	Store                 ControlPlaneStore
	PlatformToken         string
	DefaultSubjectQuota   contracts.QuotaLimits
	Now                   func() time.Time
	NewID                 func(string) string
	NewCredentialMaterial func() string
	ArtifactObjectStore   objectstore.Store
	DataPlaneStore        DataPlaneStore
	LiveDataPlane         *runnercontrol.LiveDataPlaneBroker
	DataPlanePollInterval time.Duration
	PortSessionStore      runnercontrol.PortSessionStore
	PublicBaseURL         string
}

ControlPlaneConfig contains explicit authority, quota, time, and identity dependencies.

type ControlPlaneService 

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

ControlPlaneService owns validation, authentication, and transaction inputs.

func NewControlPlaneService 

func NewControlPlaneService(config ControlPlaneConfig) (*ControlPlaneService, error)

NewControlPlaneService constructs the standalone SecondBox coordinator.

func (*ControlPlaneService) AcquireSandboxLease 

func (service *ControlPlaneService) AcquireSandboxLease(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	generation int64,
	idempotencyKey string,
	durationSeconds int64,
	replaceActive ...bool,
) (contracts.Lease, error)

AcquireSandboxLease creates profile-bounded authority for useful activity.

func (*ControlPlaneService) AcquireSandboxTerminalAttachment 

func (service *ControlPlaneService) AcquireSandboxTerminalAttachment(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	sessionID string,
	generation int64,
) (runnercontrol.DataPlaneSession, string, error)

AcquireSandboxTerminalAttachment grants the single WebSocket attachment.

func (*ControlPlaneService) CancelSandboxExecStream 

func (service *ControlPlaneService) CancelSandboxExecStream(
	ctx context.Context,
	principal contracts.Principal,
	sessionID string,
	reason string,
) (bool, error)

func (*ControlPlaneService) CancelSandboxExecStreamAtGeneration 

func (service *ControlPlaneService) CancelSandboxExecStreamAtGeneration(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	sessionID string,
	generation int64,
	idempotencyKey string,
) (runnercontrol.DataPlaneSession, bool, error)

CancelSandboxExecStreamAtGeneration durably replays one key-scoped public cancellation response.

func (*ControlPlaneService) CancelSandboxTerminal 

func (service *ControlPlaneService) CancelSandboxTerminal(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	sessionID string,
	generation int64,
	idempotencyKey string,
) (runnercontrol.DataPlaneSession, bool, error)

CancelSandboxTerminal durably replays one key-scoped public cancellation response.

func (*ControlPlaneService) CloseActivitySession 

func (service *ControlPlaneService) CloseActivitySession(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	generation int64,
	sessionID string,
) (contracts.ActivitySession, error)

CloseActivitySession releases idle suppression for completed useful work.

func (*ControlPlaneService) ClosePortTunnel 

func (service *ControlPlaneService) ClosePortTunnel(
	ctx context.Context,
	tunnel runnercontrol.PortTunnel,
	reason string,
) error

ClosePortTunnel terminates a consumed proxy and its useful-activity record.

func (*ControlPlaneService) CloseSandboxPortSession 

func (service *ControlPlaneService) CloseSandboxPortSession(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	sessionID string,
	idempotencyKey string,
) error

func (*ControlPlaneService) ConsumeDirectDataPlane 

func (service *ControlPlaneService) ConsumeDirectDataPlane(
	ctx context.Context,
	input runnercontrol.DirectDataPlaneConsumption,
) error

func (*ControlPlaneService) ConsumePortTunnel 

func (service *ControlPlaneService) ConsumePortTunnel(
	ctx context.Context,
	endpoint string,
) (runnercontrol.PortTunnel, error)

ConsumePortTunnel atomically spends the signed URL before proxying any bytes.

func (*ControlPlaneService) ConsumePortTunnelToken 

func (service *ControlPlaneService) ConsumePortTunnelToken(
	ctx context.Context,
	sessionID string,
	token string,
) (runnercontrol.PortTunnel, error)

ConsumePortTunnelToken spends a fragment-delivered credential for one exact session.

func (*ControlPlaneService) CreateProfile 

func (service *ControlPlaneService) CreateProfile(
	ctx context.Context,
	principal contracts.Principal,
	request contracts.CreateProfileRequest,
) (contracts.Profile, error)

CreateProfile creates one explicit Profile and immutable revision.

func (*ControlPlaneService) CreateProfileIdempotent 

func (service *ControlPlaneService) CreateProfileIdempotent(
	ctx context.Context,
	principal contracts.Principal,
	idempotencyKey string,
	request contracts.CreateProfileRequest,
) (contracts.Profile, bool, error)

CreateProfileIdempotent creates or replays one exact Profile response.

func (*ControlPlaneService) CreateRunnerPool 

func (service *ControlPlaneService) CreateRunnerPool(
	ctx context.Context,
	principal contracts.Principal,
	request contracts.CreateRunnerPoolRequest,
) (contracts.RunnerPool, error)

CreateRunnerPool creates one explicit operator-owned scheduling boundary.

func (*ControlPlaneService) CreateSandbox 

func (service *ControlPlaneService) CreateSandbox(
	ctx context.Context,
	principal contracts.Principal,
	idempotencyKey string,
	request contracts.CreateSandboxRequest,
) (contracts.Sandbox, bool, error)

CreateSandbox transactionally resolves authorization, compatibility, quota, and idempotency.

func (*ControlPlaneService) CreateSandboxDirectory 

func (service *ControlPlaneService) CreateSandboxDirectory(
	ctx context.Context, principal contracts.Principal, requestID string, sandboxID string,
	generation int64, leaseID string, idempotencyKey string,
	request contracts.CreateDirectoryRequest,
) (bool, error)

func (*ControlPlaneService) CreateSandboxExecStream 

func (service *ControlPlaneService) CreateSandboxExecStream(
	ctx context.Context,
	principal contracts.Principal,
	requestID string,
	sandboxID string,
	generation int64,
	leaseID string,
	idempotencyKey string,
	request contracts.StreamingExecRequest,
) (runnercontrol.DataPlaneSession, bool, error)

func (*ControlPlaneService) CreateSandboxOperation 

func (service *ControlPlaneService) CreateSandboxOperation(
	ctx context.Context,
	principal contracts.Principal,
	idempotencyKey string,
	request contracts.CreateSandboxRequest,
) (contracts.Operation, bool, error)

CreateSandboxOperation creates durable Sandbox intent and returns its observable operation.

func (*ControlPlaneService) CreateSandboxPortSession 

func (service *ControlPlaneService) CreateSandboxPortSession(
	ctx context.Context,
	principal contracts.Principal,
	requestID string,
	sandboxID string,
	generation int64,
	leaseID string,
	idempotencyKey string,
	transport string,
	request contracts.CreatePortSessionRequest,
) (contracts.PortSession, bool, error)

CreateSandboxPortSession admits one PortSession on the transport the caller's authority grants. Admission itself is identical for both transports: the same transactional binding of tenant, subject, pinned ProfileRevision, Lease, assignment fence, generation, named port, protocol, duration, and limits.

func (*ControlPlaneService) CreateSandboxSnapshot 

func (service *ControlPlaneService) CreateSandboxSnapshot(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	idempotencyKey string,
	expectedRevision int64,
	request contracts.CreateSnapshotRequest,
) (contracts.Operation, bool, error)

CreateSandboxSnapshot admits an asynchronous runner-local clone.

func (*ControlPlaneService) CreateSandboxTerminal 

func (service *ControlPlaneService) CreateSandboxTerminal(
	ctx context.Context,
	principal contracts.Principal,
	requestID string,
	sandboxID string,
	generation int64,
	leaseID string,
	idempotencyKey string,
	request contracts.CreateTerminalRequest,
) (runnercontrol.DataPlaneSession, bool, error)

CreateSandboxTerminal admits one leased PTY against the pinned Profile.

func (*ControlPlaneService) DataPlanePollInterval 

func (service *ControlPlaneService) DataPlanePollInterval() time.Duration

func (*ControlPlaneService) DeleteArtifact 

func (service *ControlPlaneService) DeleteArtifact(
	ctx context.Context,
	principal contracts.Principal,
	artifactID string,
	idempotencyKey string,
) error

DeleteArtifact ends retention idempotently and leaves provider deletion to garbage collection.

func (*ControlPlaneService) DeleteSandbox 

func (service *ControlPlaneService) DeleteSandbox(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	idempotencyKey string,
	expectedRevision int64,
) (contracts.Operation, error)

DeleteSandbox makes deletion dominate future lifecycle and activity admission.

func (*ControlPlaneService) DeleteSnapshot 

func (service *ControlPlaneService) DeleteSnapshot(
	ctx context.Context,
	principal contracts.Principal,
	snapshotID string,
	idempotencyKey string,
) (contracts.Operation, bool, error)

DeleteSnapshot admits an asynchronous runner-local deletion.

func (*ControlPlaneService) DetachSandboxTerminalAttachment 

func (service *ControlPlaneService) DetachSandboxTerminalAttachment(
	ctx context.Context,
	principal contracts.Principal,
	sessionID string,
	attachmentID string,
) (bool, error)

func (*ControlPlaneService) DisableProfile 

func (service *ControlPlaneService) DisableProfile(
	ctx context.Context,
	principal contracts.Principal,
	name string,
) (contracts.Profile, error)

DisableProfile blocks future creation without rewriting pinned Sandboxes.

func (*ControlPlaneService) DisableProfileAtRevisionIdempotent 

func (service *ControlPlaneService) DisableProfileAtRevisionIdempotent(
	ctx context.Context,
	principal contracts.Principal,
	name string,
	idempotencyKey string,
	expectedRevision int64,
) (contracts.Profile, bool, error)

DisableProfileAtRevisionIdempotent disables or replays one exact fenced Profile response.

func (*ControlPlaneService) DownloadArtifact 

func (service *ControlPlaneService) DownloadArtifact(
	ctx context.Context,
	principal contracts.Principal,
	artifactID string,
) (io.ReadCloser, contracts.Artifact, error)

DownloadArtifact returns verified immutable bytes and metadata.

func (*ControlPlaneService) ExecuteSandboxCommand 

func (service *ControlPlaneService) ExecuteSandboxCommand(
	ctx context.Context,
	principal contracts.Principal,
	requestID string,
	sandboxID string,
	generation int64,
	leaseID string,
	idempotencyKey string,
	request contracts.BufferedExecRequest,
) (any, bool, error)

func (*ControlPlaneService) GetArtifact 

func (service *ControlPlaneService) GetArtifact(
	ctx context.Context,
	principal contracts.Principal,
	artifactID string,
) (contracts.Artifact, error)

GetArtifact returns retained metadata without exposing private provider identity.

func (*ControlPlaneService) GetDeploymentTiming 

func (service *ControlPlaneService) GetDeploymentTiming(
	ctx context.Context,
	principal contracts.Principal,
	windowSeconds int64,
) (contracts.DeploymentTimingSummary, error)

GetDeploymentTiming returns a bounded current-deployment timing projection.

func (*ControlPlaneService) GetOperation 

func (service *ControlPlaneService) GetOperation(
	ctx context.Context,
	principal contracts.Principal,
	operationID string,
) (contracts.Operation, error)

GetOperation returns one durable mutation observation inside the authenticated Project.

func (*ControlPlaneService) GetOperationTiming 

func (service *ControlPlaneService) GetOperationTiming(
	ctx context.Context,
	principal contracts.Principal,
	operationID string,
) (contracts.OperationTiming, error)

GetOperationTiming returns queue, execution, and boot-stage evidence for one Operation.

func (*ControlPlaneService) GetProfile 

func (service *ControlPlaneService) GetProfile(
	ctx context.Context,
	principal contracts.Principal,
	name string,
) (contracts.Profile, error)

GetProfile returns a Profile head and its current immutable revision.

func (*ControlPlaneService) GetRunner 

func (service *ControlPlaneService) GetRunner(
	ctx context.Context,
	principal contracts.Principal,
	runnerID string,
) (contracts.Runner, error)

GetRunner returns one enrolled execution identity and current capacity evidence.

func (*ControlPlaneService) GetRunnerPool 

func (service *ControlPlaneService) GetRunnerPool(
	ctx context.Context,
	principal contracts.Principal,
	name string,
) (contracts.RunnerPool, error)

GetRunnerPool returns one administrative placement boundary.

func (*ControlPlaneService) GetSandbox 

func (service *ControlPlaneService) GetSandbox(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
) (contracts.Sandbox, error)

GetSandbox enforces non-enumerating Project isolation.

func (*ControlPlaneService) GetSandboxExecStream 

func (service *ControlPlaneService) GetSandboxExecStream(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	sessionID string,
	generation int64,
) (runnercontrol.DataPlaneSession, error)

func (*ControlPlaneService) GetSandboxLease 

func (service *ControlPlaneService) GetSandboxLease(
	ctx context.Context,
	principal contracts.Principal,
	leaseID string,
) (contracts.Lease, error)

GetSandboxLease returns one Lease inside the authenticated Project.

func (*ControlPlaneService) GetSandboxPortSession 

func (service *ControlPlaneService) GetSandboxPortSession(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	sessionID string,
	transport string,
) (contracts.PortSession, error)

func (*ControlPlaneService) GetSandboxTerminal 

func (service *ControlPlaneService) GetSandboxTerminal(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	sessionID string,
	generation int64,
) (runnercontrol.DataPlaneSession, error)

GetSandboxTerminal resolves one project-owned, generation-bound Terminal.

func (*ControlPlaneService) GetSandboxTiming 

func (service *ControlPlaneService) GetSandboxTiming(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	limit int,
) (contracts.SandboxTiming, error)

GetSandboxTiming returns bounded timing evidence owned by one caller-visible Sandbox.

func (*ControlPlaneService) GetSnapshot 

func (service *ControlPlaneService) GetSnapshot(
	ctx context.Context,
	principal contracts.Principal,
	snapshotID string,
) (contracts.Snapshot, error)

GetSnapshot returns retained immutable disk-state metadata without provider authority.

func (*ControlPlaneService) GetSubjectUsage 

func (service *ControlPlaneService) GetSubjectUsage(
	ctx context.Context,
	principal contracts.Principal,
) (contracts.SubjectUsage, error)

GetSubjectUsage returns aggregate quota reservations for the asserted subject.

func (*ControlPlaneService) InspectSandbox 

func (service *ControlPlaneService) InspectSandbox(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	generation int64,
) (contracts.SandboxInspection, error)

InspectSandbox returns current persisted guest and session evidence for one generation.

func (*ControlPlaneService) ListProfiles 

func (service *ControlPlaneService) ListProfiles(
	ctx context.Context,
	principal contracts.Principal,
	limit int,
	cursor string,
) (contracts.ProfilePage, error)

ListProfiles returns a bounded stable Profile page.

func (*ControlPlaneService) ListRunnerPools 

func (service *ControlPlaneService) ListRunnerPools(
	ctx context.Context,
	principal contracts.Principal,
	limit int,
	cursor string,
) (contracts.RunnerPoolPage, error)

ListRunnerPools returns a bounded administrative RunnerPool page.

func (*ControlPlaneService) ListRunners 

func (service *ControlPlaneService) ListRunners(
	ctx context.Context,
	principal contracts.Principal,
	poolName string,
	limit int,
	cursor string,
) (contracts.RunnerPage, error)

ListRunners returns a bounded administrative Runner page filtered by exact pool.

func (*ControlPlaneService) ListSandboxArtifacts 

func (service *ControlPlaneService) ListSandboxArtifacts(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	limit int,
	cursor string,
) (contracts.ArtifactPage, error)

ListSandboxArtifacts returns one retained Artifact page inside the authenticated Project.

func (*ControlPlaneService) ListSandboxDirectory 

func (service *ControlPlaneService) ListSandboxDirectory(
	ctx context.Context, principal contracts.Principal, requestID string, sandboxID string,
	generation int64, leaseID string, path string,
) (contracts.DirectoryListing, error)

func (*ControlPlaneService) ListSandboxSnapshots 

func (service *ControlPlaneService) ListSandboxSnapshots(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	limit int,
	cursor string,
) (contracts.SnapshotPage, error)

ListSandboxSnapshots returns one retained Snapshot page inside the authenticated Project.

func (*ControlPlaneService) ListSandboxes 

func (service *ControlPlaneService) ListSandboxes(
	ctx context.Context,
	principal contracts.Principal,
	limit int,
	cursor string,
	metadata map[string]string,
) (contracts.SandboxPage, error)

ListSandboxes returns only the authenticated Project projection.

func (*ControlPlaneService) Metrics 

func (service *ControlPlaneService) Metrics(ctx context.Context) (contracts.MetricsSnapshot, error)

Metrics returns only fixed-cardinality state counts.

func (*ControlPlaneService) MutateSandbox 

func (service *ControlPlaneService) MutateSandbox(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	kind string,
	idempotencyKey string,
	expectedRevision int64,
	metadata map[string]string,
) (contracts.Operation, bool, error)

MutateSandbox exposes one exact HTTP lifecycle action with replay evidence.

func (*ControlPlaneService) OpenActivitySession 

func (service *ControlPlaneService) OpenActivitySession(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	generation int64,
	leaseID string,
	kind string,
) (contracts.ActivitySession, error)

OpenActivitySession admits generation-bound exec, file, PTY, or port work.

func (*ControlPlaneService) OpenPortTunnel 

func (service *ControlPlaneService) OpenPortTunnel(
	ctx context.Context,
	tunnel runnercontrol.PortTunnel,
) (*SandboxPortStream, error)

func (*ControlPlaneService) OpenSandboxExecStream 

func (service *ControlPlaneService) OpenSandboxExecStream(
	ctx context.Context,
	session runnercontrol.DataPlaneSession,
) (*SandboxExecStream, error)

func (*ControlPlaneService) OpenSandboxTerminalStream 

func (service *ControlPlaneService) OpenSandboxTerminalStream(
	ctx context.Context,
	session runnercontrol.DataPlaneSession,
	attachmentID string,
	afterSequence int64,
) (*SandboxTerminalStream, error)

func (*ControlPlaneService) PingSandbox 

func (service *ControlPlaneService) PingSandbox(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	generation int64,
) (contracts.PingResult, error)

PingSandbox returns persisted health evidence without changing activity or liveness.

func (*ControlPlaneService) ReadSandboxFile 

func (service *ControlPlaneService) ReadSandboxFile(
	ctx context.Context, principal contracts.Principal, requestID string, sandboxID string,
	generation int64, leaseID string, path string,
) ([]byte, string, error)

func (*ControlPlaneService) Ready 

func (service *ControlPlaneService) Ready(ctx context.Context) error

Ready proves the database authority is reachable.

func (*ControlPlaneService) ReleaseSandboxLease 

func (service *ControlPlaneService) ReleaseSandboxLease(
	ctx context.Context,
	principal contracts.Principal,
	leaseID string,
	idempotencyKey string,
) (contracts.Lease, error)

ReleaseSandboxLease ends bounded authority without deleting the Sandbox.

func (*ControlPlaneService) RelocateSandbox 

func (service *ControlPlaneService) RelocateSandbox(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	idempotencyKey string,
	expectedRevision int64,
	request contracts.RelocateSandboxRequest,
) (contracts.Operation, bool, error)

RelocateSandbox starts one operator-initiated stopped Workspace transfer.

func (*ControlPlaneService) RemoveSandboxPath 

func (service *ControlPlaneService) RemoveSandboxPath(
	ctx context.Context, principal contracts.Principal, requestID string, sandboxID string,
	generation int64, leaseID string, idempotencyKey string,
	request contracts.RemovePathRequest,
) (bool, error)

func (*ControlPlaneService) RenewSandboxLease 

func (service *ControlPlaneService) RenewSandboxLease(
	ctx context.Context,
	principal contracts.Principal,
	leaseID string,
	idempotencyKey string,
	durationSeconds int64,
) (contracts.Lease, error)

RenewSandboxLease renews only current, active generation authority.

func (*ControlPlaneService) ReportGuestLiveness 

func (service *ControlPlaneService) ReportGuestLiveness(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	generation int64,
	liveness string,
) (contracts.Instance, error)

ReportGuestLiveness persists runner-reported guest health without renewing useful activity.

func (*ControlPlaneService) RestoreSandboxSnapshot 

func (service *ControlPlaneService) RestoreSandboxSnapshot(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	idempotencyKey string,
	expectedRevision int64,
	request contracts.RestoreSnapshotRequest,
) (contracts.Operation, bool, error)

RestoreSandboxSnapshot admits a stopped-only in-place restore.

func (*ControlPlaneService) ReviseProfile 

func (service *ControlPlaneService) ReviseProfile(
	ctx context.Context,
	principal contracts.Principal,
	name string,
	request contracts.ReviseProfileRequest,
) (contracts.Profile, error)

ReviseProfile appends immutable policy without mutating pinned Sandboxes.

func (*ControlPlaneService) ReviseProfileAtRevisionIdempotent 

func (service *ControlPlaneService) ReviseProfileAtRevisionIdempotent(
	ctx context.Context,
	principal contracts.Principal,
	name string,
	idempotencyKey string,
	request contracts.ReviseProfileRequest,
	expectedRevision int64,
) (contracts.Profile, bool, error)

ReviseProfileAtRevisionIdempotent appends or replays one exact immutable Profile revision.

func (*ControlPlaneService) SandboxExecStreamEndpoint 

func (service *ControlPlaneService) SandboxExecStreamEndpoint(
	sandboxID string,
	sessionID string,
) (string, error)

func (*ControlPlaneService) SandboxExecStreamOutcome 

func (service *ControlPlaneService) SandboxExecStreamOutcome(
	ctx context.Context,
	principal contracts.Principal,
	sessionID string,
) (any, error)

func (*ControlPlaneService) SandboxFileExists 

func (service *ControlPlaneService) SandboxFileExists(
	ctx context.Context, principal contracts.Principal, requestID string, sandboxID string,
	generation int64, leaseID string, path string,
) (contracts.FileExistsResult, error)

func (*ControlPlaneService) SandboxTerminalEndpoint 

func (service *ControlPlaneService) SandboxTerminalEndpoint(
	sandboxID string,
	sessionID string,
) (string, error)

func (*ControlPlaneService) SandboxTerminalOutcome 

func (service *ControlPlaneService) SandboxTerminalOutcome(
	ctx context.Context,
	principal contracts.Principal,
	sessionID string,
) (any, error)

func (*ControlPlaneService) StartSandbox 

func (service *ControlPlaneService) StartSandbox(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	idempotencyKey string,
	expectedRevision int64,
) (contracts.Operation, error)

StartSandbox records running intent for asynchronous reconciliation.

func (*ControlPlaneService) StatSandboxFile 

func (service *ControlPlaneService) StatSandboxFile(
	ctx context.Context, principal contracts.Principal, requestID string, sandboxID string,
	generation int64, leaseID string, path string,
) (contracts.FileStat, error)

func (*ControlPlaneService) StopSandbox 

func (service *ControlPlaneService) StopSandbox(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	idempotencyKey string,
	expectedRevision int64,
) (contracts.Operation, error)

StopSandbox converges the Sandbox to stopped after durable local generation advance.

func (*ControlPlaneService) TouchSandbox 

func (service *ControlPlaneService) TouchSandbox(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	generation int64,
	leaseID string,
	idempotencyKey string,
) (contracts.TouchResult, error)

TouchSandbox records only explicit useful client activity.

func (*ControlPlaneService) UpdateRunnerPool 

func (service *ControlPlaneService) UpdateRunnerPool(
	ctx context.Context,
	principal contracts.Principal,
	name string,
	request contracts.UpdateRunnerPoolRequest,
	expectedRevision int64,
) (contracts.RunnerPool, error)

UpdateRunnerPool changes explicit placement policy under optimistic concurrency.

func (*ControlPlaneService) UpdateSandboxMetadata 

func (service *ControlPlaneService) UpdateSandboxMetadata(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	expectedRevision int64,
	request contracts.UpdateSandboxMetadataRequest,
) (contracts.Sandbox, error)

UpdateSandboxMetadata replaces bounded consumer correlation metadata without changing lifecycle, workspace, generation, placement, or profile authority.

func (*ControlPlaneService) UploadSandboxArtifact 

func (service *ControlPlaneService) UploadSandboxArtifact(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	generation int64,
	leaseID string,
	idempotencyKey string,
	upload ArtifactUpload,
) (contracts.Artifact, error)

UploadSandboxArtifact publishes immutable bytes only after durable admission and provider verification.

func (*ControlPlaneService) WaitSandbox 

func (service *ControlPlaneService) WaitSandbox(
	ctx context.Context,
	principal contracts.Principal,
	sandboxID string,
	request contracts.WaitSandboxRequest,
) (contracts.Sandbox, error)

WaitSandbox blocks until the persisted Sandbox reaches one requested state.

func (*ControlPlaneService) WriteSandboxFile 

func (service *ControlPlaneService) WriteSandboxFile(
	ctx context.Context, principal contracts.Principal, requestID string, sandboxID string,
	generation int64, leaseID string, idempotencyKey string,
	path string, content []byte, sha256Hex string,
) (contracts.FileWriteResult, bool, error)

type ControlPlaneStore 

type ControlPlaneStore interface {
	HealthStore
	ProfileStore
	RunnerAdminStore
	SandboxStore
	ActivityStore
	SnapshotStore
	ArtifactStore
	ObservabilityStore
}

ControlPlaneStore is the service's composite consumer-side store contract.

type DataPlaneStore 

type DataPlaneStore interface {
	AdmitDataPlane(context.Context, runnercontrol.DataPlaneAdmission) (runnercontrol.DataPlaneSession, bool, error)
	GetDataPlaneSession(context.Context, string, string, string) (runnercontrol.DataPlaneSession, error)
	StartDataPlaneSession(context.Context, string, string, string, time.Time) (runnercontrol.DataPlaneSession, error)
	ExpireDataPlaneSession(context.Context, string, string, string, time.Time) (runnercontrol.DataPlaneSession, error)
	CompleteDataPlaneSession(context.Context, runnercontrol.DataPlaneCompletion) (runnercontrol.DataPlaneSession, error)
	ConsumeDirectDataPlaneSession(context.Context, runnercontrol.DirectDataPlaneConsumption) error
	CancelDataPlaneSession(context.Context, string, string, string, string, time.Time) (bool, error)
	CancelPublicDataPlaneSession(context.Context, runnercontrol.PublicDataPlaneCancellation) (runnercontrol.DataPlaneSession, bool, error)
}

DataPlaneStore owns durable admission, lifecycle, and terminal projections.

type HealthStore 

type HealthStore interface {
	Ping(ctx context.Context) error
}

HealthStore exposes only readiness authority.

type ObservabilityStore 

type ObservabilityStore interface {
	AppendAuditEvent(ctx context.Context, event contracts.AuditEvent) error
	ReadMetricsSnapshot(ctx context.Context) (contracts.MetricsSnapshot, error)
	ReadSandboxTiming(ctx context.Context, tenantRef, subjectRef, sandboxID string, limit int) (contracts.SandboxTiming, error)
	ReadOperationTiming(ctx context.Context, tenantRef, subjectRef, operationID string) (contracts.OperationTiming, error)
	ReadDeploymentTiming(ctx context.Context, since, until time.Time) (contracts.DeploymentTimingSummary, error)
}

ObservabilityStore owns audit and metrics reads/writes.

type ProfileStore 

type ProfileStore interface {
	CreateProfile(ctx context.Context, profile contracts.Profile, idempotency ports.AdminIdempotencyInput) (contracts.Profile, ports.AdminIdempotencyResult, error)
	ReviseProfile(ctx context.Context, name string, revision contracts.ProfileRevision, expectedRevision int64, now time.Time, idempotency ports.AdminIdempotencyInput) (contracts.Profile, ports.AdminIdempotencyResult, error)
	DisableProfile(ctx context.Context, name string, expectedRevision int64, now time.Time, idempotency ports.AdminIdempotencyInput) (contracts.Profile, ports.AdminIdempotencyResult, error)
	GetProfile(ctx context.Context, name string) (contracts.Profile, error)
	ListProfiles(ctx context.Context, limit int, cursor string) (contracts.ProfilePage, error)
}

ProfileStore owns immutable Profile revisions.

type RunnerAdminStore 

type RunnerAdminStore interface {
	CreateRunnerPool(ctx context.Context, pool contracts.RunnerPool) (contracts.RunnerPool, error)
	UpdateRunnerPool(ctx context.Context, name string, request contracts.UpdateRunnerPoolRequest, expectedRevision int64, now time.Time) (contracts.RunnerPool, error)
	GetRunnerPool(ctx context.Context, name string) (contracts.RunnerPool, error)
	ListRunnerPools(ctx context.Context, limit int, cursor string) (contracts.RunnerPoolPage, error)
	GetRunner(ctx context.Context, runnerID string) (contracts.Runner, error)
	ListRunners(ctx context.Context, poolName string, limit int, cursor string) (contracts.RunnerPage, error)
}

RunnerAdminStore owns runner-pool and runner administration.

type SandboxExecStream 

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

SandboxExecStream forwards one public streaming Exec attachment without retaining payload bytes outside the bounded live transport.

func (*SandboxExecStream) Cancel 

func (stream *SandboxExecStream) Cancel(ctx context.Context, reason string) error

func (*SandboxExecStream) Close 

func (stream *SandboxExecStream) Close() error

func (*SandboxExecStream) Receive 

func (stream *SandboxExecStream) Receive(
	ctx context.Context,
) (runnercontrol.ExecServerFrame, runnercontrol.DataPlaneSession, error)

func (*SandboxExecStream) Send 

func (stream *SandboxExecStream) Send(
	ctx context.Context,
	frame runnercontrol.ExecClientFrame,
) error

type SandboxPortStream 

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

SandboxPortStream forwards one proxied PortSession over the authenticated Runner connection without retaining payload bytes in PostgreSQL.

func (*SandboxPortStream) Acknowledge 

func (stream *SandboxPortStream) Acknowledge(
	ctx context.Context,
	event runnercontrol.PortTunnelEvent,
) error

func (*SandboxPortStream) Close 

func (stream *SandboxPortStream) Close() error

func (*SandboxPortStream) Receive 

func (stream *SandboxPortStream) Receive(
	ctx context.Context,
) (runnercontrol.PortTunnelEvent, error)

func (*SandboxPortStream) Send 

func (stream *SandboxPortStream) Send(ctx context.Context, payload []byte) error

type SandboxStore 

type SandboxStore interface {
	CreateSandbox(ctx context.Context, input ports.CreateSandboxInput) (contracts.Sandbox, contracts.Operation, bool, error)
	UpdateSandboxMetadata(ctx context.Context, input ports.UpdateSandboxMetadataInput) (contracts.Sandbox, error)
	GetSandbox(ctx context.Context, tenantRef, subjectRef, sandboxID string) (contracts.Sandbox, error)
	ListSandboxes(ctx context.Context, tenantRef, subjectRef string, limit int, cursor string, metadata map[string]string) (contracts.SandboxPage, error)
	GetOperation(ctx context.Context, tenantRef, subjectRef, operationID string) (contracts.Operation, error)
	GetSubjectUsage(ctx context.Context, tenantRef, subjectRef string) (contracts.SubjectUsage, error)
	RelocateSandbox(ctx context.Context, input ports.WorkspaceRelocationInput) (contracts.Operation, error)
}

SandboxStore owns public Sandbox and Operation records.

type SandboxTerminalStream 

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

SandboxTerminalStream forwards one exclusive Terminal attachment while the Runner owns bounded replay across attachment transports.

func (*SandboxTerminalStream) Close 

func (stream *SandboxTerminalStream) Close() error

func (*SandboxTerminalStream) Receive 

func (stream *SandboxTerminalStream) Receive(
	ctx context.Context,
) (runnercontrol.TerminalServerFrame, runnercontrol.DataPlaneSession, error)

func (*SandboxTerminalStream) Send 

func (stream *SandboxTerminalStream) Send(
	ctx context.Context,
	frame runnercontrol.TerminalClientFrame,
) error

type SnapshotStore 

type SnapshotStore interface {
	CreateSnapshot(ctx context.Context, input ports.SnapshotCreationInput) (contracts.Operation, error)
	DeleteSnapshot(ctx context.Context, input ports.SnapshotDeletionInput) (contracts.Operation, error)
	RestoreSnapshot(ctx context.Context, input ports.SnapshotRestoreInput) (contracts.Operation, error)
	ListSnapshots(ctx context.Context, tenantRef, subjectRef, sandboxID string, limit int, cursor string, now time.Time) (contracts.SnapshotPage, error)
	GetSnapshot(ctx context.Context, tenantRef, subjectRef, snapshotID string, now time.Time) (contracts.Snapshot, error)
}

SnapshotStore owns durable user snapshots.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.