From 2ac2904966dd2e6a7cee2c303d3f4c2373508c4b Mon Sep 17 00:00:00 2001 From: Konstantin Zaytcev Date: Wed, 16 Sep 2026 23:08:44 +0300 Subject: [PATCH 1/2] feat(transport): one retry rule across the SDKs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The three SDKs disagreed about retrying, in behaviour and not only in shape. JS listed the statuses it would retry; Go and PHP retried any 5xx but 501. So 408 retried in JS and not in Go or PHP, and an unfamiliar 5xx retried in Go and PHP and not in JS. All three now read: no response at all, 408, 429, or 5xx other than 501. The allow-list argument — that it cannot silently retry what should not be retried — does not survive this backend. Every unexpected state maps to 500 there, including the request timeout middleware and a panic in a handler. So the genuinely hopeless failure already arrives as a 500 that the list happily retries; the list protects nothing where the risk is real, and only drops codes nobody taught it. What decides it is the asymmetry. A list wrong about an unfamiliar transient 5xx loses the event silently and for good, which is the one failure an error tracker must not have. A general rule wrong about an unfamiliar terminal 5xx costs a bounded number of requests and still surfaces the error; eventId is the idempotency key, so no duplicate. And the predicate judges statuses the SDK does not control: an installation sits behind somebody else's edge, and the SDK sits pinned in somebody else's tree. Widening a list would take a release into every consumer. 408 retries because it is reachable: nginx has no client body timeout set on /api/, so the default 60s applies. It is the edge losing patience with the upload, a statement about the channel rather than the payload, and RFC 9110 permits repeating it unchanged. Differences that remain are named in each comment rather than left to be inferred: what "no response" looks like in each runtime, and that the retry budget is opt-in in Go because its transport can run in the caller's request path. BREAKING CHANGE: none, but TransportFailureInfo.attempts now reports the attempts actually made rather than the configured budget, so metrics built on that number will move. --- README.md | 2 + src/DuckBug/DuckBugService.ts | 80 +++++++++++++-- tests/DuckBug/DuckBugRetryPolicy.test.ts | 121 +++++++++++++++++++++++ 3 files changed, 194 insertions(+), 9 deletions(-) create mode 100644 tests/DuckBug/DuckBugRetryPolicy.test.ts diff --git a/README.md b/README.md index 55c9c41..ec3a64a 100644 --- a/README.md +++ b/README.md @@ -262,6 +262,8 @@ DuckBugProvider.fromDSN(dsn) - `config.dsn`: full ingest URL, e.g. `https://api.duckbug.io/ingest/myProject:myKey` - `flush()`: returns a `Promise` that resolves when queued requests for this provider have been sent +- Delivery is retried on a request that never produced a response, `408`, `429` and every `5xx`, including status codes this SDK has never been taught about - those are what an edge in front of the installation invents, and dropping the event on the first one would lose it silently. `501 Not Implemented` is the single exception and is final, because it means the capability is not configured in that DuckBug installation and repeating the request cannot change that. Everything else, `4xx` in particular, is reported to `onTransportError` after one attempt. The same predicate is implemented in `duckbug-go` and `duckbug-php`. +- `TransportFailureInfo.attempts` is how many requests were actually made, not the configured budget. ### Privacy, batching, and Node hooks diff --git a/src/DuckBug/DuckBugService.ts b/src/DuckBug/DuckBugService.ts index 4134a15..ffbf531 100644 --- a/src/DuckBug/DuckBugService.ts +++ b/src/DuckBug/DuckBugService.ts @@ -16,15 +16,71 @@ const DEFAULT_MAX_RETRIES = 2; const DEFAULT_RETRY_DELAY_MS = 200; const MAX_BACKEND_BATCH = 1000; +const STATUS_REQUEST_TIMEOUT = 408; +const STATUS_TOO_MANY_REQUESTS = 429; +const STATUS_SERVER_ERROR_MIN = 500; +const STATUS_NOT_IMPLEMENTED = 501; + +/** + * Tells whether sending the very same request again can plausibly end + * differently. This predicate is the shared one: duckbug-go and duckbug-php + * answer exactly the same question the same way, and a change here has to land + * in all three. + * + * The rule is "transient unless proven final": 408, 429 and every 5xx are worth + * another attempt; 501 is the single carve-out; everything else is the final + * answer. A request that never produced a response is handled by the caller + * below, outside this function. + * + * It is written as a rule with one hole rather than as a list of retriable + * codes on purpose. This SDK does not only talk to DuckBug's ingest - a DuckBug + * installation sits behind whatever edge the customer runs, and that edge + * invents statuses of its own. An allow list turns every code it has not been + * taught about into a silently dropped event, which is the one failure an error + * tracker must not have, and widening it means shipping a new SDK into every + * consumer's dependency tree. Being wrong the other way costs at most + * `maxRetries` extra requests with bounded backoff, and the backend treats + * `eventId` as the idempotency key, so a retry of a request that did arrive + * cannot create a second event. + * + * 408 is retried because it is the edge timing out the request body (nginx + * client_body_timeout and friends), never a verdict on the payload; RFC 9110 + * states outright that such a request may be repeated unchanged. + * + * 501 is the hole: it is DuckBug stating that the capability is not configured + * in this installation, and only an operator can change that. The backend + * reaches for 501 over 503 in exactly that case so clients stop retrying, + * because 503 would promise that waiting helps. A 501 from an intermediary + * means the same thing one layer out, so the answer is the same either way. + * + * Do not widen this carve-out to 503. On the ingest path a 503 is the edge + * during a redeploy - the transient case this predicate exists for. + * + * Deliberate differences from the other two SDKs: + * - a request that never reached a response is a rejected `fetch` promise + * with no status at all, so it cannot be expressed here; the loop below + * retries it in its `catch`. duckbug-go sees the same case as an error from + * `http.Client.Do` and duckbug-php as a cURL errno. + * - 409 never reaches this function: `ingestResponseAccepted` folds it into + * success, because a duplicate `eventId` means the event is already stored. + * duckbug-go and duckbug-php surface 409 to the caller instead, and reach + * the same retry answer - no retry - by a different route. + * + * The 429 that DuckBug's rate limiter returns carries `Retry-After`, which this + * transport does not read - the backoff below decides on its own. Honouring it + * is a separate change and has to land in all three SDKs together. + */ function isRetriableHttpStatus(status: number): boolean { - return ( - status === 408 || - status === 429 || - status === 500 || - status === 502 || - status === 503 || - status === 504 - ); + if (status === STATUS_NOT_IMPLEMENTED) { + return false; + } + if ( + status === STATUS_REQUEST_TIMEOUT || + status === STATUS_TOO_MANY_REQUESTS + ) { + return true; + } + return status >= STATUS_SERVER_ERROR_MIN; } function ingestResponseAccepted(status: number): boolean { @@ -223,8 +279,14 @@ export class DuckBugService { ): Promise { let lastErr: unknown = new Error("unknown transport failure"); const maxAttempts = this.maxRetries + 1; + // What the caller is told in `TransportFailureInfo.attempts` has to be what + // actually happened, not the budget: a terminal status stops the loop after + // one request, and reporting `maxAttempts` there would invent two retries + // that never ran. duckbug-go and duckbug-php both report the real count. + let attemptsMade = 0; for (let attempt = 0; attempt < maxAttempts; attempt++) { + attemptsMade = attempt + 1; try { const res = await this.fetchImpl(url, { method: "POST", @@ -273,7 +335,7 @@ export class DuckBugService { this.emitFailure({ kind, itemCount, - attempts: maxAttempts, + attempts: attemptsMade, error: lastErr, message, }); diff --git a/tests/DuckBug/DuckBugRetryPolicy.test.ts b/tests/DuckBug/DuckBugRetryPolicy.test.ts new file mode 100644 index 0000000..b6b68af --- /dev/null +++ b/tests/DuckBug/DuckBugRetryPolicy.test.ts @@ -0,0 +1,121 @@ +import { describe, expect, it } from "bun:test"; +import type { DuckBugConfig } from "../../src/DuckBug/DuckBugConfig"; +import { DuckBugService } from "../../src/DuckBug/DuckBugService"; +import type { TransportFailureInfo } from "../../src/DuckBug/transportTypes"; +import { logLevel } from "../../src/SDK/LogLevel"; + +const DSN = "https://api.test/ingest/p:k"; +const MAX_RETRIES = 2; + +/** + * The retry predicate lives inside the module, so it is pinned here through the + * only thing a consumer can observe: how many times the transport actually + * posts, and what it reports when it gives up. + */ +async function attemptsFor( + status: number, +): Promise<{ requests: number; failure: TransportFailureInfo | undefined }> { + let requests = 0; + let failure: TransportFailureInfo | undefined; + + const fetchImpl = (() => { + requests++; + return Promise.resolve(new Response("", { status })); + }) as unknown as typeof fetch; + + const config: DuckBugConfig = { + dsn: DSN, + transport: { + maxBatchSize: 1, + maxRetries: MAX_RETRIES, + retryDelayMs: 1, + fetchImpl, + }, + onTransportError: (info) => { + failure = info; + }, + }; + + const svc = new DuckBugService(config); + svc.sendLog({ time: 1, level: logLevel.INFO, message: "x" }); + await svc.flush(); + + return { requests, failure }; +} + +describe("DuckBugService retry policy", () => { + it("retries a request timeout", async () => { + // 408 is the edge timing out the request body, not a verdict on the + // payload; RFC 9110 states such a request may be repeated unchanged. + const { requests } = await attemptsFor(408); + expect(requests).toBe(MAX_RETRIES + 1); + }); + + it("retries throttling", async () => { + const { requests } = await attemptsFor(429); + expect(requests).toBe(MAX_RETRIES + 1); + }); + + it("retries known transient server faults", async () => { + for (const status of [500, 502, 503, 504]) { + const { requests } = await attemptsFor(status); + expect(requests).toBe(MAX_RETRIES + 1); + } + }); + + it("retries server faults it has never been taught about", async () => { + // These are what an edge in front of a DuckBug installation invents. An + // allow list would drop the event on the first one, silently. + for (const status of [505, 507, 508, 510, 521, 599]) { + const { requests } = await attemptsFor(status); + expect(requests).toBe(MAX_RETRIES + 1); + } + }); + + it("treats not implemented as final", async () => { + // 501 means the capability is not configured in this installation, so + // repeating cannot change it. + const { requests } = await attemptsFor(501); + expect(requests).toBe(1); + }); + + it("treats verdicts on this request as final", async () => { + for (const status of [400, 401, 403, 404, 413, 415, 422]) { + const { requests } = await attemptsFor(status); + expect(requests).toBe(1); + } + }); + + it("reports how many attempts were actually made", async () => { + const terminal = await attemptsFor(400); + expect(terminal.failure?.attempts).toBe(1); + + const retried = await attemptsFor(503); + expect(retried.failure?.attempts).toBe(MAX_RETRIES + 1); + }); + + it("retries a request that never produced a response", async () => { + // In this runtime a request that never reached the server is a rejected + // promise with no status at all - duckbug-go sees an error from + // http.Client.Do and duckbug-php a cURL errno. All three retry it. + let requests = 0; + const fetchImpl = (() => { + requests++; + return Promise.reject(new TypeError("fetch failed")); + }) as unknown as typeof fetch; + + const svc = new DuckBugService({ + dsn: DSN, + transport: { + maxBatchSize: 1, + maxRetries: MAX_RETRIES, + retryDelayMs: 1, + fetchImpl, + }, + }); + svc.sendLog({ time: 1, level: logLevel.INFO, message: "x" }); + await svc.flush(); + + expect(requests).toBe(MAX_RETRIES + 1); + }); +}); From 3aebe1c84aa55f343a4defdb3382f053e0bbab03 Mon Sep 17 00:00:00 2001 From: Konstantin Zaytcev Date: Wed, 16 Sep 2026 23:56:11 +0300 Subject: [PATCH 2/2] docs(transport): correct what happens on 409, and what idempotency rests on MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README said every other 4xx, 409 included, is reported to the caller. The opposite is true: 409 sets Duplicate, IsSuccess() returns true, and handleTransportResult returns before it ever builds FailureInfo, so the transport failure handler is not called at all. The retry predicate is now identical across the three SDKs; what a duplicate looks like afterwards is not, and that is worth stating rather than leaving to be discovered. JS also folds 409 into success; PHP hands it to its failure handler because its isSuccess() requires 2xx. The claim that a retry cannot create a second event was stronger than the truth. Ingest deduplicates on a Postgres primary key with ON CONFLICT DO NOTHING, with no expiry, on the single and the batch route alike — but only if the caller supplies the id. A payload that reaches ingest without an eventId gets a fresh one minted per request, so a retry does store it twice. All three SDKs generate a UUIDv4 on the normal path; the guarantee is now written with its condition instead of without it. The transport-error branch of shouldRetry had no test. It has one now, with a handler that hijacks the connection and closes it unanswered, and it was proven to bite by deleting the branch and watching the case fail. --- README.md | 3 ++- src/DuckBug/DuckBugService.ts | 15 ++++++++++++--- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ec3a64a..19f0f99 100644 --- a/README.md +++ b/README.md @@ -262,7 +262,8 @@ DuckBugProvider.fromDSN(dsn) - `config.dsn`: full ingest URL, e.g. `https://api.duckbug.io/ingest/myProject:myKey` - `flush()`: returns a `Promise` that resolves when queued requests for this provider have been sent -- Delivery is retried on a request that never produced a response, `408`, `429` and every `5xx`, including status codes this SDK has never been taught about - those are what an edge in front of the installation invents, and dropping the event on the first one would lose it silently. `501 Not Implemented` is the single exception and is final, because it means the capability is not configured in that DuckBug installation and repeating the request cannot change that. Everything else, `4xx` in particular, is reported to `onTransportError` after one attempt. The same predicate is implemented in `duckbug-go` and `duckbug-php`. +- Delivery is retried on a request that never produced a response, `408`, `429` and every `5xx`, including status codes this SDK has never been taught about - those are what an edge in front of the installation invents, and dropping the event on the first one would lose it silently. `501 Not Implemented` is the single exception and is final, because it means the capability is not configured in that DuckBug installation and repeating the request cannot change that. Everything else is decided after one attempt. `409 Conflict` is not a failure: it means the backend already holds this `eventId`, so the response counts as accepted and `onTransportError` is **not** called. Every other `4xx` is reported to `onTransportError` after one attempt. +- The retry predicate is identical in `duckbug-go`, `duckbug-js` and `duckbug-php`. What a duplicate looks like afterwards is not: `duckbug-go` also treats `409` as success (marking the result `Duplicate`), while `duckbug-php` hands it to its failure handler because its `isSuccess()` requires `2xx`. All three agree on not retrying it. - `TransportFailureInfo.attempts` is how many requests were actually made, not the configured budget. ### Privacy, batching, and Node hooks diff --git a/src/DuckBug/DuckBugService.ts b/src/DuckBug/DuckBugService.ts index ffbf531..bab1824 100644 --- a/src/DuckBug/DuckBugService.ts +++ b/src/DuckBug/DuckBugService.ts @@ -39,9 +39,18 @@ const STATUS_NOT_IMPLEMENTED = 501; * taught about into a silently dropped event, which is the one failure an error * tracker must not have, and widening it means shipping a new SDK into every * consumer's dependency tree. Being wrong the other way costs at most - * `maxRetries` extra requests with bounded backoff, and the backend treats - * `eventId` as the idempotency key, so a retry of a request that did arrive - * cannot create a second event. + * `maxRetries` extra requests with bounded backoff, and a retry of a request + * that did arrive cannot create a second event: ingest deduplicates on the + * event id with a Postgres primary key and ON CONFLICT DO NOTHING, with no + * expiry, on the single and the batch route alike. + * + * That guarantee is only as strong as the id. It has to be supplied by the + * caller: when a payload reaches ingest without an `eventId`, the server mints + * a fresh one per request and a retry does store the event twice. + * `finalizeIngestEvent` runs `ensureEventId` on everything `DuckBugProvider` + * sends, so the normal path is safe; code driving `DuckBugService` directly + * owns that field itself. The server validates it as uuid4, so a non-UUID + * idempotency key is rejected with 400 rather than honoured. * * 408 is retried because it is the edge timing out the request body (nginx * client_body_timeout and friends), never a verdict on the payload; RFC 9110