flowgraph

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

README

flowgraph

Builds a graph of how components connect through their declared ports, and reports what the graph shows: which components are connected, which have no connections, and which ports nothing matches.

import "github.com/c360studio/semengine/internal/flowgraph"

The package is internal to SemEngine. In SemStreams the composition package is its one reader; composition comes to SemEngine in a later change. Until then this package's tests are its only callers.

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 (Registry.Declare). It adds one node per instance and connects the ports.

graph, err := flowgraph.BuildFromDeclarations(declarations)
if err != nil {
    return fmt.Errorf("build flow graph: %w", err)
}

It returns an error, and no graph, when the declarations cannot form a valid one:

  • an empty or repeated instance name;
  • a port with no connection identity (no subject, bucket or address);
  • more than one writer port on one KV bucket;
  • a graph-mutation port that is not a required request port on the graph-mutation subject family with the graph-mutation interface type and version, or graph-mutation ports with not exactly one input (the provider) among them. A graph-mutation port is any port, of any kind and in either direction, whose interface type is semengine.graph.mutation or one of whose NATS subjects starts with graph.mutation.; internal/graphmutation's ClassifyPort makes that decision, and graph-ingest uses the same one.

What the graph connects

Each port has an interaction pattern (component.InteractionPattern) that decides how it is matched. An edge records the two ports, the pattern and the connection ID (subject, bucket or address) they share.

Pattern What joins
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 one direction on different components join only when their subjects differ and still match (one holds a wildcard); on the same subject they do not.
watch A watch output (a KV writer) joins every watch input on the same bucket, its own component's included.
read A watch output joins every read input on the same bucket, its own component's included.
store Every store output joins every store input on another component.
network Never joined. Two binds on one network address are refused by component.Registry when it admits a component, not here.
http-client Never joined.
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. When one side holds a wildcard, the edge records the other side's subject. SubjectCovers(filter, pattern) answers a different, one-way question: whether every subject pattern can name also matches filter.

ValidSubject(subject) reports whether a subject is well formed under the grammar both helpers 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. The message logger's Start calls ValidSubject to refuse a malformed subject.

What the analysis reports

result := graph.AnalyzeConnectivity()
for _, orphan := range result.OrphanedPorts {
    log.Warn("orphaned port",
        "component", orphan.ComponentName,
        "port", orphan.PortName,
        "issue", orphan.Issue)
}

AnalyzeConnectivity returns a FlowAnalysisResult:

  • ConnectedComponents: groups of components joined by edges. A component with no edge is a group of one.
  • DisconnectedNodes: components with no edge.
  • OrphanedPorts: ports no edge reaches. Network, http-client, store and timer ports are never orphans. Each orphan carries an Issue, one of the package's Issue constants, and the port's Required flag.

The analysis reports facts and no severity. Whether an orphan or a lone component is a problem is the reader's judgment.

JetStream inputs fed by plain NATS publishers

for _, w := range graph.ValidateStreamRequirements() {
    log.Warn("JetStream input fed by plain NATS publishers",
        "subscriber", w.SubscriberComp,
        "port", w.SubscriberPort,
        "publishers", w.PublisherComps)
}

ValidateStreamRequirements returns one warning for each JetStream input port that a plain NATS output port feeds, naming each publishing component once, sorted by subscriber component and then port.

Concurrency

A FlowGraph has no locks. Build it and read it on one goroutine.

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

View Source
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

func SubjectCovers(filter, pattern string) bool

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

func SubjectsOverlap(a, b string) bool

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

func ValidSubject(subject string) bool

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

type ComponentPortRef struct {
	ComponentName string
	PortName      string
	Direction     component.Direction
}

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

type DisconnectedNode struct {
	ComponentName string
	Issue         string
	Suggestions   []string
}

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) GetEdges

func (g *FlowGraph) GetEdges() []FlowEdge

GetEdges returns the edges in the graph

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.

type OrphanedPort

type OrphanedPort struct {
	ComponentName string
	PortName      string
	Direction     component.Direction
	ConnectionID  string
	Pattern       component.InteractionPattern
	Issue         string
	Required      bool
}

OrphanedPort represents a port with no connections

type StreamRequirementWarning

type StreamRequirementWarning struct {
	SubscriberComp string
	SubscriberPort string
	Subjects       []string
	PublisherComps []string
}

StreamRequirementWarning represents a mismatch between JetStream subscriber and NATS publisher

Jump to

Keyboard shortcuts

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