server

package
v0.6.30 Latest Latest
Warning

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

Go to latest
Published: Oct 21, 2026 License: MIT Imports: 42 Imported by: 0

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

View Source
const Name = "backplane"

Name of the service.

Variables

View Source
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

func Declare

func Declare(svc *backplane.Service[State])

Declare is what the server serves beyond its tree, declared before Run from svc.State(): the readiness. Component listeners belong to their nodes.

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.

func (Config) Validate

func (c Config) Validate() error

Validate checks what the schema cannot: required connections, listen addresses and their ports, the console's placement and lists.

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.

func NewState

func NewState(root backplane.Root[Config]) (*State, error)

NewState builds the server's tree. Every component gets what it needs by argument: cfg sections, st.Consul, st.Store, st.Registry (as a registry.Source).

func (*State) Ready

func (st *State) Ready(context.Context) error

Ready is the server's readiness beyond its required dependencies (which are readiness already): every component that must be up before traffic. A component with a readiness of its own adds its line here.

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_*.

func (Wiring) Resolve added in v0.3.0

func (w Wiring) Resolve(temporal bool) consolev1.Runtime

Resolve is the runtime "auto" stands for.

Jump to

Keyboard shortcuts

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