console

package
v0.140.1 Latest Latest
Warning

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

 Go to latest Published: Oct 11, 2026 License: MIT Imports: 10 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 (
	// ClientCapabilityActionAvailability renders unavailable declarations
	// disabled with their reason and never dispatches them.
	ClientCapabilityActionAvailability = "action_availability.v1"
	// ClientCapabilityActionDrawer opens forms from header/section/row/card slots.
	ClientCapabilityActionDrawer = "action_drawer.v1"
	// ClientCapabilityRequestID generates request IDs per action draft and
	// keeps submitted requests, their payloads and pending state (ADR-0003).
	ClientCapabilityRequestID = "request_id.v1"
	// ClientCapabilitySecondarySubmit honors the actual submitter, sets the
	// declared field and treats each submitter as a distinct request.
	ClientCapabilitySecondarySubmit = "secondary_submit.v1"
	// ClientCapabilityRichViews renders tones, steps, cards, lists and refs.
	ClientCapabilityRichViews = "rich_views.v1"

	// ClientCapabilitiesHeader carries the advertised set on HTTP requests;
	// ClientCapabilitiesQuery carries it on the live socket URL.
	ClientCapabilitiesHeader = "X-Console-Capabilities"
	ClientCapabilitiesQuery  = "capabilities"
)

Client capabilities (ADR-0004). A client advertises the workflow behavior it implements; declarations needing more stay non-executable for that client. The handshake is compatibility metadata, never actor authorization.

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"
	// PanelRendererCards renders one record card per row (title, status,
	// metadata fields and an action slot). Options: title_bind, subtitle_bind,
	// status_bind, tone_bind, fields, actions_bind, max_cards and columns (the
	// compact table used once rows exceed max_cards).
	PanelRendererCards = "cards"
	// PanelRendererList renders compact record rows (title, subtitle, status,
	// progress, time and an action slot). Options: title_bind, subtitle_bind,
	// status_bind, tone_bind, progress_bind, time_bind, actions_bind and limit.
	PanelRendererList = "list"

	// 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"
	// PanelCountMatchingRows counts list rows whose bound field is truthy (an
	// attention badge); ToneBind names a row tone, the most severe one wins.
	PanelCountMatchingRows = "matching_rows"
	// PanelCountNone shows no tab count.
	PanelCountNone = "none"

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

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

	PanelActionLayoutList   = "list"
	PanelActionLayoutSelect = "select"
	// PanelActionLayoutDrawer opens action forms from header, section, row and
	// card action slots instead of rendering them inline.
	PanelActionLayoutDrawer = "drawer"
)
View Source 
const (
	PanelActionAvailable    = "available"
	PanelActionUnsupported  = "unsupported"
	PanelActionNotPermitted = "not_permitted"
	PanelActionUnavailable  = "unavailable"
)

Action availability. An empty value is available, which keeps existing schema-v1 definitions executable. Any other value is display metadata only: it never grants dispatch, and the console refuses to run it.

View Source 
const (
	PanelFormatText      = "text"
	PanelFormatBadge     = "badge"
	PanelFormatMono      = "mono"
	PanelFormatCopy      = "copy"
	PanelFormatColor     = "color"
	PanelFormatNumber    = "number"
	PanelFormatBoolean   = "boolean"
	PanelFormatTimestamp = "timestamp"
	PanelFormatDateTime  = "datetime"
	PanelFormatRelative  = "relative"
	// PanelFormatSteps renders a value that is an ordered []PanelUIStep.
	PanelFormatSteps = "steps"
	// PanelFormatProgress renders a value that is a PanelUIProgress.
	PanelFormatProgress = "progress"
)

Value formats shared by table columns, key/value fields, cards and lists. Unknown formats render as escaped text.

View Source 
const (
	PanelToneSuccess = "success"
	PanelToneInfo    = "info"
	PanelToneWarning = "warning"
	PanelToneError   = "error"
	PanelToneNeutral = "neutral"
	// PanelTonePlanned marks planned or dry-run work so it never reads as executed.
	PanelTonePlanned = "planned"
)

Server-computed tones. Records carry a tone next to the label they color (columns name it with tone_bind); unknown tones render neutral.

View Source 
const (
	PanelStepDone    = "done"
	PanelStepCurrent = "current"
	PanelStepPending = "pending"
	PanelStepWarning = "warning"
	PanelStepFailed  = "failed"
)

Generic step states. Domain code projects labels and states; the console never infers lifecycle meaning from them.

View Source 
const (
	PanelActionEmphasisPrimary = "primary"
	PanelActionEmphasisDefault = "default"
	PanelActionEmphasisMenu    = "menu"
)

Action reference emphasis inside an action slot.

View Source 
const (
	// PanelFieldGenerateRequestID asks the client to generate a request ID
	// for the action draft (ADR-0003). Definitions never carry its value.
	PanelFieldGenerateRequestID = "request_id"
	// PanelFieldKindHidden is a declared field the client never renders; a
	// submitter sets it (see PanelUIActionSubmit) or its default is sent.
	PanelFieldKindHidden = "hidden"
)
View Source 
const (
	PanelOptionPageDefault = 25
	PanelOptionPageMax     = 100
	PanelOptionSearchMax   = 120
	PanelOptionCursorMax   = 512
	PanelOptionValuesMax   = 10
	PanelRequestIDMax      = 128
	PanelRequestScopeMax   = 200
)

Bounds for the options and request-status routes.

View Source 
const (
	// PanelRequestClaimed: the request was received; Result describes it.
	PanelRequestClaimed = "claimed"
	// PanelRequestUnclaimed: no claim exists for this request ID within the
	// retry window, so resubmitting the unchanged request cannot duplicate work.
	PanelRequestUnclaimed = "unclaimed"
	// PanelRequestExpired: the retry window or claim authority is gone; only
	// explicit new work may follow.
	PanelRequestExpired = "expired"
	// PanelRequestUnknown: the claim could not be determined now; keep the
	// request pending and never restart it automatically.
	PanelRequestUnknown = "unknown"
)

Pending request states (ADR-0003 reconciliation).

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 ClientCapabilityIDs added in v0.139.2 

func ClientCapabilityIDs() []string

ClientCapabilityIDs lists the workflow capabilities this release defines, sorted. A client advertises the subset it implements.

func NormalizePanelTone added in v0.139.2 

func NormalizePanelTone(value string) string

NormalizePanelTone returns an allowlisted tone, or "" when unknown.

func PanelDefinitionHasAction 

func PanelDefinitionHasAction(def PanelDefinition, actionID string) bool

PanelDefinitionHasAction reports whether a request-scoped panel definition exposes an executable action. Unavailable declarations are display metadata and never count as exposed.

func ValidRequestID added in v0.139.2 

func ValidRequestID(value string) bool

ValidRequestID reports whether a generated request ID is a canonical UUID. Request IDs are idempotency keys, never credentials or correlation IDs.

func WithClientCapabilities added in v0.139.2 

func WithClientCapabilities(ctx context.Context, caps ClientCapabilities) context.Context

WithClientCapabilities attaches the request's handshake to its context.

Types

type Bootstrap 

type Bootstrap struct {
	Extensions map[string]any `json:"extensions,omitempty"`
	Identity
	Title                string   `json:"title"`
	URLs                 Routes   `json:"urls"`
	PreferencesNamespace string   `json:"preferences_namespace"`
	Snapshot             Snapshot `json:"snapshot"`
}

type ClientCapabilities added in v0.139.2 

type ClientCapabilities struct {
	Mode ClientCapabilityMode
	// contains filtered or unexported fields
}

ClientCapabilities is the parsed client handshake for one request.

func ClientCapabilitiesFromContext added in v0.139.2 

func ClientCapabilitiesFromContext(ctx context.Context) ClientCapabilities

ClientCapabilitiesFromContext returns the request's handshake, or a legacy client when none was attached.

func PageClientCapabilities added in v0.139.2 

func PageClientCapabilities() ClientCapabilities

PageClientCapabilities marks a server-rendered page bootstrap.

func ParseClientCapabilities added in v0.139.2 

func ParseClientCapabilities(value string) ClientCapabilities

ParseClientCapabilities reads a comma-separated advertised list. An empty or absent value is a legacy client. Unknown entries are kept (bounded) so newer requirements are compared exactly.

func (ClientCapabilities) Covers added in v0.139.2 

func (c ClientCapabilities) Covers(required []string) bool

Covers reports whether an advertised client implements every requirement. Declarations without requirements are covered for every client.

