From 6a8f146c55d1931410b6d45984a9154b58e9e1c0 Mon Sep 17 00:00:00 2001 From: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com> Date: Sat, 21 Nov 2026 11:26:35 +0000 Subject: [PATCH] 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 --- docs/api/cloud.md | 35 +++++++++++++++++++++++ docs/docs.json | 3 +- server/src/__tests__/cloud-routes.test.ts | 1 - server/src/routes/cloud.ts | 4 --- server/src/routes/openapi.ts | 1 + 5 files changed, 38 insertions(+), 6 deletions(-) create mode 100644 docs/api/cloud.md diff --git a/docs/api/cloud.md b/docs/api/cloud.md new file mode 100644 index 00000000000..c53e406845d --- /dev/null +++ b/docs/api/cloud.md @@ -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. diff --git a/docs/docs.json b/docs/docs.json index a1a008f94dd..07d28f1bae7 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -130,7 +130,8 @@ "api/secrets", "api/tool-gateway-tokens", "api/activity", - "api/dashboard" + "api/dashboard", + "api/cloud" ] } ] diff --git a/server/src/__tests__/cloud-routes.test.ts b/server/src/__tests__/cloud-routes.test.ts index d201b44c301..75dbc1f9e11 100644 --- a/server/src/__tests__/cloud-routes.test.ts +++ b/server/src/__tests__/cloud-routes.test.ts @@ -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); diff --git a/server/src/routes/cloud.ts b/server/src/routes/cloud.ts index 7ef28a948dc..3b930ccddd2 100644 --- a/server/src/routes/cloud.ts +++ b/server/src/routes/cloud.ts @@ -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", diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.ts index 754c7ab8649..d54de50f770 100644 --- a/server/src/routes/openapi.ts +++ b/server/src/routes/openapi.ts @@ -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,