queuecumber

package
v0.2.1 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: 12 Imported by: 0

Documentation

Overview

Package queuecumber is the generated Queuecumber widget.

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

Index

Constants

View Source 
const (
	QueuecumberName    = "Queuecumber"
	QueuecumberRegion  = "widget.candaws.queuecumber"
	QueuecumberPalette = "fieldStation"
	QueuecumberTitleID = "widget.candaws.queuecumber-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 (
	QueuecumberEventToggleIntake       = "widget.candaws.queuecumber.intake-toggle"
	QueuecumberEventRedriveDeadLetters = "widget.candaws.queuecumber.redrive"
	QueuecumberEventBrokerReport       = "widget.candaws.queuecumber.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 (
	QueuecumberEventBrokerReportFieldSequence     = "sequence"
	QueuecumberEventBrokerReportFieldAccepting    = "accepting"
	QueuecumberEventBrokerReportFieldDepth        = "depth"
	QueuecumberEventBrokerReportFieldInFlight     = "in_flight"
	QueuecumberEventBrokerReportFieldDeadLettered = "dead_lettered"
	QueuecumberEventBrokerReportFieldWorkersUp    = "workers_up"
)

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 (
	// ErrWorkerCount is a worker count outside [1, maxWorkers].
	ErrWorkerCount = errors.New("queuecumber: the worker count is out of range")

	// ErrCadence is a submission cadence that is not positive.
	ErrCadence = errors.New("queuecumber: the submission cadence is not positive")

	// ErrSweep is a sweep interval that is not positive. Without one no lease
	// ever expires, and at-least-once quietly becomes at-most-once.
	ErrSweep = errors.New("queuecumber: the sweep interval is not positive")

	// ErrVisibility is a visibility timeout of fewer than two sweeps. One sweep
	// is a lease that can expire while the worker is still holding it, which
	// turns every delivery into a redelivery.
	ErrVisibility = errors.New("queuecumber: the visibility timeout is under two sweeps")

	// ErrCapacity is a queue capacity that is not positive: a queue that can
	// hold nothing refuses its own first message.
	ErrCapacity = errors.New("queuecumber: the queue capacity is not positive")

	// ErrAttemptCeiling is an attempt ceiling below one. A message that may be
	// tried zero times is dead-lettered before anybody looks at it.
	ErrAttemptCeiling = errors.New("queuecumber: the attempt ceiling is below one")

	// ErrDropRate is a drop rate outside [0, 1].
	ErrDropRate = errors.New("queuecumber: the drop rate is not a probability")
)

The faults this engine reports, each a sentinel so a caller can tell them apart without reading an English sentence.

Functions

func QueuecumberView 

func QueuecumberView(state QueuecumberState) templ.Component

QueuecumberView draws the Queuecumber widget's default live region.

func QueuecumberViewAt 

func QueuecumberViewAt(state QueuecumberState, region string) templ.Component

QueuecumberViewAt 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 BrokerView) map[string]string

ReportFields is one broker view as the brokerReport event carries it.

Six of the view's fields cross; the totals do not, because the card renders what the queue is rather than what it has been. Redelivered is the one that would be rendered largest if it crossed, and the document's own joke is that it is the redrive count in the stat line instead.

Types

type Broker 

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

Broker is one Queuecumber broker running in one process.

It holds channels and nothing else. The ready queue, the in-flight table and the dead-letter store are locals of the goroutine Broker.Run starts, and nothing in the process can name them.

func NewBroker 

func NewBroker(config Config) (*Broker, error)

NewBroker builds a broker and starts nothing.

func (*Broker) Config 

func (broker *Broker) Config() Config

Config is the configuration this broker was built from.

func (*Broker) Redrive 

func (broker *Broker) Redrive(ctx context.Context) error

Redrive moves everything in the dead-letter store back to the ready queue.

It is what the card's second control asks for, and it is a method rather than widget state because the widget changes nothing when that button is pressed: the event says what the viewer wants and the host decides what it means, which is the same seam a stream's source name is.

func (*Broker) Run 

func (broker *Broker) Run(ctx context.Context) error

