runtimehost

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package runtimehost hosts the generation manager, leases, retirement scheduling, dispatcher, and serialized reload coordinator for versioned runtime reload.

Index

Constants

View Source 
const DefaultCleanupMaxAttempts = 3

DefaultCleanupMaxAttempts is the startup-fixed cleanup retry budget.

View Source 
const DefaultReloadTimeout = time.Minute

DefaultReloadTimeout is the host-owned reload attempt bound when unset.

View Source 
const RetentionCategoryBudget = "retained_generation_budget"

RetentionCategoryBudget is the safe retention-pressure category when the retained-generation budget would be exceeded (req 10.8-10.10).

Variables

View Source 
var (
	ErrRetentionBlocked         = errors.New("runtimehost: retained-generation budget exhausted")
	ErrHostShuttingDown         = errors.New("runtimehost: host is shutting down")
	ErrNotPrepared              = errors.New("runtimehost: candidate not prepared")
	ErrAlreadyPublished         = errors.New("runtimehost: generation already published")
	ErrAlreadyClosed            = errors.New("runtimehost: generation already closed")
	ErrIllegalTransition        = errors.New("runtimehost: illegal generation lifecycle transition")
	ErrOwnedAlreadyBound        = errors.New("runtimehost: generation owned resources already bound")
	ErrRequestPlaneAlreadyBound = errors.New("runtimehost: generation request plane already bound")
)

Sentinel errors for generation publication and lifecycle (req 10.1, 10.8-10.9).

View Source 
var ErrNoActiveExecutor = errors.New("runtimehost: no active generation executor")

ErrNoActiveExecutor is returned when Execute cannot acquire an active generation executor (host shutting down or empty publication).

Functions

func BindModelViewsIfPresent 

func BindModelViewsIfPresent(ctx context.Context, plane PublishedRequestPlane) context.Context

BindModelViewsIfPresent invokes plane.BindModelViews when plane implements ModelViewBinder; otherwise returns ctx unchanged.

func DataPlaneReady 

func DataPlaneReady(mgr *Manager) bool

DataPlaneReady reports whether a healthy active generation is published. Reload-control failures must not flip this to false while last-good remains active (req 13.1-13.2).

Types

type BackendFactoryKindCounter 

type BackendFactoryKindCounter interface {
	BackendFactoryKindCounts() map[string]int
}

BackendFactoryKindCounter is optionally implemented by published request planes so the coordinator can populate LiveFactoryKinds from active/retained generations (tasks.md Implementation Notes; req 8.8).

type CandidateCompiler 

type CandidateCompiler interface {
	Compile(ctx context.Context, candidate *config.Config, liveFactoryKinds map[string]int) (PublishedRequestPlane, error)
}

CandidateCompiler builds one isolated immutable request-plane candidate. It must not mutate active generations or process-service ownership.

type CleanupPolicy 

type CleanupPolicy struct {
	MaxAttempts int
}

CleanupPolicy bounds post-drain cleanup retries (req 10.12; design Closing→Closing). MaxAttempts <= 0 defaults to DefaultCleanupMaxAttempts.

type Coordinator 

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

Coordinator serializes explicit reload attempts (design Reload Coordinator; req 1.4, 3.x, 11.x, 13.x). It orchestrates the gate, runner, state owner, and observer without directly implementing detailed source/load/classification/compile branches (req 6.4); source is kept only for FixedSourcePath (AbsolutePath), never for reload execution.

func NewCoordinator 

func NewCoordinator(deps CoordinatorDeps) (*Coordinator, error)

NewCoordinator constructs a production serialized reload coordinator.

func (*Coordinator) BeginShutdown 

func (c *Coordinator) BeginShutdown()

BeginShutdown rejects new attempts, cancels the host-owned reload context (including coalesced follow-ups), signals manager shutdown, and prevents late publication (req 1.9, 11.9, 13.7). It does not wait for rollback; callers that must close process services afterward should use Coordinator.WaitForIdle.

func (*Coordinator) FixedSourcePath 

func (c *Coordinator) FixedSourcePath() string

FixedSourcePath is the HTTP-only fixed startup source capability. Paths stay off the canonical Status contract; management adapters map this into transport DTOs only.

func (*Coordinator) Reload 

