Skip to content

docs: update CLAUDE.md #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
grdsdev merged 1 commit into from
Nov 4, 2025
Merged

docs: update CLAUDE.md #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 58 additions & 12 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,19 +8,29 @@ This is a Swift HTTP client library built upon Apple's SwiftOpenAPIRuntime and O

## Architecture Overview

The library is structured into two main modules:
The library is structured as a single module with organized subdirectories:

### HTTPClient Module
- **Core Interface**: `Client.swift` - Main HTTP client that orchestrates requests through transport and middleware layers
- **Transport Layer**: `ClientTransport` protocol abstracts HTTP operations from underlying libraries
- **Middleware Layer**: `ClientMiddleware` protocol for request/response interception (auth, logging, metrics)
- **Error Handling**: Structured error types in `Errors/` with `ClientError` and `RuntimeError`
- **HTTP Types**: Built on Apple's `HTTPTypes` package for request/response modeling

### HTTPClientFoundation Module
#### Core Interface (`Interface/`)
- **Client.swift**: Main HTTP client that orchestrates requests through transport and middleware layers
- **ClientTransport**: Protocol that abstracts HTTP operations from underlying libraries
- **ClientMiddleware**: Protocol for request/response interception (auth, logging, metrics)
- **HTTPBody**: Core body type with streaming support and progress tracking (`HTTPBody+Progress.swift`)
- **MultipartFormData**: Built-in support for multipart/form-data requests with automatic encoding
- **CurrencyTypes**: Common types used across the library

#### Foundation Transport (`HTTPClientFoundation/`)
- **URLSessionTransport**: Foundation-based implementation of `ClientTransport` using URLSession
- **Streaming Support**: Platform-dependent streaming vs buffered request handling
- **Buffered Streams**: Custom buffered streaming implementation with lock management
- **Bidirectional Streaming**: Platform-specific streaming support for request/response bodies
- **Buffered Streams**: Custom buffered streaming implementation with lock management for platforms without native streaming

#### Error Handling (`Errors/`)
- Structured error types with `ClientError` and `RuntimeError`
- Errors include full context (request, response, baseURL)

#### Middlewares (`Middlewares/`)
- **LoggingMiddleware**: Structured logging integration via swift-log

## Key Design Patterns

Expand All @@ -29,6 +39,15 @@ The library is structured into two main modules:
3. **Platform Adaptation**: Conditional compilation for Darwin vs Linux Foundation differences
4. **Error Wrapping**: All errors wrapped in `ClientError` with context (request, response, baseURL)

## Platform Support

- iOS 13.0+
- macOS 10.15+
- macCatalyst 13.0+
- watchOS 6.0+
- tvOS 13.0+
- Swift 5.10+

## Development Commands

### Building
Expand All @@ -46,10 +65,17 @@ swift test
swift test --filter HTTPClientTests
```

### CI/CD
The project uses GitHub Actions for continuous integration:
- **macOS**: Tests on Xcode 16.4 and 26.0 in both debug and release configurations
- **Linux**: Builds on Swift 6.2
- **Integration Tests**: Uses go-httpbin (httpbingo.org) for real HTTP testing

## Dependencies

- **HTTPTypes** (Apple): Core HTTP request/response types
- **swift-log** (Apple): Structured logging via `LoggingMiddleware`
- **HTTPTypesFoundation** (Apple): Foundation integration for HTTPTypes
- **swift-log** (Apple): Structured logging via `LoggingMiddleware`
- **swift-collections** (Apple): `DequeModule` for buffered streaming

## Testing Framework
Expand All @@ -59,9 +85,29 @@ Uses Apple's Swift Testing framework (not XCTest). Test files use:
- `#expect()` for assertions
- `@testable import` for internal access

## Key Features

### Multipart Form Data
Built-in support for `multipart/form-data` requests with:
- Memory-efficient encoding (< 10 MB in memory, larger files streamed from disk)
- Automatic MIME type detection for file uploads
- Convenient builder API via `Client.send(multipartFormData:with:)`

### HTTPBody Progress Tracking
Monitor upload/download progress through `HTTPBody+Progress.swift` for:
- Real-time progress updates during streaming operations
- Integration with progress reporting UIs

### Bidirectional Streaming
Platform-optimized streaming support:
- Native streaming on Darwin platforms (iOS, macOS, etc.)
- Buffered streaming fallback for Linux/other platforms
- Lock-based synchronization for thread safety

## Code Conventions

- Apache 2.0 license headers on all source files
- **License**: Project uses MIT license, though source files retain Apache 2.0 headers from upstream Apple code
- Platform-specific imports with `#if canImport(Darwin)` blocks
- `@preconcurrency` imports for Linux Foundation types
- Sendable conformance throughout for Swift concurrency safety
- Sendable conformance throughout for Swift concurrency safety
- Single module architecture with organized subdirectories
Loading