client

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: MIT Imports: 39 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func RunTunnelService

func RunTunnelService(ctx context.Context, dir string) error

RunTunnelService owns the retained listeners independently of CLI/MCP processes. It must run under a user service manager for host-login and crash recovery.

Types

type Admin

type Admin struct{ URL, Key string }

func (Admin) Account added in v0.5.0

func (c Admin) Account(ctx context.Context) (role, username string, err error)

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

func (c Admin) AuthRole(ctx context.Context) (string, error)

AuthRole preserves authentication and connection errors for explicit commands. Role is used by help, where unavailable credentials simply hide management.

func (Admin) ForceRenameMachine added in v0.2.0

func (c Admin) ForceRenameMachine(ctx context.Context, id, name string) error

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 (Admin) IsSuperuser

func (c Admin) IsSuperuser(ctx context.Context) bool

func (Admin) JSON

func (c Admin) JSON(ctx context.Context, method, path string, params, result any) error

func (Admin) ManageMachine

func (c Admin) ManageMachine(ctx context.Context, id, action string) error

func (Admin) Push

func (c Admin) Push(ctx context.Context, dir string) (update.Deployment, error)

func (Admin) RenameMachine

func (c Admin) RenameMachine(ctx context.Context, id, name string) error

func (Admin) ResolveMachine

func (c Admin) ResolveMachine(ctx context.Context, name string) (model.Node, error)

func (Admin) Role

func (c Admin) Role(ctx context.Context) string

type Client

type Client struct {
	URL   string
	Token string
	// contains filtered or unexported fields
}

Client submits and observes work on nodes without defining a fixed machine role.

func (Client) Activities

func (Client) Call

func (c Client) Call(ctx context.Context, target, method string, params any, result any) error

func (Client) Close

func (c Client) Close() 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 (c Client) DisposePersistentTunnel(ctx context.Context, id string) error

func (Client) Download

func (c Client) Download(ctx context.Context, a model.Artifact, offset int64, w io.Writer) error

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) MCPServer

func (c Client) MCPServer() *mcp.Server

func (Client) PasteClipboard

func (c Client) PasteClipboard(ctx context.Context, spec ClipboardSpec) (clipboard.Result, error)

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) Session

func (c Client) Session(ctx context.Context) (SessionInfo, error)

Session describes this requesting process, not an enrolled fleet machine.

func (Client) StartForward

func (c Client) StartForward(ctx context.Context, spec ForwardSpec) (*Forward, error)

func (Client) StartPersistentTunnel

func (c Client) StartPersistentTunnel(ctx context.Context, spec PersistentTunnelSpec) (PersistentTunnelInfo, error)

func (Client) StopForward

func (c Client) StopForward(id string) error

func (Client) TestConnection

func (c Client) TestConnection(ctx context.Context, spec ConnectionTestSpec) (model.ConnectionTestResult, error)

func (Client) Tunnel

func (c Client) Tunnel(ctx context.Context, target, address string) (net.Conn, error)

func (Client) Wait

func (c Client) Wait(ctx context.Context, target, id string) (model.Task, error)

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) Wake added in v0.5.0

func (c Client) Wake(ctx context.Context, spec WakeSpec) (model.WakeResult, error)

func (Client) WithLifetime

func (c Client) WithLifetime(ctx context.Context) Client

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 ClipboardSpec struct {
	Node    string `json:"node"`
	Reverse bool   `json:"reverse,omitempty"`
	Dir     string `json:"dir,omitempty"`
}

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) Close

func (f *Forward) Close()

func (*Forward) Done

func (f *Forward) Done() <-chan struct{}

func (*Forward) Info

func (f *Forward) Info() ForwardInfo

type ForwardInfo

type ForwardInfo struct {
	ID        string `json:"id"`
	Node      string `json:"node"`
	Address   string `json:"address"`
	Listen    string `json:"listen"`
	Reverse   bool   `json:"reverse,omitempty"`
	Active    int    `json:"activeConnections"`
	LastError string `json:"lastError,omitempty"`
}

type ForwardSpec

type ForwardSpec struct {
	Node    string `json:"node"`
	Address string `json:"address"`
	Listen  string `json:"listen,omitempty"`
	Reverse bool   `json:"reverse,omitempty"`
}

type PersistentTunnelInfo

type PersistentTunnelInfo struct {
	PersistentTunnelSpec
	NodeID    string    `json:"nodeId"`
	Created   time.Time `json:"created"`
	Expires   time.Time `json:"expires,omitempty"`
	State     string    `json:"state,omitempty"`
	Active    int       `json:"activeConnections"`
	LastError string    `json:"lastError,omitempty"`
}

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
}

type WakeSpec added in v0.5.0

type WakeSpec struct {
	Node string `json:"node"`
	From string `json:"from,omitempty"`
}

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"`
}

type WorkflowReconciliation added in v0.4.0

type WorkflowReconciliation struct {
	Parent   model.TaskSummary     `json:"parent"`
	Steps    []WorkflowObservation `json:"steps"`
	Complete bool                  `json:"complete"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL