Documentation
¶
Index ¶
- Constants
- Variables
- func DefaultCLIAddr() string
- func DefaultSocketPath() string
- func EnsureRunningAt(ctx context.Context, socketPath string) error
- func WithClient(ctx context.Context, c *Client) context.Context
- type AttachOptions
- type Client
- func (c *Client) AnswerTask(taskID, questionID, answer string) error
- func (c *Client) ApplyAction(taskID string, req apiwire.ApplyActionRequest) (*apiwire.ActionApplication, error)
- func (c *Client) AttachJob(jobID string, stdin io.Reader, stdout io.Writer, opts AttachOptions) error
- func (c *Client) CreateTask(req apiwire.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) (*apiwire.TaskDetailView, error)
- func (c *Client) IsUnix() bool
- func (c *Client) ListJobs(filter apiwire.JobListFilter) ([]apiwire.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 apiwire.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, dialed by the CLI's host-mode orchestration once the daemon container is confirmed healthy. cmd/start.go's buildStartConfig uses this same value to bind server.Config.CLIAddr, and build/container/compose.yml publishes the identical port — all three must be kept in lockstep if this literal ever changes; there is no runtime override.
func DefaultSocketPath ¶
func DefaultSocketPath() string
func EnsureRunningAt ¶ added in v0.0.13
EnsureRunningAt ensures the boid server reachable at socketPath is running, probing that exact socket rather than DefaultSocketPath() unconditionally.
Autostart (spawnServer) only knows how to spin up a daemon on the default socket path, so a non-default socketPath is probe-only: on miss it returns a clear error directing the operator to launch that daemon out-of-band, rather than silently spinning up a 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 zero value before Execute()/SetContext ever run) is treated as context.Background() instead of panicking, since context.WithValue itself panics on a nil parent.
Types ¶
type AttachOptions ¶ added in v0.2.2
type AttachOptions struct {
// Notify, when non-nil, receives one short status line per reconnect
// event ("connection lost", "reconnected", "giving up"). Lines are
// CRLF-terminated because the caller's terminal is in raw mode during
// an interactive attach — a bare LF would stair-step. nil silences
// them entirely, which is what a non-interactive caller wants.
Notify io.Writer
// ReconnectWindow bounds the total time spent retrying after a drop
// (the clock starts at the first failure and is NOT reset by a
// successful reconnect that later drops again). Zero means
// defaultAttachReconnectWindow. Negative disables reconnect entirely,
// restoring the pre-reconnect behavior of returning the drop as an
// error immediately.
ReconnectWindow time.Duration
}
AttachJob opens a live interactive attach to jobID over WebSocket 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 and an https-scheme one, since both route through c.httpClient (its DialContext for unix, its bearerTransport for the Bearer header) rather than a separate transport.
stdin may be nil (no input forwarding) — used by TestServerJobRuntimeAttachAndResize (internal/server/server_phase3_test.go), which only cares about output replay. AttachOptions tunes how AttachJobWithOptions behaves when the connection drops without the server having said the job was over.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a boid daemon API client, transport-agnostic at the call site (Do/GetRaw/... all build requests against baseURL).
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 — this falls back to NewUnixClient(DefaultSocketPath()), matching what profiles.Resolve itself produces when no profile is configured, so 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 instead.
func NewClient ¶ added in v0.0.13
NewClient builds a Client from a profile URL; the scheme decides transport:
- "unix://<path>" — a local UNIX socket, dialed like NewUnixClient. token is ignored (a local socket already implies local user trust).
- "https://<host>[:port]" — TCP + TLS, with token sent as "Authorization: Bearer <token>" on every request (including same- origin redirects; see sameOriginCheckRedirect for cross-origin ones).
- "http://<loopback-host>[:port]" — used by the CLI's own host-mode orchestration to reach the container-backend daemon's CLI listener with a shared-secret Bearer token instead of TLS. Restricted to a loopback hostname (see newHTTPClient) so a Bearer token can never be sent in cleartext to a genuinely remote host.
- 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 apiwire.ApplyActionRequest) (*apiwire.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, opts AttachOptions) error
On an unexpected drop (the connection breaking without the server having said the job was over) this redials with backoff and resumes the transcript from where it left off (the ?replay_offset= / "attach" frame pair, see ws_attach.go), so the user's screen picks up mid-stream instead of repainting the whole session. An "exit" frame, an "error" frame, a clean WS close, or a local detach (Ctrl-]) all return straight away instead of reconnecting.
func (*Client) CreateTask ¶
func (c *Client) CreateTask(req apiwire.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 — used by `boid config get`/`apply -f`/`edit` 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 the ETag header is the only place the revision exists on the wire. The quotes are kept (rather than stripped here) so the value stays standard entity-tag syntax (RFC 7232 §2.3) when it is round-tripped verbatim into a later If-Match header.
func (*Client) GetTaskDetail ¶
func (c *Client) GetTaskDetail(id string) (*apiwire.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 rather than a remote HTTPS origin. Used to decide whether daemon autostart applies.
func (*Client) ListJobs ¶
func (c *Client) ListJobs(filter apiwire.JobListFilter) ([]apiwire.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 — used by `boid workspace apply` and `boid project migrate`'s daemon push 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.
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` 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. It exists for `boid workspace import-home`, whose body is a tar of an entire workspace home — every other method here takes a []byte, which for a payload that size 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). For an https client this is a bare TCP connect, not a TLS handshake — a TLS failure means the daemon IS up and a follow-up API request will surface the real error; only a transport-level 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` 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.
func (*Client) UpdateTask ¶
func (c *Client) UpdateTask(id string, req apiwire.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.