watchevent

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 watchevent is the leeway-coded wire form of one filesystem-watch event published on `fs.handle.{uuid}.event`.

Vocabulary:

  • vdd.MembWatchEventKind — narrow symbol; the fsbroker.WatchEventKindE rendered as its canonical String() ("create" / "delete" / "modify" / "attrib" / "renameFrom" / "renameTo" / "overflow" / "closed" / "unspecified"). A new fsbroker.ParseWatchEventKind helper provides the symmetric inverse for read-side reconstruction.
  • vdd.MembWatchEventName — narrow string; basename or relative path. Empty when the event addresses the watched root itself.
  • vdd.MembWatchEventCookie — narrow u32; inotify RenameFrom/RenameTo pairing cookie. Zero on poller-backed watches.

The producer-side Ts field (unix nanoseconds — `watcher.go` uses `time.Now().UnixNano()` everywhere) maps to the codec's plain `ts=At` via `time.Unix(0, Ts)` at the boundary.

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 WatchEventActiveFields = sync.OnceValue(func() []int {
	active := map[string]bool{"stringArray": true, "symbol": true, "u32Array": 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
})

WatchEventActiveFields 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 WatchEventActiveSections = []int{9, 10, 15}

WatchEventActiveSections 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 WatchEventAddSections added in v0.0.17 

func WatchEventAddSections[
	SymbolAttr WatchEventSymbolAttrI,
	SymbolSec WatchEventSymbolSecI[SymbolAttr, Ent],
	StringArrayAttr WatchEventStringArrayAttrI,
	StringArraySec WatchEventStringArraySecI[StringArrayAttr, Ent],
	U32ArrayAttr WatchEventU32ArrayAttrI,
	U32ArraySec WatchEventU32ArraySecI[U32ArrayAttr, Ent],
	Ent any,
	DML WatchEventEntityI[
		SymbolAttr, SymbolSec,
		StringArrayAttr, StringArraySec,
		U32ArrayAttr, U32ArraySec,
		Ent,
	],
](dml DML, row WatchEvent) (err error)

WatchEventAddSections 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 WatchEventBuildEntities 

func WatchEventBuildEntities[
	SymbolAttr WatchEventSymbolAttrI,
	SymbolSec WatchEventSymbolSecI[SymbolAttr, Ent],
	StringArrayAttr WatchEventStringArrayAttrI,
	StringArraySec WatchEventStringArraySecI[StringArrayAttr, Ent],
	U32ArrayAttr WatchEventU32ArrayAttrI,
	U32ArraySec WatchEventU32ArraySecI[U32ArrayAttr, Ent],
	Ent any,
	DML WatchEventEntityI[
		SymbolAttr, SymbolSec,
		StringArrayAttr, StringArraySec,
		U32ArrayAttr, U32ArraySec,
		Ent,
	],
](dml DML, c *WatchEventColumns) (err error)

WatchEventBuildEntities 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 WatchEventEmitSectionStringArray added in v0.0.20 

func WatchEventEmitSectionStringArray[
	StringArrayAttr WatchEventStringArrayAttrI,
	StringArraySec WatchEventStringArraySecI[StringArrayAttr, Ent],
	Ent any,
](stringArraySec StringArraySec, row WatchEvent) (err error)

WatchEventEmitSectionStringArray writes this kind's stringArray 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 WatchEventEmitSectionSymbol added in v0.0.20 

func WatchEventEmitSectionSymbol[
	SymbolAttr WatchEventSymbolAttrI,
	SymbolSec WatchEventSymbolSecI[SymbolAttr, Ent],
	Ent any,
](symbolSec SymbolSec, row WatchEvent) (err error)

WatchEventEmitSectionSymbol writes this kind's symbol 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 WatchEventEmitSectionU32Array added in v0.0.20 

func WatchEventEmitSectionU32Array[
	U32ArrayAttr WatchEventU32ArrayAttrI,
	U32ArraySec WatchEventU32ArraySecI[U32ArrayAttr, Ent],
	Ent any,
](u32ArraySec U32ArraySec, row WatchEvent) (err error)

WatchEventEmitSectionU32Array writes this kind's u32Array 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 WatchEventFillFromArrow 

func WatchEventFillFromArrow[
	SymbolAttrs WatchEventSymbolAttrsReadI,
	SymbolMembs WatchEventSymbolMembsReadI,
	StringArrayAttrs WatchEventStringArrayAttrsReadI,
	StringArrayMembs WatchEventStringArrayMembsReadI,
	U32ArrayAttrs WatchEventU32ArrayAttrsReadI,
	U32ArrayMembs WatchEventU32ArrayMembsReadI,
](
	c *WatchEventColumns,
	n int,
	idCol *array.Uint64,
	nkCol *array.Binary,
	tsCol *array.Timestamp,
	symbolAttrs SymbolAttrs,
	symbolMembs SymbolMembs,
	stringArrayAttrs StringArrayAttrs,
	stringArrayMembs StringArrayMembs,
	u32ArrayAttrs U32ArrayAttrs,
	u32ArrayMembs U32ArrayMembs,
) (err error)

WatchEventFillFromArrow 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 WatchEvent 

type WatchEvent struct {
	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"`

	// Kind is fsbroker.WatchEventKindE.String() — the canonical
	// rendering of the event class.
	Kind string `lw:"watchEventKind,symbol"`

	// Name is the affected entry's basename or relative path. Empty
	// when the event addresses the watched root.
	Name string `lw:"watchEventName,stringArray"`

	// Cookie pairs RenameFrom / RenameTo events on inotify-backed
	// watches; zero elsewhere.
	Cookie uint32 `lw:"watchEventCookie,u32Array"`
	// contains filtered or unexported fields
}

WatchEvent is the flat wire form of one filesystem event.

func WatchEventReadRow added in v0.0.17 

func WatchEventReadRow[
	SymbolAttrs WatchEventSymbolAttrsReadI,
	SymbolMembs WatchEventSymbolMembsReadI,
	StringArrayAttrs WatchEventStringArrayAttrsReadI,
	StringArrayMembs WatchEventStringArrayMembsReadI,
	U32ArrayAttrs WatchEventU32ArrayAttrsReadI,
	U32ArrayMembs WatchEventU32ArrayMembsReadI,
](
	i int,
	symbolAttrs SymbolAttrs,
	symbolMembs SymbolMembs,
	stringArrayAttrs StringArrayAttrs,
	stringArrayMembs StringArrayMembs,
	u32ArrayAttrs U32ArrayAttrs,
	u32ArrayMembs U32ArrayMembs,
) (row WatchEvent, present bool, err error)

WatchEventReadRow reads row i as one optional WatchEvent 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 WatchEventCodec 

type WatchEventCodec struct{}

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

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

func (*WatchEventCodec) Decode 

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

func (*WatchEventCodec) Encode 

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

func (*WatchEventCodec) Name 

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

type WatchEventColumns 

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

	Kind   []string
	Name   []string
	Cookie []uint32
}

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

