console

package
v0.139.1 Latest Latest
Warning

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

 Go to latest Published: Oct 2, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package console contains instance-owned operator console contracts. It has no dependency on Debug, admin routing, or application services.

Index

Constants

View Source 
const (
	EventUpsert     = "upsert"
	EventDelete     = "delete"
	EventInvalidate = "invalidate"
)
View Source 
const (
	// PanelUISchemaVersion is the current declarative panel UI schema version.
	PanelUISchemaVersion = "1"

	PanelRendererMetrics    = "metrics"
	PanelRendererKeyValue   = "key_value"
	PanelRendererIdentity   = "identity"
	PanelRendererTable      = "table"
	PanelRendererStatusList = "status_list"
	PanelRendererTimeline   = "timeline"
	PanelRendererJSON       = "json"
	PanelRendererStack      = "stack"

	// PanelStackLayoutGrid flows a stack view's sections into responsive
	// columns instead of stacking each section at full width.
	PanelStackLayoutGrid = "grid"

	PanelCountArrayLength = "array_length"
	PanelCountObjectKeys  = "object_keys"
	PanelCountTruthy      = "truthy"
	PanelCountNumber      = "number"

	PanelFilterSearch   = "search"
	PanelFilterSelect   = "select"
	PanelFilterCheckbox = "checkbox"

	PanelEventReplace = "replace"
	PanelEventAppend  = "append"
	PanelEventMerge   = "merge"
	PanelEventUpsert  = "upsert"

	PanelActionLayoutList   = "list"
	PanelActionLayoutSelect = "select"
)
View Source 
const MaxWireCounter uint64 = 1<<53 - 1

MaxWireCounter keeps counters exactly representable by browser JSON numbers.

Variables

View Source 
var (
	ErrClosed       = errors.New("console closed")
	ErrInvalidEvent = errors.New("invalid console event")
	ErrCapacity     = errors.New("console stream capacity reached")
)

Functions

func PanelDefinitionHasAction 

func PanelDefinitionHasAction(def PanelDefinition, actionID string) bool

PanelDefinitionHasAction reports whether a request-scoped panel definition exposes an action.

Types

type Bootstrap 

type Bootstrap struct {
	Identity
	Title                string   `json:"title"`
	URLs                 Routes   `json:"urls"`
	PreferencesNamespace string   `json:"preferences_namespace"`
	Snapshot             Snapshot `json:"snapshot"`
}

type Event 

type Event struct {
	Identity
	PanelID string `json:"panel_id"`
	Record
	Sequence uint64 `json:"sequence"`
	Kind     string `json:"kind"`
}

Event revisions and sequences are issued by an instance EventStream. Invalidate signals authoritative snapshot recovery, including buffer/retention loss.

type EventStream 

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

EventStream is a bounded, instance-owned fanout. Providers publish complete actor/scope projections, never unscoped broadcasts. It assigns revisions and watermarks, retaining tombstones to reject old-generation resurrection.

func NewEventStream 

func NewEventStream(consoleID string, capacity int) *EventStream

func (*EventStream) Close 

func (s *EventStream) Close() error

func (*EventStream) Publish 

func (s *EventStream) Publish(event Event) (Event, error)

Publish assigns Sequence. Revision may be supplied by a trusted service's canonical store, or assigned here when the stream is the revision authority. Data is detached as JSON so retained/delivered records cannot alias providers.

func (*EventStream) Subscribe 

func (s *EventStream) Subscribe(identity Identity, buffer int) (<-chan Event, func(), error)

func (*EventStream) Watermark 

func (s *EventStream) Watermark(identity Identity) uint64

type Identity 

type Identity struct {
	ConsoleID     string `json:"console_id"`
	ApplicationID string `json:"application_id"`
	EnvironmentID string `json:"environment_id"`
	ActorID       string `json:"actor_id"`
	ScopeKey      string `json:"scope_key"`
}

Identity is resolved from trusted host state, never from a request payload. Every field participates in cache, preference and delivery isolation.

func (Identity) Namespace 

func (i Identity) Namespace() string

