What this module does not do¶

It does not read configuration¶

No go/config import, and there will not be one. Toolkit modules take typed settings; the calling application maps its own configuration onto them.

That is what lets one application configure from YAML and another from flags, and it is what keeps a configuration library out of every module's dependency graph. The struct tags exist so the mapping is a decode rather than an assignment.

It does not compose a credential ladder¶

CredentialSource is a function you supply. Precedence — environment variable name, keychain, literal, well-known variable — is the application's decision, and a library that decides it is a second statement of something the estate already states once, which is how two statements drift.

It does not wrap JetStream¶

Client.Conn() returns the underlying connection and you reach JetStream through it.

Wrapping would be forty-odd methods across seven interfaces: KeyValue alone is sixteen, plus seven for bucket lifecycle, plus ObjectStore's seventeen. Each one is a place to fall behind an actively developed upstream, and a consumer wanting a new capability would wait on a release here to reach it.

What this module will eventually own is construction, not verbs — a handful of functions that apply house limits when a stream or bucket is created and hand back the upstream interface. That is where the value is, because that is where the refusals live.

It does not retry, back off or circuit-break¶

go/transit does that. Reconnection is NATS' own and is configured, not implemented here.

It does not give you a Len()¶

Deliberately, and this generalises past this module.

Queue depth is a local read in-process and a network round trip against a broker. A method that looks free and is not becomes a per-decision round trip on somebody's hot path, discovered under load. If depth is exposed later it will carry a context.Context and an error, so the cost is visible in the signature.

Sharp edges it cannot file off¶

A message delivered but not yet acknowledged cannot be purged. If you have a deletion promise to a person — a forget-me — a subject-filtered purge reaches everything except what is currently in flight. No wrapper changes this; it is a property of the store.

File-store deletion is not secure erasure. JetStream removes the message; it does not overwrite the blocks. Encryption at rest is the answer to that question, not deletion.

Two shed points exist and only one is yours. Client-side pending limits are set by this module and counted per subscription. The server also detects slow consumers and may disconnect a client outright, and Dropped()'s own documentation notes its count may not be valid when that happens.

Identity: prefer NKeys or JWT over mTLS DN mapping. CVE-2026-33248 was an authentication bypass in verify_and_map's Subject DN matching — fixed in 2.11.15 and 2.12.6, requiring an already-trusted certificate, rated 4.2 — whose only offered workaround was "review your CA issuing practices". DN parsing is a fiddly surface to rest a tenancy boundary on. NKeys have no DN to mis-parse.