Documentation
¶
Overview ¶
Package server is the public SDK facade for serving the Harbor Protocol from your own Go binary — the external-serving on-ramp that makes an agent with compiled in-process tools reachable over the wire at parity with the stock harbor serve.
Open turns a validated configuration into a running Protocol server:
import (
_ "github.com/hurtener/Harbor/sdk/drivers/prod"
"github.com/hurtener/Harbor/sdk/config"
"github.com/hurtener/Harbor/sdk/server"
)
cfg, _ := config.Load(ctx, "harbor.yaml")
h, err := server.Open(ctx, cfg, server.Options{
RegisterCatalog: agent.RegisterTools,
})
// ... handle err ...
defer h.Close(ctx)
_ = h.Serve(ctx) // blocks until ctx cancels
Production-only by construction ¶
Open ALWAYS builds the JWT validator from cfg.Identity (the operator's JWK Set) and re-runs the full configuration Validate, so a missing JWKS source or an otherwise-invalid config fails loud at Open, naming the field — never at the first request. There is no dev-signer, no mock-LLM knob, and none of the dev-only injection seams the runtime's dev loop uses. A served binary is exactly the production surface.
The local-development loop is the three-command harbor token flow — the same one a self-hosted harbor serve operator uses:
harbor token keygen --out ./keys
# set identity.jwks_file: ./keys/jwks.json in harbor.yaml
harbor token mint --key ./keys/private.pem \
--tenant acme --user alice --session s1 \
--issuer <your issuer> --audience <your audience>
Compiled tools keep their declared policy ¶
Options.RegisterCatalog rides the assembly's pre-policy catalog seam: a tool it registers is wrapped with its declared approval / OAuth / policy shell (from tools.entries in harbor.yaml) before the run loop can dispatch it — identical to an operator's YAML-declared tool. Registering tools any other way (after Open returns) skips that shell.
This package is an alias-based facade over the internal serving band; no mechanism lives here beyond the single Options adapter.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrConfigRequired = external.ErrConfigRequired
ErrConfigRequired is returned by Open when neither a config value nor a config-path is supplied. Compare via errors.Is.
Functions ¶
This section is empty.
Types ¶
type Handle ¶
Handle is the running Protocol server Open returns: Serve binds the listener and runs until ctx cancels; Close drains every subsystem; BindAddr reports the bound address.
func Open ¶
Open composes the production Protocol server from cfg (or, when cfg is nil, from Options.ConfigPath) and returns a Handle whose Serve binds the listener. The configuration is validated loud before any subsystem opens — a missing JWKS source fails Open, naming the field — and the JWT validator is always built from cfg.Identity, its JWKS source fetched synchronously while the boot composes (a bad source fails Open with everything opened so far drained; never a server that starts and rejects every request).
This is the facade's single Options adapter: it forwards to the internal serving band, which owns the JWKS factory, the config re-validation, and the pre-policy registrar wiring.
type Options ¶
type Options struct {
// RegisterCatalog, when non-nil, registers the served agent's
// compiled in-process tools on the runtime catalog at the pre-policy
// seam, so each tool receives its declared approval / OAuth / policy
// wrapping (from tools.entries in harbor.yaml). Pass your project's
// RegisterTools here. A non-nil error fails Open loud.
RegisterCatalog func(catalog tools.ToolCatalog) error
// ConfigPath is the load-from-config convenience: when Open is
// called with a nil config, the configuration is loaded and
// validated from this path. Ignored when a non-nil config is passed
// to Open.
ConfigPath string
// Stderr is where the serve band writes Runtime lifecycle banners
// (the HARBOR_DEV_BOUND line, the CORS-wildcard warning, the pprof
// banner) and where slog output lands when a caller injects its own
// logger. Nil defaults to os.Stderr — the headless posture. A
// co-launch binary (e.g. `harbor serve --tui` or a generated
// `--tui` binary) sets this to a captured buffer so Bubble Tea
// frames are never overwritten; on failure the terminal is restored
// before the captured stderr is printed.
Stderr io.Writer
}
Options carries Open's injection points. It is deliberately minimal — the production posture (JWKS from cfg.Identity, full config Validate) is not configurable.
Source Files