Area: mq / docs — external NATS sizing and permissions text, after #624
Four places where the External NATS docs, CLI text or comments say something that does not match what the code or the server does. All of them are text, except fix 1's error message, which is a string in the code. None changes behaviour, and none blocked #624.
1. "Raise --file-store" cannot fix a topology of six or more partitions
Where:
- the error returned by
NATSManifestOptions.fits() in internal/mq/nats_manifests.go ("raise --file-store with the servers' volumes, or lower --partition-max-bytes");
docs/src/content/docs/deployment.md, External NATS → "Sizing the file store" ("from six partitions at the defaults, set --partition-max-bytes or a larger store");- the
wavehouse mq manifests usage text in cmd/wavehouse/mq.go.
Why it is wrong: every default stream size is a fraction of --file-store: each partition 15%, the history 10%, the dead-letter stream 5%. N partitions therefore reserve (15N + 15)% of the store, whatever its size. From N = 6 the topology can never fit, and a bigger store changes nothing.
Measured:
wavehouse mq manifests --partitions 8 --file-store 1Ti is refused with the "raise --file-store" error.--partitions 16 --file-store 16Ti is refused the same way.--partitions 8 --partition-max-bytes 10Gi is accepted.
Failure scenario: an operator raising N to 6 follows the documented rollout, gets the error, raises the store as the message says, and is refused again.
Fix direction:
- Word the error for the case it is in. When
PartitionMaxBytes was left at its default, name --partition-max-bytes alone, with the largest value that fits: (store − history − dlq) / N. Offer "a larger store" only when the partition size was set explicitly.
- Fix the docs sentence and the usage text to match.
- Optional, and a behaviour change, so decide it separately: let the default partition size follow N, for example (store × 0.85 − headroom) / N. The current fixed 15% was chosen so that lowering N never needs more store while the removed partitions drain. Any change must keep that property or say it gives it up.
Also document the side effect of --partition-max-bytes on a live cluster (inferred from nats-server's enforceBytesLimit, not measured):
- Applying the regenerated manifests lowers
maxBytes on the partitions that already exist.
- Partitions are
discard: new, so nothing is deleted.
- A partition already over its new limit refuses publishes, and ingest answers 503, until the worker drains it below the limit.
- The "Choosing and changing N" section should say this, and suggest lowering the size before a busy period, not during one.
Cosmetic: FormatStoreSize prints a raw byte count for any value no binary unit divides evenly; the error above shows 1484340697405. Print it rounded, e.g. 1.35Ti.
2. The wrong JetStream error code for "does not fit"
Where:
deployment.md, "Sizing the file store" (cites error 10047);- the
NATSManifestOptions.FileStore doc comment.
Measured: 10047 (insufficient storage resources) is what a single server returns. On a 3-node cluster, which is the shipped shape, the same over-reservation fails with err_code=10005 ("no suitable peers for placement, insufficient storage"). Name both codes.
3. "Cannot ack for another consumer" overclaims slightly
Where:
Measured: the generated ack allows are $JS.ACK.*.wh-ingest-<s>.> (plus the v2 layout's equivalent), with the stream name as a wildcard. The wavehouse user was able to ack a message for a consumer named wh-ingest-0 on the dead-letter stream, and that consumer's ack-pending count dropped to 0.
Fix direction: reword it as "cannot ack for any consumer that is not named like a shard durable", or narrow the stream token to the partition streams' names, which mq permissions already knows. Narrowing changes the generated permissions, so regenerate deployments/nats/values.yaml, and extend TestNATSPermissions_RefuseAcksOutsideTheShards with a wh-ingest-0 on the DLQ case.
4. Two test comments use review-process wording
Where: internal/mq/external_perms_test.go (the comment above the shard-count mismatch test, "validator's case") and internal/mq/nats_manifests_test.go ("The validator's case: …").
Fix: describe the case itself, for example "the shipped permissions name 8 shards' durables, but the topology has 16".
Checking the change
go test ./internal/mq/... ./cmd/wavehouse/...go test -tags integration -run '^TestNATSPermissions' ./internal/mqmake build-docs
Found in review of #624.
Related: #624, #613, #694.
Area: mq / docs — external NATS sizing and permissions text, after #624
Four places where the External NATS docs, CLI text or comments say something that does not match what the code or the server does. All of them are text, except fix 1's error message, which is a string in the code. None changes behaviour, and none blocked #624.
1. "Raise
--file-store" cannot fix a topology of six or more partitionsWhere:
NATSManifestOptions.fits()ininternal/mq/nats_manifests.go("raise --file-store with the servers' volumes, or lower --partition-max-bytes");docs/src/content/docs/deployment.md, External NATS → "Sizing the file store" ("from six partitions at the defaults, set--partition-max-bytesor a larger store");wavehouse mq manifestsusage text incmd/wavehouse/mq.go.Why it is wrong: every default stream size is a fraction of
--file-store: each partition 15%, the history 10%, the dead-letter stream 5%. N partitions therefore reserve (15N + 15)% of the store, whatever its size. From N = 6 the topology can never fit, and a bigger store changes nothing.Measured:
wavehouse mq manifests --partitions 8 --file-store 1Tiis refused with the "raise --file-store" error.--partitions 16 --file-store 16Tiis refused the same way.--partitions 8 --partition-max-bytes 10Giis accepted.Failure scenario: an operator raising N to 6 follows the documented rollout, gets the error, raises the store as the message says, and is refused again.
Fix direction:
PartitionMaxByteswas left at its default, name--partition-max-bytesalone, with the largest value that fits: (store − history − dlq) / N. Offer "a larger store" only when the partition size was set explicitly.Also document the side effect of
--partition-max-byteson a live cluster (inferred from nats-server'senforceBytesLimit, not measured):maxByteson the partitions that already exist.discard: new, so nothing is deleted.Cosmetic:
FormatStoreSizeprints a raw byte count for any value no binary unit divides evenly; the error above shows1484340697405. Print it rounded, e.g.1.35Ti.2. The wrong JetStream error code for "does not fit"
Where:
deployment.md, "Sizing the file store" (cites error10047);NATSManifestOptions.FileStoredoc comment.Measured:
10047(insufficient storage resources) is what a single server returns. On a 3-node cluster, which is the shipped shape, the same over-reservation fails witherr_code=10005("no suitable peers for placement, insufficient storage"). Name both codes.3. "Cannot ack for another consumer" overclaims slightly
Where:
deployment.md, External NATS → Permissions;natsPermissionsdoc comment ininternal/mq;Measured: the generated ack allows are
$JS.ACK.*.wh-ingest-<s>.>(plus the v2 layout's equivalent), with the stream name as a wildcard. Thewavehouseuser was able to ack a message for a consumer namedwh-ingest-0on the dead-letter stream, and that consumer's ack-pending count dropped to 0.Fix direction: reword it as "cannot ack for any consumer that is not named like a shard durable", or narrow the stream token to the partition streams' names, which
mq permissionsalready knows. Narrowing changes the generated permissions, so regeneratedeployments/nats/values.yaml, and extendTestNATSPermissions_RefuseAcksOutsideTheShardswith awh-ingest-0on the DLQ case.4. Two test comments use review-process wording
Where:
internal/mq/external_perms_test.go(the comment above the shard-count mismatch test, "validator's case") andinternal/mq/nats_manifests_test.go("The validator's case: …").Fix: describe the case itself, for example "the shipped permissions name 8 shards' durables, but the topology has 16".
Checking the change
go test ./internal/mq/... ./cmd/wavehouse/...go test -tags integration -run '^TestNATSPermissions' ./internal/mqmake build-docsFound in review of #624.
Related: #624, #613, #694.