Add session-actor design updates

samdeane · samdeane · commit 50cca829f05a · 2026-02-27T15:44:52.000Z
diff --git a/README.md b/README.md
@@ -32,75 +32,115 @@
 
 # JSONSession
 
-Support for periodic polling of a JSON REST resource.
+JSONSession is a small async client for JSON REST APIs that use bearer-token authentication.
 
-Authentication is passed in the `Authorization` header, as `bearer <token>`. 
+It provides:
+- a concurrency-safe `Session` actor for authenticated requests
+- a `Processor` / `ProcessorGroup` pipeline for typed response decoding
+- resource path abstraction via `ResourceResolver`
+- stream-based polling via `Session.pollData(...)`
 
-The response is expected to contain an `Etag` header field, which represents the current state of the resource, and is passed back to the server with subsequent requests.
+Authentication is sent in the `Authorization` header as `bearer <token>`.
 
-This mechanism allows efficient polling of the server for changes, and can be a workaround for rate-limiting (where requests that didn't pick up any change in state don't count towards the rate limit).
+## Design
 
-## Parsing Responses
+The current design is intentionally one-shot and structured-concurrency friendly:
 
-When a request is sent, it is passed a `ProcessorGroup` which contains a list of `Processor` objects. 
+- `Session` is an actor, so request execution and transport use are isolated.
+- `Session` does not own long-lived background polling loops.
+- Callers own scheduling and cancellation policy (for example, an actor that sleeps and calls `session.request(...)`).
+- For continuous polling, callers can use `session.pollData(...)`, which returns an `AsyncStream` and cancels automatically when the stream terminates.
+- Processing remains pluggable: `ProcessorGroup` tries processors in order by HTTP status code and decode success.
 
-When a response comes back, it is matched against each `Processor` in turn, matching against the HTTP status code. If a processor supports the code, it is given a chance to decode the response. 
+This keeps JSONSession focused on transport + decoding, while application/domain layers own timing decisions.
 
-If a processor fails to decode the response (throws an error), matching is continued unless the list of processors is exhausted. The first successful match ends this process. If all processors are exhausted without success, then the `unprocessed` method of the `ProcessorGroup` is called; this can be used for catch-all error handling.
+## Intended Usage
 
-## Example
+1. Define a `ResourceResolver` for each endpoint.
+2. Define one or more `Processor` types for expected status/payload pairs.
+3. Compose processors into a `ProcessorGroup`.
+4. Call `await session.request(...)` for each fetch cycle your app decides to run.
 
-This simple example polls the endpoint `https://some.endpoint/v1/` for the resource  `some/rest/resource`.
+You can also call `await session.data(for:)` when you want raw bytes and the `HTTPURLResponse`.
 
-When something has changed, a JSON response will be sent back. If the HTTP status code is one that we expect, we will decode the JSON into a Swift object, and call one of our Processor objects with it.
+## Example
 
 ```swift
-/// if the response is 200, the server will send us an item
-struct ItemProcessor: Processor {
-    struct Item: Decodable {
-        let name: String
-    }
-
-    let codes = [200]
-    func process(_ item: Item, response: HTTPURLResponse, in session: Session) -> RepeatStatus {
-        print("Received item \(item.name)")
-        return .inherited
-    }
+import Foundation
+import JSONSession
+
+struct Item: Decodable {
+  let name: String
 }
 
-/// if the response is 400, the server will send us an error
-struct ErrorProcessor: Processor {
-    struct Error: Decodable {
-        let error: String
-    }
-
-    let codes = [400]
-    func process(_ payload: Error, response: HTTPURLResponse, in session: Session) -> RepeatStatus {
-        print("Something went wrong: \(payload.error)")
-        return .inherited
-    }
+struct ErrorPayload: Decodable {
+  let error: String
 }
 
-// make a session for the service we're targetting, supplying the authorization token
-let session = Session(base: URL(string: "https://some.endpoint/v1/")!, token: "<api-token>")
+actor Context {
+  var lastItem: Item?
+  var lastError: String?
 
-// schedule polling of some REST resource
-session.poll(target: Resource("some/rest/request"), processors: [ItemProcessor(), ErrorProcessor()], repeatingEvery: 1.0)
+  func setItem(_ item: Item) {
+    lastItem = item
+  }
 
-// the endpoint will be queried repeatedly by the session
-// when an expected response comes back, the response will be decoded and one of our processor objects will be called to process it
-RunLoop.main.run()
-```
+  func setError(_ message: String) {
+    lastError = message
+  }
+}
 
+struct ItemProcessor: Processor {
+  typealias Context = Context
+  let codes = [200]
+
+  func process(
+    _ payload: Item,
+    response _: HTTPURLResponse,
+    for _: Request<Context>,
+    in context: Context
+  ) async throws -> RepeatStatus {
+    await context.setItem(payload)
+    return .cancel
+  }
+}
 
-### Requirements
+struct ErrorProcessor: Processor {
+  typealias Context = Context
+  let codes = [400]
+
+  func process(
+    _ payload: ErrorPayload,
+    response _: HTTPURLResponse,
+    for _: Request<Context>,
+    in context: Context
+  ) async throws -> RepeatStatus {
+    await context.setError(payload.error)
+    return .cancel
+  }
+}
 
-The `swift-tools-version` requirement is set to Swift 5, as the Foundation Networking API isn't quite right on Linux prior to 5.3. 
+let session = Session(base: URL(string: "https://some.endpoint/v1/")!, token: "<api-token>")
+let context = Context()
+let processors = AnyProcessorGroup(
+  name: "Item Query",
+  processors: [
+    ItemProcessor().eraseToAnyProcessor(),
+    ErrorProcessor().eraseToAnyProcessor(),
+  ]
+)
+
+await session.request(
+  target: Resource("some/rest/resource"),
+  context: context,
+  processors: processors
+)
+```
 
-Strictly speaking the code works with Swift 5.2 on Apple platforms, though it requires a fairly modern SDK.
+## Requirements
 
-### Made For Github
+See `Package.swift` for current platform and Swift toolchain requirements.
 
-This is a generalisation of some code I built to access the Github API, and is used by [Octoid](https://github.com/elegantchaos/Octoid) which is a more general Github library.
+## Made For GitHub
 
-I split out the JSONSession functionality because I imagined that other servers may use the same mechanism. This may be an incorrect assumption, and/or this code may need to be generalised further to work with other servers. If so, let me know via an issue.
+JSONSession originated as part of GitHub API integrations and is used by [Octoid](https://github.com/elegantchaos/Octoid).
diff --git a/Sources/JSONSession/Failure.swift b/Sources/JSONSession/Failure.swift
@@ -5,9 +5,13 @@
 
 import Foundation
 
+/// Standard GitHub-style API failure payload.
 public struct Failure: Codable, Sendable {
+  /// Human-readable failure summary.
   let message: String
+  /// Documentation URL supplied by the API.
   let documentation_url: String
 
+  /// Indicates whether this failure can be ignored by higher-level callers.
   var canIgnore: Bool { false }
 }
diff --git a/Sources/JSONSession/Processor.swift b/Sources/JSONSession/Processor.swift
@@ -65,7 +65,7 @@ extension AnyProcessor: ProcessorGroup {
 
 /// Typed processor convenience protocol for concrete payload/context types.
 public protocol Processor<Context>: Sendable {
-  /// Context type supplied by the caller while polling.
+  /// Context type supplied by the caller while processing a request.
   associatedtype Context: Sendable
   /// Decoded response type this processor consumes.
   associatedtype Payload: Decodable
diff --git a/Sources/JSONSession/ProcessorGroup.swift b/Sources/JSONSession/ProcessorGroup.swift
@@ -24,7 +24,7 @@ public protocol ProcessorGroup<Context>: Sendable {
   var groupIsProcessor: Bool { get }
 
   /// Path to the resource we process.
-  func path(for target: ResourceResolver, in session: Session) -> String
+  func path(for target: any ResourceResolver) -> String
 
   /// Decode a response and return repeat behavior.
   func decode(
@@ -36,11 +36,14 @@ public protocol ProcessorGroup<Context>: Sendable {
 }
 
 extension ProcessorGroup {
+  /// Default name used when a group does not provide one.
   public var name: String { "untitled group" }
+  /// Default assumes this value is a group and not a single processor.
   public var groupIsProcessor: Bool { false }
 
-  public func path(for target: ResourceResolver, in session: Session) -> String {
-    target.path(in: session)
+  /// Resolves request path from the provided target.
+  public func path(for target: any ResourceResolver) -> String {
+    target.path
   }
 
   public func decode(
@@ -80,6 +83,7 @@ extension ProcessorGroup {
     throw Session.Errors.unexpectedResponse(response.statusCode)
   }
 
+  /// Returns a consistent log message for successful processing.
   private func processedMessage(processor: AnyProcessor<Context>, status: RepeatStatus) -> String {
     let nameInfo = groupIsProcessor ? name : "\(name) using \(processor.name)"
     return "Processed \(nameInfo). Repeat status: \(status)."
@@ -88,9 +92,12 @@ extension ProcessorGroup {
 
 /// Convenience group wrapper for a list of erased processors.
 public struct AnyProcessorGroup<Context: Sendable>: ProcessorGroup {
+  /// Group name used in logs.
   public let name: String
+  /// Ordered processor chain used for decoding and handling responses.
   public let processors: [AnyProcessor<Context>]
 
+  /// Creates a named group from an ordered list of processors.
   public init(name: String, processors: [AnyProcessor<Context>]) {
     self.name = name
     self.processors = processors
diff --git a/Sources/JSONSession/Query.swift b/Sources/JSONSession/Query.swift
@@ -9,13 +9,17 @@ import Foundation
   import FoundationNetworking
 #endif
 
+/// Legacy helper for constructing authenticated URL requests.
 public struct Query {
+  /// Human-readable query name.
   let name: String
-  let query: (ResourceResolver, Session) -> String
+  /// Closure that resolves query-specific path components.
+  let query: @Sendable (any ResourceResolver, Session) -> String
 
-  func request(for target: ResourceResolver, in session: Session) -> URLRequest {
+  /// Builds an authenticated GET request for a target resource.
+  func request(for target: any ResourceResolver, in session: Session) -> URLRequest {
     let authorization = "bearer \(session.token)"
-    var request = URLRequest(url: session.base.appendingPathComponent(target.path(in: session)))
+    var request = URLRequest(url: session.base.appendingPathComponent(target.path))
     request.addValue(authorization, forHTTPHeaderField: "Authorization")
     request.httpMethod = "GET"
     return request
diff --git a/Sources/JSONSession/Request.swift b/Sources/JSONSession/Request.swift
@@ -9,23 +9,25 @@ import Foundation
   import FoundationNetworking
 #endif
 
-/// Runtime state for an individual polling request.
-public struct Request<Context: Sendable>: @unchecked Sendable {
+/// Runtime state for a single request execution.
+public struct Request<Context: Sendable>: Sendable {
   /// Resource being polled.
-  public let resource: ResourceResolver
+  public let resource: any ResourceResolver
   /// Processor chain used to decode/handle responses.
   let processors: any ProcessorGroup<Context>
   /// Optional ETag for conditional requests.
   var tag: String?
-  /// Indicates whether polling should continue after a response.
+  /// Indicates whether follow-up polling was requested by processing.
   var repeating: Bool
-  /// Current repeat interval in seconds.
+  /// Repeat interval hint from response headers.
   var interval: TimeInterval
 
+  /// Next scheduled repeat time when `repeating` is true.
   var repeatTime: DispatchTime? {
     repeating ? DispatchTime.now().advanced(by: interval.asDispatchTimeInterval) : nil
   }
 
+  /// Updates repeat behavior using processor output.
   mutating func updateRepeat(status: RepeatStatus) {
     switch status {
     case .request: repeating = true
@@ -34,6 +36,7 @@ public struct Request<Context: Sendable>: @unchecked Sendable {
     }
   }
 
+  /// Caps the repeat interval with `X-Poll-Interval` when present.
   mutating func capInterval(to seconds: Double) {
     let current = interval
     let interval = max(current, seconds)
@@ -42,9 +45,10 @@ public struct Request<Context: Sendable>: @unchecked Sendable {
     }
   }
 
+  /// Builds an authenticated URL request for this target.
   func urlRequest(for session: Session) -> URLRequest {
     let authorization = "bearer \(session.token)"
-    let path = processors.path(for: resource, in: session)
+    let path = processors.path(for: resource)
     var request = URLRequest(url: session.base.appendingPathComponent(path))
     request.addValue(authorization, forHTTPHeaderField: "Authorization")
     request.httpMethod = "GET"
@@ -58,20 +62,23 @@ public struct Request<Context: Sendable>: @unchecked Sendable {
     return request
   }
 
+  /// Logs scheduled request timing details.
   func log(deadline: DispatchTime) {
     let distance = DispatchTime.now().distance(to: deadline).asTimeInterval
     let timeInfo = distance < 0 ? "now." : "in \(seconds: distance)."
     let repeatInfo = repeating ? " Will repeat in \(seconds: interval)." : ""
     sessionChannel.log("Polling for \(processors.name) \(timeInfo)\(repeatInfo)")
   }
 
+  /// Logs decoder or processor errors with payload context.
   func log(error: Error, data: Data) {
     sessionChannel.log(
       "Error thrown:\n- query: \(processors.name)\n- target: \(resource)\n- processor: \(processors.name)\n- error: \(error)\n"
     )
     sessionChannel.log("- data: \(data.prettyPrinted)\n\n")
   }
 
+  /// Logs successful transport receipt.
   func log(response: URLResponse?) {
     if let _ = response {
       networkingChannel.log("got response for \(resource)")
diff --git a/Sources/JSONSession/Resource.swift b/Sources/JSONSession/Resource.swift
@@ -6,9 +6,9 @@
 import Foundation
 
 /// Basic resource with a fixed path.
-
 public struct Resource: ResourceResolver {
-  let path: String
-  public func path(in _: Session) -> String { path }
+  /// Relative path appended to the configured API base URL.
+  public let path: String
+  /// Creates a fixed-path resource.
   public init(_ path: String) { self.path = path }
 }
diff --git a/Sources/JSONSession/ResourceResolver.swift b/Sources/JSONSession/ResourceResolver.swift
@@ -6,6 +6,7 @@
 import Foundation
 
 /// Something that resolves to a path to a REST resource.
-public protocol ResourceResolver {
-  func path(in session: Session) -> String
+public protocol ResourceResolver: Sendable {
+  /// Relative path for this resource.
+  var path: String { get }
 }
diff --git a/Sources/JSONSession/Session.swift b/Sources/JSONSession/Session.swift
diff --git a/Sources/JSONSession/TimeExtensions.swift b/Sources/JSONSession/TimeExtensions.swift
diff --git a/Tests/JSONSessionTests/JSONSessionTests.swift b/Tests/JSONSessionTests/JSONSessionTests.swift

Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@`
`6`	`6`	`import Foundation`
`7`	`7`
`8`	`8`	`/// Something that resolves to a path to a REST resource.`
`9`		`-public protocol ResourceResolver {`
`10`		`- func path(in session: Session) -> String`
	`9`	`+public protocol ResourceResolver: Sendable {`
	`10`	`+ /// Relative path for this resource.`
	`11`	`+ var path: String { get }`
`11`	`12`	`}`