composition

package
v0.1.0-alpha.5 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package composition validates a component composition — the boot configuration's components composed with the catalog a binary registers — as a pure function, and projects it as a graph.

Two evidence classes share one interpreter (ADR-100):

  • Validate(catalog, cfg) is the offline judgment: each factory's static port declarer (component.Registration.Ports) predicts the ports the next boot would admit, with no NATS, no process, and no construction. Two components whose exclusive claims clash are judged by component.Declaration.ConflictWith, the rule boot admission applies.
  • Analyze(declarations, streams) is the graph-level half of the same function over declarations and the configuration's explicit streams. It refuses any stream, explicit or derived from a JetStream output, whose subject filter could capture a graph request subject (reserved_subject_capture), and reports every NATS, NATS-request or JetStream port subject, in either lane, and every explicit stream subject that fails the subject grammar (malformed_subject). It refuses a NATS-request input overlapping a subject of graph.QueryVerbs() that is not its factory's to answer, or that an earlier instance of the responder already declares (request_subject_conflict); it sees declared ports only. Service's component manager runs Analyze over what was admitted at boot and refuses to boot on an error-severity finding (ADR-100 decision 3).

FlowPaths and Mermaid read the projected graph: Mermaid draws it, and FlowPaths answers, for each input node, every node reachable from it. The component manager's flowgraph and paths routes serve them.

Findings carry a closed vocabulary (the Type* constants), one severity table (severityOf), non-nil arrays, and a deterministic order, so two runs over equal inputs marshal to byte-equal JSON. A product checks a composition in its own tests by calling Validate and requiring an empty Errors list.

Index

Constants

View Source
const (
	// TypeConfigInvalid: config.Config.ValidateDocument rejected the document.
	TypeConfigInvalid = "config_invalid"
	// TypeUnknownComponent: the configuration names a factory the catalog does not register.
	TypeUnknownComponent = "unknown_component"
	// TypeComponentTypeMismatch: the configured type differs from the factory's registered type.
	TypeComponentTypeMismatch = "component_type_mismatch"
	// TypeComponentConfigInvalid: the component entry itself is invalid (name, type, or raw config security check).
	TypeComponentConfigInvalid = "component_config_invalid"
	// TypePortDeclarationError: the factory's port declarer rejected the configuration.
	TypePortDeclarationError = "port_declaration_error"
	// TypeExclusiveResourceConflict: two components claim the same exclusive resource.
	TypeExclusiveResourceConflict = "exclusive_resource_conflict"
	// TypeConnectionPatternError: connecting the declared ports failed (KV writer conflicts, malformed graph-mutation providers).
	TypeConnectionPatternError = "connection_pattern_error"
	// TypeStreamRequirement: a JetStream subscriber is fed only by core-NATS publishers, so no stream will exist.
	TypeStreamRequirement = "stream_requirement"
	// TypeDisconnectedNode: a component with no connections at all.
	TypeDisconnectedNode = "disconnected_node"
	// TypeOrphanedPort: a port with no counterpart; an error when it is a required stream input with no publisher.
	TypeOrphanedPort = "orphaned_port"
	// TypeInterfaceMismatch: a derived edge joins an output and an input whose interface contracts differ.
	TypeInterfaceMismatch = "interface_mismatch"
	// TypeMissingInterface: a derived edge's target requires an interface its source does not declare.
	TypeMissingInterface = "missing_interface"
	// TypeEmptyComposition: no enabled components.
	TypeEmptyComposition = "empty_composition"
	// TypeReservedSubjectCapture: a stream's subject filter shares a concrete subject with a request
	// subject graph-ingest serves or with the graph mutation family, so the stream would store requests.
	TypeReservedSubjectCapture = "reserved_subject_capture"
	// TypeMalformedSubject: a port's or an explicit stream's subject fails the subject grammar
	// (flowgraph.ValidSubject), which is stricter than NATS: a token such as "a*" is refused.
	TypeMalformedSubject = "malformed_subject"
	// TypeRequestSubjectConflict: a NATS-request input overlaps a subject of graph.QueryVerbs() it is
	// not the responder for, or that an earlier instance of the responder already declares.
	TypeRequestSubjectConflict = "request_subject_conflict"
)

Finding types: the closed vocabulary every validator output draws from.

View Source
const (
	SeverityError   = "error"
	SeverityWarning = "warning"
)

Finding severities.

View Source
const (
	StatusValid    = "valid"
	StatusWarnings = "warnings"
	StatusErrors   = "errors"
)

Result statuses, derived errors → warnings → valid.

Variables

This section is empty.

Functions

func FlowPaths

func FlowPaths(graph Graph) map[string][]string

