play

package
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Jun 17, 2026 License: MIT Imports: 67 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	SQLOverride = env.NewString(env.Spec{
		Name:        "SPINNAKER_PLAY_SQL",
		Description: "initial SQL buffer for the play HMI; non-empty wins over the persisted-session restore",
		Category:    env.CategoryE("spinnaker-play"),
	})

	TimelineBandsSQLOverride = env.NewString(env.Spec{
		Name:        "SPINNAKER_PLAY_TIMELINE_BANDS_SQL",
		Description: "panel-local bands SQL for the Timeline tab; non-empty wins over the persisted-session restore",
		Category:    env.CategoryE("spinnaker-play"),
	})

	AutoRun = env.NewString(env.Spec{
		Name:        "SPINNAKER_PLAY_AUTORUN",
		Description: "non-empty enables auto-run of the initial SQL on mount",
		Category:    env.CategoryE("spinnaker-play"),
	})

	ScreenshotPath = env.NewPath(env.Spec{
		Name:        "SPINNAKER_PLAY_SCREENSHOT",
		Description: "if set, the play HMI captures a screenshot to this path after the first frame",
		Category:    env.CategoryE("spinnaker-play"),
	})

	ExitOnShot = env.NewString(env.Spec{
		Name:        "SPINNAKER_PLAY_EXIT_ON_SHOT",
		Description: "non-empty exits the play HMI after writing SPINNAKER_PLAY_SCREENSHOT",
		Category:    env.CategoryE("spinnaker-play"),
	})
)

SPINNAKER_PLAY_* drive optional one-shot/scripted-screenshot behaviours on the play HMI. Registered with the boxer-wide env registry per ADR-0058.

Functions

func ExtractParamSlots 

func ExtractParamSlots(sql string) (slots []paramSlot, err error)

ExtractParamSlots walks sql via the Grammar1 parser and returns one paramSlot per ColumnExprParamSlot CST node. Duplicate names are returned with the first occurrence's Type and Src. Hot-path callers should prefer extractSlotsAndParams, which parses once and produces both the slot list and the prelude value map.

func ExtractParams 

func ExtractParams(sql string) (residual string, params map[string]string, err error)

ExtractParams parses sql and removes any top-level `SET` statement whose every setting name starts with `param_`, returning the residual SQL plus the harvested parameter values.

The values are the raw SQL literal texts of the right-hand side, with surrounding single quotes stripped from string literals so they can be shipped verbatim as ClickHouse HTTP `?param_<name>=<value>` URL fields.

Naming convention: ClickHouse maps URL key `param_<X>` to placeholder `{<X>:Type}` — the `param_` prefix is the URL-side marker, not part of the placeholder name. This pass passes SET names through verbatim, so `SET param_a=1; SELECT {a:UInt64}` is the canonical form. To use the placeholder `{param_a:Type}` literally, the SET must be `SET param_param_a=1`.

A SET statement that mixes `param_*` settings with non-`param_*` settings is rejected: partial deletion of individual settingExprs (with their commas) is fiddly and out of scope. SET statements that contain only non-`param_*` settings are left intact in the residual.

See ExecuteArrowStream's doc for the URL-length limits that bound how large the harvested values can collectively be.

func NewCliCommand 

func NewCliCommand() *cli.Command

func SyncParamPrelude 

func SyncParamPrelude(sql string, slots []paramSlot, values map[string]string) (out string, changed bool)

SyncParamPrelude rewrites the leading `SET param_*` block of sql so it exactly matches the widget-authored (name, value) pairs, in placeholder-occurrence order. Encoding is keyed off each slot's Type (numeric → verbatim if numeric-shape, compound → verbatim, other → single-quoted with escapes); see encodeParamLiteral.

Idempotent: returns (sql, false) when the existing prelude already matches the desired one. Returns (sql, false) on ExtractParams error — a transient keystroke that breaks the parse should not destroy the user's prelude.

Trailing prelude SETs whose name isn't in values are dropped on rewrite; this is how a deleted placeholder stops contributing to the prelude. Non-param SETs intermixed with param SETs are *not* preserved in the leading block — they may shift downward after a rewrite. In practice users keep non-param SETs in a trailing block; the play app's pristine output stays stable across re-syncs.

Types

type CardDriver 

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

CardDriver bridges the current Arrow schema to the leeway streamreadaccess.Driver + a Table2CardEmitter.

Two-stage caching:

  • The Driver + TableDesc are rebuilt only when the Arrow schema object changes (cheap pointer compare).
  • Each Render call walks a single-row slice of the record batch, producing the same Begin*/End* sequence the HtmlCardEmitter consumes, but emitting ImZero2 widgets through the Table2CardEmitter.

func NewCardDriver 

func NewCardDriver(ids *c.WidgetIdStack, alloc memory.Allocator) *CardDriver

