Merge pull request #7 from BrentMifsud/bm/transport-protocol

Extract Transport protocol and migrate to swift-http-types

Author: BrentMifsud

CLAUDE.md

@@ -2,6 +2,12 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Git Workflow
+
+- **Never commit directly to `main`.** All changes must be made on a feature branch and merged via pull request.
+- Branch naming convention: `bm/<short-description>` (e.g., `bm/transport-protocol`, `bm/fix-cache-bug`)
+- If you find yourself on `main`, create a feature branch before making any changes.
+
 ## Build and Test Commands
 
 ```bash
@@ -20,26 +26,40 @@ swift test --filter "MiddlewareTests/middlewareCallOrder"
 
 ## Architecture
 
-Simplicity is a type-safe HTTP client library for Swift, inspired by swift-openapi-generator's client design.
+Simplicity is a type-safe HTTP client library for Swift, inspired by swift-openapi-generator's client design. It uses Apple's `swift-http-types` (`HTTPTypes`, `HTTPTypesFoundation`) for standard HTTP primitives.
 
 ### Core Components
 
-- **HTTPClient** (`Sources/Simplicity/HTTPClient.swift`): The main entry point. Executes requests through a middleware chain using `URLSession`. The `send(request:)` method builds the middleware chain in reverse order, so middlewares execute in the order they were added.
+- **Client protocol** (`Sources/Simplicity/Protocol/Client.swift`): The main entry point. Defines `send(_:)` and `upload(_:)` methods that execute requests through a middleware chain. Uses Apple's `HTTPRequest.Method`, `HTTPResponse.Status`, and `HTTPFields` throughout.
+
+- **Request protocol** (`Sources/Simplicity/Protocol/Request.swift`): Defines type-safe requests with associated `RequestBody`, `SuccessResponseBody`, and `FailureResponseBody` types. Uses Apple's `HTTPRequest.Method` and `HTTPFields` for properties. Provides default JSON encoding/decoding implementations. Use `Never?` for `RequestBody` on requests without a body.
+
+- **Response struct** (`Sources/Simplicity/HTTP/Response.swift`): Wraps Apple's `HTTPResponse` and adds typed decoding via `decodeSuccessBody()` / `decodeFailureBody()`. Convenience accessors: `.status`, `.headerFields`.
+
+- **Middleware protocol** (`Sources/Simplicity/Protocol/Middleware.swift`): Intercepts requests and responses via an `intercept` method that receives a `next` closure. Uses `MiddlewareRequest` and `MiddlewareResponse` structs that embed Apple's `HTTPRequest` and `HTTPResponse`.
+
+- **Transport protocol** (`Sources/Simplicity/Protocol/Transport.swift`): Abstracts the network layer at the `HTTPRequest`/`HTTPResponse` level. `URLSessionTransport` is the default implementation wrapping `URLSession`; tests inject `MockTransport`.
+
+- **URLSessionClient** (`Sources/Simplicity/Implementation/URLSessionClient.swift`): Concrete `Client` implementation. Delegates network calls to a `Transport` (defaults to `URLSessionTransport`). Accepts a `URLSession` convenience init for backward compatibility.
 
-- **HTTPRequest protocol** (`Sources/Simplicity/Protocol/HTTPRequest.swift`): Defines type-safe requests with associated `RequestBody` and `ResponseBody` types. Provides default JSON encoding/decoding implementations. Use `Never?` for `RequestBody` on requests without a body.
+### HTTP Types
 
-- **Middleware protocol** (`Sources/Simplicity/Protocol/Middleware.swift`): Intercepts requests and responses via an `intercept` method that receives a `next` closure. Middlewares can modify requests before calling `next` and inspect/modify responses after.
+The library uses Apple's `swift-http-types` throughout:
+- `HTTPRequest.Method` (extensible struct) instead of custom enum
+- `HTTPResponse.Status` (supports any status code, `.kind` categorization) instead of custom enum
+- `HTTPFields` (case-insensitive, multi-value, type-safe names) instead of `[String: String]`
 
 ### Request Body Handling
 
-The `HTTPRequest` protocol has special handling for bodyless requests:
-- Use `Never?` as `RequestBody` and set `httpBody` to `nil` for GET/DELETE requests
-- The protocol has private extensions that skip body encoding when `RequestBody` is `Never` or `Never?`
+The `Request` protocol has special handling for bodyless requests:
+- Use `Never?` as `RequestBody` and set `body` to `nil` for GET/DELETE requests
+- The protocol has extensions that skip body encoding when `RequestBody` is `Never` or `Never?`
 
 ### Testing Approach
 
-Tests use Swift Testing framework (`@Suite`, `@Test`, `#expect`). Network tests mock `URLSession` via `MockURLProtocol` configured on an ephemeral session configuration.
+Tests use Swift Testing framework (`@Suite`, `@Test`, `#expect`). Network tests inject a `MockTransport` conforming to the `Transport` protocol — each test gets its own isolated handler closure with zero shared state.
 - When running tests, be sure to run tests for all supported platforms
+- Prefer `@Test(arguments:)` for parameterized tests over writing separate test functions for each input variation. One parameterized test with an array of inputs is cleaner than many near-identical test cases.
 
 ## Documentation Lookup (Context7)
 
@@ -48,4 +68,4 @@ When working on this project, **always use Context7** to look up documentation b
 Key libraries relevant to Simplicity:
 - **Foundation** — `URLSession`, `URLRequest`, `URLCache`, `JSONEncoder`/`JSONDecoder` APIs
 - **Swift Concurrency** — actors, `async`/`await`, `@Sendable`, `@concurrent`, `nonisolated`
-- **Swift Testing** — `@Suite`, `@Test`, `#expect`, `#require`, `Issue.record`
+- **Swift Testing** — `@Suite`, `@Test`, `#expect`, `#require`, `Issue.record`

Package.resolved

@@ -3,6 +3,18 @@
 
 import PackageDescription
 
+let swiftSettings: [SwiftSetting] = [
+    .swiftLanguageMode(.v6),
+    .strictMemorySafety(),
+    .defaultIsolation(nil),
+    .enableUpcomingFeature("ExistentialAny"),
+    .enableUpcomingFeature("InferIsolatedConformances"),
+    .enableUpcomingFeature("InternalImportsByDefault"),
+    .enableUpcomingFeature("MemberImportVisibility"),
+    .enableUpcomingFeature("ImmutableWeakCaptures"),
+    .treatAllWarnings(as: .error),
+]
+
 let package = Package(
     name: "Simplicity",
     platforms: [
@@ -19,21 +31,22 @@ let package = Package(
             targets: ["Simplicity"]
         ),
     ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-http-types.git", from: "1.0.0"),
+    ],
     targets: [
         .target(
             name: "Simplicity",
-            swiftSettings: [
-                .swiftLanguageMode(.v6),
-                .strictMemorySafety(),
-                .defaultIsolation(nil),
-                .enableUpcomingFeature("InferIsolatedConformances"),
-                .enableUpcomingFeature("NonisolatedNonsendingByDefault"),
-                .enableUpcomingFeature("InternalImportsByDefault"),
-            ]
+            dependencies: [
+                .product(name: "HTTPTypes", package: "swift-http-types"),
+                .product(name: "HTTPTypesFoundation", package: "swift-http-types"),
+            ],
+            swiftSettings: swiftSettings
         ),
         .testTarget(
             name: "SimplicityTests",
-            dependencies: ["Simplicity"]
+            dependencies: ["Simplicity"],
+            swiftSettings: swiftSettings
         ),
     ]
 )