Run starts every goroutine and returns when the context ends and all of them have stopped. The only error it has is being called twice.

func (*Broker) Watch 

func (broker *Broker) Watch(ctx context.Context) (<-chan BrokerView, error)

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

type BrokerView 

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

	// Accepting is whether the queue has room. A full queue closes the intake,
	// which is the only thing in this engine that ever does.
	Accepting bool

	// Depth is how many messages are ready, InFlight how many are leased, and
	// DeadLettered how many exhausted their attempts.
	//
	// A message is in exactly one of the three at every instant. That is the
	// invariant, and [BrokerView.Conserved] is where it is checkable.
	Depth        int
	InFlight     int
	DeadLettered int

	// WorkersUp is how many distinct workers the broker has been asked for work
	// by. A broker learns its pool size from being asked; nothing tells it.
	WorkersUp int

	// Submitted and Acknowledged are the totals in and out.
	Submitted    uint64
	Acknowledged uint64

	// Redelivered is how many leases expired and put a message back. It is the
	// number the console renders largest, because a redelivery is a fresh
	// transaction.
	Redelivered uint64

	// Refused is how many submissions arrived at a full queue. They are
	// counted rather than queued, because a queue with an unbounded queue is
	// not a queue.
	Refused uint64
}

BrokerView is what the broker tells anybody, and it is deliberately the shape the Queuecumber card's `brokerReport` event carries — plus the three totals that make the conservation law checkable from outside.

func (BrokerView) Conserved 

func (view BrokerView) Conserved() bool

Conserved reports whether every message this broker accepted is still somewhere it can be named.

Accepted minus acknowledged must equal ready plus leased plus dead-lettered: there is no fourth place, and a message that stopped being in one of the three without being acknowledged was dropped. It is exported because it is the property rather than an implementation detail — a specification asserts it of every view the engine ever publishes.

type Config 

type Config struct {
	// Workers is how many worker goroutines lease from this broker.
	Workers int

	// Cadence is how often the producer submits a message.
	Cadence time.Duration

	// WorkDuration is how long a worker holds a message before acknowledging
	// it, or not.
	WorkDuration time.Duration

	// SweepInterval is how often the expiry goroutine ages every live lease by
	// one. It is the only clock on that side of the engine.
	SweepInterval time.Duration

	// VisibilitySweeps is how many sweeps a lease survives before it expires.
	// Two is the floor: one would let a lease expire while its worker was
	// still working, which turns every delivery into a redelivery.
	VisibilitySweeps int

	// Capacity is how many ready messages the queue accepts before it stops
	// accepting. A full queue is what closes the intake, and closing the intake
	// is the whole of what this bounds.
	//
	// It is an admission bound and not a ceiling on depth. A lease that expires
	// and a redrive both push onto the ready queue without consulting it, by
	// design: refusing a message the queue has already accepted would drop it,
	// and a queue that drops what it accepted is not delivering at least once.
	// So depth can stand above capacity, and what capacity promises is the
	// narrower thing — a *submission* arriving at a full queue is counted as
	// refused rather than quietly queued.
	Capacity int

	// AttemptCeiling is how many times a message is leased before it is moved
	// to the dead-letter store rather than made ready again.
	AttemptCeiling int

	// DropRate is how often a worker finishes with a message and says nothing,
	// in [0, 1]. It is the whole of at-least-once: a message nobody
	// acknowledged is a message that comes back.
	DropRate float64

	// Seed seeds the per-worker random streams.
	Seed int64
}

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

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig is the demo's own pace: three workers, a message every second and a half, and enough dropped acknowledgements that a redelivery happens while somebody is watching.

func (Config) Validate 

func (config Config) Validate() error

Validate reports the first fault in a configuration. It is called by NewBroker, so a broker that exists is one whose pace can actually deliver.

type Queuecumber 

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

Queuecumber is the generated Queuecumber 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 NewQueuecumber 

func NewQueuecumber[I live.IIdentity]() *Queuecumber[I]

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

func NewQueuecumberAt 

func NewQueuecumberAt[I live.IIdentity](region string) *Queuecumber[I]

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