NewCardDriver returns an empty driver. EnsureFor must be called before the first Render.

func (*CardDriver) Driver 

func (inst *CardDriver) Driver() *streamreadaccess.Driver

Driver returns the underlying leeway streamreadaccess.Driver iff the schema is leeway-shaped (EnsureFor returned true). Otherwise nil. Used by the Projector to drive a FeatureExtractor over the same record batch the card view consumes, so we don't pay for a second schema-discovery round.

func (*CardDriver) EnsureFor 

func (inst *CardDriver) EnsureFor(schema *arrow.Schema) bool

EnsureFor (re)builds the driver if the schema changed. Returns true iff the schema is leeway-shaped and Render can proceed.

func (*CardDriver) JSONFor 

func (inst *CardDriver) JSONFor(rec arrow.RecordBatch, row int64) (view typed.RetainedFffiHolderTyped[c.CodeViewJobS], ok bool, err error)

JSONFor returns a syntax-highlighted CodeViewJob holder for the canonical Leeway card-JSON of (rec, row), per ADR-0018. The retained holder is cached for the most-recently requested (rec, row); navigating rows or running a new query invalidates the slot. ok=false with err=nil means "not applicable" (driver not usable, nil rec, or out-of-range row) — caller should skip rendering. ok=false with err!=nil means encoding failed.

func (*CardDriver) Render 

func (inst *CardDriver) Render(rec arrow.RecordBatch, row int64) error

Render walks a single-row slice of rec through the Driver, which drives the Table2CardEmitter. The emitter pushes ImZero2 widgets into the current ui scope — call this inside a ScrollArea or Vertical container.

func (*CardDriver) SetTagClickHandler 

func (inst *CardDriver) SetTagClickHandler(fn func(display, detail string))

SetTagClickHandler wires a clipboard / filter pivot callback through to the emitter. Passing nil clears it. Note: Table2CardEmitter renders chips as comma-joined strings, so the callback never fires in practice — kept for API parity with the older two-emitter model.

type Client 

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

func NewClient 

func NewClient(cfg ClientConfig, httpClient *http.Client) *Client

func (*Client) ExecuteArrowStream 

func (inst *Client) ExecuteArrowStream(ctx context.Context, sql string, alloc memory.Allocator) (rdr *ipc.Reader, body io.Closer, summary Summary, err error)

ExecuteArrowStream rewrites the query's FORMAT clause to `ArrowStream` via the nanopass pipeline, POSTs it, and returns an ipc.Reader over the response body and the body closer. The caller must close the body after fully draining the reader.

Top-level `SET param_*=...` statements in sql are extracted by ExtractParams and shipped on the URL query string (`?param_<name>=<value>`); the residual SQL goes in the body. ClickHouse rejects multi-statement bodies, so this split is what makes a script like `SET param_a=1; SELECT {a:UInt64}` work over a single HTTP request.

Size limits

We do not use multipart/form-data, so the only relevant cap is the request URI cap. Concretely:

  • ClickHouse's `http_max_uri_size` (default 1 MiB) bounds the *total* URL length, including the URL-encoded param names and `&` separators. Exceeding it returns HTTP 414 / "URI is too long" from the server.
  • Reverse proxies may impose tighter caps (nginx default `large_client_header_buffers` is 8 KiB). When deployed behind one, bump that knob or move to a temp-table strategy for large values.
  • For reference: ClickHouse's `http_max_field_value_size` (default 128 KiB) is the *multipart/form-data* per-field cap. It is stricter per-value than the URL channel, so switching to multipart only helps when the *number* of params (not the size of any one) is the bottleneck — and that switch is not implemented here.

For a single value above the URL cap, stage it in a temp table or raise `http_max_uri_size` server-side; there is no client-side fall-back.

type ClientConfig 

type ClientConfig struct {
	URL      string
	User     string
	Password string
}

type HistoryEntry 

type HistoryEntry struct {
	SQL       string
	Executed  time.Time
	Elapsed   time.Duration
	NumRows   int64
	ErrorText string
}

type MirrorSync 

type MirrorSync struct {
	Canonical  string
	Mirror     string
	SyncedFrom string
	Prelude    string
	OK         bool
}

MirrorSync is the result of one recomposeMirror call: the new canonical SQL, the new mirror, the new syncedFrom snapshot, and the prelude string sliced off for the read-only label render. OK=false means ExtractParams failed and the caller should leave state untouched and fall back to the unsliced editor.

type PlayApp 

type PlayApp struct {

	// Auto-run + screenshot (driven by env vars for one-shot captures).
	AutoRun        bool
	ScreenshotPath string
	ExitOnShot     bool
	// contains filtered or unexported fields
}

func NewPlayApp 

func NewPlayApp(client *Client, store *QueryStore, initialSQL string) *PlayApp

