Swift Package Manager

In Xcode

// Paste this URL into the search field
https://github.com/PulseOfNetworking/PulseKit.git

In Package.swift

Package.swiftCopy
let package = Package(
    name: "MyApp",
    platforms: [.iOS(.v15)],
    dependencies: [
        .package(
            url: "https://github.com/PulseOfNetworking/PulseKit.git",
            from: "1.0.0"
        )
    ],
    targets: [
        .target(
            name: "MyApp",
            dependencies: [
                .product(name: "PulseNetworking", package: "PulseKit"),
                .product(name: "PulsePlugins",    package: "PulseKit"),
            ]
        )
    ]
)

Requirements

1. Define an endpoint

An Endpoint is a value type that declaratively describes a single API request. It has no side effects — just data.

SwiftCopy
import PulseCore

struct GetUsersEndpoint: Endpoint {
    typealias Response = [User]   // Decoded automatically

    var path:   String     { "/users" }
    var method: HTTPMethod { .get }
    var queryParameters: [String: String] {
        ["page": String(page)]
    }

    let page: Int
}

2. Create a client

Configure once at app startup, then share via dependency injection or PulseClient.default.

SwiftCopy
import PulseNetworking
import PulsePlugins

let config = PulseConfiguration(
    baseURL: URL(string: "https://api.example.com/v1")!
)

let client = PulseClient(
    configuration: config,
    plugins: [
        AuthPlugin(tokenProvider: myTokenStore),
        LoggerPlugin(),
        RetryPlugin(maxAttempts: 3)
    ]
)

3. Make a request

PulseKit supports async/await, Combine, and the @APIRequest SwiftUI property wrapper.

Swift — async/awaitCopy
// async/await
let users = try await client.request(GetUsersEndpoint(page: 1))

// Combine publisher
client.publisher(for: GetUsersEndpoint(page: 1))
    .receive(on: DispatchQueue.main)
    .assign(to: \.users, on: viewModel)
    .store(in: &cancellables)

// SwiftUI @APIRequest
@APIRequest(GetUsersEndpoint(page: 1), autoFetch: true)
var users: RequestPhase<[User]>

Complete example

SwiftContentView.swiftCopy
import SwiftUI
import PulseCore
import PulseNetworking

struct User: Codable, Identifiable {
    let id: Int
    let name: String
    let email: String
}

struct GetUsersEndpoint: Endpoint {
    typealias Response = [User]
    var path: String   { "/users" }
    var method: HTTPMethod { .get }
}

struct UsersView: View {
    @APIRequest(GetUsersEndpoint(), autoFetch: true)
    var users: RequestPhase<[User]>

    var body: some View {
        switch users {
        case .loading:
            ProgressView()
        case .success(let list):
            List(list) { Text($0.name) }
        case .failure(let error):
            Text(error.localizedDescription ?? "Error")
        default: EmptyView()
        }
    }
}

The Endpoint protocol

SwiftPulseCore/Endpoint.swiftCopy
public protocol Endpoint: Sendable {
    associatedtype Response: Decodable

    var path:              String               { get }
    var method:            HTTPMethod           { get }
    var queryParameters:   [String: String]     { get }
    var headers:           [String: String]     { get }
    var body:              RequestBody          { get }
    var timeoutInterval:   TimeInterval         { get }
    var isQueueableWhenOffline: Bool           { get }
}

Properties

Request body types

SwiftCopy
// JSON body — sets Content-Type: application/json automatically
var body: RequestBody { .json(CreateUserRequest(name: name)) }

// Form URL-encoded — sets Content-Type: application/x-www-form-urlencoded
var body: RequestBody { .formURLEncoded(["username": username]) }

// Multipart upload — for file and image uploads
var body: RequestBody {
    let part = MultipartFormData.Part(
        name: "avatar", data: imageData,
        filename: "avatar.jpg", mimeType: "image/jpeg"
    )
    return .multipart(MultipartFormData(parts: [part]))
}

// GraphQL — wraps in {"query": ..., "variables": ...}
var body: RequestBody {
    .graphQL(query: "query { users { id name } }", variables: nil)
}

Practical examples

