[zac]

Bug fix

JWTAuth committed a refresh's tokens even when setTokens(_:) or clearTokens() had replaced them while the refresh was in flight. It also persisted those tokens through onTokensUpdated. A logout during a refresh could silently sign the user back in, and a new login could be overwritten by stale refreshed tokens. With several requests sharing one refresh, a later waiter could also restore tokens after a logout that landed between two waiters resuming.

A refresh now commits only while it is still the pending refresh. The first waiter commits once, and a superseded refresh never commits. A superseded refresh calls neither onTokensUpdated nor onRefreshFailed. Requests waiting on it continue with the current tokens, or fail with .notAuthenticated after a logout.

Known limit, now documented: a persistence callback that has already started cannot be revoked. If a logout lands while onTokensUpdated is still writing, the write can finish after the logout. Apps that need a hard guarantee should have their store reject writes from a signed-out session.

Other changes

• An empty JWTAuth.Configuration.tokenPrefix sends the bare token instead of a leading space.
• EnvironmentType.swift is folded into Server.swift. The internal sample ApiServer/TestEndpoint types that shipped inside the library are removed. There is no public API change.
• The README and DocC now explain that credentials are bound to an environment. A server-wide static let auth suits single-environment apps. Multi-environment apps should pass matching auth: per request.
• Mocking guide fixes:
  • Removed the nonexistent continuation.endpoint.
  • Made the closure examples Sendable-safe.
  • Added availability annotations to the Combine helper.
  • Replaced the incorrect "no swizzling" claim with an accurate description.
• The environment: and auth: parameters are documented on every request method. DocC builds with no warnings.

Documentation pass

• README rewritten. It is shorter and puts installation first. The requirements and the migration notes from 0.4 are now accurate. The links to the GitHub wiki, which doesn't exist, now point to the guides.
• New DocC Authentication article. It covers server and endpoint declarations, per-request credentials, JWT refresh, logout behavior, custom methods, and errors.
• Examples and Mocking guides rewritten. Several examples didn't compile. The Mocking guide now documents the real behavior of .fail and .none, typed-error matching inside withMock, a URLProtocol stub for testing refresh, and building requests without sending them.
• Doc comments.
  • Every public enum case is documented.
  • Comments that described the wrong encoder or decoder are fixed.
  • Spelling is American, with no filler or em-dashes.
• No code changes. The only non-comment edit is the wording of a debug assertion message.

The README and guide examples were compiled and run against the library. DocC builds with no warnings.

Documentation hosting

The Documentation workflow is removed. It had failed on every run since its trigger moved to releases, because the github-pages environment only allowed deploys from main. As a result, velosmobile.com/Endpoints still shows docs from 2024. A new .spi.yml asks the Swift Package Index to build and host docs for both Endpoints and EndpointsMocking on each release. I checked that both modules build the way the index builds them, with no warnings. The README badges and documentation link now point to the index. The package still needs to be submitted to the index before those links work.

Testing

• swift test passes on macOS across repeated runs.
• The new tests in JWTAuthSupersededRefreshTests cover these scenarios:
  • Logout during a refresh.
  • Login during a refresh.
  • A request suspended on a refresh that is then superseded.
  • The multi-waiter race.
  • An empty token prefix.
• The multi-waiter test failed in 95 of 100 iterations before the fix.
• Linux has not been run locally. CI covers it.