Documentation
¶
Overview ¶
Package grantrequest is the leeway-coded wire form of the capability-grant request payload published on `runtime.cap.request`. First broker request/reply DTO to migrate off the buscodec fxamacker-cbor default onto the ADR-0042 SoA codec.
Pattern: nested-struct flatten. The producer-side [capbroker.GrantRequest] embeds an `app.SubjectFilter` (Pattern / Reason / Direction / Sticky). The leeway codec is flat by design — one fact kind, one row per call. Rather than introduce nested-row encoding to codegen, the codec DTO carries the SubjectFilter fields as *peer* tagged columns; conversion happens at the codec boundary inside `capbroker.MarshalRequest` / `UnmarshalRequest`. The broker's Go API (and the policy contract that consumes `req.SubjectFilter`) stays unchanged.
Vocabulary:
- vdd.MembAppId — shared with task.* DTOs.
- vdd.MembReason — shared with TaskCancel / TaskError.
- vdd.MembCapFilterPattern / vdd.MembCapDirection / vdd.MembCapFilterSticky — narrow, the flattened SubjectFilter columns.
Wire shape vs the legacy capbroker.GrantRequest JSON form:
- The nested `SubjectFilter` field becomes four peer columns (capFilterPattern / reason / capDirection / capFilterSticky).
- `Direction app.CapDirectionE` (uint8 enum) → `Direction string` (the canonical String() form). Producers call `filter.Direction.String()` at construction; consumers parse back with `app.ParseCapDirection(...)` (added in this migration).
- New `FactId uint64` plain `id` and `At time.Time` plain `ts` (per the leeway grammar contract — every fact has both).
Index ¶
- Variables
- func GrantRequestBuildEntities[StringArrayAttr GrantRequestStringArrayAttrI, ...](dml DML, c *GrantRequestColumns) (err error)
- func GrantRequestFillFromArrow[StringArrayAttrs GrantRequestStringArrayAttrsReadI, ...](c *GrantRequestColumns, n int, idCol *array.Uint64, nkCol *array.Binary, ...) (err error)
- type GrantRequest
- type GrantRequestBoolAttrI
- type GrantRequestBoolAttrsReadI
- type GrantRequestBoolMembsReadI
- type GrantRequestBoolSecI
- type GrantRequestCodec
- type GrantRequestColumns
- type GrantRequestEntityI
- type GrantRequestStringArrayAttrI
- type GrantRequestStringArrayAttrsReadI
- type GrantRequestStringArrayMembsReadI
- type GrantRequestStringArraySecI
- type GrantRequestSymbolAttrI
- type GrantRequestSymbolAttrsReadI
- type GrantRequestSymbolMembsReadI
- type GrantRequestSymbolSecI
- type GrantRequestTextArrayAttrI
- type GrantRequestTextArrayAttrsReadI
- type GrantRequestTextArrayMembsReadI
- type GrantRequestTextArraySecI
Constants ¶
This section is empty.
Variables ¶
var GrantRequestActiveFields = sync.OnceValue(func() []int { active := map[string]bool{"bool": true, "stringArray": true, "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 })
GrantRequestActiveFields is the column-index subset this kind populates in the runtime.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 GrantRequestActiveSections = []int{1, 9, 10, 12}
GrantRequestActiveSections 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.
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`.
Functions ¶
func GrantRequestBuildEntities ¶
func GrantRequestBuildEntities[ StringArrayAttr GrantRequestStringArrayAttrI, StringArraySec GrantRequestStringArraySecI[StringArrayAttr, Ent], TextArrayAttr GrantRequestTextArrayAttrI, TextArraySec GrantRequestTextArraySecI[TextArrayAttr, Ent], SymbolAttr GrantRequestSymbolAttrI, SymbolSec GrantRequestSymbolSecI[SymbolAttr, Ent], BoolAttr GrantRequestBoolAttrI, BoolSec GrantRequestBoolSecI[BoolAttr, Ent], Ent any, DML GrantRequestEntityI[ StringArrayAttr, StringArraySec, TextArrayAttr, TextArraySec, SymbolAttr, SymbolSec, BoolAttr, BoolSec, Ent, ], ](dml DML, c *GrantRequestColumns) (err error)
GrantRequestBuildEntities 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 GrantRequestFillFromArrow ¶
func GrantRequestFillFromArrow[ StringArrayAttrs GrantRequestStringArrayAttrsReadI, StringArrayMembs GrantRequestStringArrayMembsReadI, TextArrayAttrs GrantRequestTextArrayAttrsReadI, TextArrayMembs GrantRequestTextArrayMembsReadI, SymbolAttrs GrantRequestSymbolAttrsReadI, SymbolMembs GrantRequestSymbolMembsReadI, BoolAttrs GrantRequestBoolAttrsReadI, BoolMembs GrantRequestBoolMembsReadI, ]( c *GrantRequestColumns, n int, idCol *array.Uint64, nkCol *array.Binary, tsCol *array.Timestamp, stringArrayAttrs StringArrayAttrs, stringArrayMembs StringArrayMembs, textArrayAttrs TextArrayAttrs, textArrayMembs TextArrayMembs, symbolAttrs SymbolAttrs, symbolMembs SymbolMembs, boolAttrs BoolAttrs, boolMembs BoolMembs, ) (err error)
GrantRequestFillFromArrow 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 GrantRequest ¶
type GrantRequest struct {
// FactId is the per-row event id (currently zero from the
// producer; awaits the per-handle sequencer follow-up flagged in
// the TaskProgress migration).
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"`
// AppId names the app the grant targets. M2.3 logs but does not
// enforce a mismatch between AppId and Msg.Sender; M4 NKey-based
// identity upgrades that to an enforcement boundary.
AppId string `lw:"appId,stringArray"`
// FilterPattern is app.SubjectFilter.Pattern.
FilterPattern string `lw:"capFilterPattern,stringArray"`
// FilterReason is app.SubjectFilter.Reason. Shares the cross-DTO
// `reason` vocabulary entry — the same column type the audit /
// task-cancel rows use.
FilterReason string `lw:"reason,textArray"`
// FilterDirection is app.CapDirectionE.String() — one of "pub",
// "sub", "pub+sub", or "unspecified".
FilterDirection string `lw:"capDirection,symbol"`
// FilterSticky is app.SubjectFilter.Sticky.
FilterSticky bool `lw:"capFilterSticky,bool"`
// contains filtered or unexported fields
}
GrantRequest is the flat wire form of a capability-grant request. The Go-level [capbroker.GrantRequest] keeps its nested-struct shape; this struct is the codec-side projection only.
type GrantRequestBoolAttrI ¶
type GrantRequestBoolAttrI interface {
dmlruntime.InAttributeMembershipLowCardRefPI
EndAttributeP()
}
GrantRequestBoolAttrI 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 GrantRequestBoolAttrsReadI ¶
type GrantRequestBoolAttrsReadI interface {
GetAttrValueValue(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) bool
GetNumberOfAttributes(entityIdx raruntime.EntityIdx) int64
}
GrantRequestBoolAttrsReadI is the Attributes-side view of the bool section.
type GrantRequestBoolMembsReadI ¶
type GrantRequestBoolMembsReadI interface {
GetMembValueLowCardRef(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) iter.Seq[uint64]
}
GrantRequestBoolMembsReadI is the Memberships-side view of the bool section.
type GrantRequestBoolSecI ¶
type GrantRequestBoolSecI[Attr any, Ent any] interface { BeginAttribute(value bool) Attr EndSection() Ent }
GrantRequestBoolSecI is the Section-side view: opens an attribute and closes the section. Attr and Ent are bound at the call site by inference.
type GrantRequestCodec ¶
type GrantRequestCodec struct{}
GrantRequestCodec is the buscodec.CodecI bridge for GrantRequest. 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 (*GrantRequestCodec) ContentType ¶
func (inst *GrantRequestCodec) ContentType() (ct string)
func (*GrantRequestCodec) Decode ¶
func (inst *GrantRequestCodec) Decode(b []byte, v any) (err error)
func (*GrantRequestCodec) Encode ¶
func (inst *GrantRequestCodec) Encode(v any) (b []byte, err error)
func (*GrantRequestCodec) Name ¶
func (inst *GrantRequestCodec) Name() (n string)
type GrantRequestColumns ¶
type GrantRequestColumns struct {
FactId []uint64
NaturalKey [][]byte
At []time.Time
AppId []string
FilterPattern []string
FilterReason []string
FilterDirection []string
FilterSticky []bool
}
GrantRequestColumns is the SoA storage for batches of GrantRequest rows. All slices grow in lockstep — Len returns the row count.
func (*GrantRequestColumns) Append ¶
func (c *GrantRequestColumns) Append(row GrantRequest)
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 (*GrantRequestColumns) Len ¶
func (c *GrantRequestColumns) Len() int
Len returns the number of rows currently in the batch.
func (*GrantRequestColumns) Marshal ¶
func (c *GrantRequestColumns) 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 GrantRequestBuildEntities — the per-row chain lives there and works against any leeway-DML class that structurally satisfies GrantRequestEntityI.
func (*GrantRequestColumns) Row ¶
func (c *GrantRequestColumns) Row(i int) (row GrantRequest)
Row reconstructs entity i as an AoS GrantRequest record. Inverse of Append: slice / pointer fields are shared by reference (no defensive copy); scalar fields and Option[T] are copied.
func (*GrantRequestColumns) Unmarshal ¶
func (c *GrantRequestColumns) Unmarshal(rec arrow.Record) (err error)
Unmarshal appends one row to c per entity in rec, projecting the runtime.facts columns through factsschema/ra. Thin wrapper around GrantRequestFillFromArrow — the per-row decode lives there.
type GrantRequestEntityI ¶
type GrantRequestEntityI[ StringArrayAttr GrantRequestStringArrayAttrI, StringArraySec GrantRequestStringArraySecI[StringArrayAttr, Ent], TextArrayAttr GrantRequestTextArrayAttrI, TextArraySec GrantRequestTextArraySecI[TextArrayAttr, Ent], SymbolAttr GrantRequestSymbolAttrI, SymbolSec GrantRequestSymbolSecI[SymbolAttr, Ent], BoolAttr GrantRequestBoolAttrI, BoolSec GrantRequestBoolSecI[BoolAttr, Ent], Ent any, ] interface { BeginEntity() Ent SetId(id uint64, naturalKey []byte) Ent SetTimestamp(ts time.Time) Ent GetSectionStringArray() StringArraySec GetSectionTextArray() TextArraySec GetSectionSymbol() SymbolSec GetSectionBool() BoolSec CommitEntity() (err error) }
GrantRequestEntityI lists exactly the entity-level methods GrantRequest uses. Type parameters compose the per-section Attr + Sec interfaces; Ent is the entity type itself (return type of BeginEntity / SetId / SetTimestamp / SetLifecycle — usually the DML pointer).
type GrantRequestStringArrayAttrI ¶
type GrantRequestStringArrayAttrI interface {
dmlruntime.InAttributeMembershipLowCardRefPI
EndAttributeP()
}
GrantRequestStringArrayAttrI 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 GrantRequestStringArrayAttrsReadI ¶
type GrantRequestStringArrayAttrsReadI interface {
GetAttrValueSingleOrDefault(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) string
GetNumberOfAttributes(entityIdx raruntime.EntityIdx) int64
}
GrantRequestStringArrayAttrsReadI is the Attributes-side view of the stringArray section.
type GrantRequestStringArrayMembsReadI ¶
type GrantRequestStringArrayMembsReadI interface {
GetMembValueLowCardRef(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) iter.Seq[uint64]
}
GrantRequestStringArrayMembsReadI is the Memberships-side view of the stringArray section.
type GrantRequestStringArraySecI ¶
type GrantRequestStringArraySecI[Attr any, Ent any] interface { BeginAttributeSingle(value string) Attr EndSection() Ent }
GrantRequestStringArraySecI is the Section-side view: opens an attribute and closes the section. Attr and Ent are bound at the call site by inference.
type GrantRequestSymbolAttrI ¶
type GrantRequestSymbolAttrI interface {
dmlruntime.InAttributeMembershipLowCardRefPI
EndAttributeP()
}
GrantRequestSymbolAttrI 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 GrantRequestSymbolAttrsReadI ¶
type GrantRequestSymbolAttrsReadI interface {
GetAttrValueValue(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) string
GetNumberOfAttributes(entityIdx raruntime.EntityIdx) int64
}
GrantRequestSymbolAttrsReadI is the Attributes-side view of the symbol section.
type GrantRequestSymbolMembsReadI ¶
type GrantRequestSymbolMembsReadI interface {
GetMembValueLowCardRef(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) iter.Seq[uint64]
}
GrantRequestSymbolMembsReadI is the Memberships-side view of the symbol section.
type GrantRequestSymbolSecI ¶
type GrantRequestSymbolSecI[Attr any, Ent any] interface { BeginAttribute(value string) Attr EndSection() Ent }
GrantRequestSymbolSecI is the Section-side view: opens an attribute and closes the section. Attr and Ent are bound at the call site by inference.
type GrantRequestTextArrayAttrI ¶
type GrantRequestTextArrayAttrI interface {
dmlruntime.InAttributeMembershipLowCardRefPI
EndAttributeP()
}
GrantRequestTextArrayAttrI 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 GrantRequestTextArrayAttrsReadI ¶
type GrantRequestTextArrayAttrsReadI interface {
GetAttrValueSingleOrDefault(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) string
GetNumberOfAttributes(entityIdx raruntime.EntityIdx) int64
}
GrantRequestTextArrayAttrsReadI is the Attributes-side view of the textArray section.
type GrantRequestTextArrayMembsReadI ¶
type GrantRequestTextArrayMembsReadI interface {
GetMembValueLowCardRef(entityIdx raruntime.EntityIdx, attrIdx raruntime.AttributeIdx) iter.Seq[uint64]
}
GrantRequestTextArrayMembsReadI is the Memberships-side view of the textArray section.
type GrantRequestTextArraySecI ¶
type GrantRequestTextArraySecI[Attr any, Ent any] interface { BeginAttributeSingle(value string) Attr EndSection() Ent }
GrantRequestTextArraySecI is the Section-side view: opens an attribute and closes the section. Attr and Ent are bound at the call site by inference.