feat(postgrest): add automatic retries for transient errors

[grdsdev]

Summary

• Adds transparent retry logic to PostgrestBuilder for transient failures (HTTP 520, network errors), mirroring supabase-js#2072
• Retries are enabled by default and only apply to idempotent methods (GET, HEAD)
• Up to 3 retries with exponential backoff (1s → 2s → 4s, capped at 30s) using the existing _clock abstraction from Helpers

Changes

• PostgrestClient.Configuration: new retryEnabled: Bool field (default true); threaded through both init overloads
• PostgrestBuilder: retryEnabled in MutableState (propagated through copy constructor); .retry(enabled:) chainable method; private execute wrapped in retry loop with X-Retry-Count header on retried requests
• PostgrestBuilderTests: 10 new tests covering all retry scenarios; uses ImmediateRetryTestClock to skip sleep delays in tests

Retry behavior

Condition	GET/HEAD	POST/PATCH/DELETE
HTTP 520	retried (up to 3x)	never retried
Network error	retried (up to 3x)	never retried
HTTP 4xx/5xx (non-520)	not retried	not retried

Configuration

// Disable globally
let client = PostgrestClient(url: url, retryEnabled: false)

// Disable per-request
try await supabase.from("users").select().retry(enabled: false).execute()

// Re-enable per-request (overrides client-level false)
try await supabase.from("users").select().retry(enabled: true).execute()

Test plan

• Retry succeeds on 520 → 200 for GET (verifies X-Retry-Count header)
• Retry succeeds on 520 → 200 for HEAD
• No retry on 520 for POST
• No retry on non-520 error (400) for GET
• Retry on network error for GET
• No retry on network error for POST
• Exhausts all 3 retries then throws (4 total calls)
• Per-request .retry(enabled: false) disables retry
• Client-level retryEnabled: false disables retry
• Per-request .retry(enabled: true) overrides client-level false
• All 19 tests in PostgrestBuilderTests pass

Closes: SDK-771

---

🤖 Generated with Claude Code /take

[Copilot]

Pull request overview

Adds configurable automatic retry behavior to PostgREST requests to improve resilience against transient failures, along with test coverage for the new behavior.

Changes:

• Introduces retryEnabled at the PostgrestClient configuration level (defaulting to enabled).
• Adds per-request retry(enabled:) override plus retry logic (HTTP 520 + thrown network errors) for idempotent methods (GET/HEAD), including X-Retry-Count header.
• Extends/adjusts tests to validate retry behavior and keep request-building snapshots deterministic.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
Sources/PostgREST/PostgrestClient.swift	Adds retryEnabled configuration and initializer parameter.
Sources/PostgREST/PostgrestBuilder.swift	Implements retry loop + per-request override + X-Retry-Count header.
Tests/PostgRESTTests/PostgrestBuilderTests.swift	Adds retry-focused unit tests and a no-op clock for fast retries.
Tests/PostgRESTTests/BuildURLRequestTests.swift	Updates test isolation primitive and disables retries to avoid impacting snapshots.

---

You can also share your feedback on Copilot code review. Take the survey.

[mandarini]

Should we enable the retries by default? I guess it's safe since it's only for get/head, but still it's a behaviour change, we should stress it in the docs (I see you do). In any case, should we also retry on 502/503/504?

[grdsdev]

Should we enable the retries by default? I guess it's safe since it's only for get/head, but still it's a behaviour change, we should stress it in the docs (I see you do). In any case, should we also retry on 502/503/504?

@mandarini It is enabled by default already and we should only retry on 520 as per project definition.