func (ClientCapabilities) Has added in v0.139.2 

func (c ClientCapabilities) Has(capability string) bool

Has reports whether an advertised client implements one capability.

func (ClientCapabilities) List added in v0.139.2 

func (c ClientCapabilities) List() []string

List returns the advertised capabilities in sorted order.

type ClientCapabilityMode added in v0.139.2 

type ClientCapabilityMode string

ClientCapabilityMode states how a request described its client. 

const (
	// ClientCapabilitiesLegacy: no handshake. Capability-dependent and
	// unavailable declarations are withheld; dispatch of them is refused.
	ClientCapabilitiesLegacy ClientCapabilityMode = "legacy"
	// ClientCapabilitiesAdvertised: the request listed its capabilities.
	ClientCapabilitiesAdvertised ClientCapabilityMode = "advertised"
	// ClientCapabilitiesPage: a server-rendered page bootstrap. Declarations are
	// included and the client gates them itself; dispatch still requires an
	// advertised handshake, so stale cached assets cannot execute them.
	ClientCapabilitiesPage ClientCapabilityMode = "page"
)

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"`
	// Tone colors the result banner (allowlisted PanelTone* values).
	Tone string `json:"tone,omitempty"`
	// Code is a safe machine code for a typed failure, never provider text.
	Code string `json:"code,omitempty"`
	// Planned marks dry-run/planned outcomes so they never read as executed.
	Planned bool `json:"planned,omitempty"`
	// Record is the row the outcome concerns (link and highlight).
	Record *PanelUIRecordRef `json:"record,omitempty"`
	// FollowUp lists declared actions the actor may take next.
	FollowUp []PanelUIActionRef `json:"follow_up,omitempty"`
}

PanelActionResult is returned by panel action handlers. Tone, Code, Planned, Record and FollowUp are additive outcome metadata for result banners.

func NormalizePanelActionResult added in v0.139.2 

func NormalizePanelActionResult(result PanelActionResult) PanelActionResult

NormalizePanelActionResult sanitizes outcome metadata before delivery.

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:"-"`
	// Options serves paginated option sources of this panel's action fields.
	Options PanelOptionResolver `json:"-"`
	// Requests answers pending-request lookups for this panel's actions.
	Requests PanelRequestResolver `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 PanelOptionPage added in v0.139.2 

type PanelOptionPage struct {
	Items      []PanelUIActionOption `json:"items"`
	NextCursor string                `json:"next_cursor,omitempty"`
	Selected   []PanelUIActionOption `json:"selected,omitempty"`
}

PanelOptionPage is one page of options. Selected resolves requested Values that the actor may still use; unknown or unauthorized values are omitted.

func NormalizePanelOptionPage added in v0.139.2 

func NormalizePanelOptionPage(page PanelOptionPage, limit int) PanelOptionPage

NormalizePanelOptionPage bounds a resolver page to limit items and safe text.

type PanelOptionQuery added in v0.139.2 

type PanelOptionQuery struct {
	PanelID  string
	ActionID string
	Field    string
	Cursor   string
	Search   string
	Limit    int
	Values   []string
}

PanelOptionQuery asks for one bounded page of a declared field's options. Cursor is opaque and resolver-issued; Values asks the resolver to resolve already-selected values (for example an older retained receipt) without scanning every page. Identity comes from trusted context, never the query.

func NormalizePanelOptionQuery added in v0.139.2 

func NormalizePanelOptionQuery(query PanelOptionQuery) PanelOptionQuery

NormalizePanelOptionQuery bounds an options request.

type PanelOptionResolver added in v0.139.2 

type PanelOptionResolver func(ctx context.Context, query PanelOptionQuery) (PanelOptionPage, error)

PanelOptionResolver loads paginated options for executable actions only. It must apply current policy itself and stay bounded.

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:"-"`
	Options        PanelOptionResolver           `json:"-"`
	Requests       PanelRequestResolver          `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 PanelRequestQuery added in v0.139.2 

type PanelRequestQuery struct {
	PanelID     string
	ActionID    string
	RequestID   string
	Scope       string
	SubmittedAt time.Time
}

PanelRequestQuery looks up the current actor's own submitted request. The action may since have been withdrawn; Scope is the declaration's opaque RequestScope and selects nothing beyond the trusted actor/scope namespace. SubmittedAt is the client's own record of its first submission (zero when unknown). It is guidance for the retry window, never authority: a resolver reports unclaimed only while that window is still open, otherwise expired.