SwiftCopy
// GET with query parameters
struct SearchUsersEndpoint: Endpoint {
    typealias Response = [User]
    var path: String { "/users/search" }
    var method: HTTPMethod { .get }
    var queryParameters: [String: String] {
        ["q": query, "page": String(page)]
    }
    let query: String; let page: Int
}

// POST with JSON body
struct CreateUserEndpoint: Endpoint {
    typealias Response = User
    struct Body: Encodable, Sendable { let name: String; let email: String }
    var path: String { "/users" }
    var method: HTTPMethod { .post }
    var body: RequestBody { .json(Body(name: name, email: email)) }
    let name: String; let email: String
}

// DELETE with no response body
struct DeleteUserEndpoint: Endpoint {
    typealias Response = EmptyResponse
    var path: String { "/users/\(id)" }
    var method: HTTPMethod { .delete }
    let id: Int
}

How it works

Plugins form a symmetric pipeline. They execute in order during request preparation and in reverse order during response handling — exactly like Express.js middleware or an onion model.

The PulsePlugin protocol

SwiftCopy
public protocol PulsePlugin: Sendable {
    var identifier: String { get }

    /// Modify the request before it's sent.
    /// Throw a PulseError to abort the entire request.
    func prepare(_ request: inout URLRequest,
                  for context: PluginContext) async throws

    /// Called just before the request is dispatched. Great for logging.
    func willSend(_ request: URLRequest,
                   for context: PluginContext) async

    /// Intercept the response. Return nil to pass through unchanged.
    func didReceive(_ result: Result<PulseResponse, PulseError>,
                     for context: PluginContext) async
        -> Result<PulseResponse, PulseError>?

    /// Called when the full cycle is done. Good for cleanup.
    func didComplete(_ context: PluginContext) async
}

PluginContext

A thread-safe context object passed through the entire plugin lifecycle. Use it to share data between prepare and didReceive in the same request — for example, storing a start time for latency measurement.

SwiftCopy
struct TimingPlugin: PulsePlugin {
    let identifier = "com.myapp.timing"

    func prepare(_ request: inout URLRequest,
                  for context: PluginContext) async throws {
        context.store["start"] = Date()
    }

    func didReceive(_ result: Result<PulseResponse, PulseError>,
                     for context: PluginContext) async
        -> Result<PulseResponse, PulseError>? {
        let elapsed = Date().timeIntervalSince(
            context.store["start"] as! Date
        )
        print("⏱ \(context.endpointPath): \(elapsed * 1000)ms")
        return nil // pass through unchanged
    }
}

Built-in plugins

Enabling the offline queue

First, opt an endpoint in with a single property:

SwiftCopy
struct SyncProgressEndpoint: Endpoint {
    typealias Response = EmptyResponse
    var path: String { "/progress/sync" }
    var method: HTTPMethod { .post }
    var body: RequestBody { .json(payload) }

    // ↓ This single property enables offline queueing
    var isQueueableWhenOffline: Bool { true }

    let payload: ProgressPayload
}

Configure queue policy

SwiftCopy
let config = PulseConfiguration(baseURL: url)
    .with(\.offlineQueuePolicy, value: OfflineQueuePolicy(
        isEnabled:     true,
        maxQueueSize:  100,      // Max requests held in memory + disk
        persistsToDisk: true,    // Survives app restarts
        requestExpiry: 86400     // Expire after 24 hours
    ))

How it works

Observing queue events

SwiftCopy
PulseEventBus.shared.events
    .sink { event in
        switch event {
        case .offlineQueueDraining(let count):
            print("📡 Replaying \(count) queued requests")
        case .offlineQueueRequestCompleted(let id, let success):
            print("Request \(id): \(success ? "✓" : "✗")")
        default: break
        }
    }
    .store(in: &cancellables)

@APIRequest

SwiftCopy
struct MoviesView: View {
    @APIRequest(GetMoviesEndpoint(), autoFetch: true)
    var movies: RequestPhase<[Movie]>

    var body: some View {
        Group {
            switch movies {
            case .idle:
                Button("Load") { $movies.fetch() }
            case .loading:
                ProgressView()
            case .success(let list):
                MovieList(movies: list)
                    .refreshable { $movies.refresh() }
            case .refreshing(let list):
                // Still show old data while new data loads
                MovieList(movies: list)
                    .overlay(ProgressView())
            case .failure(let error):
                ErrorView(error: error) {
                    $movies.fetch()  // Retry
                }
            }
        }
    }
}

