coldstart

package
v0.2.3 Latest Latest
Warning

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

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

Documentation

Overview

Package coldstart is the generated Coldstart widget.

Edit the widget document and regenerate; edits here are overwritten.

Index

Constants

View Source 
const (
	ColdstartName    = "Coldstart"
	ColdstartRegion  = "widget.candaws.coldstart"
	ColdstartPalette = "fieldStation"
	ColdstartTitleID = "widget.candaws.coldstart-title"
)

This widget's identity. The region is the only one that crosses the wire: a patch names it, so changing it is a client-visible change. The palette is a name a host resolves to values; this widget carries no colour of its own. The title id is what the widget's landmark is labelled by.

View Source 
const (
	ColdstartEventPrewarm    = "widget.candaws.coldstart.prewarm"
	ColdstartEventPoolReport = "widget.candaws.coldstart.report"
)

The wire names this widget accepts. The set is exhaustive and default-deny: a name absent from the registration is refused before any reducer runs.

View Source 
const (
	ColdstartEventPoolReportFieldInvocationSequence = "invocation_sequence"
	ColdstartEventPoolReportFieldRuntimeName        = "runtime_name"
	ColdstartEventPoolReportFieldWarmInstances      = "warm_instances"
	ColdstartEventPoolReportFieldQueuedInvocations  = "queued_invocations"
	ColdstartEventPoolReportFieldColdStartMillis    = "cold_start_millis"
	ColdstartEventPoolReportFieldDispatcherUp       = "dispatcher_up"
	ColdstartEventPoolReportFieldDraining           = "draining"
)

The wire field names each event carries. They are the other half of an event's contract: the widget reads these out of a delivery, and whatever produced the delivery wrote them in. Registration.Payloads carries the same names as data, for a host that fills an event it cannot name at compile time.

Variables

View Source 
var (
	// ErrRuntimeName is an empty runtime name. The card interpolates it into a
	// stat line, and an empty one renders as a sentence with a hole in it.
	ErrRuntimeName = errors.New("coldstart: the runtime name is empty")

	// ErrArrivalRate is an arrival interval that is not positive.
	ErrArrivalRate = errors.New("coldstart: the arrival interval is not positive")

	// ErrStartupBudget is a start-up budget that is not positive. Scaling to
	// zero instantly and back up instantly is a different product.
	ErrStartupBudget = errors.New("coldstart: the start-up budget is not positive")

	// ErrWorkDuration is an invocation duration that is not positive.
	ErrWorkDuration = errors.New("coldstart: the invocation duration is not positive")

	// ErrMaxInstances is a pool ceiling outside [1, maxInstances].
	ErrMaxInstances = errors.New("coldstart: the pool ceiling is out of range")

	// ErrBacklogCeiling is a backlog ceiling below one: a dispatcher that
	// cannot queue anything drops the invocation that caused it to spawn.
	ErrBacklogCeiling = errors.New("coldstart: the backlog ceiling is below one")

	// ErrIdleSweeps is an idle tolerance below one, which reaps an instance in
	// the same sweep it warmed in.
	ErrIdleSweeps = errors.New("coldstart: the idle tolerance is below one")

	// ErrReapInterval is a reap interval that is not positive. Without one
	// nothing ever scales to zero, which is the other half of the product.
	ErrReapInterval = errors.New("coldstart: the reap interval is not positive")

	// ErrCallPatience is a caller patience that does not clear a cold start
	// plus an invocation, so every first call times out.
	ErrCallPatience = errors.New("coldstart: the caller's patience does not clear a cold start")
)

The faults this engine reports, each a sentinel.

Functions

func ColdstartView 

func ColdstartView(state ColdstartState) templ.Component

ColdstartView draws the Coldstart widget's default live region.

func ColdstartViewAt 

func ColdstartViewAt(state ColdstartState, region string) templ.Component

ColdstartViewAt draws one instance in its host-assigned live region.

Every value in it is a pure read of state and region: equal inputs render byte-identical markup: that comparison is what suppresses a patch nobody needs.

func ReportFields 

func ReportFields(view PoolView) map[string]string

ReportFields is one pool view as the poolReport event carries it.

The live count, the warm floor and the totals do not cross. The card draws what the pool is, and a viewer who can see that two instances are warm has been told everything the picture uses.

Types

type Coldstart 

type Coldstart[I live.IIdentity] struct {
	// contains filtered or unexported fields
}

Coldstart is the generated Coldstart widget.

I is the HOST's identity type, threaded through and never read: a widget document names no host, no address and no credential, so nothing here can look at an identity. It is a type parameter because the SDK's contract carries one — live.Session stopped erasing the application's identity type on 2026-09-03 — and a generated widget must fit whatever host registers it.