func (*PlayApp) PersistSql 

func (inst *PlayApp) PersistSql()

PersistSql writes inst.sql under persistKeyLastSql when storage is wired. Called on Run + Unmount; errors are logged at debug level (audit-trail concern, not a user-visible failure).

func (*PlayApp) PersistTimelineBandsSql 

func (inst *PlayApp) PersistTimelineBandsSql()

PersistTimelineBandsSql writes the current bands-SQL editor buffer to the persist cap. Called from Unmount so the user's bands query survives session restart; the value-write happens unconditionally so an empty buffer also persists (and overrides a previous value).

func (*PlayApp) Render 

func (inst *PlayApp) Render() error

func (*PlayApp) RestorePersistedSql 

func (inst *PlayApp) RestorePersistedSql()

RestorePersistedSql replaces inst.sql with the value stored under persistKeyLastSql when storage is wired and the value is non-empty. Best-effort: errors are logged at debug level and the existing inst.sql stays. The caller (PlayLauncher.Mount) decides precedence: today it lets SPINNAKER_PLAY_SQL win over persist, persist win over the literal default.

func (*PlayApp) RestorePersistedTimelineBandsSql 

func (inst *PlayApp) RestorePersistedTimelineBandsSql()

RestorePersistedTimelineBandsSql loads the bands-SQL editor buffer from the persist cap. Same best-effort semantics as RestorePersistedSql.

func (*PlayApp) SetCapabilities 

func (inst *PlayApp) SetCapabilities(bus app.BusI, storage app.StorageI, logger zerolog.Logger)

SetCapabilities is the host-side seam for wiring the runtime's M2 capabilities (ADR-0026). Called once from PlayLauncher.Mount with ctx.Bus() and ctx.Storage(). Either argument may be nil — the "Load .sql" button stays hidden when bus is nil; persist save/ restore is skipped when storage is nil.

type PlayLauncher 

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

PlayLauncher is the AppI wrapper for the SQL Playground. Late binding — ClickHouse connection details are read from environment variables at Mount, matching the legacy resolveApplication behaviour. A simple LegacyFuncApp wouldn't suffice because the env-var-driven configuration can't be captured cleanly at init time before the cli flag parser has run.

func (*PlayLauncher) Frame 

func (inst *PlayLauncher) Frame(ctx app.FrameContextI) (err error)

func (*PlayLauncher) Manifest 

func (inst *PlayLauncher) Manifest() (m app.Manifest)

func (*PlayLauncher) Mount 

func (inst *PlayLauncher) Mount(ctx app.MountContextI) (err error)

func (*PlayLauncher) Unmount 

func (inst *PlayLauncher) Unmount(ctx app.MountContextI) (err error)

type Projector 

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

Projector owns the UMAP projection state for the current result batch. A single goroutine runs feature extraction + UMAP in the background; the render thread polls Snapshot() each frame to draw progress / scatter.

Lifecycle: Invalidate(schema, executed) is called every frame from the renderer; if the underlying result changed it cancels any in-flight run and resets to idle. Start(rec, schema, executed) spawns the goroutine (no-op if one is already running). Cancel() signals abort.

Concurrency: all mutable fields are guarded by mu. The cancel chan is non-nil iff a goroutine is in flight; Start refuses while non-nil. The goroutine clears it on exit so the next Start can proceed.

func NewProjector 

func NewProjector(ids *c.WidgetIdStack, cards *CardDriver) *Projector

NewProjector binds the Projector to the play app's CardDriver. The Projector borrows the driver's streamreadaccess.Driver to feed the FeatureExtractor; it does not own the CardDriver and must not outlive it.

func (*Projector) Cancel 

func (inst *Projector) Cancel()

Cancel signals the in-flight run to stop. The goroutine sees the closed channel on the next stepFunc fire (or the next phase boundary) and exits. While the goroutine winds down (UMAP can take seconds with no per-epoch hook) the status sits at Cancelling so the UI can show that the click was registered. Final transition to Cancelled happens in markCancelled(). No-op if nothing is running.

func (*Projector) Invalidate 

func (inst *Projector) Invalidate(schema *arrow.Schema, executed time.Time) (matches bool)

Invalidate is called every frame with the current (schema, executed). Returns true iff the projection state matches the current result and may be displayed. If the result changed since the last call, any in-flight computation is cancelled and the state is reset to idle.

Uses detachCurrentRunLocked (not signalCancelLocked) so a goroutine that is still winding down for the previous dataset becomes a no-op on its terminal status write — the new tab state (Idle) survives instead of being overwritten with the stale run's Cancelled / Failed / Done.

func (*Projector) Snapshot 

func (inst *Projector) Snapshot() (snap projectorSnapshot)