func (c *Coordinator) Reload(ctx context.Context, trigger sdkreload.Trigger) sdkreload.Result

Reload runs one serialized attempt. API callers receive Busy when an attempt is active; SIGHUP coalesces into at most one pending follow-up (req 11.4-11.6). The attempt uses a host-owned timeout independent of API client cancel (req 12.9).

func (*Coordinator) Status 

func (c *Coordinator) Status() sdkreload.Status

Status returns a bounded safe snapshot (req 13.1-13.2, 14.1, 14.8). The snapshot is secret-safe and must not include filesystem paths. Management adapters that need the fixed startup source should call FixedSourcePath and map it into transport DTOs only (canonical Status stays path-free).

func (*Coordinator) WaitForIdle 

func (c *Coordinator) WaitForIdle(ctx context.Context) error

WaitForIdle blocks until no reload attempt (including coalesced follow-up) is in flight, or until ctx is done. It is safe after Coordinator.BeginShutdown and does not take request-path locks (req 13.7, 15.1).

type CoordinatorDeps 

type CoordinatorDeps struct {
	Source            StableConfigSource
	Loader            EffectiveLoader
	Classify          func(active, candidate *config.EffectiveConfig) ([]configreload.SafeChange, error)
	Compile           CandidateCompiler
	Manager           *Manager
	Timeout           time.Duration
	ActiveEffective   *config.EffectiveConfig
	ActiveSource      *configsource.ActiveSourceVersion
	ActiveSourceOwner *configsource.SourceOwnerSlot
	Observer          *ReloadObserver
}

CoordinatorDeps wires production or test seams for the serialized reload coordinator.

type EffectiveLoader 

type EffectiveLoader interface {
	LoadEffective(ctx context.Context, raw []byte) (*config.EffectiveConfig, error)
}

EffectiveLoader runs the shared strict effective-load pipeline on accepted bytes.

type ExecutorProvider 

type ExecutorProvider interface {
	ExecutorView() lipsdk.ExecutorView
}

ExecutorProvider is optionally implemented by PublishedRequestPlane values so the stable GenerationExecutor can dispatch without importing runtimebundle.

type FuncCompiler 

type FuncCompiler func(ctx context.Context, candidate *config.Config, liveFactoryKinds map[string]int) (PublishedRequestPlane, error)

FuncCompiler adapts a function to CandidateCompiler.

func (FuncCompiler) Compile 

func (f FuncCompiler) Compile(ctx context.Context, candidate *config.Config, liveFactoryKinds map[string]int) (PublishedRequestPlane, error)

Compile implements CandidateCompiler.

type FuncEffectiveLoader 

type FuncEffectiveLoader func(ctx context.Context, raw []byte) (*config.EffectiveConfig, error)

FuncEffectiveLoader adapts a function to EffectiveLoader.

func (FuncEffectiveLoader) LoadEffective 

func (f FuncEffectiveLoader) LoadEffective(ctx context.Context, raw []byte) (*config.EffectiveConfig, error)

LoadEffective implements EffectiveLoader.

type GenLifecycle 

type GenLifecycle uint32
const (
	GenUnspecified GenLifecycle = iota
	GenPreparing
	GenPrepared
	GenActive
	GenRetiring
	GenQuiescing
	GenQuiesced
	GenDrained
	GenClosing
	GenClosed
	GenFailed
)

type Generation 

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

func (*Generation) AttachOwned 

func (g *Generation) AttachOwned(owned OwnedCloser) error

AttachOwned binds generation-owned resources once while preparing/prepared. Lifecycle validation and payload mutation share payloadMu with assignPublish/Discard so a binding cannot commit after publication or after discard has claimed an empty payload.

func (*Generation) AttachRequestPlane 

func (g *Generation) AttachRequestPlane(plane PublishedRequestPlane) error

AttachRequestPlane atomically binds the immutable request-plane publisher as both the served plane and the generation-owned closer while preparing.

func (*Generation) BeginClose 

func (g *Generation) BeginClose() error

func (*Generation) BeginQuiesce 

func (g *Generation) BeginQuiesce() error

func (*Generation) Close 

func (g *Generation) Close() error

func (*Generation) CloseCount 

func (g *Generation) CloseCount() int32

