Documentation
¶
Overview ¶
Package sqlapplet makes SQL-defined applets first-class boxer apps (ADR-0132): each applet is one committed markdown document — frontmatter as the manifest, prose as the help page, the first `sql` fence as the play buffer — and the host mints one real app.Manifest per document, serving every instance as an attenuated embedded play (`NewLivePlayApp` with the exploration chrome removed).
Contributing packages register applet books via RegisterBook (an embedded fs.FS of .md documents, mirroring the help facility); the shell calls MintManifests once at startup, before launch resolution, so `--launch <appletId>` and the Apps menu see the minted set.
Index ¶
Constants ¶
const StoreAppId app.AppIdT = "runtime.appletstore"
StoreAppId is the synthetic identity the applet store service registers under; its SubjectAlias namespaces the persisted documents.
Variables ¶
This section is empty.
Functions ¶
func MintManifests ¶
MintManifests parses every registered applet book and registers one factory-backed Manifest per applet with the default app registry (ADR-0132 §SD2). The shell calls it exactly once at startup, after init-time book registrations and before launch resolution, so `--launch <appletId>` and the Apps menu see the minted set.
Minting is best-effort per document — an invalid doc yields an error and mints nothing, valid siblings still mint — because the corpus test (§SD6) is the hard gate; at boot, a partially minted set beats no shell.
func NewEmbedded ¶ added in v0.0.15
func NewEmbedded(def *AppletDef, cfg EmbedConfig) (inner *play.PlayApp, err error)
NewEmbedded constructs an attenuated PlayApp for def, ready to render: it resolves the endpoint, stamps identity, applies the AutoRun/Live gates and the minimal toolbar, attenuates tabs, binds any ad-hoc datasets, and grants capabilities. It is the shared core that both the standalone applet (appletApp.Mount) and an embedder call, so every applet-definition invariant holds under embedding (ADR-0132 §SD8, ADR-0134 §SD7). Instance-id salting is per-PlayApp automatically (NewPlayApp), so embedded instances do not collide.
func RegisterBook ¶
RegisterBook contributes an applet book: an fs.FS of markdown documents in the ADR-0132 §SD1 shape. Packages call it from init (the help-facility pattern); MintManifests later parses every registered book. The id names the book in diagnostics and must be unique.
Types ¶
type AppletDef ¶
type AppletDef struct {
Slug string
BookID string
Title string
Icon string
Tabs []TabSel // nil = auto (all result panels; accept/reject decides at render)
Endpoint EndpointE
SQL string
BandsSQL string // optional `sql bands` aux fence (Timeline panel-local SQL)
// Class is the ADR-0132 §SD5 security class of SQL, computed at parse
// time. It gates AutoRun at mount: only QuerySecurityRead applets run on
// open.
Class analysis.QuerySecurityClassE
// HasUnboundSlots notes whether the buffer carries `{name:Type}`
// placeholders its SET prelude does not bind — signals, in ADR-0097
// terms. Such an applet opens with the Live toggle preset
// (panel-written signals re-run the buffer, ADR-0132 §SD3); a fully
// prelude-bound buffer does not (its params re-run via the strip's
// prelude rewrite and an explicit or auto Run).
HasUnboundSlots bool
// Datasets are the stable ad-hoc dataset aliases the buffer references
// as keelson('<alias>') (ADR-0134 §SD4). An embedder binds each to an
// ephemeral handle before mount. The corpus gate treats them as
// valid-by-declaration.
Datasets []string
}
AppletDef is one parsed applet document, ready to mint.
func ParseBook ¶
ParseBook parses every markdown document of one applet book into applet definitions. A document without a role-less `sql` fence is a plain prose page and yields no definition (a book may carry an overview page); every violation of the ADR-0132 §SD1/§SD6 rules yields one error naming the document. defs come back sorted by slug.
func ParseDocSource ¶
ParseDocSource parses one applet document from raw markdown — the shared core behind the committed-book path and the runtime store's save gate (ADR-0132 Update "O4"): both submit the identical document shape and are judged by the identical rules. A nil def with a nil error is a prose page.
type EmbedConfig ¶ added in v0.0.15
type EmbedConfig struct {
// StampAppId is the identity the log_comment stamp attributes runs to.
// A standalone applet passes its minted manifest id; an embedder passes
// a composed stamp — its own app id carrying the applet slug — so
// per-applet attribution survives embedding (ADR-0134 §SD7).
StampAppId string
// RunId is the runtime run identity for the stamp.
RunId string
// Bus is the capability bus for SetCapabilities. An applet's declared
// capabilities ride the embedder's manifest (§SD8), so this is the
// embedder's bus.
Bus app.BusI
// Log is the instance logger.
Log zerolog.Logger
// EndpointURL overrides the resolved endpoint. Empty resolves from
// def.Endpoint (introspection → LocalQueryEndpoint; default → env).
EndpointURL string
// Bindings maps each declared dataset alias to the ephemeral handle the
// embedder published, applied pre-mount so the buffer's keelson('<alias>')
// rewrites to the handle client-side (ADR-0134 §SD4).
Bindings map[string]string
}
EmbedConfig carries the host-supplied collaborators NewEmbedded needs. It is the ADR-0132 §SD8 graduation surface: an embedder app hosts an applet document while every §SD1 invariant (committed, gated, classified buffer) survives (ADR-0134 §SD7).
type EndpointE ¶
type EndpointE uint8
EndpointE selects the server an applet speaks to (ADR-0132 §SD7).
const ( // EndpointDefault — the env-configured ClickHouse, exactly as play's own // launcher resolves it. EndpointDefault EndpointE = iota // EndpointIntrospection — the in-process ADR-0094 `/query` endpoint. // Parameter binding works there since ADR-0133 M3 (the chhttp dialect // plus the broker's SET-prelude channel); the remaining parity gaps are // read counters and progress headers, recorded in ADR-0133 §SD4. EndpointIntrospection )
type StoreService ¶
type StoreService struct {
// contains filtered or unexported fields
}
StoreService is the runtime applet store (ADR-0132 Update "O4"): it serves `applet.store.save`, validating each submitted document with the same parser the committed books go through, persisting it through the runtime persist facility, and minting its manifest live. It is the moderation gate between an authoring app and the launcher.
func StartStore ¶
StartStore loads the stored applet corpus, mints it into the default app registry, and subscribes the save endpoint. Call it once at startup, after MintManifests — committed books must already be minted so the collision rule ("curation outranks runtime state", O4-D3) can read the registry as the source of truth.
func (*StoreService) Stop ¶
func (inst *StoreService) Stop()
Stop unsubscribes the save endpoint. Idempotent, nil-safe.
Source Files