component

package
v0.0.4 Latest Latest
Warning

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

 Go to latest Published: Aug 31, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package component binds typed local or remote providers to frozen topology.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidControlledEpochRuntime reports incomplete lifecycle wiring.
	ErrInvalidControlledEpochRuntime = errors.New(
		"component: invalid controlled epoch runtime",
	)
	// ErrControlledEpochRuntimeStarted reports a repeated Start call.
	ErrControlledEpochRuntimeStarted = errors.New(
		"component: controlled epoch runtime already started",
	)
)
View Source 
var (
	// ErrInvalidEpochRuntime reports an incomplete builder, name, snapshot, or
	// returned Runtime.
	ErrInvalidEpochRuntime = errors.New("component: invalid epoch runtime")
	// ErrEpochRuntimeClosed reports staging, promotion, or acquisition after
	// shutdown has begun.
	ErrEpochRuntimeClosed = errors.New("component: epoch runtime closed")
	// ErrEpochNotStaged reports promotion or draining of an unknown epoch.
	ErrEpochNotStaged = errors.New("component: epoch not staged")
)
View Source 
var (
	// ErrInvalidFactory reports a nil factory or nil constructed provider.
	ErrInvalidFactory = errors.New("component: invalid provider factory")
	// ErrProviderFactory reports a failed or panicking provider factory.
	ErrProviderFactory = errors.New("component: provider factory failed")
	// ErrProviderClose reports one or more failed provider shutdown hooks.
	ErrProviderClose = errors.New("component: provider close failed")
)
View Source 
var (
	// ErrInvalidRuntime reports a nil runtime, provider, or component identity.
	ErrInvalidRuntime = errors.New("component: invalid runtime")
	// ErrRuntimeFrozen reports registration or refreezing after Freeze.
	ErrRuntimeFrozen = errors.New("component: runtime frozen")
	// ErrRuntimeNotFrozen reports Bind before Freeze.
	ErrRuntimeNotFrozen = errors.New("component: runtime not frozen")
	// ErrRuntimeActivating reports mutation while factories are being built.
	ErrRuntimeActivating = errors.New("component: runtime activating")
	// ErrRuntimeClosed reports use after provider shutdown.
	ErrRuntimeClosed = errors.New("component: runtime closed")
	// ErrDuplicateBinding reports a repeated provider for one mode and target.
	ErrDuplicateBinding = errors.New("component: duplicate binding")
	// ErrMissingBinding reports that the selected mode has no provider.
	ErrMissingBinding = errors.New("component: missing binding")
	// ErrBindingType reports that the selected provider does not implement T.
	ErrBindingType = errors.New("component: binding type mismatch")
)

Functions

func RegisterLocalFactory 

func RegisterLocalFactory[T any](
	r *Runtime,
	component topology.ComponentID,
	factory Factory[T],
) error

RegisterLocalFactory registers one typed local constructor before activation.

func RegisterRemoteFactory 

func RegisterRemoteFactory[T any](
	r *Runtime,
	component topology.ComponentID,
	factory Factory[T],
) error

RegisterRemoteFactory registers one typed remote constructor before activation.

Types

type CloseFunc 

type CloseFunc func(context.Context) error

CloseFunc releases one factory-owned provider.

type ControlledEpochRuntime 

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

ControlledEpochRuntime bootstraps one last-good epoch, then watches updates. It implements the App Component contract and owns Runtime shutdown.

func NewControlledEpochRuntime 

func NewControlledEpochRuntime(
	config ControlledEpochRuntimeConfig,
) (*ControlledEpochRuntime, error)

NewControlledEpochRuntime validates and freezes control-plane wiring.

func (*ControlledEpochRuntime) Acquire 

func (cr *ControlledEpochRuntime) Acquire(
	ctx context.Context,
) (*EpochLease, error)

Acquire pins the active topology and component providers for one call.

func (*ControlledEpochRuntime) AcquireKey 

func (cr *ControlledEpochRuntime) AcquireKey(
	ctx context.Context,
	routingKey string,
) (*EpochLease, error)

AcquireKey pins the epoch selected for one stable weighted routing key.

func (*ControlledEpochRuntime) Dependencies 

func (cr *ControlledEpochRuntime) Dependencies() []string

Dependencies returns an independent App component dependency list.

func (*ControlledEpochRuntime) HealthCheck 

func (cr *ControlledEpochRuntime) HealthCheck(
	ctx context.Context,
) health.Result

HealthCheck reports serving last-good as healthy while retaining degraded detail in Status and Ops.

func (*ControlledEpochRuntime) Name 

func (cr *ControlledEpochRuntime) Name() string

Name returns the stable App component identity.

func (*ControlledEpochRuntime) Start 

func (cr *ControlledEpochRuntime) Start(ctx context.Context) error

Start synchronously applies the initial candidate before starting Watch.

func (*ControlledEpochRuntime) Status 

func (cr *ControlledEpochRuntime) Status() ControlledEpochStatus

Status returns revision, degraded state and process-local active epoch.

func (*ControlledEpochRuntime) Stop 

func (cr *ControlledEpochRuntime) Stop(ctx context.Context) error

