gateway

Documentation

Overview

Package gateway embeds Vale in other Go programs: build a Gateway with functional options, call Start to listen on entrypoints and on the admin address from the compiled snapshot, then Stop for graceful shutdown.

Typical wiring combines the built-in default config, merged config providers from WithConfigSourceProviders, or a fixed snapshot via WithStaticSnapshot. Enable optional control-plane clustering with WithClusterFactory, custom runtime middleware with WithMiddlewareRegistry, and metrics with WithMetricsFactory. Pass WithEventBus to share lifecycle events across your app or use Events(); if no bus was passed, Gateway creates an eventx bus and closes it on Stop only when Gateway owned it internally.

Stable low-level import path: github.com/arcgolabs/vale/gateway

Index

• Constants
• type Cluster
• type ClusterFactory
• type ClusterPeer
• type Config
  • func DefaultConfig() Config
• type Gateway
  • func MustNew(options ...Option) *Gateway
  • func New(options ...Option) (*Gateway, error)
  • func NewDefault() (*Gateway, error)
  • func NewFromConfig(cfg Config) (*Gateway, error)
  • func (g *Gateway) Events() provider.EventBus
  • func (g *Gateway) Start(ctx context.Context) error
  • func (g *Gateway) Status() *mapping.Map[string, any]
  • func (g *Gateway) Stop(ctx context.Context) error
• type GroupCluster
• type MetricsFactory
• type Option
  • func WithCertificateStorage(storage certstore.Storage) Option
  • func WithClusterFactory(factory ClusterFactory) Option
  • func WithConfigSourceProviders(configProviders ...provider.ConfigProvider) Option
  • func WithEventBus(bus provider.EventBus) Option
  • func WithFallbackProviders(providers ...provider.SnapshotProvider) Option
  • func WithLogger(logger *slog.Logger) Option
  • func WithMetricsFactory(factory MetricsFactory) Option
  • func WithMiddlewareRegistry(registry *runtime.MiddlewareRegistry) Option
  • func WithObservability(obs observabilityx.Observability) Option
  • func WithSnapshotProvider(snapshotProvider provider.SnapshotProvider) Option
  • func WithStaticConfig(cfgData *config.Config) Option
  • func WithStaticSnapshot(snapshot *runtime.CompiledSnapshot) Option
  • func WithWatch(enabled bool) Option
  • func WithWatchErrorHandler(handler func(error)) Option
• type ReloadDiffView
• type ReloadResourceDiffView
• type ReloadStatusView
• type StaticRuntimeConfigChangedEvent
  • func (e StaticRuntimeConfigChangedEvent) Name() string

Constants

const ClusterGroupCertificates = "certificates"

const ClusterGroupRoutes = "data"

const EventNameStaticRuntimeConfigChanged = "gateway.static_runtime_config.changed"

Types

type Cluster

type Cluster interface {
	IsLeader() bool
	Apply([]byte, time.Duration) error
	Status() *mapping.Map[string, any]
	Peers() (*collectionlist.List[*ClusterPeer], error)
	AddVoter(id string, address string, timeout time.Duration) error
	RemoveServer(id string, timeout time.Duration) error
	Shutdown() error
}

type ClusterFactory

type ClusterFactory func(*slog.Logger) (Cluster, error)

type ClusterPeer

type ClusterPeer = mapping.Map[string, string]

type Config

type Config struct {
	Watch              bool
	Cluster            ClusterFactory
	Logger             *slog.Logger
	EventBus           provider.EventBus
	Observability      observabilityx.Observability
	Provider           provider.SnapshotProvider
	ConfigSource       *collectionlist.List[provider.ConfigProvider]
	CertificateStorage certstore.Storage
	Metrics            MetricsFactory
	Middleware         *runtime.MiddlewareRegistry
	OnWatchError       func(error)
}

Config holds construction-time settings for Gateway.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns defaults used by New/NewFromConfig when paths or watch are unspecified.

type Gateway

type Gateway struct {
	// contains filtered or unexported fields
}

