Documentation
¶
Overview ¶
Package client implements the orchestrator's CLI/MCP component, routing calls through a local node API or a standalone authenticated client session. Standalone clients are not enrolled fleet machines and expose no execution capabilities.
Index ¶
- Variables
- func RunTunnelService(ctx context.Context, dir string) error
- func SelectProxy(workers []model.ProxyWorker, worker, endpoint string) (model.ProxyWorker, string, error)
- func WithoutTaskSpec(data json.RawMessage) json.RawMessage
- type Admin
- func (c Admin) Account(ctx context.Context) (role, username string, err error)
- func (c Admin) AuthRole(ctx context.Context) (string, error)
- func (c Admin) ConfigureProxy(ctx context.Context, node string, q model.ProxyConfigure) (model.ProxyConfiguration, error)
- func (c Admin) DeleteSecret(ctx context.Context, id, name string) error
- func (c Admin) ForceRenameMachine(ctx context.Context, id, name string) error
- func (c Admin) InspectMachineState(ctx context.Context, id *identity.Identity) (model.MachineState, bool, error)
- func (c Admin) Invitation(ctx context.Context, id string) (enrollment.Invitation, error)
- func (c Admin) Invite(ctx context.Context, q enrollment.Request) (enrollment.Link, error)
- func (c Admin) IsSuperuser(ctx context.Context) bool
- func (c Admin) JSON(ctx context.Context, method, path string, params, result any) error
- func (c Admin) Machines(ctx context.Context, q MachineQuery) (json.RawMessage, error)
- func (c Admin) ManageMachine(ctx context.Context, id, action string) error
- func (c Admin) ProxyConfiguration(ctx context.Context, node string) (model.ProxyConfiguration, error)
- func (c Admin) ProxyWorkers(ctx context.Context) ([]model.ProxyWorker, error)
- func (c Admin) Push(ctx context.Context, dir string) (update.Deployment, error)
- func (c Admin) ReleaseProxyDependency(ctx context.Context, child string) error
- func (c Admin) RenameMachine(ctx context.Context, id, name string) error
- func (c Admin) ResolveMachine(ctx context.Context, name string) (model.Node, error)
- func (c Admin) Role(ctx context.Context) string
- func (c Admin) SecretTarget(ctx context.Context, name string) (string, secrets.RemoteList, error)
- func (c Admin) SetSecret(ctx context.Context, id, name, value string, public []byte) error
- func (c Admin) SupportsGatewayProxy(ctx context.Context) (bool, error)
- func (c Admin) WaitProxyActivation(ctx context.Context, worker, endpoint string, after time.Time, ...) (model.ProxyEndpointStatus, error)
- type ArtifactQuery
- type BrowserViewInfo
- type BrowserViewSpec
- type Client
- func (c Client) Activities(ctx context.Context, query model.PoolActivityQuery) (model.PoolActivitySnapshot, error)
- func (c Client) Artifacts(ctx context.Context, q ArtifactQuery) (model.ArtifactPage, error)
- func (c Client) Call(ctx context.Context, target, method string, params any, result any) error
- func (c Client) Close() error
- func (c Client) Dashboard(ctx context.Context, gateway Admin, query model.PoolActivityQuery) (model.PoolActivitySnapshot, error)
- func (c Client) DashboardFresh(ctx context.Context, gateway Admin, query model.PoolActivityQuery) (model.PoolActivitySnapshot, error)
- func (c Client) DisposePersistentTunnel(ctx context.Context, id string) error
- func (c Client) Download(ctx context.Context, a model.Artifact, offset int64, w io.Writer) error
- func (c Client) FollowLogs(ctx context.Context, target, id string, offset int64, dest io.Writer) error
- func (c Client) Forwards() []ForwardInfo
- func (c Client) MCPServer() *mcp.Server
- func (c Client) Machines(ctx context.Context, q MachineQuery) (json.RawMessage, error)
- func (c Client) PasteClipboard(ctx context.Context, spec ClipboardSpec) (clipboard.Result, error)
- func (c Client) PersistentTunnels(ctx context.Context) ([]PersistentTunnelInfo, error)
- func (c Client) PrepareTaskWait(ctx context.Context, target string)
- func (c Client) ReconcileWorkflow(ctx context.Context, target, id string) (WorkflowReconciliation, error)
- func (c Client) Runbooks(ctx context.Context, q runbooks.Query) (runbooks.Catalog, error)
- func (c Client) Session(ctx context.Context) (SessionInfo, error)
- func (c Client) StartBrowserView(ctx context.Context, spec BrowserViewSpec) (*Forward, BrowserViewInfo, error)
- func (c Client) StartForward(ctx context.Context, spec ForwardSpec) (*Forward, error)
- func (c Client) StartPersistentTunnel(ctx context.Context, spec PersistentTunnelSpec) (PersistentTunnelInfo, error)
- func (c Client) StopForward(id string) error
- func (c Client) TestConnection(ctx context.Context, spec ConnectionTestSpec) (model.ConnectionTestResult, error)
- func (c Client) Tunnel(ctx context.Context, target, address string) (net.Conn, error)
- func (c Client) Upload(ctx context.Context, s UploadSpec) (upload.Result, error)
- func (c Client) UploadStatus(ctx context.Context, node, id string, abort bool) (upload.Result, error)
- func (c Client) Wait(ctx context.Context, target, id string) (model.Task, error)
- func (c Client) Wake(ctx context.Context, spec WakeSpec) (model.WakeResult, error)
- func (c Client) WithLifetime(ctx context.Context) Client
- func (c Client) WithPersistentTunnels(root string, launch func(context.Context, string) error) Client
- func (c Client) WithStandalone(ctx context.Context, cfg StandaloneConfig) Client
- type ClipboardSpec
- type ConnectionTestSpec
- type Forward
- type ForwardInfo
- type ForwardSpec
- type MachineQuery
- type PersistentTunnelInfo
- type PersistentTunnelSpec
- type SessionInfo
- type StandaloneConfig
- type UploadSpec
- type WakeSpec
- type WorkflowObservation
- type WorkflowReconciliation
Constants ¶
This section is empty.
Variables ¶
var ErrProxyUnsupported = errors.New("gateway does not support proxied invitations; upgrade the gateway first")
ErrProxyUnsupported reports a gateway without proxied invitation support.
Functions ¶
func RunTunnelService ¶
RunTunnelService owns the retained listeners independently of CLI/MCP processes. It must run under a user service manager for host-login and crash recovery.
func SelectProxy ¶ added in v0.9.1
func SelectProxy(workers []model.ProxyWorker, worker, endpoint string) (model.ProxyWorker, string, error)
SelectProxy resolves a worker name or stable ID and an optional endpoint for a noninteractive request. It fails clearly when the address is ambiguous; the gateway repeats every check when the invitation is created.
func WithoutTaskSpec ¶ added in v0.10.4
func WithoutTaskSpec(data json.RawMessage) json.RawMessage
WithoutTaskSpec drops a task record's submitted specification, which the caller already holds, so CLI and MCP results do not repeat inline scripts.
Types ¶
type Admin ¶
type Admin struct {
URL, Key string
Route gatewayroute.Route
}
Admin calls gateway management and enrollment APIs. Route selects a direct connection or the profile's explicit gateway proxy.
func (Admin) Account ¶ added in v0.5.0
Account returns the credential's role and the browser username of a management key. Gateways older than the username field return an empty name.
func (Admin) AuthRole ¶
AuthRole preserves authentication and connection errors for explicit commands. Role is used by help, where unavailable credentials simply hide management.
func (Admin) ConfigureProxy ¶ added in v0.9.1
func (c Admin) ConfigureProxy(ctx context.Context, node string, q model.ProxyConfigure) (model.ProxyConfiguration, error)
ConfigureProxy sends one fixed mutation and waits for worker confirmation. Errors may represent uncertain delivery and must never cause automatic replay.
func (Admin) DeleteSecret ¶ added in v0.6.0
func (Admin) ForceRenameMachine ¶ added in v0.2.0
ForceRenameMachine retracts pending invitations for the destination name. Registered identities and redeemed enrollments remain protected.
func (Admin) InspectMachineState ¶
func (c Admin) InspectMachineState(ctx context.Context, id *identity.Identity) (model.MachineState, bool, error)
InspectMachineState reads identity policy without acknowledging it or advertising lifecycle support on behalf of a running node.
func (Admin) Invitation ¶
func (c Admin) Invitation(ctx context.Context, id string) (enrollment.Invitation, error)
Invitation reads the authenticated fleet's registry, including redeemed invitations whose public installation URLs are no longer available.
func (Admin) Invite ¶
func (c Admin) Invite(ctx context.Context, q enrollment.Request) (enrollment.Link, error)
func (Admin) Machines ¶ added in v0.8.2
func (c Admin) Machines(ctx context.Context, q MachineQuery) (json.RawMessage, error)
Machines lists directory metadata without connecting to execution workers.
func (Admin) ManageMachine ¶
func (Admin) ProxyConfiguration ¶ added in v0.9.1
func (c Admin) ProxyConfiguration(ctx context.Context, node string) (model.ProxyConfiguration, error)
ProxyConfiguration inspects native worker interfaces and applied settings.
func (Admin) ProxyWorkers ¶ added in v0.9.1
ProxyWorkers lists this fleet's workers that advertise gateway proxy endpoints, with the gateway's readiness projection. It needs an owner key.
func (Admin) ReleaseProxyDependency ¶ added in v0.9.1
ReleaseProxyDependency abandons waiting for an unregistered child's retirement acknowledgement, allowing explicit disable when no other dependency remains. It never disables the listener itself.
func (Admin) RenameMachine ¶
func (Admin) ResolveMachine ¶
func (Admin) SecretTarget ¶ added in v0.6.0
SecretTarget resolves one explicit fleet machine and checks management access before the CLI reads a credential. It never uses a node's local API or tasks.
func (Admin) SupportsGatewayProxy ¶ added in v0.9.1
SupportsGatewayProxy reads the authenticated feature metadata.
func (Admin) WaitProxyActivation ¶ added in v0.9.1
func (c Admin) WaitProxyActivation(ctx context.Context, worker, endpoint string, after time.Time, interval time.Duration) (model.ProxyEndpointStatus, error)
WaitProxyActivation polls the fleet's proxy readiness until the worker's managed endpoint reports a fresh ready check through its running listener, or until ctx ends. It only observes: it never creates or retries an invitation. The last observed status is returned with an error on timeout.
type ArtifactQuery ¶ added in v0.10.4
type ArtifactQuery struct {
Node string `json:"node"`
Cursor string `json:"cursor,omitempty"`
Limit int `json:"limit,omitempty"`
}
ArtifactQuery selects one newest-first page of a node's visible artifacts.
type BrowserViewInfo ¶ added in v0.8.2
type BrowserViewInfo struct {
ForwardInfo
URL string `json:"url"`
}
type BrowserViewSpec ¶ added in v0.8.2
type BrowserViewSpec struct {
Node string `json:"node"`
Port int `json:"port,omitempty"`
Listen string `json:"listen,omitempty"`
}
BrowserViewSpec exposes an already started worker dashboard on this host. It never launches a browser, retries commands, or changes authentication.
type Client ¶
Client submits and observes work on nodes without defining a fixed machine role.
func (Client) Activities ¶
func (c Client) Activities(ctx context.Context, query model.PoolActivityQuery) (model.PoolActivitySnapshot, error)
func (Client) Artifacts ¶ added in v0.10.4
func (c Client) Artifacts(ctx context.Context, q ArtifactQuery) (model.ArtifactPage, error)
Artifacts returns compact pages. Older workers ignore paging and return the complete list, which is paged here with the same ordering and cursor rules.
func (Client) Dashboard ¶
func (c Client) Dashboard(ctx context.Context, gateway Admin, query model.PoolActivityQuery) (model.PoolActivitySnapshot, error)
Dashboard observes the gateway directly. Peer activity is optional enrichment; an unavailable execution backend does not hide a reachable gateway or directory.
func (Client) DashboardFresh ¶ added in v0.2.0
func (c Client) DashboardFresh(ctx context.Context, gateway Admin, query model.PoolActivityQuery) (model.PoolActivitySnapshot, error)
DashboardFresh bypasses peer observation reuse for an explicit refresh and expires the old cache so the next automatic poll cannot restore old detail.
func (Client) DisposePersistentTunnel ¶
func (Client) FollowLogs ¶
func (c Client) FollowLogs(ctx context.Context, target, id string, offset int64, dest io.Writer) error
FollowLogs resumes from a byte offset and ends at task completion or caller cancellation. Cancelling a log follower never cancels the durable task.
func (Client) Forwards ¶
func (c Client) Forwards() []ForwardInfo
func (Client) Machines ¶ added in v0.8.2
func (c Client) Machines(ctx context.Context, q MachineQuery) (json.RawMessage, error)
Machines uses the selected client backend and applies the same CLI projection. Query options are local and are never sent as new peer or gateway parameters.
func (Client) PasteClipboard ¶
PasteClipboard copies text to the destination clipboard or streams copied files into an existing directory. Reverse reads the remote clipboard instead.
func (Client) PersistentTunnels ¶
func (c Client) PersistentTunnels(ctx context.Context) ([]PersistentTunnelInfo, error)
func (Client) PrepareTaskWait ¶ added in v0.10.2
PrepareTaskWait overlaps setup of the lane used by blocking task reads with a submission in flight. It sends no request and cannot affect acceptance; setup errors are ignored because Wait reports its own failures.
func (Client) ReconcileWorkflow ¶ added in v0.4.0
func (c Client) ReconcileWorkflow(ctx context.Context, target, id string) (WorkflowReconciliation, error)
ReconcileWorkflow reads the persisted plan and each stable child ID using the account owner's authority. It never resubmits a child or restores a grant.
func (Client) Runbooks ¶ added in v0.5.5
Runbooks discovers shared or machine-specific instructions. A source-qualified read never falls back to a different origin after a denied or failed read.
func (Client) Session ¶
func (c Client) Session(ctx context.Context) (SessionInfo, error)
Session describes this requesting process, not an enrolled fleet machine.
func (Client) StartBrowserView ¶ added in v0.8.2
func (c Client) StartBrowserView(ctx context.Context, spec BrowserViewSpec) (*Forward, BrowserViewInfo, error)
StartBrowserView forwards the dashboard, including its same-origin WebSocket proxies. Only loopback listeners are accepted: dashboard access is interactive browser authority, not a read-only observation endpoint.
func (Client) StartForward ¶
func (Client) StartPersistentTunnel ¶
func (c Client) StartPersistentTunnel(ctx context.Context, spec PersistentTunnelSpec) (PersistentTunnelInfo, error)
func (Client) StopForward ¶
func (Client) TestConnection ¶
func (c Client) TestConnection(ctx context.Context, spec ConnectionTestSpec) (model.ConnectionTestResult, error)
func (Client) Upload ¶ added in v0.7.0
Upload owns exactly one attempt. Cancellation retains the worker's durable prefix; only an explicit Resume invocation can open another attempt.
func (Client) UploadStatus ¶ added in v0.7.0
func (Client) Wait ¶
Wait returns when the task is terminal. Current workers answer a blocking tasks.get as soon as the task finishes; older workers ignore waitSeconds and answer at once, so the loop keeps a minimum poll interval for them. On error, it returns the last successfully observed task, if any, without cancelling it.
func (Client) WithLifetime ¶
WithLifetime owns local listeners and streams until Close or cancellation.
func (Client) WithPersistentTunnels ¶
func (c Client) WithPersistentTunnels(root string, launch func(context.Context, string) error) Client
WithPersistentTunnels enables host-owned tunnels without extending this client's lifetime. launch installs/starts a separate user service; no credentials are passed in argv.
func (Client) WithStandalone ¶
func (c Client) WithStandalone(ctx context.Context, cfg StandaloneConfig) Client
WithStandalone configures command-scoped peer routing. AccountRouting uses an authenticated client session without probing the local API. Other callers probe the API first and fall back only on connection refusal, never after authentication, timeout, or uncertain application failures. Close must be called when the CLI or MCP process finishes.
type ClipboardSpec ¶
type ConnectionTestSpec ¶
type ConnectionTestSpec struct {
Node string `json:"node"`
From string `json:"from,omitempty"`
model.ConnectionTestOptions
}
ConnectionTestSpec selects either this orchestrator or a named source worker.
type Forward ¶
type Forward struct {
// contains filtered or unexported fields
}
func (*Forward) Info ¶
func (f *Forward) Info() ForwardInfo
type ForwardInfo ¶
type ForwardSpec ¶
type MachineQuery ¶ added in v0.8.2
type MachineQuery struct {
Node string `json:"node,omitempty"`
Compact bool `json:"compact,omitempty"`
}
MachineQuery filters or projects an already fleet-scoped directory response. Its zero value preserves the full JSON array, including unknown fields.
type PersistentTunnelInfo ¶
type PersistentTunnelSpec ¶
type PersistentTunnelSpec struct {
ForwardSpec
ID string `json:"id"`
TTLSeconds int64 `json:"ttlSeconds,omitempty"`
}
PersistentTunnelSpec describes a retained listener, not a replayable TCP stream.
type SessionInfo ¶
type SessionInfo struct {
Role string `json:"role"`
OwnerID string `json:"ownerId"`
TransportID string `json:"transportId"`
Connections map[string]string `json:"connections"`
Sessions []model.PeerSession `json:"sessions"`
Forwards []ForwardInfo `json:"forwards"`
}
type StandaloneConfig ¶
type StandaloneConfig struct {
Gateway Admin
StateDir string
RelayOnly bool
ICEServers []webrtc.ICEServer
// AccountRouting uses the requesting account identity even with a local node.
AccountRouting bool
// PeerOptions is construction-only and follows in-process client copies.
// Saved tunnel-service configuration retains the default transport settings.
PeerOptions []transport.Options `json:"-"`
}
type UploadSpec ¶ added in v0.7.0
type WorkflowObservation ¶ added in v0.4.0
type WorkflowObservation struct {
Name string `json:"name"`
Target string `json:"target"`
ID string `json:"id"`
Task *model.TaskSummary `json:"task,omitempty"`
Error string `json:"error,omitempty"`
Code string `json:"code,omitempty"`
Outcome string `json:"outcome,omitempty"`
ErrorTruncated bool `json:"errorTruncated,omitempty"`
}
type WorkflowReconciliation ¶ added in v0.4.0
type WorkflowReconciliation struct {
Parent model.TaskSummary `json:"parent"`
Steps []WorkflowObservation `json:"steps"`
Complete bool `json:"complete"`
}
Source Files
¶
- activities.go
- activity.go
- admin.go
- artifacts.go
- browser.go
- client.go
- clipboard.go
- connectiontest.go
- delegation.go
- discovery.go
- enrollment.go
- forward.go
- instruction.go
- lifecycle.go
- listener.go
- logs.go
- machines.go
- mcp.go
- mcp_text.go
- name_hints.go
- persistent.go
- proxy.go
- refused_unix.go
- runbook_rename.go
- runbooks.go
- secrets.go
- session.go
- standalone.go
- tunnel_service.go
- upload.go
- wake.go
- workflow.go