Documentation
¶
Overview ¶
Package payloadregistry is the single type authority for a binary (SemStreams ADR-103): a message.Type is a type of the deployment if and only if it is registered here. A registration carries the factory that decodes the type, the SemStreams ADR-054 indexing-profile floor graph-ingest stamps on entities born with it, and the projection contracts bound to it. There is no second catalogue of types and no global registry — each binary constructs its own and injects it through component.Dependencies.PayloadRegistry.
Import edge: payloadregistry → pkg/projection/contract → {pkg/types, vocabulary → pkg/platform}. The genuinely new transitive dependency this adds is vocabulary itself — five init()s (hierarchy.go, labels.go, lifecycle.go, relationships.go, rulepacks/predicates.go) and a global predicate registry; pkg/platform was already reached through message. `message` imports this package and therefore inherits the edge. The package still reaches neither message nor any component package, so message and agentic can both import it without a cycle.
Pattern A (boot-registry) per SemStreams ADR-029: consumers use the *Registry instance form and dependency-inject it like other registries.
Index ¶
- type Builder
- type Factory
- type Registration
- type Registry
- func (pr *Registry) Build(domain, category, version string, fields map[string]any) (any, error)
- func (pr *Registry) Contracts() []contract.Contract
- func (pr *Registry) Create(domain, category, version string) any
- func (pr *Registry) GetRegistration(msgType types.Type) (*Registration, bool)
- func (pr *Registry) IndexingProfileFor(msgType types.Type) (profile string, registered bool)
- func (pr *Registry) List() map[string]*Registration
- func (pr *Registry) ListByDomain(domain string) []*Registration
- func (pr *Registry) Register(registration *Registration) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
Builder creates a typed payload from field mappings. Used by workflow variable interpolation to construct typed payloads from step output maps. Returns error if required fields are missing or field values cannot be converted to the target type. Returns any to avoid import cycles - the actual payload should implement message.Payload.
OPTIONAL: If not provided, BuildPayload falls back to JSON marshal/unmarshal using the Factory to create the target type. Custom builders are only needed for performance optimization of high-frequency payload types.
type Factory ¶
type Factory func() any
Factory creates a payload instance for a specific message type. The factory returns an any to avoid import cycles. The actual payload should implement the message.Payload interface.
type Registration ¶
type Registration struct {
Factory Factory `json:"-"` // Factory function (not serializable)
Builder Builder `json:"-"` // Builder function (not serializable)
Domain string `json:"domain"` // Message domain (e.g., "robotics", "sensors")
Category string `json:"category"` // Message category (e.g., "heartbeat", "gps")
Version string `json:"version"` // Schema version (e.g., "v1", "v2")
Description string `json:"description"` // Human-readable description
Example map[string]any `json:"example"` // Optional example payload data
// IndexingProfile is the SemStreams ADR-054 channel-(c) floor graph-ingest stamps on
// an entity born with this type when the producer declares none. Empty
// means the type declares no floor: ingest applies control and meters
// the gap under indexing_profile_default_total{message_type}.
IndexingProfile string `json:"indexing_profile,omitempty"`
// Contracts are the projection contracts bound to this type. Each names
// this registration's key (an empty MessageType is filled at Register);
// a contract naming another key is a registration error.
Contracts []contract.Contract `json:"-"`
}
Registration holds factory and metadata for a payload type, plus the attributes registered with the type (SemStreams ADR-103): its indexing-profile floor and the projection contracts bound to it.
func (*Registration) MessageType ¶
func (pr *Registration) MessageType() string
MessageType returns the formatted message type string for this registration. Format: "domain.category.version" (e.g., "robotics.heartbeat.v1")
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages payload factories for message deserialization. It provides thread-safe registration and lookup of payload factories, enabling BaseMessage.UnmarshalJSON to recreate typed payloads from JSON.
func (*Registry) Build ¶
Build creates a typed payload from field mappings. If a custom Builder is registered, it is used for efficient field mapping. Otherwise, falls back to JSON marshal/unmarshal using the Factory.
Returns an error if the message type is not registered or if building fails.
func (*Registry) Contracts ¶
Contracts returns fresh copies of every projection contract registered with a type, ordered by message-type key and then by contract name. The composition root derives its mutation-client contract set from it; no other table of framework contracts exists.
func (*Registry) Create ¶
Create creates a payload instance using the registered factory. Returns nil if the message type is not registered; BaseMessage.UnmarshalJSON then rejects the payload as unregistered — the fact lane admits only registered types.
func (*Registry) GetRegistration ¶
func (pr *Registry) GetRegistration(msgType types.Type) (*Registration, bool)
GetRegistration returns the payload registration for a specific message type. Returns the registration and true if found, nil and false otherwise.
func (*Registry) IndexingProfileFor ¶
IndexingProfileFor returns the floor registered with msgType and whether the type is registered in this registry. A registered type may declare no floor (profile == ""); an unregistered type reports ("", false). Floors exist per binary because registrations do.
func (*Registry) List ¶
func (pr *Registry) List() map[string]*Registration
List returns all registered payload types. Returns a copy of the registrations map to prevent external modification.
func (*Registry) ListByDomain ¶
func (pr *Registry) ListByDomain(domain string) []*Registration
ListByDomain returns all payload registrations for a specific domain. This is useful for discovering what message types are available within a particular domain (e.g., "robotics", "sensors").
func (*Registry) Register ¶
func (pr *Registry) Register(registration *Registration) error
Register registers a payload factory with validation. The message type is derived from the registration's Domain, Category, and Version fields. Returns an error if validation fails or the type is already registered.