events

package
v2.22.0 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: GPL-3.0 Imports: 9 Imported by: 0

Documentation

Overview

Package events manages global, transient UI requests. It owns presentation lifecycle and response arbitration; callers retain ownership of domain work.

Index

Constants

View Source
const (
	MaxTitleBytes   = 512
	MaxMessageBytes = 16 * 1024
	MaxChoices      = 1000
	MaxLabelBytes   = 512
)

Variables

View Source
var (
	ErrClosed         = errors.New("UI event service is closed")
	ErrNoActiveEvent  = errors.New("no active UI event")
	ErrEventNotActive = errors.New("UI event is not active")
	ErrInvalidKind    = errors.New("invalid UI event kind")
	ErrInvalidAction  = errors.New("invalid UI response action")
	ErrNotDismissible = errors.New("UI event is not dismissible")
	ErrChoiceRequired = errors.New("choice ID is required")
	ErrChoiceNotFound = errors.New("UI choice was not found")
	ErrInvalidRequest = errors.New("invalid UI event request")
	ErrInvalidOutcome = errors.New("invalid UI event outcome")
	ErrEventExpired   = errors.New("UI event has expired")
)

Functions

func RendersKind added in v2.21.0

func RendersKind(r Renderer, kind models.UIEventKind) bool

RendersKind reports whether r exists and shows events of kind. A nil renderer shows nothing; one that does not say which kinds it shows is assumed to show them all.

func RendersOverMedia added in v2.21.0

func RendersOverMedia(r Renderer) bool

RendersOverMedia reports whether r can show an event while media is running without disturbing it. A nil renderer shows nothing.

Types

type Choice

type Choice struct {
	Value any
	// Media names the local game the choice stands for, nil when it is not
	// a game. It is public and copied into the event.
	Media *models.UIChoiceMedia
	Label string
	// Current marks the choice standing for what is open now. Only host
	// widgets show it; it is not part of the public event.
	Current bool
}

Choice combines public display text with a private caller-owned value. Value is returned only to producer and is never serialized into public event.

type Handle

type Handle struct {
	Results        <-chan Result
	ID             string
	MinimumDisplay time.Duration
	// contains filtered or unexported fields
}

Handle lets producer update or complete request it opened.

func (*Handle) Complete

func (h *Handle) Complete(outcome models.UIOutcome) error

Complete resolves event from producer side. Completing stale/superseded handle is harmless so deferred loader cleanup remains safe.

func (*Handle) Update

func (h *Handle) Update(update Update) error

Update changes active event. Updating stale handle is reported to caller.

type HandoffRenderer added in v2.22.0

type HandoffRenderer interface {
	HandOffUI(ctx context.Context, event *models.UIEvent) (handled bool, minOpen time.Duration)
}

HandoffRenderer is optionally implemented by a Renderer that at times leaves events to API clients drawing on the same screen, such as a frontend that runs in place of the host's own UI. HandOffUI is asked in place of PresentUI. handled reports that the event is left to clients and must not be presented. When the clients first need the screen, as when running media has to give way to them, HandOffUI does that and returns the least time the event must stay open from now so a client can start and draw it; otherwise minOpen is zero.

type KindRenderer added in v2.21.0

type KindRenderer interface {
	RendersUIKind(models.UIEventKind) bool
}

KindRenderer is optionally implemented by a Renderer that shows only some kinds of event, so callers can tell whether a kind will reach the screen. A Renderer without it is taken to show every kind.

type OverMediaRenderer added in v2.21.0

type OverMediaRenderer interface {
	RendersOverMedia() bool
}

OverMediaRenderer is optionally implemented by a Renderer that cannot show an event while media is running without disturbing it, such as one whose display replaces the running program. A Renderer without it is taken to show events over running media without harm.

type Publisher

type Publisher func(models.UIStateResponse)

Publisher broadcasts an authoritative UI state snapshot.

type Renderer

type Renderer interface {
	PresentUI(context.Context, *models.UIEvent) (closeFn func() error, err error)
}

Renderer presents UI events on the host platform. Renderer failure never cancels an event because remote clients remain valid fallback renderers.

type Request

type Request struct {
	Kind    models.UIEventKind
	Title   string
	Message string
	Choices []Choice
	// SelectedChoice is picker choice index. Zero selects first choice; use -1
	// explicitly when no choice should be preselected.
	SelectedChoice int
	Timeout        time.Duration
	Dismissible    bool
	// SkipHostRenderer keeps the request available to API clients without
	// presenting it through the platform renderer.
	SkipHostRenderer bool
}

Request describes one transient UI interaction. A positive Timeout creates authoritative expiry; zero or negative values leave event open until resolved.

type Result

type Result struct {
	Value      any
	Resolution models.UIResolution
}

Result is delivered once when an external response, timeout, cancellation, or supersession resolves request. Value contains private selected choice value.

type Service

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

Service owns current global UI event and arbitrates all terminal outcomes.

func New

func New(clock clockwork.Clock, renderer Renderer, publish Publisher) *Service

New creates UI event service. Nil clock uses real time. Renderer and publisher may be nil for headless use and tests.

func (*Service) Cancel

func (s *Service) Cancel(id string) error

Cancel resolves active event and notifies producer.

func (*Service) Open

func (s *Service) Open(ctx context.Context, request *Request) (*Handle, error)

Open replaces current request, if any, and returns producer handle.

func (*Service) Respond

func (s *Service) Respond(id string, action models.UIResponseAction, choiceID string) error

Respond atomically resolves current event from API or host renderer input.

func (*Service) Shutdown

func (s *Service) Shutdown()

Shutdown prevents new events and cancels active request, if present.

func (*Service) State

func (s *Service) State() models.UIStateResponse

State returns immutable current snapshot. Resolved is always empty for query.

func (*Service) Update

func (s *Service) Update(id string, update Update) error

Update changes one active event and publishes newer revision.

type TimedRenderer

type TimedRenderer interface {
	MinimumUIDisplay(models.UIEventKind) time.Duration
}

TimedRenderer reports minimum time a producer should keep a newly presented event open before completing it. This accommodates host UI startup latency.

type Update

type Update struct {
	Title       *string
	Message     *string
	Timeout     *time.Duration
	Dismissible *bool
}

Update changes presentation of active event while preserving its ID. Nil fields remain unchanged. A non-positive Timeout removes authoritative expiry.

type UpdatingRenderer

type UpdatingRenderer interface {
	UpdateUI(context.Context, *models.UIEvent) error
}

UpdatingRenderer optionally applies producer updates to an existing host UI.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL