docs(proxy): stop claiming a 503 is unreachable after the queue caps went

[kojiwakayama]

Description

Follow-up to a Copilot review comment on #3420 that merged before the correction landed, so the inaccurate comment is on main now.

#3420 removed the two cold-load queue caps and left this in asset-handler.ts:

a saturated proxy therefore shows up as latency and finally an honest 504, never a phantom 503.

That overstates it. PermitSemaphore still carries its own DEFAULT_PERMIT_SEMAPHORE_MAX_QUEUE_SIZE backstop, and exhausting it raises ReleaseAssetOverloadedError and returns 503. The serviceUnavailable() path was deliberately kept for exactly that case.

The comment now says so, and says why the distinction the PR was making still holds: that threshold is two orders of magnitude above one page's module graph, so reaching it means a genuine flood rather than a project being shed for the size of the document this proxy just served it.

Type of Change

• Documentation update

Comment only, no behaviour change. asset-handler.test.ts 29 steps pass; fmt:check, lint and docs:api-reference:check all exit 0.

Summary by CodeRabbit

• Documentation
  • Clarified concurrency behavior: saturated demand is queued and may eventually return a 504 response.
  • Documented that 503 responses are reserved for the semaphore’s extreme queue backstop.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: fa312a17-7662-4a22-a9f3-f41d4c4663a7

📥 Commits

Reviewing files that changed from the base of the PR and between b8ea54e and 3c3d996.

📒 Files selected for processing (1)

• src/proxy/asset-handler.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/proxy/asset-handler.ts

---

📝 Walkthrough

Walkthrough

The asset handler documentation distinguishes 504 responses for queued requests from 503 responses when the semaphore reaches its maximum queue threshold.

Changes

Concurrency documentation

Layer / File(s)	Summary
Response status documentation src/proxy/asset-handler.ts	Documents that saturated demand queues eventually return 504. Reserves 503 for the semaphore’s maximum queue threshold during a genuine flood.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related PRs

• veryfront/veryfront-code#3420: Both PRs update concurrency queue behavior documentation in src/proxy/asset-handler.ts.

Suggested reviewers: kwakayama, copilot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the documentation change that clarifies when a proxy can return 503 after queue limits apply.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/proxy-cold-load-503-comment

---

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

[Copilot]

Pull request overview

Updates the proxy asset handler’s inline documentation to accurately describe when a 503 can still occur after the cold-load queue cap removals, clarifying the remaining PermitSemaphore backstop behavior.

Changes:

• Rewords the comment to stop claiming a 503 is impossible and to explain the remaining semaphore queue backstop.
• Keeps the original point intact: typical saturation should manifest as latency and eventually 504, not spurious 503s.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.