Documentation
¶
Overview ¶
Package payloadregistry provides type-discriminated payload registration and lookup for message.BaseMessage deserialization.
Lives as a leaf package (imports only stdlib + pkg/errs + pkg/types) so it can be referenced by both `message` and `agentic` without creating an import cycle. Previously these types lived in `component`, which forced agentic and message to import component solely for payload registration — the cycle that blocked clean dependency wiring of model.RegistryReader-style typed registries.
Pattern A (boot-registry) per ADR-029. The package-level singleton (Register / Create / Build / GlobalRegistry) is preserved for backward compatibility with existing init()-based registrations, but new consumers should prefer 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) Create(domain, category, version string) any
- func (pr *Registry) GetRegistration(msgType string) (*Registration, 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
}
Registration holds factory and metadata for a payload type.
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 NewForTest ¶
NewForTest returns a fresh empty Registry suitable for unit tests that want full isolation from other tests in the same process. Registers nothing — caller adds whatever payloads the test needs.
For tests that want the full first-party builtin set, the payloadbuiltins package provides a Register helper; tests in higher layers can call it after constructing a registry here. We don't import payloadbuiltins from this package because doing so would re-introduce the import cycle this package is structured to avoid.
func NewWithSubset ¶
NewWithSubset returns a fresh Registry populated by calling each supplied registration function in order. Useful when a test needs a subset of builtin payloads — e.g., only `agentic` types — without pulling in the full first-party set.
reg := payloadregistry.NewWithSubset(t, agentic.RegisterPayloads)
Aggregates registration errors via errors.Join; calls tb.Fatal on any error so the test terminates immediately.
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) Create ¶
Create creates a payload instance using the registered factory. Returns nil if the message type is not registered. This allows BaseMessage.UnmarshalJSON to handle unknown types gracefully by falling back to GenericPayload.
func (*Registry) GetRegistration ¶
func (pr *Registry) GetRegistration(msgType string) (*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) 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.
Source Files