serverlessoperator

package
v0.106.8-alpha.0 Latest Latest
Warning

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

Go to latest
Published: Sep 9, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Overview

Package serverlessoperator is the serverless operator core: it owns (tenant, shard) lease units, polls their endpoints' healthchecks, registers their workflows with the engine through a link, and delivers assigned tasks to the endpoints over signed HTTP. The same core runs out of process (grpclink) and, in a later phase, inside the engine.

Index

Constants

View Source
const (
	DefaultOperatorName                       = "serverless"
	DefaultLinkName                           = "grpc"
	DefaultDefaultSlots                 int32 = 10000
	DefaultDurableSlots                 int32 = 10000
	DefaultLeaseTTL                           = 15 * time.Second
	DefaultHeartbeatInterval                  = 5 * time.Second
	DefaultRebalanceInterval                  = 5 * time.Second
	DefaultShedHysteresis                     = 0.2
	DefaultDrainTimeout                       = 60 * time.Second
	DefaultRoutingRefreshInterval             = 10 * time.Second
	DefaultRoutingFullReloadInterval          = 60 * time.Second
	DefaultHealthcheckTimeout                 = 10 * time.Second
	DefaultHealthcheckConcurrency             = 256
	DefaultHealthcheckTenantConcurrency       = 32
	DefaultHealthcheckApplyTimeout            = 60 * time.Second
	DefaultMaxWorkflowsPerEndpoint            = 200
	DefaultMaxActionsPerEndpoint              = 500
	DefaultMaintenanceConcurrency             = 8
	DefaultLeaseMaxClaimPerTick         int32 = 1024
	DefaultWSMaxFrameBytes              int64 = 4 * 1024 * 1024
	DefaultWSPingInterval                     = 15 * time.Second
	DefaultHealthPort                         = 8080

	// Relay resource limit defaults.
	DefaultWSMaxUpgradeHeaderBytes int64 = 64 * 1024
	DefaultWSMaxQueuedBytes        int64 = 16 * 1024 * 1024
)

Variables

This section is empty.

Functions

func ParseNamespace

func ParseNamespace(actionId string) (uuid.UUID, bool)

ParseNamespace extracts the endpoint namespace from a registered action id of the form <uuid>_<service>:<verb>.

func Run

func Run(ctx context.Context, deps Deps) error

Run starts the leaser, the maintenance loop and the health server and blocks until ctx is done or a loop fails, then shuts down gracefully: release every lease, drain deliveries up to DrainTimeout, close registrations, delete the process row.

Types

type Config

type Config struct {
	// OperatorName is the OperatorService operator name registrations connect as.
	OperatorName string

	// LinkName labels metrics: grpc or engine.
	LinkName string

	DefaultSlots int32
	DurableSlots int32

	// LeaseTTL is how long a process row stays live after a heartbeat.
	LeaseTTL          time.Duration
	HeartbeatInterval time.Duration
	RebalanceInterval time.Duration

	// ShedHysteresis is the fraction above fair share a process tolerates before shedding.
	ShedHysteresis float64

	// DrainTimeout bounds how long in-flight deliveries are awaited when a unit is lost or the
	// process stops.
	DrainTimeout time.Duration

	// RoutingRefreshInterval is the incremental (updated_at based) routing cache refresh
	// cadence; RoutingFullReloadInterval is how often the cache is reloaded in full, which is
	// what drops hard-deleted endpoints.
	RoutingRefreshInterval    time.Duration
	RoutingFullReloadInterval time.Duration

	// HealthcheckTimeout bounds one healthcheck request; HealthcheckConcurrency caps
	// healthchecks process-wide and HealthcheckTenantConcurrency caps them per tenant inside
	// that limit, so one tenant's slow endpoints cannot hold every slot.
	HealthcheckTimeout           time.Duration
	HealthcheckConcurrency       int
	HealthcheckTenantConcurrency int

	// HealthcheckApplyTimeout bounds the application of one changed catalog: the workflow
	// puts, the action delta and the registered_actions write.
	HealthcheckApplyTimeout time.Duration

	// MaxWorkflowsPerEndpoint and MaxActionsPerEndpoint cap what one healthcheck may
	// advertise; a catalog over either cap is refused and the endpoint marked with the error.
	MaxWorkflowsPerEndpoint int
	MaxActionsPerEndpoint   int

	// MaintenanceConcurrency is how many tenants a maintenance pass refreshes at once.
	MaintenanceConcurrency int

	// LeaseMaxClaimPerTick caps how many lease units one rebalance tick claims; the process's
	// share of the claimable units is taken up to this many, in statements of the leaser's
	// claim batch.
	LeaseMaxClaimPerTick int32

	// WSMaxFrameBytes and WSPingInterval configure the durable websocket relay (a later
	// phase); they are carried here so the binary's env binding is complete.
	WSMaxFrameBytes int64
	WSPingInterval  time.Duration

	// HealthPort serves /healthz, /readyz and /metrics. Zero disables the server.
	HealthPort int

	// WSMaxUpgradeHeaderBytes bounds an endpoint's websocket upgrade response head, which is
	// parsed before WSMaxFrameBytes applies.
	WSMaxUpgradeHeaderBytes int64

	// WSMaxQueuedBytes bounds the encoded frames one relay retains for an endpoint that reads
	// slower than the engine answers; crossing it closes the socket with backpressure.
	WSMaxQueuedBytes int64
}