func (*Generation) Discard 

func (g *Generation) Discard() error

func (*Generation) Drained 

func (g *Generation) Drained() <-chan struct{}

func (*Generation) Handler 

func (g *Generation) Handler() http.Handler

Handler returns the bound request-plane handler, or nil when unbound.

func (*Generation) ID 

func (g *Generation) ID() int64

func (*Generation) Label 

func (g *Generation) Label() string

func (*Generation) Lifecycle 

func (g *Generation) Lifecycle() GenLifecycle

func (*Generation) MarkPrepared 

func (g *Generation) MarkPrepared() error

func (*Generation) MarkQuiesced 

func (g *Generation) MarkQuiesced() error

func (*Generation) Refs 

func (g *Generation) Refs() uint32

func (*Generation) RequestPlane 

func (g *Generation) RequestPlane() PublishedRequestPlane

RequestPlane returns the bound immutable request-plane publisher, or nil.

func (*Generation) SetMetaHints 

func (g *Generation) SetMetaHints(h MetaHints)

func (*Generation) Status 

func (g *Generation) Status() Status

func (*Generation) Transition 

func (g *Generation) Transition(to GenLifecycle) error

type GenerationDispatcher 

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

GenerationDispatcher is the stable data-plane http.Handler that binds each request to exactly one active generation lease (req 4.5, 5.1-5.4, 15.1).

It does not buffer or wrap http.ResponseWriter, replace connections, recover panics, or perform config/model lookups. Direct delegation preserves optional ResponseWriter interfaces and the generation handler's middleware stack.

func NewGenerationDispatcher 

func NewGenerationDispatcher(m *Manager) *GenerationDispatcher

NewGenerationDispatcher returns a production dispatcher backed by m.

func (*GenerationDispatcher) ServeHTTP 

func (d *GenerationDispatcher) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP acquires one generation lease, attaches a safe request binding, and delegates to the generation handler. The lease is released exactly once when the handler returns unless ownership was transferred to a pin.

type GenerationExecutor 

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

GenerationExecutor is the stable, process-owned ExecutorView facade. Each Execute acquires the current generation, delegates to that generation's executor, and pins the returned stream until terminal/error/EOF/Close (req 16.12). CancelALeg reaches process-owned cross-generation A-leg state via the active generation executor's shared lifecycle (req 16.13).

func NewGenerationExecutor 

func NewGenerationExecutor(m *Manager) *GenerationExecutor

NewGenerationExecutor returns a stable delegating ExecutorView backed by m.

func (*GenerationExecutor) CancelALeg 

func (e *GenerationExecutor) CancelALeg(ctx context.Context, req lipapi.ALegCancelRequest) error

CancelALeg acquires the current generation and delegates cancellation so the process-owned A-leg lifecycle (shared across generations) is reached.

func (*GenerationExecutor) Execute 

func (e *GenerationExecutor) Execute(ctx context.Context, call *lipapi.Call) (lipapi.EventStream, error)

Execute acquires the active generation, runs the generation executor, and transfers a provider pin onto the returned stream until completion/close.

func (*GenerationExecutor) SetWallClock 

func (e *GenerationExecutor) SetWallClock(clock func() time.Time)

SetWallClock installs an optional wall-clock callback for response metadata.

func (*GenerationExecutor) WallClock 

func (e *GenerationExecutor) WallClock() func() time.Time

WallClock returns the optional wall-clock callback.

type GenerationMeta 

type GenerationMeta struct {
	ID                int64
	InstanceID        string
	PreviousID        int64
	Label             string
	PublicFingerprint string
	TriggerKind       string
	LoadedAt          time.Time
	PublishedAt       time.Time
}

type GenerationObservability 

type GenerationObservability struct {
	Active              int
	Retired             int
	Pinned              int
	RetentionWouldBlock bool
}

GenerationObservability is an aggregate, ID-free manager posture snapshot.

type Lease 

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

Lease is a hot-path request lease (req 5.3-5.4, 15.1).

func (*Lease) Generation 

func (l *Lease) Generation() *Generation

Generation returns the bound generation.

func (*Lease) Handler 

func (l *Lease) Handler() http.Handler

Handler returns the bound request-plane handler for this lease, or nil.

func (*Lease) Meta 