type PanelRequestResolver added in v0.139.2 

type PanelRequestResolver func(ctx context.Context, query PanelRequestQuery) (PanelRequestStatus, error)

PanelRequestResolver answers pending-request lookups under current policy.

type PanelRequestStatus added in v0.139.2 

type PanelRequestStatus struct {
	Status     string             `json:"status"`
	Message    string             `json:"message,omitempty"`
	Result     *PanelActionResult `json:"result,omitempty"`
	RetryUntil string             `json:"retry_until,omitempty"`
}

PanelRequestStatus reports a pending request without exposing stored keys, fingerprints or principals. RetryUntil is RFC 3339 UTC guidance.

func NormalizePanelRequestStatus added in v0.139.2 

func NormalizePanelRequestStatus(status PanelRequestStatus) PanelRequestStatus

NormalizePanelRequestStatus allowlists the status and sanitizes its result. Only a claimed request carries a result.

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"`
	// Availability is empty (available) or one of the PanelAction*
	// availability values. Unavailable declarations are display metadata.
	Availability string `json:"availability,omitempty"`
	// Reason is the safe, human-readable explanation for an unavailable action.
	Reason string `json:"reason,omitempty"`
	// Requires lists client capabilities this action needs. Normalization adds
	// the capabilities implied by generated fields, hidden fields, secondary
	// submits and unavailable availability.
	Requires     []string                   `json:"requires,omitempty"`
	Drawer       *PanelUIActionDrawer       `json:"drawer,omitempty"`
	Secondary    *PanelUIActionSubmit       `json:"secondary_submit,omitempty"`
	Confirmation *PanelUIActionConfirmation `json:"confirmation,omitempty"`
	// RequestScope is an opaque, non-secret, server-issued selector that a
	// client stores with a submitted request ID so the owner can find the
	// claim again (see PanelRequestQuery). It carries no authority.
	RequestScope string `json:"request_scope,omitempty"`
}

PanelUIAction declares a UI action backed by a Go handler.

func PanelDefinitionAction added in v0.139.2 

func PanelDefinitionAction(def PanelDefinition, actionID string) (PanelUIAction, bool)

PanelDefinitionAction returns the declaration for an action ID, whether or not it is executable.

func (PanelUIAction) Executable added in v0.139.2 

func (a PanelUIAction) Executable() bool

Executable reports whether the declaration may be dispatched. It does not authorize the actor; hosts and handlers still check current policy.

type PanelUIActionConfirmation added in v0.139.2 

type PanelUIActionConfirmation struct {
	Title        string          `json:"title,omitempty"`
	Message      string          `json:"message,omitempty"`
	Changes      []PanelUIChange `json:"changes,omitempty"`
	Note         string          `json:"note,omitempty"`
	ConfirmLabel string          `json:"confirm_label,omitempty"`
	Tone         string          `json:"tone,omitempty"`
}

PanelUIActionConfirmation is a structured confirmation for the admin modal. ConfirmText remains the plain-text fallback for older clients.

type PanelUIActionDrawer added in v0.139.2 

type PanelUIActionDrawer struct {
	Eyebrow    string          `json:"eyebrow,omitempty"`
	Title      string          `json:"title,omitempty"`
	Effect     string          `json:"effect,omitempty"`
	EffectTone string          `json:"effect_tone,omitempty"`
	Steps      []PanelUIStep   `json:"steps,omitempty"`
	Details    []PanelUIDetail `json:"details,omitempty"`
	Note       string          `json:"note,omitempty"`
}

