client

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Sep 18, 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, 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

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

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

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

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 — 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

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 instead.

func NewClient added in v0.0.13

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

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

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 — 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

func (c *Client) IsUnix() bool

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

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

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.

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

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