Namespace is an unambiguous storage key, including when IDs contain separators.

func (Identity) Valid 

func (i Identity) Valid() bool

type LookupSource 

type LookupSource func(context.Context, Identity, string, string) (Record, bool, error)

type PanelActionEvent 

type PanelActionEvent struct {
	Type    string `json:"type"`
	Payload any    `json:"payload,omitempty"`
}

PanelActionEvent allows action results to be applied like a live event.

type PanelActionHandler 

type PanelActionHandler func(ctx context.Context, req PanelActionRequest) (PanelActionResult, error)

PanelActionHandler executes a console panel action. Dispatch still requires the action to be present in the request-scoped panel definition.

type PanelActionHandlerResolver 

type PanelActionHandlerResolver func(ctx context.Context, actionID string) PanelActionHandler

PanelActionHandlerResolver resolves handlers whose action set is backed by request-scoped or mutable provider state. The collector still requires the action to be present in the current request-scoped panel definition before invoking a resolved handler.

type PanelActionRequest 

type PanelActionRequest struct {
	PanelID  string         `json:"panel_id"`
	ActionID string         `json:"action_id"`
	Payload  map[string]any `json:"payload,omitempty"`
}

PanelActionRequest is sent to a registered action handler.

type PanelActionResult 

type PanelActionResult struct {
	OK      bool              `json:"ok"`
	Message string            `json:"message,omitempty"`
	Data    any               `json:"data,omitempty"`
	Refresh bool              `json:"refresh,omitempty"`
	Event   *PanelActionEvent `json:"event,omitempty"`
	Errors  map[string]any    `json:"errors,omitempty"`
}

PanelActionResult is returned by panel action handlers.

type PanelClearCheckFunc 

type PanelClearCheckFunc func(ctx context.Context) error

PanelClearCheckFunc performs an authorization-only clear preflight.

type PanelClearFunc 

type PanelClearFunc func(ctx context.Context) error

PanelClearFunc clears panel state when requested by the client.

type PanelConfig 

type PanelConfig struct {
	Label           string                        `json:"label"`
	Icon            string                        `json:"icon"`
	Span            int                           `json:"span"`
	SnapshotKey     string                        `json:"snapshot_key"`
	EventType       string                        `json:"event_type"`
	EventTypes      []string                      `json:"event_types"`
	Snapshot        PanelSnapshotFunc             `json:"snapshot"`
	ClearCheck      PanelClearCheckFunc           `json:"-"`
	Clear           PanelClearFunc                `json:"clear"`
	SupportsToolbar *bool                         `json:"supports_toolbar"`
	Category        string                        `json:"category"`
	Order           int                           `json:"order"`
	Version         string                        `json:"version"`
	Metadata        map[string]any                `json:"metadata"`
	UI              *PanelUI                      `json:"ui,omitempty"`
	Definition      PanelDefinitionFilter         `json:"-"`
	Actions         map[string]PanelActionHandler `json:"-"`
	ActionResolver  PanelActionHandlerResolver    `json:"-"`
}

PanelConfig configures a server-side console panel registration.

type PanelDefinition 

type PanelDefinition struct {
	ID              string         `json:"id"`
	Label           string         `json:"label"`
	Icon            string         `json:"icon,omitempty"`
	Span            int            `json:"span,omitempty"`
	SnapshotKey     string         `json:"snapshot_key"`
	EventTypes      []string       `json:"event_types,omitempty"`
	SupportsToolbar bool           `json:"supports_toolbar"`
	Category        string         `json:"category,omitempty"`
	Order           int            `json:"order,omitempty"`
	Version         string         `json:"version,omitempty"`
	Metadata        map[string]any `json:"metadata,omitempty"`
	UI              *PanelUI       `json:"ui,omitempty"`
}

PanelDefinition describes a registered panel for client discovery.

type PanelDefinitionFilter 

type PanelDefinitionFilter func(ctx context.Context, definition PanelDefinition) PanelDefinition

PanelDefinitionFilter adapts panel discovery metadata for a request context.

type PanelRegistration 