RequestPhase

Environment injection

Inject different clients for testing and previews using the SwiftUI environment:

SwiftCopy
// In your app or scene
ContentView()
    .environment(\.pulseClient, productionClient)

// In Xcode Previews
struct MoviesView_Previews: PreviewProvider {
    static var previews: some View {
        MoviesView()
            .environment(\.pulseClient, .preview())
    }
}

Pagination with @PaginatedRequest

SwiftCopy
struct FeedView: View {
    @PaginatedRequest(GetPostsEndpoint(page: 1))
    var feed: PaginatedPhase<[Post]>

    var body: some View {
        List {
            ForEach(feed.items ?? []) { post in
                PostRow(post: post)
            }
            // Infinite scroll trigger
            if case .loaded(_, hasMore: true) = feed {
                ProgressView()
                    .onAppear { $feed.loadMore() }
            }
        }
        .refreshable { $feed.refresh() }
    }
}

MockTransport

Swap URLSessionTransport with MockTransport to provide any response your test needs:

SwiftCopy
func test_request_decodesSuccessfully() async throws {
    let user = User(id: 1, name: "Alice", email: "alice@example.com")

    let transport = MockTransport { request in
        let data = try JSONEncoder().encode(user)
        return PulseResponse(
            data: data,
            httpResponse: .mock(statusCode: 200),
            request: request,
            latency: 0.01
        )
    }

    let client = PulseClient(
        configuration: PulseConfiguration(baseURL: url),
        transport: transport
    )

    let result: User = try await client.request(GetUserEndpoint(id: 1))
    XCTAssertEqual(result.name, "Alice")
}

Testing error paths

SwiftCopy
func test_request_throws401AsUnauthorized() async throws {
    let transport = MockTransport { request in
        PulseResponse(
            data: Data(),
            httpResponse: .mock(statusCode: 401),
            request: request, latency: 0.01
        )
    }
    let client = PulseClient(configuration: config, transport: transport)

    do {
        let _: User = try await client.request(GetUserEndpoint(id: 1))
        XCTFail("Expected .unauthorized")
    } catch PulseError.unauthorized {
        // Expected ✓
    }
}

Testing retry behavior

SwiftCopy
func test_retry_succeedsOnThirdAttempt() async throws {
    var callCount = 0

    let transport = MockTransport { request in
        callCount += 1
        if callCount < 3 {
            return PulseResponse(data: Data(),
                httpResponse: .mock(statusCode: 503),
                request: request, latency: 0.01)
        }
        let data = try JSONEncoder().encode(User(id: 1, name: "Alice"))
        return PulseResponse(data: data,
            httpResponse: .mock(statusCode: 200),
            request: request, latency: 0.01)
    }

    let retryConfig = config.with(\.retryPolicy, value: RetryPolicy(
        maxAttempts: 3,
        backoffStrategy: .immediate,  // No delay in tests!
        retryableStatusCodes: [503],
        retryOnTimeout: false,
        retryOnNoConnection: false
    ))

    let client = PulseClient(configuration: retryConfig, transport: transport)
    let result: User = try await client.request(GetUserEndpoint(id: 1))

    XCTAssertEqual(callCount, 3)
    XCTAssertEqual(result.name, "Alice")
}

SSL Certificate Pinning

Pin against public key hashes (recommended) or full certificate data:

SwiftCopy
let config = PulseConfiguration(baseURL: apiURL)
    .with(\.sslPinningPolicy, value: .publicKeyHashes([
        "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", // Primary
        "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="  // Backup ← always pin two!
    ]))

HMAC Request Signing

SwiftCopy
let signingPlugin = RequestSigningPlugin(
    secret: ProcessInfo.processInfo.environment["API_SIGNING_SECRET"]!,
    signatureHeader: "X-Signature-256"
)

// Each request gets: X-Pulse-Timestamp + X-Signature-256
// Signature = HMAC-SHA256(METHOD|PATH|TIMESTAMP|BODY_HASH)

Sensitive header redaction