func NewColdstart 

func NewColdstart[I live.IIdentity]() *Coldstart[I]

NewColdstart returns the widget a host registers, instantiated on that host's own identity type.

func NewColdstartAt 

func NewColdstartAt[I live.IIdentity](region string) *Coldstart[I]

NewColdstartAt gives one instance its host-assigned region. The host validates region syntax and uniqueness when assembling its live configuration.

func (*Coldstart[I]) Dirty 

func (instance *Coldstart[I]) Dirty(previous ColdstartState, next ColdstartState) bool

Dirty reports whether a transition may have changed this widget's markup: the state fields its bindings, its predicates and its tick read, and no others.

func (*Coldstart[I]) Mount 

func (instance *Coldstart[I]) Mount(
	ctx context.Context, session live.Session[I],
) (ColdstartState, []live.Effect[I], error)

Mount opens one session's copy of the widget. It schedules no effect: the streams this widget declared are the host's to open, because a widget document names no host, no address and no credential.

func (*Coldstart[I]) Reduce 

func (instance *Coldstart[I]) Reduce(
	state ColdstartState, event live.Event,
) (ColdstartState, []live.Effect[I])

Reduce is the pure transition from one state to the next. It performs no I/O, reads no clock and mutates nothing it was given.

func (*Coldstart[I]) Register 

func (instance *Coldstart[I]) Register() widget.Registration

Register declares this instance's definition and assigned region.

Events are the names a browser may send; Internal are the names only a declared stream delivers, which the host routes without registering.

func (*Coldstart[I]) Render 

func (instance *Coldstart[I]) Render(state ColdstartState) templ.Component

Render draws the widget's live region. It is a pure function of state: equal state renders byte-identical markup.

func (*Coldstart[I]) Snapshot 

func (instance *Coldstart[I]) Snapshot(state ColdstartState) widget.Snapshot

Snapshot projects state into ordered name/value pairs, in state-field declaration order.

func (*Coldstart[I]) Unmount 

func (instance *Coldstart[I]) Unmount(ctx context.Context, session live.Session[I], state ColdstartState)

Unmount releases what the session held. This widget holds nothing.

type ColdstartState 

type ColdstartState struct {
	// InvocationSequence is the "invocationSequence" state field, declared type counter.
	InvocationSequence uint64

	// RuntimeName is the "runtimeName" state field, declared type text.
	RuntimeName string

	// WarmInstances is the "warmInstances" state field, declared type count.
	WarmInstances int64

	// QueuedInvocations is the "queuedInvocations" state field, declared type count.
	QueuedInvocations int64

	// ColdStartMillis is the "coldStartMillis" state field, declared type count.
	ColdStartMillis int64

	// DispatcherUp is the "dispatcherUp" state field, declared type flag.
	DispatcherUp bool

	// Draining is the "draining" state field, declared type flag.
	Draining bool

	// Throttled is the "throttled" state field, declared type flag.
	Throttled bool
}

ColdstartState is this widget's own state, and the type argument every method below is written in. The host holds it without knowing it; nothing in this file asserts it back, because nothing in this file ever loses it.

func (ColdstartState) BacklogIndicatorTone 

func (state ColdstartState) BacklogIndicatorTone() string

BacklogIndicatorTone is the "backlogIndicator" indicator's tone: positive while its predicate holds, warning otherwise.

func (ColdstartState) BacklogStatusLabel 

func (state ColdstartState) BacklogStatusLabel() string

BacklogStatusLabel is the "backlogStatusLabel" label.

func (ColdstartState) BacklogStatusText 

func (state ColdstartState) BacklogStatusText() string

BacklogStatusText is the "backlogStatusText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (ColdstartState) CallerLabel 

func (state ColdstartState) CallerLabel() string

CallerLabel is the "callerLabel" label.

func (ColdstartState) CapacityIndicatorTone 

func (state ColdstartState) CapacityIndicatorTone() string

CapacityIndicatorTone is the "capacityIndicator" indicator's tone: positive while its predicate holds, warning otherwise.

func (ColdstartState) CapacityStatusLabel 

func (state ColdstartState) CapacityStatusLabel() string

CapacityStatusLabel is the "capacityStatusLabel" label.

func (ColdstartState) CapacityStatusText 

func (state ColdstartState) CapacityStatusText() string

CapacityStatusText is the "capacityStatusText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (ColdstartState) ColdCaptionLabel 

func (state ColdstartState) ColdCaptionLabel() string

ColdCaptionLabel is the "coldCaptionLabel" label.

func (ColdstartState) ColdCaptionText 

func (state ColdstartState) ColdCaptionText() string

