mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 11:54:35 +01:00
docs(api): document the Cloud stacks 429 and drop code comments
Address review on the Cloud portfolio rate-limit fix: document GET /api/cloud/stacks (including the 429 cloud_portfolio_rate_limited response and its bounded Retry-After) in docs/api and the OpenAPI registry, and remove the code comments the PR added. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
2f319bdadd
commit
6a8f146c55
5 files changed
+38
-6
No files matched your search
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Cloud Stacks
|
||||
summary: List the Paperclip Cloud stacks of the signed-in Cloud tenant user
|
||||
---
|
||||
|
||||
This endpoint is available only on a Paperclip Cloud stack. It requires a
|
||||
trusted Cloud tenant session. Board API keys and agent keys cannot use it.
|
||||
|
||||
## List Stacks
|
||||
|
||||
```
|
||||
GET /api/cloud/stacks
|
||||
```
|
||||
|
||||
The server reads the user's stack portfolio from Paperclip Cloud and returns
|
||||
Cloud's JSON payload unchanged. Responses use `Cache-Control: no-store`. A
|
||||
successful portfolio is cached on the server for 30 seconds per user.
|
||||
|
||||
## Errors
|
||||
|
||||
Error bodies have the usual `error` message and a `code`.
|
||||
|
||||
| Status | Code | Meaning |
|
||||
|--------|------|---------|
|
||||
| 403 | `cloud_tenant_required` | The caller is not a trusted Cloud tenant user |
|
||||
| 404 | — | This server is not a Paperclip Cloud stack |
|
||||
| 429 | `cloud_portfolio_rate_limited` | Paperclip Cloud is rate limiting portfolio reads |
|
||||
| 502 | `cloud_portfolio_upstream_error` | Paperclip Cloud failed or could not be reached |
|
||||
| 502 | `cloud_portfolio_invalid_response` | Paperclip Cloud returned invalid JSON |
|
||||
| 503 | `cloud_portfolio_not_configured` | The stack's Cloud connection is not configured |
|
||||
|
||||
A `429` response includes `Retry-After` in whole seconds when Paperclip Cloud
|
||||
supplied a valid hint. The value is between 1 and 300. Wait at least that long
|
||||
before you try again. A `429` is not cached, so the next request asks Paperclip
|
||||
Cloud again.
|
||||
+2
-1
@@ -130,7 +130,8 @@
|
||||
"api/secrets",
|
||||
"api/tool-gateway-tokens",
|
||||
"api/activity",
|
||||
"api/dashboard"
|
||||
"api/dashboard",
|
||||
"api/cloud"
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
@@ -87,7 +87,6 @@ describe("GET /api/cloud/stacks", () => {
|
||||
"Paperclip Cloud portfolio request rate limited",
|
||||
);
|
||||
expect(JSON.stringify(warn.mock.calls)).not.toContain("private");
|
||||
// The throttled answer is not cached: the next read asks Cloud again.
|
||||
fetchImpl.mockResolvedValueOnce(jsonResponse({ stacks: [] }));
|
||||
expect((await request(app).get("/api/cloud/stacks")).body).toEqual({ stacks: [] });
|
||||
expect(fetchImpl).toHaveBeenCalledTimes(2);
|
||||
|
||||
@@ -18,7 +18,6 @@ type PortfolioCacheEntry = {
|
||||
payload: unknown;
|
||||
};
|
||||
|
||||
/** Cloud's Retry-After as bounded whole seconds, or null when absent or malformed. */
|
||||
function retryAfterSeconds(value: string | null, currentTime: number): number | null {
|
||||
const trimmed = value?.trim();
|
||||
if (!trimmed) return null;
|
||||
@@ -126,9 +125,6 @@ export function cloudRoutes(opts: {
|
||||
phase = "http_response";
|
||||
upstreamStatus = upstream.status;
|
||||
if (upstream.status === 429) {
|
||||
// Cloud is throttling portfolio reads. That is the control plane's
|
||||
// backpressure, not a fault here: pass it on with Cloud's retry hint
|
||||
// instead of answering 502 and reporting a crash.
|
||||
logger.warn(
|
||||
{ cloudPortfolio: portfolioError("upstream").diagnostics },
|
||||
"Paperclip Cloud portfolio request rate limited",
|
||||
|
||||
@@ -2103,6 +2103,7 @@ registry.registerPath({
|
||||
200: r.ok(),
|
||||
403: r.forbidden,
|
||||
404: r.notFound,
|
||||
429: { description: "Paperclip Cloud is rate limiting portfolio reads (code cloud_portfolio_rate_limited). Retry-After, when present, gives whole seconds from 1 to 300. Not cached." },
|
||||
502: r.serverError,
|
||||
503: r.serverError,
|
||||
500: r.serverError,
|
||||
|
||||
Reference in new issue
Block a user