config

package
v0.6.111 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

Package config loads a service's configuration: one struct, schema from the Go type (schemapb), layers merged by xconf:

schema defaults < file < env <SERVICE>_* (BACKPLANE_* for the SDK block) < Consul KV

Consul KV applies only to Live fields. Load reads once; Open keeps the configuration live.

Index

Constants

View Source
const (
	DefaultNATSConnectTimeout   = 2 * time.Second
	DefaultNATSReconnectWait    = 2 * time.Second
	DefaultNATSReconnectJitter  = time.Second
	DefaultNATSPingInterval     = 2 * time.Minute
	DefaultNATSMaxPingsOut      = 2
	DefaultNATSJetStreamTimeout = 5 * time.Second
)

Defaults of NATSConnection.

View Source
const (
	HooksAuto     = "auto"
	HooksTemporal = "temporal"
	HooksDirect   = "direct"
)

Transports of hook calls.

View Source
const (
	DefaultTemporalKeepAliveTime        = 30 * time.Second
	DefaultTemporalKeepAliveTimeout     = 15 * time.Second
	DefaultTemporalGetSystemInfoTimeout = 5 * time.Second
	TemporalCompressionNone             = "none"
	TemporalCompressionGzip             = "gzip"
)

Defaults of TemporalConnection.

View Source
const (
	MeshAllow = "allow"
	MeshDeny  = "deny"
)

Mesh defaults.

View Source
const (
	// PlatformPlain: no TLS, as without a mesh.
	PlatformPlain = "plain"
	// PlatformAccept: mutual TLS is served next to plain connections; the
	// service still calls others plain. Every service of the installation
	// gets here before any goes to mtls.
	PlatformAccept = "accept"
	// PlatformMTLS: the service calls others over mutual TLS; plain
	// connections reach only the probes.
	PlatformMTLS = "mtls"
)

Platform port modes (Mesh.Platform).

View Source
const (
	// SamplerAlwaysOn records every span whatever the parent decided:
	// sampling is the collector's (tail sampling sees whole traces).
	SamplerAlwaysOn = "always_on"
	// SamplerAlwaysOff records nothing.
	SamplerAlwaysOff = "always_off"
	// SamplerTraceIDRatio records Ratio of traces by trace id.
	SamplerTraceIDRatio = "traceidratio"
	// SamplerParentBasedAlwaysOn follows the parent, records roots
	// (OpenTelemetry's default).
	SamplerParentBasedAlwaysOn = "parentbased_always_on"
	// SamplerParentBasedAlwaysOff follows the parent, drops roots.
	SamplerParentBasedAlwaysOff = "parentbased_always_off"
	// SamplerParentBasedTraceIDRatio follows the parent, records Ratio of
	// roots.
	SamplerParentBasedTraceIDRatio = "parentbased_traceidratio"
)

Samplers of Traces.

View Source
const (
	// AggregationExplicit: fixed bucket boundaries (Boundaries).
	AggregationExplicit = "explicit"
	// AggregationExponential: base-2 exponential buckets that follow the
	// data (MaxSize, MaxScale): precise quantiles at any scale, more series
	// in storage (VictoriaMetrics keeps them as vmrange buckets).
	AggregationExponential = "exponential"
	// AggregationDrop: the histogram is not exported.
	AggregationDrop = "drop"
	// AggregationDefault: what the instrument itself asks for (its
	// boundaries advice, else OpenTelemetry's defaults); stops the rules.
	AggregationDefault = "default"
)

Aggregations of a histogram rule.

View Source
const EnvFile = "BACKPLANE_CONFIG_FILE"

EnvFile names the default configuration file.

View Source
const SealKeySize = 32

SealKeySize is the size of a seal key: AES-256.

Variables

View Source
var (
	ErrRemoteDriver = errors.New("config: consul configured without a remote configuration driver")
	ErrRemoteSource = errors.New("config: remote configuration driver returned nil")
)

Remote driver configuration errors.

View Source
var (
	// ErrTLSCA: the CA holds no PEM certificate.
	ErrTLSCA = errors.New("config: tls: ca holds no PEM certificate")
	// ErrTLSPair: only one of cert and key is set.
	ErrTLSPair = errors.New("config: tls: cert and key go together")
)

Errors of TLS.ClientConfig.

View Source
var ErrInboxPrefix = errors.New("inbox_prefix is a subject prefix without wildcards or a trailing dot")

ErrInboxPrefix: an inbox prefix NATS would refuse.

View Source
var ErrSeal = errors.New("seal: invalid configuration")

ErrSeal: a seal section has no key, a key is not base64 of 32 bytes, or its vault is incomplete.

View Source
var ErrTemporalCompression = errors.New("temporal: grpc_compression: want none or gzip")