func (l *Lease) Meta() GenerationMeta

Meta returns safe generation metadata for this lease.

func (*Lease) Release 

func (l *Lease) Release()

Release drops the lease retain exactly once; double-release is a no-op (req 10.4).

func (*Lease) RequestPlane 

func (l *Lease) RequestPlane() PublishedRequestPlane

RequestPlane returns the bound immutable request-plane publisher, or nil.

func (*Lease) RetainPin 

func (l *Lease) RetainPin(kind PinKind) (*Pin, bool)

RetainPin acquires an additional independent generation pin while this lease still holds spawn rights (req 5.3, 5.7, 10.3). Unlike TransferPin, the lease retain is preserved so multiple terminal/async dependents can each hold a pin. Invalid kinds and post-release attempts fail closed without consuming ownership.

func (*Lease) Status 

func (l *Lease) Status() Status

Status returns a defensive lifecycle/metadata snapshot for this lease.

func (*Lease) TransferPin 

func (l *Lease) TransferPin(kind PinKind) (*Pin, bool)

TransferPin converts the lease retain into an async/SSE/provider pin (req 5.7, 10.3). Only PinSSE, PinAsync, and PinProvider are accepted; invalid kinds fail without consuming the lease so a subsequent valid transfer can still succeed.

type LifecycleOutcome 

type LifecycleOutcome string

LifecycleOutcome is a stable post-commit retirement status category (design Error Handling; req 10.12, 13.5, 14.1). 

const (
	LifecycleOutcomeOK            LifecycleOutcome = ""
	LifecycleOutcomeQuiesceFailed LifecycleOutcome = "quiesce_failed"
	LifecycleOutcomeCleanupFailed LifecycleOutcome = "cleanup_failed"
)

type Manager 

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

Manager is the production generation publication and acquire surface (req 5.2-5.4, 10, 15). Manager also owns post-publish retirement scheduling (task 7.3): it fires one bounded background retirement per replaced generation, bounded by the finite retained-generation budget — never an unbounded worker map/pool.

func NewManager 

func NewManager(maxRetained int, clock *ManualClock) *Manager

NewManager constructs a manager with a finite retained-generation budget (req 10.8). clock may be nil. A cryptographically random opaque instance ID is assigned once for this manager/process incarnation (task 3.6).

func NewManagerWithInstanceID 

func NewManagerWithInstanceID(maxRetained int, clock *ManualClock, instanceID string) *Manager

NewManagerWithInstanceID is the deterministic constructor/test seam for a fixed opaque runtime instance identity. Empty instanceID falls back to a random one.

func (*Manager) Acquire 

func (m *Manager) Acquire() (*Lease, bool)

Acquire loads the active generation with retain and pointer recheck (req 5.3-5.4, 10.2, 15.1).

func (*Manager) Active 

func (m *Manager) Active() *Generation

Active returns the current active generation pointer (may be nil).

func (*Manager) BeginPrepare 

func (m *Manager) BeginPrepare(label string, owned OwnedCloser) *Generation

BeginPrepare creates a preparing candidate (MarkPrepared before Publish).

func (*Manager) BeginPrepareRequestPlane 

func (m *Manager) BeginPrepareRequestPlane(label string, plane PublishedRequestPlane) *Generation

BeginPrepareRequestPlane creates a preparing candidate bound to an immutable request-plane publisher (MarkPrepared before Publish).

func (*Manager) BeginShutdown 

func (m *Manager) BeginShutdown()

BeginShutdown prevents new lease acquisitions and candidate publication. In-flight leases and pins keep their retains; pinned generations are not force-closed (req 13.x, 5.7). Publication that already holds Manager.mu may still complete; DetachActive observes any resulting active generation.

func (*Manager) ClockNow 

func (m *Manager) ClockNow() time.Time

ClockNow returns the manager clock instant, or zero if unset.

func (*Manager) DetachActive 

func (m *Manager) DetachActive() *Generation

DetachActive clears the active pointer, marks the prior generation retiring, and retains it for drain/close. It does not close generation-owned resources.

func (*Manager) GenerationByID 

func (m *Manager) GenerationByID(id int64) *Generation

GenerationByID returns an active or retained generation with the given id, or nil. Used by terminal-work generation-bound provider resolution (task 3.6).

