mirror of
https://github.com/mastra-ai/mastra.git
synced 2026-11-17 08:44:46 +00:00
fix(client-js): stop retrying state-changing requests by default (#30434)
> Opened by @factory-project:7d5175c3-3a20-42ac-aba9-756f183136f4 The JavaScript client retried every HTTP method the same way, so a `POST`, `PUT`, `PATCH`, or `DELETE` that hit a server error was silently re-sent up to four times. When the server had already committed the work before failing, that replay duplicated side effects — agent generations, workflow starts, and similar writes. `BaseResource.request()` now resolves retries by method: `GET`, `HEAD`, and `OPTIONS` keep the default of three attempts, while every other method is attempted once unless the caller opts in with an explicit `retries` count on the client or the call. Requests that pass no method keep the previous read behavior. Four observability queries only read server state even though they travel as `POST`, so `aggregateTraces()`, `aggregateSpans()`, `queryTraceThreads()`, and `querySpans()` keep the read default. An explicit `retries` on the client still wins. **Approved** — head `a2e46c41b1` (branch `factory/issue-30404-3ca17cc5ca80`, base `5b7f1302`). ### Checks on this head | Check | Result | Tests | | --- | --- | --- | | `@mastra/client-js` tests + typecheck (`npx vitest run`) | ✅ Passed | 910 passed across 48 files; typecheck no errors | | Type-aware lint (`npx oxlint --type-aware .`) | ✅ Passed | 0 warnings, 0 errors | | New tests on base code | ✅ Catches the bug | 4 of 4 write cases fail on base, pass on head | | Independent reproduction through the public client API against a real 500 server | ✅ Passed | base repeats POST/PATCH/PUT/DELETE and `agent.generate` 4× each; head sends each once, GET still 4×, opt-in counts unchanged | | Changeset package validation | ✅ Passed | `@mastra/client-js` patch accepted | ### Follow-ups - `queryTraces()` is the one read-style `POST` left on the single-attempt default (`client-sdks/client-js/src/resources/observability.ts:338`). The four queries the review named keep the read default, so the `@mastra/react` hooks that pin React Query `retry: false` on them (`client-sdks/react/src/hooks/traces/use-trace-aggregate.ts:30`, `use-span-aggregate.ts:29`, `use-query-spans.ts:64`, `use-query-threads.ts:67`) still get the client retry. - `client-sdks/react/src/hooks/traces/use-trace-aggregate.ts:17` and `use-span-aggregate.ts:16` say "the client already retries server errors", which holds again for these endpoints on head `5ba90bf1`, so those comments need no change. - `docs/src/content/en/reference/client-js/observability.mdx:523` still recommends `{ retries: 0, anchorRetryTimeoutMs: 0 }` for PUT feedback replacement; `retries: 0` is now the PUT default, so only the `anchorRetryTimeoutMs: 0` half still matters. ### Adversarial check Most damaging reading — that this silently strips the only retry layer from shipped `@mastra/react` observability queries and breaks the contract those hooks document — fails on the evidence: the loss is limited to read-style POST endpoints and is the method-based gating the issue asked for, those hooks live in a package the approved plan scoped out, and self-review treats adjacent hardening as a follow-up rather than a blocking finding. ### Follow-up commit `5ba90bf15a` adds the fix for the review finding above: the four read-only observability queries pass `retries: this.readRetries()` (new `BaseResource` helper, explicit client `retries` wins), 5 new tests fail on `a2e46c41` and pass here, and the playground-ui metrics tests that the write-only default broke pass again. Fixes #30404 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ELI5: The JavaScript client used to resend failed requests up to three times, even for actions that change data, like creating or deleting things. Now, only read requests are retried by default. Change requests are sent once unless the developer asks for retries. ## Summary This pull request changes the default retry behavior of `BaseResource.request()` in `@mastra/client-js`. The change stops implicit retries of state-changing requests after a server error. A server error does not show whether the server applied the change before it failed, so a retry can repeat a side effect. ## Behavior change - `GET`, `HEAD`, and `OPTIONS` keep the default of three retries. - `POST`, `PUT`, `PATCH`, `DELETE`, and any other unrecognized method send one attempt by default. - Requests without a method use `GET`, so they keep the read-style default of three retries. The method is normalized to upper case before the lookup. - An explicit `retries` value on the request overrides the client-level value. The client-level value overrides the method default. - Existing validation of the retry count is unchanged. A non-negative safe integer is still required. - Four read-only observability queries use `POST`: `aggregateTraces`, `aggregateSpans`, `queryTraceThreads`, and `querySpans`. These queries keep the read-style default of three retries. They do not follow the write default. ## Implementation - `client-sdks/client-js/src/resources/base.ts`: - Adds a default of three retries for read methods and a set of read methods (`GET`, `HEAD`, `OPTIONS`). - Resolves retries in this order: request-level value, then client-level value, then the method default. Other methods default to zero. - Adds a protected `readRetries()` helper. It returns the client-configured retry count, or three when none is set. - `client-sdks/client-js/src/resources/observability.ts`: The four observability queries listed above pass `readRetries()` as their retry count. `aggregateTraces` still forwards its optional abort signal. The other three calls do not add a signal option. - `client-sdks/client-js/src/types.ts`: Updates the JSDoc for `ClientOptions.retries` and `RequestOptions.retries`. The docs state the read-only default. They also state that a per-request count overrides the client count and enables retries for writes. Declarations are unchanged. - `client-sdks/client-js/src/resources/base.test.ts`: Adds 52 lines of tests. The tests cover: - One attempt for `POST`, `PATCH`, `PUT`, and `DELETE` after a 500 response, with no retry count configured. - Three attempts for read methods. - Explicit client-level and request-level retry counts that enable retries for writes. - `client-sdks/client-js/src/resources/observability.test.ts`: Adds tests that the four observability queries make four fetch attempts after a server error. Adds tests that `retries: 0` on `aggregateTraces` limits the request to one attempt. Moves the thread-query and span-query request fixtures into their `describe` scopes. Payloads are unchanged. - `client-sdks/client-js/src/resources/agent.client-tools.test.ts`: Removes a mocked continuation response from one streaming test. The test expects no recursive request. - `.changeset/witty-wolves-write-once.md`: Adds a patch changeset for `@mastra/client-js`. - `docs/src/content/en/docs/server/mastra-client.mdx` and `docs/src/content/en/reference/client-js/mastra-client.mdx`: Document the per-method default. The reference page changes the `retries` default to `3 for read requests, 0 for write requests`. The server page notes that the listed observability queries keep the read default. ## Diff scope The diff covers 9 files, with 200 insertions and 53 deletions. Six files are in `client-sdks/client-js`, with 190 insertions and 51 deletions. The changeset and two docs files make up the rest. ## Verification The PR author reports that `npx vitest run` passed 910 tests across 48 files, with no typecheck errors. The author also reports that type-aware lint and changeset validation passed. These results come from the PR description. This summary did not rerun them. ## Notes - The PR description lists `@mastra/react` hooks that use observability POST endpoints as a follow-up. Hooks that set `retry: false`, and two hook comments, may describe retry behavior that no longer applies. This summary did not verify those files. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com> Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
This commit is contained in:
parent
54708eccf8
commit
b666fdbf03
9 changed files with 200 additions and 53 deletions
Loading…
Add table
Add a link
Reference in a new issue