generators-offline-queue

First step: Tell the user: "generators-offline-queue skill loaded."

Offline Queue Generator

Generate a production offline operation queue that persists API requests/mutations when offline, stores them to disk, and retries with exponential backoff when connectivity returns. Essential for apps that need offline-first behavior.

When This Skill Activates

Use this skill when the user:

• Asks to "add offline queue" or "offline support"
• Wants to "queue requests" when there is no network
• Mentions "offline first" architecture or design
• Asks about "retry when online" or "retry on reconnect"
• Wants "pending operations" that sync later
• Mentions "offline mutations" or "queue API calls"

Pre-Generation Checks

1. Project Context Detection

• Check Swift version (requires Swift 5.9+)
• Check deployment target (iOS 16+ / macOS 13+)
• Check for @Observable support (iOS 17+ / macOS 14+)
• Identify source file locations

2. Conflict Detection

Search for existing networking/offline code:

Glob: **/*OfflineQueue*.swift, **/*OfflineOperation*.swift, **/*NetworkMonitor*.swift, **/*RetryPolicy*.swift
Grep: "NWPathMonitor" or "OfflineQueue" or "pendingOperations" or "offlineQueue"

If existing offline handling found:

• Ask if user wants to replace or extend it
• If extending, adapt generated code to existing patterns

3. Framework Availability

Check for Network framework availability (required for NWPathMonitor). Available on iOS 12+ / macOS 10.14+, so effectively always available for our iOS 16+ / macOS 13+ targets.

Configuration Questions

Ask user via AskUserQuestion:

1. Operation types?

   • API calls only (JSON requests/responses)
   • File uploads only (multipart data)
   • Both API calls and file uploads

2. Persistence strategy?

   • SwiftData (iOS 17+ / macOS 14+) — structured queries, migration support
   • File-based (JSON files in app support) — simpler, wider compatibility — recommended

3. Retry strategy?

   • Exponential backoff with jitter — recommended (prevents thundering herd)
   • Linear backoff (fixed interval between retries)
   • Immediate (retry as soon as connectivity returns, no delay)

4. Conflict resolution?

   • Server wins (discard client changes on conflict)
   • Client wins (overwrite server data on conflict)
   • Manual merge (surface conflicts to the user for resolution)

Generation Process

Step 1: Read Templates

Read references/patterns.md for architecture guidance and conflict resolution strategies. Read templates.md for production Swift code.

Step 2: Create Core Files

Generate these files:

1. OfflineOperation.swift — Codable model for queued operations
2. OfflineQueueManager.swift — Actor managing enqueue, dequeue, process, retry
3. QueuePersistence.swift — Protocol + file-based implementation for saving operations
4. NetworkMonitor.swift — @Observable wrapper around NWPathMonitor

Step 3: Create Policy Files

5. RetryPolicy.swift — Configurable backoff strategy with jitter

Step 4: Create UI Files

6. OfflineQueueDashboardView.swift — Debug view showing queue state and manual controls
7. OfflineQueueModifier.swift — ViewModifier showing "Offline" banner when disconnected

Step 5: Determine File Location

Check project structure:

• If Sources/ exists → Sources/OfflineQueue/
• If App/ exists → App/OfflineQueue/
• Otherwise → OfflineQueue/

Output Format

After generation, provide:

Files Created

OfflineQueue/
├── OfflineOperation.swift          # Codable operation model
├── OfflineQueueManager.swift       # Actor-based queue manager
├── QueuePersistence.swift          # Protocol + file-based persistence
├── NetworkMonitor.swift            # NWPathMonitor wrapper
├── RetryPolicy.swift               # Exponential backoff with jitter
├── OfflineQueueDashboardView.swift # Debug dashboard view
└── OfflineQueueModifier.swift      # Offline banner modifier

Integration with Networking Layer

Enqueue an operation when offline:

// In your networking layer or repository
func createPost(_ post: Post) async throws {
    guard networkMonitor.isConnected else {
        let operation = OfflineOperation(
            endpoint: "/api/posts",
            httpMethod: .post,
            body: try JSONEncoder().encode(post),
            headers: ["Content-Type": "application/json"]
        )
        await queueManager.enqueue(operation)
        return
    }
    // Normal online request
    try await apiClient.post("/api/posts", body: post)
}

Transparent offline support with a wrapper:

func performOrQueue<T: Codable>(
    endpoint: String,
    method: HTTPMethod,
    body: T
) async throws {
    let data = try JSONEncoder().encode(body)

    if networkMonitor.isConnected {
        try await apiClient.request(endpoint: endpoint, method: method, body: data)
    } else {
        let operation = OfflineOperation(
            endpoint: endpoint,
            httpMethod: method,
            body: data
        )
        await queueManager.enqueue(operation)
    }
}

Show offline banner in your app:

struct ContentView: View {
    var body: some View {
        NavigationStack {
            FeedView()
        }
        .offlineQueueBanner()  // Shows "Offline — changes will sync" when disconnected
    }
}

Add dashboard for debugging:

#if DEBUG
NavigationLink("Offline Queue") {
    OfflineQueueDashboardView()
}
#endif

Testing

@Test
func operationEnqueuedWhenOffline() async throws {
    let persistence = MockQueuePersistence()
    let monitor = MockNetworkMonitor(isConnected: false)
    let manager = OfflineQueueManager(persistence: persistence, monitor: monitor)

    let operation = OfflineOperation(
        endpoint: "/api/posts",
        httpMethod: .post,
        body: Data("{\"title\":\"Hello\"}".utf8)
    )
    await manager.enqueue(operation)

    let pending = await persistence.loadAll()
    #expect(pending.count == 1)
    #expect(pending.first?.endpoint == "/api/posts")
}

@Test
func operationsProcessedOnReconnect() async throws {
    let persistence = MockQueuePersistence()
    let monitor = MockNetworkMonitor(isConnected: false)
    let executor = MockOperationExecutor()
    let manager = OfflineQueueManager(
        persistence: persistence,
        monitor: monitor,
        executor: executor
    )

    let operation = OfflineOperation(
        endpoint: "/api/posts",
        httpMethod: .post,
        body: Data("{\"title\":\"Hello\"}".utf8)
    )
    await manager.enqueue(operation)

    // Simulate coming back online
    monitor.simulateConnectivityChange(isConnected: true)

    // Wait for processing
    try await Task.sleep(for: .milliseconds(200))

    #expect(executor.executedOperations.count == 1)
    let remaining = await persistence.loadAll()
    #expect(remaining.isEmpty)
}

@Test
func exponentialBackoffCalculation() {
    let policy = RetryPolicy(
        maxRetries: 5,
        baseDelay: 1.0,
        maxDelay: 60.0,
        multiplier: 2.0
    )

    #expect(policy.delay(forAttempt: 0) >= 1.0)
    #expect(policy.delay(forAttempt: 1) >= 2.0)
    #expect(policy.delay(forAttempt: 2) >= 4.0)
    #expect(policy.delay(forAttempt: 5) <= 60.0)  // Capped at maxDelay
}

Common Patterns

Enqueue Operation

let operation = OfflineOperation(
    endpoint: "/api/comments",
    httpMethod: .post,
    body: try JSONEncoder().encode(comment),
    headers: ["Authorization": "Bearer \(token)"]
)
await queueManager.enqueue(operation)

Process Queue on Connectivity

// Automatic — OfflineQueueManager observes NetworkMonitor
// and calls processQueue() when connectivity returns.
// No manual intervention needed.

Handle Conflict Resolution

// Server returns 409 Conflict
switch conflictStrategy {
case .serverWins:
    // Discard local operation, fetch server state
    await queueManager.markCompleted(operation)
case .clientWins:
    // Retry with force flag
    operation.headers["X-Force-Overwrite"] = "true"
    await queueManager.retry(operation)
case .manualMerge:
    // Surface to user
    await queueManager.markConflict(operation, serverData: responseData)
}

Gotchas

Operation Ordering and Dependencies

Operations may have dependencies (e.g., "create parent" must succeed before "create child"). The queue processes in FIFO order by default. For explicit dependencies, use the dependsOn field to chain operations, and the queue manager will skip dependent operations until their prerequisites complete.

Idempotency Keys

Every queued operation gets a UUID-based idempotency key. The server must check this key to avoid duplicate processing if the client retries an operation that actually succeeded but the response was lost. Without idempotency keys, a retry could create duplicate records.

Stale Data After Long Offline Periods

If the device is offline for hours or days, queued operations may reference data that has changed server-side. Consider adding a TTL to operations (e.g., 24 hours) and discarding expired operations with a user notification rather than blindly replaying stale mutations.

Background URLSession for Large Uploads

For file uploads, use a background URLSession configuration so uploads continue even when the app is suspended. The standard queue manager handles JSON API calls; for large uploads, delegate to a background transfer service.

Queue Size Limits

Set a maximum queue size (e.g., 500 operations or 50 MB) to prevent unbounded growth. When the limit is reached, notify the user that offline storage is full and suggest connecting to sync pending changes.

References

• templates.md — All production Swift templates
• references/patterns.md — Offline-first architecture, conflict resolution, idempotency
• Related: generators-networking-layer — Base networking layer to wrap with offline support
• Related: generators-http-cache — Cache GET responses for offline reading