Skip to content

feat(javascript): Request-ID and Correlation-ID support - #6747

Merged
eric-zaharia merged 16 commits into
mainfrom
feat/js-request-id-correlation-id
Aug 3, 2026
Merged

eric-zaharia merged 16 commits into
mainfrom
feat/js-request-id-correlation-id

Conversation

@eric-zaharia

@eric-zaharia eric-zaharia commented Jul 20, 2026 •

Copy link
Copy Markdown
Contributor

🧭 What and Why

🎟 API-516 (epic API-515 · spec)

JavaScript reference implementation of the search clusters' tracing contract, reviewed by Engines before the 10 language ports.

  • Correlation-ID on errors β€” every failed call exposes the server's Correlation-ID as error.correlationId and appended to the message: Invalid API key (Correlation-ID: …). Customers can quote it to support without inspecting raw HTTP. Header absent β†’ errors byte-identical to today.
  • Request-ID on requests β€” the transporter mints an 11-char base62 ID once per call and resends the same value on every retry/host-fallback attempt, so one log search finds all attempts of one operation. Node builds send the Request-ID header; browser/fetch/worker builds (incl. lite) send the x-algolia-request-id query parameter, which never triggers a CORS preflight. A caller-supplied ID always wins, and minting happens after the cache/dedup boundary β€” cache keys and request deduplication are provably unchanged. Covers request, requestWithHttpInfo and requestStream.

Scoped via a requestIdSupport generator flag to search, recommend, composition, algoliasearch (+lite); all other clients' generated code is untouched (their bundles grow ~0.25KB because client-common carries the plumbing β€” abtesting/recommend budgets bumped accordingly). Non-breaking: trailing optional params on the error classes, new optional requestIdChannel transporter option (undefined = off).

πŸ“‹ Behavioral notes

  • Helpers now forward caller requestOptions to their internal calls. The helper docstrings have always documented that requestOptions are forwarded to the waitForTask/getTask polls, and the batch writes inside chunkedBatch/replaceAllObjects already forwarded them β€” but the polls (and replaceAllObjects' failure-path deleteIndex, plus indexExists in accountCopyIndex) were called bare. They now receive the caller's requestOptions, which is also what lets one helper invocation share a single Request-ID. Side effect to be aware of: caller-supplied headers, query parameters and timeouts now apply to those internal requests too.
  • Error messages gain a suffix when the server returns a Correlation-ID. Per the Engines contract, the CID is both a structured field and appended to error.message. Signatures and absent-header behavior are unchanged, but consumers matching exact message strings will see the suffix appear based on server-side header rollout, not client version β€” error.correlationId is the stable way to read it.

πŸ§ͺ Test

  • Unit tests across client-common and all algoliasearch builds: cache key unchanged, dedup shares one ID, same ID across retries, fresh per call, caller precedence, per-build channel, CID on 4xx/retry-exhaustion/timeout paths, edge X-Algolia-RequestID never read.
  • Live check against a cloud-native app: the returned Correlation-ID ends with the exact 11-char request-id the client sent (suffix echo), and real API errors surface their CID.
  • Drive-by: withHttpInfo.test.ts was never registered in vitest.config.ts β€” registered and its assertions fixed.

@eric-zaharia eric-zaharia self-assigned this Jul 20, 2026
@algolia-api-clients-automation-bot

algolia-api-clients-automation-bot Bot commented Jul 20, 2026 •

Copy link
Copy Markdown
Contributor

βœ”οΈ Code generated!

Name Link
πŸͺ“ Triggered by 5a866fc0c7a2c03143729d713ddcb67f55e4544c
πŸƒ Generated commit ed1f8955b457ace5ad9d764fb8006bd665a15cda
🌲 Generated branch generated/feat/js-request-id-correlation-id
πŸ“Š Benchmark results

Benchmarks performed on the method using a mock server, the results might not reflect the real-world performance.

Language Req/s
javascript 2777
go 1805
python 1795
php 1763
csharp 1297
java 1091
swift 946
ruby 932
scala 23

@eric-zaharia
eric-zaharia force-pushed the feat/js-request-id-correlation-id branch from 38831ac to 5fdebc2 Compare July 20, 2026 13:56
@eric-zaharia eric-zaharia changed the title feat(javascript): surface Correlation-ID on client errors (API-516) feat(javascript): Request-ID and Correlation-ID support (API-516) Jul 20, 2026
@eric-zaharia eric-zaharia changed the title feat(javascript): Request-ID and Correlation-ID support (API-516) feat(javascript): Request-ID and Correlation-ID support Jul 23, 2026
@eric-zaharia
eric-zaharia marked this pull request as ready for review August 3, 2026 07:15
@eric-zaharia
eric-zaharia requested a review from a team as a code owner August 3, 2026 07:15
eric-zaharia and others added 16 commits August 3, 2026 10:16
Attach the Correlation-ID response header to ApiError, DetailedApiError
and RetryError as an optional structured field, appended to the message.
Read case-insensitively; the edge PoPs' unrelated X-Algolia-RequestID
header is never used. Missing header leaves errors unchanged.

Also registers the previously-orphaned withHttpInfo.test.ts in
vitest.config.ts (it was never listed, so it never ran) and fixes its
error assertions for vitest 4's deep comparison.
11-char [0-9A-Za-z] identifier, generated via crypto.getRandomValues
with a Math.random fallback for runtimes without the crypto global.
Not wired into the transporter yet.
New requestIdChannel transporter option ('headers' | 'queryParameters',
undefined = off; no client sets it yet). The ID is generated once per
execution after the cache/dedup key is built, reused across every
retry/host-fallback attempt, and fresh per call. A caller-supplied
Request-ID (header or x-algolia-request-id query parameter) is never
overwritten. Covers request, requestWithHttpInfo and requestStream.
New requestIdSupport generator flag scoped to search, recommend,
composition and algoliasearch; the node and liteNode build templates
set requestIdChannel: 'headers' for those clients. Browser, fetch and
worker builds send no Request-ID: production currently rejects the
x-algolia-request-id query parameter with a 400 on strict-validation
endpoints (SRCH-9380 not fully converged), and the header would fail
CORS preflights.
…nnel Request-ID precedence (API-516) (#6758)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@eric-zaharia
eric-zaharia force-pushed the feat/js-request-id-correlation-id branch from cc048d2 to f1c4f4f Compare August 3, 2026 07:16

@MarioAlexandruDan MarioAlexandruDan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok!

@eric-zaharia
eric-zaharia merged commit 2d0d8f3 into main Aug 3, 2026
36 checks passed
@eric-zaharia
eric-zaharia deleted the feat/js-request-id-correlation-id branch August 3, 2026 13:54
algolia-api-clients-automation-bot Bot added a commit that referenced this pull request Aug 3, 2026
…rated) [skip ci]

Co-authored-by: Eric Zaharia <94015633+eric-zaharia@users.noreply.github.com>
Co-authored-by: Xavier Roche <xavier.roche@algolia.com>
algolia-api-clients-automation-bot Bot added a commit to algolia/algoliasearch-client-javascript that referenced this pull request Aug 3, 2026
algolia/api-clients-automation#6747

Co-authored-by: algolia-api-clients-automation-bot[bot] <288895823+algolia-api-clients-automation-bot[bot]@users.noreply.github.com>
Co-authored-by: Eric Zaharia <94015633+eric-zaharia@users.noreply.github.com>
Co-authored-by: Xavier Roche <xavier.roche@algolia.com>
eric-zaharia added a commit that referenced this pull request Aug 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants