Documentation
¶
Overview ¶
Package hostclient is the Hub-side handle for talking to a Host.
Per Decision #3 of the hub/host refactor, there is no Go interface here and no in-process shortcut. The Hub always speaks HTTP to a Host — over a Unix socket for the local clankd↔clank-host case, and over TCP+TLS for managed remote hosts. Tests stand up a real host.Service behind an httptest.NewServer wrapped in internal/host/mux and connect via NewHTTP, so the wire shape under test matches production exactly.
Index ¶
- type BackendClient
- type HTTP
- func (c *HTTP) Backend(bt agent.BackendType) *BackendClient
- func (c *HTTP) Backends(ctx context.Context) ([]host.BackendInfo, error)
- func (c *HTTP) CancelFlow(ctx context.Context, providerID, flowID string) error
- func (c *HTTP) Close() error
- func (c *HTTP) DeleteAuthCredential(ctx context.Context, providerID string) error
- func (c *HTTP) FlowStatus(ctx context.Context, providerID, flowID string) (agent.DeviceFlowStatus, error)
- func (c *HTTP) ListAuthProviders(ctx context.Context, backend agent.BackendType) ([]agent.ProviderAuthInfo, error)
- func (c *HTTP) ListBranches(ctx context.Context, ref agent.GitRef) ([]host.BranchInfo, error)
- func (c *HTTP) MergeBranch(ctx context.Context, ref agent.GitRef, branch, commitMessage string) (host.MergeResult, error)
- func (c *HTTP) RemoveWorktree(ctx context.Context, ref agent.GitRef, branch string, force bool) error
- func (c *HTTP) ResolveWorktree(ctx context.Context, ref agent.GitRef, branch string) (host.WorktreeInfo, error)
- func (c *HTTP) Session(id string) *SessionClient
- func (c *HTTP) Sessions() *SessionsClient
- func (c *HTTP) StartDeviceFlow(ctx context.Context, providerID string) (agent.DeviceFlowStart, error)
- func (c *HTTP) StartOAuthCodeFlow(ctx context.Context, providerID string) (agent.DeviceFlowStart, error)
- func (c *HTTP) Status(ctx context.Context) (host.HostStatus, error)
- func (c *HTTP) SubmitAPIKey(ctx context.Context, providerID, key string, metadata map[string]string) (agent.DeviceFlowStart, error)
- func (c *HTTP) SubmitAuthCode(ctx context.Context, providerID, flowID, code string) error
- type SessionClient
- type SessionsClient
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BackendClient ¶
type BackendClient struct {
// contains filtered or unexported fields
}
BackendClient is a per-backend-type handle. Obtained via HTTP.Backend(bt).
func (*BackendClient) Agents ¶
Agents lists agents available for this backend in the given repo. The host resolves ref to a workdir internally — paths never cross the wire (§7.3). The three discrete GitRef fields are passed verbatim so the host can reconstruct the struct without canonical-form parsing.
func (*BackendClient) Discover ¶
func (b *BackendClient) Discover(ctx context.Context, seedDir string) ([]agent.SessionSnapshot, error)
Discover lists existing on-disk session snapshots for this backend rooted at seedDir.
type HTTP ¶
type HTTP struct {
// contains filtered or unexported fields
}
HTTP is a Client that talks to a Host over HTTP. The transport is chosen at construction time: a Unix socket for the local clankd ↔ clank-host case, or a TCP+TLS dialer for managed remote hosts.
func NewHTTP ¶
func NewHTTP(baseURL string, transport http.RoundTripper) *HTTP
NewHTTP constructs an HTTP client. baseURL must be a fully-qualified URL like "http://unix" (the host part is ignored when using a Unix socket transport). transport may be nil; in that case http.DefaultTransport is used.
func NewUnixHTTP ¶
NewUnixHTTP constructs an HTTP client that dials the Host on a Unix socket. The base URL is "http://unix"; the actual address is the socket path.
func (*HTTP) Backend ¶
func (c *HTTP) Backend(bt agent.BackendType) *BackendClient
Backend returns a handle scoped to the given backend type. Use it for per-backend catalog and discovery operations.
func (*HTTP) CancelFlow ¶
CancelFlow signals the host to abort an in-progress flow. Idempotent for already-finished flows.
func (*HTTP) Close ¶
Close releases the underlying transport's idle connections. Interface check so wrapping RoundTrippers can delegate.
func (*HTTP) DeleteAuthCredential ¶
DeleteAuthCredential removes the stored credential for providerID (logging the user out) and triggers an OpenCode server restart.
func (*HTTP) FlowStatus ¶
func (c *HTTP) FlowStatus(ctx context.Context, providerID, flowID string) (agent.DeviceFlowStatus, error)
FlowStatus reads the current state of an in-progress flow (device or api-key — the endpoint is flow-type-agnostic). Pure read — safe to call as fast as the caller wants.
func (*HTTP) ListAuthProviders ¶
func (c *HTTP) ListAuthProviders(ctx context.Context, backend agent.BackendType) ([]agent.ProviderAuthInfo, error)
ListAuthProviders returns the providers this host can authenticate plus their current connection state. Wraps GET /auth/providers. backend, if non-empty, filters the result to providers consumed by that agent CLI (opencode | claude-code) — clients use this so the compose flow only surfaces providers relevant to the chosen backend.
func (*HTTP) ListBranches ¶
ListBranches returns branches in the repo identified by ref.
func (*HTTP) MergeBranch ¶
func (c *HTTP) MergeBranch(ctx context.Context, ref agent.GitRef, branch, commitMessage string) (host.MergeResult, error)
MergeBranch merges branch into the repo's default branch.
func (*HTTP) RemoveWorktree ¶
func (c *HTTP) RemoveWorktree(ctx context.Context, ref agent.GitRef, branch string, force bool) error
RemoveWorktree removes the worktree for branch. force forwards to git.
func (*HTTP) ResolveWorktree ¶
func (c *HTTP) ResolveWorktree(ctx context.Context, ref agent.GitRef, branch string) (host.WorktreeInfo, error)
ResolveWorktree creates (or reuses) the worktree for branch and returns its info.
func (*HTTP) Session ¶
func (c *HTTP) Session(id string) *SessionClient
Session returns a handle for the session with the given hub-side id.
func (*HTTP) Sessions ¶
func (c *HTTP) Sessions() *SessionsClient
Sessions returns the collection-scoped session handle.
func (*HTTP) StartDeviceFlow ¶
func (c *HTTP) StartDeviceFlow(ctx context.Context, providerID string) (agent.DeviceFlowStart, error)
StartDeviceFlow kicks off device-flow auth for providerID and returns the user-facing fields (URL, user_code) plus a flow_id for status polls.
func (*HTTP) StartOAuthCodeFlow ¶
func (c *HTTP) StartOAuthCodeFlow(ctx context.Context, providerID string) (agent.DeviceFlowStart, error)
StartOAuthCodeFlow kicks off an oauth-code flow for providerID (Anthropic Claude subscription today). The host spawns `claude setup-token` in a PTY and returns the verification URL the CLI prints, plus a flow_id for the subsequent SubmitAuthCode call.
func (*HTTP) SubmitAPIKey ¶
func (c *HTTP) SubmitAPIKey(ctx context.Context, providerID, key string, metadata map[string]string) (agent.DeviceFlowStart, error)
SubmitAPIKey stores an API key (plus any provider-specific metadata fields like Azure resourceName or Cloudflare accountId) for providerID and returns a flow_id the caller polls via FlowStatus to observe the post-write OpenCode restart. The metadata map may be nil for providers that need only a key.
func (*HTTP) SubmitAuthCode ¶
SubmitAuthCode delivers the user-pasted authorization code to the host. The host writes it to the setup-token CLI's stdin, waits for the long-lived token to appear on stdout, and persists it. Synchronous: returns once the exchange completes (or fails).
type SessionClient ¶
type SessionClient struct {
// contains filtered or unexported fields
}
SessionClient is a per-session handle. Obtained via HTTP.Session(id).
Most per-session operations live on the SessionBackend returned by Sessions().Create — the SessionClient handle is for operations the hub initiates against a session id without holding the backend (currently just Stop).
type SessionsClient ¶
type SessionsClient struct {
// contains filtered or unexported fields
}
SessionsClient is the collection-scoped handle for session operations that don't target a single existing session. Obtained via HTTP.Sessions().
func (*SessionsClient) Create ¶
func (s *SessionsClient) Create(ctx context.Context, req agent.StartRequest) (agent.SessionBackend, string, error)
Create starts a new session on the host. The host generates the session ID. Returns a SessionBackend adapter bound to the new session and the host-resolved server URL (empty string for backends without an HTTP server, e.g. Claude Code).
Source Files