FlowPaths reports, for each origin in the projection, every node reachable from it. An origin is a node of type input, or a node with an input port whose pattern is network or http-client. Each value is the origin followed by every node reachable from it along the graph's edges, each node once, in depth-first order over the edges in the order the graph holds them. The map is never nil; it is empty when the graph has no origin. FlowPaths stores nothing and reads nothing but its argument.

func Mermaid

func Mermaid(graph Graph) string

Mermaid renders the projection as a `flowchart LR`: one node per component and one edge per derived connection, both in a stable order. Layout is the viewer's job.

Types

type CatalogEntry

type CatalogEntry struct {
	ID                 string                 `json:"id"`
	Name               string                 `json:"name"`
	Type               string                 `json:"type"`
	Protocol           string                 `json:"protocol"`
	Domain             string                 `json:"domain"`
	Description        string                 `json:"description"`
	Version            string                 `json:"version"`
	Category           string                 `json:"category"`
	Schema             component.ConfigSchema `json:"schema"`
	DefaultPorts       *Ports                 `json:"default_ports,omitempty"`
	PortsRequireConfig bool                   `json:"ports_require_config,omitempty"`
	PortsError         string                 `json:"ports_error,omitempty"`
}

CatalogEntry is one registered factory as the catalog presents it: its metadata, its configuration schema, and either the ports its declarer resolves for an empty configuration or the reason an empty configuration does not declare.

func Catalog

func Catalog(catalog *component.Registry) []CatalogEntry

Catalog lists every registered factory, sorted by ID, with its default ports (the declarer's output for the empty configuration `{}`) or the declarer's refusal.

type Edge

type Edge struct {
	From         string `json:"from"`
	FromPort     string `json:"from_port"`
	To           string `json:"to"`
	ToPort       string `json:"to_port"`
	Pattern      string `json:"pattern"`
	ConnectionID string `json:"connection_id"`
}

Edge is one derived connection between two ports.

type Finding

type Finding struct {
	Type        string   `json:"type"`
	Severity    string   `json:"severity"`
	Component   string   `json:"component"`
	Port        string   `json:"port,omitempty"`
	Message     string   `json:"message"`
	Suggestions []string `json:"suggestions"`
}

Finding is one validation finding. Component and Message are always non-empty; Suggestions is never nil.

type Graph

type Graph struct {
	Nodes []Node `json:"nodes"`
	Edges []Edge `json:"edges"`
}

Graph is the projection of a composition: one node per component with its resolved ports, one edge per derived connection. It is what a diagram is drawn from and is never stored by the framework.

type Node

type Node struct {
	Instance string     `json:"instance"`
	Factory  string     `json:"factory"`
	Type     string     `json:"type"`
	Inputs   []PortView `json:"inputs"`
	Outputs  []PortView `json:"outputs"`
}

Node is one component instance with its resolved ports.

type PortView

type PortView struct {
	Name         string `json:"name"`
	Direction    string `json:"direction"`
	Type         string `json:"type"` // interface contract type, empty when undeclared
	Required     bool   `json:"required"`
	External     bool   `json:"external,omitempty"` // fed from outside the composition (component.PortDefinition.External)
	ConnectionID string `json:"connection_id"`
	Pattern      string `json:"pattern"`
	Description  string `json:"description"`
	Kind         string `json:"kind"`
}

PortView is one resolved port as the projection shows it.

type Ports

type Ports struct {
	Inputs  []PortView `json:"inputs"`
	Outputs []PortView `json:"outputs"`
}

Ports is the resolved input and output lanes of one declaration.

type Result

type Result struct {
	Status   string    `json:"status"`
	Errors   []Finding `json:"errors"`
	Warnings []Finding `json:"warnings"`
	Graph    Graph     `json:"graph"`
}

Result is the outcome of validating or analyzing one composition. Every array is non-nil and every ordering is deterministic.

func Analyze

func Analyze(declarations []component.Declaration, streams config.StreamConfigs) *Result

Analyze is the graph-level half of composition validation: it connects the declarations, analyzes connectivity, stream requirements, and interface contracts, and projects the graph. Validate runs it over declared components; service's component manager runs it at boot over the admitted ones.

streams is the configuration's explicit `streams` block (nil when it has none). Stream provisioning derives streams from JetStream OUTPUT ports and from this block; a JetStream subscriber whose subjects an explicit stream covers is fed even when its publishers use core NATS, so it is not a stream_requirement finding.

func Validate

func Validate(catalog *component.Registry, cfg *config.Config) (*Result, error)

Validate is the offline judgment of a composition: every enabled component in cfg is checked against the catalog exactly as boot admission would check it — name, type, factory, raw-config security, the factory's port declarer, exclusive claims — and the declared ports are then analyzed as a graph. Components are visited in instance-name order, so a clash is reported on the later component and names the first holder in that order. It performs no I/O, opens no connection, and constructs no component; the only error return is for nil arguments, every judgment is a Finding.

Jump to

Keyboard shortcuts

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