func (*Manager) GenerationByIdentity 

func (m *Manager) GenerationByIdentity(instanceID string, id int64) *Generation

GenerationByIdentity returns an open generation only when both the manager instance ID and numeric generation ID match exactly (task 3.6 restart safety).

func (*Manager) HasLifecycleObserver 

func (m *Manager) HasLifecycleObserver() bool

func (*Manager) HasOpenGenerations 

func (m *Manager) HasOpenGenerations() bool

HasOpenGenerations reports whether any active or retained generation is still non-closed. Used by process shutdown to avoid closing ProcessServices while a generation pin/lease remains (req 13.x).

func (*Manager) InstanceID 

func (m *Manager) InstanceID() string

InstanceID returns the opaque process/manager incarnation identity.

func (*Manager) ObservabilitySnapshot 

func (m *Manager) ObservabilitySnapshot() GenerationObservability

ObservabilitySnapshot returns aggregate active/retired/pinned/retention gauges.

func (*Manager) Prepare 

func (m *Manager) Prepare(label string) *Generation

Prepare creates a prepared candidate with no generation-owned payload.

func (*Manager) PrepareOwned 

func (m *Manager) PrepareOwned(label string, owned OwnedCloser) *Generation

PrepareOwned creates a prepared candidate bound to generation-owned resources.

func (*Manager) PrepareRequestPlane 

func (m *Manager) PrepareRequestPlane(label string, plane PublishedRequestPlane) *Generation

PrepareRequestPlane creates a prepared candidate bound to an immutable request-plane publisher (owned close + Handler).

func (*Manager) Publish 

func (m *Manager) Publish(candidate *Generation) error

Publish atomically swaps the active pointer after budget reservation (req 5.2, 5.9, 15.4). Retention rejection and host-shutdown rejection roll back the unpublished candidate exactly once after releasing Manager.mu so closers may re-enter status paths (req 10.9).

func (*Manager) RetainedCount 

func (m *Manager) RetainedCount() int

RetainedCount returns how many retired generations occupy the retention budget.

func (*Manager) RetentionPressure 

func (m *Manager) RetentionPressure() RetentionPressure

RetentionPressure returns the current retained-generation budget posture.

func (*Manager) RetireGeneration 

func (m *Manager) RetireGeneration(ctx context.Context, g *Generation) (RetirementStatus, error)

RetireGeneration synchronously drives one generation's quiesce → drain → close cycle using the manager's cleanup policy/observer, deriving the QuiesceCloser solely from the generation (never an external collaborator). It is the sync retry/wait counterpart to automatic post-publish scheduling: callers may retry an exhausted-cleanup generation, wait for a specific generation's retirement to finish, or drive retirement during shutdown. Concurrent calls for the same generation are serialized by that generation's own context-aware retirement admission; unrelated generations retire independently.

func (*Manager) SetAfterRetainHook 

func (m *Manager) SetAfterRetainHook(fn func(*Generation))

SetAfterRetainHook installs a barrier hook between tryRetain and pointer recheck.

func (*Manager) SetCleanupPolicy 

func (m *Manager) SetCleanupPolicy(p CleanupPolicy)

SetCleanupPolicy installs the post-drain cleanup retry budget used by both automatic post-publish retirement scheduling and RetireGeneration. Nil-safe.

func (*Manager) SetLifecycleObserver 

func (m *Manager) SetLifecycleObserver(obs *ReloadObserver)

SetLifecycleObserver attaches optional reload lifecycle telemetry (quiesce/cleanup spans) used by retirement. Nil-safe.

func (*Manager) ShutdownDetached 

func (m *Manager) ShutdownDetached(ctx context.Context) error

ShutdownDetached prevents new acquisitions, detaches the active generation, and retires every retained generation with context-bounded drain waiting. Retained generations are retired concurrently (bounded by the finite retention budget) so one pinned generation cannot block unrelated drained generations from closing. A context timeout/cancel returns an error without force-closing a still-pinned generation. Per-generation retirement admission (Generation.retireAdmit) safely interleaves with any already-scheduled automatic post-publish retirement for the same generation — at most one retirement attempt runs at a time per generation.