Snapshot returns a value-copy of the current state. Safe to read on the render thread without holding the mutex. The coords slice is shared (not copied) — the goroutine treats it as immutable once published.

func (*Projector) Start 

func (inst *Projector) Start(rec arrow.RecordBatch)

Start kicks off a projection run on the given record batch. No-op if a run is already in flight (Cancel first if you want to restart). The caller must have called Invalidate(schema, executed) earlier this frame so the cache key is set.

type QueryStore 

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

func NewQueryStore 

func NewQueryStore(client *Client, alloc memory.Allocator, maxHistory int) *QueryStore

func (*QueryStore) Cancel 

func (inst *QueryStore) Cancel()

Cancel aborts the in-flight query (if any).

func (*QueryStore) Execute 

func (inst *QueryStore) Execute(sql string)

Execute kicks off an async query. Subsequent calls while a query is running are ignored; call Cancel first.

func (*QueryStore) History 

func (inst *QueryStore) History() []HistoryEntry

func (*QueryStore) IsLoading 

func (inst *QueryStore) IsLoading() bool

func (*QueryStore) Snapshot 

func (inst *QueryStore) Snapshot() (rec arrow.RecordBatch, schema *arrow.Schema, numRows int64, loading bool, elapsed time.Duration, summary Summary, executed time.Time, err error)

Snapshot returns a retained view of the last result. Caller MUST call rec.Release() when done (nil-safe). Retaining under the read lock ensures a concurrent Execute→finish can't pull the record out from under us. executed is the time the most recent finish() completed — use it as an identity token for the current dataset (changes ⇒ new query). loading is read under the same lock as executed, so the pair is consistent: feed this loading to the FSM mirror rather than a separate IsLoading() call, which could observe the post-finish flag against this pre-finish snapshot.

type Summary 

type Summary struct {
	ReadRows        uint64
	ReadBytes       uint64
	WrittenRows     uint64
	WrittenBytes    uint64
	TotalRowsToRead uint64
	ResultRows      uint64
	ResultBytes     uint64
	ElapsedNs       uint64
}

Summary mirrors ClickHouse's X-ClickHouse-Summary JSON-ish header values.

func (Summary) String 

func (inst Summary) String() string

type TimelineDriver 

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

TimelineDriver bridges QueryStore Arrow results to the composite timeline widget. Per-frame: when the result identity changes (schema pointer or executed timestamp), the driver re-resolves the column contract and pushes the layout-event slices into the widget. Clicks on intervals / annotations route back into PlayApp.selectedRow so the Detail tab updates. Bucket clicks (Points-mode rug aggregation) carry no per-row id and are ignored.

Bands: a separate panel-local SQL (held on PlayApp, accessed through bandsSQLPtr) is run synchronously whenever the main result's _tl_time extent changes — the (minMS, maxMS) pair is substituted into the user-typed SQL via the timelineBandsPlaceholder* tokens, the resulting bands are cached by (minMS, maxMS, sql) under an LRU, and a closure over inst.bands feeds the widget's WithBackgroundBands producer each frame. See play_timeline_bands.go for the bands-specific helpers.

func NewTimelineDriver 

func NewTimelineDriver(ids *c.WidgetIdStack, selectedRow *int64, client *Client, bandsSQLPtr *string, nowLinePtr *bool) (inst *TimelineDriver)

NewTimelineDriver constructs the driver and the underlying composite widget eagerly (the widget tolerates nil starter data and renders an empty axis until SetIntervals/SetPoints/SetAnnotations is called). The selectedRow pointer is captured so the WithOnSelection callback can push a row index back into PlayApp without a back-reference. The client is reused for bands-SQL submissions; bandsSQLPtr points at the PlayApp-owned, persisted bands SQL string (mutated by the TextEdit inside renderBandsControls). nowLinePtr points at the PlayApp-owned "now line" toggle (mutated by the toolbar checkbox); the driver pushes its current value into the widget via SetNowLine each frame so the flip survives data swaps without recreating the widget.

func (*TimelineDriver) Render 

func (inst *TimelineDriver) Render(rec arrow.RecordBatch, schema *arrow.Schema, executed time.Time)

Render paints the Timeline dock tab body. Caller is responsible for the nil-rec / loading / query-failed guards (see renderTimelineTab); this method assumes a non-nil record and a non-nil schema.

func (*TimelineDriver) RenderContractHelp 

func (inst *TimelineDriver) RenderContractHelp()

RenderContractHelp emits a descriptive multi-line block listing the three column-shape modes the Timeline panel accepts (Points, Intervals, Annotations) and the slot constraints. Intended for empty-state and rejection-state surfaces so first-time users learn the contract from the panel itself instead of having to chase the how-to doc. Body line is body-sized; slot rows use the monospace style so column names line up visually; the closing note is small + weak so it doesn't compete with surrounding controls.

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.