Centralize serverErrorCode wire constants in CloudKitServerErrorCode.

Share raw string, status, and summary via a single catalog used by both CloudKitError init and serverErrorDetail, and fix MemberImportVisibility CI failures in the ServerErrorCodes tests.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: leogdion

Sources/MistKit/CloudKitService/CloudKitError+ServerErrorCode.swift

@@ -42,40 +42,47 @@ extension CloudKitError {
   /// models a CloudKit `serverErrorCode`; `nil` for all other cases.
   ///
   /// The switch is deliberately exhaustive: adding a case to ``CloudKitError``
-  /// stops compiling here until the new case is classified.
-  // swiftlint:disable:next cyclomatic_complexity function_body_length
+  /// stops compiling here until the new case is classified. Wire strings and
+  /// status numbers come from ``CloudKitServerErrorCode``'s catalog — never
+  /// inlined here.
+  // swiftlint:disable:next cyclomatic_complexity
   internal var serverErrorDetail: ServerErrorCodeDetail? {
     switch self {
     case .accessDenied(let reason):
-      return Self.detail("ACCESS_DENIED", 403, "access denied", reason)
+      return ServerErrorCodeDetail(code: .accessDenied, reason: reason)
     case .atomicFailure(let reason):
-      return Self.detail("ATOMIC_ERROR", 400, "atomic batch failure", reason)
+      return ServerErrorCodeDetail(code: .atomicError, reason: reason)
     case .authenticationFailed(let reason):
-      return Self.detail("AUTHENTICATION_FAILED", 401, "authentication failed", reason)
+      return ServerErrorCodeDetail(code: .authenticationFailed, reason: reason)
     case .authenticationRequired(let reason):
-      return Self.detail("AUTHENTICATION_REQUIRED", 421, "authentication required", reason)
+      return ServerErrorCodeDetail(code: .authenticationRequired, reason: reason)
     case .badRequest(let reason):
-      return Self.detail("BAD_REQUEST", 400, "bad request", reason)
+      return ServerErrorCodeDetail(code: .badRequest, reason: reason)
     case .conflict(let reason):
-      return Self.detail("CONFLICT", 409, "conflict", reason)
+      return ServerErrorCodeDetail(code: .conflict, reason: reason)
     case .exists(let reason):
-      return Self.detail("EXISTS", 409, "already exists", reason)
+      return ServerErrorCodeDetail(code: .exists, reason: reason)
     case .internalServerError(let reason):
-      return Self.detail("INTERNAL_ERROR", 500, "internal server error", reason)
+      return ServerErrorCodeDetail(code: .internalError, reason: reason)
     case .notFound(let reason):
-      return Self.detail("NOT_FOUND", 404, "not found", reason)
+      return ServerErrorCodeDetail(code: .notFound, reason: reason)
     case .quotaExceeded(let reason, _):
-      return Self.detail("QUOTA_EXCEEDED", 413, "quota exceeded", reason)
+      return ServerErrorCodeDetail(code: .quotaExceeded, reason: reason)
     case .throttled(let reason):
-      return Self.detail("THROTTLED", 429, "throttled", reason)
+      return ServerErrorCodeDetail(code: .throttled, reason: reason)
     case .tryAgainLater(let reason):
-      return Self.detail("TRY_AGAIN_LATER", 503, "try again later", reason)
+      return ServerErrorCodeDetail(code: .tryAgainLater, reason: reason)
     case .validatingReferenceError(let reason):
-      return Self.detail("VALIDATING_REFERENCE_ERROR", 412, "reference validation error", reason)
+      return ServerErrorCodeDetail(code: .validatingReferenceError, reason: reason)
     case .zoneNotFound(let reason):
-      return Self.detail("ZONE_NOT_FOUND", 404, "zone not found", reason)
+      return ServerErrorCodeDetail(code: .zoneNotFound, reason: reason)
     case .unknownServerError(let code, let statusCode, let reason):
-      return Self.detail(code, statusCode, "unrecognized server error", reason)
+      return ServerErrorCodeDetail(
+        code: code,
+        statusCode: statusCode,
+        summary: ServerErrorCodeDetail.unrecognizedSummary,
+        reason: reason
+      )
     case .httpError, .httpErrorWithDetails, .httpErrorWithRawResponse, .invalidResponse,
       .incompleteResponse, .conversionFailed, .recordOperationFailed,
       .subscriptionOperationFailed, .subscriptionLikelyDuplicate, .underlyingError,
@@ -92,7 +99,7 @@ extension CloudKitError {
   ///   ``CloudKitError/httpErrorWithDetails(statusCode:reason:)``, preserving
   ///   the server `reason`.
   /// - Each of the fourteen codes documented in `openapi.yaml` becomes its own
-  ///   dedicated case.
+  ///   dedicated case, looked up via ``CloudKitServerErrorCode``'s dictionary.
   /// - Anything else becomes
   ///   ``CloudKitError/unknownServerError(code:statusCode:reason:)`` so a code
   ///   Apple adds after this release still reaches the caller intact.
@@ -101,56 +108,62 @@ extension CloudKitError {
   ///   - code: The raw `serverErrorCode` string from the failure body.
   ///   - statusCode: The HTTP status the failure arrived with.
   ///   - reason: The server-supplied `reason`, when present.
-  // swiftlint:disable:next cyclomatic_complexity
   internal init(serverErrorCode code: String?, statusCode: Int, reason: String?) {
     guard let code else {
       self = .httpErrorWithDetails(statusCode: statusCode, reason: reason)
       return
     }
-    switch code {
-    case "ACCESS_DENIED":
-      self = .accessDenied(reason: reason)
-    case "ATOMIC_ERROR":
-      self = .atomicFailure(reason: reason)
-    case "AUTHENTICATION_FAILED":
-      self = .authenticationFailed(reason: reason)
-    case "AUTHENTICATION_REQUIRED":
-      self = .authenticationRequired(reason: reason)
-    case "BAD_REQUEST":
-      self = .badRequest(reason: reason)
-    case "CONFLICT":
-      self = .conflict(reason: reason)
-    case "EXISTS":
-      self = .exists(reason: reason)
-    case "INTERNAL_ERROR":
-      self = .internalServerError(reason: reason)
-    case "NOT_FOUND":
-      self = .notFound(reason: reason)
-    case "QUOTA_EXCEEDED":
-      // `hint` is enriched later by the calling operation's catch block, which
-      // is the only place that can see the local request state.
-      self = .quotaExceeded(reason: reason, hint: nil)
-    case "THROTTLED":
-      self = .throttled(reason: reason)
-    case "TRY_AGAIN_LATER":
-      self = .tryAgainLater(reason: reason)
-    case "VALIDATING_REFERENCE_ERROR":
-      self = .validatingReferenceError(reason: reason)
-    case "ZONE_NOT_FOUND":
-      self = .zoneNotFound(reason: reason)
-    default:
-      self = .unknownServerError(code: code, statusCode: statusCode, reason: reason)
-    }
+    // Dictionary lookup in `CloudKitServerErrorCode.init(rawValue:)` — no
+    // string switch here. Map the typed enum onto the dedicated case.
+    self = Self.make(
+      from: CloudKitServerErrorCode(rawValue: code),
+      statusCode: statusCode,
+      reason: reason
+    )
   }
 
-  private static func detail(
-    _ code: String,
-    _ statusCode: Int,
-    _ summary: String,
-    _ reason: String?
-  ) -> ServerErrorCodeDetail {
-    ServerErrorCodeDetail(
-      code: code, statusCode: statusCode, summary: summary, reason: reason
-    )
+  /// Builds the dedicated case for a typed ``CloudKitServerErrorCode``.
+  ///
+  /// `hint` for ``CloudKitError/quotaExceeded(reason:hint:)`` is enriched later
+  /// by the calling operation's catch block, which is the only place that can
+  /// see the local request state.
+  // swiftlint:disable:next cyclomatic_complexity
+  private static func make(
+    from code: CloudKitServerErrorCode,
+    statusCode: Int,
+    reason: String?
+  ) -> CloudKitError {
+    switch code {
+    case .accessDenied:
+      return .accessDenied(reason: reason)
+    case .atomicError:
+      return .atomicFailure(reason: reason)
+    case .authenticationFailed:
+      return .authenticationFailed(reason: reason)
+    case .authenticationRequired:
+      return .authenticationRequired(reason: reason)
+    case .badRequest:
+      return .badRequest(reason: reason)
+    case .conflict:
+      return .conflict(reason: reason)
+    case .exists:
+      return .exists(reason: reason)
+    case .internalError:
+      return .internalServerError(reason: reason)
+    case .notFound:
+      return .notFound(reason: reason)
+    case .quotaExceeded:
+      return .quotaExceeded(reason: reason, hint: nil)
+    case .throttled:
+      return .throttled(reason: reason)
+    case .tryAgainLater:
+      return .tryAgainLater(reason: reason)
+    case .validatingReferenceError:
+      return .validatingReferenceError(reason: reason)
+    case .zoneNotFound:
+      return .zoneNotFound(reason: reason)
+    case .unknown(let raw):
+      return .unknownServerError(code: raw, statusCode: statusCode, reason: reason)
+    }
   }
 }

Sources/MistKit/CloudKitService/ServerErrorCodeDetail.swift

@@ -31,8 +31,12 @@
 ///
 /// Produced by `CloudKitError.serverErrorDetail` so that a code, the HTTP
 /// status Apple documents for it, and the human summary used in error
-/// descriptions all live in exactly one place.
+/// descriptions all live in exactly one place — ``CloudKitServerErrorCode``'s
+/// catalog.
 internal struct ServerErrorCodeDetail: Sendable {
+  /// Summary used when the failure carried an unrecognized `serverErrorCode`.
+  internal static let unrecognizedSummary = "unrecognized server error"
+
   /// The raw CloudKit `serverErrorCode` string, e.g. `"ACCESS_DENIED"`.
   internal let code: String
   /// The HTTP status Apple documents for `code`.
@@ -49,4 +53,20 @@ internal struct ServerErrorCodeDetail: Sendable {
     self.summary = summary
     self.reason = reason
   }
+
+  /// Builds a detail from a known catalog entry, storing catalog constants at
+  /// initialization and attaching the server-supplied `reason`.
+  ///
+  /// Returns `nil` when `code` is ``CloudKitServerErrorCode/unknown(_:)``.
+  internal init?(code: CloudKitServerErrorCode, reason: String?) {
+    guard let entry = code.catalogEntry else {
+      return nil
+    }
+    self.init(
+      code: entry.raw,
+      statusCode: entry.statusCode,
+      summary: entry.summary,
+      reason: reason
+    )
+  }
 }

Sources/MistKit/Models/CloudKitServerErrorCode.swift

@@ -34,6 +34,10 @@
 /// codes. Mirrors CloudKit's documented `serverErrorCode` values; an
 /// ``unknown(_:)`` case carries any code not yet known to this version of
 /// MistKit so forward-compatibility never drops information.
+///
+/// Wire string, documented HTTP status, and human summary for each known code
+/// live in ``knownCatalog`` — the single source of truth used by both
+/// ``CloudKitError`` construction and ``ServerErrorCodeDetail``.
 public enum CloudKitServerErrorCode: Codable, Hashable, Sendable {
   case accessDenied
   case atomicError
@@ -52,36 +56,104 @@ public enum CloudKitServerErrorCode: Codable, Hashable, Sendable {
   /// A server error code not recognized by this version of MistKit.
   case unknown(String)
 
-  /// The known (case, raw CloudKit string) pairs — the single source of truth
-  /// for converting in both directions.
-  private static let knownPairs: [(code: CloudKitServerErrorCode, raw: String)] = [
-    (.accessDenied, "ACCESS_DENIED"),
-    (.atomicError, "ATOMIC_ERROR"),
-    (.authenticationFailed, "AUTHENTICATION_FAILED"),
-    (.authenticationRequired, "AUTHENTICATION_REQUIRED"),
-    (.badRequest, "BAD_REQUEST"),
-    (.conflict, "CONFLICT"),
-    (.exists, "EXISTS"),
-    (.internalError, "INTERNAL_ERROR"),
-    (.notFound, "NOT_FOUND"),
-    (.quotaExceeded, "QUOTA_EXCEEDED"),
-    (.throttled, "THROTTLED"),
-    (.tryAgainLater, "TRY_AGAIN_LATER"),
-    (.validatingReferenceError, "VALIDATING_REFERENCE_ERROR"),
-    (.zoneNotFound, "ZONE_NOT_FOUND"),
+  /// Catalog row for one documented CloudKit `serverErrorCode`.
+  internal struct CatalogEntry: Sendable {
+    /// The typed case this row describes.
+    internal let code: CloudKitServerErrorCode
+    /// The raw CloudKit wire string, e.g. `"ACCESS_DENIED"`.
+    internal let raw: String
+    /// The HTTP status Apple documents for `raw`.
+    internal let statusCode: Int
+    /// Lowercase human summary used in error descriptions.
+    internal let summary: String
+  }
+
+  /// The known catalog — single source of truth for raw string, status, and
+  /// summary in both directions.
+  internal static let knownCatalog: [CatalogEntry] = [
+    CatalogEntry(
+      code: .accessDenied, raw: "ACCESS_DENIED", statusCode: 403, summary: "access denied"
+    ),
+    CatalogEntry(
+      code: .atomicError, raw: "ATOMIC_ERROR", statusCode: 400, summary: "atomic batch failure"
+    ),
+    CatalogEntry(
+      code: .authenticationFailed, raw: "AUTHENTICATION_FAILED", statusCode: 401,
+      summary: "authentication failed"
+    ),
+    CatalogEntry(
+      code: .authenticationRequired, raw: "AUTHENTICATION_REQUIRED", statusCode: 421,
+      summary: "authentication required"
+    ),
+    CatalogEntry(
+      code: .badRequest, raw: "BAD_REQUEST", statusCode: 400, summary: "bad request"
+    ),
+    CatalogEntry(
+      code: .conflict, raw: "CONFLICT", statusCode: 409, summary: "conflict"
+    ),
+    CatalogEntry(
+      code: .exists, raw: "EXISTS", statusCode: 409, summary: "already exists"
+    ),
+    CatalogEntry(
+      code: .internalError, raw: "INTERNAL_ERROR", statusCode: 500, summary: "internal server error"
+    ),
+    CatalogEntry(
+      code: .notFound, raw: "NOT_FOUND", statusCode: 404, summary: "not found"
+    ),
+    CatalogEntry(
+      code: .quotaExceeded, raw: "QUOTA_EXCEEDED", statusCode: 413, summary: "quota exceeded"
+    ),
+    CatalogEntry(
+      code: .throttled, raw: "THROTTLED", statusCode: 429, summary: "throttled"
+    ),
+    CatalogEntry(
+      code: .tryAgainLater, raw: "TRY_AGAIN_LATER", statusCode: 503, summary: "try again later"
+    ),
+    CatalogEntry(
+      code: .validatingReferenceError, raw: "VALIDATING_REFERENCE_ERROR", statusCode: 412,
+      summary: "reference validation error"
+    ),
+    CatalogEntry(
+      code: .zoneNotFound, raw: "ZONE_NOT_FOUND", statusCode: 404, summary: "zone not found"
+    ),
   ]
 
+  /// Lookup from raw CloudKit string → known case.
+  private static let byRawValue: [String: CloudKitServerErrorCode] = Dictionary(
+    uniqueKeysWithValues: knownCatalog.map { ($0.raw, $0.code) }
+  )
+
+  /// Lookup from known case → catalog row.
+  private static let byCode: [CloudKitServerErrorCode: CatalogEntry] = Dictionary(
+    uniqueKeysWithValues: knownCatalog.map { ($0.code, $0) }
+  )
+
   /// The raw CloudKit string for this code (e.g. `"NOT_FOUND"`).
   public var rawValue: String {
     if case .unknown(let raw) = self {
       return raw
     }
-    return Self.knownPairs.first { $0.code == self }?.raw ?? ""
+    return Self.byCode[self]?.raw ?? ""
+  }
+
+  /// The HTTP status Apple documents for this code, or `nil` for ``unknown(_:)``.
+  public var statusCode: Int? {
+    Self.byCode[self]?.statusCode
+  }
+
+  /// Lowercase human summary for this code, or `nil` for ``unknown(_:)``.
+  public var summary: String? {
+    Self.byCode[self]?.summary
+  }
+
+  /// Catalog row for a known code, or `nil` for ``unknown(_:)``.
+  internal var catalogEntry: CatalogEntry? {
+    Self.byCode[self]
   }
 
   /// Maps a raw CloudKit string to a known case, or ``unknown(_:)``.
   public init(rawValue: String) {
-    self = Self.knownPairs.first { $0.raw == rawValue }?.code ?? .unknown(rawValue)
+    self = Self.byRawValue[rawValue] ?? .unknown(rawValue)
   }
 
   /// Decodes the code from its raw CloudKit string value.

Sources/MistKit/Models/OperationFailure.swift

@@ -92,13 +92,13 @@ public struct OperationFailure<Target: OperationFailureTarget>:
   ) {
     let serverErrorCode = ServerErrorCode(rawValue: common.serverErrorCode.rawValue)
     // The generated `OperationFailureServerErrorCode` is a closed enum mirroring
-    // the schema, so a `.unknown` here means our `knownPairs` table drifted
+    // the schema, so a `.unknown` here means our `knownCatalog` drifted
     // from the regenerated schema — assert loudly (test-overridable) while
     // still preserving the raw code for forward-compatibility in release.
     if case .unknown(let raw) = serverErrorCode {
       ConversionFailureReporter.assertionHandler(
         "Unmapped CloudKit serverErrorCode \"\(raw)\""
-          + " — update CloudKitServerErrorCode.knownPairs",
+          + " — update CloudKitServerErrorCode.knownCatalog",
         #fileID,
         #line
       )

Tests/MistKitTests/CloudKitService/ServerErrorCodes/CloudKitServiceTests.ServerErrorCodes+ForwardCompatibility.swift

@@ -27,6 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
+internal import Foundation
 internal import Testing
 
 @testable import MistKit

Tests/MistKitTests/CloudKitService/ServerErrorCodes/CloudKitServiceTests.ServerErrorCodes+Roundtrip.swift

@@ -27,6 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
+internal import Foundation
 internal import Testing
 
 @testable import MistKit