Fan-out uses a buffered result channel (not a wait-group) so request/lease refcounting remains packed-atomic (req 10.4) while shutdown retires each retained generation via RetireGeneration.

func (*Manager) ShuttingDown 

func (m *Manager) ShuttingDown() bool

ShuttingDown reports whether BeginShutdown has been called.

func (*Manager) SnapshotRetained 

func (m *Manager) SnapshotRetained() []*Generation

SnapshotRetained returns a defensive copy of currently retained generations.

func (*Manager) SweepClosed 

func (m *Manager) SweepClosed()

SweepClosed drops closed generations from the retained budget set.

type ManualClock 

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

ManualClock is a fake clock for tests (no timing sleeps).

func NewManualClock 

func NewManualClock(t time.Time) *ManualClock

NewManualClock returns a controllable clock starting at t.

func (*ManualClock) Advance 

func (c *ManualClock) Advance(d time.Duration)

Advance moves the fake clock forward by d.

func (*ManualClock) Now 

func (c *ManualClock) Now() time.Time

Now returns the current fake time.

type MetaHints 

type MetaHints struct {
	PublicFingerprint string
	TriggerKind       string
	LoadedAt          time.Time
}

type ModelViewBinder 

type ModelViewBinder interface {
	BindModelViews(ctx context.Context) context.Context
}

ModelViewBinder optionally binds immutable model-registry and catalog publication views into a request context after generation lease acquisition and before the generation handler runs (req 9.4-9.5).

Implementations capture generation-owned publications exactly once. Ordinary test request planes that do not implement this interface retain prior behavior (no model-view binding).

type OwnedCloser 

type OwnedCloser interface {
	Close() error
}

type Pin 

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

Pin retains a generation across SSE/async/provider work.

func (*Pin) Generation 

func (p *Pin) Generation() *Generation

Generation returns the pinned generation.

func (*Pin) Kind 

func (p *Pin) Kind() PinKind

Kind returns the pin classification.

func (*Pin) Release 

func (p *Pin) Release()

Release drops the pin retain exactly once.

type PinKind 

type PinKind uint8
const (
	PinUnknown PinKind = iota
	PinHTTP
	PinSSE
	PinAsync
	PinProvider
)

type PublishedRequestPlane 

type PublishedRequestPlane interface {
	QuiesceCloser
	Handler() http.Handler
}

PublishedRequestPlane is the narrow immutable request-plane surface bound to a Generation for preparation, publication, and acquire. The future data-plane dispatcher only needs Handler(); Close remains on OwnedCloser.

Implementations must not expose mutable config, runtime.App, mixed Built handles, ProcessServices ownership, or process closers. runtimehost never imports runtimebundle; concrete bundles satisfy this interface from outside.

type PublishedWorkStarter 

type PublishedWorkStarter interface {
	StartPublished(ctx context.Context) error
}

PublishedWorkStarter is optionally implemented by PublishedRequestPlane values that own admission-independent work which must not run until the request plane is the active published generation. Manager.Publish invokes it after the active-pointer swap. runtimehost never imports runtimebundle.

type QuiesceCloser 

type QuiesceCloser interface {
	OwnedCloser
	Quiesce(ctx context.Context) error
}

type ReloadObserver 

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

ReloadObserver records structured logs, process-owned spans, and metrics for reload attempts without owning reload logic or canonical status history (Task 6.4: bounded history moved exclusively to ReloadState).

func NewReloadObserver 

func NewReloadObserver(deps ReloadObserverDeps) *ReloadObserver

NewReloadObserver constructs a process-owned reload observer. Nil sinks are no-ops.

func (*ReloadObserver) BeginAttempt 

func (o *ReloadObserver) BeginAttempt(ctx context.Context, trigger sdkreload.Trigger, attemptID, activeGen int64) (outCtx context.Context, end func(sdkreload.Result))

BeginAttempt starts process-owned reload spans and returns an end callback.

func (*ReloadObserver) BeginStage 

func (o *ReloadObserver) BeginStage(ctx context.Context, stage string) (outCtx context.Context, end func(result string))

BeginStage opens a child span for a reload pipeline stage.

func (*ReloadObserver) ObserveLifecycle 

func (o *ReloadObserver) ObserveLifecycle(ctx context.Context, stage string, result string, d time.Duration)

