appletcreatecfg

package
v0.0.19 Latest Latest
Warning

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

Go to latest
Published: Jul 28, 2026 License: MIT Imports: 21 Imported by: 0

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):

Index

Constants

View Source
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.

View Source
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.

View Source
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

View Source
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.

View Source
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.

func (*AppletCreateColumns) Unmarshal

func (c *AppletCreateColumns) Unmarshal(rec arrow.Record) (err error)

Unmarshal appends one row to c per entity in rec, projecting the boxer.facts columns through factsschema/ra. Thin wrapper around AppletCreateFillFromArrow — the per-row decode lives there.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL