api

Documentation

Overview

Package api defines the JSON request/response types and the NDJSON streaming framing that form the wire contract between the ShinyHub control plane and a worker agent. Both sides import this package so the contract cannot drift.

Index

• type ExitResult
• type Frame
• type FrameKind
• type HeartbeatRequest
• type HeartbeatResponse
• type InventoryItem
• type RegisterRequest
• type RegisterResponse
• type ReplicaResult
• type ReplicaStartRequest
• type SignalRequest
• type StatsResult

Types

type ExitResult

type ExitResult struct {
	Code     int  `json:"code"`
	Signaled bool `json:"signaled"`
}

ExitResult reports how a one-shot process exited. It is populated only by RunOnce; the long-running Wait path reports completion through error alone and does not surface an exit code.

type Frame

type Frame struct {
	Kind  FrameKind `json:"kind"`
	Data  []byte    `json:"data,omitempty"`
	Error string    `json:"error,omitempty"`
}

Frame is one NDJSON line in a streamed response. Exactly one of the payload fields is meaningful per Kind; Data carries log bytes for FrameLog.

type FrameKind

type FrameKind string

FrameKind identifies an NDJSON streaming frame's payload. Used by the replica control API to multiplex log output, stat samples, and the terminal result of a Start/RunOnce over a single streamed response.

const (
	FrameLog    FrameKind = "log"
	FrameStat   FrameKind = "stat"
	FrameResult FrameKind = "result"
	FrameError  FrameKind = "error"
)

type HeartbeatRequest

type HeartbeatRequest struct {
	Version     string `json:"version"`
	RenewCSRPEM string `json:"renew_csr_pem,omitempty"`
	Incarnation int64  `json:"incarnation,omitempty"`
}

HeartbeatRequest carries the worker's current version. The node id is NOT in the body: the control plane derives it from the presented client certificate so a heartbeat cannot impersonate another node. RenewCSRPEM, when non-empty, is a PEM-encoded CSR the worker submits to renew its certificate before the current one expires; the control plane re-signs it and returns the new cert. Incarnation is the generation counter the worker received at registration; the control plane compares it against its own record to detect a stale worker that missed a reap.

type HeartbeatResponse

type HeartbeatResponse struct {
	CertPEM     string `json:"cert_pem,omitempty"`
	CABundle    string `json:"ca_bundle,omitempty"`
	Incarnation int64  `json:"incarnation,omitempty"`
	Fenced      bool   `json:"fenced,omitempty"`
}

HeartbeatResponse carries a renewed certificate when the request included a RenewCSRPEM the control plane re-signed; CertPEM is then non-empty and the agent swaps it in. CABundle carries the control plane's current CA bundle so a rotated trust root reaches the worker; the agent applies it only when it differs from the bundle it already trusts. Incarnation is the control plane's current generation counter for this node; Fenced is true when the heartbeat's incarnation is stale and the worker must stop serving.

type InventoryItem

type InventoryItem struct {
	ContainerID string            `json:"container_id"`
	Labels      map[string]string `json:"labels"`
	Running     bool              `json:"running"`
	URL         string            `json:"url"`
}

InventoryItem is the wire form of a managed container in the agent inventory.

type RegisterRequest

type RegisterRequest struct {
	Token         string `json:"token"`
	Name          string `json:"name"`
	AdvertiseAddr string `json:"advertise_addr"`
	Tier          string `json:"tier"`
	Version       string `json:"version"`
	CSRPEM        string `json:"csr_pem"`
}

RegisterRequest is the join payload a worker presents to POST /api/workers/register. Token is the pre-shared join token (the only unauthenticated field; the rest of the API authenticates by client cert). CSRPEM is the worker's PEM-encoded certificate signing request.

type RegisterResponse

type RegisterResponse struct {
	NodeID      string `json:"node_id"`
	CertPEM     string `json:"cert_pem"`
	CABundle    string `json:"ca_bundle"`
	Incarnation int64  `json:"incarnation,omitempty"`
}

RegisterResponse returns the assigned node id, the signed client certificate, and the CA bundle the worker pins for the control-plane server cert. Incarnation is the generation counter the control plane assigned this registration; the worker echoes it back on every heartbeat so the control plane can fence out a stale incarnation after a restart or reap.

type ReplicaResult

type ReplicaResult struct {
	NodeID      string `json:"node_id"`
	ContainerID string `json:"container_id"`
	URL         string `json:"url"`
}

ReplicaResult identifies a started replica and its reachable URL. ContainerID is the worker-local container id; the control plane wraps it into an opaque "<node_id>/<container_id>" handle.

type ReplicaStartRequest

type ReplicaStartRequest struct {
	Slug             string            `json:"slug"`
	Index            int               `json:"index"`
	Tier             string            `json:"tier"`
	ContentDigest    string            `json:"content_digest"`
	AppVersion       string            `json:"app_version"`
	DeploymentID     int64             `json:"deployment_id"`
	Command          []string          `json:"command"`
	Env              map[string]string `json:"env,omitempty"`
	BindPort         int               `json:"bind_port"`
	SharedMountSlugs []string          `json:"shared_mount_slugs,omitempty"`
	MemoryLimitMB    int               `json:"memory_limit_mb,omitempty"`
	CPUQuotaPercent  int               `json:"cpu_quota_percent,omitempty"`
	// MaxSessions is the per-replica active-connection hard cap the worker enforces
	// in the data plane. 0 means no cap.
	MaxSessions int `json:"max_sessions,omitempty"`
}

ReplicaStartRequest is the control-plane request to start (or run-once) a replica on a worker. The control plane allocates BindPort (the in-container listen port); the worker allocates its own host publish port and returns the reachable tunnel URL in ReplicaResult.

type SignalRequest

type SignalRequest struct {
	Signal int `json:"signal"`
}

SignalRequest asks the worker to deliver a signal to a replica's container.

type StatsResult

type StatsResult struct {
	CPUPercent float64 `json:"cpu_percent"`
	RSSBytes   uint64  `json:"rss_bytes"`
}

StatsResult reports a replica's current resource usage.