ObserveLifecycle records post-commit quiesce/cleanup stage telemetry.

func (*ReloadObserver) RefreshGauges 

func (o *ReloadObserver) RefreshGauges(mgr *Manager)

RefreshGauges updates aggregate generation gauges from the manager.

type ReloadObserverDeps 

type ReloadObserverDeps struct {
	Logger  *slog.Logger
	Tracer  trace.Tracer
	Metrics *metrics.ReloadProm
}

ReloadObserverDeps wires optional telemetry sinks for a ReloadObserver.

type ReloadState 

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

ReloadState owns active effective/source snapshot, last result/success/failure, source-integrity posture, model-generation fingerprint, bounded history, and canonical status composition (req 6.3-6.4, 7.1-7.8).

func (*ReloadState) ActiveInput 

func (s *ReloadState) ActiveInput(trigger sdkreload.Trigger, attemptID, activeGeneration int64) attemptInput

func (*ReloadState) Apply 

func (s *ReloadState) Apply(outcome attemptOutcome, meta reloadTerminalMeta) sdkreload.Result

Apply applies one completed attempt outcome and terminal metadata. Busy or empty-category results return a defensive clone without mutating state.

func (*ReloadState) Snapshot 

func (s *ReloadState) Snapshot(in reloadStatusInput) sdkreload.Status

type RequestBinding 

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

RequestBinding is the safe, immutable generation binding attached to a request context. It exposes metadata snapshots and controlled pin transfer only — never mutable Generation internals, config, credentials, Built, App, or ProcessServices handles (req 4.5-4.8).

func BindingFromContext 

func BindingFromContext(ctx context.Context) (*RequestBinding, bool)

BindingFromContext returns the request generation binding when present.

func (*RequestBinding) Meta 

func (b *RequestBinding) Meta() GenerationMeta

Meta returns a defensive copy of the generation metadata frozen at bind time.

func (*RequestBinding) Retain 

func (b *RequestBinding) Retain(kind genpin.Kind) (genpin.Pin, bool)

Retain implements genpin.Retainer by acquiring an independent child pin.

func (*RequestBinding) RetainPin 

func (b *RequestBinding) RetainPin(kind PinKind) (*Pin, bool)

RetainPin acquires an additional independent generation pin while the request lease still holds spawn rights (req 5.3, 5.7, 10.3).

func (*RequestBinding) RuntimeGenerationID 

func (b *RequestBinding) RuntimeGenerationID() string

RuntimeGenerationID implements genpin.Retainer using the bind-time generation id.

func (*RequestBinding) RuntimeInstanceID 

func (b *RequestBinding) RuntimeInstanceID() string

RuntimeInstanceID implements genpin.Retainer using the bind-time manager instance.

func (*RequestBinding) Status 

func (b *RequestBinding) Status() Status

Status returns a defensive lifecycle/metadata snapshot frozen at bind time.

func (*RequestBinding) TransferPin 

func (b *RequestBinding) TransferPin(kind PinKind) (*Pin, bool)

TransferPin converts the request lease retain into an async/SSE/provider pin. Exactly one successful transfer is allowed; subsequent calls fail. After a successful transfer, the dispatcher's deferred Release becomes a no-op.

type RetentionPressure 

type RetentionPressure struct {
	MaxRetained       int
	Retained          int
	BlockingCategory  string
	WouldBlockPublish bool
}

RetentionPressure is a bounded diagnostics snapshot for retention admission (req 10.10). It never includes request content, credentials, or paths.

type RetirementStatus 

type RetirementStatus struct {
	GenerationID int64
	Outcome      LifecycleOutcome
	Attempts     int
	Err          error
}

RetirementStatus is a bounded snapshot of the most recent retirement attempt.

type StableConfigSource 

type StableConfigSource interface {
	AbsolutePath() string
	ReadStable(ctx context.Context, active *configsource.ActiveSourceVersion) (configsource.SourceSnapshot, configsource.AtomicResult, error)
}

StableConfigSource is the fixed-path source seam (typically configsource.FixedSource). Callers never supply a path or YAML through the canonical Trigger envelope.

type Status 

type Status struct {
	Meta      GenerationMeta
	Lifecycle GenLifecycle
	Refs      uint32
}

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.