payloadregistry

package
v0.1.0-alpha.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package payloadregistry is the single type authority for a binary (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 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 ADR-029: consumers use the *Registry instance form and dependency-inject it like other registries.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Builder

type Builder func(fields map[string]any) (any, error)

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 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 (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 New

func New() *Registry

New creates a new empty payload registry.

func (*Registry) Build

func (pr *Registry) Build(domain, category, version string, fields map[string]any) (any, error)

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

func (pr *Registry) Contracts() []contract.Contract

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

func (pr *Registry) Create(domain, category, version string) any

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

func (pr *Registry) IndexingProfileFor(msgType types.Type) (profile string, registered bool)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL