Documentation
¶
Overview ¶
Package wire holds the on-the-wire and carried-state contract shared by the definition side (entity/entdefine) and the caller side (entity/entclient). Internal: neither kind authors nor callers see it.
Index ¶
Constants ¶
const ( DeleteSignalName = "entity-delete" DescribeQueryName = "describe" SetLabelsCommandName = "entity-set-labels" // NoteSignalName carries a domain EVENT into the entity's history: // fire-and-forget, no state change — the history line IS the point. NoteSignalName = "entity-note" )
Reserved signal/query/command names of the chassis.
const CompletedOpsCap = 100
CompletedOpsCap bounds the completed-operations dedup cache carried across Continue-as-New (article: "bounded result caches prevent history bloat", oldest entries evicted).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CommandEnvelope ¶
type CommandEnvelope struct {
RequestID entity.RequestID `json:"requestId"`
Name entity.CommandName `json:"name"`
Payload json.RawMessage `json:"payload"`
}
CommandEnvelope is one queued command. Handlers never execute side effects; they enqueue envelopes for the main loop to serialize.
type Envelope ¶
type Envelope[Spec, State any] struct { Initialized bool `json:"initialized"` Phase entity.Phase `json:"phase"` Spec Spec `json:"spec"` State State `json:"state"` // Labels are the entity's markers — metric-label semantics: small // string pairs for selection and grouping, never data. Mirrored to // the EntityLabels search attribute as "k=v" values. Labels map[string]string `json:"labels,omitempty"` MarkedForDeletion bool `json:"markedForDeletion"` Pending []CommandEnvelope `json:"pending"` Completed map[entity.RequestID]OpResult `json:"completed"` CompletedOrder []entity.RequestID `json:"completedOrder"` }
Envelope is the compact, resumable state of one entity — exactly what the article says to carry across Continue-as-New and nothing more: current status, resource configuration (Spec), user state, the marked-for-deletion flag, pending commands, and the bounded completed-operations cache. Large artifacts (manifests, plans, logs) must live in external storage; keep references in State.
func (*Envelope[Spec, State]) MergeLabels ¶
MergeLabels applies a label patch: empty values delete keys, the rest overwrite. Returns whether anything changed.
func (*Envelope[S, T]) RecordCompleted ¶
func (e *Envelope[S, T]) RecordCompleted(requestID entity.RequestID, res json.RawMessage, err error)
RecordCompleted stores a command outcome in the bounded dedup cache, evicting the oldest entries beyond CompletedOpsCap.
type OpResult ¶
type OpResult struct {
Result json.RawMessage `json:"result,omitempty"`
Err string `json:"err,omitempty"`
}
OpResult is a completed command outcome, cached by application-level request id so retried/duplicated requests dedup across Continue-as-New.
type UpdateArgs ¶
type UpdateArgs struct {
RequestID entity.RequestID `json:"requestId"`
Payload json.RawMessage `json:"payload"`
}
UpdateArgs is the wire shape of every command update: an application-level request id (generated by the client) plus the typed request encoded as JSON. The request id is what makes deduplication survive Continue-as-New — it lives in the envelope's completed-ops cache.
Source Files