type PanelRegistration struct {
	Definition     PanelDefinition               `json:"definition"`
	Filter         PanelDefinitionFilter         `json:"-"`
	Snapshot       PanelSnapshotFunc             `json:"snapshot"`
	ClearCheck     PanelClearCheckFunc           `json:"-"`
	Clear          PanelClearFunc                `json:"clear"`
	Actions        map[string]PanelActionHandler `json:"-"`
	ActionResolver PanelActionHandlerResolver    `json:"-"`
}

PanelRegistration stores definition metadata and server hooks.

func (PanelRegistration) ActionHandlerForContext 

func (r PanelRegistration) ActionHandlerForContext(ctx context.Context, actionID string) PanelActionHandler

ActionHandlerForContext returns a handler only when the action is exposed by the current request-scoped definition. Fixed handlers are preferred; the resolver is consulted only when no fixed handler matches.

func (PanelRegistration) DefinitionForContext 

func (r PanelRegistration) DefinitionForContext(ctx context.Context) PanelDefinition

DefinitionForContext returns this registration's definition adapted for a request context.

type PanelRegistry 

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

PanelRegistry stores registered panels and metadata.

func NewPanelRegistry 

func NewPanelRegistry() *PanelRegistry

NewPanelRegistry creates an empty panel registry.

func (*PanelRegistry) DefinitionForContext 

func (r *PanelRegistry) DefinitionForContext(ctx context.Context, id string) (PanelDefinition, bool)

DefinitionForContext returns a panel definition adapted for a request context.

func (*PanelRegistry) Definitions 

func (r *PanelRegistry) Definitions() []PanelDefinition

Definitions returns a sorted list of registered panel definitions.

func (*PanelRegistry) DefinitionsWithContext 

func (r *PanelRegistry) DefinitionsWithContext(ctx context.Context) []PanelDefinition

DefinitionsWithContext returns a sorted list of context-adapted panel definitions.

func (*PanelRegistry) PanelsForEventType 

func (r *PanelRegistry) PanelsForEventType(eventType string) []string

PanelsForEventType returns panel IDs that subscribe to an event type.

func (*PanelRegistry) Register 

func (r *PanelRegistry) Register(id string, config PanelConfig) error

Register registers a panel in the registry.

func (*PanelRegistry) Registration 

func (r *PanelRegistry) Registration(id string) (PanelRegistration, bool)

Registration returns a panel registration by ID.

func (*PanelRegistry) Registrations 

func (r *PanelRegistry) Registrations() []PanelRegistration

Registrations returns a sorted list of panel registrations.

func (*PanelRegistry) SetVersion 

func (r *PanelRegistry) SetVersion(version string)

SetVersion updates the registry version identifier.

func (*PanelRegistry) Unregister 

func (r *PanelRegistry) Unregister(id string)

Unregister removes a panel from the registry.

func (*PanelRegistry) Version 

func (r *PanelRegistry) Version() string

Version returns the registry version identifier.

type PanelSnapshot 

type PanelSnapshot struct {
	PanelDefinition
	Records []Record `json:"records"`
}

type PanelSnapshotFunc 

type PanelSnapshotFunc func(ctx context.Context) any

PanelSnapshotFunc returns snapshot payloads for a panel.

type PanelUI 

type PanelUI struct {
	SchemaVersion string               `json:"schema_version"`
	Views         PanelUIViews         `json:"views"`
	Count         *PanelUICount        `json:"count,omitempty"`
	Filters       []PanelUIFilter      `json:"filters,omitempty"`
	Events        *PanelUIEventPolicy  `json:"events,omitempty"`
	ActionLayout  *PanelUIActionLayout `json:"action_layout,omitempty"`
	Actions       []PanelUIAction      `json:"actions,omitempty"`
	Metadata      map[string]any       `json:"metadata,omitempty"`
}

PanelUI is a JSON-safe declarative UI schema for Go-registered panels.

func NewPanelUI 

func NewPanelUI(console, toolbar *PanelUIView) *PanelUI

NewPanelUI creates a panel UI schema with optional console and toolbar views.

type PanelUIAction 

