refactor(keyenc): one key escaping, keep '-', DLQ counts per table

[EricAndrechek]

Part of #613.

One shared escaping for the composite keys WaveHouse builds, in the new internal/keyenc package. NATS subjects use it now, the cache's namespace tokens use it through query.SafeEncodeToken, and the dedupe keys adopt it in #625. The house rule it sets: a package that builds a composite key takes raw names and builds the key with keyenc.Join/AppendJoin, so no field can reach a key unescaped.

What changes

• internal/keyenc (new):
  • Escape/AppendEscape keep [A-Za-z0-9_-] and write every other byte as %XX in uppercase hex, so . * >, whitespace, %, /, :, |, #, { }, NUL and every non-ASCII byte are escaped. The kept bytes are exactly the tenant-id grammar, so a tenant id is its own escaped form. A % in a name is itself escaped, so names that look escaped (b%2Dc) never share a key with the name they resemble (b-c).
  • Unescape is url.PathUnescape: %XX in either case decodes, and any other byte reads as itself.
  • Join/AppendJoin escape each field and put a separator between them; Split reverses them. They panic on no fields (a key of no fields could not be told from one empty field) and on a separator the escaping could write, %, or a byte outside ASCII.
• NATS subjects (internal/mq): the private encodeToken/decodeToken are gone. Topic.key() writes the tenant verbatim, then AppendJoins the table and scope; parseTopicKey reads the tenant token verbatim (as keyTenant does) and Splits the rest.
• Dead-letter counts (internal/mq/deadletter.go): GET /v1/ops/dlq/stats counts every scope of a table under the table itself, and ?table= keeps all of its scopes. A scoped message used to count under table.scope, a name a dotted table could share. Scope is always empty today, so the response is unchanged.
• Cache namespace tokens: query.SafeEncodeToken is a one-line delegate to keyenc.Escape; feat(cache): shared redis cache, snapshot keys, uncached write pipes #614 moves the escaping into the cache itself and deletes it.

What is deliberately not byte-identical

- is kept rather than escaped as %2D, so dashed table names, scopes and (in #625) ids read as themselves. Every other byte escapes exactly as v0.1.0's encoder did (TestEscape_MatchesV010ButDash, all 256 byte values, and FuzzEscapeRoundTrip against a verbatim copy of it).

Why this is safe to change now: no released queue survives into this build. v0.1.0 queued under the shared WAVEHOUSE/WAVEHOUSE_DLQ streams with subjects that carry no tenant, and #612 deletes both at boot. What remains is a queue an unreleased build since #612 wrote. It still reads, because decoding is unchanged: %2D decodes to -, and a dead-letter count merges both forms. One path notices: a /v1/stream client resuming across such an upgrade (Last-Event-ID or since) on a table whose name holds - misses that table's events queued before it, since the replay filters on the table's exact subject. The in-process cache starts empty on restart, so its keys changing costs nothing.

Work that follows in other PRs

Each of these owes a change once it takes this branch (a note is on each PR):

• test(mq): one conformance suite for every Broker #623 (broker conformance suite): deadLetterKeepsTheTopicAndDoesNotAck expects a scoped topic under {"t.s": 1} and deadLetterCounts counts t1 and t1.s apart; both must expect every scope under its table ({"t": 1}, t1 summed). The fold is not the Broker contract any more — restoring it would undo this PR.
• fix(dedupe)!: reserve/commit ids, windowed ingest, retention, dynamodb #625 (dedupe keys): builds its keys with AppendJoin and pins evt-123 rather than evt%2D123.
• feat(cache): shared redis cache, snapshot keys, uncached write pipes #614 (cache): cache.Namespace carries raw names and the cache escapes its own keys with Join; query.SafeEncodeToken is deleted.
• feat(cache): shared cache backend on Redis, Valkey and Dragonfly #626 (Redis cache): builds its token keys with AppendJoin and hashes escaped fields.
• feat(mq): a Broker over an external NATS cluster #636 (external NATS broker): counts dead letters through the same deadLetterTables, and its copy of the conformance suite flips as test(mq): one conformance suite for every Broker #623's does.

Tests

• TestSubject_Golden: full subjects on the ingest and DLQ prefixes for dotted, wildcard, whitespace, -, %, /, brace, NUL, \xff, 2- and 3-byte UTF-8, empty-table and scopeless topics.
• TestParseTopicKey_LenientTokens: a lowercase escape, a byte left unescaped (~), and an earlier build's %2D form read as the same topic.
• TestParseTopicKey_ForeignTailKeepsItself: tails this package could not have written fall back to a topic of no tenant; an escaped tenant token (a%2Db) is refused, since the tenant is read verbatim.
• TestEscape_KeepsExactlyTheTenantGrammar, TestEscape_LookalikesStayDistinct, TestSeparators (every byte value as a separator: refused, or round-trips), TestJoin_RefusesZeroFields.
• TestDeadLetterTables: a dotted table and a table + scope pair count apart, scopes sum under their table, the filter keeps every scope, and %2D and - subjects merge.

Checks

• make ci passes locally at 79ab364.
• Pre-push reviewers: pre-push-reviewer and docs-reviewer ship_it at 79ab364, after two iterate rounds with no code defects: the changelog tied the %2D compatibility to v0.1.0 (only queues since feat(mq): give every tenant a queue of its own #612 are affected), two package listings missed keyenc, a stale cache line, the follow-up list missed test(mq): one conformance suite for every Broker #623, and the lenient-token test no longer exercised an unescaped byte.

🤖 Generated with Claude Code

https://claude.ai/code/session_01B1tJWUp6oaDoH1usLwGtLF

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 0c7139f8-4091-4b67-b8bb-073035cd638c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📚 Docs preview is live → https://8993701f-wavehouse-docs.wave-rf.workers.dev

• Commit — 16dce69: Merge remote-tracking branch 'origin/main' into refactor/keyenc
• Author — @EricAndrechek
• Committed — 2026-09-25 21:06 (UTC-04:00)
• Deployed — 2026-09-25 21:16 EDT

[github-code-quality]

Code Coverage Overview

Languages: Go

Go

The overall line coverage in commit 16dce69 in the refactor/keyenc branch remains at 94%, unchanged from commit 73c75ee in the main branch.

Show a line coverage summary of the most impacted files.

File	main 73c75ee	refactor/keyenc 16dce69	+/-
internal/mq/subject.go	100%	100%	0%
internal/query/ident.go	100%	100%	0%
internal/mq/embedded.go	88%	89%	+1%
internal/ingest/worker.go	97%	98%	+1%
internal/keyenc/keyenc.go	0%	100%	+100%
internal/mq/deadletter.go	0%	100%	+100%

---

_{Updated September 26, 2026 01:16 UTC}