client

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Aug 7, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// NoAutostartEnv disables automatic server startup when set to "1".
	NoAutostartEnv = "BOID_NO_AUTOSTART"
)

Variables

View Source
var ErrAttachDetached = errors.New("attach detached")

Functions

func DefaultCLIAddr added in v0.1.0

func DefaultCLIAddr() string

DefaultCLIAddr resolves the "host:port" the container-backend daemon's dedicated CLI TCP listener binds/is published on, and that `boid`'s host-mode orchestration (cmd/host.go, BOID_MODE=container — nose's Option 4 redesign of PR-3, docs/plans/volume-only-daemon.md §論点c) dials once the daemon container is confirmed healthy. cmd/start.go's own buildStartConfig uses this exact same value to bind server.Config.CLIAddr — a single source of truth for the literal so the two ends can never drift apart silently, and build/container/compose.yml publishes the identical port on the host's own loopback interface (`127.0.0.1:8442:8442`).

Fixed at "127.0.0.1:8442" — no BOID_CLI_ADDR override (round-2 codex review Major 2, removed here; a PORT-only override used to be honored, but nothing ever propagated it into build/container/compose.yml's own hardcoded `127.0.0.1:8442:8442` port-publish or into the daemon container's own listener bind, so an operator setting it would have the host CLI poll a port the daemon was never actually reachable on for the full hostModeStartTimeout, then time out). This literal must always match compose.yml's own hardcoded port until a real end-to-end plumbed override (host CLI dial port AND compose's published port AND the container's own bound port, all three, kept in lockstep) is worth the complexity — not needed for this single-user, same-host deployment shape. A genuinely remote daemon (a named `https://` profile, profiles.Resolve) is unaffected — that path has its own, independently configurable port as part of the profile URL.

func DefaultSocketPath

func DefaultSocketPath() string

func EnsureRunning

func EnsureRunning(ctx context.Context) error

EnsureRunning ensures the boid server is running at DefaultSocketPath(), starting it automatically if it is not. Kept for backward compatibility with pre-Phase-3 callers that never had a per-profile socket to name.

func EnsureRunningAt added in v0.0.13

func EnsureRunningAt(ctx context.Context, socketPath string) error

EnsureRunningAt ensures the boid server reachable at socketPath is running. This is the Phase 3 profile-aware entry point (docs/plans/cli-remote-connection.md PR1): root's PersistentPreRunE, once it resolves the invocation's connection profile, passes the profile's socket path here so autostart probes the SAME socket the CLI is about to talk to — not DefaultSocketPath() unconditionally.

Autostart machinery (spawnServer) only knows how to spin up a daemon on the default socket path (it re-execs `boid start`, which reads its own config for the socket path — there is no runtime override), so:

  • socketPath == DefaultSocketPath(): probe → autostart on miss (unchanged)
  • socketPath != DefaultSocketPath(): probe only; on miss, a clear error directing the operator to launch that daemon out-of-band, rather than silently spinning up a fresh default-socket daemon that would not be the one the CLI is about to connect to.

If BOID_NO_AUTOSTART=1, auto-start is skipped and an error is returned when the server is not reachable.

func WithClient added in v0.0.13

func WithClient(ctx context.Context, c *Client) context.Context

WithClient returns a copy of ctx carrying c as the resolved client for this invocation. A nil ctx (cobra's own zero value before Execute()/SetContext ever run — see cmd/root.go's PersistentPreRunE doc comment for why that is the normal case for the leaf command it is called with) is treated as context.Background() instead of panicking: context.WithValue itself panics on a nil parent.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a boid daemon API client. It is transport-agnostic at the call site (Do/GetRaw/... all build requests against baseURL) — NewUnixClient and NewClient's "https" branch are the two constructors that decide what baseURL and httpClient actually mean underneath.

func FromContext added in v0.0.13

func FromContext(ctx context.Context) *Client

FromContext returns the Client injected into ctx by root's PersistentPreRunE. If ctx is nil, or carries no client at all — every call that bypasses cobra's Execute()/PersistentPreRunE lifecycle, which today includes every cmd package test that invokes a runXxx(cmd, args) function directly against a freshly constructed *cobra.Command — this falls back to NewUnixClient(DefaultSocketPath()), this CLI's long- standing (and, until Phase 3, only) default. That fallback is deliberately identical to what profiles.Resolve itself produces when no config.yaml/--profile/BOID_PROFILE/default_profile is set at all (docs/plans/cli-remote-connection.md's "現行互換" contract), so the two paths never diverge for that common case, and this function never needs to return an error.

func FromContextOrNil added in v0.0.13

func FromContextOrNil(ctx context.Context) *Client