type PanelUIAction struct {
	ID              string               `json:"id"`
	Label           string               `json:"label"`
	SubmitLabel     string               `json:"submit_label,omitempty"`
	Kind            string               `json:"kind,omitempty"`
	ConfirmText     string               `json:"confirm_text,omitempty"`
	RequiresConfirm bool                 `json:"requires_confirm,omitempty"`
	Hidden          bool                 `json:"hidden,omitempty"`
	Refresh         bool                 `json:"refresh,omitempty"`
	UpdatePolicy    string               `json:"update_policy,omitempty"`
	Payload         map[string]any       `json:"payload,omitempty"`
	Fields          []PanelUIActionField `json:"fields,omitempty"`
	Form            *PanelUIActionForm   `json:"form,omitempty"`
}

PanelUIAction declares a UI action backed by a Go handler.

type PanelUIActionField 

type PanelUIActionField struct {
	Name         string                     `json:"name"`
	Label        string                     `json:"label,omitempty"`
	Kind         string                     `json:"kind,omitempty"`
	PayloadPath  string                     `json:"payload_path,omitempty"`
	Placeholder  string                     `json:"placeholder,omitempty"`
	Description  string                     `json:"description,omitempty"`
	Help         string                     `json:"help,omitempty"`
	Required     bool                       `json:"required,omitempty"`
	Sensitive    bool                       `json:"sensitive,omitempty"`
	Options      []string                   `json:"options,omitempty"`
	OptionItems  []PanelUIActionOption      `json:"option_items,omitempty"`
	OptionSource *PanelUIActionOptionSource `json:"option_source,omitempty"`
	Default      any                        `json:"default,omitempty"`
	DisplayHints map[string]any             `json:"display_hints,omitempty"`
}

PanelUIActionField declares a typed input that is merged into an action payload.

type PanelUIActionForm 

type PanelUIActionForm struct {
	Renderer     string `json:"renderer"`
	OperationID  string `json:"operation_id"`
	HTML         string `json:"html"`
	ModelVersion string `json:"model_version,omitempty"`
	Sensitive    bool   `json:"sensitive,omitempty"`
}

PanelUIActionForm carries trusted server-generated form markup. HTML must be produced by the named renderer; callers must never place operator-authored or command-authored raw markup in this contract.

type PanelUIActionLayout 

type PanelUIActionLayout struct {
	Mode        string `json:"mode,omitempty"`
	PickerLabel string `json:"picker_label,omitempty"`
	EmptyText   string `json:"empty_text,omitempty"`
}

PanelUIActionLayout declares how panel actions are presented.

type PanelUIActionOption 