SwiftCopy
let logger = LoggerPlugin(options: .init(
    verbosity: .standard,
    sensitiveHeaders: [
        "Authorization",
        "X-API-Key",
        "Cookie",
        "X-Signature-256"
    ]
))
// These headers appear as "***REDACTED***" in logs

Event Bus

SwiftCopy
PulseEventBus.shared.events
    .sink { event in
        switch event {
        case .requestCompleted(let result, let context, let latency):
            analytics.track(latency: latency, path: context.endpointPath)

        case .circuitBreakerOpened(let endpoint):
            alerting.fire(.circuitBreakerOpen, endpoint: endpoint)

        case .requestRetrying(let context, let error, let attempt):
            print("↩ Retry \(attempt) for \(context.endpointPath): \(error)")

        default: break
        }
    }
    .store(in: &cancellables)

Metrics collection

SwiftCopy
let metrics = PulseMetricsCollector()
metrics.attach(to: PulseEventBus.shared)

// At any point, take a snapshot
let snapshot = await metrics.snapshot()
print("Success rate: \(snapshot.successRate * 100)%")
print("p50 latency:  \(snapshot.p50Latency * 1000)ms")
print("p99 latency:  \(snapshot.p99Latency * 1000)ms")

SwiftUI debug panel

SwiftCopy
#if DEBUG
import PulseUI
#endif

struct SettingsView: View {
    @State private var showDebugger = false

    var body: some View {
        List {
            #if DEBUG
            Button("Network Inspector") { showDebugger = true }
                .sheet(isPresented: $showDebugger) {
                    NavigationView { PulseDebugView() }
                }
            #endif
        }
    }
}

PulseClient

PulseError

SwiftCopy
let config = PulseConfiguration(baseURL: url)
    .with(\.timeout, value: 20)
    .with(\.retryPolicy, value: .default)
    .with(\.logLevel, value: .info)
    .with(\.defaultHeaders, value: [
        "X-App-Version": appVersion,
        "X-Platform": "iOS"
    ])

SwiftCopy
do {
    let user: User = try await client.request(GetUserEndpoint(id: 1))
} catch let error as PulseError {
    switch error {
    case .noConnection:
        showOfflineBanner()
    case .unauthorized:
        navigateToLogin()
    case .rateLimited(let retryAfter):
        showRetryBanner(delay: retryAfter)
    default:
        showGenericError(error.localizedDescription)
    }
}

SwiftCopy
// Structured concurrency — automatic cancellation
async let users    = client.request(GetUsersEndpoint())
async let settings = client.request(GetSettingsEndpoint())
let (u, s) = try await (users, settings)

// Task cancellation propagates into PulseKit automatically
let task = Task { try await client.request(LongOperationEndpoint()) }
task.cancel() // URLSessionTask is also cancelled

SwiftCopy
class MyTokenStore: TokenProvider {
    func accessToken() async -> String? { Keychain.accessToken }
    func refreshToken() async throws -> String { /* call refresh endpoint */ }
    func handleAuthenticationFailure() async { /* show login screen */ }
}

AuthPlugin(tokenProvider: MyTokenStore())

SwiftCopy
LoggerPlugin(options: .init(
    verbosity: .verbose,
    sensitiveHeaders: ["Authorization"],
    maxBodyLength: 4096,
    output: { OSLog.network.log($0) }
))

SwiftCopy
RetryPlugin(
    maxAttempts: 4,
    strategy: .exponentialWithJitter(base: 1.0, maxDelay: 30),
    shouldRetry: { error in error.isRetryable }
)

SwiftCopy
CachePlugin(ttl: 300, maxMemoryItems: 200)  // 5-minute TTL

// Manual invalidation
await cachePlugin.invalidate(url: URL(string: "/users")!)
await cachePlugin.clearAll()

SwiftCopy
// Opens after 5 failures, 30-second cooldown
CircuitBreakerPlugin(failureThreshold: 5, cooldownDuration: 30)

SwiftCopy
struct LiveScoresSocket: SocketEndpoint {
    var path: String { "/ws/scores" }
    var pingInterval: TimeInterval { 30 }
}

let socket = TypedSocket<ScoreUpdate>(endpoint: LiveScoresSocket())
await socket.connect()

for await update in socket.messages {
    updateScoreboard(update)
}