Documentation
¶
Overview ¶
Package natsubj builds and parses the ppz subject grammar
<org_id>.<handle>.<pipe>
where {pipe} ∈ {broadcast, inbox, stdin, stdout}. The optional workspace slot between org and handle is reserved by the long-term grammar but unused.
Index ¶
- Variables
- func BuildStreamName(accountID uuid.UUID, manifold, source, name string) string
- func BuildSubject(accountID uuid.UUID, manifold, source, pipe string) string
- func OrgSubscription(accountID uuid.UUID) string
- func StreamName(accountID uuid.UUID, handle, pipe string) string
- func Subject(accountID uuid.UUID, handle, pipe string) string
- func ValidateChannel(c string) error
- func ValidateHandle(h string) error
- func ValidatePipe(name string) error
- func ValidateUserPipeName(name string) error
Constants ¶
This section is empty.
Variables ¶
var AutoProvisionedPipes = map[string]bool{ "broadcast": true, "inbox": true, "stdin": true, "stdout": true, "stdctrl": true, }
AutoProvisionedPipes covers pipes the server creates automatically for sources. Some are also allowed via user pipe creation (`stdin`, `stdout`, `stdctrl` for terminal sharing); `inbox` remains reserved from manual creation even though it is provisioned automatically. The set is here for documentation + the daemon's ls dedupe.
var HandleRegex = regexp.MustCompile(`^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$`)
HandleRegex per WIRE.md §1: lowercase alnum + hyphens, max 32, no leading or trailing hyphen.
var Reserved = map[string]bool{ "broadcast": true, "inbox": true, "stdin": true, "stdout": true, "stdctrl": true, "system": true, "db": true, }
Reserved handles that cannot be used as pipe names. They overlap with the channel names so a bare-token target stays unambiguous.
ReservedPipeNames are names blocked from user pipe creation. Reserved for future system use (e.g. an inbox routing scheme, db-backed pipes).
var ValidChannels = ValidPipes
ValidChannels is a deprecated alias kept during the Phase A rename for any caller still phrasing the check as "channel". Will be removed in Phase B.
var ValidPipes = map[string]bool{ "broadcast": true, "inbox": true, "stdin": true, "stdout": true, "stdctrl": true, }
ValidPipes are the pipe names recognised on the wire — both auto- provisioned (broadcast / stdin / stdout / stdctrl) and any future user- creatable names. The user-creatable paths add additional validation on top (regex, reserved-name check).
stdctrl carries control signals that don't fit on stdin/out — initially just JSON resize events, later potentially exit codes, title changes, focus events, etc. The web terminal viewer consumes it to keep its xterm.js viewport sized to match the source pty.
Functions ¶
func BuildStreamName ¶ added in v0.31.0
BuildStreamName produces a JetStream stream name for the four-role pipe shape. NATS stream names can't contain dots, so manifold dots are replaced with underscores. Empty manifold/source slots are omitted entirely — handle regex forbids underscores in segments so there's no ambiguity.
pipe_<orgshort>[_<manifold-underscored>][_<source>]_<name>
func BuildSubject ¶ added in v0.31.0
BuildSubject emits the four-role subject form per locked decision #18:
<account>.<manifold?>.<source?>.<pipe>
where manifold is 0+ dot-separated segments (” = root) and source ("collar") is 0 or 1 segment (” = uncollared). Wire-level the manifold-only and source-only shapes are indistinguishable (acct.X.pipe could be either) — that's by design; disambiguation happens by DB row at create time. The builder just emits the canonical dotted form.
func OrgSubscription ¶
OrgSubscription is the wildcard subscription used by the server-side subscriber and by the daemon's NATS user JWT permission set.
func StreamName ¶
StreamName produces the JetStream stream name per WIRE.md §2:
source_<orgshort>_<handle>_<pipe>
where orgshort is the first 8 hex chars of the org UUID, hyphens stripped. Pre-Phase-1.5 three-role form; for the four-role form use BuildStreamName.
func Subject ¶
Subject builds <account>.<handle>.<pipe>. Pre-Phase-1.5 three-role builder; equivalent to BuildSubject(accountID, "", handle, pipe). Retained for callers that haven't been threaded through manifold yet.
func ValidateChannel ¶
ValidateChannel is the Phase A backward-compat alias for ValidatePipe. Removed in Phase B.
func ValidateHandle ¶
func ValidatePipe ¶
ValidatePipe checks a pipe name's *syntax* — regex only, no auto/reserved restrictions. Used by `read` / `send` / `broadcast` targets, where any existing pipe is a legitimate destination (auto-provisioned or user- created). The "does this stream actually exist" check is deferred to the publish/read path against JetStream.
User pipe creation goes through ValidateUserPipeName, which adds the auto/reserved restrictions on top of the regex.
func ValidateUserPipeName ¶
ValidateUserPipeName validates a name passed to `ppz pipe create`. Same handle regex (lowercase alnum + hyphens, max 32, no leading/trailing hyphen). Reserved names are rejected. Auto-provisioned names (broadcast, stdin, stdout) ARE allowed: any source can have arbitrary pipes added to it, and the pipe-create path is idempotent against an already-existing stream.
Types ¶
This section is empty.
Source Files