Stop ends Watch, drains every epoch and releases Source-owned resources.

type ControlledEpochRuntimeConfig 

type ControlledEpochRuntimeConfig struct {
	Name          string
	Dependencies  []string
	Source        control.Source
	Runtime       *EpochRuntime
	Verifier      control.Verifier
	AllowUnsigned bool
	ApplyTimeout  time.Duration
	DrainTimeout  time.Duration
	MinBackoff    time.Duration
	MaxBackoff    time.Duration
	Sleep         control.Sleeper
	Observer      control.Observer
}

ControlledEpochRuntimeConfig wires a revisioned Source to an EpochRuntime.

type ControlledEpochStatus 

type ControlledEpochStatus struct {
	Control     control.Status
	ActiveEpoch uint64
	Running     bool
	Stopped     bool
}

ControlledEpochStatus is a bounded, payload-free lifecycle snapshot.

type EpochEvent 

type EpochEvent struct {
	Kind   EpochEventKind
	Epoch  uint64
	State  topology.EpochState
	Failed bool
}

EpochEvent contains lifecycle metadata but never provider values or request payloads.

type EpochEventKind 

type EpochEventKind string

EpochEventKind identifies one bounded epoch lifecycle observation. 

const (
	// EpochEventStage indicates that a new epoch is being staged.
	EpochEventStage EpochEventKind = "stage"
	// EpochEventReady indicates that an epoch became ready.
	EpochEventReady EpochEventKind = "ready"
	// EpochEventDrain indicates that an epoch began draining.
	EpochEventDrain EpochEventKind = "drain"
	// EpochEventAcquire indicates that a lease was acquired.
	EpochEventAcquire EpochEventKind = "acquire"
	// EpochEventRelease indicates that a lease was released.
	EpochEventRelease EpochEventKind = "release"
	// EpochEventClose indicates that an epoch was closed.
	EpochEventClose EpochEventKind = "close"
)

type EpochLease 

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

EpochLease pins one Runtime and Snapshot until Release.

func (*EpochLease) Epoch 

func (lease *EpochLease) Epoch() uint64

Epoch returns the fixed topology epoch.

func (*EpochLease) Release 

func (lease *EpochLease) Release()

Release idempotently releases the pinned epoch.

func (*EpochLease) Runtime 

func (lease *EpochLease) Runtime() *Runtime

Runtime returns the fixed component Runtime.

func (*EpochLease) Snapshot 

func (lease *EpochLease) Snapshot() topology.Snapshot

Snapshot returns the fixed topology snapshot.

type EpochObserver 

type EpochObserver interface {
	ObserveEpoch(context.Context, EpochEvent)
}

EpochObserver receives epoch, lease, and provider-close observations.

type EpochObserverFunc 

type EpochObserverFunc func(context.Context, EpochEvent)

EpochObserverFunc adapts a function to EpochObserver.

func (EpochObserverFunc) ObserveEpoch 

func (fn EpochObserverFunc) ObserveEpoch(
	ctx context.Context,
	event EpochEvent,
)

ObserveEpoch implements EpochObserver.

type EpochRuntime 

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

EpochRuntime owns one frozen component Runtime per topology epoch.

Stage constructs without changing traffic. Ready atomically changes the epoch used by new Acquire calls. Drain waits for pinned leases before releasing factory-owned providers.

func NewEpochRuntime 

func NewEpochRuntime(config EpochRuntimeConfig) (*EpochRuntime, error)

NewEpochRuntime validates and constructs an empty epoch runtime.

func (*EpochRuntime) Acquire 

func (er *EpochRuntime) Acquire(
	ctx context.Context,
) (*EpochLease, error)

Acquire pins the current Ready Runtime for one logical call.

func (*EpochRuntime) AcquireKey 

func (er *EpochRuntime) AcquireKey(
	ctx context.Context,
	routingKey string,
) (*EpochLease, error)

AcquireKey pins the Runtime chosen for a stable weighted routing key.

func (*EpochRuntime) Activate 

func (er *EpochRuntime) Activate(
	ctx context.Context,
	snapshot topology.Snapshot,
) error

Activate constructs, stages, and promotes one snapshot atomically with respect to other epoch lifecycle changes.

func (*EpochRuntime) Active 

func (er *EpochRuntime) Active() (uint64, bool)

Active returns the epoch currently used by new Acquire calls.

func (*EpochRuntime) Dependencies 

func (er *EpochRuntime) Dependencies() []string

Dependencies implements the App DependencyProvider contract.

func (*EpochRuntime) Drain 

func (er *EpochRuntime) Drain(
	ctx context.Context,
	epoch uint64,
) error

Drain prevents new leases for an old Ready epoch, waits for every pinned lease, and closes its factory-owned providers.

func (*EpochRuntime) Drainable 

func (er *EpochRuntime) Drainable() []uint64

Drainable returns zero-weight Ready epochs eligible for rollout cleanup.

func (*EpochRuntime) Name 

func (er *EpochRuntime) Name() string

Name implements the App Component contract.

func (*EpochRuntime) Ready 