func (*WatchEventColumns) Append 

func (c *WatchEventColumns) Append(row WatchEvent)

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

func (c *WatchEventColumns) Len() int

Len returns the number of rows currently in the batch.

func (*WatchEventColumns) Marshal 

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

func (*WatchEventColumns) Row 

func (c *WatchEventColumns) Row(i int) (row WatchEvent)

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

func (*WatchEventColumns) Unmarshal 

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

type WatchEventEntityI 

type WatchEventEntityI[
	SymbolAttr WatchEventSymbolAttrI,
	SymbolSec WatchEventSymbolSecI[SymbolAttr, Ent],
	StringArrayAttr WatchEventStringArrayAttrI,
	StringArraySec WatchEventStringArraySecI[StringArrayAttr, Ent],
	U32ArrayAttr WatchEventU32ArrayAttrI,
	U32ArraySec WatchEventU32ArraySecI[U32ArrayAttr, Ent],
	Ent any,
] interface {
	BeginEntity() Ent
	SetId(id uint64, naturalKey []byte) Ent
	SetTimestamp(ts time.Time) Ent
	GetSectionSymbol() SymbolSec
	GetSectionStringArray() StringArraySec
	GetSectionU32Array() U32ArraySec
	CommitEntity() (err error)
}

WatchEventEntityI is the entity-builder surface WatchEventAddSections 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 WatchEventStringArrayAttrI 

type WatchEventStringArrayAttrI interface {
	dmlruntime.InAttributeMembershipLowCardRefPI
	EndAttributeP()
}

WatchEventStringArrayAttrI 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 WatchEventStringArrayAttrsReadI 

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

WatchEventStringArrayAttrsReadI is the Attributes-side view of the stringArray section.

type WatchEventStringArrayMembsReadI 

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

WatchEventStringArrayMembsReadI is the Memberships-side view of the stringArray section.

type WatchEventStringArraySecI 

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

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

type WatchEventSymbolAttrI 

type WatchEventSymbolAttrI interface {
	dmlruntime.InAttributeMembershipLowCardRefPI
	EndAttributeP()
}

WatchEventSymbolAttrI 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 WatchEventSymbolAttrsReadI 

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

WatchEventSymbolAttrsReadI is the Attributes-side view of the symbol section.

type WatchEventSymbolMembsReadI 

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

WatchEventSymbolMembsReadI is the Memberships-side view of the symbol section.

type WatchEventSymbolSecI 

type WatchEventSymbolSecI[Attr any, Ent any] interface {
	BeginAttribute(value string) Attr
	EndSection() Ent
}

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

type WatchEventU32ArrayAttrI 

type WatchEventU32ArrayAttrI interface {
	dmlruntime.InAttributeMembershipLowCardRefPI
	EndAttributeP()
}

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

type WatchEventU32ArrayAttrsReadI 

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

WatchEventU32ArrayAttrsReadI is the Attributes-side view of the u32Array section.

type WatchEventU32ArrayMembsReadI 

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

WatchEventU32ArrayMembsReadI is the Memberships-side view of the u32Array section.

type WatchEventU32ArraySecI 

type WatchEventU32ArraySecI[Attr any, Ent any] interface {
	BeginAttributeSingle(value uint32) Attr
	EndSection() Ent
}

WatchEventU32ArraySecI 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.