PanelUIActionDrawer states what an action will do before it runs.

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"`
	// Advanced fields render inside the form's Advanced disclosure.
	Advanced bool `json:"advanced,omitempty"`
	// Generate names a client-side generator (PanelFieldGenerateRequestID).
	// Generated fields are read-only, required and never carry a default.
	Generate string `json:"generate,omitempty"`
	// Min and Max bound numeric fields for in-place validation. The handler
	// still validates every submitted value.
	Min *float64 `json:"min,omitempty"`
	Max *float64 `json:"max,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"`
	// Paginated options are loaded page by page from the console's options
	// route (PanelOptionResolver) instead of being embedded in the definition.
	Paginated bool `json:"paginated,omitempty"`
	// Searchable paginated sources accept a bounded search term.
	Searchable bool `json:"searchable,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 PanelUIActionRef added in v0.139.2 

type PanelUIActionRef struct {
	PanelID  string `json:"panel_id"`
	ActionID string `json:"action_id"`
	Emphasis string `json:"emphasis,omitempty"`
}

PanelUIActionRef names one declared action of the panel that renders it. Records carry references in the field a view names with actions_bind; the client resolves each one against the request-scoped definition, so it can neither invent availability nor execute an undeclared, withdrawn or foreign-panel reference. The action ID binds server-selected work.

func NormalizePanelActionRefs added in v0.139.2 

func NormalizePanelActionRefs(refs []PanelUIActionRef) []PanelUIActionRef

NormalizePanelActionRefs keeps well-formed, distinct action references. Projections use it before placing references in record data.

type PanelUIActionSubmit added in v0.139.2 

type PanelUIActionSubmit struct {
	Label string `json:"label"`
	Field string `json:"field"`
	Value any    `json:"value"`
}

PanelUIActionSubmit is an explicit secondary submitter, such as Preview plan. It sets one declared hidden or boolean field to Value; the primary submitter sends that field's default. Each submitter is its own request, so plan and execution never share a request ID.

type PanelUIChange added in v0.139.2 

type PanelUIChange struct {
	Label  string `json:"label"`
	Before string `json:"before,omitempty"`
	After  string `json:"after,omitempty"`
	Format string `json:"format,omitempty"`
}

PanelUIChange is a before/after pair shown before an action is confirmed.

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"`
	Tone     string `json:"tone,omitempty"`
	ToneBind string `json:"tone_bind,omitempty"`
}

PanelUICount declares badge/count behavior. Tone and ToneBind are additive badge colors; clients without them show a neutral count.

type PanelUIDetail added in v0.139.2 

type PanelUIDetail struct {
	Label  string `json:"label"`
	Value  string `json:"value,omitempty"`
	Format string `json:"format,omitempty"`
}

PanelUIDetail is a safe label/value pair shown by a drawer.

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 PanelUILink struct {
	Label   string `json:"label"`
	PanelID string `json:"panel_id"`
}

PanelUILink navigates to another panel of the same console.

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 PanelUIProgress added in v0.139.2 

type PanelUIProgress struct {
	Completed uint64 `json:"completed"`
	Total     uint64 `json:"total,omitempty"`
	Label     string `json:"label,omitempty"`
}

PanelUIProgress is bounded progress (format "progress").

type PanelUIRecordRef added in v0.139.2 

type PanelUIRecordRef struct {
	PanelID   string `json:"panel_id"`
	RecordKey string `json:"record_key"`
}

PanelUIRecordRef identifies one record of a panel, for example the row an action outcome affected.

type PanelUIStep added in v0.139.2 

type PanelUIStep struct {
	Label string `json:"label"`
	State string `json:"state,omitempty"`
	Tone  string `json:"tone,omitempty"`
}

PanelUIStep is one generic ordered step (format "steps").

func NormalizePanelSteps added in v0.139.2 

func NormalizePanelSteps(steps []PanelUIStep) []PanelUIStep

NormalizePanelSteps keeps labelled steps with allowlisted states and tones.

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"`
	// Description is a one-line section caption.
	Description string `json:"description,omitempty"`
	// Empty is the view's own empty-state guidance.
	Empty string `json:"empty,omitempty"`
	// Link navigates to another panel of the same console (for example "View all").
	Link *PanelUILink `json:"link,omitempty"`
	// Actions is the section header action slot.
	Actions []PanelUIActionRef `json:"actions,omitempty"`
}

PanelUIView declares one renderer instance. Stack views may use Sections. Description, Empty, Link and Actions are additive section metadata that older clients ignore.

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"`
	// Options serves paginated field options:
	// GET …/api/panels/:panel/actions/:action/options/:field?cursor=&q=&limit=&value=
	Options string `json:"options,omitempty"`
	// Requests answers pending-request lookups:
	// GET …/api/panels/:panel/requests/:request?action=&scope=&submitted_at=
	Requests string `json:"requests,omitempty"`
}

Routes are resolved by the host's URL manager and passed verbatim to clients. Options and Requests are additive; older clients ignore them.

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.