Documentation
¶
Overview ¶
Package server assembles the backplane server: its configuration and the State the SDK builds from it. backplane is a service on its own SDK (§12.2): the SDK block (BACKPLANE_*, §4.3) plus the sections here, whose environment names are BACKPLANE_<PATH> too — the service is named "backplane", so its prefix and the block's coincide, and no section here shares a name with a block field.
Index ¶
Constants ¶
const Name = "backplane"
Name of the service.
Variables ¶
var ( ErrNoPG = errors.New("pg.dsn is required (BACKPLANE_PG_DSN)") ErrNoConsul = errors.New("backplane.consul.addr is required (BACKPLANE_CONSUL_ADDR)") ErrAddr = errors.New("want host:port with a port in 1..65535") ErrPortTaken = errors.New("port is used twice") ErrPrefix = errors.New("console.prefix: want /path without a trailing slash") ErrOrigin = errors.New("console.origins: want scheme://host[:port]") ErrProxy = errors.New("console.trusted_proxies: want an address or CIDR") ErrURL = obs.ErrURL ErrNoAdminToken = errors.New("admin_token is required (BACKPLANE_ADMIN_TOKEN): " + "the console's login secret, set in the deployment") ErrShortAdminToken = fmt.Errorf("want at least %d characters", console.MinAdminTokenLen) ErrWiringRuntime = errors.New("want auto, temporal or direct") ErrWiringTemporal = errors.New("wiring.runtime is temporal but temporal is not configured (BACKPLANE_TEMPORAL_ADDR)") )
Errors of Validate.
Functions ¶
Types ¶
type Config ¶
type Config struct {
config.Backplane `json:"backplane"`
// PostgreSQL, schema `backplane`: BACKPLANE_PG_DSN, _QUERY_LOG, _POOL_*.
PG postgres.Config `json:"pg"`
Infrastructure Infrastructure `json:"infrastructure"`
// Console HTTP: `/`, `/ws`, `/auth`, `/plugins`, served directly or behind a deployment-owned proxy.
Console Console `json:"console"`
// Admin token of the console (§11.3): the secret /auth/login accepts,
// set in the deployment; required, at least 16 characters. Changing it
// is changing the secret and rolling the replicas; sessions opened with
// the old one last until they expire or are revoked.
AdminToken config.Secret `json:"admin_token,omitempty"`
// Read-only access to independent observability backends (§15.2).
Obs obs.Config `json:"obs"`
// Durable control audit settings belong to deployment.
Audit audit.Settings `json:"audit"`
// Durable application errors: BACKPLANE_ERRORS_*.
Errors apperrors.Settings `json:"errors"`
// OTLP admission into a deployment-owned Collector; empty URL disables it.
OTLP otlp.Config `json:"otlp"`
// Live-value overrides: BACKPLANE_LIVE_CONFIG_* (§5.3).
LiveConfig liveconfig.Settings `json:"live_config"`
// Nexus endpoint reconciliation and retirement.
Nexus Nexus `json:"nexus"`
// Wiring: the runtime of bindings and rules that name none.
Wiring Wiring `json:"wiring"`
// Direct runtime: runs in backplane's process.
Direct Direct `json:"direct"`
}
Config of the backplane server.
type Console ¶
type Console struct {
// AssetsDir serves a built console shell from a deployment-owned directory.
AssetsDir string `json:"assets_dir,omitempty"`
Listen string `json:"listen" schemapb:"default=:8081"`
// Prefix mounts the console under a path such as /backplane.
Prefix string `json:"prefix,omitempty"`
// Origins allowed to open /ws (https://console.example.com); empty:
// the console's own host.
Origins []string `json:"origins,omitempty"`
// Proxies whose X-Forwarded-For is trusted: addresses or CIDRs.
TrustedProxies []string `json:"trusted_proxies,omitempty"`
// InsecureCookie drops Secure from the session cookie (and HSTS):
// plain-HTTP development only.
InsecureCookie bool `json:"insecure_cookie" schemapb:"default=false"`
}
Console of the installation (§11): BACKPLANE_CONSOLE_*.
type Direct ¶ added in v0.3.0
type Direct struct {
// RunTimeout bounds a rule's run (a hook call is bounded by its deadline).
RunTimeout time.Duration `json:"run_timeout" schemapb:"default=5m;gt=0"`
// Retention of recorded runs; 0 keeps them.
Retention time.Duration `json:"retention" schemapb:"default=168h;gte=0"`
}
Direct runtime settings: BACKPLANE_DIRECT_*.
type Infrastructure ¶
type Infrastructure struct {
CollectorURL string `json:"collector_url,omitempty"`
GatewayURL string `json:"gateway_url,omitempty"`
MetricsURL string `json:"metrics_url,omitempty"`
LogsURL string `json:"logs_url,omitempty"`
TracesURL string `json:"traces_url,omitempty"`
}
Infrastructure contains optional deployment-owned health endpoints. Collector and gateway expose no universal health URL: deployments supply theirs here.
func (Infrastructure) Validate ¶
func (c Infrastructure) Validate() error
Validate prevents malformed endpoints and credentials in URLs.
type Nexus ¶
type Nexus struct {
AbsenceGrace time.Duration `json:"absence_grace" schemapb:"default=5m;gte=0"`
ReconcileInterval time.Duration `json:"reconcile_interval" schemapb:"default=1m;gt=0"`
}
Nexus controls cleanup of endpoints whose services have no instances.
type State ¶
type State struct {
// Consul is backplane's client (the SDK's own is not shared): the
// registry reads through it, configuration writes KV through it.
Consul *api.Client
// Store is PostgreSQL: required — the start waits for it (migrated),
// readiness follows its ping.
Store deps.Dependency[*store.Store]
// Registry is the installation as Consul sees it; everything else reads
// its snapshots (registry.Source).
Registry *registry.Registry
// Config keeps Live-value overrides: revisions in PostgreSQL, delivery
// and reconciliation to Consul KV config/, the console's ConfigService.
Config *config.Manager
// Bindings keeps bindings (hook -> steps) and rules (event -> steps):
// versions in PostgreSQL validated against the latest manifests, the
// console's BindingService and RuleService.
Bindings *bindings.Manager
// Rules consumes events for the rules and starts their runs.
Rules *rules.Engine
// Ops is the console's operations on NATS and Temporal through the
// SDK's own clients: events, streams, consumers, dead letters;
// workflows, runs, schedules; hook and activity calls (their workflows
// run on backplane's task queue).
Ops *ops.Ops
// Direct is the direct runtime: bindings and rules run in this process
// without Temporal, activities called over the services' platform
// ports; backplane's HookService; the console's run RPCs.
Direct *direct.Service
// Executor answers every hook over Temporal Nexus (an endpoint per
// service with hooks, a Nexus worker on backplane's queue) and runs
// bindings and rules as the workflow backplane.Binding.v1 there; the
// console's run RPCs of BindingService.
Executor *executor.Executor
// Console is the console's HTTP on its own listener: auth, /ws
// (backplane's own API and the relay to the services' internal API),
// plugin bundles.
Console *console.Console
// Obs reads deployment-owned stores; no dependency on their readiness.
Obs *obs.Service
// Errors keeps application errors durably and serves ErrorService.
Errors *apperrors.Service
// Audit serves durable control history and optionally exports OTel Logs.
Audit *audit.Service
Platform *platform.Service
// AuditIngest is the OTLP audit listener: application audit the
// Collector forwards, stored for AuditService.
AuditIngest *audit.Ingest
// contains filtered or unexported fields
}
State is the server's tree under the Root, in start order: the store, the registry, then the components built on them. Components stop in reverse, before what they were given.
type Wiring ¶ added in v0.3.0
type Wiring struct {
// Runtime of a binding or rule that names none: "temporal", "direct",
// or "auto": temporal when Temporal is configured, else direct.
Runtime string `json:"runtime" schemapb:"default=auto"`
// Dir holds bindings and rules as YAML files, kept in force: the
// console only reads what they define (website guides/wiring.md).
// Empty: everything is the console's.
Dir string `json:"dir,omitempty"`
// Poll is how often Dir is read again (it is read on every new
// manifest too).
Poll time.Duration `json:"poll" schemapb:"default=5s;gt=0"`
}
Wiring of the installation: BACKPLANE_WIRING_*.