Authentication with automatic refresh, plus per-request environment and credentials

[zac]

What this adds

First-class authentication for Endpoints, plus per-request runtime context, targeted at the 0.5.0 release.

Endpoints declare how they are authenticated; callers supply runtime context when they need to. A server names the method its endpoints use, and endpoints inherit or override it:

struct ApiServer: ServerDefinition {
    static let auth = JWTAuth(initialTokens: loadTokens(), refreshHandler: refresh)
    ...
}

struct ProfileEndpoint: Endpoint {
    typealias Server = ApiServer                  // authenticated, nothing else to declare
}

struct LoginEndpoint: Endpoint {
    typealias Server = ApiServer
    static var auth: NoAuth { NoAuth() }          // opts out
}

Requests go through the ordinary URLSession API — there is no separate session or client type:

let profile = try await URLSession.shared.response(with: ProfileEndpoint())

Servers that declare no auth get NoAuth, so existing endpoints compile and behave exactly as before.

Per-request environment and credentials

Static declarations cannot represent two clients talking to different deployments with different credentials — a limitation real integration hit. Both are now request parameters that default to the declarations:

func response<T: Endpoint>(
    with endpoint: T,
    environment: T.Server.Environments = T.Server.defaultEnvironment,
    auth: any AuthenticationMethod = T.auth
) async throws(T.TaskError) -> T.Response

// Two clients, different deployments and credentials, concurrently:
try await session.response(with: ProfileEndpoint(), environment: clientA.environment, auth: clientA.auth)
try await session.response(with: ProfileEndpoint(), environment: clientB.environment, auth: clientB.auth)

Because the defaults come from what endpoints already declare, this is purely additive: no endpoint declaration or call site had to change, and the entire pre-existing test suite passed untouched. Single-client code still passes nothing.

It also keeps everything the declarative model bought, since the static declaration became the default rather than the only source — per-endpoint opt-out, the endpointTask gate, the debug shared-instance assertion, and JWT coalescing (a client holds one JWTAuth and passes it, so sharing follows the account).

Removed: ServerDefinition.environment and its EnvironmentStorage backing — the process-global that made two simultaneous environments impossible. defaultEnvironment remains as the parameter default, and urlRequest() gains a defaulted in: parameter.

Authentication methods

HeaderKeyAuth, BasicAuth (RFC 7617), CookieAuth, JWTAuth, and NoAuth. Custom methods implement only authenticate(request:) — shouldReauthenticate/reauthenticate/maxRetryAttempts are defaulted. A test in EndpointsMockingTests conforms against the public API only (no @testable) to prove external conformance works.

JWTAuth is an actor providing:

• Reactive refresh on configurable status codes (default [401]), retries bounded by maxRetryAttempts.
• Proactive refresh: set TokenPair.expiresAt and tokens within expiryLeeway (default 30s) of expiring refresh before the request is sent.
• Concurrent refreshes coalesce into one refreshHandler call (join-or-start runs in a single synchronous stretch of actor isolation).
• Rotation protection: reauthenticate(after:) receives the failed request and skips refreshing when its credentials were already replaced — protects single-use refresh tokens from in-flight requests.
• onTokensUpdated/onRefreshFailed hooks for persistence and logout.

Typed throws + unified error surface

Typed throws throughout: urlRequest() throws EndpointError; endpointTask and the async response(with:) methods throw T.TaskError. Auth failures surface through a new EndpointTaskError.authenticationError(AuthenticationError) case, so callers handle one exhaustive error type with no casting. AuthenticationError.custom(underlying:) covers implementation-specific failures from custom methods.

Which request APIs support authentication

The async/await and Combine APIs both apply authentication, including refresh and retry. endpointPublisher wraps the async request path through a small bridge that carries Combine's non-Sendable promise across the concurrency boundary under a lock and cancels the underlying Task when the subscription is cancelled — so it reuses the async retry loop rather than reimplementing the semantics in Combine operators. That also made Mocking.handleMockPublisher dead code (mocks now flow through the async path), so it is removed.

Two behavior notes for the Combine publishers: they now carry the async path's macOS 12 availability (matching what the README already documents as required), and they deliver on the completing task rather than the explicit .global() queue the previous implementation used.

The closure-based endpointTask takes environment: but is the exception for authentication, staying constrained where T.Auth == NoAuth: it returns a URLSessionDataTask synchronously, so it structurally cannot await an asynchronous authenticate without changing what it returns. Calling it with an authenticated endpoint is a compile error ("requires the types 'HeaderKeyAuth' and 'NoAuth' be equivalent") rather than a request that silently skips its credentials.

Mock registry

Mocks are stored per endpoint type instead of as a single type-erased closure. This fixes a crash where any request for endpoint B inside withMock(A.self) force-cast B's continuation to A's type — exactly the shape multi-endpoint flows take. Unmocked endpoints pass through to the real transport, nested scopes merge (innermost wins per type), and a batch API mocks several endpoints in one scope:

try await withMock { mocks in
    mocks.register(RefreshEndpoint.self, action: .return(...))
    mocks.register(ProfileEndpoint.self, action: .return(...))
} test: { ... }

Mocks bypass authentication and the refresh/retry loop by design (documented); auth failures can be mocked directly via .throw(.authenticationError(...)).

Failure modes made diagnosable

Two constraints that were previously enforced only by documentation now fail loudly, since both had failure modes that are painful to diagnose:

• Shared-instance requirement. JWTAuth keeps tokens and its in-flight refresh on the instance, so writing static var auth: JWTAuth { ... } instead of static let hands out a fresh actor per request — losing tokens and turning coalescing into a refresh storm, with no error to point at. Debug builds now assert once per endpoint type, naming the type and the fix; value-type methods are skipped and the check compiles out of release builds.
• Refresh reentrancy. A refreshHandler that requests an endpoint authenticated by the same JWTAuth deadlocks. A task-local marker set around the handler lets authenticate detect the reentrant call and throw RefreshReentrancyError, whose message states the fix.

Bug fixes found along the way

• Environment storage was keyed by the Environments type, so servers sharing TypicalEnvironments shared one environment slot — switching one server switched them all (surfaced as a parallel-test flake). Fixed to key by server type, and later removed outright when the environment became a per-request value.
• ServerDefinition.Environments requires Sendable.
• handlMock typo fixed (handleMock), and Header.cookie/.setCookie recategorized as request/response.

Testing

88 tests on macOS (URLProtocol-based transport/auth tests are Apple-platform-gated). Package line coverage went from 62% to ~68%, with the auth layer at 93–100% per file and the async URLSession transport paths at 96% (up from 23%). Both platforms verified locally with clean builds, including the Linux swift:6.0 container CI uses, and xcodebuild docbuild runs warning-free.

Beyond behavior, tests cover the declaration semantics themselves: an endpoint inheriting its server's auth, opting out with NoAuth, overriding with a different method, and two endpoints on one server resolving to the same instance. The Combine suite covers an authenticated endpoint, JWT refresh-and-retry through the publisher, an authentication error surfacing, and cancellation propagating into the in-flight task — the last verified to fail when the cancellation hook is removed, since a naive version of that test passes either way.

For the per-request context, a test interleaves eight concurrent requests from two clients on different environments with different keys and asserts every request paired the right host with the right credentials — the case that was previously unrepresentable.

Reviewer notes

• The README's stated requirements now match Package.swift: the package builds against iOS 13 / macOS 10.15, while the async and Combine request APIs (and therefore authentication) require macOS 12. The macOS 12 annotations look more conservative than the SDK strictly requires, but lowering them would assert runtime support I have not verified, so they are unchanged.
• Pre-1.0, so several intentional breaking changes: reauthenticate() → reauthenticate(after:), CookieAuth lost its header knob, JWTAuth.getTokens() → tokens property, AuthenticationError.maxRetriesExceeded removed (was unreachable), and the per-server environment keying changes behavior for anyone relying on shared-enum switching.
• Biggest breaking change: ApiServer.environment = .staging is gone. Pass environment: per request, or rely on defaultEnvironment. This is what makes concurrent multi-environment clients possible.
• Hold one JWTAuth per client for that client's lifetime. Constructing one per request breaks refresh coalescing — the same failure the debug assertion catches for statics, but instance-side it looks like ordinary code.
• A JWTAuth refresh endpoint must not be authenticated by that same JWTAuth (task deadlock) — give it NoAuth; documented in the doc comment and README.
• Suggested release notes for the 0.5.0 tag: authentication with automatic refresh (headline), per-request environment and credentials, mock registry, typed throws adoption.

[zac]

🚀