persistreply

package
v0.0.21 Latest Latest
Warning

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

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

Documentation

Overview

Package persistreply is the leeway-coded wire form of the runtime.persist reply payload.

Vocabulary:

  • vdd.MembPersistFound — narrow bool. Meaningful only on Get replies; Set/Delete replies leave it false.
  • vdd.MembPersistValue — narrow blob (variable-length opaque payload via the codec's scalar-blob grammar). Empty when Found is false or when the op was not a Get.
  • vdd.MembReason — shared text. Empty on success; carries the backend's error message on any failure. Joined with TaskCancel / TaskError / WatchReply / GrantReply through the same cross-DTO column.

The Go-level [persist.PersistReply] keeps its existing shape (Found/Value/Error); the codec DTO is the wire-side projection only. Conversion lives in `persist.MarshalReply` / `UnmarshalReply`. Field rename at the boundary: `Error` (Go) → `reason` (wire) — semantically the same short failure rationale, joined with the other reason-bearing DTOs through the shared vocabulary term.

Index

Constants

This section is empty.

Variables

View Source 
var PackageProps = packageprops.Props{
	WASMWASI:         packageprops.WASMBlocked,
	WASMJS:           packageprops.WASMBlocked,
	WASMFreestanding: packageprops.WASMBlocked,
}

PackageProps records this package's curated properties (ADR-0080). Seeded by `boxer code analysis golang wasmsurvey props generate`; curate by hand. The same group's `props verify` reconciles it.

View Source 
var PersistReplyActiveFields = sync.OnceValue(func() []int {
	active := map[string]bool{"blobArray": true, "bool": 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
})

PersistReplyActiveFields 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 PersistReplyActiveSections = []int{0, 1, 12}

PersistReplyActiveSections 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 PersistReplyAddSections added in v0.0.17 

func PersistReplyAddSections[
	BoolAttr PersistReplyBoolAttrI,
	BoolSec PersistReplyBoolSecI[BoolAttr, Ent],
	BlobArrayAttr PersistReplyBlobArrayAttrI,
	BlobArraySec PersistReplyBlobArraySecI[BlobArrayAttr, Ent],
	TextArrayAttr PersistReplyTextArrayAttrI,
	TextArraySec PersistReplyTextArraySecI[TextArrayAttr, Ent],
	Ent any,
	DML PersistReplyEntityI[
		BoolAttr, BoolSec,
		BlobArrayAttr, BlobArraySec,
		TextArrayAttr, TextArraySec,
		Ent,
	],
](dml DML, row PersistReply) (err error)

PersistReplyAddSections 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 PersistReplyBuildEntities 

func PersistReplyBuildEntities[
	BoolAttr PersistReplyBoolAttrI,
	BoolSec PersistReplyBoolSecI[BoolAttr, Ent],
	BlobArrayAttr PersistReplyBlobArrayAttrI,
	BlobArraySec PersistReplyBlobArraySecI[BlobArrayAttr, Ent],
	TextArrayAttr PersistReplyTextArrayAttrI,
	TextArraySec PersistReplyTextArraySecI[TextArrayAttr, Ent],
	Ent any,
	DML PersistReplyEntityI[
		BoolAttr, BoolSec,
		BlobArrayAttr, BlobArraySec,
		TextArrayAttr, TextArraySec,
		Ent,
	],
](dml DML, c *PersistReplyColumns) (err error)

PersistReplyBuildEntities 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 PersistReplyEmitSectionBlobArray added in v0.0.20 

func PersistReplyEmitSectionBlobArray[
	BlobArrayAttr PersistReplyBlobArrayAttrI,
	BlobArraySec PersistReplyBlobArraySecI[BlobArrayAttr, Ent],
	Ent any,
](blobArraySec BlobArraySec, row PersistReply) (err error)

PersistReplyEmitSectionBlobArray writes this kind's blobArray attributes into an ALREADY-OPEN section frame, and does not close it. The caller owns the frame: one kind's AddSections, or a builder deferring the close until every component that shares the section has written.

func PersistReplyEmitSectionBool added in v0.0.20 

func PersistReplyEmitSectionBool[
	BoolAttr PersistReplyBoolAttrI,
	BoolSec PersistReplyBoolSecI[BoolAttr, Ent],
	Ent any,
](boolSec BoolSec, row PersistReply) (err error)

PersistReplyEmitSectionBool writes this kind's bool attributes into an ALREADY-OPEN section frame, and does not close it. The caller owns the frame: one kind's AddSections, or a builder deferring the close until every component that shares the section has written.

func PersistReplyEmitSectionTextArray added in v0.0.20 

func PersistReplyEmitSectionTextArray[
	TextArrayAttr PersistReplyTextArrayAttrI,
	TextArraySec PersistReplyTextArraySecI[TextArrayAttr, Ent],
	Ent any,
](textArraySec TextArraySec, row PersistReply) (err error)

PersistReplyEmitSectionTextArray writes this kind's textArray attributes into an ALREADY-OPEN section frame, and does not close it. The caller owns the frame: one kind's AddSections, or a builder deferring the close until every component that shares the section has written.

func PersistReplyFillFromArrow 

func PersistReplyFillFromArrow[
	BoolAttrs PersistReplyBoolAttrsReadI,
	BoolMembs PersistReplyBoolMembsReadI,
	BlobArrayAttrs PersistReplyBlobArrayAttrsReadI,
	BlobArrayMembs PersistReplyBlobArrayMembsReadI,
	TextArrayAttrs PersistReplyTextArrayAttrsReadI,
	TextArrayMembs PersistReplyTextArrayMembsReadI,
](
	c *PersistReplyColumns,
	n int,
	idCol *array.Uint64,
	nkCol *array.Binary,
	tsCol *array.Timestamp,
	boolAttrs BoolAttrs,
	boolMembs BoolMembs,
	blobArrayAttrs BlobArrayAttrs,
	blobArrayMembs BlobArrayMembs,
	textArrayAttrs TextArrayAttrs,
	textArrayMembs TextArrayMembs,
) (err error)

PersistReplyFillFromArrow 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 PersistReply 

type PersistReply struct {

	// FactId is the per-row event id.
	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"`

	// Found is true when a Get located the requested key. False
	// for missing keys on Get, and for Set / Delete replies in
	// general.
	Found bool `lw:"persistFound,bool"`

	// Value is the opaque payload returned by a successful Get.
	// Empty otherwise. Scalar-blob column — see the TaskDone
	// migration entry in ADR-0042 for the grammar extension.
	Value []byte `lw:"persistValue,blobArray"`

	// Reason carries the backend's error message on failure. Empty
	// on success.
	Reason string `lw:"reason,textArray"`
	// contains filtered or unexported fields
}

PersistReply is the flat wire form of a runtime.persist reply.

func PersistReplyReadRow added in v0.0.17 

func PersistReplyReadRow[
	BoolAttrs PersistReplyBoolAttrsReadI,
	BoolMembs PersistReplyBoolMembsReadI,
	BlobArrayAttrs PersistReplyBlobArrayAttrsReadI,
	BlobArrayMembs PersistReplyBlobArrayMembsReadI,
	TextArrayAttrs PersistReplyTextArrayAttrsReadI,
	TextArrayMembs PersistReplyTextArrayMembsReadI,
](
	i int,
	boolAttrs BoolAttrs,
	boolMembs BoolMembs,
	blobArrayAttrs BlobArrayAttrs,
	blobArrayMembs BlobArrayMembs,
	textArrayAttrs TextArrayAttrs,
	textArrayMembs TextArrayMembs,
) (row PersistReply, present bool, err error)

PersistReplyReadRow reads row i as one optional PersistReply 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 PersistReplyBlobArrayAttrI 

type PersistReplyBlobArrayAttrI interface {
	dmlruntime.InAttributeMembershipLowCardRefPI
	EndAttributeP()
}

PersistReplyBlobArrayAttrI 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 PersistReplyBlobArrayAttrsReadI 

type PersistReplyBlobArrayAttrsReadI interface {
	GetAttrValueSingle(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) ([]byte, error)
	GetNumberOfAttributes(entityIdx raruntime.EntityIdx) int64
}

PersistReplyBlobArrayAttrsReadI is the Attributes-side view of the blobArray section.

type PersistReplyBlobArrayMembsReadI 

type PersistReplyBlobArrayMembsReadI interface {
	GetMembValueLowCardRef(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) iter.Seq[uint64]
}

PersistReplyBlobArrayMembsReadI is the Memberships-side view of the blobArray section.

type PersistReplyBlobArraySecI 

type PersistReplyBlobArraySecI[Attr any, Ent any] interface {
	BeginAttributeSingle(value []byte) Attr
	EndSection() Ent
}

PersistReplyBlobArraySecI is the Section-side view: opens an attribute and closes the section. Attr and Ent are bound at the call site by inference.

type PersistReplyBoolAttrI 

type PersistReplyBoolAttrI interface {
	dmlruntime.InAttributeMembershipLowCardRefPI
	EndAttributeP()
}

PersistReplyBoolAttrI is the InAttr-side view of the bool section. P-variants only — every method returns void so no F-bounded `[Self]` parameter is needed.

type PersistReplyBoolAttrsReadI 

type PersistReplyBoolAttrsReadI interface {
	GetAttrValueValue(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) bool
	GetNumberOfAttributes(entityIdx raruntime.EntityIdx) int64
}

PersistReplyBoolAttrsReadI is the Attributes-side view of the bool section.

type PersistReplyBoolMembsReadI 

type PersistReplyBoolMembsReadI interface {
	GetMembValueLowCardRef(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) iter.Seq[uint64]
}

PersistReplyBoolMembsReadI is the Memberships-side view of the bool section.

type PersistReplyBoolSecI 

type PersistReplyBoolSecI[Attr any, Ent any] interface {
	BeginAttribute(value bool) Attr
	EndSection() Ent
}

PersistReplyBoolSecI is the Section-side view: opens an attribute and closes the section. Attr and Ent are bound at the call site by inference.

type PersistReplyCodec 

type PersistReplyCodec struct{}

PersistReplyCodec is the buscodec.CodecI bridge for PersistReply. 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 (*PersistReplyCodec) ContentType 

func (inst *PersistReplyCodec) ContentType() (ct string)

func (*PersistReplyCodec) Decode 

func (inst *PersistReplyCodec) Decode(b []byte, v any) (err error)

func (*PersistReplyCodec) Encode 

func (inst *PersistReplyCodec) Encode(v any) (b []byte, err error)

func (*PersistReplyCodec) Name 

func (inst *PersistReplyCodec) Name() (n string)

type PersistReplyColumns 

type PersistReplyColumns struct {
	FactId     []uint64
	NaturalKey [][]byte
	At         []time.Time

	Found  []bool
	Value  [][]byte
	Reason []string
}

PersistReplyColumns is the SoA storage for batches of PersistReply rows. All slices grow in lockstep — Len returns the row count.

func (*PersistReplyColumns) Append 

func (c *PersistReplyColumns) Append(row PersistReply)

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 (*PersistReplyColumns) Len 

func (c *PersistReplyColumns) Len() int

Len returns the number of rows currently in the batch.

func (*PersistReplyColumns) Marshal 

func (c *PersistReplyColumns) 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 PersistReplyBuildEntities — the per-row chain lives there and works against any leeway-DML class that structurally satisfies PersistReplyEntityI.

func (*PersistReplyColumns) Row 

func (c *PersistReplyColumns) Row(i int) (row PersistReply)

Row reconstructs entity i as an AoS PersistReply record. Inverse of Append: slice / pointer fields are shared by reference (no defensive copy); scalar fields and Option[T] are copied.

func (*PersistReplyColumns) Unmarshal 

func (c *PersistReplyColumns) 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 PersistReplyFillFromArrow — the per-row decode lives there.

type PersistReplyEntityI 

type PersistReplyEntityI[
	BoolAttr PersistReplyBoolAttrI,
	BoolSec PersistReplyBoolSecI[BoolAttr, Ent],
	BlobArrayAttr PersistReplyBlobArrayAttrI,
	BlobArraySec PersistReplyBlobArraySecI[BlobArrayAttr, Ent],
	TextArrayAttr PersistReplyTextArrayAttrI,
	TextArraySec PersistReplyTextArraySecI[TextArrayAttr, Ent],
	Ent any,
] interface {
	BeginEntity() Ent
	SetId(id uint64, naturalKey []byte) Ent
	SetTimestamp(ts time.Time) Ent
	GetSectionBool() BoolSec
	GetSectionBlobArray() BlobArraySec
	GetSectionTextArray() TextArraySec
	CommitEntity() (err error)
}

PersistReplyEntityI is the entity-builder surface PersistReplyAddSections 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 PersistReplyTextArrayAttrI 

type PersistReplyTextArrayAttrI interface {
	dmlruntime.InAttributeMembershipLowCardRefPI
	EndAttributeP()
}

PersistReplyTextArrayAttrI 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 PersistReplyTextArrayAttrsReadI 

type PersistReplyTextArrayAttrsReadI interface {
	GetAttrValueSingle(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) (string, error)
	GetNumberOfAttributes(entityIdx raruntime.EntityIdx) int64
}

PersistReplyTextArrayAttrsReadI is the Attributes-side view of the textArray section.

type PersistReplyTextArrayMembsReadI 

type PersistReplyTextArrayMembsReadI interface {
	GetMembValueLowCardRef(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) iter.Seq[uint64]
}

PersistReplyTextArrayMembsReadI is the Memberships-side view of the textArray section.

type PersistReplyTextArraySecI 

type PersistReplyTextArraySecI[Attr any, Ent any] interface {
	BeginAttributeSingle(value string) Attr
	EndSection() Ent
}

PersistReplyTextArraySecI is the Section-side view: opens an attribute and closes the section. Attr and Ent are bound at the call site by inference.

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.