FromContextOrNil returns the Client injected into ctx by root's PersistentPreRunE, or nil if none was injected. Unlike FromContext, this does NOT fall back to the unix default — used by shell TAB completion (cmd/completion.go's completeProjectRefs) so a failed profile resolution degrades to "no candidates" instead of silently querying whichever daemon happens to be listening on the local unix socket. Foreground CLI commands keep using FromContext, whose fallback matches the "現行互換" contract profiles.Resolve itself produces when no profile is configured.

func NewClient added in v0.0.13

func NewClient(rawURL, token string) (*Client, error)

NewClient builds a Client from a profile URL (docs/plans/ cli-remote-connection.md "Transport 分岐"): the scheme decides transport.

  • "unix://<path>" — a local UNIX socket, dialed exactly like NewUnixClient(<path>). token is ignored (decision 4: a local socket needs no Bearer auth — connecting to it already implies local user trust).
  • "https://<host>[:port]" — TCP + TLS, with token sent as "Authorization: Bearer <token>" on every request (including same- origin redirects; decision 7 rejects cross-origin ones outright — see sameOriginCheckRedirect).
  • "http://<loopback-host>[:port]" — PR-3 Option 4 host-mode redesign (docs/plans/volume-only-daemon.md §論点c, nose directive 2026-07-25): the `boid` CLI's own host-mode orchestration (cmd/host.go) dials the container-backend daemon's dedicated CLI TCP listener this way — a shared-secret Bearer token (BOID_CLI_TOKEN) instead of TLS, since host mode already owns the daemon container's lifecycle end to end (no cert to verify, no remote network hop to encrypt). Restricted to a loopback hostname (127.0.0.1/::1/localhost) — see newHTTPClient's own doc comment — so this scheme can never be (mis)used to send a Bearer token in cleartext to a genuinely remote host; decision 4's original "plain-HTTP remote daemons are not supported" verdict still holds for anything that isn't loopback.
  • anything else — a hard error.

func NewUnixClient

func NewUnixClient(socketPath string) *Client

func (*Client) AnswerTask

func (c *Client) AnswerTask(taskID, questionID, answer string) error

AnswerTask submits an answer for an awaiting task via POST /api/tasks/{id}/answer.

func (*Client) ApplyAction

func (c *Client) ApplyAction(taskID string, req api.ApplyActionRequest) (*api.ActionApplication, error)

ApplyAction sends an action to POST /api/tasks/{taskID}/actions.

func (*Client) AttachJob

func (c *Client) AttachJob(jobID string, stdin io.Reader, stdout io.Writer) error

