brokerclient

package
v0.2.2 Latest Latest
Warning

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

Go to latest
Published: Aug 10, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package brokerclient holds the low-level transport for talking to the boid broker over its UNIX socket or its TCP(mTLS) listener, plus a self-contained JobDone helper.

It is a leaf package: it deliberately does NOT import internal/sandbox so that both the sandbox CLI shim (internal/sandbox/boid_shim.go) and the go-native sandbox runner (internal/sandbox/runner) can share the transport without an import cycle. The wire structs below mirror the JSON shapes the broker decodes (internal/sandbox/protocol.go: ExecRequest / ExecResponse / BoidRequest) field-for-field; keep the json tags in sync.

Two transports (docs/plans/phase6-cutover-followups.md §⓪ "broker TCP wire completion"): SendJSON dials the broker's UNIX socket — the original, still-current mechanism for the userns backend, where the sandbox and the daemon share a mount namespace so a bind-mounted socket file is always reachable. SendJSONTLS dials the broker's TCP(mTLS) listener instead — the only mechanism a container-backend job's SIBLING container can use, since it has no access to the daemon container's own filesystem at all. Every real caller in this repo picks between the two via SendJSONFromEnv (or, for JobDone, the equivalent map-driven decision) rather than choosing a transport itself — see its own doc comment for the exact selection rule.

Index

Constants

View Source
const (
	EnvBrokerSocket        = "BOID_BROKER_SOCKET"
	EnvBrokerTLSAddr       = "BOID_BROKER_TLS_ADDR"
	EnvBrokerTLSCertPath   = "BOID_BROKER_TLS_CERT_PATH"
	EnvBrokerTLSKeyPath    = "BOID_BROKER_TLS_KEY_PATH"
	EnvBrokerTLSCAPath     = "BOID_BROKER_TLS_CA_PATH"
	EnvBrokerTLSServerName = "BOID_BROKER_TLS_SERVER_NAME"
)

Env var names shared between the container backend's delivery side (internal/dispatcher/container_backend.go's withBrokerTLSEnv, which sets these five plus BOID_BROKER_SOCKET's own separate, backend-agnostic mount) and this package's own transport-selection logic (SendJSONFromEnv). Exported so a caller that already has these values in hand some other way (e.g. a test) can reference the same literal keys instead of hand-typing them a second time.

Variables

This section is empty.

Functions

func DialFromEnv added in v0.1.0

func DialFromEnv() (net.Conn, error)

DialFromEnv dials the broker using the exact same transport-selection rule as SendJSONFromEnv (TLS when BOID_BROKER_TLS_ADDR is set, else UNIX when BOID_BROKER_SOCKET is set), but returns the raw net.Conn instead of performing one JSON request/response round trip itself. This is for a caller that needs a long-lived connection for its own streaming protocol — internal/sandbox/shim.go's sendStreamingExecRequest (host-command exec with real-time stdout/stderr forwarding and signal propagation, which predates and is not JSON-request/response-shaped the way SendJSON's protocol is) is the one caller in this repo.

func JobDone

func JobDone(env map[string]string, token, jobID, cwd string, exitCode int, output []byte) error

JobDone posts a `boid job done` builtin request to the broker. It replaces the former EXIT-trap `boid job done --exit-code … --output-file …` CLI fork-exec: the go runner calls this directly from runner-inner-child / RunContainer.

env is the job's own env view (internal/sandbox/runner.postJobDone passes spec.Env directly, not os.Environ() — see sendJSONWithLookup's own doc comment for why) — JobDone picks TLS vs UNIX from it via the exact same rule SendJSONFromEnv applies to the current process's real environment. Before docs/plans/phase6-cutover-followups.md §⓪ this parameter was a bare `socket string`; every caller (there is exactly one, internal/sandbox/runner/runner.go's postJobDone) now passes spec.Env wholesale instead of extracting BOID_BROKER_SOCKET itself, so a container-backend job's BOID_BROKER_TLS_* keys are visible to this function too.

cwd must be the sandbox working directory (the same cwd the EXIT trap ran in) because the broker validates it against the token's project/worktree root (validateBoidBuiltinCwd). output carries the agent's payload_patch.json (or the stdout-capture fallback); an empty output is valid and matches the bare `boid job done --exit-code` form.

func SendJSON

func SendJSON(socket string, req any, resp any) error

SendJSON dials the broker UNIX socket, JSON-encodes req, and decodes a single JSON response into resp. It is the extraction of the former sandbox.sendExecRequest transport so the shim and the runner share one implementation.

func SendJSONFromEnv added in v0.1.0

func SendJSONFromEnv(req any, resp any) error

SendJSONFromEnv is the single decision point every real shim caller in this repo shares for picking a broker transport based on the CURRENT PROCESS's own environment — see sendJSONWithLookup's own doc comment for the exact selection rule. This is what lets internal/sandbox/shim.go's sendExecRequest (and everything that calls it: RunBoidShim, `boid fetch`, the task-context/attachments subcommands) stay backend-agnostic without each duplicating the TLS-vs-UNIX decision itself.

func SendJSONTLS added in v0.1.0

func SendJSONTLS(addr, serverName, certPath, keyPath, caPath string, req any, resp any) error

SendJSONTLS dials the broker's TCP(mTLS) listener at addr, presenting the client certificate/key at certPath/keyPath, trusting the CA certificate at caPath, and verifying the server's own certificate against serverName — the TCP+mTLS counterpart to SendJSON's plain UNIX dial. This is the transport a container-backend job's sibling container uses (docs/plans/ phase6-cutover-followups.md §⓪): the per-job client cert/key/ca trio certPath/keyPath/caPath name is bind-mounted read-only by internal/dispatcher/container_backend.go's Launch at a fixed container-internal path (containerBrokerTLSDir), and addr/serverName are the compose service DNS name (+ port) and SAN the broker's own mtls.CA.ServerTLSConfig("127.0.0.1", "localhost", composeBrokerServiceName) call issued its listener cert for — see internal/server/server.go's Start.

Real callers should not build this argument list by hand — SendJSONFromEnv (or, for JobDone, its own equivalent) reads the exact same five values out of the caller's environment and is the actual production entry point. This function is exported mainly so it is independently unit-testable against a real tls.Listen-based fake server (see brokerclient_test.go).

Types

This section is empty.

Jump to

Keyboard shortcuts

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