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.
Runtime build identity ¶
A compiled host should set Options.Framework to the exact Harbor product version and immutable source commit it pins. runtime.info then reports those values as framework_version/framework_commit alongside the host application's unchanged build_* metadata. Leaving Options.Framework empty omits the additive framework fields and preserves existing callers' wire shape.
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.
var ErrFrameworkIdentityIncomplete = external.ErrFrameworkIdentityIncomplete
ErrFrameworkIdentityIncomplete is returned when Options.Framework names only a version or only a commit. runtime.info reports framework provenance as an immutable pair, separate from the hosting binary's build identity.
Functions ¶
This section is empty.
Types ¶
type FrameworkIdentity ¶ added in v1.28.1
type FrameworkIdentity struct {
// Version is the pinned Harbor product version (for example, "v1.28.0").
Version string
// Commit is the immutable Harbor source revision for Version.
Commit string
}
FrameworkIdentity is the Harbor framework release compiled into the host. It is deliberately distinct from the host program's own Go build metadata: a compiled agent can use it to make runtime.info identify the Harbor source that provides its runtime semantics.
Leave both fields empty to retain the compatibility fallback, which derives runtime.info's existing build_* fields from the hosting binary's Go build info. When set, Version and Commit are required together and are reported verbatim as framework_version and framework_commit.
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
// Framework identifies the Harbor framework release compiled into this
// host. When non-zero, runtime.info reports this Version and Commit as
// framework_version and framework_commit alongside the hosting program's
// existing build_* metadata. Leave it zero to omit the additive framework
// fields. Set Version and Commit together; a partial value fails Open with
// ErrFrameworkIdentityIncomplete.
Framework FrameworkIdentity
}
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