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 ¶
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.
const ( SeverityError = "error" SeverityWarning = "warning" )
Finding severities.
const ( StatusValid = "valid" StatusWarnings = "warnings" StatusErrors = "errors" )
Result statuses, derived errors → warnings → valid.
Variables ¶
This section is empty.
Functions ¶
func FlowPaths ¶
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.
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 ¶
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 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 ¶
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.