func (*Queuecumber[I]) Dirty 

func (instance *Queuecumber[I]) Dirty(previous QueuecumberState, next QueuecumberState) 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 (*Queuecumber[I]) Mount 

func (instance *Queuecumber[I]) Mount(
	ctx context.Context, session live.Session[I],
) (QueuecumberState, []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 (*Queuecumber[I]) Reduce 

func (instance *Queuecumber[I]) Reduce(
	state QueuecumberState, event live.Event,
) (QueuecumberState, []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 (*Queuecumber[I]) Register 

func (instance *Queuecumber[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 (*Queuecumber[I]) Render 

func (instance *Queuecumber[I]) Render(state QueuecumberState) templ.Component

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

func (*Queuecumber[I]) Snapshot 

func (instance *Queuecumber[I]) Snapshot(state QueuecumberState) widget.Snapshot

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

func (*Queuecumber[I]) Unmount 

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

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

type QueuecumberState 

type QueuecumberState struct {
	// Sequence is the "sequence" state field, declared type counter.
	Sequence uint64

	// Accepting is the "accepting" state field, declared type flag.
	Accepting bool

	// IntakePaused is the "intakePaused" state field, declared type flag.
	IntakePaused bool

	// Depth is the "depth" state field, declared type count.
	Depth int64

	// InFlight is the "inFlight" state field, declared type count.
	InFlight int64

	// DeadLettered is the "deadLettered" state field, declared type count.
	DeadLettered int64

	// WorkersUp is the "workersUp" state field, declared type count.
	WorkersUp int64

	// Behind is the "behind" state field, declared type flag.
	Behind bool
}

QueuecumberState 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 (QueuecumberState) AckLegendLabel 

func (state QueuecumberState) AckLegendLabel() string

AckLegendLabel is the "ackLegendLabel" label.

func (QueuecumberState) BrokerCaptionLabel 

func (state QueuecumberState) BrokerCaptionLabel() string

BrokerCaptionLabel is the "brokerCaptionLabel" label.

func (QueuecumberState) BrokerCaptionText 

func (state QueuecumberState) BrokerCaptionText() string

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

func (QueuecumberState) BrokerLabel 

func (state QueuecumberState) BrokerLabel() string

BrokerLabel is the "brokerLabel" label.

func (QueuecumberState) Clean 

func (state QueuecumberState) Clean() bool

Clean is the "clean" predicate.

func (QueuecumberState) DeadLetterCaptionText 

func (state QueuecumberState) DeadLetterCaptionText() string

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

func (QueuecumberState) DeadLetterIndicatorTone 

func (state QueuecumberState) DeadLetterIndicatorTone() string

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

func (QueuecumberState) DeadLetterStatusLabel 

func (state QueuecumberState) DeadLetterStatusLabel() string

DeadLetterStatusLabel is the "deadLetterStatusLabel" label.

func (QueuecumberState) DeadLetterStatusText 

func (state QueuecumberState) DeadLetterStatusText() string

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

func (QueuecumberState) DepthStatLabel 

func (state QueuecumberState) DepthStatLabel() string

DepthStatLabel is the "depthStatLabel" label.

func (QueuecumberState) DepthStatText 

func (state QueuecumberState) DepthStatText() string

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

func (QueuecumberState) DrainCaptionLabel 

func (state QueuecumberState) DrainCaptionLabel() string

DrainCaptionLabel is the "drainCaptionLabel" label.

func (QueuecumberState) Drained 

func (state QueuecumberState) Drained() bool

Drained is the "drained" predicate.

func (QueuecumberState) EnqueueLegendLabel 

func (state QueuecumberState) EnqueueLegendLabel() string

EnqueueLegendLabel is the "enqueueLegendLabel" label.

func (QueuecumberState) Flowing 

func (state QueuecumberState) Flowing() bool

Flowing is the "flowing" predicate.

func (QueuecumberState) GraveyardCaptionLabel 

func (state QueuecumberState) GraveyardCaptionLabel() string

GraveyardCaptionLabel is the "graveyardCaptionLabel" label.

func (QueuecumberState) GraveyardLabel 

func (state QueuecumberState) GraveyardLabel() string

GraveyardLabel is the "graveyardLabel" label.

func (QueuecumberState) IntakeCaptionLabel 

func (state QueuecumberState) IntakeCaptionLabel() string

IntakeCaptionLabel is the "intakeCaptionLabel" label.

func (QueuecumberState) IntakeCaptionText 

func (state QueuecumberState) IntakeCaptionText() string

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

func (QueuecumberState) IntakeIndicatorTone 

func (state QueuecumberState) IntakeIndicatorTone() string

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

func (QueuecumberState) IntakeStatusLabel 

func (state QueuecumberState) IntakeStatusLabel() string

IntakeStatusLabel is the "intakeStatusLabel" label.

func (QueuecumberState) IntakeStatusText 

func (state QueuecumberState) IntakeStatusText() string

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

func (QueuecumberState) IntakeTogglePressedText 

func (state QueuecumberState) IntakeTogglePressedText() string

IntakeTogglePressedText renders the "intakeToggle" control's pressed state.

func (QueuecumberState) LeaseLegendLabel 

func (state QueuecumberState) LeaseLegendLabel() string

LeaseLegendLabel is the "leaseLegendLabel" label.

func (QueuecumberState) MotionActive 

func (state QueuecumberState) 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 (QueuecumberState) MotionActiveText 

func (state QueuecumberState) MotionActiveText() string

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

func (QueuecumberState) MotionTickID 

func (state QueuecumberState) 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 (QueuecumberState) MotionTickIDAt 

func (state QueuecumberState) MotionTickIDAt(region string) string

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

func (QueuecumberState) ProducerCaptionLabel 

func (state QueuecumberState) ProducerCaptionLabel() string

ProducerCaptionLabel is the "producerCaptionLabel" label.

func (QueuecumberState) ProducerLabel 

func (state QueuecumberState) ProducerLabel() string

ProducerLabel is the "producerLabel" label.

func (QueuecumberState) QueueDescriptionText 

func (state QueuecumberState) QueueDescriptionText() string

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

func (QueuecumberState) RedeliveryStatLabel 

func (state QueuecumberState) RedeliveryStatLabel() string

RedeliveryStatLabel is the "redeliveryStatLabel" label.

func (QueuecumberState) RedriveLegendLabel 

func (state QueuecumberState) RedriveLegendLabel() string

RedriveLegendLabel is the "redriveLegendLabel" label.

func (QueuecumberState) SceneDescriptionLabel 

func (state QueuecumberState) SceneDescriptionLabel() string

SceneDescriptionLabel is the "sceneDescriptionLabel" label.

func (QueuecumberState) SourceLabel 

func (state QueuecumberState) SourceLabel() string

SourceLabel is the "sourceLabel" label.

func (QueuecumberState) StaffStatLabel 

func (state QueuecumberState) StaffStatLabel() string

StaffStatLabel is the "staffStatLabel" label.

func (QueuecumberState) StaffStatText 

func (state QueuecumberState) StaffStatText() string

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

func (QueuecumberState) Staffed 

func (state QueuecumberState) Staffed() bool

Staffed is the "staffed" predicate.

func (QueuecumberState) TitleLabel 

func (state QueuecumberState) TitleLabel() string

TitleLabel is the "titleLabel" label.

func (QueuecumberState) WorkerCaptionLabel 

func (state QueuecumberState) WorkerCaptionLabel() string

WorkerCaptionLabel is the "workerCaptionLabel" label.

func (QueuecumberState) WorkerCaptionText 

func (state QueuecumberState) WorkerCaptionText() string

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

func (QueuecumberState) WorkerOneLabel 

func (state QueuecumberState) WorkerOneLabel() string

WorkerOneLabel is the "workerOneLabel" label.

func (QueuecumberState) WorkerThreeLabel 

func (state QueuecumberState) WorkerThreeLabel() string

WorkerThreeLabel is the "workerThreeLabel" label.

func (QueuecumberState) WorkerTwoLabel 

func (state QueuecumberState) WorkerTwoLabel() string

WorkerTwoLabel is the "workerTwoLabel" label.

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.