fix(spec): declare the responses, headers and constraints the API has

[ndreno]

Summary

vacuum scored the spec 0/100 with 313 warnings. The CI gate counts only errors, so it passed. Most warnings were real gaps in what the spec declares. This PR fixes those and lists the rest, each with its reason. Score now 59/100, 118 warnings.

Changes

Declared what the API actually does

• 400 (MalformedRequest) on the 32 operations whose parameters or body the gateway validates. PATCH /api/users/me had a body and no 400.
• 500 on /ws and the public emoji routes. 502 on the SPA route, which is what the s3 dispatcher returns when the bucket is unreachable.
• X-RateLimit-* headers on the 47 rate-limited responses that lacked them.
• security: [] on the three SPA routes, which are public by design.

Constraints that match the server (crates/burst-core/src/id.rs, the parse_*_id helpers)

• IDs: usr_/ch_/exp_-prefixed on responses, a bare UUID for emoji and audit-entry IDs.
• Cursors: the last item's ID on the lists that paginate.
• limit: ^[1-9][0-9]{0,2}$ on the five endpoints where it had no pattern, matching the other endpoints.
• Webhook tokens: ^[0-9a-f]{64}$. Audit action and targetType: patterns. AdminUser.email: format: email.
• Rate-limit headers: bounds, and the policy header's real format, <name>;q=<quota>;w=<window>. The previous example 100;w=60 was not what the plugin sends.

Cleanup: descriptions on 15 request bodies and 4 schemas, descriptions for the catch-all path parameters, and the unused PinnedMessage schema removed.

specs/.vacuum-ignore.yaml: findings that don't apply, grouped with reasons: free text, cursors the server never sets, operations without input, SPA routes that run no middleware, and the 101 WebSocket upgrade. make lint-spec, CI and CLAUDE.md pass --ignore-file.

Behavior changes at the gateway

Request validation now rejects a few inputs it accepted before, with a 400 in each case:

• a limit of 0, or with a leading zero, on those five endpoints;
• a non-UUID emojiId or userId on the admin delete/update routes;
• a threadId multipart field that isn't a message ID.

The server already answered all of these with 400, except that its UUID parser also accepts uppercase hex, and the spec's patterns (like the existing shared ID parameters) require lowercase.

Depends on

• fix(rate-limit): send the X-RateLimit-* headers on allowed responses barbacane#241: the rate-limit plugin puts X-RateLimit-* on allowed responses. Until Burst runs a Barbacane release containing it, those declarations (old and new) describe headers that don't arrive. Bumping BARBACANE_VERSION then closes that.
• fix(rulesets): remove barbacane-auth-opt-out-explicit, which ignored middleware merging barbacane#242: removes barbacane-auth-opt-out-explicit, a false positive under middleware merging (the 25 remaining infos). CI fetches the ruleset from docs.barbacane.dev, so they disappear once that deploys.

Left visible on purpose

• POST /api/webhooks/{webhookId}/trigger has no rate limiting. Its x-barbacane-middlewares: [] removes rate-limit along with oidc-auth, and the server doesn't limit it either. This is a public, token-authenticated endpoint that creates messages. Needs a decision (see below).
• 116 missing examples: tracked as a good first issue.
• 24 duplicate descriptions (info): repeated cursor/limit wording across endpoints.

Testing

• make lint-spec passes.
• make gateway-compile compiles both artifacts (67 and 3 routes). The only warning is the existing E1033 on the webhook trigger.
• CI runs the Rust, spec-sync and smoke tests.

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• deep-review

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: Repository: barbacane-dev/burst/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 3fb8d693-15e1-4adc-bbbf-3f45dd3eccef

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.}