Documentation
¶
Overview ¶
Package flowgraph builds a graph of how components connect through their declared ports and reports what that graph shows: which components are connected, which have no connections, and which ports nothing matches.
Building a graph ¶
BuildFromDeclarations is the one way to build a graph. It takes the component.Declaration of every component instance (the port shape the component Registry records when it admits an instance, or derives offline from a configuration), adds one node per instance and connects the ports. It returns an error when the declarations cannot form a valid graph: an empty or repeated instance name, a port with no connection identity, more than one writer port on a KV bucket, or a graph-mutation port that is malformed or not served by exactly one provider. Which ports are graph-mutation ports, and which shape is valid, is decided by graphmutation.ClassifyPort. Two binds on one network address are refused earlier, when the component Registry admits the second one.
In SemStreams the composition package is this package's one reader; it comes to SemEngine in a later change. Until then this package's tests are its only callers.
What the graph connects ¶
A port's pattern (its component.InteractionPattern) decides how it is matched.
- stream: an output joins every input on another component whose subject matches. A JetStream port also matches on each of its stream's subjects.
- request: an output and an input on different components with matching subjects join. Two ports of the same direction on different components join only when their subjects differ and still match (one holds a wildcard); two ports of one direction on the same subject do not join.
- watch and read: a watch output (a KV writer) joins every watch or read input on the same bucket, its own component's included. A bucket with more than one writer port is refused.
- store: every store output joins every store input on another component.
- network, http-client and timer: never joined.
Subject matching is this package's own rule: `*` stands for one token and `>` for one or more trailing tokens, and either side of a pair may hold the wildcard. SubjectCovers answers the one-way question of whether a filter covers every subject a pattern can name; SubjectsOverlap answers the two-way question of whether any one subject matches both.
ValidSubject reports whether a subject is well formed under the grammar both read: one or more "."-separated tokens, none empty; "*" and ">" only as a whole token, ">" only last; no space, tab, line feed, carriage return or form feed in any token. A malformed subject covers nothing, is covered by nothing and overlaps nothing. The grammar is stricter than NATS, which takes a token such as "a*" as plain text and accepts a form feed.
What the analysis reports ¶
FlowGraph.AnalyzeConnectivity reports the connected groups of components, the components with no edge, and the orphaned ports: ports no edge reaches. Network, http-client, store and timer ports are never orphans. Each orphan carries an Issue, one of the Issue constants.
The analysis reports facts and no severity. Whether an orphan or a lone component is a problem is the reader's judgment.
FlowGraph.ValidateStreamRequirements returns one warning for each JetStream input port that a plain NATS output port feeds, naming each publishing component once.
Concurrency ¶
A FlowGraph has no locks. Build it and read it on one goroutine.
Index ¶
Constants ¶
const ( IssueNoPublishers = "no_publishers" IssueNoSubscribers = "no_subscribers" IssueOptionalAPIUnused = "optional_api_unused" IssueOptionalIndexUnwatched = "optional_index_unwatched" )
Issue type constants for orphaned port classification
Variables ¶
This section is empty.
Functions ¶
func SubjectCovers ¶
SubjectCovers reports whether filter COVERS pattern: every concrete subject that matches pattern also matches filter under NATS wildcard semantics. It is directional: `data.>` covers `data.*`, `data.*` does not cover `data.>`, and `data.raw` does not cover `data.*`. Composition validation uses it to decide whether an explicit stream's subjects feed a JetStream subscriber's subjects. Edge derivation's unexported direct-match test is a different question and is not exported: it answers "may these two ports be connected", not "does this filter deliver every subject that one".
func SubjectsOverlap ¶
SubjectsOverlap reports whether some concrete subject matches both a and b under NATS wildcard semantics (`*` one token, a final `>` one or more). It is symmetric and weaker than cover: `*.mutation.create` and `graph.mutation.>` overlap on graph.mutation.create though neither covers the other. Composition validation uses it to refuse a stream that would capture a reserved request subject. A malformed subject overlaps nothing.
func ValidSubject ¶
ValidSubject reports whether subject is well formed under the grammar SubjectCovers and SubjectsOverlap read: one or more `.`-separated tokens, none empty; `*` and `>` only as whole tokens, `>` only last; no space, tab, line feed, carriage return or form feed in any token (nats-server's whitespace set). It is stricter than NATS, which takes a token mixing a wildcard with other text, such as `a*`, as a literal.
Types ¶
type ComponentPortRef ¶
ComponentPortRef references a specific port on a component. A component may name an input and an output alike, so a port is identified by its direction as well as its name.
type DisconnectedNode ¶
DisconnectedNode represents a component with no connections
type FlowAnalysisResult ¶
type FlowAnalysisResult struct {
ConnectedComponents [][]string
DisconnectedNodes []DisconnectedNode
OrphanedPorts []OrphanedPort
}
FlowAnalysisResult contains the results of connectivity analysis
type FlowEdge ¶
type FlowEdge struct {
From ComponentPortRef
To ComponentPortRef
Pattern component.InteractionPattern
ConnectionID string // Subject, bucket, or network addr
}
FlowEdge represents a connection between two component ports
type FlowGraph ¶
type FlowGraph struct {
// contains filtered or unexported fields
}
FlowGraph represents a directed graph of component connections
func BuildFromDeclarations ¶
func BuildFromDeclarations(declarations []component.Declaration) (*FlowGraph, error)
BuildFromDeclarations constructs and connects a flow graph from component declarations — admitted (Registry snapshots) or declared offline (Registry.Declare) — so the boot-time and the offline paths build the same graph from the same interpreter.
func (*FlowGraph) AnalyzeConnectivity ¶
func (g *FlowGraph) AnalyzeConnectivity() *FlowAnalysisResult
AnalyzeConnectivity performs graph connectivity analysis. It reports what the graph IS — connected components, disconnected nodes, orphaned ports — and derives no severity of its own. Severity belongs to composition.Analyze, which owns the one findings vocabulary (ADR-100 D3); a status computed here would be a second judgment over the same walk, and the one that used to be here treated every required stream port with no publisher as critical without checking whether the operator declared it externally fed.
func (*FlowGraph) ValidateStreamRequirements ¶
func (g *FlowGraph) ValidateStreamRequirements() []StreamRequirementWarning
ValidateStreamRequirements returns one warning for each JetStream input port that a plain NATS output port feeds, naming each such publishing component once, sorted by subscriber component and then port.