Documentation
¶
Overview ¶
Package appletcreatecfg is the launch contract of the SQL applet creator (ADR-0132 Update "O4" / ADR-0135 §SD7): the target app id, the config kind, and the typed arguments an app opens a creator window with over `windowhost.open`. It is the neutral leaf both sides import — the playground (apps/play) encodes and sends; the creator (apps/sqlappletcreator) declares it as its manifest LaunchKind and decodes it in Mount — so play never imports the creator app itself, only this contract (the appletstore.SubjectSave precedent).
The DTO follows the runtime codec grammar and the generated codec is the only wire form — callers encode with buscodec.Encode, the creator decodes with buscodec.Decode.
Vocabulary (narrow, the ADR-0135 launch cohort in the keelson vdd):
- vdd.MembAppletCreateSql — text, the buffer to author into an applet.
- vdd.MembAppletCreateEndpoint — symbol, the endpoint the buffer was authored against (stamped into the applet document's frontmatter).
Index ¶
- Constants
- Variables
- func AppletCreateAddSections[TextArrayAttr AppletCreateTextArrayAttrI, ...](dml DML, row AppletCreate) (err error)
- func AppletCreateBuildEntities[TextArrayAttr AppletCreateTextArrayAttrI, ...](dml DML, c *AppletCreateColumns) (err error)
- func AppletCreateFillFromArrow[TextArrayAttrs AppletCreateTextArrayAttrsReadI, ...](c *AppletCreateColumns, n int, idCol *array.Uint64, nkCol *array.Binary, ...) (err error)
- type AppletCreate
- type AppletCreateCodec
- type AppletCreateColumns
- type AppletCreateEntityI
- type AppletCreateSymbolAttrI
- type AppletCreateSymbolAttrsReadI
- type AppletCreateSymbolMembsReadI
- type AppletCreateSymbolSecI
- type AppletCreateTextArrayAttrI
- type AppletCreateTextArrayAttrsReadI
- type AppletCreateTextArrayMembsReadI
- type AppletCreateTextArraySecI
Constants ¶
const ( // EndpointDefault is the env-configured ClickHouse target; the composed // applet document omits the `endpoint` frontmatter key. EndpointDefault = "default" // EndpointIntrospection is the in-process keelson `/query` endpoint // (introspect.LocalQueryEndpoint, ADR-0094 §SD6) — where bare // `keelson('…')` is the dialect and ad-hoc datasets resolve (ADR-0134). // A buffer authored there must reopen there, so the creator stamps // `endpoint: "introspection"` into the frontmatter. EndpointIntrospection = "introspection" )
Endpoint values for the AppletCreate.Endpoint field. Empty behaves like EndpointDefault.
const AppId = "github.com/stergiotis/boxer/apps/sqlappletcreator"
AppId is the applet creator's registered manifest id — the target an app names in a `windowhost.open` request. Kept here (not in the creator app's package) so a requester imports the contract without importing the app. Untyped so it flows into app.AppIdT contexts (Manifest.Id, RequestOpen) without this leaf depending on the app package.
const Kind = "appletCreate"
Kind is the vocabulary kind name of this config — the value the creator's manifest declares as LaunchKind and callers put in launchrequest.LaunchRequest.ConfigKind.
Variables ¶
var AppletCreateActiveFields = sync.OnceValue(func() []int { active := map[string]bool{"symbol": true, "textArray": true} schema := cbdml.CreateSchemaFacts() out := make([]int, 0, 4+len(active)*8) for i, f := range schema.Fields() { name := f.Name switch { case strings.HasPrefix(name, "id:"), strings.HasPrefix(name, "ts:"), strings.HasPrefix(name, "lc:"): out = append(out, i) case strings.HasPrefix(name, "tv:"): rest := name[3:] colon := strings.IndexByte(rest, ':') if colon < 0 { continue } if active[rest[:colon]] { out = append(out, i) } } } return out })
AppletCreateActiveFields is the column-index subset this kind populates in the boxer.facts Arrow schema. Lazily computed once via sync.OnceValue: scans cbdml.CreateSchemaFacts()'s tv:<section>:... field names against this kind's active sections plus the three plain prefixes (id:, ts:, lc:). Driven through RecordBuilder. SetActiveFields to skip per-row emit walks for unused columns.
var AppletCreateActiveSections = []int{10, 12}
AppletCreateActiveSections is the dml_cbor section-index subset this kind populates. Passed to InEntityFacts.SetActiveSections so the builder skips beginSection list-slot work for inactive sections.
Functions ¶
func AppletCreateAddSections ¶
func AppletCreateAddSections[ TextArrayAttr AppletCreateTextArrayAttrI, TextArraySec AppletCreateTextArraySecI[TextArrayAttr, Ent], SymbolAttr AppletCreateSymbolAttrI, SymbolSec AppletCreateSymbolSecI[SymbolAttr, Ent], Ent any, DML AppletCreateEntityI[ TextArrayAttr, TextArraySec, SymbolAttr, SymbolSec, Ent, ], ](dml DML, row AppletCreate) (err error)
AppletCreateAddSections contributes this kind's tagged sections to the OPEN entity on dml — the BuildEntities body without the entity frame. The caller owns BeginEntity / plain setters / CommitEntity.
func AppletCreateBuildEntities ¶
func AppletCreateBuildEntities[ TextArrayAttr AppletCreateTextArrayAttrI, TextArraySec AppletCreateTextArraySecI[TextArrayAttr, Ent], SymbolAttr AppletCreateSymbolAttrI, SymbolSec AppletCreateSymbolSecI[SymbolAttr, Ent], Ent any, DML AppletCreateEntityI[ TextArrayAttr, TextArraySec, SymbolAttr, SymbolSec, Ent, ], ](dml DML, c *AppletCreateColumns) (err error)
AppletCreateBuildEntities walks c row-by-row, drives dml's entity / section chain, and returns once every row has been committed. The dml argument's concrete type binds every type parameter via Go's type inference at the call site.
func AppletCreateFillFromArrow ¶
func AppletCreateFillFromArrow[ TextArrayAttrs AppletCreateTextArrayAttrsReadI, TextArrayMembs AppletCreateTextArrayMembsReadI, SymbolAttrs AppletCreateSymbolAttrsReadI, SymbolMembs AppletCreateSymbolMembsReadI, ]( c *AppletCreateColumns, n int, idCol *array.Uint64, nkCol *array.Binary, tsCol *array.Timestamp, textArrayAttrs TextArrayAttrs, textArrayMembs TextArrayMembs, symbolAttrs SymbolAttrs, symbolMembs SymbolMembs, ) (err error)
AppletCreateFillFromArrow walks rec row-by-row and appends each entity's plain + tagged-section values into c. Plain columns enter as concrete Arrow accessors; per-section Attrs + Membs bind through type-parameter interfaces.
Types ¶
type AppletCreate ¶
type AppletCreate struct {
// FactId is the per-row event id (zero from producers; the launch row's
// durable id is minted by the facts store on persist).
FactId uint64 `lw:",id"`
// NaturalKey is the entity natural key; these bus DTOs carry no separate
// key, so it stays the nil default (the facts SetId is 2-arg).
NaturalKey []byte `lw:",naturalKey"`
// At is the event timestamp. time.Time matches the facts SetTimestamp
// signature directly; the leeway wire truncates to u32 seconds, while the
// bus preserves full nanos.
At time.Time `lw:",ts"`
// Sql is the buffer the creator seeds its editor with and composes into
// the applet document's sql fence. Empty is valid — a plainly-opened
// creator window starts with an empty editor.
Sql string `lw:"appletCreateSql,textArray"`
// Endpoint names the query target the buffer was authored against. Empty
// or EndpointDefault omits the frontmatter key; EndpointIntrospection
// pins the in-process endpoint the buffer's bare `keelson('…')` needs.
Endpoint string `lw:"appletCreateEndpoint,symbol"`
// contains filtered or unexported fields
}
AppletCreate is the flat wire form of the applet creator's launch arguments: the buffer to author and the endpoint it was authored against. The slug/title/icon are entered in the creator window, not carried here.
func AppletCreateReadRow ¶
func AppletCreateReadRow[ TextArrayAttrs AppletCreateTextArrayAttrsReadI, TextArrayMembs AppletCreateTextArrayMembsReadI, SymbolAttrs AppletCreateSymbolAttrsReadI, SymbolMembs AppletCreateSymbolMembsReadI, ]( i int, textArrayAttrs TextArrayAttrs, textArrayMembs TextArrayMembs, symbolAttrs SymbolAttrs, symbolMembs SymbolMembs, ) (row AppletCreate, present bool, err error)
AppletCreateReadRow reads row i as one optional AppletCreate component: presence- gated (a row carrying none of the kind's memberships yields present=false), membership-matched. A slot carrying more attributes than this kind's shape admits is an error, for every shape including containers. Plain- bound fields stay zero — the caller owns the envelope. The Attrs/Membs readers bind by type inference at the call site, as with FillFromArrow.
type AppletCreateCodec ¶
type AppletCreateCodec struct{}
AppletCreateCodec is the buscodec.CodecI bridge for AppletCreate. Encodes one row through dml_cbor; decodes via cborarrow.Convert + ra-Unmarshal + Row(0). Auto-registered in init() so callers using buscodec.Encode / Decode route through here instead of the CBOR fallback.
func (*AppletCreateCodec) ContentType ¶
func (inst *AppletCreateCodec) ContentType() (ct string)
func (*AppletCreateCodec) Decode ¶
func (inst *AppletCreateCodec) Decode(b []byte, v any) (err error)
func (*AppletCreateCodec) Encode ¶
func (inst *AppletCreateCodec) Encode(v any) (b []byte, err error)
func (*AppletCreateCodec) Name ¶
func (inst *AppletCreateCodec) Name() (n string)
type AppletCreateColumns ¶
type AppletCreateColumns struct {
FactId []uint64
NaturalKey [][]byte
At []time.Time
Sql []string
Endpoint []string
}
AppletCreateColumns is the SoA storage for batches of AppletCreate rows. All slices grow in lockstep — Len returns the row count.
func (*AppletCreateColumns) Append ¶
func (c *AppletCreateColumns) Append(row AppletCreate)
Append pushes one AoS record into the SoA buffers.
Aliasing: slice and pointer fields (`[]T`, `*roaring.Bitmap`) are stored by reference, not copied. Callers must not mutate row.<F> after Append unless they want Marshal to read the mutation. Scalar fields (T, Option[T]) are copied by value.
func (*AppletCreateColumns) Len ¶
func (c *AppletCreateColumns) Len() int
Len returns the number of rows currently in the batch.
func (*AppletCreateColumns) Marshal ¶
func (c *AppletCreateColumns) Marshal(w io.Writer) (err error)
Marshal writes the SoA buffer to w as the sparse-CBOR wire format produced through factsschema/dml_cbor. Thin wrapper around AppletCreateBuildEntities — the per-row chain lives there and works against any leeway-DML class that structurally satisfies AppletCreateEntityI.
func (*AppletCreateColumns) Row ¶
func (c *AppletCreateColumns) Row(i int) (row AppletCreate)
Row reconstructs entity i as an AoS AppletCreate record. Inverse of Append: slice / pointer fields are shared by reference (no defensive copy); scalar fields and Option[T] are copied.
type AppletCreateEntityI ¶
type AppletCreateEntityI[ TextArrayAttr AppletCreateTextArrayAttrI, TextArraySec AppletCreateTextArraySecI[TextArrayAttr, Ent], SymbolAttr AppletCreateSymbolAttrI, SymbolSec AppletCreateSymbolSecI[SymbolAttr, Ent], Ent any, ] interface { BeginEntity() Ent SetId(id uint64, naturalKey []byte) Ent SetTimestamp(ts time.Time) Ent GetSectionTextArray() TextArraySec GetSectionSymbol() SymbolSec CommitEntity() (err error) }
AppletCreateEntityI is the entity-builder surface AppletCreateAddSections drives. It always lists the per-section getters; the entity-frame methods (BeginEntity / plain setters / CommitEntity) are added only for the full codec's BuildEntities. AddSections stacks sections onto a frame the caller already owns, so it needs none of them — which lets a store drive it with a builder whose frame control is unexported (ADR-0100 SD6). Ent is the builder pointer.
type AppletCreateSymbolAttrI ¶
type AppletCreateSymbolAttrI interface {
dmlruntime.InAttributeMembershipLowCardRefPI
EndAttributeP()
}
AppletCreateSymbolAttrI is the InAttr-side view of the symbol section. P-variants only — every method returns void so no F-bounded `[Self]` parameter is needed.
type AppletCreateSymbolAttrsReadI ¶
type AppletCreateSymbolAttrsReadI interface {
GetAttrValueValue(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) string
GetNumberOfAttributes(entityIdx raruntime.EntityIdx) int64
}
AppletCreateSymbolAttrsReadI is the Attributes-side view of the symbol section.
type AppletCreateSymbolMembsReadI ¶
type AppletCreateSymbolMembsReadI interface {
GetMembValueLowCardRef(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) iter.Seq[uint64]
}
AppletCreateSymbolMembsReadI is the Memberships-side view of the symbol section.
type AppletCreateSymbolSecI ¶
type AppletCreateSymbolSecI[Attr any, Ent any] interface { BeginAttribute(value string) Attr EndSection() Ent }
AppletCreateSymbolSecI is the Section-side view: opens an attribute and closes the section. Attr and Ent are bound at the call site by inference.
type AppletCreateTextArrayAttrI ¶
type AppletCreateTextArrayAttrI interface {
dmlruntime.InAttributeMembershipLowCardRefPI
EndAttributeP()
}
AppletCreateTextArrayAttrI is the InAttr-side view of the textArray section. P-variants only — every method returns void so no F-bounded `[Self]` parameter is needed.
type AppletCreateTextArrayAttrsReadI ¶
type AppletCreateTextArrayAttrsReadI interface {
GetAttrValueSingleOrDefault(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) string
GetNumberOfAttributes(entityIdx raruntime.EntityIdx) int64
}
AppletCreateTextArrayAttrsReadI is the Attributes-side view of the textArray section.
type AppletCreateTextArrayMembsReadI ¶
type AppletCreateTextArrayMembsReadI interface {
GetMembValueLowCardRef(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) iter.Seq[uint64]
}
AppletCreateTextArrayMembsReadI is the Memberships-side view of the textArray section.
type AppletCreateTextArraySecI ¶
type AppletCreateTextArraySecI[Attr any, Ent any] interface { BeginAttributeSingle(value string) Attr EndSection() Ent }
AppletCreateTextArraySecI is the Section-side view: opens an attribute and closes the section. Attr and Ent are bound at the call site by inference.