bgservice

Documentation

Overview

Package bgservice is the chassis seam for long-running background services that an overlay registers and the chassis owns — started with the other controllers and drained on shutdown. It mirrors the usage.Sink registry seam: a backend self-registers from its init() and the chassis activates it with a blank import plus a name in the BackgroundServices config. The seam is deliberately generic — no billing/quota/transport vocabulary — so it stays unopinionated; a service reads any backend-specific settings (DSNs, periods, thresholds) from its own env in its constructor.

Index

• func Register(name string, c Constructor)
• type Config
• type Constructor
• type Gate
• type Service
  • func Open(names string, cfg Config) ([]Service, error)

Functions

func Register

func Register(name string, c Constructor)

Register adds a service constructor. Called from a backend package's init().

Types

type Config

type Config struct {
	// Logger is the chassis logger.
	Logger *zap.Logger
	// Gate drives per-tenant admission state (see Gate).
	Gate Gate
	// NodeID is a stable identity for this chassis (FQDN-ish), for attribution.
	NodeID string
}

Config is the generic context a service receives at construction.

type Constructor

type Constructor func(Config) (Service, error)

Constructor builds a Service from resolved config. Called by Open.

type Gate

type Gate interface {
	SetGate(ctx context.Context, slug string, suspended bool, denyStatus int, denyReason string) error
}

Gate is the seam a background service uses to drive per-tenant admission state without touching DB internals. It engages or releases the programmatic gate (the `suspended` column) for a tenant identified by slug, with a caller-supplied deny_reason/deny_status, routing through the chassis' full-row read-modify-write + fleet-emit + reload path. Billing-neutral: the specific meaning rides in deny_reason (e.g. "credit_exhausted").

type Service

type Service interface {
	Start()
	Stop()
}

Service is a long-running background loop the chassis owns. Start launches it (non-blocking); Stop drains it on shutdown. The shape matches the chassis controller contract so a Service plugs into the existing start/stop loops.

func Open

func Open(names string, cfg Config) ([]Service, error)

Open constructs the services named in a comma-separated list (whitespace and empty/"nop" entries ignored). An empty list returns no services — the bundled default, so single-node boots register nothing. An unknown name is a startup error listing what is available (sorted for a stable message).