Gateway binds a SnapshotProvider-backed compiled runtime to HTTP servers: snapshot entrypoints plus admin (/admin/* and /metrics). Start and Stop each take a mutex; do not call them concurrently from multiple goroutines.

func MustNew

func MustNew(options ...Option) *Gateway

MustNew is like New but panics on option or construction error.

func New

func New(options ...Option) (*Gateway, error)

New applies options onto DefaultConfig then NewFromConfig.

func NewDefault

func NewDefault() (*Gateway, error)

NewDefault is equivalent to New() with defaults only (single default config path, watch on).

func NewFromConfig

func NewFromConfig(cfg Config) (*Gateway, error)

NewFromConfig validates and fills defaults on cfg then constructs the Gateway. Use New to apply functional options first.

func (*Gateway) Events

func (g *Gateway) Events() provider.EventBus

Events returns the event bus configured with WithEventBus or the internal instance.

func (*Gateway) Start

func (g *Gateway) Start(ctx context.Context) error

Start loads the first snapshot, starts health checks, optionally watches for updates, and listens on snapshot entrypoints and admin address.

func (*Gateway) Status

func (g *Gateway) Status() *mapping.Map[string, any]

Status returns a coarse snapshot-only map (started flag, counts, and cluster status when enabled).

func (*Gateway) Stop

func (g *Gateway) Stop(ctx context.Context) error

Stop shuts down watchers, health checks, all HTTP servers, cluster if enabled; closes the event bus only when Gateway created it.

type GroupCluster

type GroupCluster interface {
	IsGroupLeader(group string) bool
	ApplyGroup(group string, data []byte, timeout time.Duration) error
	GroupPeers(group string) (*collectionlist.List[*ClusterPeer], error)
	AddGroupVoter(group string, id string, address string, timeout time.Duration) error
	RemoveGroupServer(group string, id string, timeout time.Duration) error
}

type MetricsFactory

type MetricsFactory func(enabled bool, logger *slog.Logger) runtime.MetricsRecorder

type Option

type Option func(*Config) error

Option configures Config when passed to New. Return a non-nil error from a custom Option to fail construction.

func WithCertificateStorage

func WithCertificateStorage(storage certstore.Storage) Option

func WithClusterFactory

func WithClusterFactory(factory ClusterFactory) Option

func WithConfigSourceProviders

func WithConfigSourceProviders(configProviders ...provider.ConfigProvider) Option

func WithEventBus

func WithEventBus(bus provider.EventBus) Option

func WithFallbackProviders

func WithFallbackProviders(providers ...provider.SnapshotProvider) Option

func WithLogger

func WithLogger(logger *slog.Logger) Option

func WithMetricsFactory

func WithMetricsFactory(factory MetricsFactory) Option

func WithMiddlewareRegistry

func WithMiddlewareRegistry(registry *runtime.MiddlewareRegistry) Option

func WithObservability

func WithObservability(obs observabilityx.Observability) Option

func WithSnapshotProvider

func WithSnapshotProvider(snapshotProvider provider.SnapshotProvider) Option

func WithStaticConfig

func WithStaticConfig(cfgData *config.Config) Option

func WithStaticSnapshot

func WithStaticSnapshot(snapshot *runtime.CompiledSnapshot) Option

func WithWatch

func WithWatch(enabled bool) Option

func WithWatchErrorHandler

func WithWatchErrorHandler(handler func(error)) Option

type ReloadDiffView

type ReloadDiffView struct {
	Routes    ReloadResourceDiffView `json:"routes"`
	Services  ReloadResourceDiffView `json:"services"`
	Endpoints ReloadResourceDiffView `json:"endpoints"`
}

type ReloadResourceDiffView

type ReloadResourceDiffView struct {
	Added   []string `json:"added"`
	Removed []string `json:"removed"`
	Changed []string `json:"changed"`
}

type ReloadStatusView

type ReloadStatusView struct {
	State        string         `json:"state"`
	LastReload   time.Time      `json:"last_reload"`
	LastError    string         `json:"last_error,omitempty"`
	Fingerprint  string         `json:"fingerprint,omitempty"`
	BuiltAt      time.Time      `json:"built_at"`
	Routes       int            `json:"routes"`
	Services     int            `json:"services"`
	StaticFields []string       `json:"static_fields,omitempty"`
	Diff         ReloadDiffView `json:"diff"`
}

type StaticRuntimeConfigChangedEvent

type StaticRuntimeConfigChangedEvent struct {
	Fields *collectionlist.List[string]
}

StaticRuntimeConfigChangedEvent is emitted when a hot-reloaded snapshot changes settings that are bound to process lifecycle resources and require restart.

func (StaticRuntimeConfigChangedEvent) Name

func (e StaticRuntimeConfigChangedEvent) Name() string