Documentation
¶
Overview ¶
Package taskdone is the leeway-coded wire form of the terminal-success payload published on `task.<id>.done`. Fifth and final broker DTO from the task package to migrate off the buscodec fxamacker-cbor default onto the ADR-0042 SoA codec.
First in-tree consumer of the codec's scalar-blob grammar extension: the producer's `Result []byte` opaque payload routes to the blob section as a single variable-length value (not a slice of uint8). Per the boxer coding standard, `byte` is the blob spelling; sized integers stay in their own lane.
Vocabulary:
- vdd.MembTaskId — shared subject identifier across all task.* wire DTOs.
- vdd.MembTaskResult — narrow, blob section. The semantic ("application-defined success payload") is task-specific, so the membership stays kind-prefixed rather than landing in the shared file as a generic `result`. A future RPC-reply DTO that wants a generic result column can introduce its own term then.
Wire shape vs the legacy task.TaskDone JSON form:
- `Id TaskIdT` → `TaskId string`.
- `AtMs` → `At`.
- New `FactId uint64` plain `id`.
- `Result []byte` keeps the same Go shape; the codec now stores it as a single variable-length blob column instead of a CBOR bytes envelope. Empty Result reconstructs as an empty (non-nil) slice — observers should always presence-check via length.
Index ¶
- Variables
- func TaskDoneAddSections[StringArrayAttr TaskDoneStringArrayAttrI, ...](dml DML, row TaskDone) (err error)
- func TaskDoneBuildEntities[StringArrayAttr TaskDoneStringArrayAttrI, ...](dml DML, c *TaskDoneColumns) (err error)
- func TaskDoneFillFromArrow[StringArrayAttrs TaskDoneStringArrayAttrsReadI, ...](c *TaskDoneColumns, n int, idCol *array.Uint64, nkCol *array.Binary, ...) (err error)
- type TaskDone
- type TaskDoneBlobArrayAttrI
- type TaskDoneBlobArrayAttrsReadI
- type TaskDoneBlobArrayMembsReadI
- type TaskDoneBlobArraySecI
- type TaskDoneCodec
- type TaskDoneColumns
- type TaskDoneEntityI
- type TaskDoneStringArrayAttrI
- type TaskDoneStringArrayAttrsReadI
- type TaskDoneStringArrayMembsReadI
- type TaskDoneStringArraySecI
Constants ¶
This section is empty.
Variables ¶
var PackageProps = packageprops.Props{ WASMWASI: packageprops.WASMBlocked, WASMJS: packageprops.WASMBlocked, WASMFreestanding: packageprops.WASMBlocked, }
PackageProps records this package's curated properties (ADR-0080). Seeded by `wasmsurvey props generate`; curate by hand, then `wasmsurvey props verify`.
var TaskDoneActiveFields = sync.OnceValue(func() []int { active := map[string]bool{"blobArray": true, "stringArray": 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 })
TaskDoneActiveFields 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 TaskDoneActiveSections = []int{0, 9}
TaskDoneActiveSections 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 TaskDoneAddSections ¶ added in v0.0.17
func TaskDoneAddSections[ StringArrayAttr TaskDoneStringArrayAttrI, StringArraySec TaskDoneStringArraySecI[StringArrayAttr, Ent], BlobArrayAttr TaskDoneBlobArrayAttrI, BlobArraySec TaskDoneBlobArraySecI[BlobArrayAttr, Ent], Ent any, DML TaskDoneEntityI[ StringArrayAttr, StringArraySec, BlobArrayAttr, BlobArraySec, Ent, ], ](dml DML, row TaskDone) (err error)
TaskDoneAddSections 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 TaskDoneBuildEntities ¶
func TaskDoneBuildEntities[ StringArrayAttr TaskDoneStringArrayAttrI, StringArraySec TaskDoneStringArraySecI[StringArrayAttr, Ent], BlobArrayAttr TaskDoneBlobArrayAttrI, BlobArraySec TaskDoneBlobArraySecI[BlobArrayAttr, Ent], Ent any, DML TaskDoneEntityI[ StringArrayAttr, StringArraySec, BlobArrayAttr, BlobArraySec, Ent, ], ](dml DML, c *TaskDoneColumns) (err error)
TaskDoneBuildEntities 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 TaskDoneFillFromArrow ¶
func TaskDoneFillFromArrow[ StringArrayAttrs TaskDoneStringArrayAttrsReadI, StringArrayMembs TaskDoneStringArrayMembsReadI, BlobArrayAttrs TaskDoneBlobArrayAttrsReadI, BlobArrayMembs TaskDoneBlobArrayMembsReadI, ]( c *TaskDoneColumns, n int, idCol *array.Uint64, nkCol *array.Binary, tsCol *array.Timestamp, stringArrayAttrs StringArrayAttrs, stringArrayMembs StringArrayMembs, blobArrayAttrs BlobArrayAttrs, blobArrayMembs BlobArrayMembs, ) (err error)
TaskDoneFillFromArrow 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 TaskDone ¶
type TaskDone struct {
// FactId is the per-row event id; distinct from TaskId (the
// subject of the success).
FactId uint64 `lw:",id"`
// NaturalKey is the entity natural key; the facts SetId is 2-arg.
// These bus DTOs carry no separate key, so it stays the nil default.
NaturalKey []byte `lw:",naturalKey"`
// At is the event timestamp. time.Time matches the facts
// SetTimestamp signature directly (strict 1:1); the leeway wire
// truncates to u32 seconds, while the bus preserves full nanos.
At time.Time `lw:",ts"`
// TaskId names the task that completed.
TaskId string `lw:"taskId,stringArray"`
// Result is the application-defined success payload. Opaque to
// the codec; observers decode by TaskCreated.Kind. Empty (nil or
// len=0) when the task signals success without a payload.
Result []byte `lw:"taskResult,blobArray"`
// contains filtered or unexported fields
}
TaskDone is the wire payload published once at task success on subject `task.<id>.done`. Result is opaque on the wire — observers decode by the originating TaskCreated.Kind.
func TaskDoneReadRow ¶ added in v0.0.17
func TaskDoneReadRow[ StringArrayAttrs TaskDoneStringArrayAttrsReadI, StringArrayMembs TaskDoneStringArrayMembsReadI, BlobArrayAttrs TaskDoneBlobArrayAttrsReadI, BlobArrayMembs TaskDoneBlobArrayMembsReadI, ]( i int, stringArrayAttrs StringArrayAttrs, stringArrayMembs StringArrayMembs, blobArrayAttrs BlobArrayAttrs, blobArrayMembs BlobArrayMembs, ) (row TaskDone, present bool, err error)
TaskDoneReadRow reads row i as one optional TaskDone 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 TaskDoneBlobArrayAttrI ¶
type TaskDoneBlobArrayAttrI interface {
dmlruntime.InAttributeMembershipLowCardRefPI
EndAttributeP()
}
TaskDoneBlobArrayAttrI is the InAttr-side view of the blobArray section. P-variants only — every method returns void so no F-bounded `[Self]` parameter is needed.
type TaskDoneBlobArrayAttrsReadI ¶
type TaskDoneBlobArrayAttrsReadI interface {
GetAttrValueSingleOrDefault(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) []byte
GetNumberOfAttributes(entityIdx raruntime.EntityIdx) int64
}
TaskDoneBlobArrayAttrsReadI is the Attributes-side view of the blobArray section.
type TaskDoneBlobArrayMembsReadI ¶
type TaskDoneBlobArrayMembsReadI interface {
GetMembValueLowCardRef(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) iter.Seq[uint64]
}
TaskDoneBlobArrayMembsReadI is the Memberships-side view of the blobArray section.
type TaskDoneBlobArraySecI ¶
type TaskDoneBlobArraySecI[Attr any, Ent any] interface { BeginAttributeSingle(value []byte) Attr EndSection() Ent }
TaskDoneBlobArraySecI is the Section-side view: opens an attribute and closes the section. Attr and Ent are bound at the call site by inference.
type TaskDoneCodec ¶
type TaskDoneCodec struct{}
TaskDoneCodec is the buscodec.CodecI bridge for TaskDone. 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 (*TaskDoneCodec) ContentType ¶
func (inst *TaskDoneCodec) ContentType() (ct string)
func (*TaskDoneCodec) Name ¶
func (inst *TaskDoneCodec) Name() (n string)
type TaskDoneColumns ¶
type TaskDoneColumns struct {
FactId []uint64
NaturalKey [][]byte
At []time.Time
TaskId []string
Result [][]byte
}
TaskDoneColumns is the SoA storage for batches of TaskDone rows. All slices grow in lockstep — Len returns the row count.
func (*TaskDoneColumns) Append ¶
func (c *TaskDoneColumns) Append(row TaskDone)
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 (*TaskDoneColumns) Len ¶
func (c *TaskDoneColumns) Len() int
Len returns the number of rows currently in the batch.
func (*TaskDoneColumns) Marshal ¶
func (c *TaskDoneColumns) 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 TaskDoneBuildEntities — the per-row chain lives there and works against any leeway-DML class that structurally satisfies TaskDoneEntityI.
func (*TaskDoneColumns) Row ¶
func (c *TaskDoneColumns) Row(i int) (row TaskDone)
Row reconstructs entity i as an AoS TaskDone record. Inverse of Append: slice / pointer fields are shared by reference (no defensive copy); scalar fields and Option[T] are copied.
type TaskDoneEntityI ¶
type TaskDoneEntityI[ StringArrayAttr TaskDoneStringArrayAttrI, StringArraySec TaskDoneStringArraySecI[StringArrayAttr, Ent], BlobArrayAttr TaskDoneBlobArrayAttrI, BlobArraySec TaskDoneBlobArraySecI[BlobArrayAttr, Ent], Ent any, ] interface { BeginEntity() Ent SetId(id uint64, naturalKey []byte) Ent SetTimestamp(ts time.Time) Ent GetSectionStringArray() StringArraySec GetSectionBlobArray() BlobArraySec CommitEntity() (err error) }
TaskDoneEntityI is the entity-builder surface TaskDoneAddSections 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 TaskDoneStringArrayAttrI ¶
type TaskDoneStringArrayAttrI interface {
dmlruntime.InAttributeMembershipLowCardRefPI
EndAttributeP()
}
TaskDoneStringArrayAttrI is the InAttr-side view of the stringArray section. P-variants only — every method returns void so no F-bounded `[Self]` parameter is needed.
type TaskDoneStringArrayAttrsReadI ¶
type TaskDoneStringArrayAttrsReadI interface {
GetAttrValueSingleOrDefault(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) string
GetNumberOfAttributes(entityIdx raruntime.EntityIdx) int64
}
TaskDoneStringArrayAttrsReadI is the Attributes-side view of the stringArray section.
type TaskDoneStringArrayMembsReadI ¶
type TaskDoneStringArrayMembsReadI interface {
GetMembValueLowCardRef(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) iter.Seq[uint64]
}
TaskDoneStringArrayMembsReadI is the Memberships-side view of the stringArray section.
type TaskDoneStringArraySecI ¶
type TaskDoneStringArraySecI[Attr any, Ent any] interface { BeginAttributeSingle(value string) Attr EndSection() Ent }
TaskDoneStringArraySecI is the Section-side view: opens an attribute and closes the section. Attr and Ent are bound at the call site by inference.