Documentation
¶
Overview ¶
Package external is the production-only entry point behind the public sdk/server facade: it turns a validated configuration into a running Harbor Protocol server that an external Go binary can host, with its compiled in-process tools wrapped at the pre-policy catalog seam.
Production posture by construction ¶
Open ALWAYS builds the JWT validator from the operator's identity config (a JWK Set fetched from identity.jwks_url or loaded from identity.jwks_file) and re-runs the full-binary Validate on the configuration, so a hand-built config cannot bypass validation and a config missing its JWKS source fails loud, naming the field, before any subsystem opens. The JWKS source itself is then fetched and parsed synchronously while the boot composes (an unreachable URL or a keyless set fails Open non-zero; subsystems opened up to that point are drained before Open returns — the caller never sees a partial server). There is no dev-signer, no mock-LLM escape hatch, and none of the caller-side injection seams the serve band exposes for the dev subcommand — a server opened here is exactly the production surface harbor serve mounts, parameterized only by the compiled-tool registrar.
The local-development loop is the three-command harbor token flow: keygen a keypair, point identity.jwks_file at the emitted JWK Set, and mint a short-lived JWT — the same loop a self-hosted harbor serve operator uses.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrConfigRequired = errors.New("server: a config or a config path is required")
ErrConfigRequired is returned by Open when neither a config value nor a config path is supplied. Identity and configuration are mandatory: the serving facade never stands up a server from nothing.
Functions ¶
This section is empty.
Types ¶
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle is the running Protocol server a successful Open returns. It wraps the serve band's lifecycle so Close reports an error return for symmetry with Serve.
func Open ¶
func Open(ctx context.Context, cfg *config.Config, configPath string, registerCatalog func(catalog tools.ToolCatalog) error) (*Handle, error)
Open composes the production Protocol server from cfg (or, when cfg is nil, from the configuration loaded at configPath) and returns a Handle whose Serve binds the listener. registerCatalog, when non-nil, is the compiled-tool registrar wired onto the assembly's pre-policy catalog seam so the served agent's tools receive their declared approval / OAuth / policy wrapping.
The configuration is validated (loud, naming the offending field) before any subsystem opens; the JWKS source is then fetched + parsed synchronously during the boot composition, so a missing JWKS source, an unreachable provider, or a missing LLM provider fails Open non-zero — never a server that starts and rejects every request. On any boot failure the already-opened subsystems are drained before Open returns.
Open writes Runtime lifecycle banners (HARBOR_DEV_BOUND, CORS-wildcard warning, pprof banner) to os.Stderr. Callers that need to redirect this output (e.g. a co-launch binary that captures stderr so Bubble Tea frames are never overwritten) should call OpenWithStderr instead.
func OpenWithStderr ¶ added in v1.15.0
func OpenWithStderr(ctx context.Context, cfg *config.Config, configPath string, stderr io.Writer, registerCatalog func(catalog tools.ToolCatalog) error) (*Handle, error)
OpenWithStderr is Open with an explicit stderr sink. A nil stderr defaults to os.Stderr. The stderr writer receives the HARBOR_DEV_BOUND line, the CORS-wildcard warning, and the pprof debug banner — the same surfaces `harbor serve`'s co-launch path redirects to a captured buffer so the terminal stays clean for Bubble Tea. The slog logger the serve band builds also writes to this sink when the caller does not inject its own logger.
func (*Handle) BindAddr ¶
BindAddr reports the address the listener is (or will be) bound to. After Serve binds an ephemeral port it reflects the OS-assigned address. Safe to call while Serve runs.
func (*Handle) Close ¶
Close drains every subsystem in reverse dependency order. Idempotent: a second Close is a no-op. The returned error is always nil today (per-subsystem close failures are logged during the drain); the signature carries an error return so a future teardown that can fail loud does not break callers.
func (*Handle) Serve ¶
Serve binds the listener and runs the Protocol server until ctx cancels, then drains within the configured shutdown grace period.
func (*Handle) WaitReady ¶ added in v1.15.0
WaitReady blocks until the listener binds (returning the actual OS-assigned address) or until the bind fails / ctx cancels. It is the race-safe one-shot readiness contract a co-launched client waits on before dialing. See serve.Handle.WaitReady for the full contract.
Source Files