From 8c490de970cda0bb11c561a8168566af76e9d639 Mon Sep 17 00:00:00 2001 From: Guilherme Souza Date: Mon, 14 Sep 2026 15:37:14 -0300 Subject: [PATCH] docs(capability-matrix): add the request_timeout spec Describes the construction-time and per-request timeout contract for database.configuration.request_timeout: unit and default are documented per SDK, deadline or idle semantics both satisfy it, the bound applies per retry attempt, and it composes with caller-initiated cancellation. Co-Authored-By: Claude --- .../database/configuration/request_timeout.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 packages/capability-matrix/specs/database/configuration/request_timeout.md diff --git a/packages/capability-matrix/specs/database/configuration/request_timeout.md b/packages/capability-matrix/specs/database/configuration/request_timeout.md new file mode 100644 index 0000000..7a0fe1b --- /dev/null +++ b/packages/capability-matrix/specs/database/configuration/request_timeout.md @@ -0,0 +1,36 @@ +# Request Timeout + +Bound how long a database request may wait on the network. A request that exceeds the bound fails with a timeout error instead of hanging, and the underlying connection is released. + +## Behavior + +The caller sets a timeout at client construction time. It applies to every request the client sends, including the requests an automatic retry re-sends. + +Where the SDK offers a per-request override, the per-request value wins over the construction-time value for that one request. Neither value changes any other request or any other client. + +The timeout is expressed in the platform's idiomatic duration unit (milliseconds in JavaScript, seconds in Swift). The SDK documents the unit and any default it applies when the caller sets nothing. An SDK may leave requests unbounded when nothing is set, or apply a platform default; it must not invent a default silently. + +The bound may be a total deadline for the whole exchange or an idle timeout that fires once no bytes have moved for the given interval. Both satisfy this capability; the SDK documents which one it implements. Either way, when the bound fires the SDK: + +- cancels the in-flight request so the connection is released; +- surfaces a timeout error that the caller can tell apart from a server error and from a caller-initiated cancellation, where the platform makes that distinction possible. + +A non-positive value is treated as unset. It must never mean "fail immediately". + +### Interaction with retries + +The timeout bounds each attempt, not the sum of all attempts. A timeout on an idempotent request counts as a transient network failure and is eligible for `database.configuration.auto_retry`. + +### Interaction with cancellation + +A caller-initiated cancellation (`database.using_modifiers.request_cancellation`) composes with the timeout: whichever fires first ends the request. Neither disables the other. + +## Errors + +The timeout surfaces as the platform's network-layer timeout error (for example an `AbortError` in JavaScript, `URLError.timedOut` in Swift), never as a PostgREST error decoded from a response body. + +## Related + +- `database.using_modifiers.request_cancellation` — caller-initiated cancellation; composes with the timeout +- `database.configuration.auto_retry` — a timed-out attempt on an idempotent request is retried like any other transient failure +- `functions.invocation.timeout` — the same knob for Edge Function invocations