Skip to content

Groundwork for HTTP retry: injectable sessions and a shared client - #10

Merged
drewmccormack merged 4 commits into
mainfrom
http-layer
Sep 18, 2026
Merged

drewmccormack merged 4 commits into
mainfrom
http-layer

Conversation

@drewmccormack

Copy link
Copy Markdown
Contributor

Groundwork for audit item 17 (no retry or backoff in the HTTP backends). This is the first half: the plumbing and the retry layer, with tests. No backend is wired up yet, so sync behaviour is unchanged by this PR.

Why it stops here

The four HTTP backends had no injectable URLSession, so none of their networking could be tested at all. Writing retry logic for servers I cannot reach, in code no test can drive, is how you ship a broken retry loop. So this PR makes them testable and builds the retry layer against a fake server. Routing the backends through it is the next PR.

What is in it

  • The three URLSession-based file systems take an optional session. They built their own in a lazy var before, which no test could reach and which is not thread-safe.
  • A URLProtocol-based fake server in a new LLVSNetworkTests target. It returns scripted status codes, headers and transport errors, and records what was sent.
  • HTTPClient: retries 408, 429, 5xx and transport failures, with waits that double and are capped. Retry-After wins over the doubling, within the same cap. A 4xx comes back as a response, not an error, because a 404 means different things to WebDAV, Drive and OneDrive.
  • isSafeToRepeat: false for requests that would do the work twice. The Google Drive upload deletes and re-creates with a new file ID, so retrying it would leave duplicates.
  • Response.requireSuccess(allowing:), so the ~20 call sites that are coming do not each re-derive their status check, and so WebDAV's 207 and its 405 for "directory already exists" stay easy to express.

The wait is behind an injected sleeper, so the backoff is tested without the suite sleeping.

Found in review

Two holes worth naming, both fixed here:

  • Retry-After was unbounded. A server asking for 86400 seconds, or a value parsing as infinity, would have held a sync open indefinitely.
  • Cancellation was not handled. URLSession reports it as URLError(.cancelled), not CancellationError, so the original code was dead for the network path and its test only exercised the sleeper. Both now map correctly, and there is a test that uses a real cancelled request.

Also stopped retrying TLS failures: a bad certificate is a trust problem, and retrying only delays the warning.

225 tests pass. swift build --enable-all-traits is clean.

The three URLSession-based file systems built their own session in a lazy
var, so no test could reach them, and a lazy var is not thread-safe. Each
initialiser now takes an optional session, and builds the default one
itself when none is given.

The WebDAV session delegate held the file system to read its credential.
It holds the credential itself now, so the session can be made before the
delegate, and a mutable var is no longer read from the delegate queue.

New LLVSNetworkTests target, with a URLProtocol-based fake server that
records requests and returns scripted replies. Sessions find their own
server by a token header, so the tests can run in parallel.

Nothing about the requests themselves changes. This is groundwork for
retry, backoff and refresh-on-401.
HTTPClient retries a request while the problem looks temporary: 408, 429
and 5xx, plus transport failures such as a dropped connection. Waits
double from half a second, and a Retry-After header wins over that. A 4xx
is returned as it is, because repeating it would give the same answer.

It deliberately does not interpret status codes any further. A 404 means
different things to different services, so it comes back as a response,
not an error, and the caller decides.

Callers pass isSafeToRepeat: false for a request that would do the work
twice if repeated, such as the Google Drive upload, which creates a new
file each time.

The wait is behind an HTTPSleeper, so the tests check the backoff without
really sleeping. Nothing uses the client yet.
From review of the HTTP client:

- Retry-After was unbounded. A server asking for 86400 seconds, or sending
  something that parses as infinity, would hold a sync open indefinitely.
  The wait is now capped by the policy maximum, and a non-finite value is
  ignored.
- Cancellation was not handled. URLSession reports it as
  URLError(.cancelled), not CancellationError, so the old catch clause was
  dead for the network path and its test only exercised the sleeper. Both
  now map to CancellationError, and the loop checks between attempts.
- Stopped retrying .secureConnectionFailed. A TLS failure is a trust
  problem, and retrying only delays the bad news. Added .badServerResponse
  and .cannotLoadFromNetwork, which are temporary.
- Removed dead code: the loop always returns or throws on its last pass.
- New Response.requireSuccess(allowing:), so the callers that are coming
  do not each re-derive the status check, and a StatusError that keeps the
  body, because servers explain themselves there.
- The date formatter is made once, not per retry.

Test double: the routing header is stripped before recording, servers no
longer leak, and the repeat-last-reply rule is explicit.

WebDAV: the credential is a let, and passing both a session and a password
now traps, rather than silently making unauthenticated requests.
It is not wired into any backend yet, and both notes say so.
@drewmccormack
drewmccormack merged commit 56caf0b into main Sep 18, 2026
1 check passed
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.

1 participant