Documentation
¶
Index ¶
- Constants
- Variables
- func DefaultCLIAddr() string
- func DefaultSocketPath() string
- func EnsureRunning(ctx context.Context) error
- func EnsureRunningAt(ctx context.Context, socketPath string) error
- func WithClient(ctx context.Context, c *Client) context.Context
- type Client
- func (c *Client) AnswerTask(taskID, questionID, answer string) error
- func (c *Client) ApplyAction(taskID string, req api.ApplyActionRequest) (*api.ActionApplication, error)
- func (c *Client) AttachJob(jobID string, stdin io.Reader, stdout io.Writer) error
- func (c *Client) CreateTask(req api.CreateTaskRequest) (*orchestrator.Task, error)
- func (c *Client) DeleteTask(id string) error
- func (c *Client) Do(method, path string, body any, result any) error
- func (c *Client) DoContext(ctx context.Context, method, path string, body any, result any) error
- func (c *Client) DoWithContentType(method, path, contentType string, body []byte, result any) error
- func (c *Client) DuplicateTask(id string) (*orchestrator.Task, error)
- func (c *Client) GetProject(id string) (*orchestrator.Project, error)
- func (c *Client) GetRaw(path string) (statusCode int, body []byte, err error)
- func (c *Client) GetRawWithAcceptAndRevision(path, accept string) (statusCode int, body []byte, revision string, err error)
- func (c *Client) GetTaskDetail(id string) (*api.TaskDetailView, error)
- func (c *Client) IsUnix() bool
- func (c *Client) ListJobs(filter api.JobListFilter) ([]api.JobWithContext, error)
- func (c *Client) ListProjects() ([]*orchestrator.Project, error)
- func (c *Client) ListTasks(filter TaskListFilter) ([]*orchestrator.Task, error)
- func (c *Client) ListWorkspaces() ([]*orchestrator.WorkspaceSummary, error)
- func (c *Client) PostRaw(path, contentType string, body []byte) (statusCode int, respBody []byte, err error)
- func (c *Client) PostRawWithIfMatch(path, contentType string, body []byte, ifMatch string) (statusCode int, respBody []byte, err error)
- func (c *Client) PostStream(ctx context.Context, path, contentType string, body io.Reader) (statusCode int, respBody []byte, err error)
- func (c *Client) ProbeAlive(timeout time.Duration) bool
- func (c *Client) PutRawWithIfMatch(path, contentType string, body []byte, ifMatch string) (statusCode int, respBody []byte, err error)
- func (c *Client) RerunTask(id string, autoStart bool) (*orchestrator.Task, error)
- func (c *Client) ResizeJob(jobID string, rows, cols int) error
- func (c *Client) SocketPath() string
- func (c *Client) UpdateTask(id string, req api.UpdateTaskRequest) (*orchestrator.Task, error)
- type TaskListFilter
Constants ¶
const (
// NoAutostartEnv disables automatic server startup when set to "1".
NoAutostartEnv = "BOID_NO_AUTOSTART"
)
Variables ¶
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 ¶
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
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
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
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
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
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 (*Client) AnswerTask ¶
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 ¶
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 ¶
DeleteTask deletes a task via DELETE /api/tasks/{id}.
func (*Client) Do ¶
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
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 ¶
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 ¶
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
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
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 ¶
RerunTask resets a done/aborted task to pending via POST /api/tasks/{id}/rerun.
func (*Client) SocketPath ¶ added in v0.0.13
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 ¶
TaskListFilter holds filters for listing tasks.