AttachJob opens a live interactive attach to jobID over WebSocket (docs/plans/cli-remote-connection.md Phase 3 PR3: "WebSocket attach 一本化") and blocks until the job's process exits (the server sends an "exit" frame, or the socket closes normally) or the caller detaches (stdin.Read returning ErrAttachDetached — see cmd/attach.go's detachReader). Works identically for a unix-scheme Client (the WS handshake dials over the same UNIX socket via c.httpClient's DialContext) and an https-scheme one (the handshake request carries the same Authorization: Bearer header every other request on c.httpClient does, via bearerTransport) — reusing c.httpClient rather than building a separate one is what gives WS attach Bearer auth for free, and is the point of "一本化": one transport, one auth path, for both local and remote profiles alike.

This replaces the old raw net.Dial("unix", ...) + hand-written `Upgrade: boid-attach` implementation, which only ever worked for a unix socket Client — an https-scheme Client had no socketPath to dial at all, so remote attach previously just returned a "not yet supported" error — and duplicated a second attach transport alongside the Web UI's existing WebSocket one for no reason beyond history (decision 5, docs/plans/ cli-remote-connection.md: two attach transports serving the same purpose is a maintenance burden the plan explicitly rejects).

stdin may be nil (no input forwarding) — used by TestServerJobRuntimeAttachAndResize (internal/server/server_phase3_test.go), which only cares about output replay.

func (*Client) CreateTask

func (c *Client) CreateTask(req api.CreateTaskRequest) (*orchestrator.Task, error)

CreateTask creates a new task via POST /api/tasks.

func (*Client) DeleteTask

func (c *Client) DeleteTask(id string) error

DeleteTask deletes a task via DELETE /api/tasks/{id}.

func (*Client) Do

func (c *Client) Do(method, path string, body any, result any) error

Do issues an HTTP request with no deadline. Suitable for foreground CLI commands where the user explicitly waits for a response. For latency- bounded callers (shell completion, health probes) use DoContext with a bounded context.Context so a slow / hung daemon never blocks the user's shell indefinitely.

func (*Client) DoContext added in v0.0.13

func (c *Client) DoContext(ctx context.Context, method, path string, body any, result any) error

DoContext is Do with a caller-supplied context — the request is canceled (and any in-flight IO unblocked) when ctx is Done, so completion and probe callers can enforce a wall-clock bound on the daemon round trip. Behaviorally identical to Do at the API surface (same URL construction, same headers, same status-code handling); the sole difference is the context propagation.

func (*Client) DoWithContentType

func (c *Client) DoWithContentType(method, path, contentType string, body []byte, result any) error

DoWithContentType performs an HTTP request with a custom Content-Type and raw body.

func (*Client) DuplicateTask

func (c *Client) DuplicateTask(id string) (*orchestrator.Task, error)

DuplicateTask duplicates a task via POST /api/tasks/{id}/duplicate.

func (*Client) GetProject

func (c *Client) GetProject(id string) (*orchestrator.Project, error)

GetProject fetches a single project by ID via GET /api/projects/{id}.

func (*Client) GetRaw

func (c *Client) GetRaw(path string) (statusCode int, body []byte, err error)

GetRaw performs a GET request and returns the raw response body and status code.

func (*Client) GetRawWithAcceptAndRevision added in v0.1.0

func (c *Client) GetRawWithAcceptAndRevision(path, accept string) (statusCode int, body []byte, revision string, err error)

GetRawWithAcceptAndRevision performs a GET request with a custom Accept header, returning the raw response body/status alongside the response's ETag header value VERBATIM, quotes included (Minor 2, codex review round 1; fixed round 2 — see below) — used by `boid config get`/`apply -f`/ `edit` (cmd/config.go) to capture the daemon's current config.yaml revision for a later POST's If-Match. config.yaml's GET response body is raw YAML, not JSON, so unlike `boid workspace edit` (which reads api.WorkspaceDetail.Revision straight out of a JSON body via Do), there is no JSON field to carry the revision — the ETag response header is the only place it exists on the wire.

Pre-fix (round 1) this stripped the surrounding quotes here, so every subsequent If-Match this value was round-tripped into (PostRawWithIfMatch/PutRawWithIfMatch below, which just req.Header.Set("If-Match", ifMatch) verbatim) sent a bare, unquoted token — valid enough for this daemon's own unquoteETag-on-receipt tolerance (internal/api/workspace.go), but not standard entity-tag syntax (RFC 7232 §2.3: an entity-tag is always DQUOTE ... DQUOTE, optionally W/-prefixed), which a strict intermediary on a remote deployment could reject outright. Returning the header untouched and letting the server's existing unquoteETag do the unwrapping keeps the wire format standard end to end while changing nothing about how ifMatch is used client-side (it stays an opaque string, never parsed here).

func (*Client) GetTaskDetail

func (c *Client) GetTaskDetail(id string) (*api.TaskDetailView, error)

GetTaskDetail fetches task metadata + actions + jobs for a given task ID.

func (*Client) IsUnix added in v0.0.13

func (c *Client) IsUnix() bool

IsUnix reports whether c dials a local UNIX socket (NewUnixClient, or NewClient given a "unix://" url) rather than a remote HTTPS origin. root's PersistentPreRunE uses this to decide whether daemon autostart applies (decision 6: autostart only ever makes sense for a daemon this same host can spawn).

func (*Client) ListJobs

func (c *Client) ListJobs(filter api.JobListFilter) ([]api.JobWithContext, error)

ListJobs - フィルタ付きで全プロジェクト横断のジョブ一覧を取得

func (*Client) ListProjects

func (c *Client) ListProjects() ([]*orchestrator.Project, error)

ListProjects fetches all projects.

func (*Client) ListTasks

func (c *Client) ListTasks(filter TaskListFilter) ([]*orchestrator.Task, error)

ListTasks fetches tasks with optional status and project filters.

func (*Client) ListWorkspaces

func (c *Client) ListWorkspaces() ([]*orchestrator.WorkspaceSummary, error)

ListWorkspaces fetches all workspaces.

func (*Client) PostRaw added in v0.0.13

func (c *Client) PostRaw(path, contentType string, body []byte) (statusCode int, respBody []byte, err error)

PostRaw performs a POST request with a custom Content-Type and raw body, returning the raw response status code and body regardless of status (mirrors PutRawWithIfMatch's rationale) — used by `boid workspace apply` (cmd/workspace_apply.go, one raw envelope document per POST /api/workspaces/apply) and `boid project migrate`'s daemon push (cmd/project_migrate.go, POST /api/workspaces) so each caller can distinguish the status codes its own body can provoke (409 conflict, 400 bad field/reference, 200 success) instead of losing that distinction to a single generic error string.

Historical note: this doc comment used to cite `boid workspace import` (docs/plans/workspace-db-consolidation.md PR5 Step E) as the motivating caller — that command, and the POST /api/workspaces/import endpoint it drove, were both retired 2026-07-28 (see cmd/workspace.go's runWorkspaceImportDeprecated); PostRaw itself is unaffected, since its two remaining callers above always used it independently of that one.

func (*Client) PostRawWithIfMatch added in v0.1.0

func (c *Client) PostRawWithIfMatch(path, contentType string, body []byte, ifMatch string) (statusCode int, respBody []byte, err error)

PostRawWithIfMatch performs a POST request with a custom Content-Type and (optional) If-Match header, returning the raw response status code and body regardless of status — the POST counterpart of PutRawWithIfMatch, used by `boid config apply -f`/`edit` (BLOCKER 1, codex review round 1) so the CLI can distinguish 412 (stale revision) from 428 (missing If-Match) from 200 (success) instead of losing that distinction to a single error string.

func (*Client) PostStream added in v0.1.0

func (c *Client) PostStream(ctx context.Context, path, contentType string, body io.Reader) (statusCode int, respBody []byte, err error)

PostStream performs a POST request whose body is STREAMED from body rather than buffered, returning the raw response status code and body regardless of status (PostRaw's shape, PostRaw's rationale).

It exists for `boid workspace import-home` (PR8 of docs/plans/workspace-home-volume-persistence.md, 論点 f), whose body is a tar of an entire workspace home — 4.3GB on the machine that feature was written for. Every other method here takes a []byte, which for this payload would mean holding the whole archive in the CLI's heap on its way to a local socket.

Two consequences of streaming, both deliberate:

  • The request is sent with chunked transfer encoding (no Content-Length): the size is not knowable without walking the tree twice, and the walk is the expensive part.
  • The server can answer BEFORE the body has finished uploading, and net/http's transport surfaces that response rather than the resulting write error. That is precisely what this caller wants: the daemon refuses a workspace with a running job at the very start of the request, and an operator should be told so in the first second rather than after streaming multiple gigabytes.

ctx is honored for the whole exchange, so a caller can abort a transfer.

func (*Client) ProbeAlive added in v0.0.13

func (c *Client) ProbeAlive(timeout time.Duration) bool

ProbeAlive reports whether the daemon behind this client is reachable within timeout, at the transport layer only (no auth, no request body). Used by cmd/completion.go so shell TAB completion can skip a daemon that is not going to answer without blocking the shell on a full API request.

The probe is scheme-aware:

  • unix: net.DialTimeout("unix", ...) as before
  • https: net.DialTimeout("tcp", host[:port default 443], ...) — just a TCP connect, not a TLS handshake, since the point is "is anyone listening on that port at all" not "is the cert valid" (a TLS-level failure means the daemon IS up and the follow-up API request will surface the real error to the user; a transport-level connect failure means no daemon).

func (*Client) PutRawWithIfMatch added in v0.0.13

func (c *Client) PutRawWithIfMatch(path, contentType string, body []byte, ifMatch string) (statusCode int, respBody []byte, err error)

PutRawWithIfMatch performs a PUT request with a custom Content-Type and (optional) If-Match header, returning the raw response status code and body regardless of status — unlike Do/DoWithContentType, which collapse every 4xx/5xx into a generic error. Used by `boid workspace edit` (docs/plans/workspace-db-consolidation.md PR4 Step E/H) so the CLI can distinguish 412 (stale revision) from 428 (missing If-Match) from 200 (success) instead of losing that distinction to a single error string.

func (*Client) RerunTask

func (c *Client) RerunTask(id string, autoStart bool) (*orchestrator.Task, error)

RerunTask resets a done/aborted task to pending via POST /api/tasks/{id}/rerun.

func (*Client) ResizeJob

func (c *Client) ResizeJob(jobID string, rows, cols int) error

func (*Client) SocketPath added in v0.0.13

func (c *Client) SocketPath() string

SocketPath returns the UNIX socket path this Client was built to dial, or "" for an https-scheme Client. root.PersistentPreRunE passes this to EnsureRunningAt so the autostart probe hits the same socket the CLI is about to talk to (docs/plans/cli-remote-connection.md PR1 codex review).

func (*Client) UpdateTask

func (c *Client) UpdateTask(id string, req api.UpdateTaskRequest) (*orchestrator.Task, error)

UpdateTask updates the title and description of a task via PATCH /api/tasks/{id}.

type TaskListFilter

type TaskListFilter struct {
	Status    string
	ProjectID string
}

TaskListFilter holds filters for listing tasks.

Jump to

Keyboard shortcuts

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