ColdCaptionText is the "coldCaptionText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (ColdstartState) ColdLabel 

func (state ColdstartState) ColdLabel() string

ColdLabel is the "coldLabel" label.

func (ColdstartState) DispatcherCaptionLabel 

func (state ColdstartState) DispatcherCaptionLabel() string

DispatcherCaptionLabel is the "dispatcherCaptionLabel" label.

func (ColdstartState) DispatcherCaptionText 

func (state ColdstartState) DispatcherCaptionText() string

DispatcherCaptionText is the "dispatcherCaptionText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (ColdstartState) DispatcherLabel 

func (state ColdstartState) DispatcherLabel() string

DispatcherLabel is the "dispatcherLabel" label.

func (ColdstartState) Idle 

func (state ColdstartState) Idle() bool

Idle is the "idle" predicate.

func (ColdstartState) LatencyStatLabel 

func (state ColdstartState) LatencyStatLabel() string

LatencyStatLabel is the "latencyStatLabel" label.

func (ColdstartState) LatencyStatText 

func (state ColdstartState) LatencyStatText() string

LatencyStatText is the "latencyStatText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (ColdstartState) MotionActive 

func (state ColdstartState) MotionActive() bool

MotionActive is this widget's compiled motion gate: everything its motion block requires, and none of what it forbids. The host's own connection status is the gate's other half and is applied by the stylesheet, so an animation cannot run against a dead connection whatever this returns.

func (ColdstartState) MotionActiveText 

func (state ColdstartState) MotionActiveText() string

MotionActiveText renders the gate into the attribute the stylesheet selects on.

func (ColdstartState) MotionTickID 

func (state ColdstartState) MotionTickID() string

MotionTickID is the scene's identity for one tick.

Every animation is finite and none repeats, so what starts one again is a new element: the scene carries this as its id, the tick advances, and the picture moves exactly as often as the data does.

func (ColdstartState) MotionTickIDAt 

func (state ColdstartState) MotionTickIDAt(region string) string

MotionTickIDAt namespaces the scene's tick identity under its live instance.

func (ColdstartState) PoolDescriptionText 

func (state ColdstartState) PoolDescriptionText() string

PoolDescriptionText is the "poolDescriptionText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (ColdstartState) PrewarmCaptionLabel 

func (state ColdstartState) PrewarmCaptionLabel() string

PrewarmCaptionLabel is the "prewarmCaptionLabel" label.

func (ColdstartState) QueueStatLabel 

func (state ColdstartState) QueueStatLabel() string

QueueStatLabel is the "queueStatLabel" label.

func (ColdstartState) QueueStatText 

func (state ColdstartState) QueueStatText() string

QueueStatText is the "queueStatText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (ColdstartState) RequestLegendLabel 

func (state ColdstartState) RequestLegendLabel() string

RequestLegendLabel is the "requestLegendLabel" label.

func (ColdstartState) ResponseLegendLabel 

func (state ColdstartState) ResponseLegendLabel() string

ResponseLegendLabel is the "responseLegendLabel" label.

func (ColdstartState) RuntimeStatLabel 

func (state ColdstartState) RuntimeStatLabel() string

RuntimeStatLabel is the "runtimeStatLabel" label.

func (ColdstartState) SceneDescriptionLabel 

func (state ColdstartState) SceneDescriptionLabel() string

SceneDescriptionLabel is the "sceneDescriptionLabel" label.

func (ColdstartState) Serving 

func (state ColdstartState) Serving() bool

Serving is the "serving" predicate.

func (ColdstartState) SourceLabel 

func (state ColdstartState) SourceLabel() string

SourceLabel is the "sourceLabel" label.

func (ColdstartState) ThawLegendLabel 

func (state ColdstartState) ThawLegendLabel() string

ThawLegendLabel is the "thawLegendLabel" label.

func (ColdstartState) TitleLabel 

func (state ColdstartState) TitleLabel() string

TitleLabel is the "titleLabel" label.

func (ColdstartState) Warm 

func (state ColdstartState) Warm() bool

Warm is the "warm" predicate.

func (ColdstartState) WarmCaptionLabel 

func (state ColdstartState) WarmCaptionLabel() string

WarmCaptionLabel is the "warmCaptionLabel" label.

func (ColdstartState) WarmCaptionText 

func (state ColdstartState) WarmCaptionText() string

WarmCaptionText is the "warmCaptionText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (ColdstartState) WarmLabel 

func (state ColdstartState) WarmLabel() string

WarmLabel is the "warmLabel" label.

type Config 