Config holds the knobs shared by the out-of-process binary and the in-engine mode. Zero values are replaced by the defaults below; the binary binds SERVERLESS_OPERATOR_* onto it.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the plan's defaults.

type Deps

type Deps struct {
	Repo       repository.ServerlessRepository
	Link       link.Link
	Encryption encryption.EncryptionService
	Sender     RequestSender
	Logger     *zerolog.Logger
	Version    string
	Hostname   string
	Config     Config
	ProcessId  uuid.UUID
}

Deps is everything Run needs. The binary and the in-engine mode build it differently.

type RequestSender

type RequestSender interface {
	Deliver(ctx context.Context, method, endpoint string, body []byte, headers http.Header) (*safeclient.DeliveryResult, error)
}

RequestSender is the outbound HTTP seam: safeclient.Sender in production, a fake in tests.

Directories

Path Synopsis
Package contract holds the parts of the serverless endpoint contract that are not protobuf messages: header names, the upgrade signature payload, wire constants and the protojson encoding every message travels in.
Package contract holds the parts of the serverless endpoint contract that are not protobuf messages: header names, the upgrade signature payload, wire constants and the protojson encoding every message travels in.
Package durable relays one durable task invocation between the engine, reached through a link.DurableChannel, and a serverless endpoint, reached over an operator-dialed websocket.
Package durable relays one durable task invocation between the engine, reached through a link.DurableChannel, and a serverless endpoint, reached over an operator-dialed websocket.
internal
memrepo
Package memrepo is an in-memory repository.ServerlessRepository for unit tests of the serverless operator core and leaser.
Package memrepo is an in-memory repository.ServerlessRepository for unit tests of the serverless operator core and leaser.
Package lease is the serverless operator's process membership and unit ownership: one heartbeat row per process, fair-share claiming of (tenant, shard) units with FOR UPDATE SKIP LOCKED, shedding above fair share, and a periodic sweep of expired process rows.
Package lease is the serverless operator's process membership and unit ownership: one heartbeat row per process, fair-share claiming of (tenant, shard) units with FOR UPDATE SKIP LOCKED, shedding above fair share, and a periodic sweep of expired process rows.
Package link defines the seam between the serverless operator core and the engine.
Package link defines the seam between the serverless operator core and the engine.
enginelink
Package enginelink is the in-engine Link: a registration is an engine Worker row created and activated in process, an operator-backed dispatcher session that forwards assigned actions, and direct calls into the dispatcher for step events and durable invocations.
Package enginelink is the in-engine Link: a registration is an engine Worker row created and activated in process, an operator-backed dispatcher session that forwards assigned actions, and direct calls into the dispatcher for step events and durable invocations.
grpclink
Package grpclink is the out-of-process Link: registrations are OperatorSessions opened over the engine's OperatorService with a per-tenant API token from a TenantTokenExchange.
Package grpclink is the out-of-process Link: registrations are OperatorSessions opened over the engine's OperatorService with a per-tenant API token from a TenantTokenExchange.

Jump to

Keyboard shortcuts

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