fix(realtime): remove NXDOMAIN server override (minimal cherry-pick, pin-stability target)

YA
1mo ago
+23-24

User description

What this is

A minimal, isolated alternative consumption path for #109's realtime fix (fix(realtime): remove NXDOMAIN server override on the 4 /realtime/* operations, commit f2aadf1).

This branch (fix/ga-contract-001-realtime-pin) is a cherry-pick of f2aadf1 onto the commit
this spec was pinned to at the time by a downstream consumer (963712a), pushed as its own
branch. It does not touch #109's branch or history — that PR is untouched and still correct
on its own terms (it targets main, where 963712a is an ancestor).

Why this exists

A downstream service vendors this repo's openapi.yaml at a SHA pin rather than reading it live
— its served spec endpoint and its generated tool list are both derived from that vendored copy.
A review on the downstream repair PR correctly flagged that pulling #109's realtime fix through
needs a pin bump + resync + regenerate on that side.

Bumping that pin straight to f2aadf1 (this repo's main tip at the time) was tried first and
rejected: main had drifted 3+ weeks past the downstream pin (963712a → f2aadf1 is 40 files
/ ~7.2k lines — git diff --stat 963712a...f2aadf1), and all of that would have landed in the
downstream repair PR as an unreviewed side effect of a one-line NXDOMAIN fix:

  • New /compose, /leaderboard, /platform paths, including a /leaderboard//platform
    gateway-root servers override the downstream pin gate correctly didn't yet know about.
  • /compose colliding with a gateway-native /compose declaration on the downstream side —
    caught live by that repo's own collision guard test.
  • 2 new, genuinely unclassified {param} identity routes under /videos/{videoId}/chapters/ detect/{jobId} and /videos/{videoId}/chapters/{chapterId}, which a downstream
    metered-before-existence census correctly flagged as needing a real security classification —
    existence-gated vs. open, with evidence — that a contract-drift repair PR has no business
    guessing at.

None of that belongs riding in on a realtime NXDOMAIN fix's coattails. This branch gives the
downstream consumer a pin target whose diff against its prior pin is exactly the 41-line
realtime fix — verified: git diff --stat 963712a...1dbac71 (this branch's tip) matches
git diff --stat 963712a...f2aadf1's openapi.yaml hunk byte-for-byte; nothing else changed.

Disposition

Once #109 merges to main and a future pin bump legitimately carries the downstream consumer
past the compose/leaderboard/platform/video-chapters drift (with that drift properly reviewed on
its own terms — collision resolution, override classification, identity-route census entries),
this branch's SHA becomes redundant and can be deleted; #109's fix is already fully contained in
main at that point. This branch is a stepping stone, not a permanent fork of the realtime
fix.

No code review needed here beyond confirming the cherry-pick is exactly what it claims to be —
happy to close this in favor of #109 once the downstream pin naturally advances past the current
drift.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com

[!NOTE]
Low Risk
Documentation and generated types only; corrects client-facing base URLs without changing server implementation in this diff.

Overview
Aligns the Realtime OpenAPI contract with the live gateway by dropping per-operation servers overrides that pointed clients at https://realtime.wave.online (NXDOMAIN) and documenting that all four Realtime operations are called at https://api.wave.online/v1/realtime/* like other /v1 routes.

Operation descriptions no longer tell callers to use internal forward paths (e.g. “the real path is /v1/connect…”); they describe behavior only. The Realtime tag text and inline GA-CONTRACT-001 notes record the fix. generated/api-types.d.ts is regenerated to match the updated JSDoc on those paths.

Reviewed by Cursor Bugbot for commit 2a06fc9d1545ef3c6c7b33975e953a00f8d4fff7. Bugbot is set up for automated code reviews on this repo. Configure here.

CodeAnt-AI Description

Route realtime operations through the working gateway endpoint

What Changed

  • Realtime WebSocket, publish, presence, and history operations now use the documented https://api.wave.online/v1/realtime/* gateway route instead of the unresolved realtime.wave.online host
  • Removed misleading internal forwarding-path details from the API descriptions
  • Updated generated API type documentation to match the corrected realtime contract

Impact

✅ Fewer realtime connection failures
✅ Correct gateway routing for realtime requests
✅ Clearer API integration guidance

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.