type PanelUIActionOption struct {
	Value       string         `json:"value"`
	Label       string         `json:"label,omitempty"`
	Description string         `json:"description,omitempty"`
	Disabled    bool           `json:"disabled,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

PanelUIActionOption preserves a stable submitted value separately from its operator-facing label and guidance. Options remains available on the field as a legacy value-only projection for older debug clients.

type PanelUIActionOptionSource 

type PanelUIActionOptionSource struct {
	ID         string         `json:"id"`
	Label      string         `json:"label,omitempty"`
	Dynamic    bool           `json:"dynamic,omitempty"`
	CacheScope string         `json:"cache_scope,omitempty"`
	Params     map[string]any `json:"params,omitempty"`
}

PanelUIActionOptionSource describes a request-scoped option source that the client may refresh. Params is declarative and JSON-safe; source execution is still authorized and matched to the registered command descriptor server-side.

type PanelUIColumn 

type PanelUIColumn struct {
	Label    string `json:"label"`
	Bind     string `json:"bind"`
	Format   string `json:"format,omitempty"`
	Width    string `json:"width,omitempty"`
	Severity string `json:"severity,omitempty"`
}

PanelUIColumn declares a table column option.

type PanelUICount 

type PanelUICount struct {
	Bind  string `json:"bind,omitempty"`
	Mode  string `json:"mode,omitempty"`
	Label string `json:"label,omitempty"`
}

PanelUICount declares badge/count behavior.

type PanelUIEventPolicy 

type PanelUIEventPolicy struct {
	Mode       string `json:"mode"`
	Bind       string `json:"bind,omitempty"`
	Key        string `json:"key,omitempty"`
	MaxEntries int    `json:"max_entries,omitempty"`
}

PanelUIEventPolicy declares how live events update panel data.

type PanelUIField 

type PanelUIField struct {
	Label  string `json:"label"`
	Bind   string `json:"bind"`
	Format string `json:"format,omitempty"`
	Empty  string `json:"empty,omitempty"`
}

PanelUIField declares a key/value field option.

type PanelUIFilter 

type PanelUIFilter struct {
	ID      string   `json:"id"`
	Label   string   `json:"label"`
	Kind    string   `json:"kind"`
	Bind    string   `json:"bind,omitempty"`
	Options []string `json:"options,omitempty"`
}

PanelUIFilter declares a client-side console filter.

type PanelUIMetric 

type PanelUIMetric struct {
	Label    string `json:"label"`
	Bind     string `json:"bind"`
	Format   string `json:"format,omitempty"`
	Severity string `json:"severity,omitempty"`
}

PanelUIMetric declares a metric tile option.

type PanelUIView 

type PanelUIView struct {
	Renderer string         `json:"renderer"`
	Title    string         `json:"title,omitempty"`
	Bind     string         `json:"bind,omitempty"`
	Options  map[string]any `json:"options,omitempty"`
	Sections []PanelUIView  `json:"sections,omitempty"`
}

PanelUIView declares one renderer instance. Stack views may use Sections.

func GridStackView 

func GridStackView(sections ...PanelUIView) *PanelUIView

GridStackView creates a stack view whose sections flow into responsive columns instead of stacking at full width.

func IdentityView 

func IdentityView(bind string) *PanelUIView

IdentityView creates a summary identity renderer view. It presents one primary title with an optional accent color, eyebrow, subtitle, and supporting chips so a panel can lead with the value operators scan first.

func JSONView 

func JSONView(bind string) *PanelUIView

JSONView creates a JSON fallback renderer view.

func KeyValueView 

func KeyValueView(bind string) *PanelUIView

KeyValueView creates a key/value renderer view.

func MetricsView 

func MetricsView(bind string) *PanelUIView

MetricsView creates a metrics renderer view.

func PanelView 

func PanelView(renderer, bind string) *PanelUIView

PanelView creates a renderer view bound to a payload path.

func StackView 

func StackView(sections ...PanelUIView) *PanelUIView

StackView creates a stack renderer view with child sections.

func StatusListView 

func StatusListView(bind string) *PanelUIView

StatusListView creates a status list renderer view.

func TableView 

func TableView(bind string) *PanelUIView

TableView creates a table renderer view.

func TimelineView 

func TimelineView(bind string) *PanelUIView

TimelineView creates a timeline renderer view.

type PanelUIViews 

type PanelUIViews struct {
	Console *PanelUIView `json:"console,omitempty"`
	Toolbar *PanelUIView `json:"toolbar,omitempty"`
}

PanelUIViews declares console and toolbar renderers.

type Record 

type Record struct {
	Key        string `json:"record_key"`
	TargetID   string `json:"target_id,omitempty"`
	Generation uint64 `json:"generation,omitempty"`
	Revision   uint64 `json:"revision"`
	Data       any    `json:"data,omitempty"`
}

type Routes 

type Routes struct {
	Page        string `json:"page"`
	Panels      string `json:"panels"`
	Snapshot    string `json:"snapshot"`
	Action      string `json:"actions"`
	Preferences string `json:"preferences"`
	Live        string `json:"live"`
	Lookup      string `json:"lookup"`
}

Routes are resolved by the host's URL manager and passed verbatim to clients.

type Snapshot 

type Snapshot struct {
	Identity
	Watermark uint64          `json:"watermark"`
	Panels    []PanelSnapshot `json:"panels"`
}

type SnapshotSource 

type SnapshotSource func(context.Context, Identity, string) ([]Record, error)

SnapshotSource supplies canonical records. The host filters every record before returning it; opaque panel payloads must be represented as a single Record.

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.