ErrTemporalCompression: grpc_compression is neither none nor gzip.

Functions

func CheckInboxPrefix added in v0.6.74

func CheckInboxPrefix(p string) error

CheckInboxPrefix: empty (NATS's _INBOX), or subject tokens without wildcards, whitespace or a trailing dot.

func Load

func Load[C any](ctx context.Context, opts ...Option) (C, error)

Load reads the configuration once: defaults, file and environment. For tools and tests; services use Open through backplane.Open.

Types

type Backplane

type Backplane struct {
	Consul   Consul   `desc:"Service discovery, catalog registration and instance state." json:"consul"`
	NATS     NATS     `desc:"Events, reactors and dead letters (JetStream)."              json:"nats"`
	Temporal Temporal `desc:"Workflows, activities and hook calls."                       json:"temporal"`
	Hooks    Hooks    `desc:"How the service calls the platform's hooks."                 json:"hooks"`
	Shutdown Shutdown `desc:"Graceful stop budget."                                       json:"shutdown"`
	Health   Health   `desc:"Probe evaluation."                                           json:"health"`
	// Limits of the SDK's HTTP and gRPC servers (public and platform ports).
	Server Server `desc:"Limits of the HTTP and gRPC servers (public and platform ports)." json:"server"`
	// Metric export timing and histogram aggregation.
	Telemetry Telemetry `desc:"Metric export timing, histogram aggregation and trace sampling." json:"telemetry"`
	// Mutual TLS between services.
	Mesh Mesh `desc:"Mutual TLS between services." json:"mesh"`

	// Instance id; default <service>-<hostname>.
	Instance string `desc:"Instance id; empty: <service>-<hostname>." json:"instance,omitempty"`
	// Address other components reach this instance at; default POD_IP, then
	// the hostname's address.
	Advertise string `` /* 126-byte string literal not displayed */
	// deployment.environment.name for telemetry; exporters use OTEL_*.
	Environment string `desc:"deployment.environment.name of telemetry; exporters are set with OTEL_*." json:"environment,omitempty"`
	// Platform port: internal API, health, probes, UI bundle.
	InternalPort int64 `desc:"Platform port: internal API, health, probes, UI bundle." json:"internal_port" schemapb:"default=9400;gte=1;lte=65535"`
	// Shared secret the console relay presents; empty disables the check.
	InternalSecret Secret `desc:"Shared secret the console relay presents; empty disables the check." json:"internal_secret,omitempty"`
	// Also accepted while the secret rotates: set the new one as
	// internal_secret and the old one here, then drop it.
	InternalSecretPrevious Secret `` /* 173-byte string literal not displayed */
	// Default listener of managed public routes.
	PublicPort int64 `desc:"Default listener of managed public routes." json:"public_port" schemapb:"default=8080;gte=1;lte=65535"`
	// Log level; changed live from the console.
	LogLevel Live[string] `` /* 148-byte string literal not displayed */
	// Serve /debug/pprof on the platform port behind the internal secret.
	Pprof bool `desc:"Serve /debug/pprof on the platform port behind the internal secret." json:"pprof" schemapb:"default=false"`
}

Backplane is the SDK's own block, part of the service configuration:

type Config struct {
    config.Backplane `json:"backplane"`
    DB string        `json:"db"`
}

Its environment names are fixed (BACKPLANE_*) for every service. Every dependency is optional for a service: an empty address means "without it".

func (Backplane) BackplaneConfig

func (b Backplane) BackplaneConfig() Backplane

BackplaneConfig returns the block; promoted to the embedding struct.

type Backplaner

type Backplaner interface{ BackplaneConfig() Backplane }

Backplaner is satisfied by any struct embedding Backplane.

type Consul

type Consul struct {
	Addr       string `desc:"Consul agent host:port; empty: without Consul." json:"addr,omitempty"`
	Token      Secret `desc:"ACL token."                                     json:"token,omitempty"`
	Datacenter string `desc:"Datacenter; empty: the agent's."                json:"datacenter,omitempty"`
	TLS        TLS    `desc:"TLS of the connection to the agent."            json:"tls"`
	// false when the deployment registers the service itself.
	Register bool `desc:"Register the instance in the catalog; off when the deployment registers it." json:"register" schemapb:"default=true"`
	// Tags of the catalog registration.
	Tags []string `desc:"Tags of the catalog registration." json:"tags,omitempty"`
	// Health check of the catalog registration.
	CheckInterval   time.Duration `desc:"Interval of the registration's health check."           json:"check_interval"   schemapb:"default=10s"`
	CheckTimeout    time.Duration `desc:"Timeout of the registration's health check."            json:"check_timeout"    schemapb:"default=5s"`
	DeregisterAfter time.Duration `desc:"A registration failing its check this long is removed." json:"deregister_after" schemapb:"default=1m"`
	// TTL of the session the instance state lives under.
	SessionTTL time.Duration `desc:"TTL of the session the instance state lives under." json:"session_ttl" schemapb:"default=30s"`
}

Consul connection.

func (Consul) Enabled

func (c Consul) Enabled() bool

Enabled reports whether Consul is configured.

type Health

type Health struct {
	Interval time.Duration `desc:"How often the probes are evaluated." json:"interval" schemapb:"default=5s"`
	// Per evaluation; at most interval.
	Timeout time.Duration `desc:"Bound of one evaluation; at most interval." json:"timeout" schemapb:"default=3s"`
}

Health evaluation of the probes.

type Histogram added in v0.6.16

type Histogram struct {
	// Instrument name; * and ? are wildcards ("templates.*", "*").
	Instrument string `desc:"Instrument name; * and ? are wildcards." json:"instrument" schemapb:"default=*"`
	// Unit the histogram must have ("s", "ms", "By"); empty: any.
	Unit string `desc:"Unit the histogram must have (s, ms, By); empty: any." json:"unit,omitempty"`
	// explicit, exponential, drop or default.
	Aggregation string `desc:"explicit, exponential, drop or default." json:"aggregation" schemapb:"default=explicit"`
	// explicit: bucket upper bounds, strictly increasing.
	Boundaries []float64 `desc:"explicit: bucket upper bounds, strictly increasing." json:"boundaries,omitempty"`
	// exponential: most buckets per sign (default 160); fewer means coarser
	// buckets and fewer series.
	MaxSize int32 `desc:"exponential: most buckets per sign; 0: 160." json:"max_size,omitempty" schemapb:"gte=0"`
	// exponential: finest scale, -10..20 (default 20).
	MaxScale int32 `desc:"exponential: finest scale, -10..20; 0: 20." json:"max_scale,omitempty" schemapb:"gte=-10;lte=20"`
	// Leave min and max out of the histogram.
	NoMinMax bool `desc:"Leave min and max out of the histogram." json:"no_min_max,omitempty"`
}

Histogram is one rule: which histograms it matches and how they aggregate.

type Hooks added in v0.3.0

type Hooks struct {
	// Transport of hook calls: "temporal" (Nexus through the configured
	// Temporal), "direct" (gRPC to backplane's platform port, its replicas
	// found through Consul), or "auto": temporal when Temporal is
	// configured, else direct when Consul is.
	Transport string `` /* 187-byte string literal not displayed */
}

Hooks: how this service's hook calls reach backplane.

func (Hooks) Resolve added in v0.3.0

func (h Hooks) Resolve(temporal, consul bool) string

Resolve is the transport "auto" stands for given what is configured: HooksTemporal, HooksDirect or "" when neither Temporal nor Consul is.

type Live

type Live[T any] struct {
	// contains filtered or unexported fields
}

Live is a configuration field that changes at runtime: set from the console through Consul KV, applied in place. Every copy of the enclosing section reads the same current value.

Live fields must sit in structs, not in slices or maps: Open rejects those. A zero Live reads the zero value and never fires; LiveOf makes one with a value. Its methods take a pointer (loading fills it in place), so encoding/json and fmt see the current value only through a pointer to the enclosing struct.

func LiveOf

func LiveOf[T any](v T) Live[T]

LiveOf returns a Live holding v: defaults in code, tests.

func (*Live[T]) Apply added in v0.6.27

func (l *Live[T]) Apply(fn func(T) error)

Apply calls fn with every new value before it is published, to carry it to something outside the process (a pool, a client, a limiter). An error (or a panic) rejects the whole update: no Live field changes, Watch callbacks do not fire, appliers that already took the update are called again with the value they had, and the instance reports the revision rejected with the error, as a failed Validate does. Appliers run in order on the configuration's update goroutine, after Validate; the value loaded at start is the component's to apply.

func (*Live[T]) Get

func (l *Live[T]) Get() T

Get returns the current value.

func (*Live[T]) MarshalJSON

func (l *Live[T]) MarshalJSON() ([]byte, error)

MarshalJSON writes the current value.

func (*Live[T]) SchemaDecodeTarget

func (l *Live[T]) SchemaDecodeTarget() any

SchemaDecodeTarget gives the decoder a fresh private cell to fill.

func (*Live[T]) SchemaField

func (*Live[T]) SchemaField(f *sp.Schema_Field) error

SchemaField marks the field live.

func (*Live[T]) SchemaInner

func (*Live[T]) SchemaInner() reflect.Type

SchemaInner makes the field's schema the schema of T.

func (*Live[T]) Watch

func (l *Live[T]) Watch(fn func(T))

Watch calls fn with every new value applied after loading. Callbacks run in order on the configuration's update goroutine: keep them short and do not close the service from one.

type Mesh added in v0.6.20

type Mesh struct {
	// What a caller no intention names gets: allow (Consul's own default
	// without ACLs) or deny.
	Default string `desc:"What a caller no intention names gets: allow or deny." json:"default" schemapb:"default=allow"`
	// Platform is mutual TLS on the platform port and on the calls to the
	// platform ports of others (activities, hooks, the console relay):
	// plain, accept (served, not used: the step of a rollout) or mtls.
	Platform string `` /* 199-byte string literal not displayed */
}

Mesh is mutual TLS between services (api.MTLS, Root.ServiceCredentials, the platform port): BACKPLANE_MESH_*. Certificates and who may call whom come from the installed driver (Consul's CA and intentions).

type Metrics added in v0.6.16

type Metrics struct {
	// How often metrics are exported; 0: OTEL_METRIC_EXPORT_INTERVAL, else 30s.
	Interval time.Duration `desc:"How often metrics are exported; 0: OTEL_METRIC_EXPORT_INTERVAL, else 30s." json:"interval" schemapb:"default=0s;gte=0"`
	// Bound of one export; 0: OTEL_METRIC_EXPORT_TIMEOUT, else 10s.
	Timeout time.Duration `desc:"Bound of one export; 0: OTEL_METRIC_EXPORT_TIMEOUT, else 10s." json:"timeout" schemapb:"default=0s;gte=0"`
	// Histogram rules, first match wins, ahead of the built-in ones (seconds
	// and milliseconds buckets for histograms in s and ms). As an environment
	// variable: a JSON list, e.g.
	// BACKPLANE_TELEMETRY_METRICS_HISTOGRAMS='[{"instrument":"*","unit":"s","aggregation":"exponential"}]'.
	Histograms []Histogram `desc:"Histogram rules, first match wins, ahead of the built-in ones." json:"histograms,omitempty"`
}

Metrics: export timing and how histograms aggregate.

type NATS

type NATS struct {
	URL   Secret `desc:"Server URL, or comma-separated URLs; empty: without NATS." json:"url,omitempty"`
	Creds Secret `desc:"Content of a .creds file (user JWT and seed)."             json:"creds,omitempty"`
	// User/Password or Nkey authenticate as a user of the server's
	// configuration, without JWT; one of creds, user and password, nkey.
	User     string `desc:"User of the server's configuration, with password; instead of creds."            json:"user,omitempty"`
	Password Secret `desc:"Password of user."                                                               json:"password,omitempty"`
	Nkey     Secret `desc:"User nkey seed (SU...) of the server's configuration; instead of creds or user." json:"nkey,omitempty"`
	TLS      TLS    `desc:"TLS of the connection."                                                          json:"tls"`
	// InboxPrefix replaces _INBOX for the connection's reply subjects
	// (requests, JetStream API calls).
	InboxPrefix string `` /* 132-byte string literal not displayed */
	// Bound of a Publish whose context has no deadline.
	PublishTimeout time.Duration `desc:"Bound of a publish whose context has no deadline." json:"publish_timeout" schemapb:"default=5s"`
	NATSConnection

	// Retention of the service's events.
	MaxAge time.Duration `desc:"Retention of the service's events; 0: unlimited." json:"max_age" schemapb:"default=168h"`
	// Size of the event stream in bytes; the oldest events go first.
	MaxBytes int64 `` /* 127-byte string literal not displayed */
	// Replicas of the streams the process creates: both of its own and a
	// missing stream it subscribes to (JetStream cluster).
	Replicas int64 `` /* 185-byte string literal not displayed */
	// Window in which a repeated publish (same ce-id) is dropped; at most
	// max_age.
	DedupWindow time.Duration `desc:"Window in which a repeated publish (same ce-id) is dropped; at most max_age." json:"dedup_window" schemapb:"default=2m"`
	// Retention of the dead letters of the service's reactors.
	DLQMaxAge time.Duration `desc:"Retention of the dead letters of the service's reactors; 0: unlimited." json:"dlq_max_age" schemapb:"default=720h"`
}

NATS connection and the streams the service owns: its events bp_<service> (applied when a service that declares events starts) and its dead letters bp_dlq_<service> (applied when its reactors start). Zero max_age, max_bytes or dlq_max_age mean unlimited.

func (NATS) Enabled

func (n NATS) Enabled() bool

Enabled reports whether NATS is configured.

type NATSConnection added in v0.6.86

type NATSConnection struct {
	ConnectTimeout  time.Duration `desc:"Bound of establishing the connection."                           json:"connect_timeout"  schemapb:"default=2s;gt=0"`
	ReconnectWait   time.Duration `desc:"Pause between reconnection attempts."                            json:"reconnect_wait"   schemapb:"default=2s;gt=0"`
	ReconnectJitter time.Duration `desc:"Random extra pause, so clients do not reconnect all at once."    json:"reconnect_jitter" schemapb:"default=1s;gte=0"`
	PingInterval    time.Duration `desc:"How often the client pings the server."                          json:"ping_interval"    schemapb:"default=2m;gt=0"`
	MaxPingsOut     int64         `desc:"Unanswered pings after which the connection is considered lost." json:"max_pings_out"    schemapb:"default=2;gt=0"`
	// ReconnectBuffer is what a publish may buffer while reconnecting;
	// 0: nothing, a publish fails while disconnected.
	ReconnectBuffer  int64         `` /* 150-byte string literal not displayed */
	JetStreamTimeout time.Duration `` /* 150-byte string literal not displayed */
}

NATSConnection is how a NATS connection behaves, the same for the SDK's bus and infra/nats: explicit values, never derived from the node. A zero field of a section built by hand reads its default (Default*).

func (NATSConnection) Resolved added in v0.6.86

func (c NATSConnection) Resolved() NATSConnection

Resolved is the connection with every zero field at its default; the jitter keeps an explicit zero only when the wait was set too.

type Option

type Option func(*settings)

Option configures Load and Open.

func BlockDefaults added in v0.6.35

func BlockDefaults(values map[string]any) Option

BlockDefaults are Defaults of the SDK block, relative to it ("server": {...}) whatever key the configuration embeds it under.

func ConsulBackoff

func ConsulBackoff(minDelay, maxDelay time.Duration) Option

ConsulBackoff bounds the backoff between retries of an unreachable Consul (default 1s..30s).

func Defaults added in v0.6.35

func Defaults(values map[string]any) Option

Defaults are the service's own defaults, in the configuration's JSON shape (durations as strings, "30s"): a layer above the schema's defaults and below the file, so the file, the environment and Consul override them. Later calls merge over earlier ones.

func EnvPrefix

func EnvPrefix(prefix string) Option

EnvPrefix replaces the derived prefix <SERVICE>_.

func File

func File(path string) Option

File reads this file (JSON or YAML by extension) instead of BACKPLANE_CONFIG_FILE.

func Service

func Service(name string) Option

Service names the service when build.Service is not stamped.

func Source

func Source(sources ...xconf.Source) Option

Source appends layers above file and environment, below Consul KV, in order.

func WithRemote

func WithRemote(factory RemoteFactory) Option

WithRemote installs a remote configuration driver. The runtime restricts it to Live fields and preserves its last valid values during an outage.

func WithoutConsul

func WithoutConsul() Option

WithoutConsul keeps Open off Consul KV even when the block names it.

func WithoutEnv

func WithoutEnv() Option

WithoutEnv disables the environment layer.

func WithoutFile

func WithoutFile() Option

WithoutFile disables the file layer.

type RemoteFactory

type RemoteFactory func(Backplane, string) (RemoteSource, error)

RemoteFactory creates the remote layer after file and environment are loaded.

type RemoteSource

type RemoteSource interface {
	xconf.Source
	LastRevision() uint64
}

RemoteSource is a watched configuration layer carrying a console revision.

type Runtime

type Runtime[C any] struct {
	// contains filtered or unexported fields
}

Runtime is a loaded, live configuration. Value is stable for the life of the runtime: static fields never change, Live fields change in place.

func Open

func Open[C Backplaner](ctx context.Context, opts ...Option) (*Runtime[C], error)

Open loads the configuration and keeps it live: Consul KV (named by the embedded Backplane block) overrides Live fields only. The Consul layer is resilient: unreachable at start it is empty, failing later it keeps its last values; Degraded reports it and the layer recovers on its own. A required Live value that only Consul holds keeps Open waiting until Consul answers or ctx ends. The runtime outlives ctx; Close it when done.

Every Validator in C (C itself or any section, value or pointer receiver) runs on the loaded configuration — its error fails Open — and on every live update: an update it rejects is not applied, and the instance state reports the error and the rejected revision.

func (*Runtime[C]) Close

func (r *Runtime[C]) Close() error

Close stops watching; safe to call more than once.

func (*Runtime[C]) Degraded

func (r *Runtime[C]) Degraded() error

Degraded reports why the Consul layer is stale or empty; nil when healthy or not configured.

func (*Runtime[C]) OnApplied added in v0.6.76

func (r *Runtime[C]) OnApplied(fn func(revision uint64))

OnApplied calls fn with the revision after every applied update of the Live fields, once their own watchers ran; a rejected update calls nothing.

func (*Runtime[C]) Revision added in v0.6.76

func (r *Runtime[C]) Revision() uint64

Revision is the console revision the applied Live values come from: the same on every replica, a new one for every save, including a rollback or a save that restores earlier values; 0 without Consul or before the first save.

func (*Runtime[C]) Value

func (r *Runtime[C]) Value() *C

Value is the configuration. The pointer is stable; Live fields update in place.

type Seal added in v0.6.51

type Seal struct {
	// Key seals and opens: base64 of 32 random bytes (seal.GenerateKey).
	Key Secret `desc:"Active key: base64 of 32 random bytes; seals and opens." json:"key,omitempty"`
	// Previous keys only open: comma-separated, while values are rewrapped.
	Previous Secret `desc:"Previous keys, comma-separated: they only open, during rotation." json:"previous,omitempty"`
	// Vault seals instead of key when its addr is set; key and previous
	// then only open what they sealed before.
	Vault SealVault `desc:"Vault Transit: when set it seals, the keys only open." json:"vault"`
}

Seal is the section of a sealer (pkg/backplane/seal): its AES-256-GCM keys, or Vault Transit.

func (Seal) Enabled added in v0.6.51

func (s Seal) Enabled() bool

Enabled reports whether the section seals: a key or a vault is set.

func (Seal) Keys added in v0.6.51

func (s Seal) Keys() ([][]byte, error)

Keys are the decoded keys, the active one first (none when key is empty).

func (Seal) Validate added in v0.6.51

func (s Seal) Validate() error

Validate checks what is set: the keys parse, a vault is complete. An empty section passes (an optional one is off); a sealer refuses it.

type SealVault added in v0.6.51

type SealVault struct {
	// Addr is Vault's URL; empty: no Vault, the section's keys seal.
	Addr  string `desc:"Vault URL, e.g. https://vault:8200; empty: the section's keys seal." json:"addr,omitempty"`
	Token Secret `desc:"Token with datakey, decrypt and rewrap on the key."                  json:"token,omitempty"`
	// Key is the Transit key's name (type aes256-gcm96).
	Key       string        `desc:"Name of the Transit key."                     json:"key,omitempty"`
	Mount     string        `desc:"Mount path of the Transit engine."            json:"mount"               schemapb:"default=transit"`
	Namespace string        `desc:"Vault Enterprise namespace; empty: the root." json:"namespace,omitempty"`
	TLS       TLS           `desc:"TLS of the connection to Vault."              json:"tls"`
	Timeout   time.Duration `desc:"Bound of one call to Vault."                  json:"timeout"             schemapb:"default=10s"`
}

SealVault is the Transit engine of a HashiCorp Vault (or OpenBao): the key never leaves it. Every Seal takes a fresh data key from Transit and keeps it wrapped next to the value; Open has Transit unwrap it.

Give the sealer a Transit key of its own and grant no one encrypt on it: whoever can encrypt with the key can wrap a data key they chose and forge a value Open accepts. The token needs datakey, decrypt and rewrap.

func (SealVault) Enabled added in v0.6.51

func (v SealVault) Enabled() bool

Enabled reports whether Vault seals.

func (SealVault) Validate added in v0.6.51

func (v SealVault) Validate() error

Validate checks a vault that is set; an empty one passes.

type Secret

type Secret string

Secret is a string that never prints: every fmt verb, text, JSON and logs show "***". The schema marks it secret, so the console and the instance state mask it too. fmt cannot see Secrets in unexported struct fields printed with %v: keep them exported or never print the struct.

func (Secret) Format

func (Secret) Format(f fmt.State, _ rune)

Format masks the value for every verb.

func (Secret) GoString

func (Secret) GoString() string

GoString masks the value.

func (Secret) MarshalJSON

func (Secret) MarshalJSON() ([]byte, error)

MarshalJSON masks the value.

func (Secret) MarshalText

func (Secret) MarshalText() ([]byte, error)

MarshalText masks the value (slog text, YAML, XML).

func (Secret) Reveal

func (s Secret) Reveal() string

Reveal returns the value.

func (Secret) SchemaField

func (Secret) SchemaField(f *sp.Schema_Field) error

SchemaField marks the field secret.

func (Secret) SchemaInner

func (Secret) SchemaInner() reflect.Type

SchemaInner makes the field a plain string in the schema (MarshalJSON would otherwise turn it into a JSON field).

func (Secret) String

func (Secret) String() string

String masks the value.

type Server

type Server struct {
	ReadHeaderTimeout time.Duration `desc:"HTTP: time to read the request headers."               json:"read_header_timeout" schemapb:"default=10s"`
	IdleTimeout       time.Duration `desc:"HTTP: keep-alive connection idle this long is closed." json:"idle_timeout"        schemapb:"default=2m"`
	MaxHeaderBytes    int64         `desc:"HTTP: largest request headers, in bytes."              json:"max_header_bytes"    schemapb:"default=1048576;gte=1"`
	// gRPC: largest message received.
	GRPCMaxRecvMsgSize int64 `desc:"gRPC: largest message received, in bytes." json:"grpc_max_recv_msg_size" schemapb:"default=4194304;gte=1"`
	// gRPC: largest message sent; 0: unlimited (grpc-go's default).
	GRPCMaxSendMsgSize int64 `desc:"gRPC: largest message sent, in bytes; 0: unlimited." json:"grpc_max_send_msg_size" schemapb:"default=0;gte=0"`
	// gRPC: concurrent streams per connection; 0: unlimited.
	GRPCMaxConcurrentStreams int64 `` /* 138-byte string literal not displayed */
	// gRPC: the server pings a connection idle this long (long bidi streams
	// behind NAT and load balancers that drop quiet connections).
	GRPCKeepaliveTime time.Duration `` /* 171-byte string literal not displayed */
	// gRPC: how long the server waits for the ping's answer before closing.
	GRPCKeepaliveTimeout time.Duration `` /* 151-byte string literal not displayed */
	// gRPC: a connection without streams this long is closed (GOAWAY);
	// 0: never.
	GRPCMaxConnectionIdle time.Duration `` /* 141-byte string literal not displayed */
	// gRPC: a connection this old is closed (GOAWAY) so clients reconnect
	// and rebalance; 0: never.
	GRPCMaxConnectionAge time.Duration `` /* 158-byte string literal not displayed */
	// gRPC: how long streams of a connection past its age may finish; 0:
	// as long as they take.
	GRPCMaxConnectionAgeGrace time.Duration `` /* 160-byte string literal not displayed */
	// gRPC: minimum interval of client keepalive pings; some clients ping more
	// often than grpc-go's 5m default allows.
	GRPCKeepaliveMinTime time.Duration `` /* 152-byte string literal not displayed */
	// gRPC: accept keepalive pings on connections without streams.
	GRPCPermitWithoutStream bool `desc:"gRPC: accept keepalive pings on connections without streams." json:"grpc_permit_without_stream" schemapb:"default=true"`
}

Server limits, applied to the public and platform listeners.

type Shutdown

type Shutdown struct {
	Timeout time.Duration `desc:"Whole stop budget: drain + listeners + reserve at most." json:"timeout" schemapb:"default=25s"`
	// Time for load balancers to notice the instance left before its
	// listeners close.
	Drain time.Duration `desc:"Time for load balancers to notice the instance left before its listeners close." json:"drain" schemapb:"default=3s"`
	// Longest the listeners drain; then open streams are cut.
	Listeners time.Duration `desc:"Longest the listeners drain; then open streams are cut." json:"listeners" schemapb:"default=10s"`
	// Kept for the author's tree, dependencies and telemetry after the
	// listeners: drain + listeners + reserve <= timeout.
	Reserve time.Duration `` /* 126-byte string literal not displayed */
}

Shutdown of the instance: readiness drops, Consul deregisters, then after Drain the listeners stop accepting and in-flight work finishes; everything within Timeout. Keep terminationGracePeriodSeconds above Timeout.

type TLS

type TLS struct {
	Enabled    bool   `` /* 132-byte string literal not displayed */
	CA         string `desc:"PEM of the CA certificates to trust; empty: the system pool."            json:"ca,omitempty"`
	Cert       string `desc:"PEM of the client certificate; goes together with key."                  json:"cert,omitempty"`
	Key        Secret `desc:"PEM of the client certificate's private key."                            json:"key,omitempty"`
	ServerName string `desc:"Name the server certificate is checked against; empty: the host dialed." json:"server_name,omitempty"`
	// Development only.
	InsecureSkipVerify bool `desc:"Skip verification of the server certificate. Development only." json:"insecure_skip_verify" schemapb:"default=false"`
}

TLS of a client connection. PEM contents, not paths: they come from secrets like any other value. Empty CA means the system pool.

func (TLS) ClientConfig

func (t TLS) ClientConfig() (*tls.Config, error)

ClientConfig is the client TLS configuration of t — what the SDK's Consul, NATS and Temporal connections use; nil when TLS is disabled. An empty CA is the system pool, an empty ServerName the host dialed; Cert and Key together are the client certificate.

type Telemetry added in v0.6.16

type Telemetry struct {
	Metrics Metrics `desc:"Metric export timing and histogram aggregation." json:"metrics"`
	Traces  Traces  `desc:"Which spans are recorded."                       json:"traces"`
}

Telemetry of the service beyond the standard OTEL_* exporters: BACKPLANE_TELEMETRY_*. Fixed at start.

type Temporal

type Temporal struct {
	Addr      string `desc:"Frontend host:port; empty: without Temporal." json:"addr,omitempty"`
	Namespace string `desc:"Temporal namespace."                          json:"ns"             schemapb:"default=default"`
	TLS       TLS    `desc:"TLS of the connection."                       json:"tls"`
	// Temporal Cloud API key.
	APIKey Secret `desc:"Temporal Cloud API key." json:"api_key,omitempty"`
	// First dial attempt; later attempts run in the background.
	DialTimeout time.Duration `desc:"Bound of the first dial; later attempts run in the background." json:"dial_timeout" schemapb:"default=2s"`
	TemporalConnection
	// Deadline of a hook call whose context and declaration set none.
	HookTimeout time.Duration `desc:"Deadline of a hook call whose context and declaration set none." json:"hook_timeout" schemapb:"default=30s"`
	Worker      Worker        `desc:"Worker on the service's task queue."                             json:"worker"`
	// Encryption of the payloads in workflow history; empty: off. Every
	// service of the installation and backplane need the same.
	Encryption Seal `` /* 147-byte string literal not displayed */
	// RequireEncryption refuses payloads that are not sealed: on once no
	// run from before encryption is left.
	RequireEncryption bool `` /* 155-byte string literal not displayed */
}

Temporal connection. Field is `ns`: `namespace` is a CEL reserved word.

func (Temporal) Enabled

func (t Temporal) Enabled() bool

Enabled reports whether Temporal is configured.

type TemporalConnection added in v0.6.86

type TemporalConnection struct {
	KeepAliveTime        time.Duration `` /* 127-byte string literal not displayed */
	KeepAliveTimeout     time.Duration `` /* 127-byte string literal not displayed */
	GetSystemInfoTimeout time.Duration `` /* 126-byte string literal not displayed */
	// MaxPayloadSize bounds a gRPC message in bytes; 0: Temporal's own.
	MaxPayloadSize int64 `desc:"Largest gRPC message in bytes; 0: Temporal's own." json:"max_payload_size" schemapb:"default=0;gte=0"`
	// GRPCCompression is gzip (the Temporal SDK's default) or none.
	GRPCCompression string `desc:"Compression of the gRPC requests: gzip or none." json:"grpc_compression" schemapb:"default=gzip"`
}

TemporalConnection is the gRPC connection to Temporal's frontend, the same for the SDK's client and infra/temporal: explicit values. A zero field of a section built by hand reads its default (Resolved).

func (TemporalConnection) Resolved added in v0.6.86

Resolved is the connection with every zero field at its default.

func (TemporalConnection) Validate added in v0.6.86

func (c TemporalConnection) Validate() error

Validate checks the compression name.

type Traces added in v0.6.27

type Traces struct {
	// always_on, always_off, traceidratio, parentbased_always_on,
	// parentbased_always_off or parentbased_traceidratio.
	Sampler string `` /* 162-byte string literal not displayed */
	// Share of traces the ratio samplers record, 0..1.
	Ratio float64 `desc:"Share of traces the ratio samplers record, 0..1." json:"ratio" schemapb:"default=1;gte=0;lte=1"`
}

Traces: which spans the service records. OTEL_TRACES_SAMPLER does not apply: the sampler is this section's.

type Validator

type Validator interface{ Validate() error }

Validator is implemented by a configuration, or any section of it (the value of a Live field too), that checks itself beyond the schema: Open fails with its error and a live update it rejects is not applied. Value or pointer receiver.

type Worker

type Worker struct {
	// false: this replica runs no worker (activities and the author's
	// workflows are served by replicas that do); it still raises hooks
	// (their own worker runs on every replica) and
	// uses the client.
	Enabled bool `` /* 161-byte string literal not displayed */
	// Activities executing at once.
	MaxConcurrentActivities int64 `desc:"Activities executing at once; 0: Temporal's default." json:"max_concurrent_activities" schemapb:"default=0;gte=0"`
	// Workflow tasks executing at once.
	MaxConcurrentWorkflowTasks int64 `` /* 127-byte string literal not displayed */
	// Pollers of the activity and workflow task queues.
	ActivityPollers int64 `desc:"Pollers of the activity task queue; 0: Temporal's default." json:"activity_pollers" schemapb:"default=0;gte=0"`
	WorkflowPollers int64 `desc:"Pollers of the workflow task queue; 0: Temporal's default." json:"workflow_pollers" schemapb:"default=0;gte=0"`
}

Worker on the service's task queue: an operational setting, the same code runs with any of it. A zero limit is Temporal's default.

Jump to

Keyboard shortcuts

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