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 ¶
- func RunTunnelService(ctx context.Context, dir string) error
- 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) 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) ManageMachine(ctx context.Context, id, action string) error
- func (c Admin) Push(ctx context.Context, dir string) (update.Deployment, 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
- type Client
- func (c Client) Activities(ctx context.Context, query model.PoolActivityQuery) (model.PoolActivitySnapshot, 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) PasteClipboard(ctx context.Context, spec ClipboardSpec) (clipboard.Result, error)
- func (c Client) PersistentTunnels(ctx context.Context) ([]PersistentTunnelInfo, error)
- 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) 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 PersistentTunnelInfo
- type PersistentTunnelSpec
- type SessionInfo
- type StandaloneConfig
- type UploadSpec
- type WakeSpec
- type WorkflowObservation
- type WorkflowReconciliation
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Admin ¶
type Admin struct{ URL, Key string }
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) 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) ManageMachine ¶
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.
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) 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) 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) 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) 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.
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 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
- client.go
- clipboard.go
- connectiontest.go
- delegation.go
- enrollment.go
- forward.go
- instruction.go
- lifecycle.go
- listener.go
- logs.go
- machines.go
- mcp.go
- persistent.go
- refused_unix.go
- runbook_rename.go
- runbooks.go
- secrets.go
- session.go
- standalone.go
- tunnel_service.go
- upload.go
- wake.go
- workflow.go