type Config struct {
	// RuntimeName is the runtime the card interpolates into a stat line.
	RuntimeName string

	// ArrivalInterval is how often the caller invokes.
	ArrivalInterval time.Duration

	// StartupBudget is what an instance pays before it can serve anything, and
	// is the number the dashboard reports and the customer is billed for.
	StartupBudget time.Duration

	// WorkDuration is how long a warm instance takes to answer.
	WorkDuration time.Duration

	// MaxInstances is the pool ceiling.
	MaxInstances int

	// BacklogCeiling is how many invocations may wait on a start-up before the
	// dispatcher stops accepting and starts dropping the oldest.
	BacklogCeiling int

	// IdleSweeps is how many reap sweeps an instance may sit idle through
	// before its channel is closed and its goroutine returns.
	IdleSweeps int

	// ReapInterval is how often the dispatcher looks for instances to freeze.
	ReapInterval time.Duration

	// CallPatience is how long a caller waits for its own reply channel before
	// giving up on it.
	CallPatience time.Duration

	// WarmFloor is how many instances survive every sweep. Zero is legal and is
	// what "scales to zero" means; the prewarm control raises it to one, which
	// the pricing page calls Serverful.
	WarmFloor int
}

Config is one runtime's shape and pace. Every field is required.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig is the demo's own pace: a call every second and a bit, a start-up long enough to watch being paid, and a reaper patient enough that an instance is not gone before anybody saw it.

func (Config) Validate 

func (config Config) Validate() error

Validate reports the first fault in a configuration.

type PoolView 

type PoolView struct {
	// Sequence is this view's position in the stream, from 1.
	Sequence uint64

	// RuntimeName is the runtime the card interpolates into a stat line.
	RuntimeName string

	// WarmInstances is how many instances have paid their start-up and can
	// serve now.
	WarmInstances int

	// LiveInstances is how many instance goroutines exist, warming ones
	// included. The warm count never exceeds it, which is what makes
	// [PoolView.Sound] a property rather than a coincidence.
	LiveInstances int

	// Queued is how many invocations are waiting on a start-up.
	Queued int

	// ColdStartMillis is what the platform spends getting ready, and is billed.
	ColdStartMillis int

	// DispatcherUp is whether the dispatcher is still accepting. It stops when
	// the backlog reaches its ceiling, which is the only thing that closes it.
	DispatcherUp bool

	// Draining is whether any instance has served and is now waiting to be
	// called again or reaped.
	Draining bool

	// WarmFloor is how many instances survive every sweep. Zero is what
	// "scales to zero" means; the prewarm control raises it.
	WarmFloor int

	// Served and Dropped are the totals out. A dropped invocation had its reply
	// channel closed rather than being left to wait, so the two together are
	// every invocation the dispatcher ever accepted.
	Served  uint64
	Dropped uint64
}

PoolView is what the dispatcher tells anybody, and it is deliberately the shape the Coldstart card's `poolReport` event carries — plus the three numbers that make the pool's own invariants checkable from outside.

func (PoolView) ScaledToZero 

func (view PoolView) ScaledToZero() bool

ScaledToZero reports whether no instance goroutine exists at all. It is the state the product is named after, and the one a warm floor prevents.

func (PoolView) Sound 

func (view PoolView) Sound() bool

Sound reports whether this view describes a pool that could exist.

The warm count never exceeds the live count — an instance cannot have paid a start-up it was never spawned for — and a warm floor of zero is legal and is the whole of what scaling to zero means. It is exported because it is the property rather than an implementation detail: a specification asserts it of every view the engine publishes.

type Runtime 

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

Runtime is one Coldstart function runtime running in one process.

It holds channels and nothing else. The routing table, every instance's temperature, the backlog and the published view are locals of goroutines Runtime.Run starts — and the instance goroutines are not started by Run at all: they are started by the dispatcher when somebody calls, and they return when nobody does.

func NewRuntime 

func NewRuntime(config Config) (*Runtime, error)

NewRuntime builds a runtime and starts nothing.

func (*Runtime) Config 

func (runtime *Runtime) Config() Config

Config is the configuration this runtime was built from.

func (*Runtime) Prewarm 

func (runtime *Runtime) Prewarm(ctx context.Context) error

Prewarm asks the dispatcher to keep one instance permanently warm.

It is what the card's control emits, and it is a method rather than widget state because the widget changes nothing when that button is pressed. The control the card actually wants is a number, and the document records why it cannot have one.

func (*Runtime) Run 

func (runtime *Runtime) Run(ctx context.Context) error

Run starts the dispatcher, the caller and the feed, and returns when the context ends and all of them — including every instance the dispatcher spawned — have stopped.

func (*Runtime) Watch 

func (runtime *Runtime) Watch(ctx context.Context) (<-chan PoolView, error)

Watch is the pool stream the card's declared source resolves to.

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.