func (er *EpochRuntime) Ready(epoch uint64) (uint64, error)

Ready promotes one staged epoch and returns the previously active epoch.

func (*EpochRuntime) ReadyContext 

func (er *EpochRuntime) ReadyContext(
	ctx context.Context,
	epoch uint64,
) (uint64, error)

ReadyContext promotes one staged epoch while honoring caller cancellation.

func (*EpochRuntime) Stage 

func (er *EpochRuntime) Stage(
	ctx context.Context,
	snapshot topology.Snapshot,
) error

Stage constructs and activates one immutable Runtime without changing the active traffic epoch.

func (*EpochRuntime) Start 

func (er *EpochRuntime) Start(ctx context.Context) error

Start activates the configured initial snapshot for App startup.

func (*EpochRuntime) State 

func (er *EpochRuntime) State(
	epoch uint64,
) (topology.EpochState, bool)

State returns the topology lifecycle state for one epoch.

func (*EpochRuntime) Stop 

func (er *EpochRuntime) Stop(ctx context.Context) error

Stop implements the App Component contract and is safely retryable after a context timeout. It rejects new work, drains every Ready epoch, discards staging epochs, and closes stopped runtimes newest-first.

type EpochRuntimeConfig 

type EpochRuntimeConfig struct {
	Name         string
	Dependencies []string
	Initial      topology.Snapshot
	Build        RuntimeBuilder
	Observer     EpochObserver
}

EpochRuntimeConfig configures an epoch manager and optional App component.

type Factory 

type Factory[T any] func(context.Context) (T, CloseFunc, error)

Factory is a typed lazy provider constructor.

The Runtime owns a non-nil CloseFunc after a successful construction and calls it exactly once during rollback or Runtime.Close.

type ProviderFactory 

type ProviderFactory func(context.Context) (any, CloseFunc, error)

ProviderFactory is the type-erased constructor stored by Runtime.

type Ref 

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

Ref is an immutable typed component reference.

Get always returns the provider selected when Bind captured the topology binding. A Ref never re-resolves against a newer plan epoch.

func Bind 

func Bind[T any](
	r *Runtime,
	source topology.ComponentID,
	target topology.ComponentID,
) (Ref[T], error)

Bind resolves one declared edge and returns only its selected typed provider.

func (Ref[T]) Binding 

func (reference Ref[T]) Binding() topology.Binding

Binding returns the frozen topology decision.

func (Ref[T]) Epoch 

func (reference Ref[T]) Epoch() uint64

Epoch returns the frozen plan epoch for diagnostics.

func (Ref[T]) Get 

func (reference Ref[T]) Get() T

Get returns the frozen typed provider.

func (Ref[T]) Mode 

func (reference Ref[T]) Mode() topology.BindingMode

Mode returns the frozen local or remote dispatch mode.

func (Ref[T]) PlanHash 

func (reference Ref[T]) PlanHash() string

PlanHash returns the frozen canonical plan identity for diagnostics.

type Runtime 

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

Runtime registers providers during construction and freezes exactly once.

It does not watch a topology Manager. Loading a new epoch requires a new Runtime owned by the new process epoch.

func NewRuntime 

func NewRuntime() *Runtime

NewRuntime creates an unfrozen provider registry.

func (*Runtime) Activate 

func (r *Runtime) Activate(
	ctx context.Context,
	snapshot topology.Snapshot,
) error

Activate builds only providers selected by snapshot and freezes Runtime.

Selected factories are de-duplicated by component and binding mode. A failed activation closes every constructed provider in reverse order and leaves Runtime mutable for a retry.

func (*Runtime) Close 

func (r *Runtime) Close(ctx context.Context) error

Close releases factory-owned providers in reverse construction order.

Directly registered providers remain caller-owned. Repeated Close calls are idempotent.

func (*Runtime) Freeze 

func (r *Runtime) Freeze(snapshot topology.Snapshot) error

Freeze captures one activated topology Snapshot for the Runtime lifetime.

func (*Runtime) RegisterLocal 

func (r *Runtime) RegisterLocal(
	component topology.ComponentID,
	provider any,
) error

RegisterLocal registers one in-process provider before Freeze.

func (*Runtime) RegisterLocalFactory 

func (r *Runtime) RegisterLocalFactory(
	component topology.ComponentID,
	factory ProviderFactory,
) error

RegisterLocalFactory registers one type-erased local constructor.

func (*Runtime) RegisterRemote 

func (r *Runtime) RegisterRemote(
	component topology.ComponentID,
	provider any,
) error

RegisterRemote registers one remote provider before Freeze.

func (*Runtime) RegisterRemoteFactory 

func (r *Runtime) RegisterRemoteFactory(
	component topology.ComponentID,
	factory ProviderFactory,
) error

RegisterRemoteFactory registers one type-erased remote constructor.

type RuntimeBuilder 

type RuntimeBuilder func(
	context.Context,
	topology.Snapshot,
) (*Runtime, error)

RuntimeBuilder creates one mutable Runtime registration set for snapshot.

EpochRuntime calls Runtime.Activate after Build returns. A builder must not freeze or activate the returned Runtime itself.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.