From 394ac76154cc053590f7c5c5b9dd8555784d270e Mon Sep 17 00:00:00 2001 From: leogdion Date: Wed, 26 Nov 2025 16:19:38 -0500 Subject: [PATCH] feat: add write operations, example applications, and comprehensive documentation (#129) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Second alpha release adding write capabilities, production-ready examples, and extensive CloudKit development documentation. ## New Public API Write Operations: - Add RecordOperation with factory methods (create, update, delete variants) - Add CloudKitService.modifyRecords() for batch operations - Add RecordManaging protocol with query/modify/delete methods - Add FilterBuilder and SortDescriptor for type-safe queries - Add CloudKitRecord/CloudKitRecordCollection protocols - Add convenience extensions for record operations Field Value Improvements: - Add bidirectional OpenAPI conversion (FieldValue ↔ Components.Schemas.FieldValue) - Add FieldValue convenience accessors (stringValue, int64Value, etc.) - Add memberwise initializer to CustomFieldValue - Refactor conversion logic into protocol-based initializers Error Handling: - Add CloudKitResponseType protocol for unified error extraction - Improve CloudKitError with operation-specific context - Add Sendable conformance throughout for Swift 6 ## Example Applications Bushel (Examples/Bushel/): - Production CLI tool syncing macOS restore images, Xcode, and Swift versions - Multi-source data fetching (ipsw.me, AppleDB, MESU, Mr. Macintosh) - Server-to-Server authentication with automatic key rotation - Metadata tracking and intelligent fetch throttling - Tutorial-quality logging and comprehensive documentation - CloudKit schema automation with cktool scripts Celestra (Examples/Celestra/): - RSS feed reader with scheduled CloudKit sync - Web authentication demonstration - Public database architecture for shared content - Clean reference implementation for common patterns MistDemo (Examples/MistDemo/): - Restored and updated authentication demonstration - AdaptiveTokenManager showing runtime auth switching - CloudKit JS web authentication flow with Hummingbird server - Swift 6 strict concurrency compliant ## Documentation CloudKit Reference Documentation (.claude/docs/): - CloudKit Web Services API reference (webservices.md) - CloudKit JS framework guide (cloudkitjs.md) - Schema language reference and quick guides - cktool and cktooljs command documentation - Public database architecture patterns - Data source API research and integration patterns DocC Articles (Sources/MistKit/Documentation.docc/): - OpenAPICodeGeneration.md - swift-openapi-generator setup - AbstractionLayerArchitecture.md - Modern Swift patterns and design - Updated Documentation.md with new article references Development Guides: - CLAUDE.md updates with logging, schema, and development workflows - Bushel implementation notes and CloudKit setup guides - Schema design workflow documentation ## Additional Changes - Update GitHub workflows for improved CI - Add .gitignore patterns for sensitive files - Improve log redaction patterns (MISTKIT_DISABLE_LOG_REDACTION support) - Add Array+Chunked utility for batch processing - Update devcontainer configuration ## Breaking Changes None - this release is additive only, maintaining full backward compatibility with v1.0.0-alpha.1. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/docs/QUICK_REFERENCE.md | 324 + .claude/docs/README.md | 290 + .claude/docs/SUMMARY.md | 425 + .claude/docs/cktool-full.md | 113 + .claude/docs/cktool.md | 180 + .claude/docs/cktooljs-full.md | 460 ++ .claude/docs/cktooljs.md | 147 + .../cloudkit-public-database-architecture.md | 1981 +++++ .claude/docs/cloudkit-schema-plan.md | 563 ++ .claude/docs/cloudkit-schema-reference.md | 323 + .claude/docs/cloudkitjs.md | 7318 +++++++++++++++++ .claude/docs/data-sources-api-research.md | 730 ++ .claude/docs/firmware-wiki.md | 133 + ...le-swift-log-main-documentation-logging.md | 4313 ++++++++++ ...3-documentation-swift-openapi-generator.md | 6914 ++++++++++++++++ ...t-SyndiKit-0.6.1-documentation-syndikit.md | 488 ++ .claude/docs/mobileasset-wiki.md | 182 + .../docs/protocol-extraction-continuation.md | 559 ++ .claude/docs/schema-design-workflow.md | 560 ++ .claude/docs/sosumi-cloudkit-schema-source.md | 193 + .claude/docs/webservices.md | 3181 +++++++ .devcontainer/devcontainer.json | 4 +- .../swift-6.1-nightly/devcontainer.json | 32 - .github/workflows/MistKit.yml | 5 +- .gitignore | 7 +- CLAUDE.md | 85 +- Examples/Bushel/.gitignore | 16 + Examples/Bushel/CLOUDKIT-SETUP.md | 855 ++ Examples/Bushel/CLOUDKIT_SCHEMA_SETUP.md | 285 + Examples/Bushel/IMPLEMENTATION_NOTES.md | 430 + Examples/Bushel/Package.resolved | 123 + Examples/Bushel/Package.swift | 109 + Examples/Bushel/README.md | 595 ++ .../Bushel/Scripts/setup-cloudkit-schema.sh | 162 + .../BushelImages/BushelImagesCLI.swift | 24 + .../CloudKit/BushelCloudKitError.swift | 19 + .../CloudKit/BushelCloudKitService.swift | 141 + .../CloudKit/CloudKitFieldMapping.swift | 85 + .../CloudKit/RecordManaging+Query.swift | 18 + .../BushelImages/CloudKit/SyncEngine.swift | 190 + .../BushelImages/Commands/ClearCommand.swift | 113 + .../BushelImages/Commands/ExportCommand.swift | 210 + .../BushelImages/Commands/ListCommand.swift | 100 + .../BushelImages/Commands/StatusCommand.swift | 227 + .../BushelImages/Commands/SyncCommand.swift | 202 + .../Configuration/FetchConfiguration.swift | 121 + .../DataSources/AppleDB/AppleDBEntry.swift | 23 + .../DataSources/AppleDB/AppleDBFetcher.swift | 144 + .../DataSources/AppleDB/AppleDBHashes.swift | 12 + .../DataSources/AppleDB/AppleDBLink.swift | 8 + .../DataSources/AppleDB/AppleDBSource.swift | 11 + .../DataSources/AppleDB/GitHubCommit.swift | 7 + .../AppleDB/GitHubCommitsResponse.swift | 7 + .../DataSources/AppleDB/GitHubCommitter.swift | 6 + .../DataSources/AppleDB/SignedStatus.swift | 54 + .../DataSources/DataSourceFetcher.swift | 81 + .../DataSources/DataSourcePipeline.swift | 546 ++ .../DataSources/HTTPHeaderHelpers.swift | 37 + .../DataSources/IPSWFetcher.swift | 52 + .../DataSources/MESUFetcher.swift | 82 + .../DataSources/MrMacintoshFetcher.swift | 176 + .../DataSources/SwiftVersionFetcher.swift | 69 + .../DataSources/TheAppleWiki/IPSWParser.swift | 191 + .../TheAppleWiki/Models/IPSWVersion.swift | 61 + .../TheAppleWiki/Models/WikiAPITypes.swift | 23 + .../TheAppleWiki/TheAppleWikiFetcher.swift | 48 + .../DataSources/XcodeReleasesFetcher.swift | 146 + .../Bushel/Sources/BushelImages/Logger.swift | 73 + .../Models/DataSourceMetadata.swift | 122 + .../Models/RestoreImageRecord.swift | 136 + .../Models/SwiftVersionRecord.swift | 84 + .../Models/XcodeVersionRecord.swift | 141 + Examples/Bushel/XCODE_SCHEME_SETUP.md | 258 + Examples/Bushel/schema.ckdb | 66 + Examples/Celestra/.env.example | 14 + Examples/Celestra/AI_SCHEMA_WORKFLOW.md | 1068 +++ Examples/Celestra/BUSHEL_PATTERNS.md | 656 ++ Examples/Celestra/CLOUDKIT_SCHEMA_SETUP.md | 406 + Examples/Celestra/IMPLEMENTATION_NOTES.md | 837 ++ Examples/Celestra/Package.resolved | 95 + Examples/Celestra/Package.swift | 104 + Examples/Celestra/README.md | 358 + .../Celestra/Scripts/setup-cloudkit-schema.sh | 161 + .../Celestra/Sources/Celestra/Celestra.swift | 66 + .../Celestra/Commands/AddFeedCommand.swift | 55 + .../Celestra/Commands/ClearCommand.swift | 45 + .../Celestra/Commands/UpdateCommand.swift | 304 + .../Sources/Celestra/Models/Article.swift | 164 + .../Models/BatchOperationResult.swift | 60 + .../Sources/Celestra/Models/Feed.swift | 179 + .../Celestra/Services/CelestraError.swift | 107 + .../Celestra/Services/CelestraLogger.swift | 16 + .../Services/CloudKitService+Celestra.swift | 307 + .../Celestra/Services/RSSFetcherService.swift | 182 + .../Celestra/Services/RateLimiter.swift | 78 + .../Celestra/Services/RobotsTxtService.swift | 174 + Examples/Celestra/schema.ckdb | 36 + Examples/MistDemo/.gitignore | 2 + Examples/{ => MistDemo}/Package.resolved | 87 +- Examples/MistDemo/Package.swift | 107 + .../Sources/MistDemo/MistDemo.swift | 1 + .../Sources/MistDemo/Models/AuthModels.swift | 0 .../Sources/MistDemo/Resources/index.html | 0 .../MistDemo/Utilities/AsyncChannel.swift | 8 +- .../MistDemo/Utilities/BrowserOpener.swift | 0 .../Utilities/FieldValueFormatter.swift | 2 - Examples/Package.swift | 32 - Examples/SCHEMA_QUICK_REFERENCE.md | 291 + Mintfile | 6 +- Package.resolved | 11 +- Package.swift | 3 + Scripts/convert-conversations.py | 285 + Scripts/export-conversations.sh | 163 + .../Authentication/SecureLogging.swift | 7 +- ...omFieldValue.CustomFieldValuePayload.swift | 8 +- Sources/MistKit/CustomFieldValue.swift | 16 +- Sources/MistKit/Database.swift | 15 - .../AbstractionLayerArchitecture.md | 912 ++ .../Documentation.docc/Documentation.md | 7 + .../GeneratedCodeAnalysis.md | 1140 +++ .../GeneratedCodeWorkflow.md | 1025 +++ .../OpenAPICodeGeneration.md | 543 ++ Sources/MistKit/Environment.swift | 13 - .../Extensions/FieldValue+Convenience.swift | 154 + .../OpenAPI/Components+Database.swift | 46 + .../OpenAPI/Components+Environment.swift | 44 + .../OpenAPI/Components+FieldValue.swift | 111 + .../OpenAPI/Components+Filter.swift | 39 + .../OpenAPI/Components+RecordOperation.swift | 71 + .../Extensions/OpenAPI/Components+Sort.swift | 39 + .../Extensions/RecordManaging+Generic.swift | 128 + .../RecordManaging+RecordCollection.swift | 184 + Sources/MistKit/FieldValue.swift | 51 +- Sources/MistKit/Generated/Types.swift | 25 +- Sources/MistKit/Helpers/FilterBuilder.swift | 275 + Sources/MistKit/Helpers/SortDescriptor.swift | 63 + Sources/MistKit/Logging/MistKitLogger.swift | 98 + Sources/MistKit/LoggingMiddleware.swift | 30 +- .../MistKit/Protocols/CloudKitRecord.swift | 120 + .../Protocols/CloudKitRecordCollection.swift | 62 + .../MistKit/Protocols/RecordManaging.swift | 55 + Sources/MistKit/Protocols/RecordTypeSet.swift | 79 + Sources/MistKit/PublicTypes/QueryFilter.swift | 129 + Sources/MistKit/PublicTypes/QuerySort.swift | 69 + Sources/MistKit/RecordOperation.swift | 122 + .../Service/CloudKitError+OpenAPI.swift | 66 +- Sources/MistKit/Service/CloudKitError.swift | 44 + .../Service/CloudKitResponseProcessor.swift | 124 +- .../Service/CloudKitResponseType.swift | 70 + .../Service/CloudKitService+Operations.swift | 340 +- .../CloudKitService+RecordManaging.swift | 76 + .../CloudKitService+WriteOperations.swift | 151 + Sources/MistKit/Service/CloudKitService.swift | 45 +- ...e.CustomFieldValuePayload+FieldValue.swift | 124 + .../Service/FieldValue+Components.swift | 179 + .../Operations.getCurrentUser.Output.swift | 82 + .../Service/Operations.listZones.Output.swift | 82 + .../Operations.lookupRecords.Output.swift | 82 + .../Operations.modifyRecords.Output.swift | 82 + .../Operations.queryRecords.Output.swift | 82 + .../Service/RecordFieldConverter.swift | 207 - Sources/MistKit/Service/RecordInfo.swift | 53 +- Sources/MistKit/Utilities/Array+Chunked.swift | 44 + .../NSRegularExpression+CommonPatterns.swift | 4 +- ...rToServerAuthManagerTests+ErrorTests.swift | 2 +- ...AuthManagerTests+InitializationTests.swift | 2 +- ...rverAuthManagerTests+PrivateKeyTests.swift | 5 +- ...rverAuthManagerTests+ValidationTests.swift | 2 +- ...uthenticationMiddlewareAPITokenTests.swift | 4 +- ...enticationMiddlewareTests+ErrorTests.swift | 2 +- ...nMiddlewareTests+ServerToServerTests.swift | 2 +- .../Core/CustomFieldValueTests.swift | 287 + .../FieldValueConversionTests.swift | 460 ++ .../Core/FieldValue/FieldValueTests.swift | 11 +- .../Helpers/FilterBuilderTests.swift | 255 + .../Helpers/SortDescriptorTests.swift | 81 + .../NetworkError/Recovery/RecoveryTests.swift | 4 +- .../Simulation/SimulationTests.swift | 8 +- .../NetworkError/Storage/StorageTests.swift | 2 +- .../Protocols/CloudKitRecordTests.swift | 306 + .../FieldValueConvenienceTests.swift | 207 + .../Protocols/RecordManagingTests.swift | 386 + .../PublicTypes/QueryFilterTests.swift | 327 + .../PublicTypes/QuerySortTests.swift | 100 + .../Service/CloudKitServiceQueryTests.swift | 337 + .../ConcurrentTokenRefreshBasicTests.swift | 17 +- .../ConcurrentTokenRefreshErrorTests.swift | 10 +- ...ncurrentTokenRefreshPerformanceTests.swift | 10 +- openapi.yaml | 10 +- project.yml | 6 +- 190 files changed, 52573 insertions(+), 556 deletions(-) create mode 100644 .claude/docs/QUICK_REFERENCE.md create mode 100644 .claude/docs/README.md create mode 100644 .claude/docs/SUMMARY.md create mode 100644 .claude/docs/cktool-full.md create mode 100644 .claude/docs/cktool.md create mode 100644 .claude/docs/cktooljs-full.md create mode 100644 .claude/docs/cktooljs.md create mode 100644 .claude/docs/cloudkit-public-database-architecture.md create mode 100644 .claude/docs/cloudkit-schema-plan.md create mode 100644 .claude/docs/cloudkit-schema-reference.md create mode 100644 .claude/docs/cloudkitjs.md create mode 100644 .claude/docs/data-sources-api-research.md create mode 100644 .claude/docs/firmware-wiki.md create mode 100644 .claude/docs/https_-swiftpackageindex.com-apple-swift-log-main-documentation-logging.md create mode 100644 .claude/docs/https_-swiftpackageindex.com-apple-swift-openapi-generator-1.10.3-documentation-swift-openapi-generator.md create mode 100644 .claude/docs/https_-swiftpackageindex.com-brightdigit-SyndiKit-0.6.1-documentation-syndikit.md create mode 100644 .claude/docs/mobileasset-wiki.md create mode 100644 .claude/docs/protocol-extraction-continuation.md create mode 100644 .claude/docs/schema-design-workflow.md create mode 100644 .claude/docs/sosumi-cloudkit-schema-source.md create mode 100644 .claude/docs/webservices.md delete mode 100644 .devcontainer/swift-6.1-nightly/devcontainer.json create mode 100644 Examples/Bushel/.gitignore create mode 100644 Examples/Bushel/CLOUDKIT-SETUP.md create mode 100644 Examples/Bushel/CLOUDKIT_SCHEMA_SETUP.md create mode 100644 Examples/Bushel/IMPLEMENTATION_NOTES.md create mode 100644 Examples/Bushel/Package.resolved create mode 100644 Examples/Bushel/Package.swift create mode 100644 Examples/Bushel/README.md create mode 100755 Examples/Bushel/Scripts/setup-cloudkit-schema.sh create mode 100644 Examples/Bushel/Sources/BushelImages/BushelImagesCLI.swift create mode 100644 Examples/Bushel/Sources/BushelImages/CloudKit/BushelCloudKitError.swift create mode 100644 Examples/Bushel/Sources/BushelImages/CloudKit/BushelCloudKitService.swift create mode 100644 Examples/Bushel/Sources/BushelImages/CloudKit/CloudKitFieldMapping.swift create mode 100644 Examples/Bushel/Sources/BushelImages/CloudKit/RecordManaging+Query.swift create mode 100644 Examples/Bushel/Sources/BushelImages/CloudKit/SyncEngine.swift create mode 100644 Examples/Bushel/Sources/BushelImages/Commands/ClearCommand.swift create mode 100644 Examples/Bushel/Sources/BushelImages/Commands/ExportCommand.swift create mode 100644 Examples/Bushel/Sources/BushelImages/Commands/ListCommand.swift create mode 100644 Examples/Bushel/Sources/BushelImages/Commands/StatusCommand.swift create mode 100644 Examples/Bushel/Sources/BushelImages/Commands/SyncCommand.swift create mode 100644 Examples/Bushel/Sources/BushelImages/Configuration/FetchConfiguration.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBEntry.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBFetcher.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBHashes.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBLink.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBSource.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommit.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommitsResponse.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommitter.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/SignedStatus.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/DataSourceFetcher.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/DataSourcePipeline.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/HTTPHeaderHelpers.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/IPSWFetcher.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/MESUFetcher.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/MrMacintoshFetcher.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/SwiftVersionFetcher.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/IPSWParser.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/Models/IPSWVersion.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/Models/WikiAPITypes.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/TheAppleWikiFetcher.swift create mode 100644 Examples/Bushel/Sources/BushelImages/DataSources/XcodeReleasesFetcher.swift create mode 100644 Examples/Bushel/Sources/BushelImages/Logger.swift create mode 100644 Examples/Bushel/Sources/BushelImages/Models/DataSourceMetadata.swift create mode 100644 Examples/Bushel/Sources/BushelImages/Models/RestoreImageRecord.swift create mode 100644 Examples/Bushel/Sources/BushelImages/Models/SwiftVersionRecord.swift create mode 100644 Examples/Bushel/Sources/BushelImages/Models/XcodeVersionRecord.swift create mode 100644 Examples/Bushel/XCODE_SCHEME_SETUP.md create mode 100644 Examples/Bushel/schema.ckdb create mode 100644 Examples/Celestra/.env.example create mode 100644 Examples/Celestra/AI_SCHEMA_WORKFLOW.md create mode 100644 Examples/Celestra/BUSHEL_PATTERNS.md create mode 100644 Examples/Celestra/CLOUDKIT_SCHEMA_SETUP.md create mode 100644 Examples/Celestra/IMPLEMENTATION_NOTES.md create mode 100644 Examples/Celestra/Package.resolved create mode 100644 Examples/Celestra/Package.swift create mode 100644 Examples/Celestra/README.md create mode 100755 Examples/Celestra/Scripts/setup-cloudkit-schema.sh create mode 100644 Examples/Celestra/Sources/Celestra/Celestra.swift create mode 100644 Examples/Celestra/Sources/Celestra/Commands/AddFeedCommand.swift create mode 100644 Examples/Celestra/Sources/Celestra/Commands/ClearCommand.swift create mode 100644 Examples/Celestra/Sources/Celestra/Commands/UpdateCommand.swift create mode 100644 Examples/Celestra/Sources/Celestra/Models/Article.swift create mode 100644 Examples/Celestra/Sources/Celestra/Models/BatchOperationResult.swift create mode 100644 Examples/Celestra/Sources/Celestra/Models/Feed.swift create mode 100644 Examples/Celestra/Sources/Celestra/Services/CelestraError.swift create mode 100644 Examples/Celestra/Sources/Celestra/Services/CelestraLogger.swift create mode 100644 Examples/Celestra/Sources/Celestra/Services/CloudKitService+Celestra.swift create mode 100644 Examples/Celestra/Sources/Celestra/Services/RSSFetcherService.swift create mode 100644 Examples/Celestra/Sources/Celestra/Services/RateLimiter.swift create mode 100644 Examples/Celestra/Sources/Celestra/Services/RobotsTxtService.swift create mode 100644 Examples/Celestra/schema.ckdb create mode 100644 Examples/MistDemo/.gitignore rename Examples/{ => MistDemo}/Package.resolved (73%) create mode 100644 Examples/MistDemo/Package.swift rename Examples/{ => MistDemo}/Sources/MistDemo/MistDemo.swift (99%) rename Examples/{ => MistDemo}/Sources/MistDemo/Models/AuthModels.swift (100%) rename Examples/{ => MistDemo}/Sources/MistDemo/Resources/index.html (100%) rename Examples/{ => MistDemo}/Sources/MistDemo/Utilities/AsyncChannel.swift (94%) rename Examples/{ => MistDemo}/Sources/MistDemo/Utilities/BrowserOpener.swift (100%) rename Examples/{ => MistDemo}/Sources/MistDemo/Utilities/FieldValueFormatter.swift (96%) delete mode 100644 Examples/Package.swift create mode 100644 Examples/SCHEMA_QUICK_REFERENCE.md create mode 100755 Scripts/convert-conversations.py create mode 100755 Scripts/export-conversations.sh create mode 100644 Sources/MistKit/Documentation.docc/AbstractionLayerArchitecture.md create mode 100644 Sources/MistKit/Documentation.docc/GeneratedCodeAnalysis.md create mode 100644 Sources/MistKit/Documentation.docc/GeneratedCodeWorkflow.md create mode 100644 Sources/MistKit/Documentation.docc/OpenAPICodeGeneration.md create mode 100644 Sources/MistKit/Extensions/FieldValue+Convenience.swift create mode 100644 Sources/MistKit/Extensions/OpenAPI/Components+Database.swift create mode 100644 Sources/MistKit/Extensions/OpenAPI/Components+Environment.swift create mode 100644 Sources/MistKit/Extensions/OpenAPI/Components+FieldValue.swift create mode 100644 Sources/MistKit/Extensions/OpenAPI/Components+Filter.swift create mode 100644 Sources/MistKit/Extensions/OpenAPI/Components+RecordOperation.swift create mode 100644 Sources/MistKit/Extensions/OpenAPI/Components+Sort.swift create mode 100644 Sources/MistKit/Extensions/RecordManaging+Generic.swift create mode 100644 Sources/MistKit/Extensions/RecordManaging+RecordCollection.swift create mode 100644 Sources/MistKit/Helpers/FilterBuilder.swift create mode 100644 Sources/MistKit/Helpers/SortDescriptor.swift create mode 100644 Sources/MistKit/Logging/MistKitLogger.swift create mode 100644 Sources/MistKit/Protocols/CloudKitRecord.swift create mode 100644 Sources/MistKit/Protocols/CloudKitRecordCollection.swift create mode 100644 Sources/MistKit/Protocols/RecordManaging.swift create mode 100644 Sources/MistKit/Protocols/RecordTypeSet.swift create mode 100644 Sources/MistKit/PublicTypes/QueryFilter.swift create mode 100644 Sources/MistKit/PublicTypes/QuerySort.swift create mode 100644 Sources/MistKit/RecordOperation.swift create mode 100644 Sources/MistKit/Service/CloudKitResponseType.swift create mode 100644 Sources/MistKit/Service/CloudKitService+RecordManaging.swift create mode 100644 Sources/MistKit/Service/CloudKitService+WriteOperations.swift create mode 100644 Sources/MistKit/Service/CustomFieldValue.CustomFieldValuePayload+FieldValue.swift create mode 100644 Sources/MistKit/Service/FieldValue+Components.swift create mode 100644 Sources/MistKit/Service/Operations.getCurrentUser.Output.swift create mode 100644 Sources/MistKit/Service/Operations.listZones.Output.swift create mode 100644 Sources/MistKit/Service/Operations.lookupRecords.Output.swift create mode 100644 Sources/MistKit/Service/Operations.modifyRecords.Output.swift create mode 100644 Sources/MistKit/Service/Operations.queryRecords.Output.swift delete mode 100644 Sources/MistKit/Service/RecordFieldConverter.swift create mode 100644 Sources/MistKit/Utilities/Array+Chunked.swift create mode 100644 Tests/MistKitTests/Core/CustomFieldValueTests.swift create mode 100644 Tests/MistKitTests/Core/FieldValue/FieldValueConversionTests.swift create mode 100644 Tests/MistKitTests/Helpers/FilterBuilderTests.swift create mode 100644 Tests/MistKitTests/Helpers/SortDescriptorTests.swift create mode 100644 Tests/MistKitTests/Protocols/CloudKitRecordTests.swift create mode 100644 Tests/MistKitTests/Protocols/FieldValueConvenienceTests.swift create mode 100644 Tests/MistKitTests/Protocols/RecordManagingTests.swift create mode 100644 Tests/MistKitTests/PublicTypes/QueryFilterTests.swift create mode 100644 Tests/MistKitTests/PublicTypes/QuerySortTests.swift create mode 100644 Tests/MistKitTests/Service/CloudKitServiceQueryTests.swift diff --git a/.claude/docs/QUICK_REFERENCE.md b/.claude/docs/QUICK_REFERENCE.md new file mode 100644 index 00000000..bf663c54 --- /dev/null +++ b/.claude/docs/QUICK_REFERENCE.md @@ -0,0 +1,324 @@ +# CloudKit Quick Reference for MistKit Development + +## REST API Endpoints (webservices.md) + +### Base URL Structure +``` +https://api.apple-cloudkit.com/database/{version}/{container}/{environment}/{database}/{operation} +``` + +### Authentication + +**API Token (User-based)** +``` +Headers: + X-Apple-CloudKit-Request-KeyID: [api-token] + X-Apple-CloudKit-Request-ISO8601Date: [timestamp] + X-Apple-CloudKit-Request-SignatureV1: [signature] +``` + +**Server-to-Server Key** +``` +Headers: + X-Apple-CloudKit-Request-KeyID: [key-id] + X-Apple-CloudKit-Request-ISO8601Date: [timestamp] + X-Apple-CloudKit-Request-SignatureV1: [signature] +Body: Included in signature +``` + +### Common Endpoints + +| Operation | Path | Method | +|-----------|------|--------| +| Query Records | `/records/query` | POST | +| Modify Records | `/records/modify` | POST | +| Lookup Records | `/records/lookup` | POST | +| Record Changes | `/records/changes` | POST | +| List Zones | `/zones/list` | POST | +| Modify Zones | `/zones/modify` | POST | +| Current User | `/users/current` | GET | +| Upload Asset | `/assets/upload` | POST | + +### Request Format (POST endpoints) +```json +{ + "operations": [ + { + "operationType": "create", + "record": { + "recordType": "Article", + "fields": { + "title": { + "value": "Hello World" + } + } + } + } + ] +} +``` + +### Response Format +```json +{ + "records": [ + { + "recordName": "unique-id", + "recordType": "Article", + "fields": { + "title": { + "value": "Hello World" + } + }, + "created": { + "timestamp": 1234567890, + "userRecordName": "_user-id" + }, + "modified": { + "timestamp": 1234567890, + "userRecordName": "_user-id" + }, + "recordChangeTag": "etag-value" + } + ] +} +``` + +### Error Response +```json +{ + "serverErrorCode": "INVALID_ARGUMENTS", + "reason": "Detailed error message", + "uuid": "request-id" +} +``` + +--- + +## CloudKit Field Types (webservices.md) + +| Type | Description | Example | +|------|-------------|---------| +| `STRING` | Text string | `{"value": "Hello"}` | +| `INT64` | Integer | `{"value": 42}` | +| `DOUBLE` | Floating point | `{"value": 3.14}` | +| `BYTES` | Binary data | `{"value": "base64..."}` | +| `DATE` | Timestamp | `{"value": 1234567890000}` | +| `LOCATION` | Coordinates | `{"value": {"latitude": 37.7, "longitude": -122.4}}` | +| `REFERENCE` | Record ref | `{"value": {"recordName": "id", "action": "NONE"}}` | +| `ASSET` | File reference | `{"value": {"fileChecksum": "...", "size": 1024, "downloadURL": "..."}}` | +| `STRING_LIST` | Array of strings | `{"value": ["a", "b"]}` | +| `INT64_LIST` | Array of ints | `{"value": [1, 2, 3]}` | +| `DOUBLE_LIST` | Array of doubles | `{"value": [1.1, 2.2]}` | +| `DATE_LIST` | Array of dates | `{"value": [123, 456]}` | +| `LOCATION_LIST` | Array of locations | `{"value": [{"latitude": ...}, ...]}` | +| `REFERENCE_LIST` | Array of refs | `{"value": [{"recordName": "id1"}, ...]}` | + +--- + +## Query Filters (cloudkitjs.md adapted) + +### Filter Comparators +- `EQUALS`, `NOT_EQUALS` +- `LESS_THAN`, `LESS_THAN_OR_EQUALS` +- `GREATER_THAN`, `GREATER_THAN_OR_EQUALS` +- `IN`, `NOT_IN` +- `BEGINS_WITH`, `NOT_BEGINS_WITH` +- `CONTAINS_ALL_TOKENS` +- `LIST_CONTAINS`, `NOT_LIST_CONTAINS` + +### Query Structure +```json +{ + "query": { + "recordType": "Article", + "filterBy": [ + { + "comparator": "EQUALS", + "fieldName": "status", + "fieldValue": {"value": "published"} + } + ], + "sortBy": [ + { + "fieldName": "createdAt", + "ascending": false + } + ] + }, + "zoneID": { + "zoneName": "_defaultZone" + }, + "resultsLimit": 100 +} +``` + +--- + +## Swift Testing Patterns (testing-enablinganddisabling.md) + +### Basic Test +```swift +@Test("Description of what is tested") +func testFeature() async throws { + let result = await someAsyncOperation() + #expect(result == expectedValue) +} +``` + +### Parameterized Test +```swift +@Test("Validate multiple inputs", arguments: [1, 2, 3, 4, 5]) +func testWithParameter(value: Int) { + #expect(value > 0) +} +``` + +### Conditional Tests +```swift +@Test("Only run on macOS", .enabled(if: Platform.current == .macOS)) +func macOSTest() { } + +@Test("Skip when feature disabled", .disabled("Feature not ready")) +func disabledTest() { } +``` + +### Async Expectations +```swift +@Test func testAsync() async throws { + let result = try await apiCall() + #expect(result.status == .success) + #expect(result.data != nil) +} +``` + +### Required Values (halts on nil) +```swift +@Test func testRequired() throws { + let value = try #require(optionalValue) // Stops if nil + #expect(value.count > 0) +} +``` + +### Known Issues +```swift +@Test("Test with known bug", .bug(id: "12345")) +func testWithBug() { + // Test that tracks a known issue +} +``` + +### Test Suites +```swift +@Suite("Feature X Tests") +struct FeatureXTests { + @Test func testA() { } + @Test func testB() { } +} +``` + +--- + +## MistKit Type Mapping + +### CloudKit → Swift + +| CloudKit Type | Swift Type | +|---------------|------------| +| `STRING` | `String` | +| `INT64` | `Int` | +| `DOUBLE` | `Double` | +| `BYTES` | `Data` | +| `DATE` | `Date` (milliseconds since epoch) | +| `LOCATION` | `CLLocationCoordinate2D` or custom struct | +| `REFERENCE` | Custom `CKReference` struct | +| `ASSET` | Custom `CKAsset` struct with URL | +| `*_LIST` | `[T]` arrays | + +### Swift API Design Patterns + +**Container Access** +```swift +let container = CloudKitService.container(identifier: "...") +let database = container.publicDatabase +``` + +**Record Operations** +```swift +// Create +let record = CKRecord(type: "Article") +record["title"] = "Hello" +try await database.save(record) + +// Query +let query = CKQuery(recordType: "Article", predicate: ...) +let results = try await database.perform(query) + +// Modify +record["title"] = "Updated" +try await database.save(record) +``` + +**Async Sequences for Pagination** +```swift +for try await record in database.records(matching: query) { + process(record) +} +``` + +--- + +## Common Error Codes (webservices.md) + +| Code | Meaning | Action | +|------|---------|--------| +| `AUTHENTICATION_REQUIRED` | Not authenticated | Obtain web auth token | +| `INVALID_ARGUMENTS` | Bad request data | Check request format | +| `NOT_FOUND` | Record doesn't exist | Handle gracefully | +| `CONFLICT` | Record changed | Resolve conflict | +| `ATOMIC_ERROR` | Batch partially failed | Check individual results | +| `ZONE_NOT_FOUND` | Zone doesn't exist | Create zone first | +| `THROTTLED` | Rate limited | Implement backoff | +| `INTERNAL_ERROR` | Server error | Retry with backoff | + +--- + +## Authentication Flow + +### User Authentication (API Token) +1. Call `/tokens/create` with API token +2. Receive `webAuthToken` +3. Include in subsequent requests +4. Token expires after 1 hour +5. Refresh before expiry + +### Server-to-Server +1. Generate key pair +2. Upload public key to CloudKit Dashboard +3. Sign requests with private key +4. Include signature in headers + +--- + +## Development Checklist + +### Before implementing an endpoint: +- [ ] Check `webservices.md` for exact endpoint path and parameters +- [ ] Review `cloudkitjs.md` for operation semantics +- [ ] Design Swift types matching CloudKit structures +- [ ] Plan async/await API surface +- [ ] Consider error handling paths + +### Before writing tests: +- [ ] Review `testing-enablinganddisabling.md` for patterns +- [ ] Use `@Test` macro, not XCTest +- [ ] Use `#expect()` and `#require()` for assertions +- [ ] Test async code with `async throws` +- [ ] Consider parameterized tests for multiple cases + +### Code review: +- [ ] All types are `Sendable` +- [ ] All network calls use `async/await` +- [ ] Errors conform to `LocalizedError` +- [ ] Public APIs have tests +- [ ] Swift Testing patterns used correctly diff --git a/.claude/docs/README.md b/.claude/docs/README.md new file mode 100644 index 00000000..76419618 --- /dev/null +++ b/.claude/docs/README.md @@ -0,0 +1,290 @@ +# CloudKit Documentation Reference + +This directory contains Apple's official documentation for CloudKit Web Services, CloudKit JS, and Swift Testing, downloaded for offline reference during MistKit development. + +## File Overview + +### webservices.md (289 KB) +**Source**: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/ + +**Primary Use**: REST API implementation reference for MistKit's core functionality + +**Key Topics**: +- **Authentication**: API tokens, server-to-server keys, web auth tokens +- **Request Composition**: URL structure, headers, request/response formats +- **Endpoints**: + - Records: `/records/query`, `/records/modify`, `/records/lookup`, `/records/changes` + - Zones: `/zones/list`, `/zones/lookup`, `/zones/modify`, `/zones/changes` + - Subscriptions: `/subscriptions/*` + - Users: `/users/current`, `/users/discover`, `/users/lookup/contacts` + - Assets: `/assets/upload` + - Tokens: `/tokens/create`, `/tokens/register` +- **Data Types**: Record dictionaries, field types, references, assets, locations +- **Error Handling**: Error response formats and codes + +**When to Consult**: +- Implementing any CloudKit REST API endpoint +- Understanding request/response formats +- Implementing authentication mechanisms +- Working with CloudKit-specific data types +- Debugging API responses and errors + +--- + +### cloudkitjs.md (188 KB) +**Source**: https://developer.apple.com/documentation/cloudkitjs + +**Primary Use**: Understanding CloudKit concepts and data structures (adapted to Swift) + +**Key Topics**: +- **Configuration**: Container setup, authentication flows +- **Core Classes**: + - `CloudKit.Container`: Container access, authentication + - `CloudKit.Database`: Database operations (public/private/shared) + - `CloudKit.Record*`: Record operations and responses + - `CloudKit.RecordZone*`: Zone management + - `CloudKit.Subscription*`: Subscription handling + - `CloudKit.Notification*`: Push notification types +- **Operations**: + - Query operations with filters and sorting + - Batch operations for records + - Zone management + - Subscription management + - User discovery + - Sharing records +- **Response Objects**: All response types and their properties +- **Error Handling**: `CKError` structure and error types + +**When to Consult**: +- Designing Swift types that mirror CloudKit structures +- Understanding CloudKit operation flows +- Implementing query builders +- Working with subscriptions and notifications +- Understanding CloudKit error handling patterns +- Comparing JS API patterns to REST API + +--- + +### testing-enablinganddisabling.md (126 KB) +**Source**: https://developer.apple.com/documentation/testing/enablinganddisabling + +**Primary Use**: Writing modern Swift tests for MistKit + +**Key Topics**: +- **Test Definition**: `@Test` macro for test functions +- **Test Organization**: `@Suite` for grouping tests +- **Conditional Testing**: `.enabled(if:)`, `.disabled()` traits +- **Parameterization**: Testing with collections of inputs +- **Async Testing**: `async`/`await` test support +- **Expectations**: `#expect()`, `#require()` macros +- **Migration**: Converting from XCTest to Swift Testing +- **Tags**: Categorizing tests with tags +- **Known Issues**: `.bug()` trait for tracking known failures +- **Parallelization**: Serial vs parallel execution + +**When to Consult**: +- Writing new test functions +- Setting up test suites +- Implementing parameterized tests +- Testing async/await code +- Migrating from XCTest +- Organizing test execution + +--- + +### swift-openapi-generator.md (235 KB) +**Source**: https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator + +**Primary Use**: Code generation configuration and troubleshooting + +**Key Topics**: +- **Generator Configuration**: YAML config options, naming strategies (defensive vs idiomatic), access modifiers +- **Type Overrides**: Replacing generated types with custom implementations (e.g., Foundation.UUID) +- **Document Filtering**: Generating subsets by operations, paths, or tags +- **Middleware System**: ClientMiddleware for auth, logging, retry logic +- **Transport Protocols**: ClientTransport abstraction, URLSession integration +- **Content Types**: JSON, multipart, URL-encoded, plain text, binary, streaming +- **Event Streams**: JSON Lines, JSON Sequence, Server-sent Events helpers +- **API Stability**: Understanding breaking vs non-breaking changes +- **Naming Strategies**: Defensive (safe) vs idiomatic (Swift-style) identifier mapping +- **Code Generation Modes**: Build plugin vs manual CLI invocation + +**When to Consult**: +- Configuring `openapi-generator-config.yaml` settings +- Setting up custom type overrides for CloudKit types +- Implementing authentication or logging middleware +- Understanding generated code structure and evolution +- Troubleshooting "Decl has a package access level" errors +- Filtering large OpenAPI specs for specific operations +- Working with streaming responses or multipart uploads + +--- + +### cktool.md / cktool-full.md +**Source**: https://developer.apple.com/icloud/ck-tool/ + +**Primary Use**: CloudKit command-line tool for schema and data management + +**Files**: +- `cktool.md` - Curated summary with command examples +- `cktool-full.md` - Complete Apple documentation + +**Key Topics**: +- **Authentication**: Management tokens, user tokens, Keychain storage +- **Schema Management**: + - Reset development schema to production + - Export schema to `.ckdb` files + - Import schema from files to development +- **Data Commands**: + - Query records with filters + - Create records with JSON field definitions +- **Automation**: CI/CD integration, test data seeding +- **Token Management**: Saving and managing CloudKit tokens + +**When to Consult**: +- Setting up development environments with CloudKit schemas +- Exporting/importing schemas for version control +- Automating schema deployment in CI/CD pipelines +- Seeding test data for MistKit integration tests +- Resetting development databases +- Understanding CloudKit Management API workflows + +--- + +### cktooljs.md / cktooljs-full.md +**Source**: https://developer.apple.com/documentation/cktooljs/ +**Version**: CKTool JS 1.2.15+ + +**Primary Use**: JavaScript library for CloudKit management operations + +**Files**: +- `cktooljs.md` - Curated summary with key information +- `cktooljs-full.md` - Complete Apple documentation (41 pages) + +**Key Topics**: +- **Core Modules**: + - `@apple/cktool.database` - CloudKit types and operations + - `@apple/cktool.target.nodejs` - Node.js configuration + - `@apple/cktool.target.browser` - Browser configuration +- **Capabilities**: + - Deploy schemas to Sandbox databases + - Seed databases with test data + - Restore Sandbox to production settings + - Create automated integration test scripts +- **API Components**: + - PromisesApi and CancellablePromise + - Configuration for server communication + - Container and ContainersResponse structures + - Error handling framework + +**When to Consult**: +- Building JavaScript-based CloudKit automation tools +- Creating CI/CD pipelines with Node.js +- Understanding CloudKit Management API from JS perspective +- Automating schema deployment programmatically +- Building developer tooling for CloudKit workflows +- Comparing management API patterns across platforms + +--- + +## Quick Reference: When to Use Each Doc + +### Implementing Core API Functionality +→ **webservices.md**: Authoritative source for all REST endpoints + +### Designing Type Systems +→ **cloudkitjs.md**: Model CloudKit's data structures in Swift + +### Configuring Code Generation +→ **swift-openapi-generator.md**: OpenAPI generator setup and troubleshooting + +### Writing Tests +→ **testing-enablinganddisabling.md**: Modern Swift Testing patterns + +### Schema Management & Automation +→ **cktool.md**: Native command-line tool for schema and data operations +→ **cktooljs.md**: JavaScript library for programmatic management + +--- + +## Integration with MistKit Development + +### Architecture Decisions +When designing MistKit's API surface: +1. Start with **webservices.md** for REST API capabilities +2. Reference **cloudkitjs.md** for ergonomic API design patterns +3. Adapt CloudKit JS patterns to Swift idioms (async/await, Result builders, etc.) + +### Implementation Workflow +1. **Plan**: Review endpoint in `webservices.md` +2. **Design**: Check `cloudkitjs.md` for conceptual patterns +3. **Implement**: Write Swift code with async/await +4. **Test**: Use patterns from `testing-enablinganddisabling.md` + +### Data Type Mapping +- CloudKit types → Swift types +- Reference **webservices.md** for wire format +- Reference **cloudkitjs.md** for semantic meaning + +--- + +## Common Patterns + +### Authentication Flow +1. **webservices.md** → Request signing, token formats +2. **cloudkitjs.md** → Authentication state management +3. **cktool.md** → Management token setup and storage + +### Record Operations +1. **webservices.md** → `/records/modify` endpoint structure +2. **cloudkitjs.md** → `Database.saveRecords()` operation flow +3. **cktool.md** → Creating test records via CLI + +### Query Operations +1. **webservices.md** → `/records/query` request format +2. **cloudkitjs.md** → Query filters, sort descriptors, pagination +3. **cktool.md** → Query filters via command-line + +### Error Handling +1. **webservices.md** → HTTP status codes, error response format +2. **cloudkitjs.md** → `CKError` codes and retry logic +3. **cktooljs.md** → Error handling in management operations + +### Development Workflows +1. **cktool.md** → Export/import schemas for version control +2. **cktooljs.md** → Programmatic schema deployment and automation +3. **webservices.md** → Understanding underlying API operations + +--- + +## Documentation Ecosystem Map + +``` +CloudKit Development & Operations +├── Runtime APIs (Application Level) +│ ├── webservices.md ────────── REST API reference +│ ├── cloudkitjs.md ─────────── JS SDK for web apps +│ └── MistKit ───────────────── Swift implementation +│ +├── Management APIs (Development Level) +│ ├── cktool.md ─────────────── Native CLI tool (Xcode) +│ └── cktooljs.md ───────────── JS library for automation +│ +├── Code Generation +│ └── swift-openapi-generator.md ─ Generate Swift from OpenAPI +│ +└── Testing + └── testing-enablinganddisabling.md ─ Swift Testing framework +``` + +## Notes + +- These docs are from Apple's official documentation and community sources +- Most content downloaded via llm.codes and filtered for relevance +- Last updated: November 4, 2025 +- Corresponds to: + - CloudKit Web Services (archived) + - CloudKit JS 1.0+ + - Swift Testing (Swift 6.0+) + - cktool (Xcode 13+) + - CKTool JS (latest) diff --git a/.claude/docs/SUMMARY.md b/.claude/docs/SUMMARY.md new file mode 100644 index 00000000..aa1e0abc --- /dev/null +++ b/.claude/docs/SUMMARY.md @@ -0,0 +1,425 @@ +# Documentation Summary + +## Overview + +This directory contains three comprehensive Apple documentation files for MistKit development: + +1. **webservices.md** (289 KB) - CloudKit Web Services REST API Reference +2. **cloudkitjs.md** (188 KB) - CloudKit JS Framework Documentation +3. **testing-enablinganddisabling.md** (126 KB) - Swift Testing Framework Guide + +--- + +## webservices.md - CloudKit Web Services REST API + +**Source**: Apple's CloudKit Web Services Reference (Archived Documentation) + +### What It Covers + +#### Authentication & Security +- **API Token Authentication**: For web/client apps requiring user authentication + - Creating API tokens in CloudKit Dashboard + - Generating web authentication tokens + - Token lifecycle and refresh patterns + - Request signing with HMAC-SHA256 + +- **Server-to-Server Keys**: For backend/admin operations + - Certificate generation and key management + - Request authentication flow + - Signature computation + +#### Request Composition +- Base URL structure: `https://api.apple-cloudkit.com/database/1/{container}/{env}/{db}/{operation}` +- HTTP methods and headers +- Request body formats +- Response structures +- Error handling + +#### Core Endpoints + +**Records API** +- `POST /records/query` - Query records with filters and sorting +- `POST /records/modify` - Create, update, replace, delete records (batch) +- `POST /records/lookup` - Fetch specific records by ID +- `POST /records/changes` - Fetch incremental changes + +**Zones API** +- `POST /zones/list` - List all zones +- `POST /zones/lookup` - Fetch specific zones +- `POST /zones/modify` - Create, update, delete zones +- `POST /zones/changes` - Fetch zone changes + +**Subscriptions API** +- `POST /subscriptions/list` - List all subscriptions +- `POST /subscriptions/lookup` - Fetch specific subscriptions +- `POST /subscriptions/modify` - Create, update, delete subscriptions + +**Users API** +- `GET /users/current` - Get current authenticated user +- `POST /users/discover` - Discover users by email/phone +- `POST /users/lookup/contacts` - Lookup users from contacts +- `POST /users/lookup/email` - Lookup by email address +- `POST /users/lookup/phone` - Lookup by phone number + +**Assets API** +- `POST /assets/upload` - Upload binary assets +- Asset download URLs in record responses + +**Tokens API** +- `POST /tokens/create` - Create web auth token +- `POST /tokens/register` - Register for push notifications + +#### Data Types & Field Types + +**Basic Types** +- `STRING`, `INT64`, `DOUBLE`, `BYTES`, `DATE` + +**Complex Types** +- `LOCATION` - Latitude/longitude coordinates +- `REFERENCE` - References to other records (with delete actions) +- `ASSET` - File attachments with metadata + +**List Types** +- `STRING_LIST`, `INT64_LIST`, `DOUBLE_LIST`, `DATE_LIST` +- `LOCATION_LIST`, `REFERENCE_LIST` + +#### Error Handling +- Error response format +- Common error codes: + - `AUTHENTICATION_REQUIRED` + - `INVALID_ARGUMENTS` + - `NOT_FOUND` + - `CONFLICT` (for record changes) + - `ATOMIC_ERROR` (for batch operations) + - `ZONE_NOT_FOUND` + - `THROTTLED` + - `INTERNAL_ERROR` + +### Key Implementation Patterns + +1. **Batch Operations**: All modify operations support atomic batches +2. **Change Tracking**: Server sync tokens for incremental updates +3. **Conflict Resolution**: Record change tags (ETags) for optimistic locking +4. **Pagination**: Continuation markers for large result sets + +--- + +## cloudkitjs.md - CloudKit JS Framework + +**Source**: Apple's CloudKit JS Documentation (Current) + +### What It Covers + +#### Configuration & Setup +- Embedding CloudKit JS in web pages +- Container configuration with API tokens +- Environment selection (development/production) +- Authentication flows + +#### Core Classes + +**CloudKit Namespace** +- Configuration methods +- Global constants and enumerations +- Container access + +**CloudKit.Container** +- `publicCloudDatabase` - Access public database +- `privateCloudDatabase` - Access private database (requires auth) +- `sharedCloudDatabase` - Access shared database +- User authentication methods +- User discovery operations +- Share acceptance + +**CloudKit.Database** +- **Record Operations**: + - `saveRecords()` - Save/update records + - `fetchRecords()` - Fetch by record IDs + - `deleteRecords()` - Delete records + - `performQuery()` - Query with filters + - `newRecordsBatch()` - Batch builder + +- **Zone Operations**: + - `fetchAllRecordZones()` - List all zones + - `fetchRecordZones()` - Fetch specific zones + - `saveRecordZones()` - Create/update zones + - `deleteRecordZones()` - Delete zones + +- **Subscription Operations**: + - `fetchAllSubscriptions()` - List subscriptions + - `fetchSubscriptions()` - Fetch specific subscriptions + - `saveSubscriptions()` - Create/update subscriptions + - `deleteSubscriptions()` - Delete subscriptions + +- **Change Tracking**: + - `fetchDatabaseChanges()` - Database-level changes + - `fetchRecordZoneChanges()` - Zone-level changes + +#### Query System + +**Filter Comparators** +- Equality: `EQUALS`, `NOT_EQUALS` +- Comparison: `LESS_THAN`, `GREATER_THAN`, etc. +- String: `BEGINS_WITH`, `CONTAINS_ALL_TOKENS` +- List: `IN`, `LIST_CONTAINS` + +**Sort Descriptors** +- Field name +- Ascending/descending order + +**Pagination** +- `resultsLimit` for page size +- `continuationMarker` for next page + +#### Response Objects + +**CloudKit.Response** (base class) +- `isSuccess` - Operation status +- `hasErrors` - Error indication + +**CloudKit.RecordsResponse** +- `records` - Array of fetched records +- `errors` - Array of errors (by record) + +**CloudKit.QueryResponse** +- `records` - Query results +- `moreComing` - Has more pages +- `continuationMarker` - Token for next page + +**CloudKit.RecordsBatchBuilder** +- Fluent API for batch operations +- `create()`, `update()`, `replace()`, `delete()` +- `commit()` to execute + +**CloudKit.DatabaseChangesResponse** +- Changed zones since sync token +- New sync token + +**CloudKit.RecordZoneChangesResponse** +- Changed records in zones +- Deleted record IDs +- New sync tokens per zone + +#### Notification Types + +**CloudKit.Notification** (base) +- Notification ID and type +- Subscription ID + +**CloudKit.QueryNotification** +- Record change details +- Query subscription results + +**CloudKit.RecordZoneNotification** +- Zone change notifications + +#### Error Handling + +**CloudKit.CKError** +- `ckErrorCode` - CloudKit error code +- `isServerError` - Server vs client error +- `serverErrorCode` - Detailed server error +- Retry suggestions + +### Key Concepts + +1. **Databases**: Public (unauthenticated), Private (user), Shared (shared with user) +2. **Zones**: Logical groupings in private/shared databases (default zone always exists) +3. **Subscriptions**: Push notifications for record/zone changes +4. **Change Tracking**: Sync tokens for efficient synchronization +5. **Sharing**: Records can be shared between users + +--- + +## testing-enablinganddisabling.md - Swift Testing Framework + +**Source**: Apple's Swift Testing Documentation (Swift 6.0+) + +### What It Covers + +#### Test Definition + +**@Test Macro** +```swift +@Test("Display name") +func testFunction() async throws { } +``` +- No naming conventions required +- Can be defined anywhere (not just in classes) +- Supports async/await and throwing +- Can have custom display names + +**@Suite Macro** +```swift +@Suite("Feature Tests") +struct FeatureTests { + @Test func testA() { } + @Test func testB() { } +} +``` +- Groups related tests +- Uses Swift's type system +- Can nest suites +- Shares setup/teardown + +#### Test Traits + +**Conditional Execution** +- `.enabled(if: condition)` - Run only if true +- `.disabled()` - Never run +- `.disabled(if: condition)` - Skip if true +- `.disabled("Reason")` - Skip with explanation + +**Time Limits** +- `.timeLimit(.seconds(10))` - Fail if exceeds duration +- `.timeLimit(.minutes(1))` + +**Tags** +- `.tags(.critical)` - Categorize tests +- `.tags(.slow, .integration)` - Multiple tags +- Run specific tags from command line + +**Bug Tracking** +- `.bug("URL")` - Link to bug report +- `.bug(id: "12345")` - Bug number +- Associates tests with known issues + +**Parallelization** +- `.serialized` - Force serial execution +- Default is parallel in-process + +#### Test Parameterization + +**Single Collection** +```swift +@Test(arguments: [1, 2, 3, 4, 5]) +func validate(value: Int) { } +``` + +**Multiple Collections** +```swift +@Test(arguments: ["a", "b"], [1, 2]) +func combine(letter: String, number: Int) { } +``` + +**Zipped Collections** +```swift +@Test(arguments: zip(["a", "b"], [1, 2])) +func paired(letter: String, number: Int) { } +``` + +**Custom Arguments** +```swift +struct TestCase: CustomTestStringConvertible { + let input: String + let expected: Int +} + +@Test(arguments: [ + TestCase(input: "hello", expected: 5), + TestCase(input: "world", expected: 5) +]) +func validate(testCase: TestCase) { } +``` + +#### Expectations + +**#expect() - Continue on failure** +```swift +#expect(value == expected) +#expect(array.count > 0) +#expect(string.contains("test")) +``` + +**#require() - Stop on failure** +```swift +let value = try #require(optionalValue) // Stops if nil +#expect(value.isValid) +``` + +**Error Checking** +```swift +#expect(throws: MyError.invalid) { + try someOperation() +} +``` + +**Async Expectations** +```swift +await #expect { + try await asyncOperation() + return true +} +``` + +#### Migration from XCTest + +| XCTest | Swift Testing | +|--------|---------------| +| `class XCTestCase` | `@Suite struct` or `@Test func` | +| `func testFoo()` | `@Test func foo()` | +| `setUp()` | `init()` | +| `tearDown()` | `deinit` | +| `setUpWithError()` | `init() throws` | +| `tearDownWithError()` | N/A (use defer) | +| `XCTAssertEqual` | `#expect(a == b)` | +| `XCTAssertTrue` | `#expect(value)` | +| `XCTAssertNil` | `#expect(value == nil)` | +| `XCTUnwrap` | `try #require(value)` | +| `XCTAssertThrowsError` | `#expect(throws:)` | +| `addTeardownBlock` | `defer { }` | +| `continueAfterFailure` | `#expect()` (always continues) | + +#### Running Tests + +**Swift Package Manager** +```bash +swift test # Run all +swift test --filter TestName # Run specific +swift test --parallel # Parallel execution +``` + +**Xcode** +- Test navigator shows all `@Test` functions +- Run button next to each test +- Test report shows parameterized cases + +--- + +## How to Use These Docs Together + +### Implementing a Feature + +1. **Design Phase** + - Read `cloudkitjs.md` to understand operation semantics + - Check `webservices.md` for exact REST endpoint details + - Plan Swift API surface + +2. **Implementation Phase** + - Use `webservices.md` for request/response formats + - Map CloudKit types to Swift types + - Implement async/await patterns + - Add error handling + +3. **Testing Phase** + - Use `testing-enablinganddisabling.md` for test patterns + - Write parameterized tests for edge cases + - Test async operations + - Handle error paths + +### Example: Implementing Record Query + +1. **cloudkitjs.md** → Understand `Database.performQuery()` operation +2. **webservices.md** → Get exact POST `/records/query` format +3. Implement Swift async function +4. **testing-enablinganddisabling.md** → Write parameterized tests + +--- + +## Quick Navigation + +- **Need endpoint details?** → `webservices.md` +- **Need CloudKit concepts?** → `cloudkitjs.md` +- **Need test patterns?** → `testing-enablinganddisabling.md` +- **Need quick reference?** → `QUICK_REFERENCE.md` +- **Need integration guide?** → `README.md` diff --git a/.claude/docs/cktool-full.md b/.claude/docs/cktool-full.md new file mode 100644 index 00000000..62da0ff7 --- /dev/null +++ b/.claude/docs/cktool-full.md @@ -0,0 +1,113 @@ + + +# https://developer.apple.com/icloud/ck-tool/ + +View in English + +# Using cktool + +### Before you begin + +- You'll need to be a current member of the Apple Developer Program or the Apple Developer Enterprise Program in order to use `cktool`. +- Understand the concepts of Authentication, as described in Automating CloudKit Development. +- Generate a CloudKit Management Token from the CloudKit Console by choosing the Settings section for your user account. Save this token, as it will not be visible again. + +### Installing the application + +By default, `cktool` is distributed with Xcode starting with Xcode 13, which is available on the Mac App Store. + +### General usage + +`cktool` is stateless and passes all operations to the CloudKit Management API in single operations. A full list of supported operations is available from the `help` command or the `man` pages: + +xcrun cktool --help +OVERVIEW: CloudKit Command Line Tool + +-h, --help Show help information. + +SUBCOMMANDS: ... + +### Authenticating `cktool` to CloudKit + +`cktool` supports both management and user tokens, and will store them securely in Mac Keychain. You can add a token using the `save-token` command, which will launch CloudKit Console for copying of the appropriate token after prompting for information from the user: + +xcrun cktool save-token \ +--type [management | user] + +#### Issuing Schema Management commands + +Schema Management commands require the Management Token to be provided. Once provided, `cktool` can perform the following commands: + +**Reset development schema.** This allows you to revert the development database to the current production definition. + +xcrun cktool reset-schema \ +--team-id [TEAM-ID] \ +--container-id [CONTAINER] + +**Export schema file.** This allows you to save an existing CloudKit Database schema definition to a file, which can be kept alongside the related source code: + +xcrun cktool export-schema \ +--team-id [TEAM-ID] \ +--container-id [CONTAINER] \ +--environment [development | production] \ +[--output-file schema.ckdb] + +**Import schema file.** This applies a file-based schema definition against the development database for testing. + +xcrun cktool import-schema \ +--team-id [TEAM-ID] \ +--container-id [CONTAINER] \ +--environment development \ +--file schema.ckdb + +### Issuing data commands + +When a user token is available, `cktool` can access public and private databases on behalf of the user. This can be used for fetching data and inserting new records prior to integration tests. Note that due to the short lifespan of the user token, frequent interactive authentication may be required. + +Querying records can be performed with the `query-records` command. Note that queries without filters require the `___recordID` to have a `Queryable` index applied, as do fields specified in the optional `--filters` argument: + +xcrun cktool query-records \ +--team-id [TEAMID] \ +--container-id [CONTAINER] \ +--zone-name [ZONE_NAME] \ +--database-type [public | private] \ +--environment [development | production] \ +--record-type [RECORD_TYPE] \ +[--filters [FILTER_1] [FILTER_2]] + +Where `FILTER_1` is in the form `"[FIELD_NAME] [OPERATOR] [VALUE]"`, for example `"lastname == Appleseed"`. + +Inserting data is accomplished with the `create-record` command: + +xcrun cktool create-record \ +--team-id [TEAM_ID] \ +--container-id [CONTAINER] \ +--zone-name [ZONE_NAME] \ +--database-type [public | private] \ +--environment [development | production] \ +--record-type [RECORD_TYPE] \ +[--fields-json [FIELDS_JSON]] + +Where `FIELDS_JSON` is a JSON representation of the fields to set in the record. For example: + +'{ +"firstName": { +"type": "stringType", +"value": "Johnny" +}, +"lastName": { +"type": "stringType", +"value": "Appleseed" +} +}' + +--- + diff --git a/.claude/docs/cktool.md b/.claude/docs/cktool.md new file mode 100644 index 00000000..f3c0bb21 --- /dev/null +++ b/.claude/docs/cktool.md @@ -0,0 +1,180 @@ +# Using cktool (Summary) + +**Source**: https://developer.apple.com/icloud/ck-tool/ +**Downloaded**: November 4, 2025 +**Full Documentation**: See `cktool-full.md` for complete Apple documentation + +## Overview + +`cktool` is a command-line tool distributed with Xcode (starting with Xcode 13) that provides direct access to CloudKit Management APIs. It enables schema management, data operations, and automation tasks for CloudKit development. + +## Before You Begin + +- You'll need to be a current member of the Apple Developer Program or the Apple Developer Enterprise Program in order to use `cktool`. +- Understand the concepts of Authentication, as described in Automating CloudKit Development. +- Generate a CloudKit Management Token from the CloudKit Console by choosing the Settings section for your user account. Save this token, as it will not be visible again. + +## Installing the Application + +By default, `cktool` is distributed with Xcode starting with Xcode 13, which is available on the Mac App Store. + +## General Usage + +`cktool` is stateless and passes all operations to the CloudKit Management API in single operations. A full list of supported operations is available from the `help` command or the `man` pages: + +```bash +xcrun cktool --help +``` + +Output: +``` +OVERVIEW: CloudKit Command Line Tool + +-h, --help Show help information. + +SUBCOMMANDS: ... +``` + +## Authenticating `cktool` to CloudKit + +`cktool` supports both management and user tokens, and will store them securely in Mac Keychain. You can add a token using the `save-token` command, which will launch CloudKit Console for copying of the appropriate token after prompting for information from the user: + +```bash +xcrun cktool save-token \ + --type [management | user] +``` + +## Schema Management Commands + +Schema Management commands require the Management Token to be provided. Once provided, `cktool` can perform the following commands: + +### Reset Development Schema + +This allows you to revert the development database to the current production definition. + +```bash +xcrun cktool reset-schema \ + --team-id [TEAM-ID] \ + --container-id [CONTAINER] +``` + +### Export Schema File + +This allows you to save an existing CloudKit Database schema definition to a file, which can be kept alongside the related source code: + +```bash +xcrun cktool export-schema \ + --team-id [TEAM-ID] \ + --container-id [CONTAINER] \ + --environment [development | production] \ + [--output-file schema.ckdb] +``` + +### Import Schema File + +This applies a file-based schema definition against the development database for testing. + +```bash +xcrun cktool import-schema \ + --team-id [TEAM-ID] \ + --container-id [CONTAINER] \ + --environment development \ + --file schema.ckdb +``` + +## Data Commands + +When a user token is available, `cktool` can access public and private databases on behalf of the user. This can be used for fetching data and inserting new records prior to integration tests. Note that due to the short lifespan of the user token, frequent interactive authentication may be required. + +### Query Records + +Querying records can be performed with the `query-records` command. Note that queries without filters require the `___recordID` to have a `Queryable` index applied, as do fields specified in the optional `--filters` argument: + +```bash +xcrun cktool query-records \ + --team-id [TEAMID] \ + --container-id [CONTAINER] \ + --zone-name [ZONE_NAME] \ + --database-type [public | private] \ + --environment [development | production] \ + --record-type [RECORD_TYPE] \ + [--filters [FILTER_1] [FILTER_2]] +``` + +Where `FILTER_1` is in the form `"[FIELD_NAME] [OPERATOR] [VALUE]"`, for example `"lastname == Appleseed"`. + +### Create Records + +Inserting data is accomplished with the `create-record` command: + +```bash +xcrun cktool create-record \ + --team-id [TEAM_ID] \ + --container-id [CONTAINER] \ + --zone-name [ZONE_NAME] \ + --database-type [public | private] \ + --environment [development | production] \ + --record-type [RECORD_TYPE] \ + [--fields-json [FIELDS_JSON]] +``` + +Where `FIELDS_JSON` is a JSON representation of the fields to set in the record. For example: + +```json +{ + "firstName": { + "type": "stringType", + "value": "Johnny" + }, + "lastName": { + "type": "stringType", + "value": "Appleseed" + } +} +``` + +## When to Consult This Documentation + +- Setting up CloudKit schemas for development +- Exporting/importing schemas for version control +- Automating schema deployment in CI/CD pipelines +- Seeding test data for integration tests +- Resetting development environments +- Understanding CloudKit Management API capabilities + +## Relation to MistKit + +`cktool` operates at the management/development level, while MistKit operates at the runtime application level: + +- **cktool**: Schema management, data seeding for tests, development workflows +- **MistKit**: Application runtime data operations, end-user interactions + +Understanding `cktool` helps when: +- Setting up test environments for MistKit applications +- Creating reproducible CloudKit schemas +- Building CI/CD pipelines for MistKit-based projects +- Debugging schema-related issues during development + +## Common Workflows + +### Development Setup +1. Export production schema: `xcrun cktool export-schema --environment production` +2. Import to development: `xcrun cktool import-schema --environment development` +3. Seed test data: `xcrun cktool create-record` (multiple times) + +### CI/CD Integration +1. Store `schema.ckdb` in version control +2. Import schema in CI: `xcrun cktool import-schema` +3. Run MistKit integration tests against seeded data + +### Resetting Development Environment +1. Reset schema: `xcrun cktool reset-schema` +2. Re-import custom schema if needed +3. Re-seed test data + +## Related Documentation + +See also: +- `cktooljs.md` - JavaScript library for CloudKit management +- `webservices.md` - CloudKit Web Services REST API reference +- `cloudkitjs.md` - CloudKit JS SDK for web applications diff --git a/.claude/docs/cktooljs-full.md b/.claude/docs/cktooljs-full.md new file mode 100644 index 00000000..3793095f --- /dev/null +++ b/.claude/docs/cktooljs-full.md @@ -0,0 +1,460 @@ + + +# https://developer.apple.com/documentation/cktooljs/ + +Framework + +# CKTool JS + +Manage your CloudKit containers and databases from JavaScript. + +CKTool JS 1.2.15+ + +## Overview + +CKTool JS gives you access to features provided in the CloudKit Console API, facilitating CloudKit setup operations for local development and integration testing. It’s a JavaScript client library alternative to the macOS `cktool` command-line utility distributed with Xcode. To learn more about `cktool`, see Automating CloudKit Development. + +With this library, you can: + +- Apply a CloudKit schema file to Sandbox databases (for more information about CloudKit schema files, see Integrating a Text-Based Schema into Your Workflow). + +- Populate databases with test data. + +- Reset Sandbox databases to the production configuration. + +- Write scripts for your integration tests to incorporate. + +The library consists of three main modules: + +- `CKToolDatabaseModule`: This package contains all the CloudKit related types and methods, operations to fetch teams and containers for the authorized user, and utility functions and types to communicate with the CloudKit servers. This package also contains operations to work with CloudKit records. You include `@apple/cktool.database` as a dependency in your `package.json` file to access this package. + +- `CKToolNodeJsModule`: This package contains a `createConfiguration` function you use in projects intended to run in Node.js. You include `@apple/cktool.target.nodejs` as a dependency in your `package.json` file to access this package. + +- `CKToolBrowserModule`: This package contains a `createConfiguration` function for use in browser-based projects. You include `@apple/cktool.target.browser` as a dependency in your `package.json` file to access this package. + +## Topics + +### Essentials + +Integrating CloudKit access into your JavaScript automation scripts + +Configure your JavaScript project to use CKTool JS. + +### Promises API + +`PromisesApi` + +A class that exposes promise-based functions for interacting with the API. + +`CancellablePromise` + +A promise that has a function to cancel its operation. + +`CKToolDatabaseModule` + +The imported package that provides access to CloudKit containers and databases. + +### Configuration + +`Configuration` + +An object you use to hold options for communicating with the API server. + +`CKToolNodeJsModule` + +The imported package that supports using the client library within a Node.js environment. + +`CKToolBrowserModule` + +The imported package that supports using the client library within a web browser. + +### Global Structures and Enumerations + +`Container` + +Details about a CloudKit container. + +`ContainersResponse` + +An object that represents results of fetching multiple CloudKit containers. + +`CKEnvironment` + +An enumeration of container environments. + +`ContainersSortByField` + +An enumeration that indicates sorting options for retrieved containers. + +`SortDirection` + +An enumeration that indicates sorting direction when applying a custom sort. + +### Errors + +`ErrorBase` + +The base class of any error emitted by functions in the client library. + +### Classes + +`Blob` + +`File` + +--- + +# https://developer.apple.com/documentation/cktooljs + +Framework + +# CKTool JS + +Manage your CloudKit containers and databases from JavaScript. + +CKTool JS 1.2.15+ + +## Overview + +CKTool JS gives you access to features provided in the CloudKit Console API, facilitating CloudKit setup operations for local development and integration testing. It’s a JavaScript client library alternative to the macOS `cktool` command-line utility distributed with Xcode. To learn more about `cktool`, see Automating CloudKit Development. + +With this library, you can: + +- Apply a CloudKit schema file to Sandbox databases (for more information about CloudKit schema files, see Integrating a Text-Based Schema into Your Workflow). + +- Populate databases with test data. + +- Reset Sandbox databases to the production configuration. + +- Write scripts for your integration tests to incorporate. + +The library consists of three main modules: + +- `CKToolDatabaseModule`: This package contains all the CloudKit related types and methods, operations to fetch teams and containers for the authorized user, and utility functions and types to communicate with the CloudKit servers. This package also contains operations to work with CloudKit records. You include `@apple/cktool.database` as a dependency in your `package.json` file to access this package. + +- `CKToolNodeJsModule`: This package contains a `createConfiguration` function you use in projects intended to run in Node.js. You include `@apple/cktool.target.nodejs` as a dependency in your `package.json` file to access this package. + +- `CKToolBrowserModule`: This package contains a `createConfiguration` function for use in browser-based projects. You include `@apple/cktool.target.browser` as a dependency in your `package.json` file to access this package. + +## Topics + +### Essentials + +Integrating CloudKit access into your JavaScript automation scripts + +Configure your JavaScript project to use CKTool JS. + +### Promises API + +`PromisesApi` + +A class that exposes promise-based functions for interacting with the API. + +`CancellablePromise` + +A promise that has a function to cancel its operation. + +`CKToolDatabaseModule` + +The imported package that provides access to CloudKit containers and databases. + +### Configuration + +`Configuration` + +An object you use to hold options for communicating with the API server. + +`CKToolNodeJsModule` + +The imported package that supports using the client library within a Node.js environment. + +`CKToolBrowserModule` + +The imported package that supports using the client library within a web browser. + +### Global Structures and Enumerations + +`Container` + +Details about a CloudKit container. + +`ContainersResponse` + +An object that represents results of fetching multiple CloudKit containers. + +`CKEnvironment` + +An enumeration of container environments. + +`ContainersSortByField` + +An enumeration that indicates sorting options for retrieved containers. + +`SortDirection` + +An enumeration that indicates sorting direction when applying a custom sort. + +### Errors + +`ErrorBase` + +The base class of any error emitted by functions in the client library. + +### Classes + +`Blob` + +`File` + +--- + +# https://developer.apple.com/documentation/cktooljs/cktooldatabasemodule + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cktoolnodejsmodule + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cktoolnodejsmodule/createconfiguration + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cktoolbrowsermodule + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cktoolbrowsermodule/createconfiguration + + + +--- + +# https://developer.apple.com/documentation/cktooljs/integrating-cloudkit-access-into-your-javascript-automation-scripts + + + +--- + +# https://developer.apple.com/documentation/cktooljs/promisesapi + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cancellablepromise + + + +--- + +# https://developer.apple.com/documentation/cktooljs/configuration + + + +--- + +# https://developer.apple.com/documentation/cktooljs/container + + + +--- + +# https://developer.apple.com/documentation/cktooljs/containersresponse + + + +--- + +# https://developer.apple.com/documentation/cktooljs/ckenvironment + + + +--- + +# https://developer.apple.com/documentation/cktooljs/containerssortbyfield + + + +--- + +# https://developer.apple.com/documentation/cktooljs/sortdirection + + + +--- + +# https://developer.apple.com/documentation/cktooljs/errorbase + + + +--- + +# https://developer.apple.com/documentation/cktooljs/database-length-validation-and-value-errors + + + +--- + +# https://developer.apple.com/documentation/cktooljs/blob + + + +--- + +# https://developer.apple.com/documentation/cktooljs/file + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cktooldatabasemodule): + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cktoolnodejsmodule): + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cktoolnodejsmodule/createconfiguration) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cktooljs/cktoolbrowsermodule): + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cktoolbrowsermodule/createconfiguration) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cktooljs/integrating-cloudkit-access-into-your-javascript-automation-scripts) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cktooljs/promisesapi) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cancellablepromise) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cktooldatabasemodule) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/configuration) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cktoolnodejsmodule) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/cktoolbrowsermodule) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/container) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/containersresponse) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/ckenvironment) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/containerssortbyfield) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/sortdirection) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/errorbase) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/database-length-validation-and-value-errors) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cktooljs/blob) + + + +--- + +# https://developer.apple.com/documentation/cktooljs/file) + + + +--- + diff --git a/.claude/docs/cktooljs.md b/.claude/docs/cktooljs.md new file mode 100644 index 00000000..a0ee265c --- /dev/null +++ b/.claude/docs/cktooljs.md @@ -0,0 +1,147 @@ +# CKTool JS Documentation (Summary) + +**Source**: https://developer.apple.com/documentation/cktooljs/ +**Version**: CKTool JS 1.2.15+ +**Downloaded**: November 4, 2025 +**Full Documentation**: See `cktooljs-full.md` for complete Apple documentation dump + +## Overview + +CKTool JS gives you access to features provided in the CloudKit Console API, facilitating CloudKit setup operations for local development and integration testing. It's a JavaScript client library alternative to the macOS `cktool` command-line utility distributed with Xcode. + +## Key Capabilities + +With this library, you can: +- Apply a CloudKit schema file to Sandbox databases (for more information about CloudKit schema files, see "Integrating a Text-Based Schema into Your Workflow") +- Populate databases with test data +- Reset Sandbox databases to the production configuration +- Write scripts for your integration tests to incorporate + +## Core Modules + +The library consists of three main modules: + +### 1. CKToolDatabaseModule (`@apple/cktool.database`) +This package contains all the CloudKit related types and methods, operations to fetch teams and containers for the authorized user, and utility functions and types to communicate with the CloudKit servers. This package also contains operations to work with CloudKit records. You include `@apple/cktool.database` as a dependency in your `package.json` file to access this package. + +### 2. CKToolNodeJsModule (`@apple/cktool.target.nodejs`) +This package contains a `createConfiguration` function you use in projects intended to run in Node.js. You include `@apple/cktool.target.nodejs` as a dependency in your `package.json` file to access this package. + +### 3. CKToolBrowserModule (`@apple/cktool.target.browser`) +This package contains a `createConfiguration` function for use in browser-based projects. You include `@apple/cktool.target.browser` as a dependency in your `package.json` file to access this package. + +## API Topics + +### Essentials + +**Integrating CloudKit access into your JavaScript automation scripts** +- Configure your JavaScript project to use CKTool JS + +### Promises API + +**`PromisesApi`** +- A class that exposes promise-based functions for interacting with the API + +**`CancellablePromise`** +- A promise that has a function to cancel its operation + +**`CKToolDatabaseModule`** +- The imported package that provides access to CloudKit containers and databases + +### Configuration + +**`Configuration`** +- An object you use to hold options for communicating with the API server + +**`CKToolNodeJsModule`** +- The imported package that supports using the client library within a Node.js environment + +**`CKToolBrowserModule`** +- The imported package that supports using the client library within a web browser + +### Global Structures and Enumerations + +**`Container`** +- Details about a CloudKit container + +**`ContainersResponse`** +- An object that represents results of fetching multiple CloudKit containers + +**`CKEnvironment`** +- An enumeration of container environments + +**`ContainersSortByField`** +- An enumeration that indicates sorting options for retrieved containers + +**`SortDirection`** +- An enumeration that indicates sorting direction when applying a custom sort + +### Errors + +**`ErrorBase`** +- The base class of any error emitted by functions in the client library + +### Classes + +**`Blob`** +- Binary large object handling + +**`File`** +- File handling and operations + +## Installation + +The library requires npm package inclusion and configuration before use in JavaScript projects. + +```bash +npm install @apple/cktool.database +npm install @apple/cktool.target.nodejs # For Node.js +# or +npm install @apple/cktool.target.browser # For browser +``` + +## When to Consult This Documentation + +- Setting up automated CloudKit deployment pipelines +- Creating integration test environments +- Automating schema deployment to Sandbox +- Seeding test data programmatically +- Understanding CloudKit Management API capabilities +- Building developer tooling for CloudKit workflows + +## Relation to MistKit + +While MistKit provides a Swift interface to CloudKit Web Services for runtime operations, CKTool JS is focused on development-time and CI/CD tooling. Understanding CKTool JS can help when: + +- Building complementary tooling around MistKit +- Understanding the full CloudKit ecosystem +- Creating automated test environments for MistKit-based applications +- Implementing CI/CD pipelines that use both schema management (CKTool JS) and data operations (MistKit) + +## Schema Files and Workflows + +CKTool JS works with CloudKit schema files, enabling text-based schema management. This allows you to: +- Version control your CloudKit schemas +- Apply schemas programmatically during CI/CD +- Share schema definitions across teams +- Integrate schema management into automated workflows + +For more information, see Apple's documentation on: +- "Integrating a Text-Based Schema into Your Workflow" +- "Automating CloudKit Development" + +## Related Documentation + +See also: +- `cktool.md` - Native command-line tool for CloudKit management (alternative to cktooljs) +- `webservices.md` - CloudKit Web Services REST API reference (runtime operations) +- `cloudkitjs.md` - CloudKit JS SDK for web applications (runtime operations) + +## Key Differences from Other CloudKit Tools + +| Tool | Purpose | Platform | Use Case | +|------|---------|----------|----------| +| **cktooljs** | Schema management | Node.js/Browser | CI/CD, automation scripts | +| **cktool** | Schema management | macOS (Xcode) | Local development, CLI | +| **CloudKit JS** | Runtime data ops | Browser | Web applications | +| **MistKit** | Runtime data ops | Swift | Swift applications | diff --git a/.claude/docs/cloudkit-public-database-architecture.md b/.claude/docs/cloudkit-public-database-architecture.md new file mode 100644 index 00000000..a55b6769 --- /dev/null +++ b/.claude/docs/cloudkit-public-database-architecture.md @@ -0,0 +1,1981 @@ +# CloudKit Public Database Architecture for Celestara RSS Reader + +**Version**: 2.0 +**Last Updated**: 2025-11-04 +**Purpose**: Architecture overview and schema reference for CloudKit public database implementation using MistKit + +**Architecture**: Shared article cache in public database for efficiency and offline support + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Architecture Diagram](#architecture-diagram) +3. [Public Database Schema](#public-database-schema) +4. [Data Flow Patterns](#data-flow-patterns) +5. [MistKit Integration](#mistkit-integration) +6. [Implementation Considerations](#implementation-considerations) +7. [API Reference](#api-reference) + +--- + +## Overview + +### Purpose of Public Database + +The CloudKit **public database** serves as a centralized, read-mostly repository for: +- **Feed Discovery**: Community-curated RSS feed URLs for new users +- **Feed Metadata**: Analytics and quality metrics (subscriber counts, update reliability) +- **Curated Collections**: Editorial or algorithmic feed bundles +- **Category Taxonomy**: Standardized feed categorization +- **Shared Article Cache**: RSS article content pulled once and shared across all users (reduces RSS server load, enables offline reading) + +### Data Storage Architecture + +**Where does article content live?** + +| Storage Layer | What's Stored | Purpose | +|---------------|---------------|---------| +| **Public CloudKit DB** | Article CONTENT (title, body, images, author, etc.) | Shared by ALL users - fetch once, read by many | +| **Core Data (Local)** | Cached copy of articles | Offline reading on THIS device | +| **Private CloudKit DB** | User ACTIONS only (read states, stars, preferences) | Sync user's personal actions across devices | + +**Important**: Private CloudKit does NOT store article content. It only stores references to articles (e.g., "User read article with ID abc123 on Jan 1, 2025"). The actual article content is always fetched from Public CloudKit DB. + +**Example Flow**: +1. Server fetches article from RSS → saves to Public CloudKit DB +2. User's iPhone fetches article from Public CloudKit DB → saves to local Core Data +3. User reads article → saves read state (article ID + timestamp) to Private CloudKit DB +4. User's iPad syncs → gets read state from Private CloudKit DB, gets article content from Public CloudKit DB + +### Architecture Principles + +1. **Clear Separation: Content vs. User Actions** + - **Public DB**: Article CONTENT (shared by all users) - title, body, images, etc. + - **Private DB**: User ACTIONS only (read states, stars, preferences) - NO article content + - **Core Data**: Local offline cache of articles copied from Public DB + +2. **Dual-Source Article Upload (Hybrid Architecture)** + - **Primary**: CLI app (cron job on Lambda/VPS) fetches RSS and uploads to Public DB + - **Fallback**: Celestra iOS app uploads articles if missing/stale + - Benefits: Resilient (works even if server is down), community-contributed content + - All users benefit from articles uploaded by any source + +3. **Efficiency Through Sharing** + - Pull RSS content **once** per article across all users (whether by server or app) + - Store in public DB → all users read from CloudKit instead of hammering RSS servers + - Reduces bandwidth costs for RSS publishers + - Faster loading (CloudKit CDN vs slow RSS servers) + +4. **Offline-First Architecture** + - Public DB articles synced to local Core Data + - User can read offline without network + - Background sync keeps content fresh + +5. **Privacy-First** + - User subscriptions never stored in public DB + - Read states and starred articles kept private + - No cross-user tracking + - Anonymous analytics only (aggregated counts) + +--- + +## Architecture Diagram + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ RSS Feed Sources │ +│ (External RSS/Atom/JSON Feed servers on the internet) │ +└──────────────────┬─────────────────────────┬────────────────────┘ + │ │ + PRIMARY PATH │ │ FALLBACK PATH + (Server-side) │ │ (Celestra app) + │ │ + ▼ ▼ +┌────────────────────────────┐ ┌───────────────────────────────┐ +│ CLI App (Swift/Node.js) │ │ Celestra iOS App │ +│ • Cron job (every 15-30m) │ │ • If articles missing/stale │ +│ • Deployed on Lambda/VPS │ │ • Fetches RSS directly │ +│ • Fetches all feeds │ │ • Parses with SyndiKit │ +│ • Parses with SyndiKit │ │ │ +└──────────────┬─────────────┘ └────────────┬──────────────────┘ + │ │ + │ Both upload to Public DB │ + └──────────────┬───────────────┘ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Public CloudKit Database │ +│ │ +│ CKRecord: PublicFeed → Feed metadata & URLs │ +│ CKRecord: PublicArticle → Article content (SHARED) │ +│ CKRecord: FeedMetadata → Analytics & health │ +│ CKRecord: FeedCollection → Curated bundles │ +│ CKRecord: FeedCategory → Category taxonomy │ +│ │ +│ ⚠️ Articles uploaded by EITHER server OR app │ +│ All users benefit from shared cache │ +└────────────┬────────────────────────────────────────────────────┘ + │ + │ Query & Download Articles + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Core Data (Local Device) │ +│ │ +│ CDFeed → User's subscribed feeds │ +│ CDArticle → Cached article content (offline) │ +│ CDUserPreferences → App settings │ +│ │ +│ Syncs to Private CloudKit for read states & stars │ +└────────────┬────────────────────────────────────────────────────┘ + │ + │ User actions (read, star) + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Private CloudKit Database │ +│ │ +│ CKRecord: UserReadState → Which articles user read │ +│ CKRecord: UserStarred → Starred/bookmarked articles │ +│ CKRecord: UserSubscription → User's feed list │ +│ CKRecord: UserPreferences → Settings sync │ +│ │ +│ ⚠️ IMPORTANT: NO ARTICLE CONTENT STORED HERE │ +│ Only stores references (article IDs) + user actions │ +│ Syncs across user's devices │ +└─────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────┐ +│ Data Flow Patterns │ +│ │ +│ 1. Feed Discovery: Public DB → Browse feeds → Subscribe │ +│ 2. Article Ingestion: RSS → Parse → Public DB (server-side) │ +│ 3. Content Fetch: Public DB → Core Data (offline cache) │ +│ 4. User Actions: Local → Private DB (read/star states) │ +│ 5. Multi-Device Sync: Private DB ↔ User's devices │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Public Database Schema + +### Record Type: `PublicFeed` + +**Purpose**: Represents a community-discoverable RSS feed + +**Fields**: + +| Field Name | Type | Indexed | Sortable | Description | +|------------|------|---------|----------|-------------| +| `recordName` | String | ✅ | ❌ | Unique identifier (UUID) | +| `feedURL` | String | ✅ | ❌ | RSS/Atom feed URL (unique constraint) | +| `title` | String | ✅ | ✅ | Feed display name | +| `subtitle` | String | ❌ | ❌ | Feed description/tagline | +| `siteURL` | String | ❌ | ❌ | Website homepage URL | +| `imageURL` | String | ❌ | ❌ | Feed logo/icon URL | +| `category` | Reference(FeedCategory) | ✅ | ❌ | Primary category reference | +| `language` | String | ✅ | ❌ | ISO 639-1 language code (e.g., "en", "es") | +| `isFeatured` | Int64 (Boolean) | ✅ | ❌ | Editorial featured flag (1 or 0) | +| `isVerified` | Int64 (Boolean) | ✅ | ❌ | Verified/trusted source (1 or 0) | +| `qualityScore` | Double | ❌ | ✅ | Computed quality metric (0.0-100.0) | +| `subscriberCount` | Int64 | ❌ | ✅ | Number of Celestara users subscribed | +| `addedAt` | DateTime | ❌ | ✅ | When feed was added to public DB | +| `lastVerified` | DateTime | ❌ | ✅ | Last time feed was verified active | +| `updateFrequency` | Int64 | ❌ | ✅ | Average hours between updates | +| `tags` | String List | ✅ | ❌ | Searchable tags (e.g., ["swift", "ios", "apple"]) | + +**Indexes**: +- `feedURL` (unique) +- `category` + `isFeatured` +- `category` + `subscriberCount` (descending) +- `tags` + `language` + +**Security**: +- Read: World readable +- Write: Admin role only (via CloudKit Dashboard permissions) + +--- + +### Record Type: `FeedMetadata` + +**Purpose**: Analytics and health metrics for feeds + +**Fields**: + +| Field Name | Type | Indexed | Sortable | Description | +|------------|------|---------|----------|-------------| +| `recordName` | String | ✅ | ❌ | Unique identifier (UUID) | +| `feedReference` | Reference(PublicFeed) | ✅ | ❌ | Parent feed record | +| `subscriberCount` | Int64 | ❌ | ✅ | Total subscribers | +| `averageRating` | Double | ❌ | ✅ | Average user rating (0.0-5.0) | +| `ratingCount` | Int64 | ❌ | ❌ | Number of ratings | +| `lastFetchSuccess` | DateTime | ❌ | ✅ | Last successful fetch timestamp | +| `lastFetchFailure` | DateTime | ❌ | ❌ | Last failed fetch timestamp | +| `uptimePercentage` | Double | ❌ | ✅ | 30-day uptime (0.0-100.0) | +| `averageArticlesPerWeek` | Double | ❌ | ❌ | Publishing frequency | +| `healthStatus` | String | ✅ | ❌ | "healthy", "degraded", "down" | +| `lastHealthCheck` | DateTime | ❌ | ✅ | Last health verification | + +**Indexes**: +- `feedReference` (unique) +- `healthStatus` +- `uptimePercentage` (descending) + +**Security**: +- Read: World readable +- Write: Server-side process only + +--- + +### Record Type: `FeedCategory` + +**Purpose**: Hierarchical category taxonomy + +**Fields**: + +| Field Name | Type | Indexed | Sortable | Description | +|------------|------|---------|----------|-------------| +| `recordName` | String | ✅ | ❌ | Unique identifier (category slug) | +| `name` | String | ✅ | ✅ | Display name (e.g., "Technology") | +| `slug` | String | ✅ | ❌ | URL-safe identifier (e.g., "technology") | +| `icon` | String | ❌ | ❌ | SF Symbol name (e.g., "laptopcomputer") | +| `color` | String | ❌ | ❌ | Hex color code (e.g., "#007AFF") | +| `sortOrder` | Int64 | ❌ | ✅ | Display order priority | +| `parentCategory` | Reference(FeedCategory) | ✅ | ❌ | Parent category (for hierarchy) | +| `description` | String | ❌ | ❌ | Category description | + +**Predefined Categories** (matches existing `FeedCategory` enum): +- General (slug: `general`, icon: `newspaper`) +- Technology (slug: `technology`, icon: `laptopcomputer`) +- Design (slug: `design`, icon: `paintbrush`) +- Business (slug: `business`, icon: `briefcase`) +- News (slug: `news`, icon: `globe`) +- Entertainment (slug: `entertainment`, icon: `tv`) +- Science (slug: `science`, icon: `flask`) +- Health (slug: `health`, icon: `heart`) + +**Security**: +- Read: World readable +- Write: Admin role only + +--- + +### Record Type: `FeedCollection` + +**Purpose**: Curated bundles of feeds (e.g., "Best Tech Blogs", "Design Inspiration") + +**Fields**: + +| Field Name | Type | Indexed | Sortable | Description | +|------------|------|---------|----------|-------------| +| `recordName` | String | ✅ | ❌ | Unique identifier (UUID) | +| `title` | String | ✅ | ✅ | Collection display name | +| `description` | String | ❌ | ❌ | Collection description | +| `coverImageURL` | String | ❌ | ❌ | Cover art URL | +| `curatorName` | String | ❌ | ❌ | Collection creator/editor | +| `feeds` | Reference List(PublicFeed) | ❌ | ❌ | Ordered list of feed references | +| `isFeatured` | Int64 (Boolean) | ✅ | ❌ | Featured on discovery page | +| `subscriberCount` | Int64 | ❌ | ✅ | Users who imported this collection | +| `createdAt` | DateTime | ❌ | ✅ | Creation timestamp | +| `updatedAt` | DateTime | ❌ | ✅ | Last modification | +| `tags` | String List | ✅ | ❌ | Collection tags for search | + +**Indexes**: +- `isFeatured` +- `subscriberCount` (descending) +- `createdAt` (descending) + +**Security**: +- Read: World readable +- Write: Admin role only + +--- + +### Record Type: `PublicArticle` + +**Purpose**: Shared cache of RSS article content (pulled once, read by all users) + +**Fields**: + +| Field Name | Type | Indexed | Sortable | Description | +|------------|------|---------|----------|-------------| +| `recordName` | String | ✅ | ❌ | Unique identifier (content-based hash or GUID) | +| `feedReference` | Reference(PublicFeed) | ✅ | ❌ | Parent feed record | +| `guid` | String | ✅ | ❌ | Article GUID from RSS (unique per feed) | +| `title` | String | ✅ | ✅ | Article headline | +| `excerpt` | String | ❌ | ❌ | Summary/description (plain text) | +| `content` | String | ❌ | ❌ | Full article HTML content | +| `contentText` | String | ❌ | ❌ | Plain text version (for search) | +| `author` | String | ❌ | ❌ | Article author name | +| `url` | String | ✅ | ❌ | Original article URL | +| `imageURL` | String | ❌ | ❌ | Featured image URL | +| `publishedDate` | DateTime | ❌ | ✅ | Publication timestamp | +| `fetchedAt` | DateTime | ❌ | ✅ | When article was added to CloudKit | +| `expiresAt` | DateTime | ✅ | ✅ | Retention expiration (30-90 days) | +| `contentHash` | String | ✅ | ❌ | SHA-256 of content (deduplication) | +| `wordCount` | Int64 | ❌ | ❌ | Article word count | +| `estimatedReadingTime` | Int64 | ❌ | ❌ | Minutes to read (calculated) | +| `language` | String | ✅ | ❌ | ISO 639-1 language code | +| `tags` | String List | ✅ | ❌ | Article tags/categories | + +**Indexes**: +- `feedReference` + `publishedDate` (descending) — fetch latest articles for feed +- `guid` + `feedReference` (unique) — deduplication check +- `contentHash` (unique) — cross-feed deduplication +- `expiresAt` — cleanup query for expired articles +- `url` — prevent duplicate URLs + +**Security**: +- Read: World readable +- Write: Authenticated users (Celestra app can upload as fallback) + Server-side process + +**Write Strategy**: +- **Primary**: Server-side background job (MistKit) fetches and uploads articles +- **Fallback**: Celestra iOS app uploads articles if missing/stale in Public DB +- All users benefit from articles uploaded by any source + +**Retention Policy**: +- Articles auto-delete after **90 days** from `fetchedAt` +- Server-side cleanup job runs daily +- Users can manually "archive" articles to private DB for permanent storage + +**Content Limits**: +- `content` field max: 1 MB (CloudKit string limit) +- Articles larger than 1 MB truncated with "Read More" link to original URL +- Images stored as URLs (not embedded), CDN/cache on device + +**De-duplication Strategy**: +1. **Per-feed deduplication**: Check `guid` + `feedReference` +2. **Cross-feed deduplication**: Check `contentHash` (same article from multiple feeds) +3. **URL-based check**: Some feeds publish same article with different GUIDs + +--- + +## Data Flow Patterns + +### Pattern 1: Feed Discovery + +``` +User Opens Discovery Tab + │ + ▼ +┌────────────────────────┐ +│ Query Public DB │ +│ │ +│ 1. Fetch FeedCategory │◄─── Cached locally for 24h +│ records │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Query PublicFeed │ +│ │ +│ WHERE category = │ +│ selectedCategory │ +│ AND isFeatured = 1 │ +│ │ +│ SORT BY subscriberCount│ +│ LIMIT 50 │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Fetch FeedMetadata │◄─── Join on feedReference +│ for quality scores │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Display Feed List │ +│ with preview cards │ +└────────────────────────┘ +``` + +**MistKit Query Example**: +```swift +let predicate = NSPredicate( + format: "category == %@ AND isFeatured == 1", + categoryReference +) +let query = CKQuery(recordType: "PublicFeed", predicate: predicate) +query.sortDescriptors = [ + NSSortDescriptor(key: "subscriberCount", ascending: false) +] +``` + +--- + +### Pattern 2: Feed Subscription Flow + +``` +User Taps "Subscribe" on Public Feed + │ + ▼ +┌────────────────────────┐ +│ Extract feedURL from │ +│ PublicFeed record │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Fetch Feed Content │ +│ via SyndiKit │ +│ │ +│ ParsedFeed = fetch(url)│ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Save to Local DB │ +│ │ +│ CDFeed.create(from: │ +│ parsedFeed) │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Sync to Private DB │ +│ │ +│ NSPersistentCloudKit │ +│ Container handles sync │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Update Public Metadata │◄─── Async, server-side +│ │ (increment subscriberCount) +│ Via CloudKit Function │ +└────────────────────────┘ +``` + +**Key Point**: User's subscription is NEVER written to public DB. Only anonymous aggregate count incremented via server-side logic. + +--- + +### Pattern 3: Article Ingestion (Server-Side via CLI App) + +**WHO RUNS THIS**: Command-line app (cron job on AWS Lambda or VPS) - PRIMARY METHOD + +``` +Cron Job Triggers CLI App (every 15-30 min) + │ + ▼ +┌────────────────────────┐ +│ Query PublicFeed │ +│ records to fetch │ +│ │ +│ WHERE lastFetchedAt < │ +│ now - updateFreq │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ For Each Feed: │ +│ │ +│ SyndiKit Fetch │ +│ • Use ETag/If-Modified │ +│ • Parse new articles │ +│ • Extract full content │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ De-duplication Check │ +│ │ +│ 1. Check contentHash │ +│ 2. Check guid+feed │ +│ 3. Check URL │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Save to Public DB │ +│ │ +│ PublicArticle.create() │ +│ • Set expiresAt = now │ +│ + 90 days │ +│ • Calculate readTime │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Update FeedMetadata │ +│ │ +│ • lastFetchSuccess │ +│ • articleCount++ │ +│ • healthStatus │ +└────────────────────────┘ +``` + +**Key Points**: +- Server-side fetching prevents duplicate RSS requests across users +- Content stored once in public DB, accessed by all users +- Implementation: Simple command-line app (Swift or Node.js) +- Deployment: Cron job on AWS Lambda or VPS (every 15-30 min) +- Lambda benefits: Serverless, pay-per-execution, auto-scaling + +--- + +### Pattern 3b: Article Ingestion (Client-Side Fallback via Celestra) + +**WHO RUNS THIS**: Celestra iOS app (FALLBACK METHOD) + +**When**: If articles are missing from Public DB or haven't been updated by server + +``` +User Opens Feed in Celestra App + │ + ▼ +┌────────────────────────┐ +│ Query Public DB for │ +│ Recent Articles │ +│ │ +│ WHERE feedReference = │ +│ subscribed feed │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Articles Found? │ +│ │ +│ • None found? │ +│ • Last article > 24h? │ +└────────┬───────────────┘ + │ + │ YES - Articles missing/stale + ▼ +┌────────────────────────┐ +│ Celestra Fetches RSS │ +│ Directly │ +│ │ +│ SyndiKit.fetch(feedURL)│ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Check if Articles │ +│ Already Exist │ +│ │ +│ Query by guid+feed │ +└────────┬───────────────┘ + │ + │ New articles found + ▼ +┌────────────────────────┐ +│ Upload to Public DB │ +│ │ +│ CKDatabase.save( │ +│ PublicArticle │ +│ ) │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Save to Local Core │ +│ Data for Offline │ +└────────────────────────┘ +``` + +**Key Points**: +- **Celestra acts as both consumer AND contributor** to public DB +- Fills gaps when server-side process hasn't run yet or is down +- Still performs deduplication check (don't upload duplicates) +- Benefits all users (articles uploaded by one user are available to everyone) +- **CloudKit Public DB Write Permissions**: Must allow authenticated users to write PublicArticle records (not just admin/server) + +**Important for MistKit Demo**: +This client-side fallback pattern is specific to **Celestra's architecture** and won't affect the MistKit demonstration, which focuses on the server-side ingestion pattern (Pattern 3). + +--- + +### Pattern 4: User Article Sync (Client-Side) + +**WHO RUNS THIS**: User's device (iOS app) + +``` +User Opens Feed / Background Refresh + │ + ▼ +┌────────────────────────┐ +│ Load User's Subscribed │ +│ Feeds from Core Data │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Query Public DB for │ +│ New Articles │ +│ │ +│ WHERE feedReference IN │ +│ userSubscriptions │ +│ AND publishedDate > │ +│ lastSyncDate │ +│ SORT BY publishedDate │ +│ LIMIT 100 │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Download Articles │ +│ from Public DB │ +│ │ +│ Batch fetch │ +│ (50 records at a time) │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Save to Core Data │ +│ │ +│ CDArticle.bulkCreate() │ +│ • Store locally │ +│ • Enable offline read │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ User Reads Article │ +│ │ +│ Mark as read in local │ +│ Core Data │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Sync Read State to │ +│ Private CloudKit │ +│ │ +│ UserReadState record │ +│ (multi-device sync) │ +└────────────────────────┘ +``` + +**Key Points**: +- Users query public DB for articles from their subscribed feeds only +- Articles cached locally in Core Data for offline reading +- **Private CloudKit stores ONLY user actions**: + - Which articles THIS user has read (article ID + read timestamp) + - Which articles THIS user has starred (article ID + star flag) + - NOT the article content itself (content is in Public DB) +- When you switch devices, your read/star states sync, but article content comes from Public DB + +--- + +### Pattern 5: Collection Import + +``` +User Taps "Import Collection" + │ + ▼ +┌────────────────────────┐ +│ Fetch FeedCollection │ +│ record by ID │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Resolve Feed References│ +│ │ +│ feeds.forEach { ref in │ +│ fetch(PublicFeed) │ +│ } │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Show Confirmation UI │ +│ │ +│ "Import 15 feeds from │ +│ 'Best Tech Blogs'?" │ +└────────┬───────────────┘ + │ + ▼ +┌────────────────────────┐ +│ Subscribe to Each Feed │◄─── Reuses Pattern 2 +│ │ (individual subscriptions) +│ Parallel fetch with │ +│ progress indicator │ +└────────────────────────┘ +``` + +--- + +## MistKit Integration + +### MistKit Overview + +[MistKit](https://github.com/aaronpearce/MistKit) is a Swift library that simplifies CloudKit operations with: +- Type-safe record encoding/decoding +- Async/await API +- Automatic batching +- Query builders +- Subscription management + +### Record Type Definitions + +#### PublicFeed Record + +```swift +import MistKit + +struct PublicFeed: CloudKitRecordable { + static let recordType = "PublicFeed" + + var recordID: CKRecord.ID? + + // Core fields + let feedURL: URL + let title: String + let subtitle: String? + let siteURL: URL? + let imageURL: URL? + + // References + let category: CKRecord.Reference // → FeedCategory + + // Metadata + let language: String // ISO 639-1 code + let isFeatured: Bool + let isVerified: Bool + let qualityScore: Double + let subscriberCount: Int + let addedAt: Date + let lastVerified: Date + let updateFrequency: Int // Hours + let tags: [String] + + // CloudKit encoding + func encode(to record: inout CKRecord) throws { + record["feedURL"] = feedURL.absoluteString as CKRecordValue + record["title"] = title as CKRecordValue + record["subtitle"] = subtitle as CKRecordValue? + record["siteURL"] = siteURL?.absoluteString as CKRecordValue? + record["imageURL"] = imageURL?.absoluteString as CKRecordValue? + record["category"] = category + record["language"] = language as CKRecordValue + record["isFeatured"] = (isFeatured ? 1 : 0) as CKRecordValue + record["isVerified"] = (isVerified ? 1 : 0) as CKRecordValue + record["qualityScore"] = qualityScore as CKRecordValue + record["subscriberCount"] = subscriberCount as CKRecordValue + record["addedAt"] = addedAt as CKRecordValue + record["lastVerified"] = lastVerified as CKRecordValue + record["updateFrequency"] = updateFrequency as CKRecordValue + record["tags"] = tags as CKRecordValue + } + + // CloudKit decoding + init(from record: CKRecord) throws { + self.recordID = record.recordID + + guard let urlString = record["feedURL"] as? String, + let url = URL(string: urlString), + let title = record["title"] as? String else { + throw MistKitError.invalidRecord + } + + self.feedURL = url + self.title = title + self.subtitle = record["subtitle"] as? String + + if let siteURLString = record["siteURL"] as? String { + self.siteURL = URL(string: siteURLString) + } else { + self.siteURL = nil + } + + if let imageURLString = record["imageURL"] as? String { + self.imageURL = URL(string: imageURLString) + } else { + self.imageURL = nil + } + + guard let categoryRef = record["category"] as? CKRecord.Reference else { + throw MistKitError.invalidRecord + } + self.category = categoryRef + + self.language = record["language"] as? String ?? "en" + self.isFeatured = (record["isFeatured"] as? Int ?? 0) == 1 + self.isVerified = (record["isVerified"] as? Int ?? 0) == 1 + self.qualityScore = record["qualityScore"] as? Double ?? 0.0 + self.subscriberCount = record["subscriberCount"] as? Int ?? 0 + self.addedAt = record["addedAt"] as? Date ?? Date() + self.lastVerified = record["lastVerified"] as? Date ?? Date() + self.updateFrequency = record["updateFrequency"] as? Int ?? 24 + self.tags = record["tags"] as? [String] ?? [] + } +} +``` + +#### FeedCategory Record + +```swift +struct FeedCategory: CloudKitRecordable { + static let recordType = "FeedCategory" + + var recordID: CKRecord.ID? + + let name: String + let slug: String + let icon: String // SF Symbol name + let color: String // Hex code + let sortOrder: Int + let parentCategory: CKRecord.Reference? + let description: String? + + func encode(to record: inout CKRecord) throws { + record["name"] = name as CKRecordValue + record["slug"] = slug as CKRecordValue + record["icon"] = icon as CKRecordValue + record["color"] = color as CKRecordValue + record["sortOrder"] = sortOrder as CKRecordValue + record["parentCategory"] = parentCategory + record["description"] = description as CKRecordValue? + } + + init(from record: CKRecord) throws { + self.recordID = record.recordID + + guard let name = record["name"] as? String, + let slug = record["slug"] as? String else { + throw MistKitError.invalidRecord + } + + self.name = name + self.slug = slug + self.icon = record["icon"] as? String ?? "newspaper" + self.color = record["color"] as? String ?? "#007AFF" + self.sortOrder = record["sortOrder"] as? Int ?? 0 + self.parentCategory = record["parentCategory"] as? CKRecord.Reference + self.description = record["description"] as? String + } +} +``` + +#### FeedMetadata Record + +```swift +struct FeedMetadata: CloudKitRecordable { + static let recordType = "FeedMetadata" + + var recordID: CKRecord.ID? + + let feedReference: CKRecord.Reference // → PublicFeed + let subscriberCount: Int + let averageRating: Double + let ratingCount: Int + let lastFetchSuccess: Date? + let lastFetchFailure: Date? + let uptimePercentage: Double + let averageArticlesPerWeek: Double + let healthStatus: String // "healthy", "degraded", "down" + let lastHealthCheck: Date + + func encode(to record: inout CKRecord) throws { + record["feedReference"] = feedReference + record["subscriberCount"] = subscriberCount as CKRecordValue + record["averageRating"] = averageRating as CKRecordValue + record["ratingCount"] = ratingCount as CKRecordValue + record["lastFetchSuccess"] = lastFetchSuccess as CKRecordValue? + record["lastFetchFailure"] = lastFetchFailure as CKRecordValue? + record["uptimePercentage"] = uptimePercentage as CKRecordValue + record["averageArticlesPerWeek"] = averageArticlesPerWeek as CKRecordValue + record["healthStatus"] = healthStatus as CKRecordValue + record["lastHealthCheck"] = lastHealthCheck as CKRecordValue + } + + init(from record: CKRecord) throws { + self.recordID = record.recordID + + guard let feedRef = record["feedReference"] as? CKRecord.Reference else { + throw MistKitError.invalidRecord + } + + self.feedReference = feedRef + self.subscriberCount = record["subscriberCount"] as? Int ?? 0 + self.averageRating = record["averageRating"] as? Double ?? 0.0 + self.ratingCount = record["ratingCount"] as? Int ?? 0 + self.lastFetchSuccess = record["lastFetchSuccess"] as? Date + self.lastFetchFailure = record["lastFetchFailure"] as? Date + self.uptimePercentage = record["uptimePercentage"] as? Double ?? 100.0 + self.averageArticlesPerWeek = record["averageArticlesPerWeek"] as? Double ?? 0.0 + self.healthStatus = record["healthStatus"] as? String ?? "healthy" + self.lastHealthCheck = record["lastHealthCheck"] as? Date ?? Date() + } +} +``` + +#### FeedCollection Record + +```swift +struct FeedCollection: CloudKitRecordable { + static let recordType = "FeedCollection" + + var recordID: CKRecord.ID? + + let title: String + let description: String? + let coverImageURL: URL? + let curatorName: String? + let feeds: [CKRecord.Reference] // → PublicFeed list + let isFeatured: Bool + let subscriberCount: Int + let createdAt: Date + let updatedAt: Date + let tags: [String] + + func encode(to record: inout CKRecord) throws { + record["title"] = title as CKRecordValue + record["description"] = description as CKRecordValue? + record["coverImageURL"] = coverImageURL?.absoluteString as CKRecordValue? + record["curatorName"] = curatorName as CKRecordValue? + record["feeds"] = feeds as CKRecordValue + record["isFeatured"] = (isFeatured ? 1 : 0) as CKRecordValue + record["subscriberCount"] = subscriberCount as CKRecordValue + record["createdAt"] = createdAt as CKRecordValue + record["updatedAt"] = updatedAt as CKRecordValue + record["tags"] = tags as CKRecordValue + } + + init(from record: CKRecord) throws { + self.recordID = record.recordID + + guard let title = record["title"] as? String else { + throw MistKitError.invalidRecord + } + + self.title = title + self.description = record["description"] as? String + + if let imageURLString = record["coverImageURL"] as? String { + self.coverImageURL = URL(string: imageURLString) + } else { + self.coverImageURL = nil + } + + self.curatorName = record["curatorName"] as? String + self.feeds = record["feeds"] as? [CKRecord.Reference] ?? [] + self.isFeatured = (record["isFeatured"] as? Int ?? 0) == 1 + self.subscriberCount = record["subscriberCount"] as? Int ?? 0 + self.createdAt = record["createdAt"] as? Date ?? Date() + self.updatedAt = record["updatedAt"] as? Date ?? Date() + self.tags = record["tags"] as? [String] ?? [] + } +} +``` + +#### PublicArticle Record + +```swift +import MistKit +import CryptoKit + +struct PublicArticle: CloudKitRecordable { + static let recordType = "PublicArticle" + + var recordID: CKRecord.ID? + + // Core fields + let feedReference: CKRecord.Reference // → PublicFeed + let guid: String + let title: String + let excerpt: String? + let content: String? // HTML + let contentText: String? // Plain text for search + let author: String? + let url: URL + let imageURL: URL? + + // Metadata + let publishedDate: Date + let fetchedAt: Date + let expiresAt: Date + let contentHash: String // SHA-256 + let wordCount: Int + let estimatedReadingTime: Int + let language: String // ISO 639-1 + let tags: [String] + + // CloudKit encoding + func encode(to record: inout CKRecord) throws { + record["feedReference"] = feedReference + record["guid"] = guid as CKRecordValue + record["title"] = title as CKRecordValue + record["excerpt"] = excerpt as CKRecordValue? + record["content"] = content as CKRecordValue? + record["contentText"] = contentText as CKRecordValue? + record["author"] = author as CKRecordValue? + record["url"] = url.absoluteString as CKRecordValue + record["imageURL"] = imageURL?.absoluteString as CKRecordValue? + record["publishedDate"] = publishedDate as CKRecordValue + record["fetchedAt"] = fetchedAt as CKRecordValue + record["expiresAt"] = expiresAt as CKRecordValue + record["contentHash"] = contentHash as CKRecordValue + record["wordCount"] = wordCount as CKRecordValue + record["estimatedReadingTime"] = estimatedReadingTime as CKRecordValue + record["language"] = language as CKRecordValue + record["tags"] = tags as CKRecordValue + } + + // CloudKit decoding + init(from record: CKRecord) throws { + self.recordID = record.recordID + + guard let feedRef = record["feedReference"] as? CKRecord.Reference, + let guid = record["guid"] as? String, + let title = record["title"] as? String, + let urlString = record["url"] as? String, + let url = URL(string: urlString), + let publishedDate = record["publishedDate"] as? Date, + let fetchedAt = record["fetchedAt"] as? Date, + let expiresAt = record["expiresAt"] as? Date, + let contentHash = record["contentHash"] as? String else { + throw MistKitError.invalidRecord + } + + self.feedReference = feedRef + self.guid = guid + self.title = title + self.excerpt = record["excerpt"] as? String + self.content = record["content"] as? String + self.contentText = record["contentText"] as? String + self.author = record["author"] as? String + self.url = url + + if let imageURLString = record["imageURL"] as? String { + self.imageURL = URL(string: imageURLString) + } else { + self.imageURL = nil + } + + self.publishedDate = publishedDate + self.fetchedAt = fetchedAt + self.expiresAt = expiresAt + self.contentHash = contentHash + self.wordCount = record["wordCount"] as? Int ?? 0 + self.estimatedReadingTime = record["estimatedReadingTime"] as? Int ?? 1 + self.language = record["language"] as? String ?? "en" + self.tags = record["tags"] as? [String] ?? [] + } + + // Helper: Calculate content hash + static func calculateContentHash(_ content: String) -> String { + let data = Data(content.utf8) + let hash = SHA256.hash(data: data) + return hash.compactMap { String(format: "%02x", $0) }.joined() + } + + // Helper: Estimate reading time (based on 200 words/min) + static func estimateReadingTime(wordCount: Int) -> Int { + max(1, wordCount / 200) + } + + // Helper: Extract plain text from HTML + static func extractPlainText(from html: String) -> String { + // Basic HTML stripping (in production, use proper parser) + html.replacingOccurrences(of: "<[^>]+>", with: " ", options: .regularExpression) + .replacingOccurrences(of: "\\s+", with: " ", options: .regularExpression) + .trimmingCharacters(in: .whitespacesAndNewlines) + } +} +``` + +--- + +### Service Layer: PublicFeedService + +```swift +import MistKit +import CloudKit + +@MainActor +final class PublicFeedService: ObservableObject { + private let database: CKDatabase + private let cache: PublicFeedCache + + init(container: CKContainer = .default()) { + self.database = container.publicCloudDatabase + self.cache = PublicFeedCache() + } + + // MARK: - Fetch Operations + + /// Fetch featured feeds in a category + func fetchFeaturedFeeds( + category: CKRecord.Reference, + limit: Int = 50 + ) async throws -> [PublicFeed] { + // Check cache first + if let cached = cache.featuredFeeds(for: category.recordID.recordName), + !cache.isExpired(for: "featured_\(category.recordID.recordName)") { + return cached + } + + // Query CloudKit + let predicate = NSPredicate( + format: "category == %@ AND isFeatured == 1", + category + ) + let query = CKQuery(recordType: PublicFeed.recordType, predicate: predicate) + query.sortDescriptors = [ + NSSortDescriptor(key: "subscriberCount", ascending: false) + ] + + let results = try await database.records( + matching: query, + resultsLimit: limit + ) + + let feeds = try results.matchResults.compactMap { (recordID, result) -> PublicFeed? in + switch result { + case .success(let record): + return try? PublicFeed(from: record) + case .failure: + return nil + } + } + + // Cache results + cache.store(feeds, for: "featured_\(category.recordID.recordName)", ttl: 3600) + + return feeds + } + + /// Search feeds by query string + func searchFeeds( + query: String, + language: String = "en", + limit: Int = 20 + ) async throws -> [PublicFeed] { + // Search by title or tags + let predicate = NSPredicate( + format: "(title CONTAINS[cd] %@ OR ANY tags CONTAINS[cd] %@) AND language == %@", + query, query, language + ) + let ckQuery = CKQuery(recordType: PublicFeed.recordType, predicate: predicate) + ckQuery.sortDescriptors = [ + NSSortDescriptor(key: "subscriberCount", ascending: false) + ] + + let results = try await database.records( + matching: ckQuery, + resultsLimit: limit + ) + + return try results.matchResults.compactMap { (_, result) -> PublicFeed? in + switch result { + case .success(let record): + return try? PublicFeed(from: record) + case .failure: + return nil + } + } + } + + /// Fetch all categories + func fetchCategories() async throws -> [FeedCategory] { + // Check cache + if let cached = cache.categories, + !cache.isExpired(for: "categories") { + return cached + } + + let predicate = NSPredicate(value: true) // Fetch all + let query = CKQuery(recordType: FeedCategory.recordType, predicate: predicate) + query.sortDescriptors = [ + NSSortDescriptor(key: "sortOrder", ascending: true) + ] + + let results = try await database.records(matching: query) + + let categories = try results.matchResults.compactMap { (_, result) -> FeedCategory? in + switch result { + case .success(let record): + return try? FeedCategory(from: record) + case .failure: + return nil + } + } + + // Cache for 24 hours + cache.storeCategories(categories, ttl: 86400) + + return categories + } + + /// Fetch metadata for a feed + func fetchMetadata(for feedID: CKRecord.ID) async throws -> FeedMetadata? { + let reference = CKRecord.Reference(recordID: feedID, action: .none) + let predicate = NSPredicate(format: "feedReference == %@", reference) + let query = CKQuery(recordType: FeedMetadata.recordType, predicate: predicate) + + let results = try await database.records(matching: query, resultsLimit: 1) + + guard let first = results.matchResults.first else { + return nil + } + + switch first.value { + case .success(let record): + return try? FeedMetadata(from: record) + case .failure: + return nil + } + } + + /// Fetch featured collections + func fetchFeaturedCollections(limit: Int = 10) async throws -> [FeedCollection] { + let predicate = NSPredicate(format: "isFeatured == 1") + let query = CKQuery(recordType: FeedCollection.recordType, predicate: predicate) + query.sortDescriptors = [ + NSSortDescriptor(key: "subscriberCount", ascending: false) + ] + + let results = try await database.records( + matching: query, + resultsLimit: limit + ) + + return try results.matchResults.compactMap { (_, result) -> FeedCollection? in + switch result { + case .success(let record): + return try? FeedCollection(from: record) + case .failure: + return nil + } + } + } + + /// Resolve feed references in a collection + func resolveFeeds(in collection: FeedCollection) async throws -> [PublicFeed] { + let recordIDs = collection.feeds.map { $0.recordID } + + // Batch fetch all referenced feeds + let results = try await database.records(for: recordIDs) + + return try results.compactMap { (recordID, result) -> PublicFeed? in + switch result { + case .success(let record): + return try? PublicFeed(from: record) + case .failure: + return nil + } + } + } + + // MARK: - Article Operations + + /// Fetch recent articles for a feed + func fetchArticles( + for feedID: CKRecord.ID, + limit: Int = 50, + since: Date? = nil + ) async throws -> [PublicArticle] { + let reference = CKRecord.Reference(recordID: feedID, action: .none) + + let predicate: NSPredicate + if let since = since { + predicate = NSPredicate( + format: "feedReference == %@ AND publishedDate > %@", + reference, since as NSDate + ) + } else { + predicate = NSPredicate( + format: "feedReference == %@", + reference + ) + } + + let query = CKQuery(recordType: PublicArticle.recordType, predicate: predicate) + query.sortDescriptors = [ + NSSortDescriptor(key: "publishedDate", ascending: false) + ] + + let results = try await database.records( + matching: query, + resultsLimit: limit + ) + + return try results.matchResults.compactMap { (_, result) -> PublicArticle? in + switch result { + case .success(let record): + return try? PublicArticle(from: record) + case .failure: + return nil + } + } + } + + /// Fetch articles for multiple feeds (user's subscriptions) + func fetchArticles( + for feedIDs: [CKRecord.ID], + since: Date? = nil, + limit: Int = 100 + ) async throws -> [PublicArticle] { + let references = feedIDs.map { CKRecord.Reference(recordID: $0, action: .none) } + + let predicate: NSPredicate + if let since = since { + predicate = NSPredicate( + format: "feedReference IN %@ AND publishedDate > %@", + references, since as NSDate + ) + } else { + predicate = NSPredicate( + format: "feedReference IN %@", + references + ) + } + + let query = CKQuery(recordType: PublicArticle.recordType, predicate: predicate) + query.sortDescriptors = [ + NSSortDescriptor(key: "publishedDate", ascending: false) + ] + + let results = try await database.records( + matching: query, + resultsLimit: limit + ) + + return try results.matchResults.compactMap { (_, result) -> PublicArticle? in + switch result { + case .success(let record): + return try? PublicArticle(from: record) + case .failure: + return nil + } + } + } + + /// Fetch a specific article by record ID + func fetchArticle(byID recordID: CKRecord.ID) async throws -> PublicArticle? { + let record = try await database.record(for: recordID) + return try? PublicArticle(from: record) + } + + /// Search articles by keyword + func searchArticles( + query: String, + limit: Int = 20 + ) async throws -> [PublicArticle] { + // Search in title and contentText + let predicate = NSPredicate( + format: "title CONTAINS[cd] %@ OR contentText CONTAINS[cd] %@", + query, query + ) + let ckQuery = CKQuery(recordType: PublicArticle.recordType, predicate: predicate) + ckQuery.sortDescriptors = [ + NSSortDescriptor(key: "publishedDate", ascending: false) + ] + + let results = try await database.records( + matching: ckQuery, + resultsLimit: limit + ) + + return try results.matchResults.compactMap { (_, result) -> PublicArticle? in + switch result { + case .success(let record): + return try? PublicArticle(from: record) + case .failure: + return nil + } + } + } +} +``` + +--- + +### Caching Layer + +```swift +import Foundation +import CloudKit + +/// Simple in-memory cache for public database queries +final class PublicFeedCache { + private var storage: [String: CachedItem] = [:] + private let queue = DispatchQueue(label: "com.celestra.publicfeedcache") + + struct CachedItem { + let data: Any + let expiresAt: Date + } + + func store(_ data: T, for key: String, ttl: TimeInterval) { + queue.async { + let expiresAt = Date().addingTimeInterval(ttl) + self.storage[key] = CachedItem(data: data, expiresAt: expiresAt) + } + } + + func retrieve(for key: String) -> T? { + queue.sync { + guard let item = storage[key], + item.expiresAt > Date() else { + storage.removeValue(forKey: key) + return nil + } + return item.data as? T + } + } + + func isExpired(for key: String) -> Bool { + queue.sync { + guard let item = storage[key] else { return true } + return item.expiresAt <= Date() + } + } + + // Convenience accessors + + func featuredFeeds(for categoryID: String) -> [PublicFeed]? { + retrieve(for: "featured_\(categoryID)") + } + + var categories: [FeedCategory]? { + retrieve(for: "categories") + } + + func storeCategories(_ categories: [FeedCategory], ttl: TimeInterval) { + store(categories, for: "categories", ttl: ttl) + } + + func clear() { + queue.async { + self.storage.removeAll() + } + } +} +``` + +--- + +## Implementation Considerations + +### 1. Rate Limiting & Quotas + +**CloudKit Public Database Limits** (per user): +- **Requests**: 40 requests/second +- **Assets**: 200 MB/day download +- **Transfer**: 200 MB/day total + +**Mitigation Strategies**: +- Aggressive caching (TTL: 1-24 hours for most queries) +- Batch operations where possible +- Conditional requests (use `CKFetchRecordZoneChangesOperation` with change tokens) +- Pagination for large result sets + +### 2. Circuit Breaker Pattern + +Implement circuit breaker for public DB operations to handle service degradation: + +```swift +@MainActor +final class CircuitBreaker { + enum State { + case closed // Normal operation + case open // Failures threshold exceeded, reject requests + case halfOpen // Testing if service recovered + } + + private var state: State = .closed + private var failureCount = 0 + private var lastFailureTime: Date? + + private let failureThreshold = 5 + private let resetTimeout: TimeInterval = 60 + + func execute(_ operation: () async throws -> T) async throws -> T { + switch state { + case .open: + if shouldAttemptReset() { + state = .halfOpen + } else { + throw CircuitBreakerError.circuitOpen + } + + case .halfOpen: + break // Allow one test request + + case .closed: + break // Normal operation + } + + do { + let result = try await operation() + onSuccess() + return result + } catch { + onFailure(error) + throw error + } + } + + private func onSuccess() { + failureCount = 0 + state = .closed + } + + private func onFailure(_ error: Error) { + failureCount += 1 + lastFailureTime = Date() + + if failureCount >= failureThreshold { + state = .open + } + } + + private func shouldAttemptReset() -> Bool { + guard let lastFailure = lastFailureTime else { return true } + return Date().timeIntervalSince(lastFailure) >= resetTimeout + } +} + +enum CircuitBreakerError: Error { + case circuitOpen +} +``` + +**Usage in PublicFeedService**: + +```swift +private let circuitBreaker = CircuitBreaker() + +func fetchFeaturedFeeds(...) async throws -> [PublicFeed] { + try await circuitBreaker.execute { + // CloudKit query logic here + } +} +``` + +### 3. Privacy Considerations + +**✅ DO**: +- Store feed URLs, metadata, and analytics in public DB +- Use anonymous aggregate metrics (subscriber counts) +- Cache aggressively to minimize requests + +**❌ DON'T**: +- Store user subscription data in public DB +- Track individual user behavior +- Link user identities to feed subscriptions +- Store article read states publicly + +### 4. Conflict Resolution + +Public DB is primarily **read-only** for clients, so conflicts are minimal. For admin writes: + +- Use `CKModifyRecordsOperation` with `.changedKeys` save policy +- Implement optimistic locking via `modificationDate` checks +- Server-side aggregation for subscriber counts (CloudKit Functions) + +### 5. Offline Support + +```swift +final class OfflinePublicFeedManager { + private let service: PublicFeedService + private let cache: PublicFeedCache + + func fetchFeaturedFeeds( + category: CKRecord.Reference + ) async -> Result<[PublicFeed], Error> { + do { + let feeds = try await service.fetchFeaturedFeeds(category: category) + return .success(feeds) + } catch { + // Fallback to cache on network failure + if let cached = cache.featuredFeeds(for: category.recordID.recordName) { + return .success(cached) + } + return .failure(error) + } + } +} +``` + +### 6. Index Strategy + +**Critical Indexes** (configure in CloudKit Dashboard): + +**PublicFeed**: +- `QUERYABLE`: feedURL, category, isFeatured, language, tags +- `SORTABLE`: title, subscriberCount, qualityScore, addedAt + +**FeedMetadata**: +- `QUERYABLE`: feedReference, healthStatus +- `SORTABLE`: uptimePercentage, averageRating + +**FeedCategory**: +- `QUERYABLE`: slug, parentCategory +- `SORTABLE`: sortOrder, name + +**FeedCollection**: +- `QUERYABLE`: isFeatured, tags +- `SORTABLE`: subscriberCount, createdAt + +**PublicArticle**: +- `QUERYABLE`: feedReference, guid, url, contentHash, expiresAt, language, tags +- `SORTABLE`: publishedDate (descending), fetchedAt, expiresAt +- `COMPOUND`: feedReference + publishedDate (fetch feed articles), guid + feedReference (deduplication) + +### 7. RSS Content Syndication + +RSS/Atom feeds are provided by publishers for syndication purposes. Caching RSS content for improved app performance and offline reading is a common practice in RSS reader applications. Articles are attributed to their original sources and link back to the publisher's website. + +--- + +### 8. CLI App Implementation (Server-Side Fetcher) + +**Architecture Options**: + +#### Option A: AWS Lambda (Recommended for simplicity) + +**Pros**: +- Serverless (no server maintenance) +- Pay-per-execution (cost-effective for infrequent jobs) +- Auto-scaling (handles load automatically) +- Easy deployment with AWS SAM or Serverless Framework + +**Implementation**: +```bash +# Project structure +rss-fetcher-cli/ +├── Package.swift # Swift dependencies (SyndiKit, CloudKit SDK) +├── Sources/ +│ └── main.swift # Fetch feeds → Upload to CloudKit +├── template.yaml # AWS SAM template +└── scripts/ + └── deploy.sh # Deployment script +``` + +**Deployment**: +1. Package Swift CLI as Lambda layer or zip +2. Create EventBridge rule (cron: `rate(15 minutes)`) +3. Lambda invokes CLI app every 15 minutes +4. CLI fetches all PublicFeed records → downloads RSS → uploads articles + +**Costs** (estimate): +- Lambda: ~$0.01/month for 15-min intervals (2,880 invocations/month) +- CloudKit: Covered by iCloud storage (Public DB writes are free) + +#### Option B: VPS/Server with Cron + +**Pros**: +- Full control over execution environment +- No cold start delays (Lambda can have 1-2 sec delay) +- Easier debugging with logs + +**Implementation**: +```bash +# Cron job on Linux server +*/15 * * * * /usr/local/bin/rss-fetcher >> /var/log/rss-fetcher.log 2>&1 +``` + +**Costs** (estimate): +- VPS: $5-10/month (DigitalOcean, Linode) + +**Recommendation**: Start with **AWS Lambda** for simplicity and cost-effectiveness. Can migrate to VPS later if needed. + +--- + +### 9. Testing Strategy + +**Unit Tests**: +- Mock CloudKit responses +- Test PublicFeed/PublicArticle model encoding/decoding +- Validate predicate construction +- Test deduplication logic (GUID, hash, URL) + +**Integration Tests**: +- Use CloudKit Development environment +- Test query performance with realistic data volumes +- Verify cache expiration logic +- Test retention policy (article auto-deletion) + +**Load Tests**: +- Simulate concurrent user queries +- Measure cache hit rates +- Monitor quota consumption +- Test with 100,000+ article records + +--- + +## API Reference + +### PublicFeedService Methods + +#### Feed Operations + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| `fetchFeaturedFeeds` | `category`, `limit` | `[PublicFeed]` | Fetch featured feeds in category | +| `searchFeeds` | `query`, `language`, `limit` | `[PublicFeed]` | Full-text search feeds | +| `fetchCategories` | - | `[FeedCategory]` | Fetch all categories | +| `fetchMetadata` | `feedID` | `FeedMetadata?` | Get metadata for feed | +| `fetchFeaturedCollections` | `limit` | `[FeedCollection]` | Fetch featured collections | +| `resolveFeeds` | `collection` | `[PublicFeed]` | Resolve references in collection | + +#### Article Operations + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| `fetchArticles(for:limit:since:)` | `feedID`, `limit`, `since` | `[PublicArticle]` | Fetch recent articles for a feed | +| `fetchArticles(for:since:limit:)` | `feedIDs`, `since`, `limit` | `[PublicArticle]` | Fetch articles for multiple feeds | +| `fetchArticle(byID:)` | `recordID` | `PublicArticle?` | Fetch a specific article | +| `searchArticles` | `query`, `limit` | `[PublicArticle]` | Search articles by keyword | + +### Query Examples + +#### Find Top Tech Feeds + +```swift +let techCategory = CKRecord.Reference( + recordID: CKRecord.ID(recordName: "technology"), + action: .none +) + +let feeds = try await service.fetchFeaturedFeeds( + category: techCategory, + limit: 20 +) +``` + +#### Search by Tag + +```swift +let query = "swift" +let results = try await service.searchFeeds( + query: query, + language: "en", + limit: 10 +) +``` + +#### Get Feed Health Status + +```swift +let feedID = CKRecord.ID(recordName: "feed-uuid-123") +if let metadata = try await service.fetchMetadata(for: feedID) { + print("Health: \(metadata.healthStatus)") + print("Uptime: \(metadata.uptimePercentage)%") +} +``` + +#### Import Collection + +```swift +let collections = try await service.fetchFeaturedCollections(limit: 5) + +if let first = collections.first { + let feeds = try await service.resolveFeeds(in: first) + + // Subscribe to each feed + for feed in feeds { + let parsedFeed = try await syndiKitParser.fetch(feed.feedURL) + try await feedRepository.create(from: parsedFeed) + } +} +``` + +#### Fetch Recent Articles for a Feed + +```swift +let feedID = CKRecord.ID(recordName: "feed-uuid-123") + +// Fetch latest 50 articles +let articles = try await service.fetchArticles( + for: feedID, + limit: 50 +) + +// Fetch articles since last sync +let lastSync = Date().addingTimeInterval(-24 * 60 * 60) // 24h ago +let newArticles = try await service.fetchArticles( + for: feedID, + since: lastSync, + limit: 100 +) +``` + +#### Sync Articles for User's Subscriptions + +```swift +// User has subscribed to multiple feeds +let userFeedIDs = userSubscriptions.map { $0.feedRecordID } + +// Fetch latest articles from all subscribed feeds +let lastSync = UserDefaults.standard.object(forKey: "lastArticleSync") as? Date + ?? Date().addingTimeInterval(-7 * 24 * 60 * 60) // Default: 7 days ago + +let articles = try await service.fetchArticles( + for: userFeedIDs, + since: lastSync, + limit: 200 +) + +// Save to Core Data for offline reading +for article in articles { + try await articleRepository.saveFromPublicDB(article) +} + +// Update last sync timestamp +UserDefaults.standard.set(Date(), forKey: "lastArticleSync") +``` + +#### Search Articles by Keyword + +```swift +let query = "Swift 6 concurrency" +let results = try await service.searchArticles( + query: query, + limit: 20 +) + +// Display search results +for article in results { + print("\(article.title) - \(article.publishedDate)") + print(article.url) +} +``` + +--- + +## Migration Path + +### Phase 1: Schema Setup (Development Environment) +1. Configure record types in CloudKit Dashboard: + - `PublicFeed` + - `FeedCategory` + - `FeedMetadata` + - `FeedCollection` + - **`PublicArticle`** (NEW) +2. Create indexes as specified above (especially compound indexes for articles) +3. Set security roles: + - World Readable (all record types) + - Admin Write (`PublicFeed`, `FeedCategory`, `FeedCollection`) + - **Authenticated Users + Server Write** (`PublicArticle`, `FeedMetadata`) ← Celestra app needs write permission for fallback uploads + +### Phase 2: Seed Data +1. Import initial `FeedCategory` records (8 categories) +2. Curate 50-100 high-quality `PublicFeed` records +3. Generate `FeedMetadata` via server-side health checks +4. Create 3-5 editorial `FeedCollection` records +5. **Run initial RSS fetch to populate ~1,000 `PublicArticle` records** + +### Phase 3: Server-Side Infrastructure (Optional but Recommended) +1. **Build CLI app** for RSS fetching: + - Language: Swift (can share code with iOS app) or Node.js + - Uses SyndiKit for parsing + - Implements deduplication logic (contentHash, GUID, URL) + - Uploads to Public CloudKit DB +2. **Deploy as cron job**: + - **Option A**: AWS Lambda (serverless, pay-per-execution) + - Use EventBridge (CloudWatch Events) for scheduling + - Run every 15-30 minutes + - **Option B**: VPS/Server with cron + - Traditional cron job on Linux server + - More control, but requires server maintenance +3. **Implement cleanup job**: + - Delete expired articles (expiresAt < now) daily + - Keep retention at 90 days max +4. Add proper attribution to original sources in uploaded articles + +### Phase 4: App Integration (Client-Side) +1. Add MistKit dependency (`Package.swift`) +2. Implement `PublicFeedService` with caching +3. Build discovery UI (browse categories, search, collections) +4. **Implement article sync flow**: + - Background fetch articles from public DB + - Save to local Core Data for offline reading + - Sync read states to private DB +5. Add article reading UI with offline support + +### Phase 5: Monitoring & Optimization +1. CloudKit telemetry dashboard +2. Cache hit rate metrics +3. Query performance monitoring +4. Transfer bandwidth monitoring +5. Retention policy effectiveness (90-day cleanup) +6. Server-side fetch job health monitoring + +--- + +## Conclusion + +This architecture provides a **scalable, efficient, privacy-first approach** to RSS feed distribution using CloudKit's public database with shared article caching. Key design principles: + +1. **Hybrid Article Ingestion**: + - **Primary**: CLI app (cron job on AWS Lambda or VPS) fetches RSS and uploads to Public DB + - **Fallback**: Celestra iOS app uploads articles if missing/stale (resilient, community-contributed) +2. **Shared Content Efficiency**: Articles pulled once from RSS (by server OR app), cached in public DB, accessed by all users +3. **Offline-First**: Public DB → Core Data sync enables full offline reading +4. **Privacy Protection**: + - **Public DB** = article content (shared by everyone) + - **Private DB** = user actions ONLY (read states, stars) - NO article content + - **Core Data** = local offline cache +5. **Cost Optimization**: Reduces RSS server load, leverages CloudKit CDN +6. **RSS Syndication**: Standard practice for RSS readers with proper attribution +7. **MistKit Integration**: Type-safe Swift models with async/await (both server-side and client-side) + +### Architecture Summary + +``` + PRIMARY FALLBACK +RSS Feeds → CLI App (cron on Lambda/VPS) OR Celestra App (if missing/stale) + │ │ + └──────────────┬─────────────────────┘ + ▼ + Public CloudKit DB (article content - shared) + ↓ + User's Device + ↓ + Core Data (offline cache) + ↓ + Private CloudKit (user actions only: read states, stars) +``` + +**Key Points**: +- **Two upload paths**: CLI app cron job (primary) or Celestra app (fallback) +- **CLI app**: Simple command-line tool, runs every 15-30 min on Lambda or VPS +- **Private CloudKit stores ONLY user actions** (which articles read/starred), NOT article content +- **All users benefit** from articles uploaded by any source (CLI or other users) + +**Benefits**: +- 📉 **Reduced Load**: RSS servers fetched once per article (not once per user) +- ⚡ **Fast Loading**: CloudKit CDN vs slow RSS servers +- 📴 **Offline Reading**: Full articles cached locally in Core Data +- 🔒 **Privacy**: User actions stay private, content is shared +- 💰 **Efficient**: Shared storage vs per-user duplication +- 🛡️ **Resilient**: Works even if server-side process is down (app fills gaps) + +**Trade-offs**: +- 🔧 **Infrastructure**: Server-side process recommended (but app works without it via fallback) +- ⏱️ **Retention Policy**: Auto-delete after 90 days (can't archive everything) +- 🌐 **Dependency**: Users rely on public DB availability +- 📱 **Client Bandwidth**: Apps may fetch RSS directly if server hasn't updated feeds yet + +--- + +**Document Status**: ✅ Ready for Implementation + +**Critical Next Steps**: +1. Configure CloudKit schema in Dashboard (5 record types) +2. Configure write permissions: Allow authenticated users to write `PublicArticle` records +3. Add MistKit dependency to iOS app +4. Implement `PublicFeedService` with article sync +5. Implement client-side fallback: Celestra uploads articles if missing +6. Build article reading UI with offline support +7. Ensure proper attribution and links to original sources +8. **(Optional but recommended)** Build and deploy CLI app for RSS fetching: + - Write simple Swift/Node.js CLI app + - Deploy as cron job on AWS Lambda or VPS (every 15-30 min) + - Improves efficiency and reduces client bandwidth usage + +--- + +*For questions or clarifications, refer to:* +- *CloudKit documentation: https://developer.apple.com/icloud/cloudkit/* +- *MistKit GitHub: https://github.com/aaronpearce/MistKit* +- *RSS Best Practices: https://www.rssboard.org/rss-specification* diff --git a/.claude/docs/cloudkit-schema-plan.md b/.claude/docs/cloudkit-schema-plan.md new file mode 100644 index 00000000..6d4d2b16 --- /dev/null +++ b/.claude/docs/cloudkit-schema-plan.md @@ -0,0 +1,563 @@ +# CloudKit Schema Plan for Bushel & Demo App + +## Overview + +Three CloudKit record types for tracking macOS restore images, Xcode releases, and Swift versions with their compatibility relationships. Optimized for Bushel's virtualization use case and demonstrating MistKit's capabilities. + +## Record Types + +### 1. RestoreImage + +**Purpose**: macOS IPSW files for Apple Virtualization framework (VirtualMac restore images) + +**Fields**: +- `version` (String, indexed) - macOS version: "14.2.1", "15.0 Beta 3" +- `buildNumber` (String, indexed) - Build identifier: "23C71", "24A5264n" +- `releaseDate` (Date, indexed) - Official release date +- `downloadURL` (String) - Direct IPSW download link +- `fileSize` (Int64) - File size in bytes +- `sha256Hash` (String) - SHA-256 checksum for integrity verification +- `sha1Hash` (String) - SHA-1 hash (from MESU/ipsw.me for compatibility) +- `isSigned` (Boolean, indexed) - Whether Apple still signs this restore image +- `isPrerelease` (Boolean, indexed) - Beta/RC release indicator +- `source` (String) - Data source: "ipsw.me", "mrmacintosh.com", "mesu.apple.com" +- `notes` (String) - Additional metadata or release notes + +**Indexes**: +- `version` - For version lookups +- `buildNumber` - Unique identifier queries +- `releaseDate` - Chronological sorting +- `isSigned` - Filter to signed-only images +- `isPrerelease` - Filter beta vs final releases +- Compound: `(isSigned, releaseDate)` - "Latest signed releases" + +### 2. XcodeVersion + +**Purpose**: Xcode releases with macOS requirements and bundled Swift versions + +**Fields**: +- `version` (String, indexed) - Xcode version: "15.1", "15.2 Beta 3" +- `buildNumber` (String) - Build identifier: "15C65" +- `releaseDate` (Date, indexed) - Release date +- `downloadURL` (String) - Optional developer.apple.com download link +- `fileSize` (Int64) - Download size in bytes +- `isPrerelease` (Boolean, indexed) - Beta/RC indicator +- `minimumMacOS` (Reference) - Link to minimum RestoreImage record required +- `includedSwiftVersion` (Reference) - Link to bundled Swift compiler +- `sdkVersions` (String) - JSON of SDKs: `{"macOS": "14.2", "iOS": "17.2", "watchOS": "10.2"}` +- `notes` (String) - Release notes or additional info + +**Indexes**: +- `version` - Version lookups +- `releaseDate` - Chronological sorting +- `isPrerelease` - Filter production vs beta + +### 3. SwiftVersion + +**Purpose**: Swift compiler releases bundled with Xcode + +**Fields**: +- `version` (String, indexed) - Swift version: "5.9", "5.10", "6.0" +- `releaseDate` (Date, indexed) - Release date +- `downloadURL` (String) - Optional swift.org toolchain download +- `isPrerelease` (Boolean) - Beta/snapshot indicator +- `notes` (String) - Release notes + +**Indexes**: +- `version` - Version lookups +- `releaseDate` - Chronological sorting + +## Relationship Model + +**Simplified unidirectional references:** + +``` +RestoreImage "14.2.1" + - No outbound references + +XcodeVersion "15.1" + ├─ minimumMacOS → RestoreImage "13.5" + └─ includedSwiftVersion → SwiftVersion "5.9.2" + +SwiftVersion "5.9.2" + - No outbound references +``` + +**Example Query (Bushel use case):** +```swift +// 1. Get RestoreImage by version +let restoreImage = queryRestoreImage(version: "14.2.1") + +// 2. Find compatible Xcode versions +let xcodeVersions = queryXcode(where: minimumMacOS.version <= "14.2.1") + +// 3. Display restore image with compatible dev tools +``` + +## Data Sources + +### RestoreImage Records + +#### Primary Source - ipsw.me API via IPSWDownloads Swift Package + +- **Device**: `VirtualMac2,1` (Apple Virtual Machine restore images) +- **Coverage**: 46 final releases from macOS 12.4 (May 2022) onwards +- **Provides**: version, buildid, sha256sum, sha1sum, md5sum, filesize, url, releasedate, signed status +- **Format**: Clean JSON API +- **Package**: https://github.com/brightdigit/IPSWDownloads + +**Example API Response:** +```json +{ + "identifier": "VirtualMac2,1", + "version": "26.1", + "buildid": "25B78", + "sha1sum": "479d6bb78f069062ca016d496fd50804b673e815", + "md5sum": "e270ede6a1eba02253ac42bcd76dab4b", + "sha256sum": "e0217b3cd0f2edb9ab3294480bef5af2a0be43e86d84a15fab6bca31d3802ee8", + "filesize": 18718884780, + "url": "https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-04148/791B6F00-A30B-4EB0-B2E3-257167F7715B/UniversalMac_26.1_25B78_Restore.ipsw", + "releasedate": "2025-11-03T21:34:29Z", + "uploaddate": "2025-10-30T05:50:08Z", + "signed": true +} +``` + +#### Secondary Source - Mr. Macintosh Database + +- **URL**: https://mrmacintosh.com/apple-silicon-m1-full-macos-restore-ipsw-firmware-files-database/ +- **Coverage**: Beta/RC releases including Big Sur 11.x through current +- **Provides**: version, build, releasedate, download url, signing status, beta/RC classification +- **Total additional entries**: ~100+ beta/RC versions +- **Format**: HTML scraping required + +**Data Available:** +- Version number (e.g., "26.1 Beta 4") +- Build identifier (e.g., "25B5072a") +- Release date (formatted as MM/DD or MM/DD/YY) +- Download URL (Apple CDN links) +- Signing status ("YES" or "N/A") +- Release classification (Final, RC, Beta with numbering) + +#### Freshness Detection - Apple MESU XML + +- **URL**: https://mesu.apple.com/assets/macos/com_apple_macOSIPSW/com_apple_macOSIPSW.xml +- **Coverage**: Single entry - currently signed latest release only +- **Provides**: BuildVersion, ProductVersion, FirmwareURL, FirmwareSHA1 +- **Purpose**: Detect new releases immediately, trigger sync if version not in database +- **Update Frequency**: Real-time by Apple + +**Example XML Structure:** +```xml + + + 25B78 + 26.1 + https://updates.cdn-apple.com/.../UniversalMac_26.1_25B78_Restore.ipsw + 479d6bb78f069062ca016d496fd50804b673e815 + + +``` + +**Total Coverage**: ~140+ restore images from Big Sur 11.0 (2020) to current + +### XcodeVersion Records + +#### Primary Source - xcodereleases.com + +- **URL**: https://xcodereleases.com +- **Coverage**: Community-maintained comprehensive database +- **Provides**: version, build, release date, minimum macOS, bundled Swift version, SDK versions +- **Includes**: Both release and beta versions +- **Format**: Likely requires scraping or API if available + +#### Secondary Source - Apple Developer Release Notes + +- **Purpose**: Official documentation for validation +- **Use**: Manual curation for critical metadata + +### SwiftVersion Records + +#### Primary Source - swiftversion.net + +- **URL**: https://swiftversion.net +- **Coverage**: Community-maintained Swift version database +- **Provides**: version, release date, Xcode bundling information +- **Includes**: Comprehensive historical coverage +- **Format**: Likely requires scraping or API if available + +#### Secondary Source - swift.org Official Releases + +- **URL**: https://swift.org +- **Purpose**: Primary validation source +- **Use**: GitHub releases for version tracking + +## Database Configuration + +- **Schema Level**: Container (schema applies to both public and private databases) +- **Database**: Public Database (readable by all, writable with authentication) +- **Write Target**: Demo app writes to public database via `database: .public` parameter +- **Zone**: Default Zone (sufficient for this use case) +- **Write Access**: API token authentication for sync tool (MistKit) +- **Read Access**: Public (Bushel queries directly using native CloudKit framework) +- **Permissions**: `GRANT READ TO "_world"` makes records publicly readable +- **Container**: User-configurable (e.g., `iCloud.com.yourcompany.Bushel`) + +## Data Import Strategy + +### Sync Command Workflow + +#### 1. Fetch from ipsw.me (via IPSWDownloads package) + +```swift +// Query VirtualMac2,1 device for all firmwares +let device = try await ipswDownloads.device("VirtualMac2,1") +let firmwares = device.firmwares + +// Map to RestoreImage records with complete metadata +let restoreImages = firmwares.map { firmware in + RestoreImageRecord( + version: firmware.version, + buildNumber: firmware.buildid, + releaseDate: firmware.releasedate, + downloadURL: firmware.url, + fileSize: firmware.filesize, + sha256Hash: firmware.sha256sum, + sha1Hash: firmware.sha1sum, + isSigned: firmware.signed, + isPrerelease: false, // ipsw.me only has finals + source: "ipsw.me" + ) +} +``` + +#### 2. Fetch from Mr. Macintosh + +```swift +// Scrape database for beta/RC versions +let mrMacHTML = try await fetchHTML("https://mrmacintosh.com/...") +let betaReleases = parseMrMacTable(mrMacHTML) + +// Filter duplicates (match on version + build) +let uniqueBetas = betaReleases.filter { beta in + !restoreImages.contains(where: { $0.buildNumber == beta.buildNumber }) +} + +// Add beta-specific RestoreImage records +restoreImages.append(contentsOf: uniqueBetas.map { beta in + RestoreImageRecord( + version: beta.version, + buildNumber: beta.build, + releaseDate: beta.releaseDate, + downloadURL: beta.url, + isSigned: beta.signed, + isPrerelease: true, // Beta/RC + source: "mrmacintosh.com" + ) +}) +``` + +#### 3. Check MESU XML + +```swift +// Parse for latest signed release +let mesuXML = try await fetchMESU() +let latestRelease = parseMESUXML(mesuXML) + +// If version not in database, add from MESU +if !restoreImages.contains(where: { $0.buildNumber == latestRelease.buildNumber }) { + restoreImages.append(RestoreImageRecord( + version: latestRelease.productVersion, + buildNumber: latestRelease.buildVersion, + downloadURL: latestRelease.firmwareURL, + sha1Hash: latestRelease.firmwareSHA1, + isSigned: true, + isPrerelease: false, + source: "mesu.apple.com" + )) +} + +// Update signing status for existing records +// (MESU only lists currently signed version, so others are unsigned) +``` + +#### 4. Fetch Xcode data (xcodereleases.com) + +```swift +// Parse versions and requirements +let xcodeReleases = try await fetchXcodeReleases() + +// Create XcodeVersion records with References to RestoreImage +let xcodeRecords = xcodeReleases.map { release in + XcodeVersionRecord( + version: release.version, + buildNumber: release.build, + releaseDate: release.date, + isPrerelease: release.isBeta, + minimumMacOS: referenceToRestoreImage(version: release.minMacOS), + includedSwiftVersion: referenceToSwiftVersion(version: release.swiftVersion), + sdkVersions: release.sdks.toJSON() + ) +} +``` + +#### 5. Fetch Swift data (swiftversion.net) + +```swift +// Parse versions and metadata +let swiftReleases = try await fetchSwiftVersions() + +// Create SwiftVersion records +let swiftRecords = swiftReleases.map { release in + SwiftVersionRecord( + version: release.version, + releaseDate: release.date, + isPrerelease: release.isBeta + ) +} + +// Link from XcodeVersion records (already done in step 4) +``` + +#### 6. Upsert to CloudKit + +```swift +// Use record IDs based on version+build for idempotency +for image in restoreImages { + let recordID = CKRecord.ID(recordName: "RestoreImage-\(image.buildNumber)") + + // Update existing records if data changed + // Create new records for new versions + try await cloudKit.save(image, withID: recordID) +} + +// Same for XcodeVersion and SwiftVersion records +``` + +### Export Command + +Simple JSON dump for inspection/debugging: + +```json +{ + "restoreImages": [ + { + "version": "14.2.1", + "buildNumber": "23C71", + "releaseDate": "2024-01-22T00:00:00Z", + "downloadURL": "https://updates.cdn-apple.com/.../UniversalMac_14.2.1_23C71_Restore.ipsw", + "fileSize": 17892345678, + "sha256Hash": "abc123...", + "isSigned": true, + "isPrerelease": false, + "source": "ipsw.me" + } + ], + "xcodeVersions": [...], + "swiftVersions": [...] +} +``` + +## Demo CLI Application + +### Two Commands + +#### 1. `sync` - Import/update all data from sources to CloudKit + +```bash +# Full sync - fetch all data from all sources +./demo sync + +# Incremental sync - only check for new versions +./demo sync --incremental + +# Dry run - preview changes without writing to CloudKit +./demo sync --dry-run + +# Sync specific record types only +./demo sync --restore-images-only +./demo sync --xcode-only +./demo sync --swift-only +``` + +**Implementation:** +- Uses MistKit for all CloudKit operations +- Implements async/await throughout +- Handles rate limiting and batch operations +- Provides progress output +- Logs all changes made + +#### 2. `export` - Export CloudKit data to JSON + +```bash +# Export all records to stdout +./demo export + +# Write to file +./demo export --output data.json + +# Export specific record types +./demo export --restore-images-only +./demo export --xcode-only + +# Pretty-print JSON +./demo export --pretty + +# Filter exports +./demo export --signed-only +./demo export --no-betas +``` + +**Implementation:** +- Queries CloudKit for all records +- Serializes to JSON +- Supports filtering and formatting options + +## Bushel Integration Pattern + +Bushel will use **native CloudKit framework** (not MistKit) to query the public database: + +### Example Queries + +#### 1. Get all signed restore images, sorted by date + +```swift +let query = CKQuery( + recordType: "RestoreImage", + predicate: NSPredicate(format: "isSigned == true") +) +query.sortDescriptors = [NSSortDescriptor(key: "releaseDate", ascending: false)] + +let results = try await publicDatabase.records(matching: query) +``` + +#### 2. Filter to final releases only (no betas) + +```swift +let query = CKQuery( + recordType: "RestoreImage", + predicate: NSPredicate(format: "isSigned == true AND isPrerelease == false") +) +``` + +#### 3. Find compatible Xcode versions for a restore image + +```swift +// For a given restore image version, find Xcode versions that can run on it +let query = CKQuery( + recordType: "XcodeVersion", + predicate: NSPredicate(format: "minimumMacOS.version <= %@", "14.2.1") +) +``` + +#### 4. Get Swift version for an Xcode release + +```swift +// Fetch Xcode record +let xcodeRecord = try await publicDatabase.record(for: xcodeRecordID) + +// Fetch referenced Swift version +let swiftReference = xcodeRecord["includedSwiftVersion"] as! CKRecord.Reference +let swiftRecord = try await publicDatabase.record(for: swiftReference.recordID) +``` + +### Display Patterns + +Bushel can display: +- Restore image metadata: version, build, size, signing status, release date +- Compatible Xcode versions for each restore image +- Swift versions bundled with Xcode +- Filtering options: final vs beta, signed vs unsigned +- Search by version number or build + +## Implementation Plan + +### Phase 1: Schema Documentation ✓ + +- [x] Create `.taskmaster/docs/cloudkit-schema-plan.md` with complete schema definition +- [x] Document all fields, indexes, relationships +- [x] Include query patterns and examples + +### Phase 2: Swift Model Types + +- [ ] Define Codable structs matching CloudKit schema + - `RestoreImageRecord` + - `XcodeVersionRecord` + - `SwiftVersionRecord` +- [ ] Create CloudKit field mapping helpers +- [ ] Implement Reference type handling for relationships + +### Phase 3: Data Fetchers + +- [ ] Integrate IPSWDownloads package for ipsw.me +- [ ] Implement Mr. Macintosh HTML scraper +- [ ] Implement MESU XML parser +- [ ] Implement xcodereleases.com parser (research API/scraping approach) +- [ ] Implement swiftversion.net parser (research API/scraping approach) + +### Phase 4: Demo CLI with MistKit + +- [ ] Setup Swift Package with MistKit dependency +- [ ] Setup CloudKit container and configure authentication +- [ ] Implement `sync` command with data pipeline +- [ ] Implement `export` command for inspection +- [ ] Add Swift ArgumentParser for CLI interface +- [ ] Add logging and error handling + +### Phase 5: Blog Post Integration + +- [ ] Demonstrate MistKit usage patterns in blog post +- [ ] Show CloudKit querying with async/await +- [ ] Highlight practical real-world use case +- [ ] Document lessons learned +- [ ] Include code examples from demo app + +## Reference Documentation + +### MobileAsset Framework + +Key insights from TheAppleWiki MobileAsset documentation: + +- MESU (mesu.apple.com) serves **static XML plists** containing asset metadata +- MESU is **not a MobileAsset** - it's a special firmware manifest system +- The macOS IPSW XML is one of three special plists: + - `macos/com_apple_macOSIPSW/com_apple_macOSIPSW.xml` + - `bridgeos/com_apple_bridgeOSIPSW/com_apple_bridgeOSIPSW.xml` + - `visionos/com_apple_visionOSIPSW/com_apple_visionOSIPSW.xml` +- These contain URLs for **.ipsw files for the latest version** only +- MESU is intentionally limited to current signed releases + +Full documentation saved to: `.taskmaster/docs/mobileasset-wiki.md` (to be created) + +### Firmware Wiki + +Key insights from TheAppleWiki Firmware documentation: + +- Main firmware manifest for iOS/iPod/Apple TV/HomePod mini: https://s.mzstatic.com/version +- Separate manifests for macOS, bridgeOS, visionOS (listed above) +- MESU serves only the **latest signed version**, updated in real-time by Apple +- Historical versions and beta releases require community databases like ipsw.me + +### ipsw.me API + +- **Devices endpoint**: https://api.ipsw.me/v4/devices +- **Device firmware endpoint**: https://api.ipsw.me/v4/device/{identifier} +- **VirtualMac identifier**: `VirtualMac2,1` for Apple Virtualization framework +- Comprehensive coverage: 46 final releases from macOS 12.4 onwards +- Complete metadata: SHA-256, SHA-1, MD5, file sizes, release dates, signing status + +## Next Steps + +1. Save MobileAsset and Firmware wiki documentation for future reference +2. Update Task 5 subtasks in Task Master with refined implementation plan +3. Begin Swift model type definitions +4. Research xcodereleases.com and swiftversion.net data access methods +5. Setup CloudKit container configuration +6. Begin demo app scaffolding with MistKit integration + +## Notes + +- This schema is designed for **public database** read access by Bushel +- Demo app uses **MistKit** to populate and maintain CloudKit data +- Bushel uses **native CloudKit framework** to query the data +- Blog post will showcase both approaches as a complete ecosystem diff --git a/.claude/docs/cloudkit-schema-reference.md b/.claude/docs/cloudkit-schema-reference.md new file mode 100644 index 00000000..a669ff29 --- /dev/null +++ b/.claude/docs/cloudkit-schema-reference.md @@ -0,0 +1,323 @@ +# CloudKit Schema Language Quick Reference + +**For AI Agents:** This quick reference provides essential CloudKit Schema Language syntax and patterns for reading and modifying `.ckdb` schema files in MistKit projects. + +**Source:** Derived from [Apple's CloudKit Schema Language Documentation](https://developer.apple.com/documentation/cloudkit/integrating-a-text-based-schema-into-your-workflow) via [sosumi.ai](https://sosumi.ai/documentation/cloudkit/integrating-a-text-based-schema-into-your-workflow) + +--- + +## Grammar Overview + +``` +DEFINE SCHEMA + [ { create-role | record-type } ";" ] ... + +CREATE ROLE %role-name% + +RECORD TYPE %type-name% ( + %field-name% data-type [ QUERYABLE | SORTABLE | SEARCHABLE ] [, ...] + GRANT { READ | CREATE | WRITE } [, ...] TO %role-name% +) +``` + +## Field Options + +| Option | Purpose | Use When | +|--------|---------|----------| +| `QUERYABLE` | Index for equality lookups | Filtering by exact value (`feedURL == "..."`) | +| `SORTABLE` | Index for range searches | Range queries or sorting (`pubDate > date`, `ORDER BY pubDate`) | +| `SEARCHABLE` | Full-text search index | Text search in STRING fields (`title CONTAINS "keyword"`) | + +**Note:** Fields can have multiple options (e.g., `QUERYABLE SORTABLE`) + +## Data Types + +### Primitive Types + +| CloudKit Type | Swift Equivalent | Use Case | Example | +|---------------|------------------|----------|---------| +| `STRING` | `String` | Text data | `title STRING` | +| `INT64` | `Int64` | Integers, booleans (0/1) | `usageCount INT64` | +| `DOUBLE` | `Double` | Floating-point numbers | `rating DOUBLE` | +| `TIMESTAMP` | `Date` | Date and time | `pubDate TIMESTAMP` | +| `REFERENCE` | `CKRecord.Reference` | Relationships to other records | `feed REFERENCE` | +| `ASSET` | `CKAsset` | Files, images, binary data | `image ASSET` | +| `LOCATION` | `CLLocation` | Geographic coordinates | `location LOCATION` | +| `BYTES` | `Data` | Binary data | `data BYTES` | + +### List Types + +``` +LIST +``` + +Examples: +- `LIST` → `[String]` +- `LIST` → `[Int64]` +- `LIST` → `[CKRecord.Reference]` + +### Encrypted Types + +``` +ENCRYPTED { STRING | INT64 | DOUBLE | BYTES | LOCATION | TIMESTAMP } +``` + +Example: `ENCRYPTED STRING` for sensitive data + +## System Fields (Always Present) + +All record types automatically include these fields: + +``` +"___recordID" REFERENCE // Unique record identifier +"___createTime" TIMESTAMP // Record creation time +"___modTime" TIMESTAMP // Last modification time +"___createdBy" REFERENCE // Creator reference +"___modifiedBy" REFERENCE // Last modifier reference +"___etag" STRING // Conflict resolution tag +``` + +**Important:** System fields are implicit. Only declare them if adding `QUERYABLE`, `SORTABLE`, or `SEARCHABLE`. + +## Permission Grants + +### Standard Public Database Pattern + +``` +GRANT READ, CREATE, WRITE TO "_creator" // Record creator has full access +GRANT READ, CREATE, WRITE TO "_icloud" // Authenticated iCloud users +GRANT READ TO "_world" // Anyone can read (even unauthenticated) +``` + +### Permission Types + +- `READ` - Query and fetch records +- `CREATE` - Create new records of this type +- `WRITE` - Modify existing records + +### Built-in Roles + +- `"_creator"` - User who created the record +- `"_icloud"` - Any authenticated iCloud user +- `"_world"` - Anyone, including unauthenticated users + +### Custom Roles + +``` +CREATE ROLE AdminUser; + +RECORD TYPE ProtectedData ( + name STRING, + GRANT READ, WRITE TO AdminUser, + GRANT READ TO "_world" +); +``` + +## Naming Rules + +**Identifiers must:** +- Start with `a-z` or `A-Z` +- Contain only `a-z`, `A-Z`, `0-9`, `_` +- Use double quotes for reserved words: `grant`, `preferred`, `queryable`, `sortable`, `searchable` +- Use double quotes for system fields starting with `___` + +**Examples:** +- ✅ `feedURL`, `feed_url`, `Feed123` +- ❌ `123feed`, `feed-url`, `feed.url` +- ✅ `"grant"` (reserved word) +- ✅ `"___recordID"` (system field) + +## Comments + +``` +// Single-line comment +-- Single-line comment (SQL style) +/* Multi-line + comment */ +``` + +**Note:** CloudKit doesn't preserve comments when uploading schemas. + +## Common Patterns + +### Boolean Fields (Use INT64) + +CloudKit doesn't have a native boolean type. Use `INT64` with 0 (false) or 1 (true): + +``` +"isActive" INT64 QUERYABLE // 0 = inactive, 1 = active +"isPublished" INT64 QUERYABLE // 0 = draft, 1 = published +``` + +### Timestamps for Tracking + +``` +"createdAt" TIMESTAMP QUERYABLE SORTABLE // Creation time +"updatedAt" TIMESTAMP QUERYABLE SORTABLE // Last update +"expiresAt" TIMESTAMP QUERYABLE SORTABLE // Expiration time +``` + +### References (Relationships) + +``` +RECORD TYPE Article ( + "feed" REFERENCE QUERYABLE, // Foreign key to Feed record + "author" REFERENCE, // Foreign key to Author record + ... +); +``` + +Query pattern: `article.feed == feedRecord.recordID` + +### List Fields + +``` +"tags" LIST // Multiple tags +"imageURLs" LIST // Multiple URLs +"attachments" LIST // Multiple files +"relatedIDs" LIST // Multiple references +``` + +### Text Search + +``` +"title" STRING SEARCHABLE // Full-text search +"description" STRING SEARCHABLE // Full-text search +"keywords" STRING SEARCHABLE // Full-text search +``` + +Query pattern: `title CONTAINS "search term"` + +## MistKit-Specific Notes + +### Celestra Example Schema + +``` +DEFINE SCHEMA + +RECORD TYPE Feed ( + "___recordID" REFERENCE QUERYABLE, + "feedURL" STRING QUERYABLE SORTABLE, + "title" STRING SEARCHABLE, + "description" STRING, + "isActive" INT64 QUERYABLE, + "lastAttempted" TIMESTAMP QUERYABLE SORTABLE, + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); + +RECORD TYPE Article ( + "___recordID" REFERENCE QUERYABLE, + "feed" REFERENCE QUERYABLE, // References Feed.___recordID + "title" STRING SEARCHABLE, + "pubDate" TIMESTAMP QUERYABLE SORTABLE, + "guid" STRING QUERYABLE SORTABLE, + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); +``` + +### Swift Type Mapping + +CloudKit schema fields map to Swift properties: + +```swift +// Schema: "title" STRING +var title: String + +// Schema: "pubDate" TIMESTAMP +var pubDate: Date + +// Schema: "isActive" INT64 +var isActive: Bool // Convert 0/1 to Bool + +// Schema: "feed" REFERENCE +var feed: CKRecord.Reference + +// Schema: "tags" LIST +var tags: [String] +``` + +## Validation Commands + +```bash +# Validate schema syntax +cktool validate-schema schema.ckdb + +# Import to development environment (dry run) +cktool import-schema --validate schema.ckdb + +# Import to development environment +cktool import-schema schema.ckdb +``` + +**Environment Variables Required:** +- `CLOUDKIT_CONTAINER_ID` - Your container identifier +- `CLOUDKIT_ENVIRONMENT` - `development` or `production` +- `CLOUDKIT_MANAGEMENT_TOKEN` - Management token from CloudKit Dashboard + +## Common Mistakes to Avoid + +1. **Don't remove existing fields** - In production, removing fields causes data loss errors +2. **Don't change field types** - Type changes are not allowed after deployment +3. **Don't forget indexes** - Add `QUERYABLE` to fields used in queries +4. **Don't over-index** - Each index increases storage and write costs +5. **Don't use `NUMBER` type** - Use explicit `INT64` or `DOUBLE` instead +6. **Don't forget permissions** - Records without grants are inaccessible +7. **Don't manually reconstruct schemas** - Use `cktool export-schema` to download existing schemas + +## Schema Evolution Best Practices + +### ✅ Safe Operations + +- Add new fields to existing record types +- Add new record types +- Add indexes (`QUERYABLE`, `SORTABLE`, `SEARCHABLE`) to existing fields +- Change permissions (grants) + +### ⚠️ Dangerous Operations (Development Only) + +- Remove fields from record types +- Change field data types +- Remove record types +- Remove indexes from fields + +### 🚫 Never Allowed + +- Rename fields (must remove old, add new) +- Change system field types + +## Quick Workflow + +1. **Export existing schema:** + ```bash + cktool export-schema > schema.ckdb + ``` + +2. **Edit schema in text editor** (add/modify fields) + +3. **Validate changes:** + ```bash + cktool validate-schema schema.ckdb + ``` + +4. **Test in development:** + ```bash + export CLOUDKIT_ENVIRONMENT=development + cktool import-schema schema.ckdb + ``` + +5. **Commit to version control:** + ```bash + git add schema.ckdb + git commit -m "feat: add Article.expiresAt field" + ``` + +## See Also + +- **Full Documentation:** [Examples/Celestra/AI_SCHEMA_WORKFLOW.md](../../Examples/Celestra/AI_SCHEMA_WORKFLOW.md) +- **Apple Docs Source:** [.claude/docs/sosumi-cloudkit-schema-source.md](sosumi-cloudkit-schema-source.md) +- **Setup Guide:** [Examples/Celestra/CLOUDKIT_SCHEMA_SETUP.md](../../Examples/Celestra/CLOUDKIT_SCHEMA_SETUP.md) +- **Quick Reference:** [Examples/SCHEMA_QUICK_REFERENCE.md](../../Examples/SCHEMA_QUICK_REFERENCE.md) diff --git a/.claude/docs/cloudkitjs.md b/.claude/docs/cloudkitjs.md new file mode 100644 index 00000000..f631efb9 --- /dev/null +++ b/.claude/docs/cloudkitjs.md @@ -0,0 +1,7318 @@ + + +# https://developer.apple.com/documentation/cloudkitjs + +Framework + +# CloudKit JS + +Provide access from your web app to your CloudKit app’s containers and databases. + +CloudKit JS 1.0+ + +## Overview + +Use CloudKit JS to build a web interface that lets users access the same public and private databases as your CloudKit app running on iOS or macOS. You must have an existing CloudKit app and enable web services to use CloudKit JS. + +### Before You Begin + +Set up your app’s containers and configure CloudKit JS. + +1. Create your app’s containers and schema. + +If you’re new to CloudKit, start by reading CloudKit Quick Start. You’ll use Xcode to create your app’s containers and use CloudKit Dashboard to view the containers. Then create an iOS or Mac app that uses CloudKit to store your app’s data. + +2. In CloudKit Dashboard, enable web services by creating either an API token or server-to-server key. + +Use an API Token from a website or an embedded web view in a native app, or when you need to authenticate the user. To create an API token, read Obtaining an API Token for an iCloud Container. + +Use a server-to-server key to access the public database from a server process or script as an administrator. To create a server-to-server key, read Accessing CloudKit Using a Server-to-Server Key in CloudKit Web Services Reference. See CloudKit Catalog: An Introduction to CloudKit (Cocoa and JavaScript) for a JavaScript sample that uses a server-to-server key. + +3. Embed CloudKit JS in your webpage. + +Embed CloudKit JS in your webpage using the `script` tag and link to Apple’s hosted version of CloudKit JS at `https://cdn.apple-CloudKit.com/ck/2/CloudKit.js`. + +4. Enable JavaScript strict mode. + +To enable strict mode for an entire script, put “use strict” before any other statements. + +"use strict"; + +5. Configure CloudKit JS. + +Use the `CloudKit`. `configure` method to provide information about your app’s containers to CloudKit JS. Also, specify whether to use the development or production environment. See `CloudKit` for an example, and see CloudKit JS Data Types for details on the `CloudKit.CloudKitConfig` properties you can set. + +Now you can use the `CloudKit`. `getDefaultContainer` method in your JavaScript code to get the app container ( `CloudKit.Container`) and its database objects ( `CloudKit.Database`). + +### Next Steps + +To learn CloudKit JS, download the CloudKit Catalog: An Introduction to CloudKit (Cocoa and JavaScript) sample code project and refer to the CloudKit JS class reference documents for API details. For the hosted version of this sample code project, which allows you to execute CloudKit JS code and see the CloudKit server responses, go to CloudKit Catalog. + +The following resources provide more information about CloudKit: + +- CloudKit Quick Start gets you started creating a CloudKit native app. + +- `CloudKit` teaches you how to write native app code. + +- CloudKit Web Services Reference describes the HTTP interface to CloudKit containers and databases. + +- iCloud Design Guide provides an overview of all the iCloud services available to apps submitted to the App Store or Mac App Store. + +## Topics + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +`CloudKit.SubscriptionsResponse` + +A `CloudKit.SubscriptionsResponse` object encapsulates the results of database operations on subscriptions. + +`CloudKit.UserIdentitiesResponse` + +A `CloudKit.UserIdentitiesResponse` object encapsulates the results of fetching user identities. + +### Reference + +This document describes the CloudKit JS data types that are not described in individual class reference documents. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit/configure + +- CloudKit JS +- CloudKit +- configure + +Instance Method + +# configure + +Configures CloudKit JS. + +CloudKit JS 1.0+ + +`CloudKit` configure( +`CloudKit.CloudKitConfig` config +); + +## Parameters + +`config` + +The properties to use to initialize CloudKit JS. + +## Return Value + +The configured CloudKit object. + +## Discussion + +For each container that you access, specify the container ID, API token, and environment. + +CloudKit.configure({ +containers: [{\ +containerIdentifier: '[insert your container ID here]',\ +apiTokenAuth: {\ +apiToken: '[insert your API token and other authentication properties here]'\ +},\ +environment: 'development'\ +}] +}); + +Other `CloudKit.ContainerConfig`. `apiTokenAuth` keys, such as the `persist` key, are optional. To keep the user signed in after closing and reopening the browser, set `persist` to `true`. + +CloudKit.configure({ +containers: [{\ +// ...\ +apiTokenAuth: {\ +apiToken: '[insert your API token and other authentication properties here]',\ +persist: true\ +}\ +}] +}); + +To customize the sign in and sign out buttons, add `signInButton` and `signOutButton` keys to the `auth` dictionary. + +For more container and service configuration options, see `CloudKit.CloudKitConfig` in CloudKit JS Data Types. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit + +- CloudKit JS +- CloudKit + +Class + +# CloudKit + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +CloudKit JS 1.0+ + +interface CloudKit + +## Overview + +Set up CloudKit JS by passing container and authentication information to the `configure` method. Also, specify whether to use the development or production environment. You’ll need the container ID and API token to configure CloudKit JS. (Use CloudKit Dashboard to create an API token, as described in Accessing CloudKit Using an API Token.) Some operations require users to enter their Apple ID credentials. Apple presents the sign-in dialog, but you can customize the position and theme of the sign-in and sign-out buttons. + +After configuring CloudKit JS, use the container methods to get the app’s container objects ( `CloudKit.Container`), and from the container objects, get the database objects ( `CloudKit.Database`). + +## Topics + +### Configuring CloudKit JS + +`configure` + +Configures CloudKit JS. + +### Accessing Containers + +`getDefaultContainer` + +Returns the default container. + +`getContainer` + +Returns the container with the specified container ID. + +`getAllContainers` + +Returns all the containers that were configured. + +### Constants + +Constants describing the environment that stores the containers. + +Constants to use when configuring the environment of containers. + +### Enumerations + +`CloudKit.AppleIDButtonTheme` + +Specifies the look of the Apple ID button. + +`CloudKit.DatabaseScope` + +Available database scopes. + +`CloudKit.QueryFilterComparator` + +The comparators you use to create queries. + +`CloudKit.ReferenceAction` + +The delete action for a reference object. + +`CloudKit.ShareParticipantAcceptanceStatus` + +The status of a participant accepting a share invitation. + +`CloudKit.ShareParticipantPermission` + +`CloudKit.ShareParticipantType` + +Determines whether a participant can modify the list of participants of a shared record. + +`CloudKit.SubscriptionType` + +The type of subscription. + +### Properties + +`CKError` + +Property to access the error codes. + +`DatabaseScope` + +Property to access the enumeration. + +`Promise` + +Represents an operation that hasn’t completed yet, but is expected in the future. + +`QueryFilterComparator` + +`ReferenceAction` + +`ShareParticipantAcceptanceStatus` + +`ShareParticipantPermission` + +`ShareParticipantType` + +`ShareRecordType` + +Property to access the class instance. + +`SubscriptionType` + +### Classes + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +`CloudKit.SubscriptionsResponse` + +A `CloudKit.SubscriptionsResponse` object encapsulates the results of database operations on subscriptions. + +`CloudKit.UserIdentitiesResponse` + +A `CloudKit.UserIdentitiesResponse` object encapsulates the results of fetching user identities. + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +`CloudKit.UserLookupInfo` + +Information that can be used to fetch a user. + +`CloudKit.ZoneID` + +An identifier for a zone, which is an area in a database for organizing related records. + +## See Also + +### Classes + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit-js-data-types + +Collection + +- CloudKit JS +- CloudKit JS Data Types + +API Collection + +# CloudKit JS Data Types + +This document describes the CloudKit JS data types that are not described in individual class reference documents. + +## Topics + +### Dictionaries + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +`CloudKit.UserLookupInfo` + +Information that can be used to fetch a user. + +`CloudKit.ZoneID` + +An identifier for a zone, which is an area in a database for organizing related records. + +## See Also + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.cloudkitconfig + +- CloudKit JS +- CloudKit.CloudKitConfig + +Structure + +# CloudKit.CloudKitConfig + +Dictionary used to configure the CloudKit environment. + +CloudKit JS 1.0+ + +dictionary CloudKit.CloudKitConfig { +[`CloudKit.ContainerConfig[]`](https://developer.apple.com/documentation/cloudkitjs/cloudkit.containerconfig) containers; +Object services; +}; + +## Overview + +The table describes the `services` properties. + +| Property | Description | +| --- | --- | +| `logger` | An object with methods `info`, `log`, `warn`, and `error`. You can set this to `window.console`. | +| `fetch` | A function compatible with `window.fetch`. | +| `Promise` | An object used for deferred and asynchronous computations. To learn more, go to Mozilla Developer Network: Promise. | + +## Topics + +### Instance Properties + +`containers` + +An array of dictionaries used to configure each container of type `CloudKit.ContainerConfig`. + +`services` + +Encapsulates information about services, described in the Discussion section. + +## See Also + +### Structures + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit/getdefaultcontainer + +- CloudKit JS +- CloudKit +- getDefaultContainer + +Instance Method + +# getDefaultContainer + +Returns the default container. + +CloudKit JS 1.0+ + +`CloudKit.Container` getDefaultContainer(); + +## Return Value + +The default container (the first container that appears in the configuration list of containers). + +## See Also + +### Accessing Containers + +`getContainer` + +Returns the container with the specified container ID. + +`getAllContainers` + +Returns all the containers that were configured. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container + +- CloudKit JS +- CloudKit.Container + +Class + +# CloudKit.Container + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +CloudKit JS 1.0+ + +interface CloudKit.Container + +## Overview + +You do not create container objects yourself, nor should you subclass the `CloudKit.Container` class. You configure a container using the `CloudKit`. `configure` method and obtain a container using one of the `CloudKit` namespace container methods. + +The asynchronous methods in this class return a `Promise` object that resolves when the operation completes. For a description of the `Promise` class returned by these methods, go to Mozilla Developer Network: Promise. + +This class is similar to the `CKContainer` class in the CloudKit framework. + +## Topics + +### Getting the Public and Private Databases + +`publicCloudDatabase` + +The database containing the data shared by all users. + +`privateCloudDatabase` + +The database containing the user’s private data. + +`sharedCloudDatabase` + +The database containing shared records accepted by the current user. + +`getDatabaseWithDatabaseScope` + +Returns the specified (public, private, or shared) database. + +### Getting the Identifier and Environment + +`containerIdentifier` + +The string that identifies the app’s container. + +`environment` + +The container environment, either development or production. + +`apnsEnvironment` + +The Apple Push Notification service (APNs) environment associated with this container. + +### Authenticating Users + +`setUpAuth` + +Determines whether a user is signed in and presents an appropriate sign in or sign out button. + +`whenUserSignsIn` + +Returns an object representing a deferred or asynchronous operation that resolves when the user signs in. + +`whenUserSignsOut` + +Returns an object representing a deferred or asynchronous operation that resolves when the user signs out. + +### Discovering Users + +`fetchCurrentUserIdentity` + +Fetches information about the current user asynchronously. + +`discoverAllUserIdentities` + +Fetches all user identities in the current user’s address book. + +`discoverUserIdentities` + +Fetches all users in the specified array. + +`discoverUserIdentityWithEmailAddress` + +Fetches information about a single user based on the user’s email address. + +`discoverUserIdentityWithPhoneNumber` + +Fetches information about a single user based on the user’s phone number. + +`discoverUserIdentityWithUserRecordName` + +Fetches information about a single user using the record name. + +### Accepting Shared Records + +`acceptShares` + +Accepts a share—that is represented by a `shortGUID`—on behalf of the current user. + +`fetchRecordInfos` + +Returns information about a record for which you have a `shortGUID` property. + +### Receiving Notifications + +`addNotificationListener` + +Adds a function to call when a push notification occurs. + +`removeNotificationListener` + +Removes a function to call when a push notification occurs. + +`registerForNotifications` + +Registers to receive push notifications. + +`unregisterForNotifications` + +Unregisters to receive push notifications. + +`isRegisteredForNotifications` + +Boolean value indicating whether this container is registered to receive push notifications. + +### Logging + +`toString` + +Returns a string representation of this `CloudKit.Container` object. + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.database + +- CloudKit JS +- CloudKit.Database + +Class + +# CloudKit.Database + +A `CloudKit.Database` object represents a public or private database in an app container. + +CloudKit JS 1.0+ + +interface CloudKit.Database + +## Overview + +Each container has a public database whose data is accessible to all users and, if the current user is signed in, a private database whose data is accessible only by the current user. A database object applies operations to records, subscriptions, and zones within a database. + +You do not create database objects yourself, nor should you subclass the `CloudKit.Database` class. You get a database object using either the `publicCloudDatabase` or `privateCloudDatabase` properties in the `CloudKit.Container` class. You get a `CloudKit.Container` object using methods in the `CloudKit` namespace. For example, use `CloudKit`. `getDefaultContainer` to get the default container object. + +var container = CloudKit.getDefaultContainer(); +var publicDatabase = container.publicCloudDatabase; +var privateDatabase = container.privateCloudDatabase; + +Read access to the public database doesn’t require that the user sign in. Your web app may fetch records and perform queries on the public database, but by default your app may not save changes to the public database without a signed-in user. Access to the private database requires that the user sign in. To determine whether a user is authenticated, see `setUpAuth` in `CloudKit.Container`. + +The asynchronous methods in this class return a `Promise` object that resolves when the operation completes or is rejected due to an error. For a description of the `Promise` class returned by these methods, go to Mozilla Developer Network: Promise. + +This class is similar to the `CKDatabase` class in the CloudKit framework. + +### Creating Your Schema + +Before you can access records, you must create a schema from your native app using just-in-time schema (see Creating a Database Schema by Saving Records) or using CloudKit Dashboard (see Using CloudKit Dashboard to Manage Databases). Use CloudKit Dashboard to verify that the record types and fields appear in your app’s containers before you test your JavaScript code. + +## Topics + +### Getting the Container ID + +`containerIdentifier` + +A unique identifier for the container that this database resides in. + +### Accessing Records + +`saveRecords` + +Saves records to the database. + +`fetchRecords` + +Fetches one or more records. + +`deleteRecords` + +Deletes one or more records. + +`performQuery` + +Fetches records by using a query. + +`newRecordsBatch` + +Creates records batch builder object for modifying multiple records. + +### Accessing Record Zones + +`saveRecordZones` + +Creates one or more zones in the database. + +`fetchRecordZones` + +Fetches one or more zones. + +`fetchAllRecordZones` + +Fetches all zones in the database. + +`deleteRecordZones` + +Deletes the specified zones. + +### Subscribing to Changes + +`saveSubscriptions` + +Saves one or more subscriptions to record changes. + +`fetchSubscriptions` + +Fetches one or more subscriptions. + +`fetchAllSubscriptions` + +Fetches all subscriptions in the schema. + +`deleteSubscriptions` + +Deletes one or more subscriptions. + +### Fetching Changes + +`databaseScope` + +The type of database (public, private, or shared). + +`fetchDatabaseChanges` + +Fetch changed record zones in the database. + +`fetchRecordZoneChanges` + +Fetch changes to the specified record zones in the database. + +### Sharing Records + +`shareWithUI` + +Presents a UI to the user which lets them share a record with other users. + +### Logging + +`toString` + +Returns a string representation of this object. + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror + +- CloudKit JS +- CloudKit.CKError + +Class + +# CloudKit.CKError + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +CloudKit JS 1.0+ + +interface CloudKit.CKError + +## Topics + +### Handling Errors + +`isError` + +A Boolean value indicating whether this is an error object. + +`isCKError` + +A Boolean value indicating whether this is a CloudKit error object. + +`ckErrorCode` + +The error code for this error. + +`isServerError` + +A Boolean value indicating whether a server error occurred. + +`serverErrorCode` + +The error code generated by the server. + +`reason` + +A description of the error that occurred. + +`retryAfter` + +The suggested time to wait before trying this operation again. + +`uuid` + +A unique identifier for this error. + +`redirectURL` + +A redirect URL for the user to securely sign in with the user’s Apple ID. + +### Identifying the Operation + +`recordName` + +The name of the record that the operation failed on. + +`subscriptionID` + +A string that is a unique identifier for the subscription where the error occurred. + +`zoneID` + +The record zone in the database where the error occurred. + +### Constants + +The errors that may occur when posting requests. + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.databasechangesresponse + +- CloudKit JS +- CloudKit.DatabaseChangesResponse + +Class + +# CloudKit.DatabaseChangesResponse + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +CloudKit JS 1.0+ + +interface CloudKit.DatabaseChangesResponse + +## Topics + +### Request Properties + +`resultsLimit` + +The maximum number of records to fetch. + +### Response Properties + +`moreComing` + +A Boolean value that indicates there are more database changes to fetch. + +`syncToken` + +A point in the database’s change history. + +`zones` + +The zones in the database where the changes occurred. + +### Identifying the Class + +`isDatabaseChangesResponse` + +A Boolean value indicating whether this object is an instance of the `CloudKit.DatabaseChangesResponse` class. + +## Relationships + +### Inherited By + +- `CloudKit.Response` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.notification + +- CloudKit JS +- CloudKit.Notification + +Class + +# CloudKit.Notification + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +CloudKit JS 1.0+ + +interface CloudKit.Notification + +## Overview + +This class is similar to the `CKNotification` class in the CloudKit framework. + +## Topics + +### Getting Identifiers + +`containerIdentifier` + +The identifier of the container that generated this notification. + +`notificationID` + +A unique identifier for this notification. + +`subscriptionID` + +The identifier for the associated subscription. + +`zoneID` + +The identifier of the zone that this notification belongs to. + +### Getting the Notification Type + +`notificationType` + +The type of notification. + +`isQueryNotification` + +A Boolean value indicating whether this push notification is a query notification. + +`isRecordZoneNotification` + +A Boolean value indicating whether this notification is a push notification that was sent because of changes to a record zone. + +### Presenting Notifications + +`alertActionLocalizationKey` + +A key to get a localized right button title that appears in the alert dialog. + +`alertBody` + +The text of the alert message. + +`alertLaunchImage` + +The filename of an image file in the app bundle used as a launch image. + +`alertLocalizationArgs` + +An array of strings that appear as variables if `alertLocalizationKey` is a format specifier. + +`alertLocalizationKey` + +A key to a localized alert message. + +`badge` + +The badge number to display. + +`category` + +Name of the action group corresponding to this notification. + +`soundName` + +The name of a sound file in the app bundle to play as an alert. + +### Constants + +Constants indicating the type of event that generated the push notification. + +### Variables + +`QUERY_NOTIFICATION_REASON_RECORD_CREATED` + +A record matching the subscription’s predicate was created. + +`QUERY_NOTIFICATION_REASON_RECORD_DELETED` + +A record matching the subscription’s predicate was deleted. + +`QUERY_NOTIFICATION_REASON_RECORD_UPDATED` + +A record matching the subscription’s predicate was updated. + +## Relationships + +### Inherits From + +- `CloudKit.QueryNotification` +- `CloudKit.RecordZoneNotification` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.querynotification + +- CloudKit JS +- CloudKit.QueryNotification + +Class + +# CloudKit.QueryNotification + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +CloudKit JS 1.0+ + +interface CloudKit.QueryNotification + +## Overview + +This class is similar to the `CKQueryNotification` class in the CloudKit framework. + +## Topics + +### Getting Record Changes + +`queryNotificationReason` + +The reason for the query notification. + +`recordName` + +The name of the record that was created, deleted, or updated. + +`recordFields` + +A dictionary representation of the fields that changed in the record. + +`isPublicDatabase` + +Boolean value indicating whether the notification is from the public database. + +### Getting the Notification Type + +`notificationType` + +The type of notification. + +`isQueryNotification` + +Boolean value indicating whether this notification is a `CloudKit.QueryNotification` object. + +### Logging + +`toString` + +Returns a string representation of the notification. + +### Constants + +Constants indicating the event that triggered the notification. + +## Relationships + +### Inherited By + +- `CloudKit.Notification` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.database/savesubscriptions + +- CloudKit JS +- CloudKit.Database +- saveSubscriptions + +Instance Method + +# saveSubscriptions + +Saves one or more subscriptions to record changes. + +CloudKit JS 1.0+ + +`CloudKit.Subscription` | `CloudKit.Subscription`[] subscriptions +); + +## Parameters + +`subscriptions` + +Possible values are: + +| Type | Description | +| --- | --- | +| `CloudKit.Subscription` | A subscription in the database to save. | +| `CloudKit.Subscription[]` | An array of subscriptions to save. | + +## Return Value + +A `Promise` object that resolves to a `CloudKit.SubscriptionsResponse` object if the operation succeeds; otherwise, a `CKError` object. + +## Discussion + +Instead of fetching records, you can subscribe to changes, and let the server run the query in the background. You subscribe to changes by creating a subscription, represented by a `CloudKit.Subscription` dictionary, and saving it to a database. Then you register for push notifications and handle them when they arrive. + +Subscribing to Zone Changes + +To subscribe to all changes in a zone, set the `CloudKit.Subscription` dictionary’s `subscriptionType` key to `zone` and set the `zoneID` key to the name of the zone you want to observe. + +var zoneSubscription = { +subscriptionType: 'zone', +subscriptionID: 'changedArtwork', +zoneID: { zoneName: 'publicArtwork' } +}; + +Save the subscription using the `saveSubscriptions` method. + +database.saveSubscriptions(zoneSubscription).then(function(response) { +if (response.hasErrors) { +// Insert error handling +throw response.errors[0]; +} else { +// Successfully saved subscription +} +}); + +To get the saved subscription, use the `subscriptions` property in the `CloudKit.SubscriptionsResponse` class. + +Subscribing to Record Changes Using a Query + +Create a query subscription object (a `CloudKit.Subscription` dictionary with the `subscriptionType` key set to `query`) specifying the record type, matching criteria, and types of changes you want to be notified about. Then save the query subscription object to the database. + +For example, subscribe to receive new artwork from an artist where the `artist` field in the `Artwork` record type is a `Reference` type. First create a reference to the `Artist` record to use in the query. + +var artistReference = { +action: 'NONE', +recordName: 'Mei Chen' +} + +Create a query subscription object specifying `Artwork` records whose `artist` field matches the `Reference` object. Use the `firesOn` key to specify the types of operations that fire this subscription. + +var querySubscription = { +subscriptionType: 'query', +firesOn: ['create', 'update', 'delete'], +query: { +recordType: 'Artwork', +filterBy: [{\ +fieldName: 'artist',\ +comparator: 'EQUALS',\ +fieldValue: { value: artistReference }\ +}] +} +}; + +Save the subscription using the `saveSubscriptions` method and get the saved subscription using the `subscriptions` property in the `CloudKit.SubscriptionsResponse` class. + +database.saveSubscriptions(querySubscription).then(function(response) { +if (response.hasErrors) { +// Insert error handling +throw response.errors[0]; +} else { +// Successfully saved subscription +} +}); + +Handling Subscription Push Notifications + +Add a notification listener to the app’s container using the `addNotificationListener` method in the `CloudKit.Container` class and implement the listener to handle the push notifications. + +myContainer.addNotificationListener(function(notification) { +console.log(notification); +}); + +For details on the `CloudKit.Notification` object passed to the listener, read `CloudKit.Notification`. + +Registering for Subscription Push Notifications + +Saving subscriptions to the database doesn’t automatically configure your web app to receive notifications when a subscription fires. CloudKit uses the Apple Push Notification service (APNs) to send notifications, so your web app needs to register for push notifications to receive them. + +To receive push notifications when a subscription fires, use the `registerForNotifications` method in the `CloudKit.Container` class. + +var myContainer = CloudKit.getDefaultContainer(); +myContainer.registerForNotifications(); + +## See Also + +### Subscribing to Changes + +`fetchSubscriptions` + +Fetches one or more subscriptions. + +`fetchAllSubscriptions` + +Fetches all subscriptions in the schema. + +`deleteSubscriptions` + +Deletes one or more subscriptions. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.queryresponse + +- CloudKit JS +- CloudKit.QueryResponse + +Class + +# CloudKit.QueryResponse + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +CloudKit JS 1.0+ + +interface CloudKit.QueryResponse + +## Overview + +The `performQuery` method in the `CloudKit.Database` class returns a `Promise` object that resolves to a `CloudKit.QueryResponse` object. You should not create instances of this class directly. + +If the criteria matches more records than are returned by the server, the `continuationMarker` property is non- `null`, or the `moreComing` property is `true`. To fetch the rest of the matching records, pass the `CloudKit.QueryResponse` object to another `performQuery` call until the `continuationMarker` property is `null` or the `moreComing` property is `false`. + +For an example use of this class, see the `performQuery` method in `CloudKit.Database`. + +## Topics + +### Accessing Request Properties + +`zoneID` + +A `CloudKit.ZoneID` dictionary that identifies a record zone in the database. + +`resultsLimit` + +The maximum number of records to fetch. + +`continuationMarker` + +Marks the location of the last batch of results. + +`desiredKeys` + +An array of strings containing record field names that limits the amount of data returned in this operation. + +`zoneWide` + +A Boolean value that determines whether all zones should be searched. + +### Accessing Response Properties + +`moreComing` + +A Boolean value that indicates whether there are more records to fetch. + +`query` + +A `CloudKit.Query` dictionary containing the criteria for matching records in the database. + +### Identifying the Class + +`isQueryResponse` + +A Boolean value indicating whether this object is an instance of the `CloudKit.QueryResponse` class. + +### Logging + +`toString` + +Returns a string representation of this `CloudKit.QueryResponse` object. + +## Relationships + +### Inherited By + +- `CloudKit.RecordsResponse` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordinfosresponse + +- CloudKit JS +- CloudKit.RecordInfosResponse + +Class + +# CloudKit.RecordInfosResponse + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +CloudKit JS 1.0+ + +interface CloudKit.RecordInfosResponse + +## Topics + +### Response Properties + +`results` + +The results of fetching record information. + +### Identifying the Class + +`isRecordInfosResponse` + +A Boolean value indicating whether this object is an instance of the `CloudKit.RecordInfosResponse` class. + +### Logging + +`toString` + +Returns a string representation of this object. + +## Relationships + +### Inherited By + +- `CloudKit.Response` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordsbatchbuilder + +- CloudKit JS +- CloudKit.RecordsBatchBuilder + +Class + +# CloudKit.RecordsBatchBuilder + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +CloudKit JS 1.0+ + +interface CloudKit.RecordsBatchBuilder + +## Overview + +It is more efficient to use this class to batch multiple record changes into a single operation than to use the individual record change methods in the `CloudKit.Database` class. Using this class is especially important if the record types contain `Reference` fields. CloudKit ensures that in a graph of related records, target records are saved before source records. + +You should not create instances of this class directly. Instead use the `newRecordsBatch` method in the `CloudKit.Database` class to get a `CloudKit.RecordsBatchBuilder` object. Then use the create, replace, and delete methods in this class to build the batch operation. Use the `commit` method to execute the batch operation. + +For convenience, most methods in this class that add operations return the `CloudKit.RecordsBatchBuilder` object so that you can chain method calls together; for example: + +myDatabase.newRecordsBatch() +.create(someRecord) +.update(someOtherRecord) +.delete(aThirdRecord) +.commit() + +For similar web service operations, read Modifying Records (records/modify) in CloudKit Web Services Reference. + +## Topics + +### Creating and Updating Records + +`create` + +Creates one or more records. + +`createOrUpdate` + +Creates or updates one or more records depending on the information provided. + +`update` + +Updates one or more existing records. + +`forceUpdate` + +Updates one or more existing records regardless of conflicts. + +### Replacing Records + +`replace` + +Replaces one or more records with the specified records. + +`forceReplace` + +Replaces one or more records with the specified records regardless of conflicts. + +### Deleting Records + +`delete` + +Deletes one or more records. + +`forceDelete` + +Deletes one or more records regardless of conflicts. + +### Executing Operations + +`commit` + +Executes the operations on the database that created this batch builder object. + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordsresponse + +- CloudKit JS +- CloudKit.RecordsResponse + +Class + +# CloudKit.RecordsResponse + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +CloudKit JS 1.0+ + +interface CloudKit.RecordsResponse + +## Overview + +The methods in the `CloudKit.Database` class that operate on records and the `commit` method in the `CloudKit.RecordsBatchBuilder` class return a `Promise` object that resolves to a `CloudKit.RecordsResponse` object if the operation is successful. You should not create instances of this class directly. + +Errors can occur for individual operations although the overall method may succeed. If an individual operation is successful, a corresponding `CloudKit.Record` dictionary appears in the `records` array. If an individual operation is unsuccessful, a corresponding `CKError` appears in the errors array. + +For examples using the `CloudKit.Database` methods that resolve to a `CloudKit.RecordsResponse` object, see the `saveRecord` and `fetchRecord` methods in `CloudKit.Database`. + +## Topics + +### Getting Records + +`records` + +The records for the successful operations. + +`numbersAsStrings` + +A Boolean value indicating whether the numbers in fields are represented as strings. + +### Identifying the Class + +`isRecordsResponse` + +A Boolean value indicating whether this object is an instance of the `CloudKit.RecordsResponse` class. + +### Logging + +`toString` + +Returns a string representation of this `CloudKit.RecordsResponse` object. + +## Relationships + +### Inherits From + +- `CloudKit.QueryResponse` + +### Inherited By + +- `CloudKit.Response` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzonechangesresponse + +- CloudKit JS +- CloudKit.RecordZoneChangesResponse + +Class + +# CloudKit.RecordZoneChangesResponse + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +CloudKit JS 1.0+ + +interface CloudKit.RecordZoneChangesResponse + +## Topics + +### Response Properties + +`zones` + +The records that changed in each zone. + +### Identifying the Class + +`isRecordZoneChangesResponse` + +A Boolean value indicating whether this object is an instance of the `CloudKit.RecordZoneChangesResponse` class. + +## Relationships + +### Inherited By + +- `CloudKit.Response` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzonenotification + +- CloudKit JS +- CloudKit.RecordZoneNotification + +Class + +# CloudKit.RecordZoneNotification + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +CloudKit JS 1.0+ + +interface CloudKit.RecordZoneNotification + +## Overview + +This class is similar to the `CKRecordZoneNotification` class in the CloudKit framework. + +## Topics + +### Getting the Notification Type + +`notificationType` + +The type of notification. + +`isRecordZoneNotification` + +A Boolean value indicating whether this notification is a `CloudKit.RecordZoneNotification` object. + +### Logging + +`toString` + +Returns a string representation of the notification. + +## Relationships + +### Inherited By + +- `CloudKit.Notification` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzonesresponse + +- CloudKit JS +- CloudKit.RecordZonesResponse + +Class + +# CloudKit.RecordZonesResponse + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +CloudKit JS 1.0+ + +interface CloudKit.RecordZonesResponse + +## Overview + +The methods in the `CloudKit.Database` class that operate on record zones return a `Promise` object that resolves to a `CloudKit.RecordZonesResponse` object if the operation is successful. You should not create instances of this class directly. + +Errors can occur for individual operations although the overall method may succeed. If an individual operation is successful, a corresponding zone dictionary appears in the `zones` array. If an individual operation is unsuccessful, a corresponding `CKError` appears in the errors array. + +## Topics + +### Accessing Properties + +`zones` + +The zones for the successful database operations. + +### Identifying the Class + +`isRecordZonesResponse` + +A Boolean value indicating whether this object is an instance of the `CloudKit.RecordZonesResponse` class. + +### Logging + +`toString` + +Returns a string representation of this `CloudKit.RecordZonesResponse` object. + +## Relationships + +### Inherited By + +- `CloudKit.Response` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.response + +- CloudKit JS +- CloudKit.Response + +Class + +# CloudKit.Response + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +CloudKit JS 1.0+ + +interface CloudKit.Response + +## Overview + +For examples of methods that resolve to a `CloudKit.Response` subclass, read `CloudKit.Database`. + +## Topics + +### Handling Errors + +`hasErrors` + +A Boolean value indicating whether errors occurred in the request. + +`errors` + +Errors that occurred in the request. + +### Identifying the Class + +`isResponse` + +A Boolean value that indicates whether there is a response from the request. + +## Relationships + +### Inherits From + +- `CloudKit.DatabaseChangesResponse` +- `CloudKit.RecordInfosResponse` +- `CloudKit.RecordZoneChangesResponse` +- `CloudKit.RecordZonesResponse` +- `CloudKit.RecordsResponse` +- `CloudKit.SubscriptionsResponse` +- `CloudKit.UserIdentitiesResponse` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.ShareRecordType` + +Display information about the record type of a shared record. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.sharerecordtype + +- CloudKit JS +- CloudKit.ShareRecordType + +Class + +# CloudKit.ShareRecordType + +Display information about the record type of a shared record. + +CloudKit JS 1.0+ + +interface CloudKit.ShareRecordType + +## Topics + +### Properties + +`NAME` + +The name of the share record type `CloudKit.share`. + +`THUMBNAIL_IMAGE_DATA_FIELD_NAME` + +The name of the thumbnail image data field. + +`TITLE_FIELD_NAME` + +The name of the title field. + +`TYPE_FIELD_NAME` + +The name of the type field. + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.subscriptionsresponse + +- CloudKit JS +- CloudKit.SubscriptionsResponse + +Class + +# CloudKit.SubscriptionsResponse + +A `CloudKit.SubscriptionsResponse` object encapsulates the results of database operations on subscriptions. + +CloudKit JS 1.0+ + +interface CloudKit.SubscriptionsResponse + +## Overview + +The methods in the `CloudKit.Database` class that operate on subscriptions return a `Promise` object that resolves to a `CloudKit.SubscriptionsResponse` object if the operation is successful. You should not create instances of this class directly. + +Errors can occur for individual operations even though the overall method may succeed. If an individual operation is successful, a corresponding `CloudKit.Subscription` dictionary appears in the `subscriptions` array. If an individual operation is unsuccessful, a corresponding `CKError` appears in the errors array. + +For examples of using `CloudKit.Database` methods that resolve to a `CloudKit.SubscriptionsResponse` object, see the `saveSubscriptions` method in `CloudKit.Database`. + +## Topics + +### Getting Subscriptions + +`subscriptions` + +Contains the subscriptions for the successful operations. + +### Identifying the Class + +`isSubscriptionsResponse` + +Boolean value indicating whether this object is an instance of the `CloudKit.SubscriptionsResponse` class. + +### Logging + +`toString` + +Returns a string representation of this object. + +## Relationships + +### Inherited By + +- `CloudKit.Response` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.useridentitiesresponse + +- CloudKit JS +- CloudKit.UserIdentitiesResponse + +Class + +# CloudKit.UserIdentitiesResponse + +A `CloudKit.UserIdentitiesResponse` object encapsulates the results of fetching user identities. + +CloudKit JS 1.0+ + +interface CloudKit.UserIdentitiesResponse + +## Topics + +### Response Properties + +`users` + +The fetched user identities. + +### Identifying the Class + +`isUserIdentitiesResponse` + +A Boolean value indicating whether this object is an instance of the `CloudKit.UserIdentitiesResponse` class. + +### Logging + +`toString` + +Returns a string representation of this object. + +## Relationships + +### Inherited By + +- `CloudKit.Response` + +## See Also + +### Classes + +`CloudKit` + +Use the `CloudKit` namespace to configure CloudKit JS, and to access app containers and global constants. + +`CloudKit.CKError` + +A `CloudKit.CKError` object encapsulates an error that may occur when you use CloudKit JS. This includes CloudKit server errors and local errors. + +`CloudKit.Container` + +A `CloudKit.Container` object provides access to an app container, and through the app container, access to its databases. It also contains methods for authenticating and fetching users. + +`CloudKit.Database` + +A `CloudKit.Database` object represents a public or private database in an app container. + +`CloudKit.DatabaseChangesResponse` + +A `CloudKit.DatabaseChangesResponse` object encapsulates the results of fetching changed record zones in a database. + +`CloudKit.Notification` + +A `CloudKit.Notification` object represents a push notification that was sent to your app. Notifications are triggered by subscriptions that you save to the database. To subscribe to record changes and handle push notifications, see the `saveSubscription` method in `CloudKit.Database`. + +`CloudKit.QueryNotification` + +A `CloudKit.QueryNotification` object represents a push notification that was generated by a subscription object. A query notification is triggered by subscriptions where the `subscriptionType` key is `query`. Use a `CloudKit.QueryNotification` object to get information about the record that changed. To create query subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.QueryResponse` + +A `CloudKit.QueryResponse` object encapsulates the results of using a query to fetch records + +`CloudKit.RecordInfosResponse` + +A `CloudKit.RecordInfosResponse` object encapsulates the results of fetching information about records in general and shared records in particular. + +`CloudKit.RecordsBatchBuilder` + +A `CloudKit.RecordsBatchBuilder` object encapsulates the results of changes to multiple records in a single database operation. + +`CloudKit.RecordsResponse` + +A `CloudKit.RecordsResponse` object encapsulates the results of fetching records. + +`CloudKit.RecordZoneChangesResponse` + +The `CloudKit.RecordZoneChangesResponse` object encapsulates the results of fetching changes to one or more record zones. + +`CloudKit.RecordZoneNotification` + +A `CloudKit.RecordZoneNotification` object represents a push notification that was caused by changes to the contents of a record zone. A zone notification is triggered by subscriptions where the `subscriptionType` key is `zone`. Use a `CloudKit.RecordZoneNotification` object to get information about the record that changed. To create zone subscriptions and handle push notifications, see the `saveSubscriptions` method in `CloudKit.Database`. + +`CloudKit.RecordZonesResponse` + +A `CloudKit.RecordZonesResponse` object encapsulates the results of database operations on a record zone. + +`CloudKit.Response` + +The `CloudKit.Response` class is an abstract superclass for subclasses that encapsulate the response from server requests. Don’t create instances of this class. Instances of subclasses are returned by methods in the `CloudKit.Container` and `CloudKit.Database` classes. Most of these methods return a `Promise` object that resolves to a subclass of `CloudKit.Response` if the operation is successful. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit-js-enumerations + +Collection + +- CloudKit JS +- CloudKit JS Enumerations + +API Collection + +# CloudKit JS Enumerations + +## Topics + +### Enumerations + +`CloudKit.AppleIDButtonTheme` + +Specifies the look of the Apple ID button. + +`CloudKit.DatabaseScope` + +Available database scopes. + +`CloudKit.QueryFilterComparator` + +The comparators you use to create queries. + +`CloudKit.ReferenceAction` + +The delete action for a reference object. + +`CloudKit.ShareParticipantAcceptanceStatus` + +The status of a participant accepting a share invitation. + +`CloudKit.ShareParticipantPermission` + +`CloudKit.ShareParticipantType` + +Determines whether a participant can modify the list of participants of a shared record. + +`CloudKit.SubscriptionType` + +The type of subscription. + +## See Also + +### Reference + +This document describes the CloudKit JS data types that are not described in individual class reference documents. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit/configure) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit-js-data-types) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.cloudkitconfig) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit/getdefaultcontainer) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container)) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.database)). + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.database) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.databasechangesresponse) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.notification) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.database). + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.querynotification) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.database/savesubscriptions) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.queryresponse) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordinfosresponse) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordsbatchbuilder) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordsresponse) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzonechangesresponse) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzonenotification) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzonesresponse) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.response) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.sharerecordtype) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.subscriptionsresponse) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.useridentitiesresponse) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit-js-enumerations) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit/getcontainer + +- CloudKit JS +- CloudKit +- getContainer + +Instance Method + +# getContainer + +Returns the container with the specified container ID. + +CloudKit JS 1.0+ + +`CloudKit.Container` getContainer( +String containerIdentifier +); + +## Parameters + +`containerIdentifier` + +The identifier for the container you want to get. + +## Return Value + +The container with the specified container ID if it exists; otherwise, the value is undefined. + +## See Also + +### Accessing Containers + +`getDefaultContainer` + +Returns the default container. + +`getAllContainers` + +Returns all the containers that were configured. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit/getallcontainers + +- CloudKit JS +- CloudKit +- getAllContainers + +Instance Method + +# getAllContainers + +Returns all the containers that were configured. + +CloudKit JS 1.0+ + +[`CloudKit.Container[]`](https://developer.apple.com/documentation/cloudkitjs/cloudkit.container) getAllContainers(); + +## Return Value + +All the configured containers. + +## See Also + +### Related Documentation + +`configure` + +Configures CloudKit JS. + +### Accessing Containers + +`getDefaultContainer` + +Returns the default container. + +`getContainer` + +Returns the container with the specified container ID. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit/getcontainer) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit/getallcontainers) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.containerconfig + +- CloudKit JS +- CloudKit.ContainerConfig + +Structure + +# CloudKit.ContainerConfig + +A configuration for a container. + +CloudKit JS 1.0+ + +dictionary CloudKit.ContainerConfig { +String containerIdentifier; +String environment; +String apnsEnvironment; +Object apiTokenAuth; +Object serverToServerKeyAuth; +}; + +## Overview + +This table describes `apiTokenAuth` properties. + +| Property | Description | +| --- | --- | +| `apiToken` | The API token generated and obtained using CloudKit Dashboard. To create an API token, read Accessing CloudKit Using an API Token in CloudKit Web Services Reference. | +| `persist` | Boolean value indicating whether the CloudKit session token persists. The default value is `false`. | +| `signInButton` | The sign-in button to display to the user. The properties are: ![](https://docs-assets.developer.apple.com/published/67dc4b07a8d84366d4cc0e812eb40b4a/spacer.png) id: The DOM element ID. The default value is `apple-sign-in-button`. ![](https://docs-assets.developer.apple.com/published/67dc4b07a8d84366d4cc0e812eb40b4a/spacer.png) theme: The button theme. The default value is `medium`. ![](https://docs-assets.developer.apple.com/published/67dc4b07a8d84366d4cc0e812eb40b4a/spacer.png) If `null`, uses the default property values. | +| `signOutButton` | The sign-out button to display to the user. The properties are: ![](https://docs-assets.developer.apple.com/published/67dc4b07a8d84366d4cc0e812eb40b4a/spacer.png) id: The DOM element ID. The default value is `apple-sign-out-button`. ![](https://docs-assets.developer.apple.com/published/67dc4b07a8d84366d4cc0e812eb40b4a/spacer.png) theme: The button theme. The default value is `medium`. ![](https://docs-assets.developer.apple.com/published/67dc4b07a8d84366d4cc0e812eb40b4a/spacer.png) If `null`, uses the default property values. | + +This table describes `serverToServerKeyAuth` properties. + +| Property | Description | +| --- | --- | +| `keyID` | A unique identifier for the key generated using CloudKit Dashboard. To create this key, read Accessing CloudKit Using a Server-to-Server Key in CloudKit Web Services Reference. | +| `privateKeyFile` | The path to the PEM encoded key file. | +| `privateKeyPassPhrase` | The pass phrase for the key. | + +## Topics + +### Instance Properties + +`apiTokenAuth` + +The API token and other authentication properties, described in the Discussion section. Either this key or the `serverToServerKeyAuth` key is required. If you include this key, don’t include the `serverToServerKeyAuth` key. + +`apnsEnvironment` + +The Apple Push Notification service (APNs) environment associated with this container. Possible values are `CloudKit`. `DEVELOPMENT_ENVIRONMENT` and `CloudKit`. `PRODUCTION_ENVIRONMENT`. + +`containerIdentifier` + +The string that identifies the app’s container. This key is required. + +`environment` + +The version of the app’s container. Possible values are `CloudKit`. `DEVELOPMENT_ENVIRONMENT` and `CloudKit`. `PRODUCTION_ENVIRONMENT`. + +`serverToServerKeyAuth` + +The server-to-server authentication key and related properties, described in the Discussion section. Either this key or the `apiTokenAuth` key is required. If you include this key, don’t include the `apiTokenAuth` key. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.namecomponents + +- CloudKit JS +- CloudKit.NameComponents + +Structure + +# CloudKit.NameComponents + +The parts of the user’s name. + +CloudKit JS 1.0+ + +dictionary CloudKit.NameComponents { +String givenName; +String familyName; +}; + +## Topics + +### Instance Properties + +`familyName` + +The user’s last name. + +`givenName` + +The user’s first name. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.notificationinfo + +- CloudKit JS +- CloudKit.NotificationInfo + +Structure + +# CloudKit.NotificationInfo + +Information about a notification. + +CloudKit JS 1.0+ + +dictionary CloudKit.NotificationInfo { +String alertBody; +String alertLocalizationKey; +String[] alertLocalizationArgs; +String alertActionLocalizationKey; +String alertLaunchImage; +String soundName; +Boolean shouldBadge; +Boolean shouldSendContentAvailable; +String[] additionalFields; +String category; +}; + +## Overview + +The `CloudKit.NotificationInfo` dictionary is the same as the dictionary described in Notification Info Dictionary in CloudKit Web Services Reference. + +## Topics + +### Instance Properties + +`additionalFields` + +Fields the server sends along with this notification. + +`alertActionLocalizationKey` + +A key to get a localized right button title that appears in the alert dialog. + +`alertBody` + +The text of the alert message. + +`alertLaunchImage` + +The filename of an image file in the app bundle used as a launch image. + +`alertLocalizationArgs` + +Array of strings to appear as variables if `alertLocalizationKey` is a format specifier. + +`alertLocalizationKey` + +A key to a localized alert-message. + +`category` + +The name of the action group corresponding to this notification. + +`shouldBadge` + +A Boolean value indicating whether a badge should be displayed. If `true`, a badge is displayed; otherwise, it is not. The default value is `false`. + +`shouldSendContentAvailable` + +A Boolean value indicating whether new content is available. If `true`, new content is available; otherwise, it is not. The default value is `false`. + +`soundName` + +The name of a sound file in the app bundle to play as an alert. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.query + +- CloudKit JS +- CloudKit.Query + +Structure + +# CloudKit.Query + +Search parameters to use when fetching records from the database. + +CloudKit JS 1.0+ + +dictionary CloudKit.Query { +String recordType; +Object[] filterBy; +Object[] sortBy; +}; + +## Overview + +The `CloudKit.Query` dictionary is the same as the dictionary described in Fetching Records Using a Query (records/query) in CloudKit Web Services Reference. + +## Topics + +### Instance Properties + +`filterBy` + +An array of predicate dictionaries used to determine whether a record matches the query. + +`recordType` + +The name of the record type. This key is required. + +`sortBy` + +An array of sort descriptor dictionaries that specify how to order the fetched records. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.record + +- CloudKit JS +- CloudKit.Record + +Structure + +# CloudKit.Record + +A record in the database. + +CloudKit JS 1.0+ + +dictionary CloudKit.Record { +Object created; +Object modified; +String recordType; +String recordName; +String recordChangeTag; +Boolean deleted; +Boolean createShortGUID; +String shortGUID; +CKReference parent; +CKReference share; + +}; + +## Overview + +The `CloudKit.Record` dictionary is the same as the dictionary described in Modifying Records (records/modify) in CloudKit Web Services Reference. + +## Topics + +### Instance Properties + +`createShortGUID` + +A Boolean value indicating whether to create a short GUID. + +`created` + +Information about when the record was created on the server. The properties of this object are: `timestamp` ( `Number`), the time at which the record was created, and `user` ( `String`), the ID of the user who created the record. This field is used by the `CloudKit.RecordsResponse` class. The value of this field is set by the server. Omit this key when saving a record. + +`deleted` + +A Boolean value indicating whether the record was deleted. `true` if the record was deleted; otherwise, `false`. + +`fields` + +Names of the fields or field-value pairs. + +`modified` + +Information about when the record was last modified. The properties of this object are: `timestamp` ( `Number`), the time at which the record was created, and `user` ( `String`), the ID of the user who modified the record. This field is used by the `CloudKit.RecordsResponse` class. This value of this field is set by the server. Omit this key when saving a record. + +`parent` + +A reference to a parent object used for sharing. + +`recordChangeTag` + +A string containing the server change token for the record. Use this tag to indicate which version of the record you last fetched. This key is required if you are saving an existing record. + +`recordName` + +The unique name used to identify the record. The default value is a random UUID. + +`recordType` + +The name of the record type. This key is required if the record doesn’t exist. + +`share` + +A reference to the shared object for this record. + +`shortGUID` + +A global unique identifier for this record used for sharing. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordfield + +- CloudKit JS +- CloudKit.RecordField + +Structure + +# CloudKit.RecordField + +A field value of a record. + +CloudKit JS 1.0+ + +dictionary CloudKit.RecordField { +String type; +Object value; +}; + +## Overview + +The `CloudKit.RecordField` dictionary is similar to the dictionary described in Record Field Dictionary in CloudKit Web Services Reference. + +## Topics + +### Instance Properties + +`type` + +The type of the field. + +`value` + +The value of the field. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordinfo + +- CloudKit JS +- CloudKit.RecordInfo + +Structure + +# CloudKit.RecordInfo + +Encapsulates the results of fetching information about a record. + +CloudKit JS 1.0+ + +dictionary CloudKit.RecordInfo { +`CloudKit.Record` rootRecord; +`CloudKit.Share` share; +}; + +## Topics + +### Instance Properties + +`rootRecord` + +The root shared record. + +`share` + +The shared record. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzone + +- CloudKit JS +- CloudKit.RecordZone + +Structure + +# CloudKit.RecordZone + +Represents a record zone. + +CloudKit JS 1.0+ + +dictionary CloudKit.RecordZone { +`CloudKit.ZoneID` zoneID; +}; + +## Topics + +### Instance Properties + +`zoneID` + +The record zone identifier. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzonechanges + +- CloudKit JS +- CloudKit.RecordZoneChanges + +Structure + +# CloudKit.RecordZoneChanges + +Represents the changes in a record zone. + +CloudKit JS 1.0+ + +dictionary CloudKit.RecordZoneChanges { +`CloudKit.ZoneID` zoneID; +Boolean resultsLimit; +String[] desiredKeys; +String[] desiredRecordTypes; +Boolean moreComing; +String syncToken; +[`CloudKit.Record[]`](https://developer.apple.com/documentation/cloudkitjs/cloudkit.record) records; +[`CloudKit.CKError[]`](https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror) errors; +}; + +## Topics + +### Instance Properties + +`desiredKeys` + +An array of record field names that limit the amount of data returned. Only the fields specified in the array are returned. The default is `null`, which fetches all record fields. + +`desiredRecordTypes` + +An array of record types that limit the amount of records returned. Only the record types specified in the array are returned. + +`errors` + +Errors that may have occurred fetching the changed records. + +`moreComing` + +Boolean value that indicates whether there are more changes to request. If `moreComing` is `true`, request more changes using the value of the included `syncToken` key. If `moreComing` is `false`, there are no more changes. + +`records` + +The records that changed. + +`resultsLimit` + +The maximum number of records to fetch. + +`syncToken` + +Identifies a point in the zone’s change history. The first time you get record changes, omit this key and if `moreComing` is `true` in the response, use the `syncToken` in the response in the next request until `moreComing` is `false`. Otherwise, get the current sync token by fetching a zone. + +`zoneID` + +The record zone identifier. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzonechangesoptions + +- CloudKit JS +- CloudKit.RecordZoneChangesOptions + +Structure + +# CloudKit.RecordZoneChangesOptions + +Options about fetching changes in a record zone. + +CloudKit JS 1.0+ + +dictionary CloudKit.RecordZoneChangesOptions { +`CloudKit.ZoneID` zoneID; +String[] desiredKeys; +String[] desiredRecordTypes; +String syncToken; +}; + +## Topics + +### Instance Properties + +`desiredKeys` + +An array of record field names that limit the amount of data returned. Only the fields specified in the array are returned. The default is `null`, which fetches all record fields. + +`desiredRecordTypes` + +`syncToken` + +Identifies a point in the zone’s change history. The first time you get record changes, omit this key and if `moreComing` is `true` in the response, use the `syncToken` in the response in the next request until `moreComing` is `false`. Otherwise, get the current sync token by fetching a zone. + +`zoneID` + +The record zone identifier. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.share + +- CloudKit JS +- CloudKit.Share + +Structure + +# CloudKit.Share + +Represents a shared record. + +CloudKit JS 1.0+ + +dictionary CloudKit.Share { +String recordType; +`CloudKit.ShareParticipantPermission` publicPermission; +[`CloudKit.ShareParticipant[]`](https://developer.apple.com/documentation/cloudkitjs/cloudkit.shareparticipant) participants; +}; + +## Topics + +### Instance Properties + +`participants` + +Users who accepted this shared record. + +`publicPermission` + +Th public’s read and write permissions. + +`recordType` + +The type of record. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.shareparticipant + +- CloudKit JS +- CloudKit.ShareParticipant + +Structure + +# CloudKit.ShareParticipant + +Represents a user who accepted a shared record. + +CloudKit JS 1.0+ + +dictionary CloudKit.ShareParticipant { +`CloudKit.ShareParticipantPermission` permission; +`CloudKit.ShareParticipantAcceptanceStatus` acceptanceStatus; +`CloudKit.ShareParticipantType` type; +}; + +## Topics + +### Instance Properties + +`acceptanceStatus` + +Indicates the status of accepting the shared record. + +`permission` + +The participant’s read and write permissions. + +`type` + +Type of participant. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.sharinguiresult + +- CloudKit JS +- CloudKit.SharingUIResult + +Structure + +# CloudKit.SharingUIResult + +Represents the results of sharing a record with other users. + +CloudKit JS 1.0+ + +dictionary CloudKit.SharingUIResult { +`CloudKit.Share` share; +}; + +## Topics + +### Instance Properties + +`share` + +The record that was accepted. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.subscription + +- CloudKit JS +- CloudKit.Subscription + +Structure + +# CloudKit.Subscription + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +CloudKit JS 1.0+ + +dictionary CloudKit.Subscription { +String subscriptionType; +String subscriptionID; +`CloudKit.ZoneID` zoneID; +`CloudKit.NotificationInfo` notificationInfo; +Boolean zoneWide; +String[] firesOn; +Boolean firesOnce; +Query query; +}; + +## Overview + +The `CloudKit.Subscription` dictionary is the same as the dictionary described in Subscription Dictionary in CloudKit Web Services Reference. + +## Topics + +### Instance Properties + +`firesOn` + +An array of keywords that specify the actions that should trigger push notifications. Possible values in the array are: `"create"`, `"update"`, and `"delete"`. This key is not used if `query` is null. + +`firesOnce` + +A Boolean value indicating whether push notifications should be triggered once. If `true`, push notifications are sent once. If `false`, they can be sent multiple times. The default value is `false`. + +`notificationInfo` + +A dictionary containing information about how the system should alert the user. + +`query` + +The matching criteria to apply to records. + +`subscriptionID` + +A unique identifier for the subscription. + +`subscriptionType` + +The type of subscription. Possible values are: `"zone"`, and `"query”`. This key is required. + +`zoneID` + +Dictionary that identifies a record zone to monitor in the database. + +`zoneWide` + +A Boolean value determining whether all zones should be searched. If `true`, all zones are searched. If `false`, the default zone is searched. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.UserIdentity` + +Information to identify a user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.useridentity + +- CloudKit JS +- CloudKit.UserIdentity + +Structure + +# CloudKit.UserIdentity + +Information to identify a user. + +CloudKit JS 1.0+ + +dictionary CloudKit.UserIdentity { +`CloudKit.NameComponents` nameComponents; +String userRecordName; +`CloudKit.UserLookupInfo` lookupInfo; +}; + +## Overview + +If a user is discoverable, the `CloudKit.UserIdentity` dictionary contains a `nameComponents` key that you can use to get the user’s first and last name; otherwise, to protect the users’s privacy, the `CloudKit.UserIdentity` dictionary contains only the `lookupInfo` key. + +## Topics + +### Instance Properties + +`lookupInfo` + +Information used to fetch a user. + +`nameComponents` + +An object that contains the user’s name. Use the `familyName` key to get the last name, and the `givenName` key to get the first name. + +`userRecordName` + +The name of the user record. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.userlookupinfo + +- CloudKit JS +- CloudKit.UserLookupInfo + +Structure + +# CloudKit.UserLookupInfo + +Information that can be used to fetch a user. + +CloudKit JS 1.0+ + +dictionary CloudKit.UserLookupInfo { +String userRecordName; +String emailAddress; +String phoneNumber; +}; + +## Topics + +### Instance Properties + +`emailAddress` + +The user’s email address. + +`phoneNumber` + +The user’s phone number. + +`userRecordName` + +The name of the user record. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.zoneid + +- CloudKit JS +- CloudKit.ZoneID + +Structure + +# CloudKit.ZoneID + +An identifier for a zone, which is an area in a database for organizing related records. + +CloudKit JS 1.0+ + +dictionary CloudKit.ZoneID { +String zoneName; +}; + +## Overview + +The `CloudKit.ZoneID` dictionary is the same as the dictionary described in Zone Dictionary in CloudKit Web Services Reference. + +## Topics + +### Instance Properties + +`zoneName` + +The name that identifies the record zone. The default value is `_defaultZone`, which indicates the default zone of the current database. This key is required. + +## See Also + +### Structures + +`CloudKit.CloudKitConfig` + +Dictionary used to configure the CloudKit environment. + +`CloudKit.ContainerConfig` + +A configuration for a container. + +`CloudKit.NameComponents` + +The parts of the user’s name. + +`CloudKit.NotificationInfo` + +Information about a notification. + +`CloudKit.Query` + +Search parameters to use when fetching records from the database. + +`CloudKit.Record` + +A record in the database. + +`CloudKit.RecordField` + +A field value of a record. + +`CloudKit.RecordInfo` + +Encapsulates the results of fetching information about a record. + +`CloudKit.RecordZone` + +Represents a record zone. + +`CloudKit.RecordZoneChanges` + +Represents the changes in a record zone. + +`CloudKit.RecordZoneChangesOptions` + +Options about fetching changes in a record zone. + +`CloudKit.Share` + +Represents a shared record. + +`CloudKit.ShareParticipant` + +Represents a user who accepted a shared record. + +`CloudKit.SharingUIResult` + +Represents the results of sharing a record with other users. + +`CloudKit.Subscription` + +A subscription, which is a persistent query on the server that tracks the creation, deletion, and modification of records. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.containerconfig) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.namecomponents) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.notificationinfo) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.query) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.record) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordfield) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordinfo) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzone) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzonechanges) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.recordzonechangesoptions) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.share) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.shareparticipant) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.sharinguiresult) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.subscription) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.useridentity) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.userlookupinfo) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.zoneid) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/iserror + +- CloudKit JS +- CloudKit.CKError +- isError + +Instance Property + +# isError + +A Boolean value indicating whether this is an error object. + +CloudKit JS 1.0+ + +readonly attribute Boolean isError; + +## Discussion + +This property is always `true`; for example, use this method when processing the results of operations that may contain errors. + +## See Also + +### Handling Errors + +`isCKError` + +A Boolean value indicating whether this is a CloudKit error object. + +`ckErrorCode` + +The error code for this error. + +`isServerError` + +A Boolean value indicating whether a server error occurred. + +`serverErrorCode` + +The error code generated by the server. + +`reason` + +A description of the error that occurred. + +`retryAfter` + +The suggested time to wait before trying this operation again. + +`uuid` + +A unique identifier for this error. + +`redirectURL` + +A redirect URL for the user to securely sign in with the user’s Apple ID. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/isckerror + +- CloudKit JS +- CloudKit.CKError +- isCKError + +Instance Property + +# isCKError + +A Boolean value indicating whether this is a CloudKit error object. + +CloudKit JS 1.0+ + +readonly attribute Boolean isCKError; + +## See Also + +### Handling Errors + +`isError` + +A Boolean value indicating whether this is an error object. + +`ckErrorCode` + +The error code for this error. + +`isServerError` + +A Boolean value indicating whether a server error occurred. + +`serverErrorCode` + +The error code generated by the server. + +`reason` + +A description of the error that occurred. + +`retryAfter` + +The suggested time to wait before trying this operation again. + +`uuid` + +A unique identifier for this error. + +`redirectURL` + +A redirect URL for the user to securely sign in with the user’s Apple ID. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/ckerrorcode + +- CloudKit JS +- CloudKit.CKError +- ckErrorCode + +Instance Property + +# ckErrorCode + +The error code for this error. + +CloudKit JS 1.0+ + +readonly attribute String ckErrorCode; + +## Discussion + +Possible values are described in Errors. + +## See Also + +### Handling Errors + +`isError` + +A Boolean value indicating whether this is an error object. + +`isCKError` + +A Boolean value indicating whether this is a CloudKit error object. + +`isServerError` + +A Boolean value indicating whether a server error occurred. + +`serverErrorCode` + +The error code generated by the server. + +`reason` + +A description of the error that occurred. + +`retryAfter` + +The suggested time to wait before trying this operation again. + +`uuid` + +A unique identifier for this error. + +`redirectURL` + +A redirect URL for the user to securely sign in with the user’s Apple ID. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/isservererror + +- CloudKit JS +- CloudKit.CKError +- isServerError + +Instance Property + +# isServerError + +A Boolean value indicating whether a server error occurred. + +CloudKit JS 1.0+ + +readonly attribute Boolean isServerError; + +## Discussion + +`true` if a server error occurred; otherwise, `false`. + +## See Also + +### Handling Errors + +`isError` + +A Boolean value indicating whether this is an error object. + +`isCKError` + +A Boolean value indicating whether this is a CloudKit error object. + +`ckErrorCode` + +The error code for this error. + +`serverErrorCode` + +The error code generated by the server. + +`reason` + +A description of the error that occurred. + +`retryAfter` + +The suggested time to wait before trying this operation again. + +`uuid` + +A unique identifier for this error. + +`redirectURL` + +A redirect URL for the user to securely sign in with the user’s Apple ID. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/servererrorcode + +- CloudKit JS +- CloudKit.CKError +- serverErrorCode + +Instance Property + +# serverErrorCode + +The error code generated by the server. + +CloudKit JS 1.0+ + +readonly attribute String serverErrorCode; + +## Discussion + +Possible values are described in Error Codes in CloudKit Web Services Reference. + +## See Also + +### Handling Errors + +`isError` + +A Boolean value indicating whether this is an error object. + +`isCKError` + +A Boolean value indicating whether this is a CloudKit error object. + +`ckErrorCode` + +The error code for this error. + +`isServerError` + +A Boolean value indicating whether a server error occurred. + +`reason` + +A description of the error that occurred. + +`retryAfter` + +The suggested time to wait before trying this operation again. + +`uuid` + +A unique identifier for this error. + +`redirectURL` + +A redirect URL for the user to securely sign in with the user’s Apple ID. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/reason + +- CloudKit JS +- CloudKit.CKError +- reason + +Instance Property + +# reason + +A description of the error that occurred. + +CloudKit JS 1.0+ + +readonly attribute String reason; + +## Discussion + +Possible values are described in Errors. + +## See Also + +### Handling Errors + +`isError` + +A Boolean value indicating whether this is an error object. + +`isCKError` + +A Boolean value indicating whether this is a CloudKit error object. + +`ckErrorCode` + +The error code for this error. + +`isServerError` + +A Boolean value indicating whether a server error occurred. + +`serverErrorCode` + +The error code generated by the server. + +`retryAfter` + +The suggested time to wait before trying this operation again. + +`uuid` + +A unique identifier for this error. + +`redirectURL` + +A redirect URL for the user to securely sign in with the user’s Apple ID. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/retryafter + +- CloudKit JS +- CloudKit.CKError +- retryAfter + +Instance Property + +# retryAfter + +The suggested time to wait before trying this operation again. + +CloudKit JS 1.0+ + +readonly attribute Number retryAfter; + +## Discussion + +If this key is `null`, the operation can’t be retried. + +## See Also + +### Handling Errors + +`isError` + +A Boolean value indicating whether this is an error object. + +`isCKError` + +A Boolean value indicating whether this is a CloudKit error object. + +`ckErrorCode` + +The error code for this error. + +`isServerError` + +A Boolean value indicating whether a server error occurred. + +`serverErrorCode` + +The error code generated by the server. + +`reason` + +A description of the error that occurred. + +`uuid` + +A unique identifier for this error. + +`redirectURL` + +A redirect URL for the user to securely sign in with the user’s Apple ID. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/uuid + +- CloudKit JS +- CloudKit.CKError +- uuid + +Instance Property + +# uuid + +A unique identifier for this error. + +CloudKit JS 1.0+ + +readonly attribute String uuid; + +## See Also + +### Handling Errors + +`isError` + +A Boolean value indicating whether this is an error object. + +`isCKError` + +A Boolean value indicating whether this is a CloudKit error object. + +`ckErrorCode` + +The error code for this error. + +`isServerError` + +A Boolean value indicating whether a server error occurred. + +`serverErrorCode` + +The error code generated by the server. + +`reason` + +A description of the error that occurred. + +`retryAfter` + +The suggested time to wait before trying this operation again. + +`redirectURL` + +A redirect URL for the user to securely sign in with the user’s Apple ID. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/redirecturl + +- CloudKit JS +- CloudKit.CKError +- redirectURL + +Instance Property + +# redirectURL + +A redirect URL for the user to securely sign in with the user’s Apple ID. + +CloudKit JS 1.0+ + +readonly attribute String redirectURL; + +## Discussion + +Open this URL in a dialog or full-page redirect. + +## See Also + +### Handling Errors + +`isError` + +A Boolean value indicating whether this is an error object. + +`isCKError` + +A Boolean value indicating whether this is a CloudKit error object. + +`ckErrorCode` + +The error code for this error. + +`isServerError` + +A Boolean value indicating whether a server error occurred. + +`serverErrorCode` + +The error code generated by the server. + +`reason` + +A description of the error that occurred. + +`retryAfter` + +The suggested time to wait before trying this operation again. + +`uuid` + +A unique identifier for this error. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/recordname + +- CloudKit JS +- CloudKit.CKError +- recordName + +Instance Property + +# recordName + +The name of the record that the operation failed on. + +CloudKit JS 1.0+ + +readonly attribute String recordName; + +## Discussion + +This property value is `Undefined` if the error is unrelated to a record operation. + +## See Also + +### Identifying the Operation + +`subscriptionID` + +A string that is a unique identifier for the subscription where the error occurred. + +`zoneID` + +The record zone in the database where the error occurred. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/subscriptionid + +- CloudKit JS +- CloudKit.CKError +- subscriptionID + +Instance Property + +# subscriptionID + +A string that is a unique identifier for the subscription where the error occurred. + +CloudKit JS 1.0+ + +readonly attribute String subscriptionID; + +## Discussion + +This property value is `Undefined` if the error is unrelated to a subscription operation. + +## See Also + +### Identifying the Operation + +`recordName` + +The name of the record that the operation failed on. + +`zoneID` + +The record zone in the database where the error occurred. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/zoneid + +- CloudKit JS +- CloudKit.CKError +- zoneID + +Instance Property + +# zoneID + +The record zone in the database where the error occurred. + +CloudKit JS 1.0+ + +readonly attribute `CloudKit.ZoneID` zoneID; + +## Discussion + +This property value is `Undefined` if the error is unrelated to a zone operation. + +## See Also + +### Identifying the Operation + +`recordName` + +The name of the record that the operation failed on. + +`subscriptionID` + +A string that is a unique identifier for the subscription where the error occurred. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/errors + +Collection + +- CloudKit JS +- CloudKit.CKError +- Errors + +API Collection + +# Errors + +The errors that may occur when posting requests. + +## Topics + +### Constants + +`ACCESS_DENIED` + +You don’t have permission to access the endpoint, record, zone, or database. + +`ATOMIC_ERROR` + +An atomic batch operation failed. + +`AUTH_PERSIST_ERROR` + +`AUTHENTICATION_FAILED` + +Authentication was rejected. + +`AUTHENTICATION_REQUIRED` + +The request requires authentication but none was provided. + +`BAD_REQUEST` + +The request was not valid. + +`CONFIGURATION_ERROR` + +CloudKit JS configuration error. For example, no containers are configured. + +`CONFLICT` + +The `recordChangeTag` value expired. (Retry the request with the latest tag.) + +`EXISTS` + +The resource that you attempted to create already exists. + +`INTERNAL_ERROR` + +An internal error occurred. + +`INVALID_ARGUMENTS` + +The parameters you provided for this method are invalid. + +`NETWORK_ERROR` + +A network error occurred, such as a connection time out. + +`NOT_FOUND` + +The resource was not found. + +`QUOTA_EXCEEDED` + +If accessing the public database, you exceeded the app’s quota. If accessing the private database, you exceeded the user’s iCloud quota. + +`SERVICE_UNAVAILABLE` + +The CloudKit service could not be reached. + +`SHARE_UI_TIMEOUT` + +The share UI failed to load and timed out. + +`SIGN_IN_FAILED` + +The user failed to sign in. + +`THROTTLED` + +The request was throttled. Try the request again later. + +`TRY_AGAIN_LATER` + +An internal error occurred. Try the request again. + +`UNEXPECTED_SERVER_RESPONSE` + +CloudKit JS was not able to decode the server response. + +`UNIQUE_FIELD_ERROR` + +The server rejected the request because there was a conflict with a unique field. + +`UNKNOWN_ERROR` + +An unknown error occurred. For example, if the server returns an error that is not recognized by the version of CloudKit JS you are using. + +`VALIDATING_REFERENCE_ERROR` + +The request violates a validating reference constraint. + +`ZONE_NOT_FOUND` + +The zone specified in the request was not found. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/iserror) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/isckerror) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/ckerrorcode) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/isservererror) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/servererrorcode) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/reason) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/retryafter) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/uuid) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/redirecturl) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/recordname) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/subscriptionid) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.ckerror/zoneid) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/errors) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/publicclouddatabase + +- CloudKit JS +- CloudKit.Container +- publicCloudDatabase + +Instance Property + +# publicCloudDatabase + +The database containing the data shared by all users. + +CloudKit JS 1.0+ + +readonly attribute `CloudKit.Database` publicCloudDatabase; + +## See Also + +### Getting the Public and Private Databases + +`privateCloudDatabase` + +The database containing the user’s private data. + +`sharedCloudDatabase` + +The database containing shared records accepted by the current user. + +`getDatabaseWithDatabaseScope` + +Returns the specified (public, private, or shared) database. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/privateclouddatabase + +- CloudKit JS +- CloudKit.Container +- privateCloudDatabase + +Instance Property + +# privateCloudDatabase + +The database containing the user’s private data. + +CloudKit JS 1.0+ + +readonly attribute `CloudKit.Database` privateCloudDatabase; + +## See Also + +### Getting the Public and Private Databases + +`publicCloudDatabase` + +The database containing the data shared by all users. + +`sharedCloudDatabase` + +The database containing shared records accepted by the current user. + +`getDatabaseWithDatabaseScope` + +Returns the specified (public, private, or shared) database. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/sharedclouddatabase + +- CloudKit JS +- CloudKit.Container +- sharedCloudDatabase + +Instance Property + +# sharedCloudDatabase + +The database containing shared records accepted by the current user. + +CloudKit JS 1.0+ + +readonly attribute `CloudKit.Database` sharedCloudDatabase; + +## Discussion + +The shared database allows the current user (a participant) to access records shared by other users (owners). Shared records are stored in the owner’s container and count towards the owner’s iCloud account storage quota. + +## See Also + +### Getting the Public and Private Databases + +`publicCloudDatabase` + +The database containing the data shared by all users. + +`privateCloudDatabase` + +The database containing the user’s private data. + +`getDatabaseWithDatabaseScope` + +Returns the specified (public, private, or shared) database. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/getdatabasewithdatabasescope + +- CloudKit JS +- CloudKit.Container +- getDatabaseWithDatabaseScope + +Instance Method + +# getDatabaseWithDatabaseScope + +Returns the specified (public, private, or shared) database. + +CloudKit JS 1.0+ + +`CloudKit.Database` getDatabaseWithDatabaseScope( +`CloudKit.DatabaseScope` databaseScope +); + +## Parameters + +`databaseScope` + +Specifies the type of database to return. + +## Return Value + +The specified database. + +## Discussion + +This is a convenience method that you can use instead of the specific properties. + +## See Also + +### Getting the Public and Private Databases + +`publicCloudDatabase` + +The database containing the data shared by all users. + +`privateCloudDatabase` + +The database containing the user’s private data. + +`sharedCloudDatabase` + +The database containing shared records accepted by the current user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/containeridentifier + +- CloudKit JS +- CloudKit.Container +- containerIdentifier + +Instance Property + +# containerIdentifier + +The string that identifies the app’s container. + +CloudKit JS 1.0+ + +readonly attribute String containerIdentifier; + +## See Also + +### Getting the Identifier and Environment + +`environment` + +The container environment, either development or production. + +`apnsEnvironment` + +The Apple Push Notification service (APNs) environment associated with this container. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/environment + +- CloudKit JS +- CloudKit.Container +- environment + +Instance Property + +# environment + +The container environment, either development or production. + +CloudKit JS 1.0+ + +attribute String environment; + +## Discussion + +Possible values are `CloudKit`. `DEVELOPMENT_ENVIRONMENT` and `CloudKit`. `PRODUCTION_ENVIRONMENT`. + +## See Also + +### Getting the Identifier and Environment + +`containerIdentifier` + +The string that identifies the app’s container. + +`apnsEnvironment` + +The Apple Push Notification service (APNs) environment associated with this container. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/apnsenvironment + +- CloudKit JS +- CloudKit.Container +- apnsEnvironment + +Instance Property + +# apnsEnvironment + +The Apple Push Notification service (APNs) environment associated with this container. + +CloudKit JS 1.0+ + +attribute String apnsEnvironment; + +## Discussion + +Possible values are `CloudKit`. `DEVELOPMENT_ENVIRONMENT` and `CloudKit`. `PRODUCTION_ENVIRONMENT`. + +## See Also + +### Getting the Identifier and Environment + +`containerIdentifier` + +The string that identifies the app’s container. + +`environment` + +The container environment, either development or production. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/setupauth + +- CloudKit JS +- CloudKit.Container +- setUpAuth + +Instance Method + +# setUpAuth + +Determines whether a user is signed in and presents an appropriate sign in or sign out button. + +CloudKit JS 1.0+ + +## Return Value + +A `Promise` that resolves to a `CloudKit.UserIdentity` dictionary if an active CloudKit session was found; otherwise, `null`. If an error occurs, a `Promise` object that rejects to a `CKError` object. + +## Discussion + +Use the `setUpAuth` method to determine whether the user is authenticated and to display the appropriate button. + +var myContainer = CloudKit.getDefaultContainer(); + +myContainer.setUpAuth().then(function(userIdentity) { +if(userIdentity) { +// The user is authenticated +} +}); + +In the function, use the `userRecordName` property to get the user record name from the `CloudKit.UserIdentity` parameter. + +The `setUpAuth` method displays the appropriate buttons only if the required DOM elements are found. If the user is not signed in, the method displays a sign-in button; otherwise, it displays a sign-out button. + +You can call this method multiple times. For example, call this method to determine if a previous CloudKit session is still valid, and call this method later to display the buttons after you add the required DOM elements. + +## See Also + +### Authenticating Users + +`whenUserSignsIn` + +Returns an object representing a deferred or asynchronous operation that resolves when the user signs in. + +`whenUserSignsOut` + +Returns an object representing a deferred or asynchronous operation that resolves when the user signs out. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/whenusersignsin + +- CloudKit JS +- CloudKit.Container +- whenUserSignsIn + +Instance Method + +# whenUserSignsIn + +Returns an object representing a deferred or asynchronous operation that resolves when the user signs in. + +CloudKit JS 1.0+ + +## Return Value + +A `Promise` object that resolves to a `CloudKit.UserIdentity` dictionary when the user signs in, or rejects to a `CKError` object. + +## Discussion + +Use the `whenUserSignsIn` method to call a function when the user signs in. + +myContainer.whenUserSignsIn().then(function(userIdentity) { +// The user signed in +}); + +## See Also + +### Authenticating Users + +`setUpAuth` + +Determines whether a user is signed in and presents an appropriate sign in or sign out button. + +`whenUserSignsOut` + +Returns an object representing a deferred or asynchronous operation that resolves when the user signs out. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/whenusersignsout + +- CloudKit JS +- CloudKit.Container +- whenUserSignsOut + +Instance Method + +# whenUserSignsOut + +Returns an object representing a deferred or asynchronous operation that resolves when the user signs out. + +CloudKit JS 1.0+ + +## Return Value + +A `Promise` object that resolves to `Undefined` when the user signs out, or rejects to a `CKError` object. + +## Discussion + +Use the `whenUserSignsOut` method to call a function when the user signs out. + +myContainer.whenUserSignsOut().then(function() { +// The user signed out +}); + +## See Also + +### Authenticating Users + +`setUpAuth` + +Determines whether a user is signed in and presents an appropriate sign in or sign out button. + +`whenUserSignsIn` + +Returns an object representing a deferred or asynchronous operation that resolves when the user signs in. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/fetchcurrentuseridentity + +- CloudKit JS +- CloudKit.Container +- fetchCurrentUserIdentity + +Instance Method + +# fetchCurrentUserIdentity + +Fetches information about the current user asynchronously. + +CloudKit JS 1.0+ + +## Return Value + +A `Promise` object that resolves to a `CloudKit.UserIdentity` dictionary if the current user is found, or rejects to a `CKError` object. + +## Discussion + +If the current user is discoverable, the `CloudKit.UserIdentity` dictionary contains a `nameComponents` key that you can use to get the user’s first and last name. + +## See Also + +### Discovering Users + +`discoverAllUserIdentities` + +Fetches all user identities in the current user’s address book. + +`discoverUserIdentities` + +Fetches all users in the specified array. + +`discoverUserIdentityWithEmailAddress` + +Fetches information about a single user based on the user’s email address. + +`discoverUserIdentityWithPhoneNumber` + +Fetches information about a single user based on the user’s phone number. + +`discoverUserIdentityWithUserRecordName` + +Fetches information about a single user using the record name. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/discoveralluseridentities + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/discoveruseridentities + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/discoveruseridentitywithemailaddress + +- CloudKit JS +- CloudKit.Container +- discoverUserIdentityWithEmailAddress + +Instance Method + +# discoverUserIdentityWithEmailAddress + +Fetches information about a single user based on the user’s email address. + +CloudKit JS 1.0+ + +String emailAddress +); + +## Parameters + +`emailAddress` + +The user’s email address. + +## Return Value + +A `Promise` object that resolves to `CloudKit.UserIdentitiesResponse` object, or rejects to a `CKError` object. + +## Discussion + +Use this method to get the ID of a user based on the user’s email address. The user must meet the following criteria: + +- The user must be in the current user’s address book. + +- The user must have run the app. + +- The user must have granted the permission to be discovered for this container. + +## See Also + +### Discovering Users + +`fetchCurrentUserIdentity` + +Fetches information about the current user asynchronously. + +`discoverAllUserIdentities` + +Fetches all user identities in the current user’s address book. + +`discoverUserIdentities` + +Fetches all users in the specified array. + +`discoverUserIdentityWithPhoneNumber` + +Fetches information about a single user based on the user’s phone number. + +`discoverUserIdentityWithUserRecordName` + +Fetches information about a single user using the record name. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/discoveruseridentitywithphonenumber + +- CloudKit JS +- CloudKit.Container +- discoverUserIdentityWithPhoneNumber + +Instance Method + +# discoverUserIdentityWithPhoneNumber + +Fetches information about a single user based on the user’s phone number. + +CloudKit JS 1.0+ + +String phoneNumber +); + +## Parameters + +`phoneNumber` + +The user’s phone number. + +## Return Value + +A `Promise` object that resolves to `CloudKit.UserIdentitiesResponse` object, or rejects to a `CKError` object. + +## Discussion + +Use this method to get the ID of a user based on the user’s phone number. The user must meet the following criteria: + +- The user must be in the current user’s address book. + +- The user must have run the app. + +- The user must have granted the permission to be discovered for this container. + +## See Also + +### Discovering Users + +`fetchCurrentUserIdentity` + +Fetches information about the current user asynchronously. + +`discoverAllUserIdentities` + +Fetches all user identities in the current user’s address book. + +`discoverUserIdentities` + +Fetches all users in the specified array. + +`discoverUserIdentityWithEmailAddress` + +Fetches information about a single user based on the user’s email address. + +`discoverUserIdentityWithUserRecordName` + +Fetches information about a single user using the record name. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/discoveruseridentitywithuserrecordname + +- CloudKit JS +- CloudKit.Container +- discoverUserIdentityWithUserRecordName + +Instance Method + +# discoverUserIdentityWithUserRecordName + +Fetches information about a single user using the record name. + +CloudKit JS 1.0+ + +String userRecordName +); + +## Parameters + +`userRecordName` + +The name of the user record. + +## Return Value + +A `Promise` object that resolves to `CloudKit.UserIdentitiesResponse` object, or rejects to a `CKError` object. + +## Discussion + +Use this method to retrieve information about a user for whom you have the corresponding `name` property of the `User` record. The user must meet the following criteria: + +- The user must be in the current user’s address book. + +- The user must have run the app. + +- The user must have granted the permission to be discovered for this container. + +## See Also + +### Discovering Users + +`fetchCurrentUserIdentity` + +Fetches information about the current user asynchronously. + +`discoverAllUserIdentities` + +Fetches all user identities in the current user’s address book. + +`discoverUserIdentities` + +Fetches all users in the specified array. + +`discoverUserIdentityWithEmailAddress` + +Fetches information about a single user based on the user’s email address. + +`discoverUserIdentityWithPhoneNumber` + +Fetches information about a single user based on the user’s phone number. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/acceptshares + +- CloudKit JS +- CloudKit.Container +- acceptShares + +Instance Method + +# acceptShares + +Accepts a share—that is represented by a `shortGUID`—on behalf of the current user. + +CloudKit JS 1.0+ + +String[] shortGUIDs +); + +## Parameters + +`shortGUIDs` + +One or more short GUIDs that represent shared records. + +## Return Value + +A `Promise` object that resolves to a `CloudKit.RecordInfosResponse` object, or rejects to a `CKError` object. + +## See Also + +### Accepting Shared Records + +`fetchRecordInfos` + +Returns information about a record for which you have a `shortGUID` property. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/fetchrecordinfos + +- CloudKit JS +- CloudKit.Container +- fetchRecordInfos + +Instance Method + +# fetchRecordInfos + +Returns information about a record for which you have a `shortGUID` property. + +CloudKit JS 1.0+ + +String[] shortGUIDs +); + +## Parameters + +`shortGUIDs` + +One or more short GUIDs that represent records you want to fetch information about. + +## Return Value + +A `Promise` object that resolves to a `CloudKit.RecordInfosResponse` object, or rejects to a `CKError` object. + +## Discussion + +Use this method to show details about a record to a user before asking them to accept a share. + +## See Also + +### Accepting Shared Records + +`acceptShares` + +Accepts a share—that is represented by a `shortGUID`—on behalf of the current user. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/addnotificationlistener + +- CloudKit JS +- CloudKit.Container +- addNotificationListener + +Instance Method + +# addNotificationListener + +Adds a function to call when a push notification occurs. + +CloudKit JS 1.0+ + +void addNotificationListener( +function listener +); + +## Parameters + +`listener` + +The function to call when a push notification occurs. The function must have a single argument that is a `CloudKit.Notification` object. + +## Discussion + +To subscribe to changes and register for push notifications, see `saveSubscription` in the `CloudKit.Database` class. + +## See Also + +### Receiving Notifications + +`removeNotificationListener` + +Removes a function to call when a push notification occurs. + +`registerForNotifications` + +Registers to receive push notifications. + +`unregisterForNotifications` + +Unregisters to receive push notifications. + +`isRegisteredForNotifications` + +Boolean value indicating whether this container is registered to receive push notifications. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/removenotificationlistener + +- CloudKit JS +- CloudKit.Container +- removeNotificationListener + +Instance Method + +# removeNotificationListener + +Removes a function to call when a push notification occurs. + +CloudKit JS 1.0+ + +void removeNotificationListener( +function listener +); + +## See Also + +### Receiving Notifications + +`addNotificationListener` + +Adds a function to call when a push notification occurs. + +`registerForNotifications` + +Registers to receive push notifications. + +`unregisterForNotifications` + +Unregisters to receive push notifications. + +`isRegisteredForNotifications` + +Boolean value indicating whether this container is registered to receive push notifications. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/registerfornotifications + +- CloudKit JS +- CloudKit.Container +- registerForNotifications + +Instance Method + +# registerForNotifications + +Registers to receive push notifications. + +CloudKit JS 1.0+ + +void registerForNotifications(); + +## Discussion + +To subscribe to changes and register for push notifications, see `saveSubscription` in the `CloudKit.Database` class. + +## See Also + +### Receiving Notifications + +`addNotificationListener` + +Adds a function to call when a push notification occurs. + +`removeNotificationListener` + +Removes a function to call when a push notification occurs. + +`unregisterForNotifications` + +Unregisters to receive push notifications. + +`isRegisteredForNotifications` + +Boolean value indicating whether this container is registered to receive push notifications. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/unregisterfornotifications + +- CloudKit JS +- CloudKit.Container +- unregisterForNotifications + +Instance Method + +# unregisterForNotifications + +Unregisters to receive push notifications. + +CloudKit JS 1.0+ + +void unregisterForNotifications(); + +## See Also + +### Receiving Notifications + +`addNotificationListener` + +Adds a function to call when a push notification occurs. + +`removeNotificationListener` + +Removes a function to call when a push notification occurs. + +`registerForNotifications` + +Registers to receive push notifications. + +`isRegisteredForNotifications` + +Boolean value indicating whether this container is registered to receive push notifications. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/isregisteredfornotifications + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/tostring + +- CloudKit JS +- CloudKit.Container +- toString + +Instance Method + +# toString + +Returns a string representation of this `CloudKit.Container` object. + +CloudKit JS 1.0+ + +String toString(); + +## Return Value + +A string representation of the container. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/publicclouddatabase) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/privateclouddatabase) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/sharedclouddatabase) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/getdatabasewithdatabasescope) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/containeridentifier) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/environment) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/apnsenvironment) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/setupauth) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/whenusersignsin) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/whenusersignsout) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/fetchcurrentuseridentity) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/discoveralluseridentities) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/discoveruseridentities) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/discoveruseridentitywithemailaddress) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/discoveruseridentitywithphonenumber) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/discoveruseridentitywithuserrecordname) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/acceptshares) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/fetchrecordinfos) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/addnotificationlistener) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/removenotificationlistener) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/registerfornotifications) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/unregisterfornotifications) + +# The page you're looking for can't be found. + +Search developer.apple.comSearch Icon + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/isregisteredfornotifications) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.container/tostring) + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.notification/containeridentifier + + + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.notification/notificationid + +- CloudKit JS +- CloudKit.Notification +- notificationID + +Instance Property + +# notificationID + +A unique identifier for this notification. + +CloudKit JS 1.0+ + +readonly attribute String notificationID; + +## See Also + +### Getting Identifiers + +`containerIdentifier` + +The identifier of the container that generated this notification. + +`subscriptionID` + +The identifier for the associated subscription. + +`zoneID` + +The identifier of the zone that this notification belongs to. + +--- + +# https://developer.apple.com/documentation/cloudkitjs/cloudkit.notification/subscriptionid + +- CloudKit JS +- CloudKit.Notification +- subscriptionID + +Instance Property + +# subscriptionID + +The identifier for the associated subscription. + +CloudKit JS 1.0+ + +readonly attribute String subscriptionID; + +## See Also + +### Getting Identifiers + +`containerIdentifier` + +The identifier of the container that generated this notification. + +`notificationID` + +A unique identifier for this notification. + +`zoneID` + +The identifier of the zone that this notification belongs to. + +--- + diff --git a/.claude/docs/data-sources-api-research.md b/.claude/docs/data-sources-api-research.md new file mode 100644 index 00000000..60e9f9ff --- /dev/null +++ b/.claude/docs/data-sources-api-research.md @@ -0,0 +1,730 @@ +# Data Sources & API Research + +This document contains detailed research on all external data sources and MistKit API patterns needed for implementing the Bushel CloudKit demo tool. + +## Table of Contents + +1. [xcodereleases.com API](#xcoderereleasescom-api) +2. [swiftversion.net Scraping](#swiftversionnet-scraping) +3. [MistKit API Patterns](#mistkit-api-patterns) + +--- + +## xcodereleases.com API + +### API Endpoint + +**URL**: https://xcodereleases.com/data.json +**Format**: JSON +**Authentication**: None required +**Method**: GET + +### Data Structure + +```json +{ + "_dateOrder": 20251103, + "_swiftOrder": 6002001, + "_versionOrder": 26001000999, + "checksums": { + "sha1": "24df34c049bf695f2ef7262815828c52ed5479fe" + }, + "compilers": { + "clang": [ + { + "build": "1700.4.4.1", + "number": "17.0.0", + "release": { + "release": true + } + } + ], + "swift": [ + { + "build": "6.2.1.4.8", + "number": "6.2.1", + "release": { + "release": true + } + } + ] + }, + "date": { + "day": 3, + "month": 11, + "year": 2025 + }, + "links": { + "download": { + "architectures": ["arm64", "x86_64"], + "url": "https://download.developer.apple.com/Developer_Tools/Xcode_26.1/XcodeXIP_26.1_Universal.xip" + }, + "notes": { + "url": "https://developer.apple.com/documentation/xcode-release-notes/xcode-26_1-release-notes" + } + }, + "name": "Xcode", + "requires": "15.6", + "sdks": { + "iOS": [{"build": "23B77", "number": "26.1", "release": {"release": true}}], + "macOS": [{"build": "25B74", "number": "26.1", "release": {"release": true}}], + "tvOS": [{"build": "23J576", "number": "26.1", "release": {"release": true}}], + "visionOS": [{"build": "23N45", "number": "26.1", "release": {"release": true}}], + "watchOS": [{"build": "23S34", "number": "26.1", "release": {"release": true}}] + }, + "version": { + "build": "17B55", + "number": "26.1", + "release": { + "release": true + } + } +} +``` + +### Key Fields + +| Field | Type | Description | Mapping | +|-------|------|-------------|---------| +| `version.number` | String | Xcode version | → `XcodeVersion.version` | +| `version.build` | String | Build identifier | → `XcodeVersion.buildNumber` | +| `version.release.release` | Boolean | Is final release | → `!XcodeVersion.isPrerelease` | +| `date` | Object | Release date | → `XcodeVersion.releaseDate` | +| `requires` | String | Minimum macOS version | → `XcodeVersion.minimumMacOS` (Reference) | +| `compilers.swift[0].number` | String | Swift version | → `XcodeVersion.includedSwiftVersion` (Reference) | +| `sdks` | Object | SDK versions | → `XcodeVersion.sdkVersions` (JSON) | +| `links.download.url` | String | Download URL | → `XcodeVersion.downloadURL` | +| `checksums.sha1` | String | SHA-1 checksum | (Optional field) | + +### Swift Parsing Code + +```swift +import Foundation + +struct XcodeRelease: Codable { + let _dateOrder: Int + let _swiftOrder: Int + let _versionOrder: Int + let checksums: Checksums? + let compilers: Compilers + let date: ReleaseDate + let links: Links + let name: String + let requires: String + let sdks: SDKs + let version: Version + + struct Checksums: Codable { + let sha1: String + } + + struct Compilers: Codable { + let clang: [Compiler] + let swift: [Compiler] + } + + struct Compiler: Codable { + let build: String + let number: String + let release: Release + } + + struct Release: Codable { + let release: Bool? + let beta: Int? + let rc: Int? + } + + struct ReleaseDate: Codable { + let day: Int + let month: Int + let year: Int + + var toDate: Date { + let components = DateComponents(year: year, month: month, day: day) + return Calendar.current.date(from: components)! + } + } + + struct Links: Codable { + let download: Download + let notes: Notes + + struct Download: Codable { + let architectures: [String] + let url: String + } + + struct Notes: Codable { + let url: String + } + } + + struct SDKs: Codable { + let iOS: [SDK] + let macOS: [SDK] + let tvOS: [SDK] + let visionOS: [SDK] + let watchOS: [SDK] + } + + struct SDK: Codable { + let build: String + let number: String + let release: Release + } + + struct Version: Codable { + let build: String + let number: String + let release: Release + } + + var isPrerelease: Bool { + version.release.beta != nil || version.release.rc != nil + } + + var swiftVersion: String { + compilers.swift.first?.number ?? "Unknown" + } + + var sdkVersionsJSON: String { + let dict: [String: String] = [ + "macOS": sdks.macOS.first?.number ?? "", + "iOS": sdks.iOS.first?.number ?? "", + "watchOS": sdks.watchOS.first?.number ?? "", + "tvOS": sdks.tvOS.first?.number ?? "", + "visionOS": sdks.visionOS.first?.number ?? "" + ] + let data = try! JSONEncoder().encode(dict) + return String(data: data, encoding: .utf8)! + } +} + +// Usage +func fetchXcodeReleases() async throws -> [XcodeRelease] { + let url = URL(string: "https://xcodereleases.com/data.json")! + let (data, _) = try await URLSession.shared.data(from: url) + let releases = try JSONDecoder().decode([XcodeRelease].self, from: data) + return releases +} +``` + +--- + +## swiftversion.net Scraping + +### Website URL + +**URL**: https://swiftversion.net +**Format**: HTML Table +**Authentication**: None required +**Method**: GET + HTML Parsing + +### HTML Structure + +```html + + + + + + + + + + + + + + + + + + + + +
DateSwiftXcode
15 Sep 256.226
31 Mar 256.116.3
+``` + +### Data Format + +| Date | Swift | Xcode | +|------|-------|-------| +| 15 Sep 25 | 6.2 | 26 | +| 31 Mar 25 | 6.1 | 16.3 | +| 16 Sep 24 | 6.0 | 16.0 | + +**Date Format**: `DD Mon YY` (e.g., "15 Sep 25") +**Swift Version**: Semantic version (e.g., "6.2") +**Xcode Version**: Major version only (e.g., "26") + +### Key Fields + +| Field | Type | Description | Mapping | +|-------|------|-------------|---------| +| Date | String | Release date | → `SwiftVersion.releaseDate` (parse date) | +| Swift | String | Swift version | → `SwiftVersion.version` | +| Xcode | String | Xcode major version | (Used to link with XcodeVersion) | + +### Swift Parsing Code + +```swift +import Foundation +import SwiftSoup // Add dependency: https://github.com/scinfu/SwiftSoup + +struct SwiftVersionEntry { + let date: Date + let swiftVersion: String + let xcodeVersion: String +} + +func fetchSwiftVersions() async throws -> [SwiftVersionEntry] { + let url = URL(string: "https://swiftversion.net")! + let (data, _) = try await URLSession.shared.data(from: url) + let html = String(data: data, encoding: .utf8)! + + let doc = try SwiftSoup.parse(html) + let rows = try doc.select("tbody tr.table-entry") + + var entries: [SwiftVersionEntry] = [] + let dateFormatter = DateFormatter() + dateFormatter.dateFormat = "dd MMM yy" + + for row in rows { + let cells = try row.select("td") + guard cells.count == 3 else { continue } + + let dateStr = try cells[0].text() + let swiftVer = try cells[1].text() + let xcodeVer = try cells[2].text() + + guard let date = dateFormatter.date(from: dateStr) else { + print("Warning: Could not parse date: \(dateStr)") + continue + } + + entries.append(SwiftVersionEntry( + date: date, + swiftVersion: swiftVer, + xcodeVersion: xcodeVer + )) + } + + return entries +} +``` + +### Dependencies + +Add SwiftSoup to Package.swift: +```swift +dependencies: [ + .package(url: "https://github.com/scinfu/SwiftSoup.git", from: "2.6.0") +] +``` + +--- + +## MistKit API Patterns + +### Main Client Class + +**Type**: `CloudKitService` +**Location**: `Sources/MistKit/Service/CloudKitService.swift` + +### Initialization + +```swift +// Option 1: API Token Only (Public Database) +let service = try CloudKitService( + containerIdentifier: "iCloud.com.example.MyApp", + apiToken: apiToken +) + +// Option 2: Web Authentication (Private/Shared Database) +let service = try CloudKitService( + containerIdentifier: "iCloud.com.example.MyApp", + apiToken: apiToken, + webAuthToken: webAuthToken +) + +// Option 3: Custom TokenManager +let service = try CloudKitService( + containerIdentifier: "iCloud.com.example.MyApp", + tokenManager: tokenManager, + environment: .development, + database: .private +) +``` + +### Environment Configuration + +```bash +# .env file +CLOUDKIT_API_TOKEN=your_api_token_here +CLOUDKIT_CONTAINER=iCloud.com.example.MyApp +``` + +```swift +// Load from environment +let apiToken = ProcessInfo.processInfo.environment["CLOUDKIT_API_TOKEN"]! +let container = ProcessInfo.processInfo.environment["CLOUDKIT_CONTAINER"]! +``` + +### Field Values + +```swift +import MistKit + +// Simple types +let title: FieldValue = .string("Buy groceries") +let count: FieldValue = .int64(5) +let price: FieldValue = .double(19.99) +let isComplete: FieldValue = .boolean(true) +let createdAt: FieldValue = .date(Date()) + +// Reference to another record +let categoryRef: FieldValue = .reference( + FieldValue.Reference( + recordName: "category-123", + action: nil // or "DELETE_SELF" for cascade delete + ) +) + +// Location +let location: FieldValue = .location( + FieldValue.Location( + latitude: 37.7749, + longitude: -122.4194 + ) +) + +// List of values +let tags: FieldValue = .list([ + .string("urgent"), + .string("shopping") +]) +``` + +### Query Records + +```swift +func queryRecords(service: CloudKitService) async throws -> [RecordInfo] { + let records = try await service.queryRecords( + recordType: "RestoreImage", + limit: 100 + ) + + for record in records { + print("Record: \(record.recordName)") + + // Extract fields using pattern matching + if case .string(let version) = record.fields["version"] { + print(" Version: \(version)") + } + + if case .boolean(let isSigned) = record.fields["isSigned"] { + print(" Signed: \(isSigned)") + } + + if case .reference(let ref) = record.fields["minimumMacOS"] { + print(" Min macOS: \(ref.recordName)") + } + } + + return records +} +``` + +### Create Record + +```swift +func createRecord(service: CloudKitService) async throws { + let client = service.mistKitClient.client + + // Create field values + let fields: [String: Components.Schemas.FieldValue] = [ + "version": .init( + value: .stringValue("14.2.1"), + type: .string + ), + "buildNumber": .init( + value: .stringValue("23C71"), + type: .string + ), + "isSigned": .init( + value: .booleanValue(true), + type: nil + ), + "releaseDate": .init( + value: .dateTimeValue(Date().timeIntervalSince1970), + type: .dateTime + ) + ] + + // Create record operation + let operation = Components.Schemas.RecordOperation( + operationType: .create, + record: .init( + recordName: "RestoreImage-23C71", // Unique ID based on build + recordType: "RestoreImage", + recordChangeTag: nil, + fields: .init(additionalProperties: fields) + ) + ) + + // Execute modify + let response = try await client.modifyRecords( + .init( + path: .init( + version: "1", + container: service.containerIdentifier, + environment: service.environment.toComponentsEnvironment(), + database: service.database.toComponentsDatabase() + ), + body: .json(.init( + operations: [operation], + atomic: true + )) + ) + ) + + switch response { + case .ok: + print("Record created successfully") + default: + throw CloudKitError.httpErrorWithRawResponse( + statusCode: 400, + rawResponse: "Failed to create record" + ) + } +} +``` + +### Update Record + +```swift +func updateRecord( + service: CloudKitService, + recordName: String, + recordChangeTag: String +) async throws { + let client = service.mistKitClient.client + + let operation = Components.Schemas.RecordOperation( + operationType: .update, + record: .init( + recordName: recordName, + recordType: "RestoreImage", + recordChangeTag: recordChangeTag, // Required for optimistic locking + fields: .init(additionalProperties: [ + "isSigned": .init( + value: .booleanValue(false), + type: nil + ) + ]) + ) + ) + + let response = try await client.modifyRecords( + .init( + path: .init( + version: "1", + container: service.containerIdentifier, + environment: service.environment.toComponentsEnvironment(), + database: service.database.toComponentsDatabase() + ), + body: .json(.init( + operations: [operation], + atomic: true + )) + ) + ) +} +``` + +### Handle References + +```swift +func createWithReference(service: CloudKitService) async throws { + let client = service.mistKitClient.client + + // Create fields including reference + let fields: [String: Components.Schemas.FieldValue] = [ + "version": .init( + value: .stringValue("15.1"), + type: .string + ), + "minimumMacOS": .init( + value: .referenceValue( + .init( + recordName: "RestoreImage-23A344", // Reference to another record + action: nil // or .DELETE_SELF for cascade delete + ) + ), + type: .reference + ) + ] + + let operation = Components.Schemas.RecordOperation( + operationType: .create, + record: .init( + recordName: "XcodeVersion-15C65", + recordType: "XcodeVersion", + recordChangeTag: nil, + fields: .init(additionalProperties: fields) + ) + ) + + let response = try await client.modifyRecords( + .init( + path: .init( + version: "1", + container: service.containerIdentifier, + environment: service.environment.toComponentsEnvironment(), + database: service.database.toComponentsDatabase() + ), + body: .json(.init( + operations: [operation], + atomic: true + )) + ) + ) +} +``` + +### Batch Operations + +```swift +func batchCreate(service: CloudKitService, records: [RecordData]) async throws { + let client = service.mistKitClient.client + + // Create multiple operations + let operations = records.map { recordData in + Components.Schemas.RecordOperation( + operationType: .create, + record: .init( + recordName: recordData.id, + recordType: recordData.type, + recordChangeTag: nil, + fields: .init(additionalProperties: recordData.fields) + ) + ) + } + + // Execute all in one request + let response = try await client.modifyRecords( + .init( + path: .init( + version: "1", + container: service.containerIdentifier, + environment: service.environment.toComponentsEnvironment(), + database: service.database.toComponentsDatabase() + ), + body: .json(.init( + operations: operations, + atomic: true // All succeed or all fail + )) + ) + ) +} +``` + +### Error Handling + +```swift +do { + let records = try await service.queryRecords(recordType: "RestoreImage") +} catch let error as CloudKitError { + switch error { + case .httpErrorWithRawResponse(let statusCode, let response): + print("HTTP \(statusCode): \(response)") + case .networkError(let underlying): + print("Network error: \(underlying)") + default: + print("CloudKit error: \(error.localizedDescription)") + } +} catch let error as TokenManagerError { + print("Auth error: \(error)") +} +``` + +### Async/Await Patterns + +All MistKit operations are async: + +```swift +// Basic usage +let records = try await service.queryRecords(recordType: "RestoreImage") + +// With Task groups for parallel operations +await withThrowingTaskGroup(of: Void.self) { group in + group.addTask { + try await createRestoreImage(service) + } + group.addTask { + try await createXcodeVersion(service) + } + group.addTask { + try await createSwiftVersion(service) + } + + try await group.waitForAll() +} +``` + +### Key Files + +- **Main Service**: `Sources/MistKit/Service/CloudKitService.swift` +- **Service Operations**: `Sources/MistKit/Service/CloudKitService+Operations.swift` +- **Field Values**: `Sources/MistKit/FieldValue.swift` +- **Record Info**: `Sources/MistKit/Service/RecordInfo.swift` +- **Generated Client**: `Sources/MistKit/Generated/Client.swift` +- **Generated Types**: `Sources/MistKit/Generated/Types.swift` +- **Example Demo**: `Examples/Sources/MistDemo/MistDemo.swift` + +--- + +## Implementation Checklist + +### Phase 1: Data Fetchers + +- [ ] Implement xcodereleases.com JSON fetcher +- [ ] Implement swiftversion.net HTML scraper (with SwiftSoup) +- [ ] Integrate IPSWDownloads for ipsw.me +- [ ] Implement MESU XML parser +- [ ] Implement Mr. Macintosh scraper (if needed) + +### Phase 2: CloudKit Integration + +- [ ] Create wrapper functions for record create/update +- [ ] Implement RestoreImage record builder +- [ ] Implement XcodeVersion record builder +- [ ] Implement SwiftVersion record builder +- [ ] Handle CKReference relationships +- [ ] Implement batch operations + +### Phase 3: Sync Logic + +- [ ] Fetch data from all sources +- [ ] Deduplicate records (match by build/version) +- [ ] Create/update CloudKit records +- [ ] Handle reference resolution +- [ ] Implement incremental sync +- [ ] Add progress reporting + +### Phase 4: Export Logic + +- [ ] Query all records from CloudKit +- [ ] Serialize to JSON +- [ ] Support filtering options +- [ ] Pretty-print output + +### Phase 5: CLI Interface + +- [ ] Setup ArgumentParser +- [ ] Implement `sync` command with options +- [ ] Implement `export` command with options +- [ ] Add help documentation +- [ ] Environment variable configuration diff --git a/.claude/docs/firmware-wiki.md b/.claude/docs/firmware-wiki.md new file mode 100644 index 00000000..f64cc781 --- /dev/null +++ b/.claude/docs/firmware-wiki.md @@ -0,0 +1,133 @@ +# Firmware + +Source: TheAppleWiki - https://theapplewiki.com/wiki/Firmware +(Saved from PDF: Firmware - The Apple Wiki.pdf) + +A **firmware** is an IPSW file or OTA update ZIP file that contains everything needed to install the core operating system of a device. + +## Firmware Manifests + +To check for iOS, iPod, Apple TV, and HomePod mini updates, iTunes, Finder, Apple Configurator, and Apple Devices contact the main manifest at: +- **https://s.mzstatic.com/version** + +This manifest also contains carrier bundles. + +There are separate manifests for: +- **macOS**: https://mesu.apple.com/assets/macos/com_apple_macOSIPSW/com_apple_macOSIPSW.xml +- **bridgeOS**: https://mesu.apple.com/assets/bridgeos/com_apple_bridgeOSIPSW/com_apple_bridgeOSIPSW.xml +- **visionOS**: https://mesu.apple.com/assets/visionos/com_apple_visionOSIPSW/com_apple_visionOSIPSW.xml + +The first-generation Apple TV also uses a firmware manifest, found at: +- **https://mesu.apple.com/version.xml** + +It uses separate files, rather than consolidating them into an IPSW archive. + +## History + +The original use of the version manifest was to notify the user of iPod firmware updates. The notification directs the user to the Apple Support website to download iPod Updater. With iTunes 7.0, iPod Updater functionality was merged into iTunes, using IPSW files to hold the firmware. iTunes 7.3 extends the manifest and IPSW file format to support the iPhone. + +## Limitations + +There is no public manifest of IPSWs for any Apple Watch, HomePod (other than HomePod mini), or Apple TV 4K and later. These devices exclusively use OTA updates, and can be recovered using recoveryOS. Some IPSW files have been discovered for these devices through various means, but lack of a user-accessible Lightning or USB-C port renders it difficult to make use of them. + +## Firmware List (by device) + +### Release Firmware + +**Apple TV** +- 1.x · 2.x · 3.x · 4.x · 5.x · 6.x · 7.x · 9.x · 10.x · 11.x · 12.x · 13.x · 14.x · 15.x · 16.x · 17.x · 18.x · 26.x + +**Apple Vision** +- 1.x · 2.x · 26.x + +**Apple Watch** +- 1.x · 2.x · 3.x · 4.x · 5.x · 6.x · 7.x · 8.x · 9.x · 10.x · 11.x · 26.x + +**HomePod** +- 11.x · 12.x · 13.x · 14.x · 15.x · 16.x · 17.x · 18.x · 26.x + +**Mac** +- 1.x · 2.x · 3.x · 4.x · 6.x · 7.x · 8.x · 9.x · 10.0.x Cheetah · 10.1.x Puma · 10.2.x Jaguar · 10.3.x Panther · 10.4.x Tiger · 10.5.x Leopard · 10.6.x Snow Leopard · 10.7.x Lion · 10.8.x Mountain Lion · 10.9.x Mavericks · 10.10.x Yosemite · 10.11.x El Capitan · 10.12.x Sierra · 10.13.x High Sierra · 10.14.x Mojave · 10.15.x Catalina · 11.x Big Sur · 12.x Monterey · 13.x Ventura · 14.x Sonoma · 15.x Sequoia · 26.x Tahoe + +**Mac Server** +- 1.x · 10.0.x Cheetah · 10.1.x Puma · 10.2.x Jaguar · 10.3.x Panther · 10.4.x Tiger · 10.5.x Leopard · 10.6.x Snow Leopard · 10.7.x Lion · macOS Server + +**iBridge (T2 chip)** +- 1.x (embeddedOS) · 2.x · 3.x · 4.x · 5.x · 6.x · 7.x · 8.x · 9.x · 10.x + +**iPad** +- 3.x · 4.x · 5.x · 6.x · 7.x · 8.x · 9.x · 10.x · 11.x · 12.x · 13.x · 14.x · 15.x · 16.x · 17.x · 18.x · 26.x + +**iPad Air** +- 7.x · 8.x · 9.x · 10.x · 11.x · 12.x · 13.x · 14.x · 15.x · 16.x · 17.x · 18.x · 26.x + +**iPad Pro** +- 9.x · 10.x · 11.x · 12.x · 13.x · 14.x · 15.x · 16.x · 17.x · 18.x · 26.x + +**iPad mini** +- 6.x · 7.x · 8.x · 9.x · 10.x · 11.x · 12.x · 13.x · 14.x · 15.x · 16.x · 17.x · 18.x · 26.x + +**iPhone** +- 1.x · 2.x · 3.x · 4.x · 5.x · 6.x · 7.x · 8.x · 9.x · 10.x · 11.x · 12.x · 13.x · 14.x · 15.x · 16.x · 17.x · 18.x · 26.x + +**iPod touch** +- 1.x · 2.x · 3.x · 4.x · 5.x · 6.x · 7.x · 8.x · 9.x · 10.x · 11.x · 12.x · 13.x · 14.x · 15.x + +### Other Firmware Types + +- Preinstalled Firmware +- iPod Firmware +- iPod Recovery Firmware +- Mac Security Updates +- Mac Server Security Updates + +### Beta Firmware + +### OTA Updates + +### Rapid Security Responses + +### Beta Rapid Security Responses + +### RecoveryOSUpdates + +### Firmware Keys + +## External Links + +### Manifests + +**iOS, iPod, Apple TV, and HomePod mini**: +- https://s.mzstatic.com/version +- Old URL: https://itunes.apple.com/WebObjects/MZStore.woa/wa/com.apple.jingle.appserver.client.MZITunesClientCheck/version + +**bridgeOS**: +- https://mesu.apple.com/assets/bridgeos/com_apple_bridgeOSIPSW/com_apple_bridgeOSIPSW.xml + +**macOS**: +- https://mesu.apple.com/assets/macos/com_apple_macOSIPSW/com_apple_macOSIPSW.xml + +**visionOS**: +- https://mesu.apple.com/assets/visionos/com_apple_visionOSIPSW/com_apple_visionOSIPSW.xml + +## Key Insights for CloudKit Schema + +1. **Multiple firmware types**: IPSW files (full OS), OTA updates (incremental) +2. **macOS versioning**: Uses both legacy (10.x) and modern (11+) numbering +3. **Latest version number**: 26.x appears across all platforms (likely future release) +4. **Apple Silicon coverage**: Big Sur 11.x onwards for Apple Silicon Macs +5. **Manifest structure**: + - iOS/iPod/Apple TV/HomePod mini: Single manifest at s.mzstatic.com + - macOS/bridgeOS/visionOS: Separate MESU XML files +6. **Beta firmware**: Listed separately from release firmware +7. **OTA vs IPSW**: Different update mechanisms, both tracked in manifests + +## Relevance to MistKit Project + +For Bushel's macOS virtualization use case: +- Focus on **macOS manifest only**: `mesu.apple.com/assets/macos/com_apple_macOSIPSW/` +- Version coverage: Big Sur 11.x through current (26.x) +- IPSW files specifically for restore/install, not OTA updates +- MESU provides only latest signed version +- Need community sources (ipsw.me, Mr. Macintosh) for historical data +- Beta firmware requires separate tracking (not in main MESU manifest) diff --git a/.claude/docs/https_-swiftpackageindex.com-apple-swift-log-main-documentation-logging.md b/.claude/docs/https_-swiftpackageindex.com-apple-swift-log-main-documentation-logging.md new file mode 100644 index 00000000..b1361cad --- /dev/null +++ b/.claude/docs/https_-swiftpackageindex.com-apple-swift-log-main-documentation-logging.md @@ -0,0 +1,4313 @@ + + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging + +Framework + +# Logging + +A unified, performant, and ergonomic logging API for Swift. + +## Overview + +SwiftLog provides a logging API package designed to establish a common API the ecosystem can use. It allows packages to emit log messages without tying them to any specific logging implementation, while applications can choose any compatible logging backend. + +SwiftLog is an _API package_ which cuts the logging problem in half: + +1. A logging API (this package) + +2. Logging backend implementations (community-provided) + +This separation allows libraries to adopt the API while applications choose any compatible logging backend implementation without requiring changes from libraries. + +## Getting Started + +Use this package if you’re writing a cross-platform application (for example, Linux and macOS) or library, and want to target this logging API. + +### Adding the Dependency + +Add the dependency to your `Package.swift`: + +.package(url: "https://github.com/apple/swift-log", from: "1.6.0") + +And to your target: + +.target( +name: "YourTarget", +dependencies: [\ +.product(name: "Logging", package: "swift-log")\ +] +) + +### Basic Usage + +// Import the logging API +import Logging + +// Create a logger with a label +let logger = Logger(label: "MyLogger") + +// Use it to log messages +logger.info("Hello World!") + +This outputs: + +2025-10-24T17:26:47-0700 info MyLogger: [your_app] Hello World! + +### Default Behavior + +SwiftLog provides basic console logging via `StreamLogHandler`. By default it uses `stdout`, however, you can configure it to use `stderr` instead: + +LoggingSystem.bootstrap(StreamLogHandler.standardError) + +`StreamLogHandler` is primarily for convenience. For production applications, implement the `LogHandler` protocol directly or use a community-maintained backend. + +## Topics + +### Logging API + +Understanding Loggers and Log Handlers + +Learn how to create and configure loggers, set log levels, and use metadata to add context to your log messages. + +`struct Logger` + +A Logger emits log messages using methods that correspond to a log level. + +`enum LoggingSystem` + +The logging system is a global facility where you can configure the default logging backend implementation. + +### Log Handlers + +`protocol LogHandler` + +A log handler provides an implementation of a logging backend. + +`struct MultiplexLogHandler` + +A pseudo log handler that sends messages to multiple other log handlers. + +`struct StreamLogHandler` + +Stream log handler presents log messages to STDERR or STDOUT. + +`struct SwiftLogNoOpLogHandler` + +A no-operation log handler, used when no logging is required + +### Best Practices + +Best practices for effective logging with SwiftLog. + +Implementing a log handler + +Create a custom logging backend that provides logging services for your apps and libraries. + +- Logging +- Overview +- Getting Started +- Adding the Dependency +- Basic Usage +- Default Behavior +- Topics + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler + +- Logging +- StreamLogHandler + +Structure + +# StreamLogHandler + +Stream log handler presents log messages to STDERR or STDOUT. + +struct StreamLogHandler + +Logging.swift + +## Mentioned in + +Understanding Loggers and Log Handlers + +## Overview + +This is a simple implementation of `LogHandler` that directs `Logger` output to either `stderr` or `stdout` via the factory methods. + +Metadata is merged in the following order: + +1. Metadata set on the log handler itself is used as the base metadata. + +2. The handler’s `metadataProvider` is invoked, overriding any existing keys. + +3. The per-log-statement metadata is merged, overriding any previously set keys. + +## Topics + +### Creating a stream log handler + +Creates a stream log handler that directs its output to STDOUT. + +Creates a stream log handler that directs its output to STDOUT using the metadata provider you provide. + +Creates a stream log handler that directs its output to STDERR. + +Creates a stream log handler that directs its output to STDERR using the metadata provider you provide. + +### Sending log messages + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, source: String, file: String, function: String, line: UInt)` + +Log a message using the log level and source that you provide. + +### Updating metadata + +Add, change, or remove a logging metadata item. + +### Inspecting a log handler + +`var logLevel: Logger.Level` + +Get the log level configured for this `Logger`. + +`var metadata: Logger.Metadata` + +Get or set the entire metadata storage as a dictionary. + +`var metadataProvider: Logger.MetadataProvider?` + +The metadata provider. + +## Relationships + +### Conforms To + +- `LogHandler` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Log Handlers + +`protocol LogHandler` + +A log handler provides an implementation of a logging backend. + +`struct MultiplexLogHandler` + +A pseudo log handler that sends messages to multiple other log handlers. + +`struct SwiftLogNoOpLogHandler` + +A no-operation log handler, used when no logging is required + +- StreamLogHandler +- Mentioned in +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler + +- Logging +- LogHandler + +Protocol + +# LogHandler + +A log handler provides an implementation of a logging backend. + +protocol LogHandler : _SwiftLogSendableLogHandler + +LogHandler.swift + +## Mentioned in + +Implementing a log handler + +## Overview + +This type is an implementation detail and should not normally be used, unless you implement your own logging backend. To use the SwiftLog API, please refer to the documentation of `Logger`. + +# Implementation requirements + +To implement your own `LogHandler` you should respect a few requirements that are necessary so applications work as expected, regardless of the selected `LogHandler` implementation. + +- The `LogHandler` must be a `struct`. + +- The metadata and `logLevel` properties must be implemented so that setting them on a `Logger` does not affect other instances of `Logger`. + +### Treat log level & metadata as values + +When developing your `LogHandler`, please make sure the following test works. + +@Test +func logHandlerValueSemantics() { +LoggingSystem.bootstrap(MyLogHandler.init) +var logger1 = Logger(label: "first logger") +logger1.logLevel = .debug +logger1[metadataKey: "only-on"] = "first" + +var logger2 = logger1 +logger2.logLevel = .error // Must not affect logger1 +logger2[metadataKey: "only-on"] = "second" // Must not affect logger1 + +// These expectations must pass +#expect(logger2[metadataKey: "only-on"] == "second") +} + +### Special cases + +In certain special cases, the log level behaving like a value on `Logger` might not be what you want. For example, you might want to set the log level across _all_`Logger`s to `.debug` when a signal (for example `SIGUSR1`) is received to be able to debug special failures in production. This special case is acceptable but please create a solution specific to your `LogHandler` implementation to achieve that. + +The following code illustrates an example implementation of this behavior. On reception of the signal you would call `LogHandlerWithGlobalLogLevelOverride.overrideGlobalLogLevel = .debug`, for example. + +import class Foundation.NSLock + +public struct LogHandlerWithGlobalLogLevelOverride: LogHandler { +// The static properties hold the globally overridden +// log level (if overridden). +private static let overrideLock = NSLock() +private static var overrideLogLevel: Logger.Level? = nil + +// this holds the log level if not overridden +private var _logLevel: Logger.Level = .info + +// metadata storage +public var metadata: Logger.Metadata = [:] + +public init(label: String) { +// [...] +} + +public var logLevel: Logger.Level { +// When asked for the log level, check +// if it was globally overridden or not. +get { +LogHandlerWithGlobalLogLevelOverride.overrideLock.lock() +defer { LogHandlerWithGlobalLogLevelOverride.overrideLock.unlock() } +return LogHandlerWithGlobalLogLevelOverride.overrideLogLevel ?? self._logLevel +} +// Set the log level whenever asked +// (note: this might not have an effect if globally +// overridden). +set { +self._logLevel = newValue +} +} + +public func log( +level: Logger.Level, +message: Logger.Message, +metadata: Logger.Metadata?, +source: String, +file: String, +function: String, +line: UInt) { +// [...] +} + +get { +return self.metadata[metadataKey] +} +set(newValue) { +self.metadata[metadataKey] = newValue +} +} + +// This is the function to globally override the log level, +// it is not part of the `LogHandler` protocol. +public static func overrideGlobalLogLevel(_ logLevel: Logger.Level) { +LogHandlerWithGlobalLogLevelOverride.overrideLock.lock() +defer { LogHandlerWithGlobalLogLevelOverride.overrideLock.unlock() } +LogHandlerWithGlobalLogLevelOverride.overrideLogLevel = logLevel +} +} + +## Topics + +### Sending log messages + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, source: String, file: String, function: String, line: UInt)` + +The library calls this method when a log handler must emit a log message. + +**Required** Default implementation provided. + +A default implementation for a log message handler that forwards the source location for the message. + +Deprecated + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, file: String, function: String, line: UInt)` + +SwiftLog 1.0 log compatibility method. + +A default implementation for a log message handler. + +### Updating metadata + +Add, remove, or change the logging metadata. + +**Required** + +### Inspecting a log handler + +`var logLevel: Logger.Level` + +Get or set the configured log level. + +`var metadata: Logger.Metadata` + +Get or set the entire metadata storage as a dictionary. + +`var metadataProvider: Logger.MetadataProvider?` + +The metadata provider this log handler uses when a log statement is about to be emitted. + +## Relationships + +### Inherits From + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +### Conforming Types + +- `MultiplexLogHandler` +- `StreamLogHandler` +- `SwiftLogNoOpLogHandler` + +## See Also + +### Log Handlers + +`struct MultiplexLogHandler` + +A pseudo log handler that sends messages to multiple other log handlers. + +`struct StreamLogHandler` + +Stream log handler presents log messages to STDERR or STDOUT. + +`struct SwiftLogNoOpLogHandler` + +A no-operation log handler, used when no logging is required + +- LogHandler +- Mentioned in +- Overview +- Implementation requirements +- Treat log level & metadata as values +- Special cases +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/understandingloggers + +- Logging +- Understanding Loggers and Log Handlers + +Article + +# Understanding Loggers and Log Handlers + +Learn how to create and configure loggers, set log levels, and use metadata to add context to your log messages. + +## Overview + +Create or retrieve a logger to get an instance for logging messages. Log messages have a level that you use to indicate the message’s importance. + +SwiftLog defines seven log levels, represented by `Logger.Level`, ordered from least to most severe: + +- `Logger.Level.trace` + +- `Logger.Level.debug` + +- `Logger.Level.info` + +- `Logger.Level.notice` + +- `Logger.Level.warning` + +- `Logger.Level.error` + +- `Logger.Level.critical` + +Once a message is sent to a logger, a log handler processes it. The app using the logger configures the handler, usually for the environment in which that app runs, processing messages appropriate to that environment. If the app doesn’t provide its own log handler, SwiftLog defaults to using a `StreamLogHandler` that outputs log messages to `STDOUT`. + +### Loggers + +Loggers are used to emit log messages at different severity levels: + +// Informational message +logger.info("Processing request") + +// Something went wrong +logger.error("Houston, we have a problem") + +`Logger` is a value type with value semantics, meaning that when you modify a logger’s configuration (like its log level or metadata), it only affects that specific logger instance: + +let baseLogger = Logger(label: "MyApp") + +// Create a new logger with different configuration. +var requestLogger = baseLogger +requestLogger.logLevel = .debug +requestLogger[metadataKey: "request-id"] = "\(UUID())" + +// baseLogger is unchanged. It still has default log level and no metadata +// requestLogger has debug level and request-id metadata. + +This value type behavior makes loggers safe to pass between functions and modify without unexpected side effects. + +### Log Levels + +Log levels can be changed per logger without affecting others: + +var logger = Logger(label: "MyLogger") +logger.logLevel = .debug + +For guidance on what level to use for a message, see 001: Choosing log levels. + +### Logging Metadata + +Metadata provides contextual information crucial for debugging: + +var logger = Logger(label: "com.example.server") +logger[metadataKey: "request.id"] = "\(UUID())" +logger.info("Processing request") + +Output: + +2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED Processing request + +### Source vs Label + +A `Logger` has an immutable `label` that identifies its creator, while each log message carries a `source` parameter that identifies where the message originated. Use `source` for filtering messages from specific subsystems. + +## See Also + +### Logging API + +`struct Logger` + +A Logger emits log messages using methods that correspond to a log level. + +`enum LoggingSystem` + +The logging system is a global facility where you can configure the default logging backend implementation. + +- Understanding Loggers and Log Handlers +- Overview +- Loggers +- Log Levels +- Logging Metadata +- Source vs Label +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger + + + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loggingsystem + +- Logging +- LoggingSystem + +Enumeration + +# LoggingSystem + +The logging system is a global facility where you can configure the default logging backend implementation. + +enum LoggingSystem + +Logging.swift + +## Overview + +`LoggingSystem` is set up just once in a given program to set up the desired logging backend implementation. The default behavior, if you don’t define otherwise, sets the `LogHandler` to use a `StreamLogHandler` that presents its output to `STDOUT`. + +You can configure that handler to present the output to `STDERR` instead using the following code: + +LoggingSystem.bootstrap(StreamLogHandler.standardError) + +The default ( `StreamLogHandler`) is intended to be a convenience. For production applications, implement the `LogHandler` protocol directly, or use a community-maintained backend. + +## Topics + +### Initializing the logging system + +A one-time configuration function that globally selects the implementation for your desired logging backend. + +### Inspecting the logging system + +`static var metadataProvider: Logger.MetadataProvider?` + +System wide `Logger.MetadataProvider` that was configured during the logging system’s `bootstrap`. + +## See Also + +### Logging API + +Understanding Loggers and Log Handlers + +Learn how to create and configure loggers, set log levels, and use metadata to add context to your log messages. + +`struct Logger` + +A Logger emits log messages using methods that correspond to a log level. + +- LoggingSystem +- Overview +- Topics +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler + +- Logging +- MultiplexLogHandler + +Structure + +# MultiplexLogHandler + +A pseudo log handler that sends messages to multiple other log handlers. + +struct MultiplexLogHandler + +Logging.swift + +### Effective Logger.Level + +When first initialized, the multiplex log handlers’ log level is automatically set to the minimum of all the provided log handlers. This ensures that each of the handlers are able to log at their appropriate level any log events they might be interested in. + +Example: If log handler `A` is logging at `.debug` level, and log handler `B` is logging at `.info` level, the log level of the constructed `MultiplexLogHandler([A, B])` is set to `.debug`. This means that this handler will operate on debug messages, while only logged by the underlying `A` log handler (since `B`’s log level is `.info` and thus it would not actually log that log message). + +If the log level is _set_ on a `Logger` backed by an `MultiplexLogHandler` the log level applies to _all_ underlying log handlers, allowing a logger to still select at what level it wants to log regardless of if the underlying handler is a multiplex or a normal one. If for some reason one might want to not allow changing a log level of a specific handler passed into the multiplex log handler, this is possible by wrapping it in a handler which ignores any log level changes. + +### Effective Logger.Metadata + +Since a `MultiplexLogHandler` is a combination of multiple log handlers, the handling of metadata can be non-obvious. For example, the underlying log handlers may have metadata of their own set before they are used to initialize the multiplex log handler. + +The multiplex log handler acts purely as proxy and does not make any changes to underlying handler metadata other than proxying writes that users made on a `Logger` instance backed by this handler. + +Setting metadata is always proxied through to _all_ underlying handlers, meaning that if a modification like `logger[metadataKey: "x"] = "y"` is made, all the underlying log handlers used to create the multiplex handler observe this change. + +Reading metadata from the multiplex log handler MAY need to pick one of conflicting values if the underlying log handlers were previously initiated with metadata before passing them into the multiplex handler. The multiplex handler uses the order in which the handlers were passed in during its initialization as a priority indicator - the first handler’s values are more important than the next handlers values, etc. + +Example: If the multiplex log handler was initiated with two handlers like this: `MultiplexLogHandler([handler1, handler2])`. The handlers each have some already set metadata: `handler1` has metadata values for keys `one` and `all`, and `handler2` has values for keys `two` and `all`. + +A query through the multiplex log handler the key `one` naturally returns `handler1`’s value, and a query for `two` naturally returns `handler2`’s value. Querying for the key `all` will return `handler1`’s value, as that handler has a high priority, as indicated by its earlier position in the initialization, than the second handler. The same rule applies when querying for the `metadata` property of the multiplex log handler; it constructs `Metadata` uniquing values. + +## Topics + +### Creating a multiplex log handler + +[`init([any LogHandler])`](https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/init(_:)) + +Create a multiplex log handler. + +[`init([any LogHandler], metadataProvider: Logger.MetadataProvider?)`](https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/init(_:metadataprovider:)) + +Create a multiplex log handler with the metadata provider you provide. + +### Sending log messages + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, source: String, file: String, function: String, line: UInt)` + +Log a message using the log level and source that you provide. + +### Updating metadata + +Add, change, or remove a logging metadata item. + +### Inspecting a log handler + +`var logLevel: Logger.Level` + +Get or set the log level configured for this `Logger`. + +`var metadata: Logger.Metadata` + +Get or set the entire metadata storage as a dictionary. + +`var metadataProvider: Logger.MetadataProvider?` + +The metadata provider. + +## Relationships + +### Conforms To + +- `LogHandler` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Log Handlers + +`protocol LogHandler` + +A log handler provides an implementation of a logging backend. + +`struct StreamLogHandler` + +Stream log handler presents log messages to STDERR or STDOUT. + +`struct SwiftLogNoOpLogHandler` + +A no-operation log handler, used when no logging is required + +- MultiplexLogHandler +- Effective Logger.Level +- Effective Logger.Metadata +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler + +- Logging +- SwiftLogNoOpLogHandler + +Structure + +# SwiftLogNoOpLogHandler + +A no-operation log handler, used when no logging is required + +struct SwiftLogNoOpLogHandler + +Logging.swift + +## Topics + +### Creating a Swift Log no-op log handler + +`init()` + +Creates a no-op log handler. + +`init(String)` + +### Sending log messages + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, source: String, file: String, function: String, line: UInt)` + +A proxy that discards every log message that you provide. + +### Updating metadata + +Add, change, or remove a logging metadata item. + +### Inspecting a log handler + +`var logLevel: Logger.Level` + +Get or set the log level configured for this `Logger`. + +`var metadata: Logger.Metadata` + +Get or set the entire metadata storage as a dictionary. + +`var metadataProvider: Logger.MetadataProvider?` + +Default implementation for a metadata provider that defaults to nil. + +### Instance Methods + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, file: String, function: String, line: UInt)` + +A proxy that discards every log message it receives. + +## Relationships + +### Conforms To + +- `LogHandler` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Log Handlers + +`protocol LogHandler` + +A log handler provides an implementation of a logging backend. + +`struct MultiplexLogHandler` + +A pseudo log handler that sends messages to multiple other log handlers. + +`struct StreamLogHandler` + +Stream log handler presents log messages to STDERR or STDOUT. + +- SwiftLogNoOpLogHandler +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loggingbestpractices + +- Logging +- Logging best practices + +# Logging best practices + +Best practices for effective logging with SwiftLog. + +## Overview + +This collection of best practices helps library authors and application developers create effective, maintainable logging that works well across diverse environments. Each practice is designed to ensure your logs are useful for debugging while being respectful of system resources and operational requirements. + +### Who Should Use These Practices + +- **Library Authors**: Creating reusable components that log appropriately. + +- **Application Developers**: Implementing logging strategies in applications. + +### Philosophy + +Good logging strikes a balance between providing useful information and avoiding system overhead. These practices are based on real-world experience with production systems and emphasize: + +- **Predictable behavior** across different environments. + +- **Performance consciousness** to avoid impacting application speed. + +- **Operational awareness** to support production debugging and monitoring. + +- **Developer experience** to make debugging efficient and pleasant. + +### Contributing to these practices + +These best practices evolve based on community experience and are maintained by the Swift Server Working Group ( SSWG). Each practice includes: + +- **Clear motivation** explaining why the practice matters + +- **Concrete examples** showing good and bad patterns + +- **Alternatives considered** documenting trade-offs and rejected approaches + +## Topics + +001: Choosing log levels + +Select appropriate log levels in applications and libraries. + +002: Structured logging + +Use metadata to create machine-readable, searchable log entries. + +003: Accepting loggers in libraries + +Accept loggers through method parameters to ensure proper metadata propagation. + +## See Also + +### Best Practices + +Implementing a log handler + +Create a custom logging backend that provides logging services for your apps and libraries. + +- Logging best practices +- Overview +- Who Should Use These Practices +- Philosophy +- Contributing to these practices +- Topics +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/implementingaloghandler + +- Logging +- Implementing a log handler + +Article + +# Implementing a log handler + +Create a custom logging backend that provides logging services for your apps and libraries. + +## Overview + +To become a compatible logging backend that any SwiftLog consumer can use, you need to fulfill a few requirements, primarily conforming to the `LogHandler` protocol. + +### Implement with value type semantics + +Your log handler **must be a `struct`** and exhibit value semantics. This ensures that changes to one logger don’t affect others. + +To verify that your handler reflects value semantics ensure that it passes this test: + +@Test +func logHandlerValueSemantics() { +LoggingSystem.bootstrap(MyLogHandler.init) +var logger1 = Logger(label: "first logger") +logger1.logLevel = .debug +logger1[metadataKey: "only-on"] = "first" + +var logger2 = logger1 +logger2.logLevel = .error // Must not affect logger1 +logger2[metadataKey: "only-on"] = "second" // Must not affect logger1 + +// These expectations must pass +#expect(logger2[metadataKey: "only-on"] == "second") +} + +### Example implementation + +Here’s a complete example of a simple print-based log handler: + +import Foundation +import Logging + +public struct PrintLogHandler: LogHandler { +private let label: String +public var logLevel: Logger.Level = .info +public var metadata: Logger.Metadata = [:] + +public init(label: String) { +self.label = label +} + +public func log( +level: Logger.Level, +message: Logger.Message, +metadata: Logger.Metadata?, +source: String, +file: String, +function: String, +line: UInt +) { +let timestamp = ISO8601DateFormatter().string(from: Date()) +let levelString = level.rawValue.uppercased() + +// Merge handler metadata with message metadata +let combinedMetadata = Self.prepareMetadata( +base: self.metadata +explicit: metadata +) + +// Format metadata +let metadataString = combinedMetadata.map { "\($0.key)=\($0.value)" }.joined(separator: ",") + +// Create log line and print to console +let logLine = "\(label) \(timestamp) \(levelString) [\(metadataString)]: \(message)" +print(logLine) +} + +get { +return self.metadata[key] +} +set { +self.metadata[key] = newValue +} +} + +static func prepareMetadata( +base: Logger.Metadata, +explicit: Logger.Metadata? + +var metadata = base + +guard let explicit else { +// all per-log-statement values are empty +return metadata +} + +metadata.merge(explicit, uniquingKeysWith: { _, explicit in explicit }) + +return metadata +} +} + +#### Metadata providers + +Metadata providers allow you to dynamically add contextual information to all log messages without explicitly passing it each time. Common use cases include request IDs, user sessions, or trace contexts that should be included in logs throughout a request’s lifecycle. + +public struct PrintLogHandler: LogHandler { +private let label: String +public var logLevel: Logger.Level = .info +public var metadata: Logger.Metadata = [:] +public var metadataProvider: Logger.MetadataProvider? + +// Get provider metadata +let providerMetadata = metadataProvider?.get() ?? [:] + +// Merge handler metadata with message metadata +let combinedMetadata = Self.prepareMetadata( +base: self.metadata, +provider: self.metadataProvider, +explicit: metadata +) + +static func prepareMetadata( +base: Logger.Metadata, +provider: Logger.MetadataProvider?, +explicit: Logger.Metadata? + +let provided = provider?.get() ?? [:] + +guard !provided.isEmpty || !((explicit ?? [:]).isEmpty) else { +// all per-log-statement values are empty +return metadata +} + +if !provided.isEmpty { +metadata.merge(provided, uniquingKeysWith: { _, provided in provided }) +} + +if let explicit = explicit, !explicit.isEmpty { +metadata.merge(explicit, uniquingKeysWith: { _, explicit in explicit }) +} + +### Performance considerations + +1. **Avoid blocking**: Don’t block the calling thread for I/O operations. + +2. **Lazy evaluation**: Remember that messages and metadata are autoclosures. + +3. **Memory efficiency**: Don’t hold onto large amounts of messages. + +## See Also + +### Related Documentation + +`protocol LogHandler` + +A log handler provides an implementation of a logging backend. + +`struct StreamLogHandler` + +Stream log handler presents log messages to STDERR or STDOUT. + +`struct MultiplexLogHandler` + +A pseudo log handler that sends messages to multiple other log handlers. + +### Best Practices + +Best practices for effective logging with SwiftLog. + +- Implementing a log handler +- Overview +- Implement with value type semantics +- Example implementation +- Advanced features +- Performance considerations +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler). + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/understandingloggers) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loggingsystem) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loggingbestpractices) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/implementingaloghandler) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loggingsystem/bootstrap(_:) + +#app-main) + +- Logging +- LoggingSystem +- bootstrap(\_:) + +Type Method + +# bootstrap(\_:) + +A one-time configuration function that globally selects the implementation for your desired logging backend. + +@preconcurrency + +Logging.swift + +## Parameters + +`factory` + +A closure that provides a `Logger` label identifier and produces an instance of the `LogHandler`. + +## Discussion + +## See Also + +### Initializing the logging system + +- bootstrap(\_:) +- Parameters +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loggingsystem/bootstrap(_:metadataprovider:) + +#app-main) + +- Logging +- LoggingSystem +- bootstrap(\_:metadataProvider:) + +Type Method + +# bootstrap(\_:metadataProvider:) + +A one-time configuration function that globally selects the implementation for your desired logging backend. + +@preconcurrency +static func bootstrap( + +metadataProvider: Logger.MetadataProvider? +) + +Logging.swift + +## Parameters + +`factory` + +A closure that provides a `Logger` label identifier and produces an instance of the `LogHandler`. + +`metadataProvider` + +The `MetadataProvider` used to inject runtime-generated metadata from the execution context. + +## Discussion + +## See Also + +### Initializing the logging system + +- bootstrap(\_:metadataProvider:) +- Parameters +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loggingsystem/metadataprovider + +- Logging +- LoggingSystem +- metadataProvider + +Type Property + +# metadataProvider + +System wide `Logger.MetadataProvider` that was configured during the logging system’s `bootstrap`. + +static var metadataProvider: Logger.MetadataProvider? { get } + +Logging.swift + +## Discussion + +When creating a `Logger` using the plain `init(label:)` initializer, this metadata provider will be provided to it. + +When using custom log handler factories, make sure to provide the bootstrapped metadata provider to them, or the metadata will not be filled in automatically using the provider on log-sites. While using a custom factory to avoid using the bootstrapped metadata provider may sometimes be useful, usually it will lead to un-expected behavior, so make sure to always propagate it to your handlers. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/metadataprovider-swift.struct + +- Logging +- Logger +- Logger.MetadataProvider + +Structure + +# Logger.MetadataProvider + +A MetadataProvider automatically injects runtime-generated metadata to all logs emitted by a logger. + +struct MetadataProvider + +MetadataProvider.swift + +### Example + +A metadata provider may be used to automatically inject metadata such as trace IDs: + +import Tracing // + +let metadataProvider = MetadataProvider { +guard let traceID = Baggage.current?.traceID else { return nil } +return ["traceID": "\(traceID)"] +} +let logger = Logger(label: "example", metadataProvider: metadataProvider) +var baggage = Baggage.topLevel +baggage.traceID = 42 +Baggage.withValue(baggage) { +logger.info("hello") // automatically includes ["traceID": "42"] metadata +} + +We recommend referring to swift-distributed-tracing for metadata providers which make use of its tracing and metadata propagation infrastructure. It is however possible to make use of metadata providers independently of tracing and instruments provided by that library, if necessary. + +## Topics + +### Creating a metadata provider + +Creates a new metadata provider. + +### Invoking the provider + +Invokes the metadata provider and returns the generated contextual metadata. + +### Merging metadata + +A pseudo metadata provider that merges metadata from multiple other metadata providers. + +## Relationships + +### Conforms To + +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Creating Loggers + +`init(label: String)` + +Construct a logger with the label you provide to identify the creator of the logger. + +`init(label: String, metadataProvider: Logger.MetadataProvider)` + +Creates a logger using the label that identifies the creator of the logger or a non-standard log handler. + +- Logger.MetadataProvider +- Example +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loggingsystem/bootstrap(_:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loggingsystem/bootstrap(_:metadataprovider:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loggingsystem/metadataprovider) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/metadataprovider-swift.struct) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/metadataprovider + +- Logging +- StreamLogHandler +- metadataProvider + +Instance Property + +# metadataProvider + +The metadata provider. + +var metadataProvider: Logger.MetadataProvider? + +Logging.swift + +## See Also + +### Inspecting a log handler + +`var logLevel: Logger.Level` + +Get the log level configured for this `Logger`. + +`var metadata: Logger.Metadata` + +Get or set the entire metadata storage as a dictionary. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/standardoutput(label:) + +#app-main) + +- Logging +- StreamLogHandler +- standardOutput(label:) + +Type Method + +# standardOutput(label:) + +Creates a stream log handler that directs its output to STDOUT. + +Logging.swift + +## See Also + +### Creating a stream log handler + +Creates a stream log handler that directs its output to STDOUT using the metadata provider you provide. + +Creates a stream log handler that directs its output to STDERR. + +Creates a stream log handler that directs its output to STDERR using the metadata provider you provide. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/standardoutput(label:metadataprovider:) + +# The page you're looking for can't be found. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/standarderror(label:) + +#app-main) + +- Logging +- StreamLogHandler +- standardError(label:) + +Type Method + +# standardError(label:) + +Creates a stream log handler that directs its output to STDERR. + +Logging.swift + +## See Also + +### Creating a stream log handler + +Creates a stream log handler that directs its output to STDOUT. + +Creates a stream log handler that directs its output to STDOUT using the metadata provider you provide. + +Creates a stream log handler that directs its output to STDERR using the metadata provider you provide. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/standarderror(label:metadataprovider:) + +#app-main) + +- Logging +- StreamLogHandler +- standardError(label:metadataProvider:) + +Type Method + +# standardError(label:metadataProvider:) + +Creates a stream log handler that directs its output to STDERR using the metadata provider you provide. + +static func standardError( +label: String, +metadataProvider: Logger.MetadataProvider? + +Logging.swift + +## See Also + +### Creating a stream log handler + +Creates a stream log handler that directs its output to STDOUT. + +Creates a stream log handler that directs its output to STDOUT using the metadata provider you provide. + +Creates a stream log handler that directs its output to STDERR. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/log(level:message:metadata:source:file:function:line:) + +#app-main) + +- Logging +- StreamLogHandler +- log(level:message:metadata:source:file:function:line:) + +Instance Method + +# log(level:message:metadata:source:file:function:line:) + +Log a message using the log level and source that you provide. + +func log( +level: Logger.Level, +message: Logger.Message, +metadata explicitMetadata: Logger.Metadata?, +source: String, +file: String, +function: String, +line: UInt +) + +Logging.swift + +## Parameters + +`level` + +The log level to log the `message`. + +`message` + +The message to be logged. The `message` parameter supports any string interpolation literal. + +`explicitMetadata` + +One-off metadata to attach to this log message. + +`source` + +The source this log message originates from. The value defaults to the module that emits the log message. + +`file` + +The file this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#fileID`. + +`function` + +The function this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#function`. + +`line` + +The line this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#line`. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/subscript(metadatakey:) + +#app-main) + +- Logging +- StreamLogHandler +- subscript(metadataKey:) + +Instance Subscript + +# subscript(metadataKey:) + +Add, change, or remove a logging metadata item. + +Logging.swift + +## Overview + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/loglevel + +- Logging +- StreamLogHandler +- logLevel + +Instance Property + +# logLevel + +Get the log level configured for this `Logger`. + +var logLevel: Logger.Level + +Logging.swift + +## Discussion + +## See Also + +### Inspecting a log handler + +`var metadata: Logger.Metadata` + +Get or set the entire metadata storage as a dictionary. + +`var metadataProvider: Logger.MetadataProvider?` + +The metadata provider. + +- logLevel +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/metadata + +- Logging +- StreamLogHandler +- metadata + +Instance Property + +# metadata + +Get or set the entire metadata storage as a dictionary. + +var metadata: Logger.Metadata { get set } + +Logging.swift + +## See Also + +### Inspecting a log handler + +`var logLevel: Logger.Level` + +Get the log level configured for this `Logger`. + +`var metadataProvider: Logger.MetadataProvider?` + +The metadata provider. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/loghandler-implementations + + + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/metadataprovider) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/standardoutput(label:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/standardoutput(label:metadataprovider:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/standarderror(label:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/standarderror(label:metadataprovider:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/log(level:message:metadata:source:file:function:line:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/subscript(metadatakey:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/loglevel) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/metadata) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/streamloghandler/loghandler-implementations) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level + +- Logging +- Logger +- Logger.Level + +Enumeration + +# Logger.Level + +The log level. + +enum Level + +Logging.swift + +## Mentioned in + +001: Choosing log levels + +Understanding Loggers and Log Handlers + +## Overview + +Log levels are ordered by their severity, with `.trace` being the least severe and `.critical` being the most severe. + +## Topics + +### Log Levels + +`case trace` + +Appropriate for messages that contain information normally of use only when tracing the execution of a program. + +`case debug` + +Appropriate for messages that contain information normally of use only when debugging a program. + +`case info` + +Appropriate for informational messages. + +`case notice` + +Appropriate for conditions that are not error conditions, but that may require special handling. + +`case warning` + +Appropriate for messages that are not error conditions, but more severe than notice. + +`case error` + +Appropriate for error conditions. + +`case critical` + +Appropriate for critical error conditions that usually require immediate attention. + +### Initializers + +`init?(rawValue: String)` + +## Relationships + +### Conforms To + +- `Swift.CaseIterable` +- `Swift.Comparable` +- `Swift.Copyable` +- `Swift.Decodable` +- `Swift.Encodable` +- `Swift.Equatable` +- `Swift.Hashable` +- `Swift.RawRepresentable` +- `Swift.Sendable` +- `Swift.SendableMetatype` + +## See Also + +### Sending general log messages + +Log a message using the log level you provide. + +Log a message using the log level and source that you provide. + +`struct Message` + +The content of log message. + +`typealias Metadata` + +The type of the metadata storage. + +- Logger.Level +- Mentioned in +- Overview +- Topics +- Relationships +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/trace + + + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/debug + +- Logging +- Logger +- Logger.Level +- Logger.Level.debug + +Case + +# Logger.Level.debug + +Appropriate for messages that contain information normally of use only when debugging a program. + +case debug + +Logging.swift + +## Mentioned in + +001: Choosing log levels + +Understanding Loggers and Log Handlers + +## See Also + +### Log Levels + +`case trace` + +Appropriate for messages that contain information normally of use only when tracing the execution of a program. + +`case info` + +Appropriate for informational messages. + +`case notice` + +Appropriate for conditions that are not error conditions, but that may require special handling. + +`case warning` + +Appropriate for messages that are not error conditions, but more severe than notice. + +`case error` + +Appropriate for error conditions. + +`case critical` + +Appropriate for critical error conditions that usually require immediate attention. + +- Logger.Level.debug +- Mentioned in +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/info + +- Logging +- Logger +- Logger.Level +- Logger.Level.info + +Case + +# Logger.Level.info + +Appropriate for informational messages. + +case info + +Logging.swift + +## Mentioned in + +001: Choosing log levels + +Understanding Loggers and Log Handlers + +## See Also + +### Log Levels + +`case trace` + +Appropriate for messages that contain information normally of use only when tracing the execution of a program. + +`case debug` + +Appropriate for messages that contain information normally of use only when debugging a program. + +`case notice` + +Appropriate for conditions that are not error conditions, but that may require special handling. + +`case warning` + +Appropriate for messages that are not error conditions, but more severe than notice. + +`case error` + +Appropriate for error conditions. + +`case critical` + +Appropriate for critical error conditions that usually require immediate attention. + +- Logger.Level.info +- Mentioned in +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/notice + +- Logging +- Logger +- Logger.Level +- Logger.Level.notice + +Case + +# Logger.Level.notice + +Appropriate for conditions that are not error conditions, but that may require special handling. + +case notice + +Logging.swift + +## Mentioned in + +001: Choosing log levels + +Understanding Loggers and Log Handlers + +## See Also + +### Log Levels + +`case trace` + +Appropriate for messages that contain information normally of use only when tracing the execution of a program. + +`case debug` + +Appropriate for messages that contain information normally of use only when debugging a program. + +`case info` + +Appropriate for informational messages. + +`case warning` + +Appropriate for messages that are not error conditions, but more severe than notice. + +`case error` + +Appropriate for error conditions. + +`case critical` + +Appropriate for critical error conditions that usually require immediate attention. + +- Logger.Level.notice +- Mentioned in +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/warning + +- Logging +- Logger +- Logger.Level +- Logger.Level.warning + +Case + +# Logger.Level.warning + +Appropriate for messages that are not error conditions, but more severe than notice. + +case warning + +Logging.swift + +## Mentioned in + +001: Choosing log levels + +Understanding Loggers and Log Handlers + +## See Also + +### Log Levels + +`case trace` + +Appropriate for messages that contain information normally of use only when tracing the execution of a program. + +`case debug` + +Appropriate for messages that contain information normally of use only when debugging a program. + +`case info` + +Appropriate for informational messages. + +`case notice` + +Appropriate for conditions that are not error conditions, but that may require special handling. + +`case error` + +Appropriate for error conditions. + +`case critical` + +Appropriate for critical error conditions that usually require immediate attention. + +- Logger.Level.warning +- Mentioned in +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/error + +- Logging +- Logger +- Logger.Level +- Logger.Level.error + +Case + +# Logger.Level.error + +Appropriate for error conditions. + +case error + +Logging.swift + +## Mentioned in + +001: Choosing log levels + +Understanding Loggers and Log Handlers + +## See Also + +### Log Levels + +`case trace` + +Appropriate for messages that contain information normally of use only when tracing the execution of a program. + +`case debug` + +Appropriate for messages that contain information normally of use only when debugging a program. + +`case info` + +Appropriate for informational messages. + +`case notice` + +Appropriate for conditions that are not error conditions, but that may require special handling. + +`case warning` + +Appropriate for messages that are not error conditions, but more severe than notice. + +`case critical` + +Appropriate for critical error conditions that usually require immediate attention. + +- Logger.Level.error +- Mentioned in +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/critical + +- Logging +- Logger +- Logger.Level +- Logger.Level.critical + +Case + +# Logger.Level.critical + +Appropriate for critical error conditions that usually require immediate attention. + +case critical + +Logging.swift + +## Mentioned in + +001: Choosing log levels + +Understanding Loggers and Log Handlers + +## Discussion + +When a `critical` message is logged, the logging backend (`LogHandler`) is free to perform more heavy-weight operations to capture system state (such as capturing stack traces) to facilitate debugging. + +## See Also + +### Log Levels + +`case trace` + +Appropriate for messages that contain information normally of use only when tracing the execution of a program. + +`case debug` + +Appropriate for messages that contain information normally of use only when debugging a program. + +`case info` + +Appropriate for informational messages. + +`case notice` + +Appropriate for conditions that are not error conditions, but that may require special handling. + +`case warning` + +Appropriate for messages that are not error conditions, but more severe than notice. + +`case error` + +Appropriate for error conditions. + +- Logger.Level.critical +- Mentioned in +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/001-choosingloglevels + +- Logging +- Logging best practices +- 001: Choosing log levels + +Article + +# 001: Choosing log levels + +Select appropriate log levels in applications and libraries. + +## Overview + +SwiftLog defines seven log levels, and choosing the right level is crucial for creating well-behaved libraries that don’t overwhelm logging systems or misuse severity levels. This practice provides clear guidance on when to use each level. + +### Motivation + +Libraries must be well-behaved across various use cases and cannot assume specific logging backend configurations. Using inappropriate log levels can flood production logs, trigger false alerts, or make debugging more difficult. Following consistent log level guidelines ensures your library integrates well with diverse application environments. + +### Log levels + +SwiftLog defines seven log levels via `Logger.Level`, ordered from least to most severe: + +- `Logger.Level.trace` + +- `Logger.Level.debug` + +- `Logger.Level.info` + +- `Logger.Level.notice` + +- `Logger.Level.warning` + +- `Logger.Level.error` + +- `Logger.Level.critical` + +### Level guidelines + +How you use log levels depends in large part if you are developing a library, or an application which bootstraps its logging system and is in full control over its logging environment. + +#### For libraries + +Libraries should use **info level or less severe** (info, debug, trace). + +Libraries **should not** log information on **warning or more severe levels**, unless it is a one-time (for example during startup) warning, that cannot lead to overwhelming log outputs. + +Each level serves different purposes: + +##### Trace Level + +- **Usage**: Log everything needed to diagnose hard-to-reproduce bugs. + +- **Performance**: May impact performance; assume it won’t be used in production. + +- **Content**: Internal state, detailed operation flows, diagnostic information. + +##### Debug Level + +- **Usage**: May be enabled in some production deployments. + +- **Performance**: Should not significantly undermine production performance. + +- **Content**: High-level operation overview, connection events, major decisions. + +##### Info Level + +- **Usage**: Reserved for things that went wrong but can’t be communicated through other means, like throwing from a method. + +- **Examples**: Connection retry attempts, fallback mechanisms, recoverable failures. + +- **Guideline**: Use sparingly - Don’t use for normal successful operations. + +#### For applications + +Applications can use **any level** depending on the context and what they want to achieve. Applications have full control over their logging strategy. + +#### Configuring logger log levels + +It depends on the use-case of your application which log level your logger should use. For **console and other end-user-visible displays**: Consider using **notice level** as the minimum visible level to avoid overwhelming users with technical details. + +#### Recommended: Libraries should use info level or lower + +// ✅ Good: Trace level for detailed diagnostics +logger.trace("Connection pool state", metadata: [\ +"active": "\(activeConnections)",\ +"idle": "\(idleConnections)",\ +"pending": "\(pendingRequests)"\ +]) + +// ✅ Good: Debug level for high-value operational info +logger.debug("Database connection established", metadata: [\ +"host": "\(host)",\ +"database": "\(database)",\ +"connectionTime": "\(duration)"\ +]) + +// ✅ Good: Info level for issues that can't be communicated through other means +logger.info("Connection failed, retrying", metadata: [\ +"attempt": "\(attemptNumber)",\ +"maxRetries": "\(maxRetries)",\ +"host": "\(host)"\ +]) + +#### Use sparingly: Warning and error levels + +// ✅ Good: One-time startup warning or error +logger.warning("Deprecated TLS version detected. Consider upgrading to TLS 1.3") + +#### Avoid: Logging potentially intentional failures at info level + +Some failures may be completely intentional from the high-level perspective of a developer or system using your library. For example: failure to resolve a domain, failure to make a request, or failure to complete some task; + +Instead, log at debug or trace levels and offer alternative ways to observe these behaviors, for example using `swift-metrics` to emit counts. + +// ❌ Bad: Normal operations at info level flood production logs +logger.info("Request failed") + +#### Avoid: Normal operations at info level + +// ❌ Bad: Normal operations at info level flood production logs +logger.info("HTTP request received") +logger.info("Database query executed") +logger.info("Response sent") + +// ✅ Good: Use appropriate levels instead +logger.debug("Processing request", metadata: ["path": "\(path)"]) +logger.trace("Query", metadata: ["sql": "\(query)"]) +logger.debug("Request completed", metadata: ["status": "\(status)"]) + +## See Also + +002: Structured logging + +Use metadata to create machine-readable, searchable log entries. + +003: Accepting loggers in libraries + +Accept loggers through method parameters to ensure proper metadata propagation. + +- 001: Choosing log levels +- Overview +- Motivation +- Log levels +- Level guidelines +- Example +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level), + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/trace) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/debug) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/info) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/notice) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/warning) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/error) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger/level/critical) + + + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/001-choosingloglevels). + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/init() + +#app-main) + +- Logging +- SwiftLogNoOpLogHandler +- init() + +Initializer + +# init() + +Creates a no-op log handler. + +init() + +Logging.swift + +## See Also + +### Creating a Swift Log no-op log handler + +`init(String)` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/init(_:) + +#app-main) + +- Logging +- SwiftLogNoOpLogHandler +- init(\_:) + +Initializer + +# init(\_:) + +Creates a no-op log handler. + +init(_: String) + +Logging.swift + +## See Also + +### Creating a Swift Log no-op log handler + +`init()` + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/log(level:message:metadata:source:file:function:line:) + +#app-main) + +- Logging +- SwiftLogNoOpLogHandler +- log(level:message:metadata:source:file:function:line:) + +Instance Method + +# log(level:message:metadata:source:file:function:line:) + +A proxy that discards every log message that you provide. + +func log( +level: Logger.Level, +message: Logger.Message, +metadata: Logger.Metadata?, +source: String, +file: String, +function: String, +line: UInt +) + +Logging.swift + +## Parameters + +`level` + +The log level to log the `message`. + +`message` + +The message to be logged. The `message` parameter supports any string interpolation literal. + +`metadata` + +One-off metadata to attach to this log message. + +`source` + +The source this log message originates from. The value defaults to the module that emits the log message. + +`file` + +The file this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#fileID`. + +`function` + +The function this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#function`. + +`line` + +The line this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#line`. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/subscript(metadatakey:) + +#app-main) + +- Logging +- SwiftLogNoOpLogHandler +- subscript(metadataKey:) + +Instance Subscript + +# subscript(metadataKey:) + +Add, change, or remove a logging metadata item. + +Logging.swift + +## Overview + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/loglevel + +- Logging +- SwiftLogNoOpLogHandler +- logLevel + +Instance Property + +# logLevel + +Get or set the log level configured for this `Logger`. + +var logLevel: Logger.Level { get set } + +Logging.swift + +## Discussion + +## See Also + +### Inspecting a log handler + +`var metadata: Logger.Metadata` + +Get or set the entire metadata storage as a dictionary. + +`var metadataProvider: Logger.MetadataProvider?` + +Default implementation for a metadata provider that defaults to nil. + +- logLevel +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/metadata + +- Logging +- SwiftLogNoOpLogHandler +- metadata + +Instance Property + +# metadata + +Get or set the entire metadata storage as a dictionary. + +var metadata: Logger.Metadata { get set } + +Logging.swift + +## See Also + +### Inspecting a log handler + +`var logLevel: Logger.Level` + +Get or set the log level configured for this `Logger`. + +`var metadataProvider: Logger.MetadataProvider?` + +Default implementation for a metadata provider that defaults to nil. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/metadataprovider + +- Logging +- SwiftLogNoOpLogHandler +- metadataProvider + +Instance Property + +# metadataProvider + +Default implementation for a metadata provider that defaults to nil. + +var metadataProvider: Logger.MetadataProvider? { get set } + +LogHandler.swift + +## Discussion + +This default exists in order to facilitate the source-compatible introduction of the `metadataProvider` protocol requirement. + +## See Also + +### Inspecting a log handler + +`var logLevel: Logger.Level` + +Get or set the log level configured for this `Logger`. + +`var metadata: Logger.Metadata` + +Get or set the entire metadata storage as a dictionary. + +- metadataProvider +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/log(level:message:metadata:file:function:line:) + +#app-main) + +- Logging +- SwiftLogNoOpLogHandler +- log(level:message:metadata:file:function:line:) + +Instance Method + +# log(level:message:metadata:file:function:line:) + +A proxy that discards every log message it receives. + +func log( +level: Logger.Level, +message: Logger.Message, +metadata: Logger.Metadata?, +file: String, +function: String, +line: UInt +) + +Logging.swift + +## Parameters + +`level` + +The log level to log the `message`. + +`message` + +The message to be logged. The `message` parameter supports any string interpolation literal. + +`metadata` + +One-off metadata to attach to this log message. + +`file` + +The file this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#fileID`. + +`function` + +The function this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#function`. + +`line` + +The line this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#line`. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/loghandler-implementations + +- Logging +- SwiftLogNoOpLogHandler +- LogHandler Implementations + +API Collection + +# LogHandler Implementations + +## Topics + +### Instance Properties + +`var metadataProvider: Logger.MetadataProvider?` + +Default implementation for a metadata provider that defaults to nil. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/init()) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/init(_:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/log(level:message:metadata:source:file:function:line:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/subscript(metadatakey:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/loglevel) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/metadata) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/metadataprovider) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/log(level:message:metadata:file:function:line:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/swiftlognooploghandler/loghandler-implementations) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/002-structuredlogging + +- Logging +- Logging best practices +- 002: Structured logging + +Article + +# 002: Structured logging + +Use metadata to create machine-readable, searchable log entries. + +## Overview + +Structured logging uses metadata to separate human-readable messages from machine-readable data. This practice makes logs easier to search, filter, and analyze programmatically while maintaining readability. + +### Motivation + +Traditional string-based logging embeds all information in the message text, making it more difficult for automated tools to parse and extract. Structured logging separates these concerns; messages provide human readable context while metadata provides structured data for tooling. + +#### Recommended: Structured logging + +// ✅ Structured - message provides context, metadata provides data +logger.info( +"Accepted connection", +metadata: [\ +"connection.id": "\(id)",\ +"connection.peer": "\(peer)",\ +"connections.total": "\(count)"\ +] +) + +logger.error( +"Database query failed", +metadata: [\ +"query.retries": "\(retries)",\ +"query.error": "\(error)",\ +"query.duration": "\(duration)"\ +] +) + +### Advanced: Nested metadata for complex data + +// ✅ Complex structured data +logger.trace( +"HTTP request started", +metadata: [\ +"request.id": "\(requestId)",\ +"request.method": "GET",\ +"request.path": "/api/users",\ +"request.headers": [\ +"user-agent": "\(userAgent)"\ +],\ +"client.ip": "\(clientIP)",\ +"client.country": "\(country)"\ +] +) + +#### Avoid: Unstructured logging + +// ❌ Not structured - hard to parse programmatically +logger.info("Accepted connection \(id) from \(peer), total: \(count)") +logger.error("Database query failed after \(retries) retries: \(error)") + +### Metadata key conventions + +Use hierarchical dot-notation for related fields: + +// ✅ Good: Hierarchical keys +logger.debug( +"Database operation completed", +metadata: [\ +"db.operation": "SELECT",\ +"db.table": "users",\ +"db.duration": "\(duration)",\ +"db.rows": "\(rowCount)"\ +] +) + +// ✅ Good: Consistent prefixing +logger.info( +"HTTP response", +metadata: [\ +"http.method": "POST",\ +"http.status": "201",\ +"http.path": "/api/users",\ +"http.duration": "\(duration)"\ +] +) + +## See Also + +001: Choosing log levels + +Select appropriate log levels in applications and libraries. + +003: Accepting loggers in libraries + +Accept loggers through method parameters to ensure proper metadata propagation. + +- 002: Structured logging +- Overview +- Motivation +- Example +- Advanced: Nested metadata for complex data +- Metadata key conventions +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/003-acceptingloggers + +- Logging +- Logging best practices +- 003: Accepting loggers in libraries + +Article + +# 003: Accepting loggers in libraries + +Accept loggers through method parameters to ensure proper metadata propagation. + +## Overview + +Libraries should accept logger instances through method parameters rather than storing them as instance variables. This practice ensures metadata (such as correlation IDs) is properly propagated down the call stack, while giving applications control over logging configuration. + +### Motivation + +When libraries accept loggers as method parameters, they enable automatic propagation of contextual metadata attached to the logger instance. This is especially important for distributed systems where correlation IDs must flow through the entire request processing pipeline. + +#### Recommended: Accept logger through method parameters + +// ✅ Good: Pass the logger through method parameters. +struct RequestProcessor { + +// Add structured metadata that every log statement should contain. +var logger = logger +logger[metadataKey: "request.method"] = "\(request.method)" +logger[metadataKey: "request.path"] = "\(request.path)" +logger[metadataKey: "request.id"] = "\(request.id)" + +logger.debug("Processing request") + +// Pass the logger down to maintain metadata context. +let validatedData = try validateRequest(request, logger: logger) +let result = try await executeBusinessLogic(validatedData, logger: logger) + +logger.debug("Request processed successfully") +return result +} + +logger.debug("Validating request parameters") +// Include validation logic that uses the same logger context. +return ValidatedRequest(request) +} + +logger.debug("Executing business logic") + +// Further propagate the logger to other services. +let dbResult = try await databaseService.query(data.query, logger: logger) + +logger.debug("Business logic completed") +return HTTPResponse(data: dbResult) +} +} + +#### Alternative: Accept logger through initializer when appropriate + +// ✅ Acceptable: Logger through initializer for long-lived components +final class BackgroundJobProcessor { +private let logger: Logger + +init(logger: Logger) { +self.logger = logger +} + +func run() async { +// Execute some long running work +logger.debug("Update about long running work") +// Execute some more long running work +} +} + +#### Avoid: Libraries creating their own loggers + +Libraries might create their own loggers; however, this leads to two problems. First, users of the library can’t inject their own loggers which means they have no control in customizing the log level or log handler. Secondly, it breaks the metadata propagation since users can’t pass in a logger with already attached metadata. + +// ❌ Bad: Library creates its own logger +final class MyLibrary { +private let logger = Logger(label: "MyLibrary") // Loses all context +} + +// ✅ Good: Library accepts logger from caller +final class MyLibrary { +func operation(logger: Logger) { +// Maintains caller's context and metadata +} +} + +## See Also + +001: Choosing log levels + +Select appropriate log levels in applications and libraries. + +002: Structured logging + +Use metadata to create machine-readable, searchable log entries. + +- 003: Accepting loggers in libraries +- Overview +- Motivation +- Example +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/001-choosingloglevels) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/002-structuredlogging) + + + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/003-acceptingloggers) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/log(level:message:metadata:source:file:function:line:) + +#app-main) + +- Logging +- MultiplexLogHandler +- log(level:message:metadata:source:file:function:line:) + +Instance Method + +# log(level:message:metadata:source:file:function:line:) + +Log a message using the log level and source that you provide. + +func log( +level: Logger.Level, +message: Logger.Message, +metadata: Logger.Metadata?, +source: String, +file: String, +function: String, +line: UInt +) + +Logging.swift + +## Parameters + +`level` + +The log level to log the `message`. + +`message` + +The message to be logged. The `message` parameter supports any string interpolation literal. + +`metadata` + +One-off metadata to attach to this log message. + +`source` + +The source this log message originates from. The value defaults to the module that emits the log message. + +`file` + +The file this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#fileID`. + +`function` + +The function this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#function`. + +`line` + +The line this log message originates from. There’s usually no need to pass it explicitly, as it defaults to `#line`. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/subscript(metadatakey:) + +#app-main) + +- Logging +- MultiplexLogHandler +- subscript(metadataKey:) + +Instance Subscript + +# subscript(metadataKey:) + +Add, change, or remove a logging metadata item. + +Logging.swift + +## Overview + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/loglevel + +- Logging +- MultiplexLogHandler +- logLevel + +Instance Property + +# logLevel + +Get or set the log level configured for this `Logger`. + +var logLevel: Logger.Level { get set } + +Logging.swift + +## Discussion + +## See Also + +### Inspecting a log handler + +`var metadata: Logger.Metadata` + +Get or set the entire metadata storage as a dictionary. + +`var metadataProvider: Logger.MetadataProvider?` + +The metadata provider. + +- logLevel +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/metadata + +- Logging +- MultiplexLogHandler +- metadata + +Instance Property + +# metadata + +Get or set the entire metadata storage as a dictionary. + +var metadata: Logger.Metadata { get set } + +Logging.swift + +## See Also + +### Inspecting a log handler + +`var logLevel: Logger.Level` + +Get or set the log level configured for this `Logger`. + +`var metadataProvider: Logger.MetadataProvider?` + +The metadata provider. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/metadataprovider + + + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/loghandler-implementations + +- Logging +- MultiplexLogHandler +- LogHandler Implementations + +API Collection + +# LogHandler Implementations + +## Topics + +### Instance Methods + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, file: String, function: String, line: UInt)` + +A default implementation for a log message handler. + +Deprecated + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/init(_:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/init(_:metadataprovider:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/log(level:message:metadata:source:file:function:line:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/subscript(metadatakey:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/loglevel) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/metadata) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/metadataprovider) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/multiplexloghandler/loghandler-implementations) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/log(level:message:metadata:source:file:function:line:) + +#app-main) + +- Logging +- LogHandler +- log(level:message:metadata:source:file:function:line:) + +Instance Method + +# log(level:message:metadata:source:file:function:line:) + +The library calls this method when a log handler must emit a log message. + +func log( +level: Logger.Level, +message: Logger.Message, +metadata: Logger.Metadata?, +source: String, +file: String, +function: String, +line: UInt +) + +LogHandler.swift + +**Required** Default implementation provided. + +## Parameters + +`level` + +The log level of the message. + +`message` + +The message to log. To obtain a `String` representation call `message.description`. + +`metadata` + +The metadata associated to this log message. + +`source` + +The source where the log message originated, for example the logging module. + +`file` + +The file this log message originates from. + +`function` + +The function this log message originates from. + +`line` + +The line this log message originates from. + +## Discussion + +There is no need for the `LogHandler` to check if the `level` is above or below the configured `logLevel` as `Logger` already performed this check and determined that a message should be logged. + +## Default Implementations + +### LogHandler Implementations + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, source: String, file: String, function: String, line: UInt)` + +A default implementation for a log message handler that forwards the source location for the message. + +Deprecated + +## See Also + +### Sending log messages + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, file: String, function: String, line: UInt)` + +SwiftLog 1.0 log compatibility method. + +A default implementation for a log message handler. + +- log(level:message:metadata:source:file:function:line:) +- Parameters +- Discussion +- Default Implementations +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/log(level:message:metadata:source:file:function:line:)-69pez + + + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/log(level:message:metadata:file:function:line:) + +#app-main) + +- Logging +- LogHandler +- log(level:message:metadata:file:function:line:) + +Instance Method + +# log(level:message:metadata:file:function:line:) + +SwiftLog 1.0 log compatibility method. + +func log( +level: Logger.Level, +message: Logger.Message, +metadata: Logger.Metadata?, +file: String, +function: String, +line: UInt +) + +LogHandler.swift + +**Required** Default implementation provided. + +## Parameters + +`level` + +The log level of the message. + +`message` + +The message to log. To obtain a `String` representation call `message.description`. + +`metadata` + +The metadata associated to this log message. + +`file` + +The file this log message originates from. + +`function` + +The function this log message originates from. + +`line` + +The line this log message originates from. + +## Discussion + +Please do _not_ implement this method when you create a LogHandler implementation. Implement `log(level:message:metadata:source:file:function:line:)` instead. + +## Default Implementations + +### LogHandler Implementations + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, file: String, function: String, line: UInt)` + +A default implementation for a log message handler. + +Deprecated + +## See Also + +### Sending log messages + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, source: String, file: String, function: String, line: UInt)` + +The library calls this method when a log handler must emit a log message. + +A default implementation for a log message handler that forwards the source location for the message. + +- log(level:message:metadata:file:function:line:) +- Parameters +- Discussion +- Default Implementations +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/log(level:message:metadata:file:function:line:)-1xdau + +-1xdau#app-main) + +- Logging +- LogHandler +- log(level:message:metadata:file:function:line:) + +Instance Method + +# log(level:message:metadata:file:function:line:) + +A default implementation for a log message handler. + +func log( +level: Logger.Level, +message: Logger.Message, +metadata: Logger.Metadata?, +file: String, +function: String, +line: UInt +) + +LogHandler.swift + +## Parameters + +`level` + +The log level of the message. + +`message` + +The message to log. To obtain a `String` representation call `message.description`. + +`metadata` + +The metadata associated to this log message. + +`file` + +The file this log message originates from. + +`function` + +The function this log message originates from. + +`line` + +The line this log message originates from. + +## See Also + +### Sending log messages + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, source: String, file: String, function: String, line: UInt)` + +The library calls this method when a log handler must emit a log message. + +**Required** Default implementation provided. + +A default implementation for a log message handler that forwards the source location for the message. + +Deprecated + +`func log(level: Logger.Level, message: Logger.Message, metadata: Logger.Metadata?, file: String, function: String, line: UInt)` + +SwiftLog 1.0 log compatibility method. + +- log(level:message:metadata:file:function:line:) +- Parameters +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/subscript(metadatakey:) + +#app-main) + +- Logging +- LogHandler +- subscript(metadataKey:) + +Instance Subscript + +# subscript(metadataKey:) + +Add, remove, or change the logging metadata. + +LogHandler.swift + +**Required** + +## Parameters + +`metadataKey` + +The key for the metadata item + +## Overview + +- subscript(metadataKey:) +- Parameters +- Overview + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/loglevel + +- Logging +- LogHandler +- logLevel + +Instance Property + +# logLevel + +Get or set the configured log level. + +var logLevel: Logger.Level { get set } + +LogHandler.swift + +**Required** + +## Discussion + +## See Also + +### Inspecting a log handler + +`var metadata: Logger.Metadata` + +Get or set the entire metadata storage as a dictionary. + +`var metadataProvider: Logger.MetadataProvider?` + +The metadata provider this log handler uses when a log statement is about to be emitted. + +**Required** Default implementation provided. + +- logLevel +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/metadata + +- Logging +- LogHandler +- metadata + +Instance Property + +# metadata + +Get or set the entire metadata storage as a dictionary. + +var metadata: Logger.Metadata { get set } + +LogHandler.swift + +**Required** + +## Discussion + +## See Also + +### Inspecting a log handler + +`var logLevel: Logger.Level` + +Get or set the configured log level. + +`var metadataProvider: Logger.MetadataProvider?` + +The metadata provider this log handler uses when a log statement is about to be emitted. + +**Required** Default implementation provided. + +- metadata +- Discussion +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/metadataprovider + +- Logging +- LogHandler +- metadataProvider + +Instance Property + +# metadataProvider + +The metadata provider this log handler uses when a log statement is about to be emitted. + +var metadataProvider: Logger.MetadataProvider? { get set } + +LogHandler.swift + +**Required** Default implementation provided. + +## Discussion + +A `Logger.MetadataProvider` may add a constant set of metadata, or use task-local values to pick up contextual metadata and add it to emitted logs. + +## Default Implementations + +### LogHandler Implementations + +`var metadataProvider: Logger.MetadataProvider?` + +Default implementation for a metadata provider that defaults to nil. + +## See Also + +### Inspecting a log handler + +`var logLevel: Logger.Level` + +Get or set the configured log level. + +**Required** + +`var metadata: Logger.Metadata` + +Get or set the entire metadata storage as a dictionary. + +- metadataProvider +- Discussion +- Default Implementations +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/logger). + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/log(level:message:metadata:source:file:function:line:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/log(level:message:metadata:source:file:function:line:)-69pez) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/log(level:message:metadata:file:function:line:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/log(level:message:metadata:file:function:line:)-1xdau) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/subscript(metadatakey:)) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/loglevel) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/metadata) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-log/main/documentation/logging/loghandler/metadataprovider) + +Has it really been five years since Swift Package Index launched? Read our anniversary blog post! + +#### 404 - Not Found + +If you were expecting to find a page here, please raise an issue. + +From here, you'll want to go to the home page or search for a package. + +| +| + +--- + diff --git a/.claude/docs/https_-swiftpackageindex.com-apple-swift-openapi-generator-1.10.3-documentation-swift-openapi-generator.md b/.claude/docs/https_-swiftpackageindex.com-apple-swift-openapi-generator-1.10.3-documentation-swift-openapi-generator.md new file mode 100644 index 00000000..1865fb27 --- /dev/null +++ b/.claude/docs/https_-swiftpackageindex.com-apple-swift-openapi-generator-1.10.3-documentation-swift-openapi-generator.md @@ -0,0 +1,6914 @@ + + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator + +# Swift OpenAPI Generator + +Generate Swift client and server code from an OpenAPI document. + +## Overview + +OpenAPI is a specification for documenting HTTP services. An OpenAPI document is written in either YAML or JSON, and can be read by tools to help automate workflows, such as generating the necessary code to send and receive HTTP requests. + +Swift OpenAPI Generator is a Swift package plugin that can generate the ceremony code required to make API calls, or implement API servers. + +The code is generated at build-time, so it’s always in sync with the OpenAPI document and doesn’t need to be committed to your source repository. + +## Features + +- Works with OpenAPI Specification versions 3.0 and 3.1. + +- Streaming request and response bodies enabling use cases such as JSON event streams, and large payloads without buffering. + +- Support for JSON, multipart, URL-encoded form, base64, plain text, and raw bytes, represented as value types with type-safe properties. + +- Client, server, and middleware abstractions, decoupling the generated code from the HTTP client library and web framework. + +To see these features in action, see Checking out an example project. + +## Usage + +Swift OpenAPI Generator can be used to generate API clients and server stubs. + +Below you can see some example code, or you can follow one of the Working with Swift OpenAPI Generator tutorials. + +### Using a generated API client + +The generated `Client` type provides a method for each HTTP operation defined in the OpenAPI document and can be used with any HTTP library that provides an implementation of `ClientTransport`. + +import OpenAPIURLSession +import Foundation + +let client = Client( +serverURL: URL(string: "http://localhost:8080/api")!, +transport: URLSessionTransport() +) +let response = try await client.getGreeting() +print(try response.ok.body.json.message) + +### Using generated API server stubs + +To implement a server, define a type that conforms to the generated `APIProtocol`, providing a method for each HTTP operation defined in the OpenAPI document. + +The server can be used with any web framework that provides an implementation of `ServerTransport`, which allows you to register your API handlers with the HTTP server. + +import OpenAPIRuntime +import OpenAPIVapor +import Vapor + +struct Handler: APIProtocol { + +let name = input.query.name ?? "Stranger" +return .ok(.init(body: .json(.init(message: "Hello, \(name)!")))) +} +} + +@main struct HelloWorldVaporServer { +static func main() async throws { +let app = try await Application.make() +let transport = VaporTransport(routesBuilder: app) +let handler = Handler() +try handler.registerHandlers(on: transport, serverURL: URL(string: "/api")!) +try await app.execute() +} +} + +### Package ecosystem + +The Swift OpenAPI Generator project is split across multiple repositories to enable extensibility and minimize dependencies in your project. + +| Repository | Description | +| --- | --- | +| apple/swift-openapi-generator | Swift package plugin and CLI | +| apple/swift-openapi-runtime | Runtime library used by the generated code | +| apple/swift-openapi-urlsession | `ClientTransport` using URLSession | +| swift-server/swift-openapi-async-http-client | `ClientTransport` using AsyncHTTPClient | +| swift-server/swift-openapi-vapor | `ServerTransport` using Vapor | +| swift-server/swift-openapi-hummingbird | `ServerTransport` using Hummingbird | +| swift-server/swift-openapi-lambda | `ServerTransport` using AWS Lambda | + +### Requirements and supported features + +| Generator versions | Supported OpenAPI versions | Minimum Swift version | +| --- | --- | --- | +| `1.0.0` … `main` | 3.0, 3.1 | 5.9 | + +See also Supported OpenAPI features. + +### Supported platforms and minimum versions + +The generator is used during development and is supported on macOS and Linux. + +The generated code, runtime library, and transports are supported on more platforms, listed below. + +| Component | macOS | Linux | iOS | tvOS | watchOS | visionOS | +| --- | --- | --- | --- | --- | --- | --- | +| Generator plugin and CLI | ✅ 10.15+ | ✅ | ✖️ | ✖️ | ✖️ | ✖️ | +| Generated code and runtime library | ✅ 10.15+ | ✅ | ✅ 13+ | ✅ 13+ | ✅ 6+ | ✅ 1+ | + +### Documentation and example projects + +To get started, check out the topics below, or one of the Working with Swift OpenAPI Generator tutorials. + +You can also experiment with one of the examples in Checking out an example project that use Swift OpenAPI Generator and integrate with other packages in the ecosystem. + +Or if you prefer to watch a video, check out Meet Swift OpenAPI Generator from WWDC23. + +### Example OpenAPI document + +openapi: '3.1.0' +info: +title: GreetingService +version: 1.0.0 +servers: +- url: +description: Example service deployment. +paths: +/greet: +get: +operationId: getGreeting +parameters: +- name: name +required: false +in: query +description: The name used in the returned greeting. +schema: +type: string +responses: +'200': +description: A success response with a greeting. +content: +application/json: +schema: +$ref: '#/components/schemas/Greeting' +components: +schemas: +Greeting: +type: object +description: A value with the greeting contents. +properties: +message: +type: string +description: The string representation of the greeting. +required: +- message + +## Topics + +### Essentials + +Checking out an example project + +Check out a working example to learn how packages using Swift OpenAPI Generator can be structured and integrated with the ecosystem. + +Generating a client in a Swift package + +This tutorial guides you through building _GreetingServiceClient_—an API client for a fictitious service that returns a personalized greeting. + +Generating a client in an Xcode project + +Generating server stubs in a Swift package + +This tutorial guides you through building _GreetingService_—an API server for a fictitious service that returns a personalized greeting. + +### OpenAPI + +Exploring an OpenAPI document + +This tutorial covers the basics of the OpenAPI specification and guides you through writing an OpenAPI document that describes a service API. We’ll use a fictitious service that returns a personalized greeting. + +Adding OpenAPI and Swagger UI endpoints + +One of the most popular ways to share your OpenAPI document with your users is to host it alongside your API server itself. + +Practicing spec-driven API development + +Design, iterate on, and generate both client and server code from your hand-written OpenAPI document. + +Useful OpenAPI patterns + +Explore OpenAPI patterns for common data representations. + +Supported OpenAPI features + +Learn which OpenAPI features are supported by Swift OpenAPI Generator. + +### Generator plugin and CLI + +Configuring the generator + +Create a configuration file to control the behavior of the generator. + +Manually invoking the generator CLI + +Manually invoke the command-line tool to generate code as an alternative to the Swift package build plugin. + +Frequently asked questions + +Review some frequently asked questions below. + +### API stability + +API stability of the generator + +Understand the impact of updating the generator package plugin on the generated Swift code. + +API stability of generated code + +Understand the impact of changes to the OpenAPI document on generated Swift code. + +### Getting involved + +Project scope and goals + +Learn about what is in and out of scope of Swift OpenAPI Generator. + +Contributing to Swift OpenAPI Generator + +Help improve Swift OpenAPI Generator by implementing a missing feature or fixing a bug. + +Collaborate on API changes to Swift OpenAPI Generator by writing a proposal. + +Learn about the internals of Swift OpenAPI Generator. + +- Swift OpenAPI Generator +- Overview +- Features +- Usage +- Using a generated API client +- Using generated API server stubs +- Package ecosystem +- Requirements and supported features +- Supported platforms and minimum versions +- Documentation and example projects +- Example OpenAPI document +- Topics + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/api-stability-of-the-generator + +- Swift OpenAPI Generator +- API stability of the generator + +Article + +# API stability of the generator + +Understand the impact of updating the generator package plugin on the generated Swift code. + +## Overview + +Swift OpenAPI Generator generates client and server Swift code from an OpenAPI document. The generated code may change if the OpenAPI document is changed or a different version of the generator is used. + +This document outlines the API stability goals for the generator to help you avoid unintentional build errors when updating to a new version of Swift OpenAPI Generator. + +Swift OpenAPI Generator follows Semantic Versioning 2.0.0 for the following, which are considered part of its API: + +- The name of the Swift OpenAPI Generator package plugin. + +- The format of the config file provided to Swift OpenAPI Generator (plugin or CLI tool). + +- The Swift OpenAPI Generator CLI tool arguments, options, and flags. + +If you upgrade any of the components above to the next non-breaking version, your project should continue to build successfully. Check out how these rules are applied, and what a breaking change means for the generated code: API stability of generated code. + +### Implementation details + +In contrast to the guarantees provided for the API of Swift OpenAPI Generator, the following list of behaviors are _not_ considered API, and can change without prior warning: + +- The number and names of files generated by the Swift OpenAPI Generator CLI and plugins. + +- The SPI provided by the OpenAPIRuntime library used by generated code (marked with `@_spi(Generated)`). + +- The business logic of the generated code, any code that isn’t part of the API of the generated code. + +- The diagnostics emitted by the generator, both their severity and printed description. + +## See Also + +### Related Documentation + +API stability of generated code + +Understand the impact of changes to the OpenAPI document on generated Swift code. + +### API stability + +- API stability of the generator +- Overview +- Implementation details +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/project-scope-and-goals + +- Swift OpenAPI Generator +- Project scope and goals + +Article + +# Project scope and goals + +Learn about what is in and out of scope of Swift OpenAPI Generator. + +## Overview + +Swift OpenAPI Generator aims to cover the most commonly used OpenAPI features to simplify your workflow and streamline your codebase. The main goal is to reduce ceremony by generating the repetitive, verbose, and error-prone code associated with encoding API inputs, making HTTP requests, parsing HTTP responses, and decoding the outputs. + +The goal of the project is to compose with the wider OpenAPI tooling ecosystem so functionality beyond reducing ceremony using code generation is, by default, considered out of scope. When in doubt, file an issue to discuss whether your idea should be a feature of Swift OpenAPI Generator, or fits better as a separate project. + +#### Principle: Faithfully represent the OpenAPI document + +The OpenAPI document is considered as the source of truth. The generator aims to produce code that reflects the document where possible. This includes the specification structure, and the identifiers used by the authors of the OpenAPI document. + +As a result, the generated code may not always be idiomatic Swift style or conform to your own custom style guidelines. For example, the API operation identifiers may not be `lowerCamelCase` by default, when using the `defensive` naming strategy. However, an alternative naming strategy called `idiomatic` is available since version 1.6.0 that closer matches Swift conventions. + +If you require the generated code to conform to specific style, we recommend you preprocess the OpenAPI document to update the identifiers to produce different code. + +For larger documents, you may want to do this programmatically and, if you are doing so in Swift, you could use OpenAPIKit, which is the same library used by Swift OpenAPI Generator. + +#### Principle: Generate code that evolves with the OpenAPI document + +As features are added to a service, the OpenAPI document for that service will evolve. The generator aims to produce code that evolves ergonomically as the OpenAPI document evolves. + +As a result, the generated code might appear unnecessarily verbose, especially for simple operations. + +A concrete example of this is the use of enum types when there is only one documented scenario. This allows for a new enum case to be added to the generated Swift code when a new scenario is added to the OpenAPI document, which results in a better experience for users of the generated code. + +Another example is the generation of empty structs within the input or output types. For example, the input type will contain a nested struct for the header fields, even if the API operation has no documented header fields. + +#### Principle: Reduce complexity of the generator implementation + +Some generators offer lots of options that affect the code generation process. In order to keep the project streamlined and maintainable, Swift OpenAPI Generator offers very few options. + +One concrete example of this is that users cannot configure the names of generated types, such as `Client` and `APIProtocol`, and there is no attempt to prevent namespace collisions in the target into which it is generated. + +Instead, users are advised to generate code into a dedicated target, and use Swift’s module system to separate the generated code from code that depends on it. + +Another example is the lack of ability to customize how Swift names are computed from strings provided in the OpenAPI document. + +You can read more about this in API stability of generated code. + +## See Also + +### Related Documentation + +Contributing to Swift OpenAPI Generator + +Help improve Swift OpenAPI Generator by implementing a missing feature or fixing a bug. + +Supported OpenAPI features + +Learn which OpenAPI features are supported by Swift OpenAPI Generator. + +API stability of generated code + +Understand the impact of changes to the OpenAPI document on generated Swift code. + +### Getting involved + +Collaborate on API changes to Swift OpenAPI Generator by writing a proposal. + +Learn about the internals of Swift OpenAPI Generator. + +- Project scope and goals +- Overview +- Guiding principles +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/useful-openapi-patterns + +- Swift OpenAPI Generator +- Useful OpenAPI patterns + +Article + +# Useful OpenAPI patterns + +Explore OpenAPI patterns for common data representations. + +## Overview + +This document lists some common OpenAPI patterns that have been tested to work well with Swift OpenAPI Generator. + +### Open enums and oneOfs + +While `enum` and `oneOf` are closed by default in OpenAPI, meaning that decoding fails if an unknown value is encountered, it can be a good practice to instead use open enums and oneOfs in your API, as it allows adding new cases over time without having to roll a new API-breaking version. + +#### Enums + +A simple enum looks like: + +type: string +enum: +- foo +- bar +- baz + +To create an open enum, in other words an enum that has a “default” value that doesn’t fail during decoding, but instead preserves the unknown value, wrap the enum in an `anyOf` and add a string schema as the second subschema. + +anyOf: +- type: string +enum: +- foo +- bar +- baz +- type: string + +When accessing this data on the generated Swift code, first check if the first value (closed enum) is non-nil – if so, one of the known enum values were provided. If the enum value is nil, the second string value will contain the raw value that was provided, which you can log or pass through your program. + +#### oneOfs + +A simple oneOf looks like: + +oneOf: +- #/components/schemas/Foo +- #/components/schemas/Bar +- #/components/schemas/Baz + +To create an open oneOf, wrap it in an `anyOf`, and provide a fragment as the second schema, or a more constrained container if you know that the payload will always follow a certain structure. + +MyOpenOneOf: +anyOf: +- oneOf: +- #/components/schemas/Foo +- #/components/schemas/Bar +- #/components/schemas/Baz +- {} + +The above is the most flexible, any JSON payload that doesn’t match any of the cases in oneOf will be saved into the second schema. + +If you know the payload is, for example, always a JSON object, you can constrain the second schema further, like this: + +MyOpenOneOf: +anyOf: +- oneOf: +- #/components/schemas/Foo +- #/components/schemas/Bar +- #/components/schemas/Baz +- type: object + +### Event streams: JSON Lines, JSON Sequence, and Server-sent Events + +While JSON Lines, JSON Sequence, and Server-sent Events are not explicitly part of the OpenAPI 3.0 or 3.1 specification, you can document an operation that returns events and also the event payloads themselves. + +Each event stream format has one or more commonly associated content types with it: + +- JSON Lines: `application/jsonl`, `application/x-ndjson`, others. + +- JSON Sequence: `application/json-seq`. + +- Server-sent Events: `text/event-stream`. + +In the OpenAPI document, an example of an operation that returns JSON Lines could look like (analogous for the other formats): + +paths: +/events: +get: +operationId: getEvents +responses: +'200': +content: +application/jsonl: {} +components: +schemas: +MyEvent: +type: object +properties: +... + +- JSON Lines + +- decode: `AsyncSequence>.asDecodedJSONLines(of:decoder:)` + +- JSON Sequence + +- decode: `AsyncSequence>.asDecodedJSONSequence(of:decoder:)` + +- Server-sent Events + +- decode (if data is JSON): `AsyncSequence>.asDecodedServerSentEventsWithJSONData(of:decoder:)` + +- decode (if data is JSON with a non-JSON terminating byte sequence): `AsyncSequence>.asDecodedServerSentEventsWithJSONData(of:decoder:while:)` + +- decode (for other data): `AsyncSequence>.asDecodedServerSentEvents(while:)` + +See the `event-streams-*` client and server examples in Checking out an example project to learn how to produce and consume these sequences. + +## See Also + +### OpenAPI + +Exploring an OpenAPI document + +This tutorial covers the basics of the OpenAPI specification and guides you through writing an OpenAPI document that describes a service API. We’ll use a fictitious service that returns a personalized greeting. + +Adding OpenAPI and Swagger UI endpoints + +One of the most popular ways to share your OpenAPI document with your users is to host it alongside your API server itself. + +Practicing spec-driven API development + +Design, iterate on, and generate both client and server code from your hand-written OpenAPI document. + +Supported OpenAPI features + +Learn which OpenAPI features are supported by Swift OpenAPI Generator. + +- Useful OpenAPI patterns +- Overview +- Open enums and oneOfs +- Event streams: JSON Lines, JSON Sequence, and Server-sent Events +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/contributing-to-swift-openapi-generator + +- Swift OpenAPI Generator +- Contributing to Swift OpenAPI Generator + +Article + +# Contributing to Swift OpenAPI Generator + +Help improve Swift OpenAPI Generator by implementing a missing feature or fixing a bug. + +## Overview + +Swift OpenAPI Generator is an open source project that encourages contributions, either to the generator itself, or by building new transport and middleware packages. + +### Missing transport or middleware + +Anyone can create a custom transport or middleware in a new package that depends on the runtime library and provides a type conforming to one of the transport or middleware protocols. + +Any adopter of Swift OpenAPI Generator can then depend on that package and use the transport or middleware when creating their client or server. + +### Missing or broken feature in the generator + +The code generator project is written in Swift and can be thought of as a function that takes an OpenAPI document as input and provides one or more Swift source files as output. + +The generated Swift code depends on the runtime library, so some features might require coordinated changes in both the runtime and generator repositories. + +Similarly, any changes to the transport and middleware protocols in the runtime library must consider the impact on existing transport and middleware implementation packages. + +### Testing the generator + +The generator relies on a mix of unit and integration tests. + +When contributing, consider how the change can be tested and how the tests will be maintained over time. + +### Runtime SPI for generated code + +The generated code relies on functionality in the runtime library that is not part of its public API. This is provided in an SPI, named `Generated` and is not intended to be used directly by adopters of the generator. + +To use this functionality, use an SPI import: + +@_spi(Generated) import OpenAPIRuntime + +### Example contribution workflow + +Let’s walk through the steps to implement a missing OpenAPI feature that requires changes in multiple repositories. For example, adding support for a new query style. + +01. Clone the generator and runtime repositories and set up a development environment where the generator uses the local runtime package dependency, by either: + +1. Adding both packages to an Xcode workspace; or + +2. Using `swift package edit` to edit the runtime dependency used in the generator package. +02. Run all of the tests in the generator package and make sure they pass, which includes reference tests for the generated code. + +03. Update the OpenAPI document in the reference test to use the new OpenAPI feature. + +04. Manually update the Swift code in the reference test to include the code you’d like the generator to output. + +05. At this point **the reference tests should _fail_**. The differences between the generated code and the desired code are printed in the reference test output. + +06. Make incremental changes to the generator and runtime library until the reference tests pass. + +07. Once the reference test succeeds, add unit tests for the code you changed. + +08. Open pull requests for both the generator and runtime changes and cross-reference them in the pull request descriptions. Note: it’s expected that the CI for the generator pull request will fail, because it won’t have the changes from the runtime library until the runtime pull request it is merged. + +09. One of the project maintainers will review your changes and, once approved, will merge the runtime changes and release a new version of the runtime package. + +10. The generator pull request will need to be updated to bump the minimum version of the runtime dependency. At this point the CI should pass and the generator pull request can be merged. + +11. All done! Thank you for your contribution! 🙏 + +## See Also + +### Getting involved + +Project scope and goals + +Learn about what is in and out of scope of Swift OpenAPI Generator. + +Collaborate on API changes to Swift OpenAPI Generator by writing a proposal. + +Learn about the internals of Swift OpenAPI Generator. + +- Contributing to Swift OpenAPI Generator +- Overview +- Missing transport or middleware +- Missing or broken feature in the generator +- Testing the generator +- Runtime SPI for generated code +- Example contribution workflow +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/api-stability-of-generated-code + +- Swift OpenAPI Generator +- API stability of generated code + +Article + +# API stability of generated code + +Understand the impact of changes to the OpenAPI document on generated Swift code. + +## Overview + +Swift OpenAPI Generator generates client and server Swift code from an OpenAPI document. The generated code may change if the OpenAPI document is changed or a different version of the generator is used. + +This document outlines the API stability goals for the generated code to help you avoid unintentional build errors when updating the OpenAPI document. + +### Example changes + +There are three API boundaries to consider: + +- **HTTP**: the requests and responses sent over the network + +- **OpenAPI**: the description of the API using the OpenAPI specification + +- **Swift**: the client or server code generated from the OpenAPI document + +Below is a table of example changes you might make to an OpenAPI document, and whether that would result in a breaking change (❌) or a non-breaking change (✅). + +| Change | HTTP | OpenAPI | Swift | +| --- | --- | --- | --- | +| Add a new schema | ✅ | ✅ | ✅ | +| Add a new property to an existing schema (†) | ✅ | ✅ | ⚠️ | +| Add a new operation | ✅ | ✅ | ✅ | +| Add a new response to an existing operation (‡) | ✅ | ❌ | ❌ | +| Add a new content type to an existing response (§) | ✅ | ❌ | ❌ | +| Remove a required property | ❌ | ❌ | ❌ | +| Rename a schema | ✅ | ❌ | ❌ | + +The table above is not exhaustive, but it shows a pattern: + +- Removing (or renaming) anything that the adopter might have relied on is usually a breaking change. + +- Adding a new schema or a new operation is an additive, non-breaking change (†). + +- Adding a new response or content type is considered a breaking change (‡)(§). + +### Avoid including the generated code in your public API + +Due to the complicated rules above, we recommend that you don’t publish the generated code for others to rely on. + +If you do expose the generated code as part of your package’s API, we recommend auditing your API for breaking changes, especially if your package uses Semantic Versioning. + +Maintaining Swift library package that uses the generated code as an implementation detail is supported (and recommended), as long as no generated symbols are exported in your public API. + +#### Create a curated client library package + +Let’s consider an example where you’re creating a Swift library that provides a curated API for making the following API call: + +% curl +{ +"message": "Howdy, Maria!" +} + +You can hide the generated client code as an implementation detail and provide a hand-written Swift API to your users using the following steps: + +1. Create a library target that is not exposed as a product, called, for example, `GeneratedGreetingClient`, which uses the Swift OpenAPI Generator package plugin. + +2. Create another library target that is exposed as a product, called, for example, `Greeter`, which depends on the `GeneratedGreetingClient` target but doesn’t use the imported types in its public API. + +This way, you are in full control of the public API of the `Greeter` library, but you also benefit from calling the service using generated code. + +## See Also + +### Related Documentation + +API stability of the generator + +Understand the impact of updating the generator package plugin on the generated Swift code. + +### API stability + +- API stability of generated code +- Overview +- Example changes +- Avoid including the generated code in your public API +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/configuring-the-generator + +- Swift OpenAPI Generator +- Configuring the generator + +Article + +# Configuring the generator + +Create a configuration file to control the behavior of the generator. + +## Overview + +Swift OpenAPI Generator build plugin requires a configuration file that controls what files are generated. + +The command-line tool also uses the same configuration file. + +### Create a configuration file + +The configuration file is named `openapi-generator-config.yaml` or `openapi-generator-config.yml` and must exist in the target source directory. + +. +├── Package.swift +└── Sources +└── MyTarget +├── MyCode.swift +├── openapi-generator-config.yaml <-- place the file here +└── openapi.yaml + +The configuration file has the following keys: + +- `generate` (required): array of strings. Each string value is a mode for the generator invocation, which is one of: + +- `types`: Common types and abstractions used by generated client and server code. + +- `client`: Client code that can be used with any client transport (depends on code from `types`). + +- `server`: Server code that can be used with any server transport (depends on code from `types`). +- `accessModifier` (optional): a string. Customizes the visibility of the API of the generated code. + +- `public`: Generated API is accessible from other modules and other packages (if included in a product). + +- `package`: Generated API is accessible from other modules within the same package or project. + +- `internal` (default): Generated API is accessible from the containing module only. +- `additionalImports` (optional): array of strings. Each string value is a Swift module name. An import statement will be added to the generated source files for each module. + +- `additionalFileComments` (optional): array of strings. Each string value is a comment that will be added to the top of each generated file (after the do-not-edit comment). Useful for adding directives like `swift-format-ignore-file` or `swiftlint:disable all`. + +- `filter` (optional): Filters to apply to the OpenAPI document before generation. + +- `operations`: Operations with these operation IDs will be included in the filter. + +- `tags`: Operations tagged with these tags will be included in the filter. + +- `paths`: Operations for these paths will be included in the filter. + +- `schemas`: These (additional) schemas will be included in the filter. +- `namingStrategy` (optional): a string. The strategy of converting OpenAPI identifiers into Swift identifiers. + +- `defensive` (default): Produces non-conflicting Swift identifiers for any OpenAPI identifiers. Check out SOAR-0001 for details. + +- `idiomatic`: Produces more idiomatic Swift identifiers for OpenAPI identifiers. Might produce name conflicts (in that case, switch for details. +- `nameOverrides` (optional): a string to string dictionary. Allows customizing how individual OpenAPI identifiers get converted to Swift identifiers. + +- `typeOverrides` (optional): Allows replacing a generated type with a custom type. + +- `schemas` (optional): a string to string dictionary. The key is the name of the schema, the last component of `#/components/schemas/Foo` (here, `Foo`). The value is the custom type name, such as `CustomFoo`. Check out details in SOAR-0014. +- `featureFlags` (optional): array of strings. Each string must be a valid feature flag to enable. For a list of currently supported feature flags, check out FeatureFlags.swift. + +### Example config files + +To generate client code in a single target: + +generate: +- types +- client +namingStrategy: idiomatic + +To generate server code in a single target: + +generate: +- types +- server +namingStrategy: idiomatic + +If you are generating client _and_ server code, you can generate the types in a shared target using the following config: + +generate: +- types +namingStrategy: idiomatic + +Then, to generate client code that depends on the module from this target, use the following config (where `APITypes` is the name of the library target that contains the generated `types`): + +generate: +- client +namingStrategy: idiomatic +additionalImports: +- APITypes + +To use the generated code from other packages, also customize the access modifier: + +generate: +- client +namingStrategy: idiomatic +additionalImports: +- APITypes +accessModifier: public + +To add file comments to exclude generated files from formatting tools: + +generate: +- types +- client +namingStrategy: idiomatic +additionalFileComments: +- "swift-format-ignore-file" +- "swiftlint:disable all" + +### Document filtering + +The generator supports filtering the OpenAPI document prior to generation, which can be useful when generating client code for a subset of a large API, or splitting an implementation of a server across multiple modules. + +For example, to generate client code for only the operations with a given tag, use the following config: + +filter: +tags: +- myTag + +When multiple filters are specified, their union will be considered for inclusion. + +In all cases, the transitive closure of dependencies from the components object will be included. + +The CLI also provides a `filter` command that takes the same configuration file as the `generate` command, which can be used to inspect the filtered document: + +% swift-openapi-generator filter --config path/to/openapi-generator-config.yaml path/to/openapi.yaml + +To use this command as a standalone filtering tool, use the following config and redirect stdout to a new file: + +generate: [] +filter: +tags: +- myTag + +### Type overrides + +Type Overrides can be used used to replace the default generated type with a custom type. + +typeOverrides: +schemas: +UUID: Foundation.UUID + +Check out SOAR-0014 for details. + +## See Also + +### Generator plugin and CLI + +Manually invoking the generator CLI + +Manually invoke the command-line tool to generate code as an alternative to the Swift package build plugin. + +Frequently asked questions + +Review some frequently asked questions below. + +- Configuring the generator +- Overview +- Create a configuration file +- Example config files +- Document filtering +- Type overrides +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/documentation-for-maintainers + +- Swift OpenAPI Generator +- Documentation for maintainers + +# Documentation for maintainers + +Learn about the internals of Swift OpenAPI Generator. + +## Overview + +Swift OpenAPI Generator contains multiple moving pieces, from the runtime library, to the generator CLI, plugin, to extension packages using the transport and middleware APIs. + +Use the resources below if you’d like to learn more about how the generator works under the hood, for example as part of contributing a new feature to it. + +## Topics + +Converting between data and Swift types + +Learn about the type responsible for converting between binary data and Swift types. + +Generating custom Codable implementations + +Learn about when and how the generator emits a custom Codable implementation. + +Handling nullable schemas + +Learn how the generator handles schema nullability. + +Supporting recursive types + +Learn how the generator supports recursive types. + +## See Also + +### Getting involved + +Project scope and goals + +Learn about what is in and out of scope of Swift OpenAPI Generator. + +Contributing to Swift OpenAPI Generator + +Help improve Swift OpenAPI Generator by implementing a missing feature or fixing a bug. + +Collaborate on API changes to Swift OpenAPI Generator by writing a proposal. + +- Documentation for maintainers +- Overview +- Topics +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/checking-out-an-example-project + +- Swift OpenAPI Generator +- Checking out an example project + +Article + +# Checking out an example project + +Check out a working example to learn how packages using Swift OpenAPI Generator can be structured and integrated with the ecosystem. + +## Overview + +The following examples show how to use and integrate Swift OpenAPI Generator with other packages in the ecosystem. + +All the examples can be found in the Examples directory of the Swift OpenAPI Generator repository. + +To run an example locally, for example hello-world-urlsession-client-example, clone the Swift OpenAPI Generator repository, and run the example, as shown below: + +% git clone +% cd swift-openapi-generator/Examples +% swift run --package-path hello-world-urlsession-client-example + +## Getting started + +Each of the following packages shows an end-to-end working example with the given transport. + +- hello-world-urlsession-client-example \- A CLI client using the URLSession API. + +- hello-world-async-http-client-example \- A CLI client using the AsyncHTTPClient library. + +- hello-world-vapor-server-example \- A CLI server using the Vapor web framework. + +- hello-world-hummingbird-server-example \- A CLI server using the Hummingbird web framework. + +- HelloWorldiOSClientAppExample \- An iOS client SwiftUI app with a mock server for unit and UI tests. + +- curated-client-library-example \- A library that hides the generated API and exports a hand-written interface, allowing decoupled versioning. + +## Various content types + +The following packages show working with various content types, such as JSON, URL-encoded request bodies, plain text, raw bytes, multipart bodies, as well as event streams, such as JSON Lines, JSON Sequence, and Server-sent Events. + +- various-content-types-client-example \- A client showing how to provide and handle the various content types. + +- various-content-types-server-example \- A server showing how to handle and provide the various content types. + +- event-streams-client-example \- A client showing how to provide and handle event streams. + +- event-streams-server-example \- A server showing how to handle and provide event streams. + +- bidirectional-event-streams-client-example \- A client showing how to handle and provide bidirectional event streams. + +- bidirectional-event-streams-server-example \- A server showing how to handle and provide bidirectional event streams. + +## Integrations + +- swagger-ui-endpoint-example \- A server with endpoints for its raw OpenAPI document and interactive documentation using Swagger UI. + +- postgres-database-example \- A server using a Postgres database for persistent state. + +- command-line-client-example \- A client with a rich command-line interface using Swift Argument Parser. + +## Middleware + +- logging-middleware-oslog-example \- A middleware that logs requests and responses using OSLog (only available on Apple platforms, such as macOS, iOS, and more). + +- logging-middleware-swift-log-example \- A middleware that logs requests and responses using SwiftLog. + +- metrics-middleware-example \- A middleware that collects metrics using SwiftMetrics. + +- tracing-middleware-example \- A middleware that emits traces using Swift Distributed Tracing. + +- retrying-middleware-example \- A middleware that retries some failed requests. + +- auth-client-middleware-example \- A middleware that injects a token header. + +- auth-server-middleware-example \- A middleware that inspects a token header. + +## Ahead-of-time (manual) code generation + +The recommended way to use Swift OpenAPI generator is by integrating the _build plugin_, which all of the examples above use. The build plugin generates Swift code from your OpenAPI document at build time, and you don’t check in the generated code into your git repository. + +However, if you cannot use the build plugin, for example because you must check in your generated code, use the _command plugin_, which you trigger manually either in Xcode or on the command line. See the following example for this workflow: + +- manual-generation-package-plugin-example \- A client using the Swift package command plugin for manual code generation. + +If you can’t even use the command plugin, for example because your package is not allowed to depend on Swift OpenAPI Generator, you can invoke the generator CLI manually from a Makefile. See the following example for this workflow: + +- manual-generation-generator-cli-example \- A client using the `swift-openapi-generator` CLI for manual code generation. + +## Talks + +- FOSDEM 2025: Streaming ChatGPT Proxy with Swift OpenAPI \- A tailored API server, backed by ChatGPT, and client CLI, with end-to-end streaming. + +## See Also + +### Essentials + +Generating a client in a Swift package + +This tutorial guides you through building _GreetingServiceClient_—an API client for a fictitious service that returns a personalized greeting. + +Generating a client in an Xcode project + +Generating server stubs in a Swift package + +This tutorial guides you through building _GreetingService_—an API server for a fictitious service that returns a personalized greeting. + +- Checking out an example project +- Overview +- Getting started +- Various content types +- Integrations +- Middleware +- Ahead-of-time (manual) code generation +- Talks +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/proposals + +- Swift OpenAPI Generator +- Proposals + +# Proposals + +Collaborate on API changes to Swift OpenAPI Generator by writing a proposal. + +## Overview + +For non-trivial changes that affect the public API, the Swift OpenAPI Generator project adopts a lightweight version of the Swift Evolution process. + +Writing a proposal first helps discuss multiple possible solutions early, apply useful feedback from other contributors, and avoid reimplementing the same feature multiple times. + +While it’s encouraged to get feedback by opening a pull request with a proposal early in the process, it’s also important to consider the complexity of the implementation when evaluating different solutions (as per Project scope and goals). For example, this might mean including a link to a branch containing a prototype implementation of the feature in the pull request description. + +### Steps + +1. Make sure there’s a GitHub issue for the feature or change you would like to propose. + +2. Duplicate the `SOAR-NNNN.md` document and replace `NNNN` with the next available proposal number. + +3. Link the GitHub issue from your proposal, and fill in the proposal. + +4. Open a pull request with your proposal and solicit feedback from other contributors. + +5. Once a maintainer confirms that the proposal is ready for review, the state is updated accordingly. The review period is 7 days, and ends when one of the maintainers marks the proposal as Ready for Implementation, or Deferred. + +6. Before the pull request is merged, there should be an implementation ready, either in the same pull request, or a separate one, linked from the proposal. + +7. The proposal is considered Approved once the implementation, proposal PRs have been merged, and, if originally disabled by a feature flag, feature flag enabled unconditionally. + +If you have any questions, tag Honza Dvorsky or Si Beaumont in your issue or pull request on GitHub. + +### Possible review states + +- Awaiting Review + +- In Review + +- Ready for Implementation + +- In Preview + +- Approved + +- Deferred + +### Possible affected components + +- generator + +- runtime + +- client transports + +- server transports + +## Topics + +SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +## See Also + +### Getting involved + +Project scope and goals + +Learn about what is in and out of scope of Swift OpenAPI Generator. + +Contributing to Swift OpenAPI Generator + +Help improve Swift OpenAPI Generator by implementing a missing feature or fixing a bug. + +Learn about the internals of Swift OpenAPI Generator. + +- Proposals +- Overview +- Steps +- Possible review states +- Possible affected components +- Topics +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/supported-openapi-features + +- Swift OpenAPI Generator +- Supported OpenAPI features + +Article + +# Supported OpenAPI features + +Learn which OpenAPI features are supported by Swift OpenAPI Generator. + +## Overview + +Swift OpenAPI Generator is currently focused on supporting OpenAPI 3.0.3 and OpenAPI 3.1.0. + +Supported features are always provided on _both_ client and server. + +### Structured content types + +For the checked serialization formats below, the generator emits types conforming to `Codable`, structured based on the provided JSON Schema. + +For any other formats, the payload is provided as raw bytes (using the `HTTPBody` streaming body type), leaving it up to the adopter to decode as needed. + +- [ ] +JSON + +- when content type is `application/json` or ends with `+json` +- [ ] +URL-encoded form request bodies + +- when content type is `application/x-www-form-urlencoded` +- [ ] +multipart + +- for details, see SOAR-0009 +- [ ] +XML + +#### OpenAPI Object + +- [ ] +openapi + +- [ ] +info + +- [ ] +servers + +- [ ] +paths + +- [ ] +components + +- [ ] +security + +- [ ] +tags + +- [ ] +externalDocs + +#### Info Object + +- [ ] +title + +- [ ] +description + +- [ ] +termsOfService + +- [ ] +contact + +- [ ] +license + +- [ ] +version + +#### Contact Object + +- [ ] +name + +- [ ] +url + +- [ ] +email + +#### License Object + +#### Server Object + +- [ ] +variables + +#### Server Variable Object + +- [ ] +enum + +- [ ] +default + +#### Paths Object + +- [ ] +map from pattern to Path Item Object + +#### Path Item Object + +- [ ] +$ref + +- [ ] +summary + +- [ ] +get/put/post/delete/options/head/patch/trace + +- [ ] +parameters + +#### Operation Object + +- [ ] +operationId + +- [ ] +requestBody + +- [ ] +responses + +- [ ] +callbacks + +- [ ] +deprecated + +#### Request Body Object + +- [ ] +content + +- [ ] +required + +#### Media Type Object + +- [ ] +schema + +- [ ] +example + +- [ ] +examples + +- [ ] +encoding (in multipart only) + +#### Security Requirement Object + +- [ ] +map from name pattern to a list of strings + +#### Responses Object + +- [ ] +map of HTTP status code to response + +#### Response Object + +- [ ] +headers + +- [ ] +links + +#### Header Object + +- [ ] +a special case of Parameter Object + +#### Callback Object + +- [ ] +map from expression to Path Item Object + +#### Schema Object + +- [ ] +multipleOf + +- [ ] +maximum + +- [ ] +exclusiveMaximum + +- [ ] +minimum + +- [ ] +exclusiveMinimum + +- [ ] +maxLength + +- [ ] +minLength + +- [ ] +pattern + +- [ ] +maxItems + +- [ ] +minItems + +- [ ] +uniqueItems + +- [ ] +maxProperties + +- [ ] +minProperties + +- [ ] +enum (when type is string or integer) + +- [ ] +type + +- [ ] +allOf + +- a wrapper struct is generated, children can be any schema +- [ ] +oneOf + +- if a discriminator is specified, each child must be a reference to an object schema + +- if no discriminator is specified, children can be any schema +- [ ] +anyOf + +- a wrapper struct is generated, children can be any schema +- [ ] +not + +- [ ] +items + +- [ ] +properties + +- [ ] +additionalProperties + +- [ ] +format + +- [ ] +nullable (only in 3.0, removed in 3.1, add `null` in `types` instead) + +- [ ] +discriminator + +- [ ] +readOnly + +- [ ] +writeOnly + +- [ ] +xml + +#### External Documentation Object + +#### Discriminator Object + +- [ ] +propertyName + +- [ ] +mapping + +#### XML Object + +- [ ] +namespace + +- [ ] +prefix + +- [ ] +attribute + +- [ ] +wrapped + +#### Encoding Object + +- [ ] +contentType + +- [ ] +style + +- [ ] +explode + +- [ ] +allowReserved + +#### Parameter Object + +- [ ] +in + +- [ ] +allowEmptyValue + +#### Style Values + +- [ ] +matrix (in path) + +- [ ] +label (in path) + +- [ ] +form (in query) + +- [ ] +form (in cookie) + +- [ ] +simple (in path) + +- [ ] +simple (in header) + +- [ ] +spaceDelimited (in query) + +- [ ] +pipeDelimited (in query) + +- [ ] +deepObject (in query) + +#### Supported combinations + +| Location | Style | Explode | +| --- | --- | --- | +| path | `simple` | `false` | +| query | `form` | `true` | +| query | `form` | `false` | +| query | `deepObject` | `true` | +| header | `simple` | `false` | + +#### Reference Object + +#### Components Object + +- [ ] +schemas + +- [ ] +responses (always inlined) + +- [ ] +requestBodies (always inlined) + +- [ ] +securitySchemes + +#### Link Object + +- [ ] +operationRef + +- [ ] +server + +#### Tag Object + +#### Security Scheme Object + +- [ ] +scheme + +- [ ] +bearerFormat + +- [ ] +flows + +- [ ] +openIdConnectUrl + +#### OAuth Flows Object + +- [ ] +implicit + +- [ ] +password + +- [ ] +clientCredentials + +- [ ] +authorizationCode + +#### OAuth Flow Object + +- [ ] +authorizationUrl + +- [ ] +tokenUrl + +- [ ] +refreshUrl + +- [ ] +scopes + +#### Specification Extensions + +- no specific extensions supported + +## See Also + +### OpenAPI + +Exploring an OpenAPI document + +This tutorial covers the basics of the OpenAPI specification and guides you through writing an OpenAPI document that describes a service API. We’ll use a fictitious service that returns a personalized greeting. + +Adding OpenAPI and Swagger UI endpoints + +One of the most popular ways to share your OpenAPI document with your users is to host it alongside your API server itself. + +Practicing spec-driven API development + +Design, iterate on, and generate both client and server code from your hand-written OpenAPI document. + +Useful OpenAPI patterns + +Explore OpenAPI patterns for common data representations. + +- Supported OpenAPI features +- Overview +- Structured content types +- OpenAPI specification features +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/manually-invoking-the-generator-cli + +# An unknown error occurred. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/frequently-asked-questions + +- Swift OpenAPI Generator +- Frequently asked questions + +Article + +# Frequently asked questions + +Review some frequently asked questions below. + +## Overview + +This article includes some commonly asked questions and answers. + +### How do I \_\_ in OpenAPI? + +- Review the official OpenAPI specification. + +- Check out the OpenAPI Guide. + +- Learn how to achieve common patterns with OpenAPI and Swift OpenAPI Generator at Useful OpenAPI patterns. + +### Why doesn’t the generator have feature \_\_? + +Check out Project scope and goals. + +### What OpenAPI features does the generator support? + +Check out Supported OpenAPI features. + +### Which underlying HTTP library does the generated code use? + +Swift OpenAPI Generator is not tied to any particular HTTP library. Instead, the generated code utilizes a general protocol called `ClientTransport` for client code, and `ServerTransport` for server code. + +The user of the generated code provides one of the concrete transport implementations, based on what’s appropriate for their use case. + +Swift OpenAPI Generator lists some transport implementations in its README, but anyone is welcome to create their own custom transport implementation and share it as a package with the community. + +To learn more, check out Getting started, which shows how to use some of the transport implementations. + +### How do I customize the HTTP requests and responses? + +If the code generated from the OpenAPI document, combined with the concrete transport implementation, doesn’t behave exactly as you need, you can provide a _middleware_ type that can inspect and modify the HTTP requests and responses that are passed between the generated code and the transport. + +Just like with transports, there are two types, `ClientMiddleware` and `ServerMiddleware`. + +To learn more, check out Middleware examples. + +### Do I commit the generated code to my source repository? + +It depends on the way you’re integrating Swift OpenAPI Generator. + +The recommended way is to use the Swift package plugin, and let the build system generate the code on-demand, without the need to check it into your git repository. + +However, if you require to check your generated code into git, you can use the command plugin, or manually invoke the command-line tool. + +For details, check out Manually invoking the generator CLI. + +### Does regenerating code from an updated OpenAPI document overwrite any of my code? + +Swift OpenAPI Generator was designed for a workflow called spec-driven development (check out Practicing spec-driven API development for details). That means that it is expected that the OpenAPI document changes frequently, and no developer-written code is overwritten when the Swift code is regenerated from the OpenAPI document. + +When run in `client` mode, the generator emits a type called `Client` that conforms to a generated protocol called `APIProtocol`, which defines one method per OpenAPI operation. Client code generation provides you with a concrete implementation that makes HTTP requests over a provided transport. From your code, you _use_ the `Client` type, so when it gets updated, unless the OpenAPI document removed API you’re using, you don’t need to make any changes to your code. + +When run in `server` mode, the generator emits the same `APIProtocol` protocol, and you implement a type that conforms to it, providing one method per OpenAPI operation. The other server generated code takes care of registering the generated routes on the underlying server. That means that when a new operation is added to the OpenAPI document, you get a build error telling you that your custom type needs to implement the new method to conform to `APIProtocol` again, guiding you towards writing code that complies with your OpenAPI document. However, none of your hand-written code is overwritten. + +To learn about the different ways of integrating Swift OpenAPI Generator, check out Manually invoking the generator CLI. + +### How do I fix the build error “Decl has a package access level but no -package-name was passed”? + +The build error `Decl has a package access level but no -package-name was passed` appears when the package or project is not configured with the `package` access level feature yet. + +The cause of this error is that the generated code is using the `package` access modifier for its API, but the project or package are not passing the `-package-name` option to the Swift compiler yet. + +For Swift packages, the fix is to ensure your `Package.swift` has a `swift-tools-version` of 5.9 or later. + +For Xcode projects, make sure the target that uses the Swift OpenAPI Generator build plugin provides the build setting `SWIFT_PACKAGE_NAME` (called “Package Access Identifier”). Set it to any name, for example the name of your Xcode project. + +Alternatively, change the access modifier of the generated code to either `internal` (if no code outside of that module needs to use it) or `public` (if the generated code is exported to other modules and packages.) You can do so by setting `accessModifier: internal` in the generator configuration file, or by providing `--access-modifier internal` to the `swift-openapi-generator` CLI. + +For details, check out Configuring the generator. + +### How do I enable the build plugin in Xcode and Xcode Cloud? + +By default, you must explicitly enable build plugins before they are allowed to run. + +Before a plugin is enabled, you will encounter a build error with the message `"OpenAPIGenerator" is disabled`. + +In Xcode, enable the plugin by clicking the “Enable Plugin” button next to the build error and confirm the dialog by clicking “Trust & Enable”. + +In Xcode Cloud, add the script `ci_scripts/ci_post_clone.sh` next to your Xcode project or workspace, containing: + +#!/usr/bin/env bash + +set -e + +# NOTE: the misspelling of validation as "validatation" is intentional and the spelling Xcode expects. +defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES + +Learn more about Xcode Cloud custom scripts in the documentation. + +## See Also + +### Generator plugin and CLI + +Configuring the generator + +Create a configuration file to control the behavior of the generator. + +Manually invoking the generator CLI + +Manually invoke the command-line tool to generate code as an alternative to the Swift package build plugin. + +- Frequently asked questions +- Overview +- How do I \_\_ in OpenAPI? +- Why doesn’t the generator have feature \_\_? +- What OpenAPI features does the generator support? +- Which underlying HTTP library does the generated code use? +- How do I customize the HTTP requests and responses? +- Do I commit the generated code to my source repository? +- Does regenerating code from an updated OpenAPI document overwrite any of my code? +- How do I fix the build error “Decl has a package access level but no -package-name was passed”? +- How do I enable the build plugin in Xcode and Xcode Cloud? +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/converting-between-data-and-swift-types + +- Swift OpenAPI Generator +- Documentation for maintainers +- Converting between data and Swift types + +Article + +# Converting between data and Swift types + +Learn about the type responsible for converting between binary data and Swift types. + +## Overview + +The `Converter` type is a structure defined in the runtime library and is used by both the client and server generated code to perform conversions between binary data and Swift types. + +Most of the functionality of `Converter` is implemented as helper methods in extensions: + +- `Converter+Client.swift` + +- `Converter+Server.swift` + +- `Converter+Common.swift` + +Some helper methods can be reused between client and server code, such as headers, but most can’t. It’s important that we only generalize (move helper methods into common extensions) if the client and server variants would have been exact copies. However, if there are differences, prefer to keep them separate and optimize each variant (for client or server) separately. + +The converter, it contains helper methods for all the supported combinations of an schema location, a “coding strategy” and a Swift type. + +### Codable and coders + +The project uses multiple encoder and decoder implementations that all utilize the `Codable` conformance of generated and built-in types. + +At the time of writing, the list of coders used is as follows. + +| Format | Encoder | Decoder | Supported in | +| --- | --- | --- | --- | +| JSON | `Foundation.JSONEncoder` | `Foundation.JSONDecoder` | Bodies, headers | +| URI (†) | `OpenAPIRuntime.URIEncoder` | `OpenAPIRuntime.URIDecoder` | Path, query, headers | +| Plain text | `OpenAPIRuntime.StringEncoder` | `OpenAPIRuntime.StringDecoder` | Bodies | + +While the generator attempts to catch invalid inputs at generation time, there are still combinations of `Codable` types and locations that aren’t compatible, and will only get caught at runtime by the specific coder implementation. For example, one could ask the `StringEncoder` to encode an array, but the encoder will throw an error, as containers are not supported in that encoder. + +### Dimensions of helper methods + +Below is a list of the “dimensions” across which the helper methods differ: + +- **Client/server** represents whether the code is needed by the client, server, or both (“common”). + +- **Set/get** represents whether the generated code sets or gets the value. + +- **Schema location** refers to one of the several places where schemas can be used in OpenAPI documents. Values: + +- request path parameters + +- request query items + +- request header fields + +- request body + +- response header fields + +- response body +- **Coding strategy** represents the chosen coder to convert between the Swift type and data. Supported options: + +- `JSON` + +- example content type: `application/json` and any with the `+json` suffix + +- `{"color": "red", "power": 24}` +- `URI` + +- example: query, path, header parameters + +- `color=red&power=24` +- `urlEncodedForm` + +- example: request body with the `application/x-www-form-urlencoded` content type + +- `greeting=Hello+world` +- `multipart` + +- example: request body with the `multipart/form-data` content type + +- part 1: `{"color": "red", "power": 24}`, part 2: `greeting=Hello+world` +- `binary` + +- example: `application/octet-stream` + +- serves as the fallback for content types that don’t have more specific handling + +- doesn’t transform the binary data, just passes it through +- **Optional/required** represents whether the method works with optional values. Values: + +- _required_ represents a special overload only for required values + +- _optional_ represents a special overload only for optional values + +- _both_ represents a special overload that works for optional values without negatively impacting passed-in required values (for example, setters) + +### Helper method variants + +Together, the dimensions are enough to deterministically decide which helper method on the converter should be used. + +In the list below, each row represents one helper method. + +The helper method naming convention can be described as: + +method name: {set,get}{required/optional/omit if both}{location}As{strategy} +method parameters: value or type of value + +| Client/server | Set/get | Schema location | Coding strategy | Optional/required | Method name | +| --- | --- | --- | --- | --- | --- | +| common | set | header field | URI | both | setHeaderFieldAsURI | +| common | set | header field | JSON | both | setHeaderFieldAsJSON | +| common | get | header field | URI | optional | getOptionalHeaderFieldAsURI | +| common | get | header field | URI | required | getRequiredHeaderFieldAsURI | +| common | get | header field | JSON | optional | getOptionalHeaderFieldAsJSON | +| common | get | header field | JSON | required | getRequiredHeaderFieldAsJSON | +| client | set | request path | URI | required | renderedPath | +| client | set | request query | URI | both | setQueryItemAsURI | +| client | set | request body | JSON | optional | setOptionalRequestBodyAsJSON | +| client | set | request body | JSON | required | setRequiredRequestBodyAsJSON | +| client | set | request body | binary | optional | setOptionalRequestBodyAsBinary | +| client | set | request body | binary | required | setRequiredRequestBodyAsBinary | +| client | set | request body | urlEncodedForm | optional | setOptionalRequestBodyAsURLEncodedForm | +| client | set | request body | urlEncodedForm | required | setRequiredRequestBodyAsURLEncodedForm | +| client | set | request body | multipart | required | setRequiredRequestBodyAsMultipart | +| client | get | response body | JSON | required | getResponseBodyAsJSON | +| client | get | response body | binary | required | getResponseBodyAsBinary | +| client | get | response body | multipart | required | getResponseBodyAsMultipart | +| server | get | request path | URI | required | getPathParameterAsURI | +| server | get | request query | URI | optional | getOptionalQueryItemAsURI | +| server | get | request query | URI | required | getRequiredQueryItemAsURI | +| server | get | request body | JSON | optional | getOptionalRequestBodyAsJSON | +| server | get | request body | JSON | required | getRequiredRequestBodyAsJSON | +| server | get | request body | binary | optional | getOptionalRequestBodyAsBinary | +| server | get | request body | binary | required | getRequiredRequestBodyAsBinary | +| server | get | request body | urlEncodedForm | optional | getOptionalRequestBodyAsURLEncodedForm | +| server | get | request body | urlEncodedForm | required | getRequiredRequestBodyAsURLEncodedForm | +| server | get | request body | multipart | required | getRequiredRequestBodyAsMultipart | +| server | set | response body | JSON | required | setResponseBodyAsJSON | +| server | set | response body | binary | required | setResponseBodyAsBinary | +| server | set | response body | multipart | required | setResponseBodyAsMultipart | + +## See Also + +Generating custom Codable implementations + +Learn about when and how the generator emits a custom Codable implementation. + +Handling nullable schemas + +Learn how the generator handles schema nullability. + +Supporting recursive types + +Learn how the generator supports recursive types. + +- Converting between data and Swift types +- Overview +- Codable and coders +- Dimensions of helper methods +- Helper method variants +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-0008 + +- Swift OpenAPI Generator +- Proposals +- SOAR-0008: OpenAPI document filtering + +Article + +# SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +## Overview + +- Proposal: SOAR-0008 + +- Author(s): Si Beaumont + +- Status: **Implemented (0.3.0)** + +- Issue: apple/swift-openapi-generator#285 + +- Implementation: apple/swift-openapi-generator#319 + +- Review: ( review) + +- Affected components: generator + +- Related links: + +- Project scope and goals +- Versions: + +- v1 (2023-09-28): Initial version + +- v2 (2023-10-05): + +- Filtering by tag only includes the tagged operations (cf. whole path) + +- Add support for filtering operations by ID + +### Introduction + +When generating client code, Swift OpenAPI Generator generates code for the entire OpenAPI document, even if the user only makes use of a subset of its types and operations. + +Generating code that is unused constitutes overhead for the adopter: + +- The overhead of generating code for unused types and operations + +- The overhead of compiling the generated code + +- The overhead of unused code in the users codebase (AOT generation) + +This is particularly noticeable when working with a small subset of a large API, which can result in O(100k) lines of unused code and long generation and compile times. + +The initial scope of the Swift OpenAPI Generator was to focus only on generating Swift code from an OpenAPI document, and any preprocessing of the OpenAPI document was considered out of scope. The proposed answer to this was to preprocess the document before providing to the generator\[\[0\]\]. + +Even with tooling, filtering the document requires more than just filtering the YAML or JSON document for the deterministic keys for the desired operations because such operations likely contain JSON references to the reusable types in the document’s `components` dictionary, and these components can themselves contain references. Consequently, in order to filter an OpenAPI document for a single operation requires including the transitive closure of the operations referenced dependencies. + +Furthermore, it’s common that Swift OpenAPI Generator adopters do not own the OpenAPI document, and simply vendor it from the service owner. In these cases, it presents a user experience hurdle to have to edit the document, and a maintenance burden to continue to do so when updating the document to a new version. + +Because this problem has a general solution that is non-trivial to implement, this proposal covers adding opt-in, configurable document filtering to the generator, to improve the user experience for those using a subset of a large API. + +### Motivation + +% cat api.github.com.yaml | wc -l +231063 + +% cat api.github.com.yaml | yq '.paths.* | keys' | wc -l +898 + +% cat api.github.com.yaml | yq '.components.* | keys' | wc -l +1260 + +% time ./swift-openapi-generator.release \ +generate \ +--mode types \ +--config openapi-generator-config.yaml \ +api.github.com.yaml +Writing data to file Types.swift... + +real 0m41.397s +user 0m40.912s +sys 0m0.456s + +% cat Types.swift | wc -l +458852 + +OpenAPI has support for grouping operations by tag. For example, the OpenAPI document for the Github API has the following tags: + +% cat api.github.com.yaml | yq '[.tags[].name] | join(", ")' +actions, activity, apps, billing, checks, code-scanning, codes-of-conduct, +emojis, dependabot, dependency-graph, gists, git, gitignore, issues, licenses, +markdown, merge-queue, meta, migrations, oidc, orgs, packages, projects, pulls, +rate-limit, reactions, repos, search, secret-scanning, teams, users, +codespaces, copilot, security-advisories, interactions, classroom + +If a user wants to make use of just the parts of the API that relate to Github issues, then they could work with a much smaller document. For example, filtering for only operations tagged `issues` (including all components on which those operations depend) results in an OpenAPI document that is just 25k lines with 40 operations and 90 reusable components, comprising a ~90% reduction in these dimensions. + +Running the generator with `--mode types` with this filtered API document takes just 1.6 seconds\[^1\] and results in < 15k LOC, which is 20x faster and a 95% reduction in generated code. + +% cat issues.api.github.com.yaml | wc -l +25314 + +% cat issues.api.github.com.yaml | yq '.paths.* | keys' | wc -l +40 + +% cat issues.api.github.com.yaml | yq '.components.* | keys' | wc -l +90 + +% time ./swift-openapi-generator.filter.release \ +generate \ +--mode types \ +--config openapi-generator-config.yaml \ +issues.api.github.com.yaml +Writing data to file Types.swift... + +real 0m1.638s +user 0m1.595s +sys 0m0.031s + +% cat Types.swift | wc -l +14691 + +### Proposed solution + +We propose a configuable, opt-in filtering feature, which would run before generation, allowing users to select the paths and schemas they are interested in. + +This would be driven by a new `filter` key in the config file used by the generator. + +# filter: +# paths: +# - ... +# tags: +# operations: +# schemas: + +For example, to filter the document for only paths that contain operations tagged with `issues` (along with the components on which those paths depend), users could add the following to their config file. + +# openapi-generator-config.yaml +generate: +- types +- client + +filter: +tags: +- issues + +When this config key is present, the OpenAPI document will be filtered, before generation, to contain the paths and schemas requested, along with the transitive closure of components on which they depend. + +This config key is optional; when it is not present, no filtering will take place. + +The following filters will be supported: + +- `paths`: Includes the given paths, specified using the same keys as ‘#/paths’ in the OpenAPI document. + +- `tags`: Includes the operations with any of the given tags. + +- `operations`: Includes the operations with these explicit operation IDs. + +- `schemas`: Includes any schemas, specifid using the same keys as ‘#/components/schemas’ in the OpenAPI document. + +When multiple filters are specified, their union will be considered for inclusion. + +In all cases, the transitive closure of dependencies from the components object will be included. + +Appendix A contains several examples on a real OpenAPI document. + +### Detailed design + +The config file is currently defined by an internal Codable struct, to which a new, optional property has been added: + +--- a/Sources/swift-openapi-generator/UserConfig.swift ++++ b/Sources/swift-openapi-generator/UserConfig.swift +@@ -27,6 +27,9 @@ struct _UserConfig: Codable { +/// generated Swift file. +var additionalImports: [String]? + ++ /// Filter to apply to the OpenAPI document before generation. ++ var filter: DocumentFilter? ++ +/// A set of features to explicitly enable. +var featureFlags: FeatureFlags? +} +/// Rules used to filter an OpenAPI document. +struct DocumentFilter: Codable, Sendable { + +/// Operations with these tags will be included. +var tags: [String]? + +/// Operations with these IDs will be included. +var operations: [String]? + +/// These paths will be included in the filter. +var paths: [OpenAPI.Path]? + +/// These schemas will be included. +/// +/// These schemas are included in addition to the transitive closure of +/// schema dependencies of the included paths. +var schemas: [String]? +} + +Note that these types are not being added to any Swift API; they are just used to decode the `openapi-generator-config.yaml`. + +### API stability + +This change is purely API additive: + +- Additional, optional keys in the config file schema. + +#### Providing a \`fitler\` CLI command + +Filtering the OpenAPI document has general utility beyond use within the generator itself. In the future, we could consider adding a CLI for filtering. + +#### Not supporting including schema components + +While the primary audience for this feature is adopters generating clients, there are use cases where adopters may wish to interact with serialized data that makes use of OpenAPI types. Indeed, OpenAPI is sometimes used as a language-agnostic means of defining types outside of the context of a HTTP service. + +#### Supporting including other parts of the components object + +While we chose to include schemas, for the reason highlighted above, we chose _not_ to allow including other parts of the components object (e.g. `parameters`, `requestBodies`, etc.). + +That’s because, unlike schemas, which have standalone utility, all other components are only useful in conjuction with an API operation. + +* * * + +#### Input OpenAPI document + +# unfiltered OpenAPI document +openapi: 3.1.0 +info: +title: ExampleService +version: 1.0.0 +tags: +- name: t +paths: +/things/a: +get: +operationId: getA +tags: +- t +responses: +200: +$ref: '#/components/responses/A' +delete: +operationId: deleteA +responses: +200: +$ref: '#/components/responses/Empty' +/things/b: +get: +operationId: getB +responses: +200: +$ref: '#/components/responses/B' +components: +schemas: +A: +type: string +B: +$ref: '#/components/schemas/A' +responses: +A: +description: success +content: +application/json: +schema: +$ref: '#/components/schemas/A' +B: +description: success +content: +application/json: +schema: +$ref: '#/components/schemas/B' +Empty: +description: success + +#### Including paths by key + +filter: +paths: +- /things/b +# filtered OpenAPI document +openapi: 3.1.0 +info: +title: ExampleService +version: 1.0.0 +tags: +- name: t +paths: +/things/b: +get: +operationId: getB +responses: +200: +$ref: '#/components/responses/B' +components: +schemas: +A: +type: string +B: +$ref: '#/components/schemas/A' +responses: +B: +description: success +content: +application/json: +schema: +$ref: '#/components/schemas/B' + +#### Including operations by tag + +filter: +tags: +- t +openapi: 3.1.0 +info: +title: ExampleService +version: 1.0.0 +tags: +- name: t +paths: +/things/a: +get: +tags: +- t +operationId: getA +responses: +200: +$ref: '#/components/responses/A' +components: +schemas: +A: +type: string +responses: +A: +description: success +content: +application/json: +schema: +$ref: '#/components/schemas/A' + +#### Including schemas by key + +filter: +schemas: +- B +openapi: 3.1.0 +info: +title: ExampleService +version: 1.0.0 +tags: +- name: t +components: +schemas: +A: +type: string +B: +$ref: '#/components/schemas/A' + +#### Including operations by ID + +filter: +operations: +- deleteA +openapi: 3.1.0 +info: +title: ExampleService +version: 1.0.0 +tags: +- name: t +paths: +/things/a: +delete: +operationId: deleteA +responses: +200: +$ref: '#/components/responses/Empty' +components: +responses: +Empty: +description: success + +\[^1\]: Compiled in release mode, running on Apple M1 Max. + +## See Also + +SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +- SOAR-0008: OpenAPI document filtering +- Overview +- Introduction +- Motivation +- Proposed solution +- Detailed design +- API stability +- Future directions +- Alternatives considered +- Appendix A: Examples +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-0010 + +- Swift OpenAPI Generator +- Proposals +- SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Article + +# SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +## Overview + +- Proposal: SOAR-0010 + +- Author(s): Honza Dvorsky + +- Status: **Implemented (1.2.0)** + +- Issue: apple/swift-openapi-generator#416 + +- Implementation: + +- apple/swift-openapi-runtime#91 + +- apple/swift-openapi-generator#494 +- Affected components: + +- generator (examples and docs only) + +- runtime (streaming encoders and decoders) +- Related links: + +- JSON Lines + +- JSON Sequence + +- Server-sent Events + +### Introduction + +Add streaming encoders and decoders for these three event stream formats to the runtime library, allowing adopters to easily produce and consume event streams, both on the client and server. + +### Motivation + +While the OpenAPI specification is optimized for HTTP APIs that send a single request value, and receive a single response value, there are many use cases in which developers want to stream values over time. + +A simple example of streaming “values” is a file transfer, which can be thought of as a stream of byte chunks that represent the contents of the file. Another is multipart content, streaming individual parts over time. Both of these are already supported by Swift OpenAPI Generator, as of version 0.3.0 and 1.0.0-alpha.1, respectively. + +Another popular use case for streaming is to send JSON-encoded events over time, usually (but not exclusively), from the server to the client. + +- The Kubernetes API uses JSON Lines to stream updates to resources from its control plane. + +- The OpenAI API uses Server-sent Events to stream text snippets from ChatGPT. + +- I couldn’t find a popular service using JSON Sequence, but unlike JSON Lines, it’s well-defined in RFC7464, and also used around the industry. + +The flow starts with the client initiating an HTTP request to the server, and the server responding with an HTTP response head, and then the server starting to stream the response body, which contains the delimited events, processed over time by the client. + +This lightweight solution has the advantage of being a plain HTTP request/response pair, without requiring a custom protocol to either replace HTTP, or sit on top of it. This makes intermediaries, such as proxies, still able to pass data through without being aware of the streaming nature of the HTTP body. + +### Proposed solution + +Since the OpenAPI specification does not explicitly mention event streaming, it’s up to tools, such as Swift OpenAPI Generator, to provide additional conveniences. + +This proposed solution consists of two parts: + +1. Add streaming encoders and decoders for the three event stream formats to the runtime library, represented as an `AsyncSequence` that converts elements between byte chunks and parsed events. + +2. Provide examples for how adopters can then chain those sequences on the `HTTPBody` values they either produce or consume, in their code. No extra code would be generated. + +Generally, the three event stream formats are associated with the following content types: + +- JSON Lines: `application/jsonl`, `application/x-ndjson` + +- JSON Sequence: `application/json-seq` + +- Server-sent Events: `text/event-stream` + +The generated code would continue to only vend the raw sequence of byte chunks (`HTTPBody`), and adopters could optionally chain the encoding/decoding sequence on it. For example, an OpenAPI document with a JSON Lines stream of `Greeting` values could contain the following: + +paths: +/greetings: +get: +operationId: getGreetingsStream +responses: +'200': +content: +application/jsonl: +schema: +$ref: '#/components/schemas/Greeting' +components: +schemas: +Greeting: +type: object +properties: +... + +The important part is the `application/jsonl` (JSON Lines) content type (not to be confused with a plain `application/json` content type), and the event schema in `#/components/schemas`. + +#### Consuming event streams + +As a consumer of such a body in Swift (usually on the client), you’d use one of the proposed methods, here `asDecodedJSONLines(of:decoder:)` to get a stream that parses the individual JSON lines and decodes each JSON object as a value of `Components.Schemas.Greeting`. + +Then, you can read the stream, for example in a `for try await` loop. + +let response = try await client.getGreetingsStream() +let httpBody = try response.ok.body.application_jsonl +let greetingStream = httpBody.asDecodedJSONLines(of: Components.Schemas.Greeting.self) +for try await greeting in greetingStream { +print("Got greeting: \(greeting.message)") +} + +#### Producing event streams + +As a producer of such a body, start with a root async sequence, for example an `AsyncStream`, and submit events to it. + +// Pass the continuation to another task that calls +// `continuation.yield(...)` with events, and `continuation.finish()` +// at the end. + +let httpBody = HTTPBody( +stream.asEncodedJSONLines(), +length: .unknown, +iterationBehavior: .single +) +// Provide `httpBody` to the response, for example. +return .ok(.init(body: .application_jsonl(httpBody))) + +### Detailed design + +The rest of this section contains the Swift interface of the new API for the runtime library. + +/// A sequence that parses arbitrary byte chunks into lines using the JSON Lines format. + +/// Creates a new sequence. +/// - Parameter upstream: The upstream sequence of arbitrary byte chunks. +public init(upstream: Upstream) +} + +extension JSONLinesDeserializationSequence : AsyncSequence { + +} + +/// Returns another sequence that decodes each JSON Lines event as the provided type using the provided decoder. +/// - Parameters: +/// - eventType: The type to decode the JSON event into. +/// - decoder: The JSON decoder to use. +/// - Returns: A sequence that provides the decoded JSON events. + +/// A sequence that serializes lines by concatenating them using the JSON Lines format. + +/// Creates a new sequence. +/// - Parameter upstream: The upstream sequence of lines. +public init(upstream: Upstream) +} + +extension JSONLinesSerializationSequence : AsyncSequence { + +extension AsyncSequence where Self.Element : Encodable { + +/// Returns another sequence that encodes the events using the provided encoder into JSON Lines. +/// - Parameter encoder: The JSON encoder to use. +/// - Returns: A sequence that provides the serialized JSON Lines. +public func asEncodedJSONLines(encoder: JSONEncoder = { +let encoder = JSONEncoder() +encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes] +return encoder +}()) -> JSONLinesSerializationSequence>> +} + +/// A sequence that parses arbitrary byte chunks into lines using the JSON Sequence format. + +extension JSONSequenceDeserializationSequence : AsyncSequence { + +/// Returns another sequence that decodes each JSON Sequence event as the provided type using the provided decoder. +/// - Parameters: +/// - eventType: The type to decode the JSON event into. +/// - decoder: The JSON decoder to use. +/// - Returns: A sequence that provides the decoded JSON events. + +/// A sequence that serializes lines by concatenating them using the JSON Sequence format. + +extension JSONSequenceSerializationSequence : AsyncSequence { + +/// Returns another sequence that encodes the events using the provided encoder into a JSON Sequence. +/// - Parameter encoder: The JSON encoder to use. +/// - Returns: A sequence that provides the serialized JSON Sequence. +public func asEncodedJSONSequence(encoder: JSONEncoder = { +let encoder = JSONEncoder() +encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes] +return encoder +}()) -> JSONSequenceSerializationSequence>> +} + +/// An event sent by the server that has a JSON payload in the data field. +/// +/// + +/// A type of the event, helps inform how to interpret the data. +public var event: String? + +/// The payload of the event. +public var data: JSONDataType? + +/// A unique identifier of the event, can be used to resume an interrupted stream by +/// making a new request with the `Last-Event-ID` header field set to this value. +/// +/// +public var id: String? + +/// The amount of time, in milliseconds, the client should wait before reconnecting in case +/// of an interruption. +/// +/// +public var retry: Int64? + +/// Creates a new event. +/// - Parameters: +/// - event: A type of the event, helps inform how to interpret the data. +/// - data: The payload of the event. +/// - id: A unique identifier of the event. +/// - retry: The amount of time, in milliseconds, to wait before retrying. +public init(event: String? = nil, data: JSONDataType? = nil, id: String? = nil, retry: Int64? = nil) +} + +/// An event sent by the server. +/// +/// +public struct ServerSentEvent : Sendable, Hashable { + +/// The payload of the event. +public var data: String? + +/// Creates a new event. +/// - Parameters: +/// - id: A unique identifier of the event. +/// - event: A type of the event, helps inform how to interpret the data. +/// - data: The payload of the event. +/// - retry: The amount of time, in milliseconds, to wait before retrying. +public init(id: String? = nil, event: String? = nil, data: String? = nil, retry: Int64? = nil) +} + +/// A sequence that parses arbitrary byte chunks into events using the Server-sent Events format. +/// +/// + +extension ServerSentEventsDeserializationSequence : AsyncSequence { +public typealias Element = ServerSentEvent + +/// Returns another sequence that decodes each event's data as the provided type using the provided decoder. +/// +/// Use this method if the event's `data` field is not JSON, or if you don't want to parse it using `asDecodedServerSentEventsWithJSONData`. +/// - Returns: A sequence that provides the events. +public func asDecodedServerSentEvents() -> ServerSentEventsDeserializationSequence> + +/// Returns another sequence that decodes each event's data as the provided type using the provided decoder. +/// +/// Use this method if the event's `data` field is JSON. +/// - Parameters: +/// - dataType: The type to decode the JSON data into. +/// - decoder: The JSON decoder to use. +/// - Returns: A sequence that provides the events with the decoded JSON data. +public func asDecodedServerSentEventsWithJSONData(of dataType: JSONDataType.Type = JSONDataType.self, decoder: JSONDecoder = .init()) -> AsyncThrowingMapSequence>, ServerSentEventWithJSONData> where JSONDataType : Decodable +} + +/// A sequence that serializes Server-sent Events. + +/// Creates a new sequence. +/// - Parameter upstream: The upstream sequence of events. +public init(upstream: Upstream) +} + +extension ServerSentEventsSerializationSequence : AsyncSequence where Upstream.Element == ServerSentEvent { + +extension AsyncSequence { + +/// Returns another sequence that encodes Server-sent Events with generic data in the data field. +/// - Returns: A sequence that provides the serialized Server-sent Events. + +/// Returns another sequence that encodes Server-sent Events that have a JSON value in the data field. +/// - Parameter encoder: The JSON encoder to use. +/// - Returns: A sequence that provides the serialized Server-sent Events. + +let encoder = JSONEncoder() +encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes] +return encoder +}()) -> ServerSentEventsSerializationSequence> where JSONDataType : Encodable, Self.Element == ServerSentEventWithJSONData +} + +### API stability + +Additive changes to the runtime library, no API changes to the generator or other components. + +### Future directions + +We could add additional event stream formats, if they become popular and well-defined in the industry. + +### Alternatives considered + +- Not doing anything - this would require adopters to write these encoders and decoders by hand, which is time-consuming, error prone, and duplicates effort across the ecosystem. + +- Generating special types for these streams - this was rejected because it would force the adopter to parse the event stream, even if they instead wanted to forward it as raw data elsewhere. Since these event streams formats are not part of OpenAPI, it felt like a too strong of a limitation, which is why these conveniences are opt-in. + +## See Also + +SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +- SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events +- Overview +- Introduction +- Motivation +- Proposed solution +- Detailed design +- API stability +- Future directions +- Alternatives considered +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/handling-nullable-schemas + +- Swift OpenAPI Generator +- Documentation for maintainers +- Handling nullable schemas + +Article + +# Handling nullable schemas + +Learn how the generator handles schema nullability. + +## Overview + +Both the OpenAPI specification itself and JSON Schema, which OpenAPI uses to describe payloads, make the important distinction between optional and required values. + +As Swift not only supports, but enforces this distinction as well, Swift OpenAPI Generator represents nullable schemas as optional Swift values. + +This document describes the rules used to decide which generated Swift types and properties are marked as optional. + +### Optionality in OpenAPI and JSON Schema + +OpenAPI 3.0.3 uses JSON Schema Draft 5, while OpenAPI 3.1.0 uses JSON Schema 2020-12. There are a few differences that we call out below, but it’s important to be aware of the fact that the generator needs to handle both. + +The generator uses a simple rule: if any of the places that hint at optionality mark a field as optional, the value is generated as optional. It can be thought of as an `OR` operator. + +### Standalone schemas + +A schema in JSON Schema Draft 5 (used by OpenAPI 3.0.3) can be marked as optional using: + +- the `nullable` field, a Boolean, if enabled, the field can be omitted and defaults to nil + +For example: + +MyOptionalString: +type: string +nullable: true + +A schema in JSON Schema 2020-12 (used by OpenAPI 3.1.0) can be marked as optional by: + +- adding `null` as one of the types, if present, the field can be omitted and defaults to nil + +- the `nullable` keyword was removed in this JSON Schema version + +MyOptionalString: +type: [string, null] + +The nullability of a schema is propagated through references. That means if a schema is a reference, the generator looks up the target schema of the reference to decide whether the value is treated as optional. + +### Schemas as object properties + +In addition to the schema itself being marked as nullable, we also have to consider the context in which the schema is used. + +When used as an object property, we must also consider the `required` array. For example, in the following example (valid for both JSON Schema and OpenAPI versions mentioned above), we have a JSON object with a required property `name` of type string, and an optional property `age` of type integer. + +MyPerson: +type: object +properties: +name: +type: string +age: +type: integer +required: +- name + +Notice that the `required` array only contains `name`, but not `age`. In objects, a property being omitted from the `required` array also signals to the generator that the property should be treated as an optional. + +Marking the schema itself as nullable _as well_ doesn’t make a difference, it will still be treated as a single-wrapped optional. Same if the property is included in the `required` array but marked as `nullable`, it will be an optional. + +That means the following alternative definition results in the same generated Swift code as the above. + +MyPerson: +type: object +properties: +name: +type: string +age: +type: [integer, null] +required: +- name +- age # even though required, the nullability of the schema "wins" + +### Schemas in parameters + +Another context in which a schema can appear, in addition to being standalone or an object property, is as a parameter. Examples of parameters are header fields, query items, path parameters. The following also applies to request bodies, even though they’re not technically parameters. + +OpenAPI defines a separate `required` field on parameters, of a Boolean value, which defaults to false (meaning parameters are optional by default). + +parameters: +- name: limit +in: query +schema: +type: integer + +The example above defines an optional query item called “limit” of type integer. + +Such a property would be generated as an optional `Int`. + +To mark the property as required, and get a non-optional `Int` value generated in Swift, add `required: true`. + +parameters: +- name: limit +in: query +required: true +schema: +type: integer + +This adds a third way to mark a value as optional to the previous two. Again, if any of them marks the parameter as optional, the generated Swift value will be optional as well. + +## See Also + +Converting between data and Swift types + +Learn about the type responsible for converting between binary data and Swift types. + +Generating custom Codable implementations + +Learn about when and how the generator emits a custom Codable implementation. + +Supporting recursive types + +Learn how the generator supports recursive types. + +- Handling nullable schemas +- Overview +- Optionality in OpenAPI and JSON Schema +- Standalone schemas +- Schemas as object properties +- Schemas in parameters +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/supporting-recursive-types + +- Swift OpenAPI Generator +- Documentation for maintainers +- Supporting recursive types + +Article + +# Supporting recursive types + +Learn how the generator supports recursive types. + +## Overview + +In some applications, the most expressive way to represent arbitrarily nested data is using a type that holds another value of itself, either directly, or through another type. We refer to such types as _recursive types_. + +By default, structs and enums do not support recursion in Swift, so the generator needs to detect recursion in the OpenAPI document and emit a different internal representation for the Swift types involved in recursion. + +This article discusses the details of what boxing is, and how the generator chooses the types to box. + +### Examples of recursive types + +One example of a recursive type would be a file system item, representing a tree. The `FileItem` node contains more `FileItem` nodes in an array. + +FileItem: +type: object +properties: +name: +type: string +isDirectory: +type: boolean +contents: +type: array +items: +$ref: '#/components/schemas/FileItem' +required: +- name + +Another example would be a `Person` type, that can have a `partner` property of type `Person`. + +Person: +type: object +properties: +name: +type: string +partner: +$ref: '#/components/schemas/Person' +required: +- name + +### Recursive types in Swift + +In Swift, the generator emits structs or enums for JSON schemas that support recursion (enums for `oneOf`, structs for `object`, `allOf`, and `anyOf`). Both structs and enums require that their size is known at compile time, however for arbitrarily nested values, such as a file system hierarchy, it cannot be known at compile time how deep the nesting goes. If such types were generated naively, they would not compile. + +To allow recursion, a _reference_ Swift type must be involved in the reference cycle (as opposed to only _value_ types). We call this technique of using a reference type for storage inside a value type “boxing” and it allows for the outer type to keep its original API, including value semantics, but at the same time be used as a recursive type. + +### Boxing different Swift types + +- Enums can be boxed by adding the `indirect` keyword to the declaration, for example by changing: + +public enum Directory {} + +to: + +public indirect enum Directory { ... } + +When an enum type needs to be boxed, the generator simply includes the `indirect` keyword in the generated type. + +- Structs require more work, including: + +- Moving the stored properties into a private `final class Storage` type. + +- Adding an explicit setter and getter for each property that calls into the storage. + +- Adjusting the initializer to forward the initial values to the storage. + +- Using a copy-on-write wrapper for the storage to avoid creating copies unless multiple references exist to the value and it’s being modified. + +For example, the original struct: + +public struct Person { +public var partner: Person? +public init(partner: Person? = nil) { +self.partner = partner +} +} + +Would look like this when boxed: + +public struct Person { +public var partner: Person? { +get { storage.value.partner } +_modify { yield &storage.value.partner } +} +public init(partner: Person? = nil) { +self.storage = .init(Storage(partner: partner)) +} + +var partner: Person? +public init(partner: Person? = nil) { +self.partner = partner +} +} +} + +The details of the copy-on-write wrapper can be found in the runtime library, where it’s defined. + +- Arrays and dictionaries are reference types under the hood (but retain value semantics) and can already be considered boxed. For that reason, the first example that showed a `FileItem` type actually would compile successfully, because the `contents` array is already boxed. That means the `FileItem` type itself does not require boxing. + +- Pure reference schemas can contribute to reference cycles, but cannot be boxed, because they are represented as a `typealias` in Swift. For that reason, the algorithm never chooses a `$ref` type for boxing, and instead boxes the next eligible type in the cycle. + +### Computing which types need boxing + +Since a boxed type requires an internal reference type, and can be less performant than a non-recursive value type, the generator implements an algorithm that _minimizes_ the number of boxed types required to make all the reference cycles still build successfully. + +The algorithm outputs a list of type names that require boxing. + +It iterates over the types defined in `#/components/schemas`, in the order defined in the OpenAPI document, and for each type walks all of its references. + +Once it detects a reference cycle, it adds the first type in the cycle, in other words the one to which the last reference closed the cycle. + +For example, walking the following: + +The algorithm would choose type “B” for boxing. + +## See Also + +Converting between data and Swift types + +Learn about the type responsible for converting between binary data and Swift types. + +Generating custom Codable implementations + +Learn about when and how the generator emits a custom Codable implementation. + +Handling nullable schemas + +Learn how the generator handles schema nullability. + +- Supporting recursive types +- Overview +- Examples of recursive types +- Recursive types in Swift +- Boxing different Swift types +- Computing which types need boxing +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-nnnn + +- Swift OpenAPI Generator +- Proposals +- SOAR-NNNN: Feature name + +Article + +# SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +## Overview + +- Proposal: SOAR-NNNN + +- Author(s): Author 1, Author 2 + +- Status: **Awaiting Review** + +- Issue: apple/swift-openapi-generator#1 + +- Implementation: + +- apple/swift-openapi-generator#1 +- Feature flag: `proposalNNNN` + +- Affected components: + +- generator + +- runtime + +- client transports + +- server transports +- Related links: + +- Swift Evolution + +### Introduction + +A short, one-sentence overview of the feature or change. + +### Motivation + +Describe the problems that this proposal aims to address, and what workarounds adopters have to employ currently, if any. + +### Proposed solution + +Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds. + +This section should focus on what will change for the _adopters_ of Swift OpenAPI Generator. + +### Detailed design + +Describe the implementation of the feature, a link to a prototype implementation is encouraged here. + +This section should focus on what will change for the _contributors_ to Swift OpenAPI Generator. + +### API stability + +Discuss the API implications, making sure to considering all of: + +- runtime public API + +- runtime “Generated” SPI + +- existing transport and middleware implementations + +- generator implementation affected by runtime API changes + +- generator API (config file, CLI, plugin) + +- existing and new generated adopter code + +### Future directions + +Discuss any potential future improvements to the feature. + +### Alternatives considered + +Discuss the alternative solutions considered, even during the review process itself. + +## See Also + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +- SOAR-NNNN: Feature name +- Overview +- Introduction +- Motivation +- Proposed solution +- Detailed design +- API stability +- Future directions +- Alternatives considered +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-0013 + +- Swift OpenAPI Generator +- Proposals +- SOAR-0013: Idiomatic naming strategy + +Article + +# SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +## Overview + +- Proposal: SOAR-0013 + +- Author(s): Honza Dvorsky, Si Beaumont + +- Status: **Implemented (1.6.0)** + +- Versions: + +- v1.0 (2024-11-27): Initial version + +- v1.1 (2024-11-28): Also handle “/”, “{”, and “}” for better synthesized operation names + +- v1.2 (2024-12-10): Treat “/” as a word separator and improve handling of the lowercasing of acronyms at the start of an identifier. + +- v1.3 (2024-12-17): Add “+” as a word separator, clarify that defensive strategy always post-processes the output of the idiomatic strategy, clarify that content type names also change with the idiomatic strategy +- Issues: + +- apple/swift-openapi-generator#112 + +- apple/swift-openapi-generator#107 + +- apple/swift-openapi-generator#503 + +- apple/swift-openapi-generator#244 + +- apple/swift-openapi-generator#405 +- Implementation: + +- apple/swift-openapi-generator#679 +- New configuration options: + +- `namingStrategy` + +- `nameOverrides` +- Affected components: + +- generator + +### Introduction + +Introduce a new naming strategy as an opt-in feature, instructing the generator to produce more conventional Swift names, and offer a way to completely customize how any OpenAPI identifier gets projected to a Swift identifier. + +### Motivation + +The purpose of Swift OpenAPI Generator is to generate Swift code from OpenAPI documents. As part of that process, names specified in the OpenAPI document have to be converted to names in Swift code - and there are many ways to do that. We call these “naming strategies” in this proposal. + +When Swift OpenAPI Generator 0.1.0 went open-source in May 2023, it had a simple naming strategy that produced relatively conventional Swift identifiers from OpenAPI names. + +However, when tested on a large test corpus of around 3000 OpenAPI documents, it produced an unacceptably high number of non-compiling packages due to naming conflicts. The root cause of conflicts are the different allowed character sets for OpenAPI names and Swift identifiers. OpenAPI has a more flexible allowed character set than Swift identifiers. + +In response to these findings, SOAR-0001: Improved mapping of identifiers, which shipped in 0.2.0, changed the naming strategy to avoid these conflicts, allowing hundreds of additional OpenAPI documents to be correctly handled by Swift OpenAPI Generator. This addressed all issues related to naming conflicts in the test corpus. This is the existing naming strategy today. This strategy also avoids changing the character casing, as we discovered OpenAPI documents with properties within an object schema that only differed by case. + +The way the conflicts are avoided in the naming strategy from SOAR-0001 is by turning any special characters (any characters that aren’t letters, numbers, or an underscore) into words, resulting in identifiers like: + +Our priority was to support as many valid OpenAPI documents as possible. However, we’ve also heard from adopters who would prefer more idiomatic generated code and don’t benefit from the defensive naming strategy. + +### Proposed solution + +For clarity, we’ll refer to the existing naming strategy as the “defensive” naming strategy, and to the new proposed strategy as the “idiomatic” naming strategy. The names reflect the strengths of each strategy - the defensive strategy can handle any OpenAPI document and produce compiling Swift code, the idiomatic naming strategy produces prettier names, but does not work for all documents. + +Part of the new strategy is adjusting the capitalization, and producing `UpperCamelCase` names for types, and `lowerCamelCase` names for members, as is common in hand-written Swift code. + +This strategy will pre-process the input string, and then still apply the defensive strategy on the output, to handle any illegal characters that are no explicitly handled by the idiomatic strategy. + +The configurable naming strategy will affect not only general names from the OpenAPI document ( SOAR-0001), but also content type names ( SOAR-0002). + +#### Examples + +To get a sense for the proposed change, check out the table below that compares the existing defensive strategy against the proposed idiomatic strategy on a set of examples: + +| OpenAPI name | Defensive | Idiomatic (capitalized) | Idiomatic (non-capitalized) | +| --- | --- | --- | --- | +| `foo` | `foo` | `Foo` | `foo` | +| `Hello world` | `Hello_space_world` | `HelloWorld` | `helloWorld` | +| `My_URL_value` | `My_URL_value` | `MyURLValue` | `myURLValue` | +| `Retry-After` | `Retry_hyphen_After` | `RetryAfter` | `retryAfter` | +| `NOT_AVAILABLE` | `NOT_AVAILABLE` | `NotAvailable` | `notAvailable` | +| `version 2.0` | `version_space_2_period_0` | `Version2_0` | `version2_0` | +| `naïve café` | `naïve_space_café` | `NaïveCafé` | `naïveCafé` | +| `__user` | `__user` | `__User` | `__user` | +| `get/pets/{petId}` _Changed in v1.2_ | `get_sol_pets_sol__lcub_petId_rcub_` | `GetPetsPetId` | `getPetsPetId` | +| `HTTPProxy` _Added in v1.2_ | `HTTPProxy` | `HTTPProxy` | `httpProxy` | +| `application/myformat+json` _Added in v1.3_ | `application_myformat_plus_json` | - | `applicationMyformatJson` | +| `order#123` | `order_num_123` | `order_num_123` | `order_num_123` | + +Notice that in the last example, since the OpenAPI name contains the pound (`#`) character, the idiomatic naming strategy lets the defensive naming strategy handle the illegal character. In all the other cases, however, the resulting names are more idiomatic Swift identifiers. + +### Detailed design + +This section goes into detail of the draft implementation that you can already check out and try to run on your OpenAPI document. + +#### Naming logic + +The idiomatic naming strategy (check out the current code here, look for the method `safeForSwiftCode_idiomatic`) is built around the decision to _only_ optimize for names that include the following: + +- letters + +- numbers + +- periods (`.`, ASCII: `0x2e`) + +- dashes (`-`, ASCII: `0x2d`) + +- underscores (`_`, ASCII: `0x5f`) + +- spaces (``, ASCII: `0x20`) + +- slashes (`/`, ASCII: `0x2f`) _Added in v1.1, changed meaning in 1.2_ + +- curly braces (`{` and `}`, ASCII: `0x7b` and `0x7d`) _Added in v1.1_ + +- pluses (`+`, ASCII: `0x2b`) _Added in v1.3_ + +If the OpenAPI name includes any _other_ characters, the idiomatic naming strategy lets the defensive strategy handle those characters. + +There’s a second special case for handling all uppercased names, such as `NOT_AVAILABLE` \- if this situation is detected, the idiomatic naming strategy turns it into `NotAvailable` for types and `notAvailable` for members. + +The best way to understand the detailed logic is to check out the code, feel free to leave comments on the pull request. + +#### Naming strategy configuration + +Since Swift OpenAPI Generator is on a stable 1.x version, we cannot change the naming strategy for everyone, as it would be considered an API break. So this new naming strategy is fully opt-in using a new configuration key called `namingStrategy`, with the following allowed values: + +- `defensive`: the existing naming strategy introduced in 0.2.0 + +- `idiomatic`: the new naming strategy proposed here + +- not specified: defaults to `defensive` for backwards compatibility + +Enabling this feature in the configuration file would look like this: + +namingStrategy: idiomatic + +#### Name overrides + +While the new naming strategy produces much improved Swift names, there are still cases when the adopter knows better how they’d like a specific OpenAPI name be translated to a Swift identifier. + +A good examples are the `+1` and `-1` properties in the GitHub OpenAPI document: using both strategies, the names would be `_plus_1` and `_hyphen_1`, respectively. While such names aren’t too confusing, the adopter might want to customize them to, for example: `thumbsUp` and `thumbsDown`. + +nameOverrides: +'+1': 'thumbsUp' +'-1': 'thumbsDown' + +### API stability + +Both the new naming strategy and name overrides are purely additive, and require the adopter to explicitly opt-in. + +### Future directions + +With this proposal, we plan to abandon the “naming extensions” idea, as we consider the solution in this proposal to solve the name conversion problem for Swift OpenAPI Generator 1.x for all use cases. + +### Alternatives considered + +- “Naming extensions”, however that’d require the community to build and maintain custom naming strategies, and it was not clear that this feature would be possible in SwiftPM using only current features. + +- Not changing anything, this was the status quo since 0.2.0, but adopters have made it clear that there is room to improve the naming strategy through the several filed issues linked at the top of the proposal, so we feel that some action here is justified. + +## See Also + +SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +- SOAR-0013: Idiomatic naming strategy +- Overview +- Introduction +- Motivation +- Proposed solution +- Detailed design +- API stability +- Future directions +- Alternatives considered +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-0011 + +- Swift OpenAPI Generator +- Proposals +- SOAR-0011: Improved Error Handling + +Article + +# SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +## Overview + +- Proposal: SOAR-0011 + +- Author(s): Gayathri Sairamkrishnan + +- Status: **Implemented** + +- Issue: apple/swift-openapi-generator#609 + +- Affected components: + +- runtime +- Versions: + +- v1.0 (2024-09-19): Initial version + +- v1.1(2024-10-07): + +- Replace the proposed solution to have a single error handling protocol, with the status being required and headers/body being optional. + +### Introduction + +The goal of this proposal to improve the current error handling mechanism in Swift OpenAPI runtime. The proposal introduces a way for users to map errors thrown by their handlers to specific HTTP responses. + +### Motivation + +When implementing a server with Swift OpenAPI Generator, users implement a type that conforms to a generated protocol, providing one method for each API operation defined in the OpenAPI document. At runtime, if this function throws, it’s up to the server transport to transform it into an HTTP response status code – for example, some transport use `500 Internal Error`. + +Instead, server developers may want to map errors thrown by the application to a more specific HTTP response. Currently, this can be achieved by checking for each error type in each handler’s catch block, converting it to an appropriate HTTP response and returning it. + +For example, + +do { +let response = try callGreetingLib() +return .ok(.init(body: response)) +} catch let error { +switch error { +case GreetingError.authorizationError: +return .unauthorized(.init()) +case GreetingError.timeout: +return ... +} +} +} + +If a user wishes to map many errors, the error handling block scales linearly and introduces a lot of ceremony. + +### Proposed solution + +The proposed solution is twofold. + +1. Provide a protocol in `OpenAPIRuntime` to allow users to extend their error types with mappings to HTTP responses. + +2. Provide an (opt-in) middleware in OpenAPIRuntime that will call the conversion function on conforming error types when constructing the HTTP response. + +Vapor has a similar mechanism called AbortError. + +Hummingbird also has an error handling mechanism by allowing users to define a HTTPError + +The proposal aims to provide a transport agnostic error handling mechanism for OpenAPI users. + +#### Proposed Error protocols + +Users can choose to conform to the error handling protocol below and optionally provide the optional fields depending on the level of specificity they would like to have in the response. + +public protocol HTTPResponseConvertible { +var httpStatus: HTTPResponse.Status { get } +var httpHeaderFields: HTTPTypes.HTTPFields { get } +var httpBody: OpenAPIRuntime.HTTPBody? { get } +} + +extension HTTPResponseConvertible { +var httpHeaderFields: HTTPTypes.HTTPFields { [:] } +var httpBody: OpenAPIRuntime.HTTPBody? { nil } +} + +#### Proposed Error Middleware + +The proposed error middleware in OpenAPIRuntime will convert the application error to the appropriate error response. It returns 500 for application error(s) that do not conform to HTTPResponseConvertible protocol. + +public struct ErrorHandlingMiddleware: ServerMiddleware { +func intercept(_ request: HTTPTypes.HTTPRequest, +body: OpenAPIRuntime.HTTPBody?, +metadata: OpenAPIRuntime.ServerRequestMetadata, +operationID: String, + +do { +return try await next(request, body, metadata) +} catch let error as ServerError { +if let appError = error.underlyingError as? HTTPResponseConvertible else { +return (HTTPResponse(status: appError.httpStatus, headerFields: appError.httpHeaderFields), +appError.httpBody) +} else { +throw error +} +} +} +} + +Please note that the proposal places the responsibility to conform to the documented API in the hands of the user. There’s no mechanism to prevent the users from inadvertently transforming a thrown error into an undocumented response. + +#### Example usage + +1. Create an error type that conforms to the error protocol + +extension MyAppError: HTTPResponseConvertible { +var httpStatus: HTTPResponse.Status { +switch self { +case .invalidInputFormat: +.badRequest +case .authorizationError: +.forbidden +} +} +} + +2. Opt in to the error middleware while registering the handler + +let handler = try await RequestHandler() +try handler.registerHandlers(on: transport, middlewares: [ErrorHandlingMiddleware()]) + +### API stability + +This feature is purely additive: + +- Additional APIs in the runtime library + +### Future directions + +A possible future direction is to add the error middleware by default by changing the default value for the middlewares argument in handler initialisation. + +### Alternatives considered + +An alternative here is to invoke the error conversion function directly from OpenAPIRuntime’s handler. The feature would still be opt-in as users have to explicitly conform to the new error protocols. + +However, there is a rare case where an application might depend on a library (for eg: an auth library) which in turn depends on OpenAPIRuntime. If the authentication library conforms to the new error protocols, this would result in a breaking change for the application, whereas an error middleware provides flexibility to the user on whether they want to subscribe to the new behaviour or not. + +## See Also + +SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +- SOAR-0011: Improved Error Handling +- Overview +- Introduction +- Motivation +- Proposed solution +- Detailed design +- API stability +- Future directions +- Alternatives considered +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-0003 + +- Swift OpenAPI Generator +- Proposals +- SOAR-0003: Type-safe Accept headers + +Article + +# SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +## Overview + +- Proposal: SOAR-0003 + +- Author(s): Honza Dvorsky, Si Beaumont + +- Status: **Implemented (0.2.0)** + +- Issue: apple/swift-openapi-generator#160 + +- Implementation: apple/swift-openapi-runtime#37, apple/swift-openapi-generator#185 + +- Review: ( review) + +- Affected components: generator, runtime + +### Introduction + +Generate a type-safe representation of the possible values in the Accept header for each operation. + +#### Accept header + +The Accept request header allows the client to communicate to the server which content types the client can handle in the response body. This includes the ability to provide multiple values, and to give each a numeric value to that represents preference (called “quality”). + +Many clients don’t provide any preference, for example by not including the Accept header, providing `accept: */*`, or listing all the known response headers in a list. The last option is what our generated clients do by default already today. + +However, sometimes the client needs to narrow down the list of acceptable content types, or it prefers one over the other, while it can still technically handle both. + +For example, let’s consider an operation that returns an image either in the `png` or `jpeg` format. A client with a low amount of CPU and memory might choose `jpeg`, even though it could also handle `png`. In such a scenario, it would send an Accept header that could look like: `accept: image/jpeg, image/png; q=0.1`. This tells the server that while the client can handle both formats, it really prefers `jpeg`. Note that the “q” parameter represents a priority value between `0.0` and `1.0` inclusive, and the default value is `1.0`. + +However, the client could also completely lack a `png` decoder, in which case it would only request the `jpeg` format with: `accept: image/jpeg`. Note that `image/png` is completely omitted from the Accept header in this case. + +To summarize, the client needs to _provide_ Accept header information, and the server _inspects_ that information and uses it as a hint. Note that the server is still in charge of making the final decision over which of the acceptable content types it chooses, or it can return a 4xx status code if it cannot satisfy the client’s request. + +#### Existing behavior + +Today, the generated client includes in the Accept header all the content types that appear in any response for the invoked operation in the OpenAPI document, essentially allowing the server to pick any content type. For an operation that uses JSON and plain text, the header would be: `accept: application/json, text/plain`. However, there is no way for the client to narrow down the choices or customize the quality value, meaning the only workaround is to build a `ClientMiddleware` that modifies the raw HTTP request before it’s executed by the transport. + +On the server side, adopters have had to resort to workarounds, such as extracting the Accept header in a custom `ServerMiddleware` and saving the parsed value into a task local value. + +#### Why now? + +While the Accept header can be sent even with requests that only have one documented response content type, it is most useful when the response contains multiple possible content types. + +That’s why we are proposing this feature now, since multiple content types recently got implemented in Swift OpenAPI Generator - hidden behind the feature flag `multipleContentTypes` in versions `0.1.7+`. + +### Proposed solution + +We propose to start generating a new enum in each operation’s namespace that contains all the unique concrete content types that appear in any of the operation’s responses. This enum would also have a case called `other` with an associated `String` value, which would be an escape hatch, similar to the `undocumented` case generated today for undocumented response codes. + +This enum would be used by a new property that would be generated on every operation’s `Input.Headers` struct, allowing clients a type-safe way to set, and servers to get, this information, represented as an array of enum values each wrapped in a type that also includes the quality value. + +### Example + +For example, let’s consider the following operation: + +/stats: +get: +operationId: getStats +responses: +'200': +description: A successful response with stats. +content: +application/json: +schema: +... +text/plain: {} + +The generated code in `Types.swift` would gain an enum definition and a property on the headers struct. + +// Types.swift +// ... +enum Operations { +enum getStats { +struct Input { +struct Headers { ++ var accept: [AcceptHeaderContentType<\ ++ Operations.getStats.AcceptableContentType\ + +} +} +enum Output { +// ... +} ++ enum AcceptableContentType: AcceptableProtocol { ++ case json ++ case plainText ++ case other(String) ++ } +} +} + +As a client adopter, you would be able to set the new defaulted property `accept` on `Input.Headers`. The following invocation of the `getStats` operation tells the server that the JSON content type is preferred over plain text, but both are acceptable. + +let response = try await client.getStats(.init( +headers: .init(accept: [\ +.init(contentType: .json),\ +.init(contentType: .plainText, quality: 0.5)\ +]) +)) + +You could also leave it to its default value, which sends the full list of content types documented in the responses for this operation - which is the existing behavior. + +As a server implementer, you would inspect the provided Accept information for example by sorting it by quality (highest first), and always returning the most preferred content type. And if no Accept header is provided, this implementation defaults to JSON. + +struct MyHandler: APIProtocol { + +let contentType = input +.headers +.accept +.sortedByQuality() +.first? +.contentType ?? .json +switch contentType { +case .json: +// ... return JSON +case .plainText: +// ... return plain text +case .other(let value): +// ... inspect the value or return an error +} +} +} + +### Detailed design + +This feature requires a new API in the runtime library, in addition to the new generated code. + +#### New runtime library APIs + +/// The protocol that all generated `AcceptableContentType` enums conform to. +public protocol AcceptableProtocol : CaseIterable, Hashable, RawRepresentable, Sendable where Self.RawValue == String {} + +/// A wrapper of an individual content type in the accept header. + +/// The value representing the content type. +public var contentType: ContentType + +/// The quality value of this content type. +/// +/// Used to describe the order of priority in a comma-separated +/// list of values. +/// +/// Content types with a higher priority should be preferred by the server +/// when deciding which content type to use in the response. +/// +/// Also called the "q-factor" or "q-value". +public var quality: QualityValue + +/// Creates a new content type from the provided parameters. +/// - Parameters: +/// - value: The value representing the content type. +/// - quality: The quality of the content type, between 0.0 and 1.0. +/// - Precondition: Priority must be in the range 0.0 and 1.0 inclusive. +public init(contentType: ContentType, quality: QualityValue = 1.0) + +/// Returns the default set of acceptable content types for this type, in +/// the order specified in the OpenAPI document. +public static var defaultValues: [`Self`] { get } +} + +/// A quality value used to describe the order of priority in a comma-separated +/// list of values, such as in the Accept header. +public struct QualityValue : Sendable, Equatable, Hashable { + +/// Creates a new quality value of the default value 1.0. +public init() + +/// Returns a Boolean value indicating whether the quality value is +/// at its default value 1.0. +public var isDefault: Bool { get } + +/// Creates a new quality value from the provided floating-point number. +/// +/// - Precondition: The value must be between 0.0 and 1.0, inclusive. +public init(doubleValue: Double) + +/// The value represented as a floating-point number between 0.0 and 1.0, inclusive. +public var doubleValue: Double { get } +} + +extension QualityValue : RawRepresentable { ... } +extension QualityValue : ExpressibleByIntegerLiteral { ... } +extension QualityValue : ExpressibleByFloatLiteral { ... } +extension AcceptHeaderContentType : RawRepresentable { ... } + +extension Array { +/// Returns the array sorted by the quality value, highest quality first. + +/// Returns the default values for the acceptable type. + +} + +The generated operation-specific enum called `AcceptableContentType` conforms to the `AcceptableProtocol` protocol. + +A full example of a generated `AcceptableContentType` for `getStats` looks like this: + +@frozen public enum AcceptableContentType: AcceptableProtocol { +case json +case plainText +case other(String) +public init?(rawValue: String) { +switch rawValue.lowercased() { +case "application/json": self = .json +case "text/plain": self = .plainText +default: self = .other(rawValue) +} +} +public var rawValue: String { +switch self { +case let .other(string): return string +case .json: return "application/json" +case .plainText: return "text/plain" +} +} +public static var allCases: [Self] { [.json, .plainText] } +} + +### API stability + +This feature is purely additive, and introduces a new property to `Input.Headers` generated structs for all operations with at least 1 documented response content type. + +The default behavior is still the same – all documented response content types are sent in the Accept header. + +#### Support for wildcards + +One deliberate omission from this design is the support for wildcards, such as `*/*` or `application/*`. If such a value needs to be sent or received, the adopter is expected to use the `other(String)` case. + +While we discussed this topic at length, we did not arrive at a solution that would provide enough added value for the extra complexity, so it is left up to future proposals to solve, or for real-world usage to show that nothing more is necessary. + +#### A stringly array + +The `accept` property could have simply been `var accept: [String]`, where the generated code would only concatenate or split the header value with a comma, but then leave it to the adopter to construct or parse the type, subtype, and optional quality parameter. + +That seemed to go counter to this project’s goals of making access to the information in the OpenAPI document as type-safe as possible, helping catch bugs at compile time. + +#### Maintaing the status quo + +We also could have not implemented anything, leaving adopters who need to customize the Accept header to inject or extract that information with a middleware, both on the client and server side. + +That option was rejected as without explicit support for setting and getting the Accept header information, the support for multiple content types seemed incomplete. + +## See Also + +SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +- SOAR-0003: Type-safe Accept headers +- Overview +- Introduction +- Motivation +- Proposed solution +- Example +- Detailed design +- API stability +- Future directions +- Alternatives considered +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-0007 + +- Swift OpenAPI Generator +- Proposals +- SOAR-0007: Shorthand APIs for operation inputs and outputs + +Article + +# SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +## Overview + +- Proposal: SOAR-0007 + +- Author(s): Si Beaumont + +- Status: **Implemented (0.3.0)** + +- Review period: 2023-09-22 – 2023-09-29 + +- Swift Forums post +- Issue: apple/swift-openapi-generator#22, apple/swift-openapi-generator#104, apple/swift-openapi-generator#105, apple/swift-openapi-generator#145 + +- Implementation: apple/swift-openapi-runtime#56, apple/swift-openapi-generator#308 + +- Review: ( review) + +- Affected components: generator, runtime + +- Related links: + +- Project scope and goals +- Versions: + +- v1 (2023-09-22): Initial version + +### Introduction + +A key goal of Swift OpenAPI Generator is to generate code that faithfully represents the OpenAPI document\ [0\] and is capable of remaining as expressive as the OpenAPI specification, in which operations can have one of several responses (e.g. `200`, `204`), each of which can have one of several response bodies (e.g. `application/json`, `text/plain`). + +Consequently, the generated code allows for exhaustive type-safe handling of all possible responses (including undocumented responses) by using nested enum values for the HTTP status and the body. + +However, for simple operations that have just one documented outcome, the generated API seems overly verbose to use. We discuss a concrete example in the following section. + +### Motivation + +To motivate the proposal we will consider a trivial API which returns a personalized greeting. The OpenAPI document for this service is provided in an appendix, but its behaviour is illustrated with the following API call from the terminal: + +% curl 'localhost:8080/api/greet?name=Maria' +{ "message" : "Hello, Maria" } + +The generated API protocols define one function per OpenAPI operation. These functions take a single input parameter that holds all the operation inputs (header fields, query items, cookies, body, etc.). Consequently, when making an API call, there is an additional initializer to call. This presents unnecessary ceremony, especially when calling operations with no parameters or only default parameters. + +// before (with parameters) +_ = try await client.getGreeting(Operations.getGreeting.Input( +query: Operations.getGreeting.Input.Query(name: "Maria") +)) + +// before (with parameters, shorthand) +_ = try await client.getGreeting(.init(query: .init(name: "Maria"))) + +// before (no parameters, shorthand) +_ = try await client.getGreeting(.init())) + +The generated `Output` type for each API operation is an enum with cases for each documented response and a case for an undocumented response. Following this pattern, the `Output.Body` is also an enum with cases for every documented content type for the response. + +While this API encourages users to handle all possible scenarios, it leads to ceremony when the user requires a specific response and receiving anything else is considered an error. This is especially apparent for API operations that have just a single response, e.g. `OK`, and a single content type, e.g. `application/json`. + +// before +switch try await client.getGreeting() { +case .ok(let response): +switch response.body { +case .json(let body): +print(body.message) +} +case .undocumented(statusCode: _, _): +throw UnexpectedResponseError() +} + +For users who wish to get an expected response or fail, they will have to define their own error type. They may also make use of `guard case let ... else { throw ... }` which reduces the code, but still presents additional ceremony. + +### Proposed solution + +To simplify providing inputs, generate an overload for each operation that lifts each of the parameters of `Input.init` as function parameters. This removes the need for users to call `Input.init`, which streamlines the API call, especially when the user does not need to provide parameters. + +// after (with parameters, shorthand) +_ = try await client.getGreeting(query: .init(name: "Maria")) + +// after (no parameters) +_ = try await client.getGreeting() + +To simplify handling outputs, provide a throwing computed property for each enum case related to a documented outcome, which will return the associated value for the expected case, or throw a runtime error if the value is a different enum case. This allows for expressing the expected outcome as a chained operation. + +// after +print(try await client.getGreeting().ok.body.json.message) +// ^ ^ ^ +// | | `- (New) Throws if body did not conform to documented JSON. +// | | +// | `- (New) Throws if HTTP response is not 200 (OK). +// | +// `- (Existing) Throws if there is an error making the API call. + +### Detailed design + +The following listing is a relevant subset of the code that is currently generated for our example API. The comments have been changed for the audience of this proposal. The entire code is contained in an appendix. + +public protocol APIProtocol: Sendable { +// A function requirement is generated for each operation. It takes an +// input type, comprising all parameters, and returns an output type, which +// is an nested enum covering all possible responses. + +} + +public enum Operations { +public enum getGreeting { +public struct Input: Sendable, Hashable { +// If all parameters have default values, then the initializer +// parameter also has a default value. +public init( +query: Operations.getGreeting.Input.Query = .init(), +headers: Operations.getGreeting.Input.Headers = .init() +) { +self.query = query +self.headers = headers +} +} +@frozen public enum Output: Sendable, Hashable { +public struct Ok: Sendable, Hashable { +@frozen public enum Body: Sendable, Hashable { +case json(Components.Schemas.Greeting) +} +public var body: Operations.getGreeting.Output.Ok.Body +public init(body: Operations.getGreeting.Output.Ok.Body) { self.body = body } +} +// An enum case is generated for each documented response. +case ok(Operations.getGreeting.Output.Ok) +// An additional enum case is generated for any undocumented response. +case undocumented(statusCode: Int, OpenAPIRuntime.UndocumentedPayload) +} +} +} + +This proposal covers generating the following additional API surface to simplify providing inputs. + +extension APIProtocol { +// The parameters to each overload will match those of the corresponding +// operation input initializer, including optionality. +public func getGreeting( +query: Operations.getGreeting.Input.Query = .init(), +headers: Operations.getGreeting.Input.Headers = .init() +) { +// Simply wraps the call to the protocol function in an input value. +getGreeting(Operations.getGreeting.Input( +query: query, +headers: headers +)) +} +} + +This proposal also covers generating the following additional API surface to simplify handling outputs. + +// Note: Generating an extension is not prescriptive; implementations may +// generate these properties within the primary type definition. +extension Operations.getGreeting.Output { +// A throwing computed property is generated for each documented outcome. +var ok: Operations.getGreeting.Output.Ok { +get throws { +guard case let .ok(response) = self else { +// This error will be added to the OpenAPIRuntime library. +throw UnexpectedResponseError(expected: "ok", actual: self) +} +return response +} +} +// Note: a property is _not_ generated for the undocumented enum case. +} + +// Note: Generating an extension is not prescriptive; implementations may +// generate these properties within the primary type definition. +extension Operations.getGreeting.Output.Ok.Body { +// A throwing computed property is generated for each document content type. +var json: Components.Schemas.Greeting { +get throws { +guard case let .json(body) = self else { +// This error will be added to the OpenAPIRuntime library. +throw UnexpectedContentError(expected: "json", actual: self) +} +return body +} +} +} + +### API stability + +This change is purely API additive: + +- Additional SPI in the runtime library + +- Additional API in the generated code + +### Future directions + +Nothing in this proposal. + +#### Providing macros + +A macro library could be used in conjunction with the existing generated code. + +However, this proposal does not consider this a viable option for two reasons: + +1. We currently support Swift 5.8; and + +2. Adopters that rely on ahead-of-time generation will not benefit. + +#### Making this an opt-in feature + +There generator could conditionally generate this code, e.g. using a configuration option, or hiding the generated code behind an SPI. + +This proposal does so unconditionally in the spirit of _making easy things, easy._ Based on adopter feedback, enough users want to be able to do this that it should be very discoverable on first use. + +### Appendix A: OpenAPI document for example service + +# openapi.yaml +# ------------ +openapi: '3.0.3' +info: +title: GreetingService +version: 1.0.0 +servers: +- url: +description: Example +paths: +/greet: +get: +operationId: getGreeting +parameters: +- name: name +required: false +in: query +description: A name used in the returned greeting. +schema: +type: string +responses: +'200': +description: A success response with a greeting. +content: +application/json: +schema: +$ref: '#/components/schemas/Greeting' +components: +schemas: +Greeting: +type: object +properties: +message: +type: string +required: +- message + +### Appendix B: Existing generated code for example service + +Generated using the following command: + +% swift-openapi-generator generate --mode types openapi.yaml +// Types.swift +// ----------- +// Generated by swift-openapi-generator, do not modify. +@_spi(Generated) import OpenAPIRuntime +#if os(Linux) +@preconcurrency import struct Foundation.URL +@preconcurrency import struct Foundation.Data +@preconcurrency import struct Foundation.Date +#else +import struct Foundation.URL +import struct Foundation.Data +import struct Foundation.Date +#endif +/// A type that performs HTTP operations defined by the OpenAPI document. +public protocol APIProtocol: Sendable { +/// - Remark: HTTP `GET /greet`. +/// - Remark: Generated from `#/paths//greet/get(getGreeting)`. + +} +/// Server URLs defined in the OpenAPI document. +public enum Servers { +/// Example + +} +/// Types generated from the components section of the OpenAPI document. +public enum Components { +/// Types generated from the `#/components/schemas` section of the OpenAPI document. +public enum Schemas { +/// - Remark: Generated from `#/components/schemas/Greeting`. +public struct Greeting: Codable, Hashable, Sendable { +/// - Remark: Generated from `#/components/schemas/Greeting/message`. +public var message: Swift.String +/// Creates a new `Greeting`. +/// +/// - Parameters: +/// - message: +public init(message: Swift.String) { self.message = message } +public enum CodingKeys: String, CodingKey { case message } +} +} +/// Types generated from the `#/components/parameters` section of the OpenAPI document. +public enum Parameters {} +/// Types generated from the `#/components/requestBodies` section of the OpenAPI document. +public enum RequestBodies {} +/// Types generated from the `#/components/responses` section of the OpenAPI document. +public enum Responses {} +/// Types generated from the `#/components/headers` section of the OpenAPI document. +public enum Headers {} +} +/// API operations, with input and output types, generated from `#/paths` in the OpenAPI document. +public enum Operations { +/// - Remark: HTTP `GET /greet`. +/// - Remark: Generated from `#/paths//greet/get(getGreeting)`. +public enum getGreeting { +public static let id: String = "getGreeting" +public struct Input: Sendable, Hashable { +/// - Remark: Generated from `#/paths/greet/GET/query`. +public struct Query: Sendable, Hashable { +/// A name used in the returned greeting. +/// +/// - Remark: Generated from `#/paths/greet/GET/query/name`. +public var name: Swift.String? +/// Creates a new `Query`. +/// +/// - Parameters: +/// - name: A name used in the returned greeting. +public init(name: Swift.String? = nil) { self.name = name } +} +public var query: Operations.getGreeting.Input.Query +/// - Remark: Generated from `#/paths/greet/GET/header`. +public struct Headers: Sendable, Hashable { +public var accept: + +/// Creates a new `Headers`. +/// +/// - Parameters: +/// - accept: +public init( + +.defaultValues() +) { self.accept = accept } +} +public var headers: Operations.getGreeting.Input.Headers +/// Creates a new `Input`. +/// +/// - Parameters: +/// - query: +/// - headers: +public init( +query: Operations.getGreeting.Input.Query = .init(), +headers: Operations.getGreeting.Input.Headers = .init() +) { +self.query = query +self.headers = headers +} +} +@frozen public enum Output: Sendable, Hashable { +public struct Ok: Sendable, Hashable { +/// - Remark: Generated from `#/paths/greet/GET/responses/200/content`. +@frozen public enum Body: Sendable, Hashable { +/// - Remark: Generated from `#/paths/greet/GET/responses/200/content/application\/json`. +case json(Components.Schemas.Greeting) +} +/// Received HTTP response body +public var body: Operations.getGreeting.Output.Ok.Body +/// Creates a new `Ok`. +/// +/// - Parameters: +/// - body: Received HTTP response body +public init(body: Operations.getGreeting.Output.Ok.Body) { self.body = body } +} +/// A success response with a greeting. +/// +/// - Remark: Generated from `#/paths//greet/get(getGreeting)/responses/200`. +/// +/// HTTP response code: `200 ok`. +case ok(Operations.getGreeting.Output.Ok) +/// Undocumented response. +/// +/// A response with a code that is not documented in the OpenAPI document. +case undocumented(statusCode: Int, OpenAPIRuntime.UndocumentedPayload) +} +@frozen public enum AcceptableContentType: AcceptableProtocol { +case json +case other(String) +public init?(rawValue: String) { +switch rawValue.lowercased() { +case "application/json": self = .json +default: self = .other(rawValue) +} +} +public var rawValue: String { +switch self { +case let .other(string): return string +case .json: return "application/json" +} +} +public static var allCases: [Self] { [.json] } +} +} +} + +## See Also + +SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +- SOAR-0007: Shorthand APIs for operation inputs and outputs +- Overview +- Introduction +- Motivation +- Proposed solution +- Detailed design +- API stability +- Future directions +- Alternatives considered +- Appendix A: OpenAPI document for example service +- Appendix B: Existing generated code for example service +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-0014 + +- Swift OpenAPI Generator +- Proposals +- SOAR-0014: Support Type Overrides + +Article + +# SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +## Overview + +- Proposal: SOAR-0014 + +- Author(s): simonbility + +- Status: **Implemented (1.9.0)** + +- Issue: apple/swift-openapi-generator#375 + +- Implementation: + +- apple/swift-openapi-generator#764 +- Affected components: + +- generator + +### Introduction + +The goal of this proposal is to allow users to specify custom types for generated. This will enable users to use their own types instead of the default generated ones, allowing for greater flexibility. + +### Motivation + +This proposal would enable more flexibility in the generated code. Some usecases include: + +- Using custom types that are already defined in the user’s codebase or even coming from a third party library, instead of generating new ones. + +- workaround missing support for `format` for strings + +- Implement custom validation/encoding/decoding logic that cannot be expressed using the OpenAPI spec + +This is intended as a “escape hatch” for use-cases that (currently) cannot be expressed. Using this comes with the risk of user-provided types not being compliant with the original OpenAPI spec. + +### Proposed solution + +The proposed solution is to allow specifying typeOverrides using a new configuration option named `typeOverrides`. This is only supported for schemas defined in the `components.schemas` section of a OpenAPI document. + +### Example + +A current limitiation is string formats are not directly supported by the generator. (for example, `uuid` is not supported) + +With this proposal this can be worked around with with the following approach (This proposal does not preclude extending support for formats in the future): + +Given schemas defined in the OpenAPI document like this: + +components: +schemas: +UUID: +type: string +format: uuid + +Adding typeOverrides like this in the configuration + ++ typeOverrides: ++ schemas: ++ UUID: Foundation.UUID + +Will affect the generated code in the following way: + +/// Types generated from the `#/components/schemas` section of the OpenAPI document. +package enum Schemas { +/// - Remark: Generated from `#/components/schemas/UUID`. +- package typealias Uuid = Swift.String ++ package typealias Uuid = Foundation.UUID +} + +### Detailed design + +In the configuration file a new `typeOverrides` option is supported. It contains mapping from the original name (as defined in the OpenAPI document) to a override type name to use instead of the generated name. + +The mapping is evaluated relative to `#/components/schemas` + +So defining overrides like this: + +typeOverrides: +schemas: +OriginalName: NewName + +will replace the generated type for `#/components/schemas/OriginalName` with `NewName`. + +Its in the users responsibility to ensure that the type is valid and available. It must conform to `Codable`, `Hashable` and `Sendable` + +### API stability + +While this proposal does affect the generated code, it requires the user to explicitly opt-in to using the `typeOverrides` configuration option. + +This is interpreted as a “strong enough” signal of the user to opt into this behaviour, to justify NOT introducing a feature-flag or considering this a breaking change. + +### Future directions + +The implementation could potentially be extended to support inline defined properties as well. This could be done by supporting “Paths” instead of names in the mapping. + +For example with the following schema. + +components: +schemas: +User: +properties: +id: +type: string +format: uuid + +This configuration could be used to override the type of `id`: + +typeOverrides: +schemas: +'User/id': Foundation.UUID + +### Alternatives considered + +An alternative to the mapping defined in the configuration file is to use a vendor extension (for instance `x-swift-open-api-override-type`) in the OpenAPI document itself. + +... +components: +schemas: +UUID: +type: string +x-swift-open-api-override-type: Foundation.UUID + +The current proposal using the configuration file was preferred because it does not rely on modifying the OpenAPI document itself, which is not always possible/straightforward when its provided by a third-party. + +## See Also + +SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +- SOAR-0014: Support Type Overrides +- Overview +- Introduction +- Motivation +- Proposed solution +- Example +- Detailed design +- API stability +- Future directions +- Alternatives considered +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-0004 + +- Swift OpenAPI Generator +- Proposals +- SOAR-0004: Streaming request and response bodies + +Article + +# SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +## Overview + +- Proposal: SOAR-0004 + +- Author(s): Honza Dvorsky + +- Status: **Implemented (0.3.0)** + +- Issue: apple/swift-openapi-generator#9 + +- Implementation: apple/swift-openapi-generator#245, apple/swift-openapi-runtime#47, apple/swift-openapi-urlsession#15, swift-server/swift-openapi-async-http-client#16 + +- Review: ( review) + +- Affected components: generator, runtime, client transports, server transports + +- Versions: + +- v1 (2023-09-08): Initial version + +- v1.1: Make HTTPBody.Iterator.next() mutating + +- v1.2 (2023-09-12): Added more Sendable requirements on all the async sequences. + +- v1.3: Removed initializers for sync sequences-of-chunks, removed labels for the first parameter, switched from `collect` methods to convenience initializers. + +- v1.4 (2023-09-13): Use opaque parameter types wherever possible. + +### Introduction + +Represent HTTP request and response bodies as an asynchronous sequence of byte chunks, unlocking use-cases that require streaming the body instead of buffering it in memory. + +### Motivation + +OpenAPI describes two kinds of body payloads: _structured_ and _unstructured_. + +Structured payloads use JSON Schema for describing their structure, and some examples of structured content types are JSON, XML, URL encoded forms, multipart forms, and so on. As the name suggests, for structured payloads, the generator emits types that conform to `Codable`, providing the adopter with type-safe access to the underlying contents. Generally, in order to decode the bytes representing a structured payload into a `Decodable` type, all the bytes have to be buffered and provided to the decoder in one go. + +Unstructured payloads, on the other hand, are represented by content types such as `text/plain` (a string) and `application/octet-stream` (raw bytes). An example use-case for a string payload would be raw logs emitted by a web service, and for a raw byte payload a compressed archive of a directory. Or, a byte stream can represent a completely custom serialization scheme that the user interprets using a higher level library, for example Server-Sent Events using the `text/event-stream` content type. + +In contrast with structured payloads, unstructured payloads can generally be interpreted as a stream, without first buffering the full body into memory. This allows using unstructured content types to transfer large payloads, such as multi-GB files even through a process that only has a fraction of that memory available - by transferring the large payload in smaller chunks. + +Up to Swift OpenAPI Generator 0.2.x, all body payloads were treated as structured, meaning the generated code buffered both request and response bodies at the user/generated code boundary, and handed it over to the transport as `Foundation.Data`. This was a simple solution that optimized for the common JSON use-case, but as the project matures and is used in more areas where unstructued payloads are used, such as file uploads, buffering bodies has become a blocker. + +### Proposed solution + +Introduce a new type called `HTTPBody` in the runtime library, and use it both as the body type in the transport and middleware protocols, and also as the value nested in the respective generated `Input`/ `Output` types for operations that use an unstructured payload. + +#### A unified streaming body type + +To understand why a single type is proposed, as opposed to one type for client and another for server, let’s consider the entities that perform reading and writing. + +- Producers of bodies: + +- client produces HTTP request bodies + +- server produces HTTP response bodies +- Consumers of bodies: + +- server consumes HTTP request bodies + +- client consumes HTTP response bodies + +We can simplify the space by only talking about “body producers” and “body consumers”, and they apply to both requests and responses, and clients and servers. + +Furthermore, instead of creating two types, one for producing a body and another for consuming a body, we also have to consider entities that do _both_ consuming and producing of bodies, such as middlewares. + +- Both consumers and producers of bodies: + +- client middleware consumes and produces both HTTP request and response bodies + +- server middleware consumes and produces both HTTP request and response bodies + +In the case of middlewares, sometimes a middleware might pass a body unmodified, and for example only add an extra header, but other times it might transform the body, such as by performing compression. + +The new `HTTPBody` type serves as the single unified type for producing and consuming bodies for clients, servers, and their respective middlewares. + +#### Streaming bodies in transport and middleware protocols + +Previously, the currency type for the underlying HTTP request and response bodies was `Foundation.Data`. + +We instead propose to replace it with `OpenAPIRuntime.HTTPBody`, both on the request and response side. + +In Swift-looking pseudo-code, the existing signature of a client transport currently looks something like this: + +protocol ClientTransport { +func send( +requestMetadata: HTTPRequestMetadata, +requestBody: Foundation.Data + +} + +In goes the request metadata (the path, query, and header fields) together with a buffered request body, and out comes the response metadata (the status code and header fields) together with a buffered response body. + +Conceptually, we propose to change it to the following: + +protocol ClientTransport { +func send( +requestMetadata: HTTPRequestMetadata, +requestBody: OpenAPIRuntime.HTTPBody + +All that changed is the body type switched from `Foundation.Data` to `OpenAPIRuntime.HTTPBody`, which removes the forced buffering. + +#### Streaming bodies in generated code + +The previous section discussed using the `HTTPBody` type in the transport and middleware protocols, as the currency type for HTTP bodies. The transport and middleware protocols are defined in the runtime library, and are _shared_ by all adopter of Swift OpenAPI Generator and all their OpenAPI documents. + +This section discusses how the concept of a streaming unstructured payload is surfaced in the generated code, which is _specific_ to each adopter’s OpenAPI document. + +To better illustrate the change, let’s consider an example service called “Stats service”, which allows a client to get and post statistics in various serialization formats. + +The service has two operations, `getStats` and `postStats`. + +The first operation, `getStats`, is a `GET` call to the `/stats` path and returns the status code 200 on success, with one of the following three content types: + +application/json: +schema: +$ref: '#/components/schemas/StatItems' +text/plain: {} +application/octet-stream: {} + +The first option is JSON, a structured payload, with the structure described by the `StatItems` JSON schema value. For example: + +[{"name":"CatCount","value":42},{"name":"DogCount","value":24}] + +The second option is a text-based representation of the stats, that works similarly to CSV, but where all values are separated using an underscore: + +CatCount_42_DogCount_24 + +The third option is a tightly packed representation that uses individual bits to persist the data. The binary representation could look like the following, where two bits are used for signifying the name, and the next six hold the count. + +0010101001011000 + +Notice that while the JSON payload needs to be buffered fully before it can be parsed, the text and binary representations can be interpreted as the data comes in, whenever the next key-value pair arrives (in the text case, a key-value pair can be parsed once two underscores have been encountered, and in the binary case, every 8 bits represent one key-value pair). + +With Stats service in mind, let’s compare the way code is generated today, and how it can be improved using a streaming `HTTPBody`. + +First, the whole Stats service API contract is represented by a generated protocol, used both by the client to make API calls, and by the server to implement the business logic. + +public protocol APIProtocol: Sendable { + +And the generated types used by the `getStats` operation include the `Operations.getStats.Output.Ok.Body` enum, which represent the body of the 200 response: + +// Generated by Swift OpenAPI Generator 0.2.x. +public enum Body { +case json(Components.Schemas.StatItems) +case plainText(Swift.String) +case binary(Foundation.Data) +} + +Notice that the plain text contents are generated as `Swift.String`, and the raw bytes contents as `Foundation.Data`. Both require buffering, which prevents continuously streaming the contents. + +// Proposed to be generated by Swift OpenAPI Generator 0.3.x. +public enum Body { +case json(Components.Schemas.StatItems) +case plainText(OpenAPIRuntime.HTTPBody) // <<< changed +case binary(OpenAPIRuntime.HTTPBody) // <<< changed +} + +To address this shortcoming for unstructured payloads, we propose to use the `HTTPBody` type as the container for both the text and raw bytes contents. + +Note that `HTTPBody` contains convenience initializers and helper methods that make working with it easy for the simple cases, some examples follow: + +- Creating a body from string: + +let body = HTTPBody("Hello, world!") + +- Consuming the full body and converting it to string: + +let string = try await String(collecting: body, upTo: 2 * 1024 * 1024) + +- Creating a body from data: + +let data: Foundation.Data = ... +let body = HTTPBody(data) + +- Consuming the full body and converting it to data: + +let data: Foundation.Data = try await Data(collecting: body, upTo: 2 * 1024 * 1024) + +Note that the request body example in `postStats` with its equivalent generated `Body` enum works the same way as the `getStats` response body above, so it’s not repeated here. + +### Detailed design + +What follows is the generated API interface of the `HTTPBody` type. + +A reminder that the exact spelling of integrating `HTTPBody` into the transport and middleware protocols is included in the SOAR-0005 proposal instead, so it is omitted from here. + +/// A body of an HTTP request or HTTP response. +/// +/// Under the hood, it represents an async sequence of byte chunks. +/// +/// ## Creating a body from a buffer +/// There are convenience initializers to create a body from common types, such + +/// +/// Create an empty body: +/// ```swift +/// let body = HTTPBody() +/// ``` +/// +/// Create a body from a byte chunk: +/// ```swift + +/// let body = HTTPBody(bytes) +/// ``` +/// +/// Create a body from `Foundation.Data`: +/// ```swift +/// let data: Foundation.Data = ... +/// let body = HTTPBody(data) +/// ``` +/// +/// Create a body from a string: +/// ```swift +/// let body = HTTPBody("Hello, world!") +/// ``` +/// +/// ## Creating a body from an async sequence +/// The body type also supports initialization from an async sequence. +/// +/// ```swift +/// let producingSequence = ... // an AsyncSequence +/// let length: HTTPBody.Length = .known(1024) // or .unknown +/// let body = HTTPBody( +/// producingSequence, +/// length: length, +/// iterationBehavior: .single // or .multiple +/// ) +/// ``` +/// +/// In addition to the async sequence, also provide the total body length, +/// if known (this can be sent in the `content-length` header), and whether +/// the sequence is safe to be iterated multiple times, or can only be iterated +/// once. +/// +/// Sequences that can be iterated multiple times work better when an HTTP +/// request needs to be retried, or if a redirect is encountered. +/// +/// In addition to providing the async sequence, you can also produce the body +/// using an `AsyncStream` or `AsyncThrowingStream`: +/// +/// ```swift +/// let body = HTTPBody( + +/// continuation.yield([72, 69]) +/// continuation.yield([76, 76, 79]) +/// continuation.finish() +/// }), +/// length: .known(5) +/// ) +/// ``` +/// +/// ## Consuming a body as an async sequence + +/// as its element type, so it can be consumed in a streaming fashion, without +/// ever buffering the whole body in your process. +/// +/// For example, to get another sequence that contains only the size of each +/// chunk, and print each size, use: +/// +/// ```swift +/// let chunkSizes = body.map { chunk in chunk.count } +/// for try await chunkSize in chunkSizes { +/// print("Chunk size: \(chunkSize)") +/// } +/// ``` +/// +/// ## Consuming a body as a buffer +/// If you need to collect the whole body before processing it, use one of +/// the convenience initializers on the target types that take an `HTTPBody`. +/// + +/// +/// ```swift +/// let buffer = try await ArraySlice(collecting: body, upTo: 2 * 1024 * 1024) +/// ``` +/// +/// The body type provides more variants of the collecting initializer on commonly +/// used buffers, such as: +/// - `Foundation.Data` +/// - `Swift.String` +/// + +/// memory, in the example above we provide 2 MB. If more bytes are available, +/// the method throws the `TooManyBytesError` to stop the process running out +/// of memory. While discouraged, you can provide `upTo: .max` to +/// read all the available bytes, without a limit. +public final class HTTPBody : @unchecked Sendable { + +/// The underlying byte chunk type. + +public enum IterationBehavior : Sendable { + +/// The input sequence can only be iterated once. +/// +/// If a retry or a redirect is encountered, fail the call with +/// a descriptive error. +case single + +/// The input sequence can be iterated multiple times. +/// +/// Supports retries and redirects, as a new iterator is created each +/// time. +case multiple +} + +/// The body's iteration behavior, which controls how many times +/// the input sequence can be iterated. +public let iterationBehavior: IterationBehavior + +/// Describes the total length of the body, if known. +public enum Length : Sendable { + +/// Total length not known yet. +case unknown + +/// Total length is known. +case known(Int) +} + +/// The total length of the body, if known. +public let length: Length + +/// Creates a new body. +/// - Parameters: +/// - sequence: The input sequence providing the byte chunks. +/// - length: The total length of the body, in other words the accumulated +/// length of all the byte chunks. +/// - iterationBehavior: The sequence's iteration behavior, which +/// indicates whether the sequence can be iterated multiple times. +@usableFromInline +internal init(_ sequence: BodySequence, length: Length, iterationBehavior: IterationBehavior) + +/// Creates a new body with the provided sequence of byte chunks. +/// - Parameters: +/// - byteChunks: A sequence of byte chunks. +/// - length: The total length of the body. +/// - iterationBehavior: The iteration behavior of the sequence, which +/// indicates whether it can be iterated multiple times. +@usableFromInline + +extension HTTPBody : Equatable { + +extension HTTPBody : Hashable { +public func hash(into hasher: inout Hasher) +} + +extension HTTPBody { + +/// Creates a new empty body. +@inlinable public convenience init() + +/// Creates a new body with the provided byte chunk. +/// - Parameters: +/// - bytes: A byte chunk. +/// - length: The total length of the body. +@inlinable public convenience init(_ bytes: ByteChunk, length: Length) + +/// Creates a new body with the provided byte chunk. +/// - Parameter bytes: A byte chunk. +@inlinable public convenience init(_ bytes: ByteChunk) + +/// Creates a new body with the provided byte sequence. +/// - Parameters: +/// - bytes: A byte chunk. +/// - length: The total length of the body. +/// - iterationBehavior: The iteration behavior of the sequence, which +/// indicates whether it can be iterated multiple times. + +/// Creates a new body with the provided byte collection. +/// - Parameters: +/// - bytes: A byte chunk. +/// - length: The total length of the body. + +/// Creates a new body with the provided byte collection. +/// - Parameters: +/// - bytes: A byte chunk. + +/// Creates a new body with the provided async throwing stream. +/// - Parameters: +/// - stream: An async throwing stream that provides the byte chunks. +/// - length: The total length of the body. + +/// Creates a new body with the provided async stream. +/// - Parameters: +/// - stream: An async stream that provides the byte chunks. +/// - length: The total length of the body. + +/// Creates a new body with the provided async sequence. +/// - Parameters: +/// - sequence: An async sequence that provides the byte chunks. +/// - length: The total lenght of the body. +/// - iterationBehavior: The iteration behavior of the sequence, which +/// indicates whether it can be iterated multiple times. + +/// - Parameters: +/// - sequence: An async sequence that provides the byte chunks. +/// - length: The total lenght of the body. +/// - iterationBehavior: The iteration behavior of the sequence, which +/// indicates whether it can be iterated multiple times. + +extension HTTPBody : AsyncSequence { + +/// The type of element produced by this asynchronous sequence. +public typealias Element = ByteChunk + +/// The type of asynchronous iterator that produces elements of this +/// asynchronous sequence. +public typealias AsyncIterator = Iterator + +/// Creates the asynchronous iterator that produces elements of this +/// asynchronous sequence. +/// +/// - Returns: An instance of the `AsyncIterator` type used to produce +/// elements of the asynchronous sequence. + +extension HTTPBody.ByteChunk where Element == UInt8 { + +/// Creates a byte chunk by accumulating the full body in-memory into a single buffer +/// up to the provided maximum number of bytes and returning it. +/// - Parameters: +/// - body: The HTTP body to collect. +/// - maxBytes: The maximum number of bytes this method is allowed +/// to accumulate in memory before it throws an error. +/// - Throws: `TooManyBytesError` if the body contains more +/// than `maxBytes`. +public init(collecting body: HTTPBody, upTo maxBytes: Int) async throws +} + +extension Array where Element == UInt8 { + +/// Creates a byte array by accumulating the full body in-memory into a single buffer +/// up to the provided maximum number of bytes and returning it. +/// - Parameters: +/// - body: The HTTP body to collect. +/// - maxBytes: The maximum number of bytes this method is allowed +/// to accumulate in memory before it throws an error. +/// - Throws: `TooManyBytesError` if the body contains more +/// than `maxBytes`. +public init(collecting body: HTTPBody, upTo maxBytes: Int) async throws +} + +/// Creates a new body with the provided string encoded as UTF-8 bytes. +/// - Parameters: +/// - string: A string to encode as bytes. +/// - length: The total length of the body. +@inlinable public convenience init(_ string: some StringProtocol & Sendable, length: Length) + +/// Creates a new body with the provided string encoded as UTF-8 bytes. +/// - Parameters: +/// - string: A string to encode as bytes. +@inlinable public convenience init(_ string: some StringProtocol & Sendable) + +/// Creates a new body with the provided async throwing stream of strings. +/// - Parameters: +/// - stream: An async throwing stream that provides the string chunks. +/// - length: The total length of the body. + +/// Creates a new body with the provided async stream of strings. +/// - Parameters: +/// - stream: An async stream that provides the string chunks. +/// - length: The total length of the body. + +/// Creates a new body with the provided async sequence of string chunks. +/// - Parameters: +/// - sequence: An async sequence that provides the string chunks. +/// - length: The total lenght of the body. +/// - iterationBehavior: The iteration behavior of the sequence, which +/// indicates whether it can be iterated multiple times. + +/// Creates a byte chunk compatible with the `HTTPBody` type from the provided string. +/// - Parameter string: The string to encode. +@inlinable internal init(_ string: some StringProtocol & Sendable) +} + +extension String { + +/// Creates a string by accumulating the full body in-memory into a single buffer up to +/// the provided maximum number of bytes, converting it to string using the provided encoding. +/// - Parameters: +/// - body: The HTTP body to collect. +/// - maxBytes: The maximum number of bytes this method is allowed +/// to accumulate in memory before it throws an error. +/// - Throws: `TooManyBytesError` if the body contains more +/// than `maxBytes`. +public init(collecting body: HTTPBody, upTo maxBytes: Int) async throws +} + +extension HTTPBody : ExpressibleByStringLiteral { + +/// Creates an instance initialized to the given string value. +/// +/// - Parameter value: The value of the new instance. +public convenience init(stringLiteral value: String) +} + +/// Creates a new body from the provided array of bytes. +/// - Parameter bytes: An array of bytes. +@inlinable public convenience init(_ bytes: [UInt8]) +} + +extension HTTPBody : ExpressibleByArrayLiteral { + +/// The type of the elements of an array literal. +public typealias ArrayLiteralElement = UInt8 + +/// Creates an instance initialized with the given elements. +public convenience init(arrayLiteral elements: UInt8...) +} + +/// Creates a new body from the provided data chunk. +/// - Parameter data: A single data chunk. +public convenience init(data: Data) +} + +extension Data { + +/// Creates a string by accumulating the full body in-memory into a single buffer up to +/// the provided maximum number of bytes and converting it to `Data`. +/// - Parameters: +/// - body: The HTTP body to collect. +/// - maxBytes: The maximum number of bytes this method is allowed +/// to accumulate in memory before it throws an error. +/// - Throws: `TooManyBytesError` if the body contains more +/// than `maxBytes`. +public init(collecting body: HTTPBody, upTo maxBytes: Int) async throws +} + +/// An async iterator of both input async sequences and of the body itself. +public struct Iterator : AsyncIteratorProtocol { + +/// The element byte chunk type. +public typealias Element = HTTPBody.ByteChunk + +/// Creates a new type-erased iterator from the provided iterator. +/// - Parameter iterator: The iterator to type-erase. +@usableFromInline + +/// sequence if there is no next element. +/// +/// - Returns: The next element, if it exists, or `nil` to signal the end of +/// the sequence. + +} +} + +/// A type-erased async sequence that wraps input sequences. +@usableFromInline +internal struct BodySequence : AsyncSequence, Sendable { + +/// The type of the type-erased iterator. +@usableFromInline +internal typealias AsyncIterator = HTTPBody.Iterator + +/// The byte chunk element type. +@usableFromInline +internal typealias Element = ByteChunk + +/// A closure that produces a new iterator. +@usableFromInline + +/// Creates a new sequence. +/// - Parameter sequence: The input sequence to type-erase. + +/// asynchronous sequence. +/// +/// - Returns: An instance of the `AsyncIterator` type used to produce +/// elements of the asynchronous sequence. +@usableFromInline + +/// An async sequence wrapper for a sync sequence. +@usableFromInline + +/// The type of the iterator. +@usableFromInline +internal typealias AsyncIterator = Iterator + +/// An iterator type that wraps a sync sequence iterator. +@usableFromInline +internal struct Iterator : AsyncIteratorProtocol { + +/// The underlying sync sequence iterator. + +/// sequence if there is no next element. +/// +/// - Returns: The next element, if it exists, or `nil` to signal the end of +/// the sequence. +@usableFromInline + +/// The underlying sync sequence. +@usableFromInline +internal let sequence: Bytes + +/// Creates a new async sequence with the provided sync sequence. +/// - Parameter sequence: The sync sequence to wrap. +@inlinable internal init(sequence: Bytes) + +/// Creates the asynchronous iterator that produces elements of this +/// asynchronous sequence. +/// +/// - Returns: An instance of the `AsyncIterator` type used to produce +/// elements of the asynchronous sequence. +@usableFromInline + +/// An empty async sequence. +@usableFromInline +internal struct EmptySequence : AsyncSequence, Sendable { + +/// The type of the empty iterator. +@usableFromInline +internal typealias AsyncIterator = EmptyIterator + +/// An async iterator of an empty sequence. +@usableFromInline +internal struct EmptyIterator : AsyncIteratorProtocol { + +/// Asynchronously advances to the next element and returns it, or ends the +/// sequence if there is no next element. +/// +/// - Returns: The next element, if it exists, or `nil` to signal the end of +/// the sequence. +@usableFromInline + +/// Creates a new empty async sequence. +@inlinable internal init() + +### API stability + +This proposal, together with SOAR-0005, proposes a holistic change to the transport and middleware protocols and currency types, including the bodies. The change is not backwards compatible and will require the authors of transports and middlewares to explicitly update their packages, once they upgrade to the latest version. + +In addition, users of the generated code that have any content types of unstructured payloads included in their OpenAPI document, such as `text/plain` and `application/octet-stream` will have to update their code to handle the switch from `Swift.String` and `Foundation.Data`, respectively, to `OpenAPIRuntime.HTTPBody`. Special care has been taken to provide convenience initializers and helper methods to convert to and from `Swift.String` and `Foundation.Data` for an easier migration and integration with the rest of the ecosystem. + +#### Async writer in the API + +At the moment of writing this proposal, `AsyncSequence` seems like the most appropriate representation for HTTP bodies, which can be thought of as “byte chunks over time”, both on the request and response side of both the client and the server. + +However, there are discussions in the Swift ecosystem about also providing a lower level abstraction using the “async writer” pattern, which might be even more appropriate especially for client request and server response body production. + +While the use of `AsyncSequence` is believed to be the most pragmatic solution at the time of writing, if the async writer pattern becomes part of the Swift standard library and embraced by HTTP clients and servers, we should consider also providing that lower level extension point at both the transport/middleware and the generated layer. + +This should be possible to do without requiring an API-breaking change, similar to how async middlewares were previously introduced to projects that supported synchronous and EventLoopFuture-based asynchronous middlewares. + +#### Native JSON Sequence support + +There might be room for introducing a concrete async sequence type with a concrete `Codable` element type, to allow representing a stream of structured payloads. + +One example of a content type describing such is `application/json-seq` from RFC 7464, which is being considered to be officially mentioned in the OpenAPI specification. + +Such a feature is out of scope of this proposal, and would likely be API breaking (unless introduced behind a feature flag or a configuration option), unless a newer version of OpenAPI specification does mention it, at which point we could only generate a more type-safe type for documents with the newer OpenAPI version. + +Today, any such work is left to the adopter to build on top of the proposed API. We verified with a prototype that it is possible to build a higher level pub/sub system with Codable “Event” types on top of the proposed API. + +#### Body generic over its chunk + +We originally started with the approach of `HTTPBody` being generic over its chunk type, mainly for more convenient support of both raw byte and string-based bodies. However, once we realized that strings bytes cannot be split at arbitrary locations, it became clear that only the user can safely split and concatenate encoded strings. So we only provide the lower level, the raw byte chunks, and the user can transform them into strings after taking care of doing so at the appropriate byte boundaries. + +### Acknowledgements + +Special thanks to David Nadoba and Franz Busch who contributed ideas and helped refine this proposal through thoughtful discussions. + +### Appendix 1: Stats service OpenAPI document + +openapi: 3.0.3 +info: +title: Stats service +version: 1.0.0 +paths: +/stats: +get: +operationId: getStats +responses: +'200': +description: A successful response. +content: +application/json: +schema: +$ref: '#/components/schemas/StatItems' +text/plain: {} +application/octet-stream: {} +post: +operationId: postStats +requestBody: +required: true +content: +application/json: +schema: +$ref: '#/components/schemas/StatItems' +text/plain: {} +application/octet-stream: {} +responses: +'202': +description: Successfully submitted. +components: +schemas: +StatItem: +type: object +properties: +name: +type: string +value: +type: integer +required: [name, value] +StatItems: +type: array +items: +$ref: '#/components/schemas/StatItem' + +## See Also + +SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +- SOAR-0004: Streaming request and response bodies +- Overview +- Introduction +- Motivation +- Proposed solution +- Detailed design +- API stability +- Future directions +- Alternatives considered +- Acknowledgements +- Appendix 1: Stats service OpenAPI document +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-0012 + +- Swift OpenAPI Generator +- Proposals +- SOAR-0012: Generate enums for server variables + +Article + +# SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +## Overview + +- Proposal: SOAR-0012 + +- Author(s): Joshua Asbury + +- Status: **Implemented (1.4.0)** + +- Issue: apple/swift-openapi-generator#628 + +- Implementation: + +- apple/swift-openapi-generator#618 +- Affected components: + +- generator +- Related links: + +- Server variable object +- Versions: + +- v1.0 (2024-09-19): Initial version + +- v1.1 (2024-10-01): + +- Replace the the proposed solution to a purely additive API so it is no longer a breaking change requiring a feature flag + +- Moved previous proposed solution to alternatives considered section titled “Replace generation of `serverN` static functions, behind feature flag” + +- Moved generation of static computed-property `default` on variable enums to future direction + +### Introduction + +Add generator logic to generate Swift enums for server variables that define the ‘enum’ field and use Swift String for server variables that only define the ‘default’ field. + +### Motivation + +The OpenAPI specification for server URL templating defines that fields can define an ‘enum’ field if substitution options should be restricted to a limited set. + +The current implementation of the generator component offer the enum field values via strings that are embedded within the static function implementation and not exposed to the adopter. Relying on the runtime extension `URL.init(validatingOpenAPIServerURL:variables:)` to verify the string provided matches the allowed values. + +Consider the following example + +servers: +- url: +description: Example service deployment. +variables: +environment: +description: Server environment. +default: prod +enum: +- prod +- staging +- dev +version: +default: v1 + +The currently generated code: + +/// Server URLs defined in the OpenAPI document. +internal enum Servers { +/// Server environment. +/// +/// - Parameters: +/// - environment: +/// - version: +internal static func server1( +environment: Swift.String = "prod", +version: Swift.String = "v1" + +try Foundation.URL( +validatingOpenAPIServerURL: "https://{environment}.example.com/api/{version}", +variables: [\ +.init(\ +name: "environment",\ +value: environment,\ +allowedValues: [\ +"prod",\ +"staging",\ +"dev"\ +]\ +),\ +.init(\ +name: "version",\ +value: version\ +)\ +] +) +} +} + +This means the adopter needs to rely on the runtime checks as to whether their supplied string was valid. Additionally if the OpenAPI document were to ever remove an option it could only be discovered at runtime. + +let serverURL = try Servers.server1(environment: "stg") // might be a valid environment, might not + +### Proposed solution + +Server variables that define enum values can instead be generated as Swift enums. Providing important information (including code completion) about allowed values to adopters, and providing compile-time guarantees that a valid variable has been supplied. + +Using the same configuration example, from the motivation section above, the newly generated code would be: + +/// Server URLs defined in the OpenAPI document. +internal enum Servers { +/// Example service deployment. +internal enum Server1 { +/// Server environment. +/// +/// The "environment" variable defined in the OpenAPI document. The default value is ``prod``. +internal enum Environment: Swift.String { +case prod +case staging +case dev +} +/// +/// - Parameters: +/// - environment: Server environment. +/// - version: +internal static func url( +environment: Environment = Environment.prod, +version: Swift.String = "v1" + +try Foundation.URL( +validatingOpenAPIServerURL: "https://{environment}.example.com/api/{version}", +variables: [\ +.init(\ +name: "environment",\ +value: environment.rawValue\ +),\ +.init(\ +name: "version",\ +value: version\ +)\ +] +) +} +} +/// Example service deployment. +/// +/// - Parameters: +/// - environment: Server environment. +/// - version: +@available(*, deprecated, message: "Migrate to the new type-safe API for server URLs.") +internal static func server1( +environment: Swift.String = "prod", +version: Swift.String = "v1" + +This leaves the existing implementation untouched, except for the addition of a deprecation message, and introduces a new type-safe structure that allows the compiler to validate the provided arguments. + +let url = try Servers.Server1.url() // ✅ compiles + +let url = try Servers.Server1.url(environment: .default) // ✅ compiles + +let url = try Servers.Server1.url(environment: .staging) // ✅ compiles + +let url = try Servers.Server1.url(environment: .stg) // ❌ compiler error, 'stg' not defined on the enum + +Later if the OpenAPI document removes an enum value that was previously allowed, the compiler will be able to alert the adopter. + +// some time later "staging" gets removed from OpenAPI document +let url = try Servers.Server1.url(environment: . staging) // ❌ compiler error, 'staging' not defined on the enum + +#### Default only variables + +As seen in the generated code example, variables that do not define an ‘enum’ field will still remain a string (see the ‘version’ variable). + +### Detailed design + +Implementation: + +The implementation of `translateServers(_:)` is modified to generate the relevant namespaces (enums) for each server, deprecate the existing generated functions, and generate a new more type-safe function. A new file `translateServersVariables` has been created to contain implementations of the two generator kinds; enum and string. + +The server namespace contains a newly named `url` static function which serves the same purpose as the `serverN` static functions generated as members of the `Servers` namespace; it has been named `url` to both be more expressive and because the containing namespace already provides the server context. + +The server namespace also lends the purpose of containing the variable enums, should they be required, since servers may declare variables that are named the same but contain different enum values. e.g. + +servers: +- url: +variables: +environment: +default: prod +enum: +- prod +- staging +- url: +variables: +environment: +default: prod +enum: +- prod +- dev + +The above would generate the following (simplified for clarity) output + +enum Servers { +enum Server1 { +enum Environment: String { +// ... +} + +} +enum Server2 { +enum Environment: String { +// ... +} + +} + +Server variables that have names or enum values that are not safe to be used as a Swift identifier will be converted. E.g. + +enum Servers { +enum Server1 { +enum _Protocol: String { +case https +case https +} +enum Port: String { +case _443 = "443" +case _8443 = "8443" +} + +} +} + +#### Deeper into the implementation + +To handle the branching logic of whether a variable will be generated as a string or an enum a new protocol, `TranslatedServerVariable`, defines the common behaviours that may need to occur within each branch. This includes: + +- any required declarations + +- the parameters for the server’s static function + +- the expression for the variable initializer in the static function’s body + +- the parameter description for the static function’s documentation + +There are two concrete implementations of this protocol to handle the two branching paths in logic + +##### \`RawStringTranslatedServerVariable\` + +This concrete implementation will not provide a declaration for generated enum. + +It will define the parameter using `Swift.String` and a default value that is a String representation of the OpenAPI document defined default field. + +The generated initializer expression will match the existing implementation of a variable that does not define an enum field. + +Note: While the feature flag for this proposal is disabled this type is also used to generate the initializer expression to include the enum field as the allowed values parameter. + +##### \`GeneratedEnumTranslatedServerVariable\` + +This concrete implementation will provide an enum declaration which represents the variable’s enum field and a static computed property to access the default. + +The parameter will reference a fully-qualified path to the generated enum declaration and have a default value of the fully qualified path to the static property accessor. + +The initializer expression will never need to provide the allowed values parameter and only needs to provide the `rawValue` of the enum. + +### API stability + +This proposal creates new generated types and modifies the existing generated static functions to include a deprecation, therefore is a non-breaking change for adopters. + +#### Other components + +No API changes are required to other components, though once this proposal is adopted the runtime component _could_ remove the runtime validation of allowed values since the generated code guarantees the `rawValue` is in the document. + +#### Variable enums could have a static computed-property convenience, called \`default\`, generated + +Each server variable enum could generate a static computed-property with the name `default` which returns the case as defined by the OpenAPI document. e.g. + +enum Servers { +enum Variables { +enum Server1 { +enum Environment: Swift.String { +case prod +case staging +case dev +static var `default`: Environment { +return Environment.prod +} +} +} +} + +This would allow the server’s static function to use `default` as the default parameter instead of using a specific case. + +#### Generate all variables as Swift enums + +A previous implementation had generated all variables as a swift enum, even if the ‘enum’ field was not defined in the document. An example + +servers: +- url: +variables: +version: +default: v1 + +Would have been generated as + +/// Server URLs defined in the OpenAPI document. +internal enum Servers { +internal enum Variables { +/// The variables for Server1 defined in the OpenAPI document. +internal enum Server1 { +/// The "version" variable defined in the OpenAPI document. +/// +/// The default value is "v1". +internal enum Version: Swift.String { +case v1 +/// The default variable. +internal static var `default`: Version { +return Version.v1 +} +} +} +} +/// +/// - Parameters: +/// - version: + +try Foundation.URL( +validatingOpenAPIServerURL: "https://example.com/api/{version}", +variables: [\ +.init(\ +name: "version",\ +value: version.rawValue\ +)\ +] +) +} +} + +This approach was reconsidered due to the wording in the OpenAPI specification of both the ‘enum’ and ‘default’ fields. + +This indicates that by providing enum values the options are restricted, whereas a default value is provided when no other value is supplied. + +#### Replace generation of \`serverN\` static functions, behind feature flag + +This approach was considered to be added behind a feature flag as it would introduce breaking changes for adopters that didn’t use default values; it would completely rewrite the static functions to accept enum variables as Swift enums. + +An example of the output, using the same configuration example from the motivation section above, this approach would generate the following code: + +/// Server URLs defined in the OpenAPI document. +internal enum Servers { +/// Server URL variables defined in the OpenAPI document. +internal enum Variables { +/// The variables for Server1 defined in the OpenAPI document. +internal enum Server1 { +/// Server environment. +/// +/// The "environment" variable defined in the OpenAPI document. The default value is "prod". +internal enum Environment: Swift.String { +case prod +case staging +case dev +/// The default variable. +internal static var `default`: Environment { +return Environment.prod +} +} +} +} +/// Example service deployment. +/// +/// - Parameters: +/// - environment: Server environment. +/// - version: +internal static func server1( +environment: Variables.Server1.Environment = Variables.Server1.Environment.default, +version: Swift.String = "v1" + +try Foundation.URL( +validatingOpenAPIServerURL: "https://example.com/api", +variables: [\ +.init(\ +name: "environment",\ +value: environment.rawValue\ +),\ +.init(\ +name: "version",\ +value: version\ +)\ +] +) +} +} + +The variables were scoped within a `Variables` namespace for clarity, and each server had its own namespace to avoid collisions of names between different servers. + +Ultimately this approach was decided against due to lack of discoverability since it would have to be feature flagged. + +## See Also + +SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +- SOAR-0012: Generate enums for server variables +- Overview +- Introduction +- Motivation +- Proposed solution +- Detailed design +- API stability +- Future directions +- Alternatives considered +- See Also + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-0002 + +# An unknown error occurred. + +| +| + +--- + +# https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator/soar-0009 + +- Swift OpenAPI Generator +- Proposals +- SOAR-0009: Type-safe streaming multipart support + +Article + +# SOAR-0009: Type-safe streaming multipart support + +Provide a type-safe streaming API to produce and consume multipart bodies. + +## Overview + +- Proposal: SOAR-0009 + +- Author(s): Honza Dvorsky + +- Status: **Implemented (1.0.0)** + +- Issue: apple/swift-openapi-generator#36 + +- Implementation: apple/swift-openapi-runtime#69, apple/swift-openapi-generator#366 + +- Review: ( review) + +- Affected components: generator, runtime + +- Related links: + +- OpenAPI 3.0.3 specification + +- OpenAPI 3.1.0 specification + +- Swagger.io documentation on multipart support in OpenAPI 3.x + +- RFC 7578: Returning Values from Forms: multipart/form-data + +- RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types +- Versions: + +- v1.0 (2023-11-08): Initial version + +- v1.1 (2023-11-16): Replace the prefix “Randomized” with “Random” in the boundary generator name. + +### Introduction + +Support multipart requests and responses by providing a streaming way to produce and consume type-safe parts. + +### Motivation + +Since its first version, Swift OpenAPI Generator has supported OpenAPI operations that represent the most common HTTP request/response pairs. + +For example, posting JSON data to a server, which can look like this: + +> +> {"objectCatName":"Waffles","photographerId":24} + +< HTTP/1.1 204 No Content + +Or uploading a raw file, such as a photo, to a server: + +> +> ... + +In both of these examples, the HTTP message (a request or a response) has a single content type that describes the format of the body payload. + +However, there are use cases where the client wants to send multiple different payloads, each of a different content type, in a single HTTP message. That’s what the multipart content type is for, and this proposal describes how Swift OpenAPI Generator can add support for it, providing both type safety while retaining a fully streaming API. + +With multipart support, uploading both a JSON object and a raw file to the server in one request could look something like: + +> +> --___MY_BOUNDARY_1234__ +> content-disposition: form-data; name="metadata" +> content-type: application/json +> x-sender-id: zoom123 +> +> {"objectCatName":"Waffles","photographerId":24} +> --___MY_BOUNDARY_1234__ +> content-disposition: form-data; name="contents" +> content-type: image/jpeg +> +> ... +> --___MY_BOUNDARY_1234__-- + +While we’ll discuss the structure of a multipart message in detail below, the TL;DR is: + +- This is still a regular HTTP message, just with a different content type and body. + +- The body uses a _boundary_ string to separate individual _parts_. + +- Each part has its own header fields and body. + +Extra requirements to keep in mind: + +- A multipart message must have at least one part (an empty multipart body is invalid). + +- But, a part can have no headers or an empty body. + +- So, the least you can send is a single part with no headers and no body bytes, but it’d still have the boundary strings around it, making it a valid multipart body consisting of one part. + +### Proposed solution + +As an example, let’s consider a service that allows uploading cat photos together with additional JSON metadata in a single request, as seen in the previous section. + +#### Describing a multipart request in OpenAPI + +Let’s define a `POST` request on the `/photos` path that accepts a `multipart/form-data` body containing 2 parts, one JSON part with the name “metadata”, and another called “contents” that contains the raw JPEG bytes of the cat photo. + +In OpenAPI 3.1.0, the operation could look like this (irrelevant parts were omitted, see the full OpenAPI document in Appendix A): + +paths: +/photos: +post: +requestBody: +required: true +content: +multipart/form-data: +schema: +type: object +properties: +metadata: +$ref: '#/components/schemas/PhotoMetadata' +contents: +type: string +contentEncoding: binary +required: +- metadata +- contents +encoding: +metadata: +headers: +x-sender-id: +schema: +type: string +contents: +contentType: image/jpeg + +In OpenAPI, the schema for the multipart message is defined using JSON Schema, even though the top level schema is never actually serialized as JSON - it only serves as a way to define the individual parts. + +The top level schema is always an object (or an object-ish type, such as allOf or anyOf of objects), and each property describes one part. Top level properties that describe an array schema are interpreted as a way to say that there might be more than one part of the provided name (matching the property name). The `required` property of the schema is used just like in regular JSON Schema – to communicate which properties (in this case, parts) are required and which are optional. + +Finally, a sibling field of the `schema` is called `encoding` and mirrors the `schema` structure. For each part, you can override the content type and add custom header fields for each part. + +#### Generating a multipart request in Swift + +As with other Swift OpenAPI Generator features, the goal of generating code for multipart is to maximize type safety for adopters without compromising their ability to stream HTTP bodies. + +With that in mind, multiple different strategies were considered for how to best represent a multipart body in Swift – for details, see the “Future directions” and “Alternatives considered” sections of this proposal. + +To that end, we propose to represent a multipart body as an _async sequence of type-safe parts_ (spelled as `OpenAPIRuntime.MultipartBody` in this proposal). This is motivated by the fact that multipart bodies can be gigabytes in size and contain hundreds of parts, so any Swift representation that forces buffering immediately prevents advanced use cases. + +In addition to `MultipartBody`, we are proposing a few new public types (`MultipartPart` and `MultipartRawPart`) in the runtime library that are used in the Swift snippets below. The full proposed runtime library API diff can be found in Appendix B, and the details of each type will be discussed in “Detailed design” section. + +Getting + +let response = try await client.uploadPhoto(body: multipartBody) +// ... + +Similarly to `OpenAPIRuntime.HTTPBody`, the `OpenAPIRuntime.MultipartBody` async sequence has several convenience initializers, making it easy to construct both from buffered and streaming sources. + +For a buffered example, just provide an array of the part values, such as: + +.metadata(.init(\ +payload: .init(\ +headers: .init(x_dash_sender_dash_id: "zoom123"),\ +body: .init(objectCatName: "Waffles", photographerId: 24)\ +)\ +)),\ +.contents(.init(\ +payload: .init(\ +body: .init(try Data(contentsOf: URL(fileURLWithPath: "/tmp/waffles-summer-2023.jpg")))\ +),\ +filename: "cat.jpg"\ +))\ +] +let response = try await client.uploadPhoto(body: multipartBody) +// ... + +However, you can also stream the parts and their bodies: + +let (stream, continuation) = AsyncStream.makeStream(of: Operations.uploadPhoto.Input.Body.multipartFormPayload.self) +// Pass `continuation` to another task to start producing parts by calling `continuation.yield(...)` and at the end, `continuation.finish()`. +let response = try await client.uploadPhoto(body: .init(stream)) +// ... + +#### Consuming a multipart body sequence + +When consuming a multipart body sequence, for example as a client consuming a multipart response, or a server consuming a multipart request, you are provided with the multipart body async sequence and are responsible for iterating it to completion. + +Additionally, for received parts that have their own streaming bodies, you _must_ consume those bodies before requesting the next part, as the underlying async sequence never does any buffering for you, so you can’t “skip” any parts or chunks of bytes within a part without explicitly consuming it. + +Consuming a multipart body, where you print the metadata fields, and write the photo to disk, could look something like this: + +for try await part in multipartBody { +switch part { +case .metadata(let metadataPart): +let metadata = metadataPart.payload + +print("Cat name: \(metadata.body.objectCatName)") + +case .contents(let contentsPart): +// Ensure the incoming filepath doesn't try to escape to a parent directory, and so on, before using it. +let fileName = contentsPart.filename ?? "\(UUID().uuidString).jpg" +guard let outputStream = OutputStream(toFileAtPath: "/tmp/received-cat-photos/\(fileName)", shouldAppend: false) else { +// failed to open a stream +} +outputStream.open() +defer { +outputStream.close() +} +// Consume the body before moving to the next part. +for try await chunk in contentsPart.body { +chunk.withUnsafeBufferPointer { _ = outputStream.write($0.baseAddress!, maxLength: $0.count) } +} +case .undocumented(let rawPart): +print("Received an undocumented part with header fields: \(rawPart.headerFields)") +// Consume the body before moving to the next part. + +} +} + +### Detailed design + +This section describes more details of the functionality supporting the kind of examples we saw above. + +#### Different enum case types + +In this section, we enumerate the different enum case types and under what circumstances they are generated. + +- **Scenario A**: Zero or more documented cases and `additionalProperties` is not set - a common default. + +- Also generates an `undocumented` case with an associated type `MultipartRawPart`. + +OpenAPI: + +multipart/form-data: +schema: +type: object +properties: +metadata: +$ref: '#/components/schemas/PhotoMetadata' + +Generated Swift enum members: + +struct metadataPayload { +var body: Components.Schemas.PhotoMetadata +} + +case undocumented(MultipartRawType) + +- **Scenario B**: Zero or more documented cases and `additionalProperties: true`. + +- For each documented case, same as Scenario A. + +- Also generates an `other` case with an associated type `MultipartRawPart`. + +- Note that while similar to `undocumented`, the `other` case uses a different name to communicate the fact that the OpenAPI author deliberately enabled `additionalProperties` and thus any parts with unknown names are expected – so the name “undocumented” would not be appropriate. + +multipart/form-data: +schema: +type: object +properties: +metadata: +$ref: '#/components/schemas/PhotoMetadata' +additionalProperties: true + +case other(MultipartRawType) + +- Also generates an `other` case with an associated type `MultipartDynamicallyNamedPart`. + +- Note that while similar to `MultipartPart`, `MultipartDynamicallyNamedPart` adds a read-write `name` property, because while the part name is statically known when `MultipartPart` is used, that’s not the case when `MultipartDynamicallyNamedPart` is used, thus the extra property into which the part name is written is required. + +- Also, since there is no way to define custom headers in this case, the generic parameter of `MultipartDynamicallyNamedPart` is the body value itself, instead of being nested in an `otherPayload` generated struct like for statically documented parts. + +multipart/form-data: +schema: +type: object +properties: +metadata: +$ref: '#/components/schemas/PhotoMetadata' +additionalProperties: +$ref: '#/components/schemas/OtherInfo' + +- **Scenario D**: Zero or more documented cases and `additionalProperties: false`. + +- No other cases are generated, and the runtime validation logic ensures that no undocumented part is allowed through. + +multipart/form-data: +schema: +type: object +properties: +metadata: +$ref: '#/components/schemas/PhotoMetadata' +additionalProperties: false + +#### Validation + +Since the OpenAPI document can describe some parts as single value properties, and others as array; and some as required, while others as optional, the generator will emit code that enforces these semantics in the internals of the `MultipartBody` sequence. + +The following will be enforced: + +- if a property is a required single value, the sequence fails validation with an error if a part of that name is not seen before the sequence is finished, or if it appears multiple times + +- if a property is an optional single value, the sequence fails validation with an error if a part of that name is seen multiple times + +- if a property is a required array value, the sequence fails validation with an error if a part of that name is not seen at least once + +- if a property is an optional array value, the sequence never fails validation, as any number, from 0 up, are a valid number of occurrences + +- if `additionalProperties` is not specified, the default behavior is to allow undocumented parts through + +- if `additionalProperties: true`, the sequence never fails validation when an undocumented part is encountered + +- if `additionalProperties: false`, the sequence fails validation if an undocumented part is encountered + +This validation is implemented as a private async sequence inserted into the chain with the names of parts that need the specific requirements enforced. This affords the adopter the same amount of type safety as the rest of the generated code, such as `Codable` generated types that parse from JSON. + +Optionality of parts is not reflected as an optional type (`Type?`) here, instead the _absence_ of a part in the async sequence represents it being nil. + +#### Boundary customization + +When sending a multipart message, the sender needs to choose a boundary string (for example, `___MY_BOUNDARY_1234__`) that is used to separate the individual parts. The boundary string must not appear in any of the parts themselves. + +The runtime library comes with two implementations, `ConstantMultipartBoundaryGenerator` and `RandomMultipartBoundaryGenerator`. + +`ConstantMultipartBoundaryGenerator` returns the same boundary every time and is useful for testing and in cases where stable output for stable inputs is desired, for example for caching. `RandomMultipartBoundaryGenerator` uses a constant prefix and appends a random suffix made out of `0-9` digits, returning a different output every time. + +By default, the updated `Configuration` uses the random boundary generator, but the adopter can switch to the constant one, or provide a completely custom implementation. + +#### The OpenAPI Encoding object + +In the initial example (again listed below), we saw how to use the `encoding` object in the OpenAPI document to: + +1. explicitly specify the content type `image/jpeg` for the `contents` part. + +2. define a custom header field `x-sender-id` for the `metadata` part. + +multipart/form-data: +schema: +type: object +properties: +metadata: +$ref: '#/components/schemas/PhotoMetadata' +contents: +type: string +contentEncoding: binary +required: +- metadata +- contents +encoding: +metadata: +headers: +x-sender-id: +schema: +type: string +contents: +contentType: image/jpeg + +Adopters only need to explicitly specify the content type if the inferred content type doesn’t match what they need. + +The inferred content type uses the following logic, copied from the OpenAPI 3.1.0 specification: + +The generator follows these rules and once a serialization method is chosen, treats the payloads the same way as bodies in regular HTTP requests and responses. + +Custom headers are also optional, so if the default content type is correctly inferred, and the adopter doesn’t need any custom headers, the `encoding` object can be omitted from the OpenAPI document. + +#### Optional multipart request bodies + +While the OpenAPI specification allows a request body to be optional, in multipart the rule is that at least one part must be sent, so a nil or empty multipart sequence is not valid. For that reason, when the generator encounters an optional multipart request body, it will emit a warning diagnostic and treat it as a required one (as we assume that the OpenAPI author just forgot to mark the body as required). + +### API stability + +- Runtime API: + +- All of the runtime API changes are purely additive, so this feature does not require a new API-breaking release of the runtime library. +- Generated API: + +- However, we will stage it into the 0.3.x release behind a feature flag, and enable it in the next API-breaking release of the generator. + +### Future directions + +As this proposal already is of a considerable size and complexity, we chose to defer some additional ideas to future proposals. Those will be considered based on feedback from real-world usage of this initial multipart support. + +#### A buffered representation of the full body + +While we believe that offering a fully streaming representation of the multipart parts, and even their individual bodies, is the correct choice at the lowest type-safe layer, some adopters might not take advantage of the streaming nature, and the streaming API might not be ergonomic for them. This might especially be the case when the individual parts are small and were sent in one data chunk from the client anyway, for example from an HTML form in a web browser. + +For such adopters, it might make sense to generate an extra convenience type that has a property for each part, and is only delivered to the receiver once all the data has come in. This type would represent optional values as optional properties, and array values as array properties, closer to the generated `Codable` types. + +This change should be purely additive, and would build on top of the multipart async sequence form this proposal. The generated code should simply accumulate all the parts, and then assign them to the properties on this generated type. + +The feature needs to be balanced against the cost of generating another variant of the code we will already generate with this proposal, and it’s also important not to let it overshadow the streaming variant, as then even adopters who would benefit from streaming might not use it, because they might see the buffered type first and not realize multipart streaming is even supported. + +#### Other multipart subtypes + +This proposal focuses on the `multipart/form-data` type, but there are other multipart variants, such as `multipart/alternative` and `multipart/mixed`. It might make sense to add support for these in the future as well. + +### Alternatives considered + +This proposal is a product of several months of thinking about how to best represent multipart in a type-safe, yet streaming, way. Below is an incomplete list of other ideas that were considered, and the reasons we ultimately chose not to pursue them. + +#### No action - keep multipart as a raw body + +The first obvious alternative to adding type-safe support for multipart is to _not_ do it. It has the advantage of preserving the streaming nature, and doesn’t force buffering on users. + +However, better support for multipart has been the top adopter request in recent months, so it seemed clear that the status quo is not sufficient. On the wire, multipart is not trivial to serialize and parse correctly, so asking every adopter to reimplement it seemed suboptimal. + +It also doesn’t align with our goal of maximizing type-safety without compromising on streaming. + +#### Only surfacing raw parts + +The next step on the spectrum is to provide a sequence of parsed raw parts (in other words, the header fields and the raw body), without generating custom code for each part. + +It has the advantage of taking care of the trickiest part of multipart, and that’s the serialization and parsing of parts between boundaries, and it retains streaming. However, it drops on the floor the static information the adopter authored in their OpenAPI document, and seems inconsistent with the rest of the generated code, where we do generate custom code for each schema. + +However, in a scenario where we didn’t have time to implement the more advanced solution, this still would have been a decent quality-of-life improvement. + +#### No runtime validation of part semantics + +Even with type-safe generated parts, as proposed, we could avoid doing runtime validation of the part semantics defined in the OpenAPI document, such as that a required part did actually arrive before the multipart body sequence was completed, and that only parts described by an array schema are allowed to appear more than once. + +While skipping this work would simplify implementation a little bit, it would again weaken the trust that adopters can have in the type-safe code truly verifying as much information as possible from the OpenAPI document. + +The verification happens in a private async sequence that’s inserted into the middle of the serialization/parsing chain, so is mostly implemented in the runtime library, not really affecting the complexity of the generator. + +#### Buffered representation at the bottom layer + +We also could have generated custom code for the schema describing the parts, and only offer a non-streaming, buffered representation of the multipart body. However, that seems to go against the work we did in 0.3.0 to transition the transport and middleware layers to fully streaming mode, unlocking high-performance use cases, and would arbitrarily treat multipart as somewhat different to all the other content types. + +While this is what most other code generators for OpenAPI do today, we didn’t just want to follow precedent. We wanted to show how the power of Swift’s type safety combined with modern concurrency features allows library authors not to be forced to choose between type-safety and performance – Swift gives us both. It certainly did require more work and several iterations, especially around the layering of `MultipartRawPart`, `MultipartDynamicallyNamedPart`, and `MultipartPart`, but we believe what we propose here is ready for wider feedback. + +### Feedback + +We’re looking for feedback from: + +- potential adopters of multipart, both on client and server, both with buffering and streaming use cases + +- contributors of Swift OpenAPI Generator, about how this fits into the rest of the tool + +And we’re especially looking for ideas on the naming of the new types, especially: + +- `MultipartRawType` + +- `MultipartDynamicallyNamedPart` + +- `MultipartPart` + +- `MultipartBody` + +That said, any and all feedback is appreciated, especially the kind that can help newcomers pick up the API and easily work with multipart. + +### Acknowledgements + +A special thanks to Si Beaumont for helping refine this proposal with thoughtful feedback. + +### Appendix A: Example OpenAPI document with multipart bodies + +openapi: '3.1.0' +info: +title: Cat photo service +version: 2.0.0 +paths: +/photos: +post: +operationId: uploadPhoto +description: Uploads the provided photo with metadata to the server. +requestBody: +required: true +content: +multipart/form-data: +schema: +type: object +description: The individual parts of the photo upload. +properties: +metadata: +$ref: '#/components/schemas/PhotoMetadata' +description: Extra information about the uploaded photo. +contents: +type: string +contentEncoding: binary +description: The raw contents of the photo. +required: +- metadata +- contents +encoding: +metadata: +# No need to explicitly specify `contents: application/json` because +# it's inferred from the schema itself. +headers: +x-sender-id: +# Note that this serves as an example of a part header. +# But conventionally, you'd include this property in the metadata JSON instead. +description: The identifier of the device sending the photo. +schema: +type: string +contents: +contentType: image/jpeg +responses: +'204': +description: Successfully uploaded the file. +components: +schemas: +PhotoMetadata: +type: object +description: Extra information about a photo. +properties: +objectCatName: +type: string +description: The name of the cat that's in the photo. +photographerId: +type: integer +description: The identifier of the photographer. +required: +- objectCatName +OtherInfo: +type: object +description: Other information. + +### Appendix B: Runtime library API changes + +1. New API to represent a boundary generator. + +/// A generator of a new boundary string used by multipart messages to separate parts. +public protocol MultipartBoundaryGenerator : Sendable { + +/// Generates a boundary string for a multipart message. +/// - Returns: A boundary string. + +} + +extension MultipartBoundaryGenerator where Self == OpenAPIRuntime.ConstantMultipartBoundaryGenerator { + +/// A generator that always returns the same boundary string. +public static var constant: OpenAPIRuntime.ConstantMultipartBoundaryGenerator { get } +} + +extension MultipartBoundaryGenerator where Self == OpenAPIRuntime.RandomMultipartBoundaryGenerator { + +/// A generator that produces a random boundary every time. +public static var random: OpenAPIRuntime.RandomMultipartBoundaryGenerator { get } +} + +/// A generator that always returns the same constant boundary string. +public struct ConstantMultipartBoundaryGenerator : OpenAPIRuntime.MultipartBoundaryGenerator { + +/// The boundary string to return. +public let boundary: String + +/// Creates a new generator. +/// - Parameter boundary: The boundary string to return every time. +public init(boundary: String = "__X_SWIFT_OPENAPI_GENERATOR_BOUNDARY__") + +/// A generator that returns a boundary containg a constant prefix and a randomized suffix. +public struct RandomMultipartBoundaryGenerator : OpenAPIRuntime.MultipartBoundaryGenerator { + +/// The constant prefix of each boundary. +public let boundaryPrefix: String + +/// The length, in bytes, of the randomized boundary suffix. +public let randomNumberSuffixLength: Int + +/// Create a new generator. +/// - Parameters: +/// - boundaryPrefix: The constant prefix of each boundary. +/// - randomNumberSuffixLength: The length, in bytes, of the randomized boundary suffix. +public init(boundaryPrefix: String = "__X_SWIFT_OPENAPI_", randomNumberSuffixLength: Int = 20) + +2. Customizing the boundary generator on `Configuration`. + +The below property and initializer added to the Configuration struct, while the existing initializer is deprecated. + +/// A set of configuration values used by the generated client and server types. +/* public struct Configuration : Sendable { */ + +/// The generator to use when creating mutlipart bodies. +public var multipartBoundaryGenerator: OpenAPIRuntime.MultipartBoundaryGenerator + +/// Creates a new configuration with the specified values. +/// +/// - Parameters: +/// - dateTranscoder: The transcoder to use when converting between date +/// and string values. +/// - multipartBoundaryGenerator: The generator to use when creating mutlipart bodies. +public init(dateTranscoder: OpenAPIRuntime.DateTranscoder = .iso8601, multipartBoundaryGenerator: OpenAPIRuntime.MultipartBoundaryGenerator = .random) + +/// Creates a new configuration with the specified values. +/// +/// - Parameter dateTranscoder: The transcoder to use when converting between date +/// and string values. +@available(*, deprecated, renamed: "init(dateTranscoder:multipartBoundaryGenerator:)") +public init(dateTranscoder: OpenAPIRuntime.DateTranscoder) +/* } */ + +3. New multipart part types. + +/// A raw multipart part containing the header fields and the body stream. +public struct MultipartRawPart : Sendable, Hashable { + +/// The header fields contained in this part, such as `content-disposition`. +public var headerFields: HTTPTypes.HTTPFields + +/// The body stream of this part. +public var body: OpenAPIRuntime.HTTPBody + +/// Creates a new part. +/// - Parameters: +/// - headerFields: The header fields contained in this part, such as `content-disposition`. +/// - body: The body stream of this part. +public init(headerFields: HTTPTypes.HTTPFields, body: OpenAPIRuntime.HTTPBody) +} + +extension MultipartRawPart { + +/// Creates a new raw part by injecting the provided name and filename into +/// the `content-disposition` header field. +/// - Parameters: +/// - name: The name of the part. +/// - filename: The file name of the part. +/// - headerFields: The header fields of the part. +/// - body: The body stream of the part. +public init(name: String?, filename: String? = nil, headerFields: HTTPTypes.HTTPFields, body: OpenAPIRuntime.HTTPBody) + +/// The name of the part stored in the `content-disposition` header field. +public var name: String? + +/// The file name of the part stored in the `content-disposition` header field. +public var filename: String? +} + +/// A wrapper of a typed part with a statically known name that adds other +/// dynamic `content-disposition` parameter values, such as `filename`. + +/// The underlying typed part payload, which has a statically known part name. +public var payload: Payload + +/// A file name parameter provided in the `content-disposition` part header field. +public var filename: String? + +/// Creates a new wrapper. +/// - Parameters: +/// - payload: The underlying typed part payload, which has a statically known part name. +/// - filename: A file name parameter provided in the `content-disposition` part header field. +public init(payload: Payload, filename: String? = nil) +} + +/// A wrapper of a typed part without a statically known name that adds +/// dynamic `content-disposition` parameter values, such as `name` and `filename`. + +/// A name parameter provided in the `content-disposition` part header field. +public var name: String? + +/// Creates a new wrapper. +/// - Parameters: +/// - payload: The underlying typed part payload, which has a statically known part name. +/// - filename: A file name parameter provided in the `content-disposition` part header field. +/// - name: A name parameter provided in the `content-disposition` part header field. +public init(payload: Payload, filename: String? = nil, name: String? = nil) +} + +4. New multipart body async sequence type. + +/// The body of multipart requests and responses. +/// +/// `MultipartBody` represents an async sequence of multipart parts of a specific type. +/// +/// The `Part` generic type parameter is usually a generated enum representing +/// the different values documented for this multipart body. +/// +/// ## Creating a body from buffered parts +/// +/// Create a body from an array of values of type `Part`: +/// +/// ```swift + +/// .myCaseA(...),\ +/// .myCaseB(...),\ +/// ] +/// ``` +/// +/// ## Creating a body from an async sequence of parts +/// +/// The body type also supports initialization from an async sequence. +/// +/// ```swift +/// let producingSequence = ... // an AsyncSequence of MyPartType +/// let body = MultipartBody( +/// producingSequence, +/// iterationBehavior: .single // or .multiple +/// ) +/// ``` +/// +/// In addition to the async sequence, also specify whether the sequence is safe +/// to be iterated multiple times, or can only be iterated once. +/// +/// Sequences that can be iterated multiple times work better when an HTTP +/// request needs to be retried, or if a redirect is encountered. +/// +/// In addition to providing the async sequence, you can also produce the body +/// using an `AsyncStream` or `AsyncThrowingStream`: +/// +/// ```swift +/// let (stream, continuation) = AsyncStream.makeStream(of: MyPartType.self) +/// // Pass the continuation to another task that produces the parts asynchronously. +/// Task { +/// continuation.yield(.myCaseA(...)) +/// // ... later +/// continuation.yield(.myCaseB(...)) +/// continuation.finish() +/// } +/// let body = MultipartBody(stream) +/// ``` +/// +/// ## Consuming a body as an async sequence +/// +/// The `MultipartBody` type conforms to `AsyncSequence` and uses a generic element type, +/// so it can be consumed in a streaming fashion, without ever buffering the whole body +/// in your process. +/// +/// ```swift + +/// for try await part in multipartBody { +/// switch part { +/// case .myCaseA(let myCaseAValue): +/// // Handle myCaseAValue. +/// case .myCaseB(let myCaseBValue): +/// // Handle myCaseBValue, which is a raw type with a streaming part body. +/// // +/// // Option 1: Process the part body bytes in chunks. +/// for try await bodyChunk in myCaseBValue.body { +/// // Handle bodyChunk. +/// } +/// // Option 2: Accumulate the body into a byte array. +/// // (For other convenience initializers, check out ``HTTPBody``. +/// let fullPartBody = try await UInt8 +/// // ... +/// } +/// } +/// ``` +/// +/// Multipart parts of different names can arrive in any order, and the order is not significant. +/// +/// Consuming the multipart body should be resilient to parts of different names being reordered. +/// +/// However, multiple parts of the same name, if allowed by the OpenAPI document by defining it as an array, +/// should be treated as an ordered array of values, and those cannot be reordered without changing +/// the message's meaning. +/// + +/// have their bodies fully consumed before the multipart body sequence is asked for +/// the next part. The multipart body sequence does not buffer internally, and since +/// the parts and their bodies arrive in a single stream of bytes, you cannot move on +/// to the next part until the current one is consumed. + +/// The iteration behavior, which controls how many times the input sequence can be iterated. +public let iterationBehavior: OpenAPIRuntime.IterationBehavior +} + +extension MultipartBody : Equatable { + +extension MultipartBody : Hashable { +public func hash(into hasher: inout Hasher) +} + +extension MultipartBody { + +/// Creates a new sequence with the provided async sequence of parts. +/// - Parameters: +/// - sequence: An async sequence that provides the parts. +/// - iterationBehavior: The iteration behavior of the sequence, which indicates whether it +/// can be iterated multiple times. + +/// Creates a new sequence with the provided collection of parts. +/// - Parameter elements: A collection of parts. + +/// Creates a new sequence with the provided async throwing stream. +/// - Parameter stream: An async throwing stream that provides the parts. + +/// Creates a new sequence with the provided async stream. +/// - Parameter stream: An async stream that provides the parts. + +extension MultipartBody : ExpressibleByArrayLiteral { + +extension MultipartBody : AsyncSequence { +public typealias Element = Part + +extension MultipartBody { +public struct Iterator : AsyncIteratorProtocol { + +5. Move `HTTPBody.IterationBehavior` to the top of the module, as `OpenAPIRuntime.IterationBehavior`. + +It is then used by `MultipartBody` as well as `HTTPBody`. + +A deprecated compatibility typealias is added to `HTTPBody` to retain source stability, but it’ll be removed on the next API break. + +## See Also + +SOAR-NNNN: Feature name + +Feature abstract – a one sentence summary. + +SOAR-0001: Improved mapping of identifiers + +Improved mapping of OpenAPI identifiers to Swift identifiers. + +SOAR-0002: Improved naming of content types + +Improved naming of content types to Swift identifiers. + +SOAR-0003: Type-safe Accept headers + +Generate a dedicated Accept header enum for each operation. + +SOAR-0004: Streaming request and response bodies + +Represent HTTP request and response bodies as a stream of bytes. + +SOAR-0005: Adopting the Swift HTTP Types package + +Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in the transport and middleware protocols. + +SOAR-0007: Shorthand APIs for operation inputs and outputs + +Generating additional API to simplify providing operation inputs and handling operation outputs. + +SOAR-0008: OpenAPI document filtering + +Filtering the OpenAPI document for just the required parts prior to generating. + +SOAR-0010: Support for JSON Lines, JSON Sequence, and Server-sent Events + +Introduce streaming encoders and decoders for JSON Lines, JSON Sequence, and Server-sent Events for as a convenience API. + +SOAR-0011: Improved Error Handling + +Improve error handling by adding the ability for mapping application errors to HTTP responses. + +SOAR-0012: Generate enums for server variables + +Introduce generator logic to generate Swift enums for server variables that define the ‘enum’ field. + +SOAR-0013: Idiomatic naming strategy + +Introduce an alternative naming strategy for more idiomatic Swift identifiers, including a way to provide custom name overrides. + +SOAR-0014: Support Type Overrides + +Allow using user-defined types instead of generated ones + +- SOAR-0009: Type-safe streaming multipart support +- Overview +- Introduction +- Motivation +- Proposed solution +- Detailed design +- API stability +- Future directions +- Alternatives considered +- Feedback +- Acknowledgements +- Appendix A: Example OpenAPI document with multipart bodies +- Appendix B: Runtime library API changes +- See Also + +| +| + +--- + diff --git a/.claude/docs/https_-swiftpackageindex.com-brightdigit-SyndiKit-0.6.1-documentation-syndikit.md b/.claude/docs/https_-swiftpackageindex.com-brightdigit-SyndiKit-0.6.1-documentation-syndikit.md new file mode 100644 index 00000000..1a0a1c1d --- /dev/null +++ b/.claude/docs/https_-swiftpackageindex.com-brightdigit-SyndiKit-0.6.1-documentation-syndikit.md @@ -0,0 +1,488 @@ + + +# https://swiftpackageindex.com/brightdigit/SyndiKit/0.6.1/documentation/syndikit + +Framework + +# SyndiKit + +Swift Package for Decoding RSS Feeds. + +## Overview + +Built on top of XMLCoder, **SyndiKit** provides models and utilities for decoding RSS feeds of various formats and extensions. + +### Features + +- Import of RSS 2.0, Atom, and JSONFeed formats + +- Extensions for various formats such as: + +- iTunes-compatabile podcasts + +- YouTube channels + +- WordPress export data +- User-friendly errors + +- Abstractions for format-agnostic parsing + +### Requirements + +**Apple Platforms** + +- Xcode 13.3 or later + +- Swift 5.5.2 or later + +- iOS 15.4 / watchOS 8.5 / tvOS 15.4 / macOS 12.3 or later deployment targets + +**Linux** + +- Ubuntu 18.04 or later + +### Installation + +Swift Package Manager is Apple’s decentralized dependency manager to integrate libraries to your Swift projects. It is now fully integrated with Xcode 11. + +To integrate **SyndiKit** into your project using SPM, specify it in your Package.swift file: + +let package = Package( +... +dependencies: [\ +.package(url: "https://github.com/brightdigit/SyndiKit", from: "0.3.0")\ +], +targets: [\ +.target(\ +name: "YourTarget",\ +dependencies: ["SyndiKit", ...]),\ +...\ +] +) + +If this is for an Xcode project simply import the Github repository at: + +### Decoding Your First Feed + +You can get started decoding your feed by creating your first `SynDecoder`. Once you’ve created you decoder you can decode using `decode(_:)`: + +let decoder = SynDecoder() +let empowerAppsData = Data(contentsOf: "empowerapps-show.xml")! +let empowerAppsRSSFeed = try decoder.decode(empowerAppsData) + +### Working with Abstractions + +Rather than working directly with the various formats, **SyndiKit** abstracts many of the common properties of the various formats. This enables developers to be agnostic regarding the specific format. + +let decoder = SynDecoder() + +// decoding a RSS 2.0 feed +let empowerAppsData = Data(contentsOf: "empowerapps-show.xml")! +let empowerAppsRSSFeed = try decoder.decode(empowerAppsData) +print(empowerAppsRSSFeed.title) // Prints "Empower Apps" + +// decoding a Atom feed from YouTube +let kiloLocoData = Data(contentsOf: "kilo.youtube.xml")! +let kiloLocoAtomFeed = try decoder.decode(kiloLocoData) +print(kiloLocoAtomFeed.title) // Prints "Kilo Loco" + +For a mapping of properties: + +| Feedable | RSS 2.0 `channel` | Atom `AtomFeed` | JSONFeed `JSONFeed` | +| --- | --- | --- | --- | +| `title` | `title` | `title` | `title` | +| `siteURL` | `link` | `siteURL` | `title` | +| `summary` | `description` | `summary` | `homePageUrl` | +| `updated` | `lastBuildDate` | `pubDate` or `published` | `nil` | +| `authors` | `author` | `authors` | `author` | +| `copyright` | `copyright` | `nil` | `nil` | +| `image` | `url` | `links`.`first` | `nil` | +| `children` | `items` | `entries` | `items` | + +### Specifying Formats + +If you wish to access properties of specific formats, you can attempt to cast the objects to see if they match: + +let empowerAppsRSSFeed = try decoder.decode(empowerAppsData) +if let rssFeed = empowerAppsRSSFeed as? RSSFeed { +print(rssFeed.channel.title) // Prints "Empower Apps" +} + +let kiloLocoAtomFeed = try decoder.decode(kiloLocoData) +if let atomFeed = kiloLocoAtomFeed as? AtomFeed { +print(atomFeed.title) // Prints "Kilo Loco" +} + +### Accessing Extensions + +In addition to supporting RSS, Atom, and JSONFeed, **SyndiKit** also supports various RSS extensions for specific media including: YouTube, iTunes, and WordPress. + +You can access these properties via their specific feed formats or via the `media` property on `Entryable`. + +let empowerAppsRSSFeed = try decoder.decode(empowerAppsData) +switch empowerAppsRSSFeed.children.last?.media { +case .podcast(let podcast): +print(podcast.title) // print "WWDC 2018 - What Does It Mean For Businesses?" +default: +print("Not a Podcast! 🤷‍♂️") +} + +let kiloLocoAtomFeed = try decoder.decode(kiloLocoData) +switch kiloLocoAtomFeed.children.last?.media { +case .video(.youtube(let youtube): +print(youtube.videoID) // print "SBJFl-3wqx8" +print(youtube.channelID) // print "UCv75sKQFFIenWHrprnrR9aA" +default: +print("Not a Youtube Video! 🤷‍♂️") +} + +| `MediaContent` | Actual Property | +| --- | --- | +| `title` | `itunesTitle` | +| `episode` | `itunesEpisode` | +| `author` | `itunesAuthor` | +| `subtitle` | `itunesSubtitle` | +| `summary` | `itunesSummary` | +| `explicit` | `itunesExplicit` | +| `duration` | `itunesDuration` | +| `image` | `itunesImage` | +| `channelID` | `youtubeChannelID` | +| `videoID` | `youtubeVideoID` | + +## Topics + +### Decoding an RSS Feed + +`class SynDecoder` + +An object that decodes instances of Feedable from JSON or XML objects. + +### Basic Feeds + +The basic types used by **SyndiKit** for traversing the feed in abstract manner without needing the specific properties from the various feed formats. + +`protocol Feedable` + +Basic abstract Feed + +`protocol Entryable` + +Basic Feed type with abstract properties. + +`struct Author` + +a person, corporation, or similar entity. + +`protocol EntryCategory` + +Abstract category type. + +`enum EntryID` + +An identifier for an entry based on the RSS guid. + +### Abstract Media Types + +Abstract media types which can be pulled for the various `Entryable` objects. + +`protocol PodcastEpisode` + +A protocol representing a podcast episode. + +`enum MediaContent` + +A struct representing an Atom category. Represents different types of media content. + +`enum Video` + +A struct representing an Atom category. An enumeration representing different types of videos. + +### XML Primitive Types + +In many cases, types are encoded in non-matching types but are intended to strong-typed for various formats. These primitives are setup to make XML decoding easier while retaining their intended strong-type. + +`struct CData` + +#CDATA XML element. + +`struct XMLStringInt` + +XML Element which contains a `String` parsable into a `Integer`. + +`struct ListString` + +A struct representing a list of values that can be encoded/decoded as a comma-separated string. Useful for handling feed formats where multiple values are stored in a single string field. + +### Syndication Updates + +Properties from the RDF Site Summary Syndication Module concerning how often it is updated a feed is updated. + +`struct SyndicationUpdate` + +Properties concerning how often it is updated a feed is updated. + +`enum SyndicationUpdatePeriod` + +Describes the period over which the channel format is updated. + +`typealias SyndicationUpdateFrequency` + +Used to describe the frequency of updates in relation to the update period. A positive integer indicates how many times in that period the channel is updated. + +### Atom Feed Format + +Specific properties related to the Atom format. + +`struct AtomFeed` + +A struct representing an Atom category. An XML-based Web content and metadata syndication format. + +`struct AtomEntry` + +A struct representing an entry in an Atom feed. + +`struct AtomCategory` + +A struct representing an Atom category. A struct representing an Atom category. + +`struct AtomMedia` + +A struct representing an Atom category. Media structure which enables content publishers and bloggers to syndicate multimedia content such as TV and video clips, movies, images and audio. + +`struct AtomMediaGroup` + +A group of media elements in an Atom feed. + +`struct Link` + +A struct representing a link with a URL and optional relationship type. Used in various feed formats to represent hyperlinks with metadata. + +### JSON Feed Format + +Specific properties related to the JSON Feed format. + +`struct JSONFeed` + +A struct representing an Atom category. A struct representing a JSON feed. + +`struct JSONItem` + +A struct representing an Atom category. A struct representing an item in JSON format. + +### OPML Feed Formate + +`struct OPML` + +A struct representing an OPML (Outline Processor Markup Language) document. OPML is an XML format for outlines that can be used to exchange subscription lists between feed readers. It consists of a version, head section with metadata, and body section with outline elements. + +`enum OutlineType` + +### RSS Feed Format + +Specific properties related to the RSS Feed format. + +`struct RSSFeed` + +A struct representing an Atom category. RSS is a Web content syndication format. + +`struct RSSChannel` + +A struct representing an Atom category. A struct representing information about the channel (metadata) and its contents. + +`struct RSSImage` + +Represents a GIF, JPEG, or PNG image. + +`struct RSSItem` + +A struct representing an RSS item/entry. RSS items contain the individual pieces of content within an RSS feed, including title, link, description, publication date, and various media attachments. + +`struct RSSItemCategory` + +A struct representing an Atom category. A struct representing a category for an RSS item. + +`struct Enclosure` + +A struct representing an enclosure for a resource. + +### Podcast Extensions + +Specific properties related to . + +`struct PodcastPerson` + +A struct representing a person associated with a podcast. + +`struct PodcastSeason` + +A struct representing a season of a podcast. + +`struct PodcastChapters` + +A struct representing chapters of a podcast. + +`struct PodcastLocation` + +A struct representing the location of a podcast. + +`struct PodcastSoundbite` + +A struct representing a soundbite from a podcast. + +`struct PodcastTranscript` + +A struct representing a podcast transcript. + +`struct PodcastFunding` + +A struct representing funding information for a podcast. + +`struct PodcastLocked` + +A struct representing a locked podcast. + +### WordPress Extensions + +Specific extension properties provided by WordPress. + +`enum WordPressElements` + +A namespace for WordPress related elements. + +`struct WordPressPost` + +A struct representing a WordPress post. + +`typealias WPTag` + +A typealias for `WordPressElements.Tag` + +`typealias WPCategory` + +A typealias for `WordPressElements.Category` + +`typealias WPPostMeta` + +A typealias for `WordPressElements.PostMeta`. + +`enum WordPressError` + +An error type representing a missing field in a WordPress post. + +### YouTube Extensions + +Specific type abstracting the id properties a YouTube RSS Feed. + +`protocol YouTubeID` + +A struct representing an Atom category. A protocol abstracting the ID properties of a YouTube RSS Feed. + +### iTunes Extensions + +Specific extension properties provided by iTunes regarding mostly podcasts and their episodes. + +`typealias iTunesImage` + +A type alias for iTunes image links. + +`struct iTunesOwner` + +A struct representing an Atom category. A struct representing the owner of an iTunes account. + +`typealias iTunesEpisode` + +A struct representing an Atom category. A type alias for an iTunes episode. + +`struct iTunesDuration` + +A struct representing the duration of an iTunes track. + +### Site Directories + +Types related to the format used by the . + +`protocol SiteDirectory` + +A protocol for site directories. + +`struct SiteCollectionDirectory` + +A directory of site collections. + +`protocol SiteDirectoryBuilder` + +A protocol for building site directories. + +`struct CategoryDescriptor` + +A struct representing an Atom category. A descriptor for a category. + +`struct CategoryLanguage` + +A struct representing an Atom category. A struct representing a category in a specific language. + +`struct Site` + +A struct representing a website. + +`struct SiteCategory` + +A struct representing an Atom category. A struct representing a site category. + +`struct SiteCollectionDirectoryBuilder` + +A builder for creating a site collection directory. + +`struct SiteLanguage` + +A struct representing an Atom category. A struct representing a site language. + +`struct SiteLanguageCategory` + +A struct representing an Atom category. A struct representing a category of site languages. + +`struct SiteLanguageContent` + +A struct representing an Atom category. A struct representing the content of a site in a specific language. + +`typealias SiteCategoryType` + +A type alias representing a site category. + +`typealias SiteCollection` + +A collection of site language content. + +`typealias SiteLanguageType` + +A type representing the language of a website. + +`typealias SiteStub` + +A type alias for `SiteLanguageCategory.Site`. + +- SyndiKit +- Overview +- Features +- Requirements +- Installation +- Decoding Your First Feed +- Working with Abstractions +- Specifying Formats +- Accessing Extensions +- License +- Topics + +| +| + +--- + diff --git a/.claude/docs/mobileasset-wiki.md b/.claude/docs/mobileasset-wiki.md new file mode 100644 index 00000000..a64decdb --- /dev/null +++ b/.claude/docs/mobileasset-wiki.md @@ -0,0 +1,182 @@ +# MobileAsset Framework + +Source: TheAppleWiki - https://theapplewiki.com/wiki/MobileAsset + +> This page is a work in progress + +Apple's operating systems have a framework called **MobileAsset** +used to download and update system data, independently of OS updates. + +For example, the timezone database and the keyboard autocorrect language models +are updated silently in the background and don't need an OS update. +High-quality speech synthesizer voices for Siri and accessibility features +are downloaded on demand when a language is selected, +rather than being included with the OS, +since they are large and most people only need one or two languages. +OTA updates to iOS itself and firmware for Apple accessories are also mobile assets. + +## Asset types + +Assets are grouped using an *asset type* string in reverse-domain format, +starting with `com.apple.MobileAsset`, +such as `com.apple.MobileAsset.TimeZoneUpdate`. +There are currently more than a hundred asset types known. + +There may be multiple *assets* for each asset type. +For example, the asset type for AirTag firmware +has a single asset with the latest version of the firmware, +but the asset type for Siri voices has hundreds of assets, +for the different voice languages, qualities, and compatible OS versions. + +## Servers + +There are two server systems from which asset metadata is retrieved. +"Mesu" uses static plist files in a simple CDN, +and the newer "Pallas" uses POST requests to a dynamic server. +Some assets are only in mesu, some are only in pallas, +some are actively updated in both, +and some are present in both but mesu doesn't get updated anymore +(still there only for compatibility with older operating systems). +Apple seems to be moving to Pallas for new asset types. + +Both servers only provide the list of available assets +and their metadata, not the content. +The metadata includes a URL to the actual asset file, +which is hosted on `updates.cdn-apple.com` +(or `appldnld.apple.com` for some very old stuff). + +### Mesu + +The original asset server is `mesu.apple.com`. +It's a file server (probably Amazon S3 with a CDN) which serves XML plists, +containing the metadata for all the assets with a given asset type. +For example, every Siri voice for every language is listed in the same file, +and every iOS OTA update for every device is in the same file. + +For iOS, these XML plists are downloaded from `mesu.apple.com/assets/{type}/{type}.xml`, +where `{type}` is the asset type, with dots replaced with underscores. +Other operating systems use `mesu.apple.com/assets/{os}/{type}/{type}.xml`, +where `{os}` is one of: `audio`, `watch`, `tv`, `macos`, `visionos`. +Some old visionOS assets are under "xros" instead. + +Example: +`https://mesu.apple.com/assets/macos/com_apple_MobileAsset_TimeZoneUpdate/com_apple_MobileAsset_TimeZoneUpdate.xml` + +They are simply static files; +no special user agent, request headers or query parameters are required, +and cache headers like ETag, Last-Modified and If-Modified-Since work as expected. + +In the past, when iOS OTA updates used mesu, +there were also other directories like "iOS12DeveloperBeta" +in place of the {os} to serve OTAs of iOS betas. +This is not used anymore on newer iOS versions, +since OTA software updates (both beta and release) use Pallas exclusively. +The only known remaining exception is beta firmware for AirPods, +which are in `AirPods2022Seed/`. + +The plist files in mesu have a dictionary containing these keys: +* `AssetType` (string): The dot-separated asset type string. Not always present. +* `Signature` (data): RSA signature of the asset metadata. +* `Certificate` (data): X.509 certificate used to verify the signature. +* `SigningKey` (string): Always "`AssetManifestSigning`". +* `FormatVersion` (integer): Always "1" (but not always present). +* `Assets` (array of dict): The list of assets. See below for details on the content of each dict. + +There are three additional plists +in the mesu server that are not MobileAssets, +as their content is completely different: +* `macos/com_apple_macOSIPSW/com_apple_macOSIPSW.xml` +* `bridgeos/com_apple_bridgeOSIPSW/com_apple_bridgeOSIPSW.xml` +* `visionos/com_apple_visionOSIPSW/com_apple_visionOSIPSW.xml` + +They contain URLs for .ipsw files for the latest version of +macOS (Apple Silicon), bridgeOS (T2 firmware) and visionOS. + +### Pallas + +The newer system is codenamed Pallas. +It runs in `gdmf.apple.com` +(the meaning of "gdmf" is unknown). +To get assets, you do a POST request sending JSON, +and get back a signed "JSON Web Token" (JWT) as response. + +An example minimal request: +```json +{ + "ClientVersion": 2, + "AssetAudience": "0c88076f-c292-4dad-95e7-304db9d29d34", + "AssetType": "com.apple.MobileAsset.TimeZoneUpdate" +} +``` + +Unlike mesu, with pallas the OS can make more specific requests, +such as sending the OS version number +and only getting assets compatible with that version. +Or in the case of OS OTA updates, +getting updates only for the specific hardware device, +and deltas with the current version as prerequisite. + +## Asset metadata + +The XML plists from mesu and the JSON responses from pallas both have +an `"Assets"` key with an array of dictionaries. +Each dictionary in the array describes a downloadable asset file. +The content of these dictionaries can vary depending on asset type, +but it's the same schema for Mesu and Pallas. + +Some asset types (currently) have no assets. +This is represented with a dummy entry in the array: +```json +"Assets": [ + { + "__Empty": "Empty" + } +] +``` + +Strangely, `com.apple.MobileAsset.DeviceCheck` in mesu +is missing the `Assets` key altogether. + +Some dictionary keys are common to every asset +(even though they may not be always present), +and others are specific to certain asset types. +The common keys are: +* `__BaseURL` (string): The prefix of the URL that the asset file can be downloaded from. Always present. +* `__RelativePath` (string): The path to download the asset file from, relative to the BaseURL. Always present. +* `_DownloadSize` (integer): Size of the file to download, in bytes. Always present. +* `_UnarchivedSize` (integer): How much space this asset takes once the archive is extracted. Always present. +* `_Measurement` (data): SHA-1 hash of the asset file to download. Always present. This is a <data> element in mesu plists, and a base64 string in pallas JSON responses. +* `_MeasurementAlgorithm` (string): Hashing algorithm used in `_Measurement`. Always present, always set to "SHA-1". It's unknown if the code even supports other algorithms. +* `_CompressionAlgorithm` (string): Outer format of the asset file. Always "zip" in Mesu assets, can also be "aea", "AppleArchive", or "AppleEncryptedArchive" in some Pallas assets. Always present. +* `_IsZipStreamable` (bool): Exact meaning unknown; either `true` or missing. Seems to be `true` on every `zip`- and `aea`-format asset, except old ones hosted in the `appldnld` server. +* `_MasteredVersion` (string): Some version number. Present in every mesu asset, except some with asset type `SoftwareUpdate`, and some newer "auto assets" (`_IsMAAutoAsset==true`). +* `_CompatibilityVersion` (integer): A version number increased when the content of the asset changes in an incompatible way; newer versions of the OS start using assets with a newer content version while older OS versions keep using the old assets. +* `__CanUseLocalCacheServer` (bool): Presumably, whether this asset is eligible for Content Caching. It seems to be either true or missing. + +The full URL to download an asset file is `__BaseURL + __RelativePath`. +The reason why it's split into two is that `__RelativePath` +can also be requested from a local caching server. + +Most asset types have extra keys specific to their own purposes, +sometimes *a lot* of extra keys. + +## Key Insights for CloudKit Schema + +1. **MESU is NOT a historical database** - It only contains the current signed release +2. **Three special IPSW plists** that are NOT MobileAssets: + - macOS: `mesu.apple.com/assets/macos/com_apple_macOSIPSW/com_apple_macOSIPSW.xml` + - bridgeOS: `mesu.apple.com/assets/bridgeos/com_apple_bridgeOSIPSW/com_apple_bridgeOSIPSW.xml` + - visionOS: `mesu.apple.com/assets/visionos/com_apple_visionOSIPSW/com_apple_visionOSIPSW.xml` +3. **MESU structure**: Simple static XML files, no authentication required +4. **Hash algorithm**: MESU only provides SHA-1, not SHA-256 +5. **Download URLs**: All hosted on `updates.cdn-apple.com` +6. **Beta releases**: No longer in MESU for iOS (moved to Pallas), unknown for macOS + +## Relevance to MistKit Project + +For the Bushel CloudKit schema: +- Use MESU as a **freshness detector** for new releases only +- Don't rely on MESU for historical data (it doesn't have any) +- Primary source should be ipsw.me API (via IPSWDownloads package) +- MESU only provides SHA-1, need ipsw.me for SHA-256 +- MESU won't have beta releases - need Mr. Macintosh for those diff --git a/.claude/docs/protocol-extraction-continuation.md b/.claude/docs/protocol-extraction-continuation.md new file mode 100644 index 00000000..bf6679ae --- /dev/null +++ b/.claude/docs/protocol-extraction-continuation.md @@ -0,0 +1,559 @@ +# MistKit Protocol Extraction - Continuation Guide + +## Current State (As of this session) + +### ✅ Completed Work + +#### Phase 1: Critical Build Fixes +- ✅ Added missing `processLookupRecordsResponse` method +- ✅ Complete boolean support in FieldValue system +- ✅ All 157 tests passing +- ✅ Build successful + +#### Phase 2: API Consolidation +- ✅ Deprecated `CloudKitService+RecordModification.swift` methods +- ✅ Enhanced `CloudKitService+WriteOperations.swift` with optional `recordName` +- ✅ Clear migration path established + +#### Phase 3: Simple Cleanup +- ✅ Deleted `Examples/MistDemo` directory +- ✅ Linting verified (only pre-existing style warnings) + +### 🔄 Remaining Work (Phase 3 continuation) + +The major work item remaining is **extracting Bushel's protocol-oriented patterns into MistKit core**. This is a 6-8 hour task that will significantly improve the developer experience. + +--- + +## Quick Verification Commands + +Before starting, verify the current state: + +```bash +cd /Users/leo/Documents/Projects/MistKit + +# Should build cleanly +swift build + +# Should show 157/157 tests passing +swift test + +# Should show current branch +git branch --show-current +# Expected: blog-post-examples-code-celestra + +# Verify Bushel example exists +ls Examples/Bushel/Sources/Bushel/Protocols/ +# Should show: CloudKitRecord.swift, RecordManaging.swift, etc. + +# Verify MistDemo was deleted +ls Examples/ +# Should show only: Bushel, Celestra (no MistDemo) +``` + +--- + +## Remaining Tasks Breakdown + +### Task 1: Extract CloudKitRecord Protocol (2-3 hours) + +**Source:** `Examples/Bushel/Sources/Bushel/Protocols/CloudKitRecord.swift` + +**Destination:** `Sources/MistKit/Protocols/CloudKitRecord.swift` + +**What to extract:** +```swift +public protocol CloudKitRecord: Codable, Sendable { + static var cloudKitRecordType: String { get } + var recordName: String { get } + func toCloudKitFields() -> [String: FieldValue] + static func from(recordInfo: RecordInfo) -> Self? + static func formatForDisplay(_ recordInfo: RecordInfo) -> String +} +``` + +**Steps:** +1. Create `Sources/MistKit/Protocols/` directory +2. Copy `CloudKitRecord.swift` from Bushel to new location +3. Update imports (should only need `Foundation`) +4. Make protocol `public` (it's currently internal in Bushel) +5. Update file header with MistKit copyright + +**Testing:** +- Build should succeed +- Create a simple test conforming a test struct to `CloudKitRecord` +- Verify protocol requirements are clear + +--- + +### Task 2: Extract RecordManaging Protocol (1-2 hours) + +**Source:** `Examples/Bushel/Sources/Bushel/Protocols/RecordManaging.swift` + +**Destination:** `Sources/MistKit/Protocols/RecordManaging.swift` + +**What to extract:** +```swift +public protocol RecordManaging { + func queryRecords(recordType: String) async throws -> [RecordInfo] + func executeBatchOperations(_ operations: [RecordOperation], recordType: String) async throws +} +``` + +**Key Decision:** The protocol in Bushel throws untyped errors, but MistKit uses `throws(CloudKitError)`. + +**Recommendation:** Use untyped `throws` for protocol flexibility, implementations can be more specific. + +**Steps:** +1. Copy `RecordManaging.swift` to `Sources/MistKit/Protocols/` +2. Make protocol `public` +3. Update to use MistKit's `RecordInfo` and `RecordOperation` types +4. Update file header + +--- + +### Task 3: Add FieldValue Convenience Extensions (2 hours) + +**Source:** `Examples/Bushel/Sources/Bushel/Extensions/FieldValue+Extensions.swift` + +**Destination:** `Sources/MistKit/Extensions/FieldValue+Convenience.swift` + +**What to add:** +```swift +extension FieldValue { + public var stringValue: String? { + if case .string(let value) = self { return value } + return nil + } + + public var intValue: Int? { + if case .int64(let value) = self { return value } + return nil + } + + public var boolValue: Bool? { + if case .boolean(let value) = self { return value } + return nil + } + + public var dateValue: Date? { + if case .date(let value) = self { return value } + return nil + } + + public var referenceValue: Reference? { + if case .reference(let value) = self { return value } + return nil + } + + // Add similar for: doubleValue, bytesValue, locationValue, assetValue, listValue +} +``` + +**Note:** Check if Bushel has these - they're **essential** for the `CloudKitRecord` protocol to work ergonomically. + +**Testing:** +```swift +let fields: [String: FieldValue] = ["name": .string("Test")] +XCTAssertEqual(fields["name"]?.stringValue, "Test") +XCTAssertNil(fields["name"]?.intValue) +``` + +--- + +### Task 4: Add RecordManaging Generic Extensions (3-4 hours) + +**Source:** `Examples/Bushel/Sources/Bushel/Protocols/RecordManaging+Generic.swift` + +**Destination:** `Sources/MistKit/Extensions/RecordManaging+Generic.swift` + +**What to extract:** +```swift +public extension RecordManaging { + func sync(_ records: [T]) async throws { + // Convert records to RecordOperation array + // Call executeBatchOperations + } + + func query(_ type: T.Type) async throws -> [T] { + // Query by cloudKitRecordType + // Convert RecordInfo results using T.from() + } + + func list(_ type: T.Type) async throws -> [RecordInfo] { + // Query and return raw RecordInfo + } +} +``` + +**Critical Implementation Details:** + +1. **Batch Size Handling** (CloudKit limit: 200 operations) +```swift +func sync(_ records: [T]) async throws { + let operations = records.map { record in + RecordOperation.create( + recordType: T.cloudKitRecordType, + recordName: record.recordName, + fields: record.toCloudKitFields() + ) + } + + // Split into chunks of 200 + for chunk in operations.chunked(size: 200) { + try await executeBatchOperations(chunk, recordType: T.cloudKitRecordType) + } +} +``` + +2. **Error Handling** - See Bushel's implementation for handling partial failures + +**Testing:** +- Create test struct conforming to `CloudKitRecord` +- Test sync with < 200 records +- Test sync with > 200 records (batching) +- Test query operations +- Verify type safety + +--- + +### Task 5: Add CloudKitService Conformance (1 hour) + +**Destination:** `Sources/MistKit/Service/CloudKitService+RecordManaging.swift` + +**Implementation:** +```swift +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +extension CloudKitService: RecordManaging { + public func queryRecords(recordType: String) async throws -> [RecordInfo] { + // Use existing queryRecords implementation + try await self.queryRecords( + recordType: recordType, + desiredKeys: nil, + filters: [], + sortDescriptors: [] + ) + } + + public func executeBatchOperations(_ operations: [RecordOperation], recordType: String) async throws { + _ = try await self.modifyRecords(operations) + } +} +``` + +**Testing:** +- Verify CloudKitService now conforms to RecordManaging +- Test that generic extensions work on CloudKitService instances + +--- + +### Task 6: Update Bushel to Import from MistKit (1 hour) + +**Files to update:** +- `Examples/Bushel/Sources/Bushel/Protocols/CloudKitRecord.swift` - DELETE +- `Examples/Bushel/Sources/Bushel/Protocols/RecordManaging.swift` - DELETE +- `Examples/Bushel/Sources/Bushel/Protocols/RecordManaging+Generic.swift` - DELETE +- All Bushel source files that reference these protocols + +**Changes:** +```swift +// OLD: +import protocol Bushel.CloudKitRecord + +// NEW: +import MistKit +// CloudKitRecord is now part of MistKit +``` + +**Verification:** +```bash +cd Examples/Bushel +swift build +# Should build successfully using MistKit's protocols +``` + +--- + +### Task 7: Add Tests for Protocols (2-3 hours) + +**Create:** `Tests/MistKitTests/Protocols/CloudKitRecordTests.swift` + +**Test Coverage:** +```swift +@Test("CloudKitRecord protocol conformance") +func testCloudKitRecordConformance() async throws { + struct TestRecord: CloudKitRecord { + static var cloudKitRecordType: String { "TestRecord" } + var recordName: String + var name: String + var count: Int + + func toCloudKitFields() -> [String: FieldValue] { + ["name": .string(name), "count": .int64(count)] + } + + static func from(recordInfo: RecordInfo) -> TestRecord? { + guard let name = recordInfo.fields["name"]?.stringValue, + let count = recordInfo.fields["count"]?.intValue else { + return nil + } + return TestRecord(recordName: recordInfo.recordName, name: name, count: count) + } + + static func formatForDisplay(_ recordInfo: RecordInfo) -> String { + recordInfo.recordName + } + } + + let record = TestRecord(recordName: "test-1", name: "Test", count: 42) + #expect(record.toCloudKitFields()["name"]?.stringValue == "Test") + #expect(record.toCloudKitFields()["count"]?.intValue == 42) +} + +@Test("RecordManaging generic operations") +func testRecordManagingSync() async throws { + // Test with mock CloudKitService + // Verify sync operations work + // Verify batching works (test with > 200 records) +} +``` + +--- + +### Task 8: Advanced Features (Optional - 2-3 hours) + +**Only if time permits:** + +**Source:** `Examples/Bushel/Sources/Bushel/Protocols/CloudKitRecordCollection.swift` + +This uses Swift 6.0 variadic generics for type-safe multi-record-type operations: + +```swift +protocol CloudKitRecordCollection { + associatedtype RecordTypeSetType: RecordTypeIterating + static var recordTypes: RecordTypeSetType { get } +} +``` + +**Enables:** +```swift +try await service.syncAllRecords(swiftVersions, restoreImages, xcodeVersions) +``` + +**Decision:** This is advanced and can be deferred. The core protocols provide 90% of the value. + +--- + +## Important Context & Decisions + +### Why Extract to Core? + +1. **Reduces Boilerplate:** From ~50 lines to ~20 lines per model +2. **Type Safety:** Compile-time guarantees, eliminates stringly-typed APIs +3. **Production Tested:** Bushel uses this in production syncing 1000+ records +4. **DX Improvement:** This was the #1 request from early users + +### Key Design Principles + +1. **Additive Only:** No breaking changes to existing APIs +2. **Protocol-Oriented:** Enables testing via mocking +3. **Swift 6 Ready:** All types are `Sendable` +4. **Documentation First:** Every public API needs examples + +### Potential Issues to Watch + +1. **Boolean Confusion:** CloudKit uses int64 (0/1) on wire, Swift uses Bool + - Document this clearly in `CloudKitRecord` protocol docs + - FieldValue convenience extensions handle the conversion + +2. **Batch Limits:** CloudKit has 200 operations per request limit + - The generic `sync()` must chunk operations + - See Bushel's implementation for reference + +3. **Error Handling:** Bushel's `RecordInfo.isError` pattern is fragile + - Consider improving error handling in MistKit's implementation + - Maybe add typed errors for batch operations + +--- + +## File Reference Map + +### Source Files in Bushel (to extract from) + +``` +Examples/Bushel/Sources/Bushel/ +├── Protocols/ +│ ├── CloudKitRecord.swift → Extract to MistKit/Protocols/ +│ ├── RecordManaging.swift → Extract to MistKit/Protocols/ +│ ├── RecordManaging+Generic.swift → Extract to MistKit/Extensions/ +│ ├── CloudKitRecordCollection.swift → Optional (advanced) +│ └── RecordTypeSet.swift → Optional (advanced) +├── Extensions/ +│ └── FieldValue+Extensions.swift → Extract to MistKit/Extensions/ +└── Services/ + └── BushelCloudKitService.swift → Reference for conformance example +``` + +### Target Structure in MistKit + +``` +Sources/MistKit/ +├── Protocols/ +│ ├── CloudKitRecord.swift ← NEW +│ ├── RecordManaging.swift ← NEW +│ └── CloudKitRecordCollection.swift ← NEW (optional) +├── Extensions/ +│ ├── FieldValue+Convenience.swift ← NEW +│ ├── RecordManaging+Generic.swift ← NEW +│ └── RecordManaging+RecordCollection.swift ← NEW (optional) +└── Service/ + └── CloudKitService+RecordManaging.swift ← NEW (conformance) + +Tests/MistKitTests/ +└── Protocols/ + ├── CloudKitRecordTests.swift ← NEW + └── RecordManagingTests.swift ← NEW +``` + +--- + +## Example Domain Models to Test With + +Use these as test cases (from Bushel): + +### Simple Model: +```swift +struct SwiftVersionRecord: CloudKitRecord { + static var cloudKitRecordType: String { "SwiftVersion" } + var recordName: String + var version: String + var releaseDate: Date + + // Implement protocol requirements... +} +``` + +### Complex Model with References: +```swift +struct XcodeVersionRecord: CloudKitRecord { + static var cloudKitRecordType: String { "XcodeVersion" } + var recordName: String + var version: String + var buildNumber: String + var releaseDate: Date + var swiftVersion: FieldValue.Reference // Reference to SwiftVersionRecord + var macOSVersion: FieldValue.Reference // Reference to another record + + // Implement protocol requirements... +} +``` + +--- + +## Testing Checklist + +Before considering this work complete: + +- [ ] All protocols compile and are public +- [ ] CloudKitService conforms to RecordManaging +- [ ] Generic extensions work with test models +- [ ] FieldValue convenience extensions work +- [ ] Batch operations handle 200+ record limit +- [ ] Bushel example builds using MistKit protocols +- [ ] New tests added with >90% coverage +- [ ] Documentation updated with examples +- [ ] `swift build` succeeds +- [ ] `swift test` shows all tests passing +- [ ] No new lint violations introduced +- [ ] CHANGELOG.md updated + +--- + +## Useful Commands + +```bash +# Build just MistKit +swift build --target MistKit + +# Build Bushel example +cd Examples/Bushel && swift build + +# Build Celestra example +cd Examples/Celestra && swift build + +# Run specific test suite +swift test --filter CloudKitRecordTests + +# Check protocol conformance +swift build -Xswiftc -debug-constraints 2>&1 | grep "CloudKitRecord" + +# Find protocol usage +rg "CloudKitRecord" Examples/Bushel/Sources/ + +# Generate documentation +swift package generate-documentation +``` + +--- + +## Questions to Consider + +When implementing, think about: + +1. **Should `formatForDisplay` be required or have a default implementation?** + - Recommendation: Provide default that returns `recordName` + +2. **Should RecordManaging support transactions/atomic operations?** + - Recommendation: Add optional `atomic` parameter to `executeBatchOperations` + +3. **How to handle partial failures in batch operations?** + - Recommendation: Return `[Result]` instead of throwing + +4. **Should we provide convenience initializers for common record types?** + - Recommendation: Yes, add `CloudKitRecord.create(fields:)` helper + +--- + +## Estimated Timeline + +| Task | Time | Priority | +|------|------|----------| +| Extract CloudKitRecord | 2-3h | HIGH | +| Extract RecordManaging | 1-2h | HIGH | +| FieldValue convenience extensions | 2h | HIGH | +| RecordManaging generic extensions | 3-4h | HIGH | +| CloudKitService conformance | 1h | HIGH | +| Update Bushel to import from MistKit | 1h | HIGH | +| Add comprehensive tests | 2-3h | HIGH | +| Advanced features (variadic generics) | 2-3h | LOW | +| Documentation & examples | 1-2h | MEDIUM | + +**Total: 13-20 hours** (8-14 hours for core features only) + +--- + +## Success Criteria + +The protocol extraction is complete when: + +1. ✅ A new model conforming to `CloudKitRecord` requires <25 lines of code +2. ✅ Bushel example builds using MistKit's protocols (no local duplicates) +3. ✅ Generic `sync()` and `query()` operations work with any `CloudKitRecord` +4. ✅ All tests pass with >90% coverage on new code +5. ✅ Documentation includes before/after examples showing DX improvement +6. ✅ No breaking changes to existing MistKit APIs + +--- + +## Contact Points + +If stuck, reference these key files: + +- **Error Handling Pattern:** `Sources/MistKit/CloudKitError.swift` +- **Existing Protocol Example:** `Sources/MistKit/TokenManager.swift` +- **Testing Patterns:** `Tests/MistKitTests/Core/FieldValue/FieldValueTests.swift` +- **Bushel Production Usage:** `Examples/Bushel/Sources/Bushel/Commands/SyncCommand.swift` + +--- + +Good luck! This is high-value work that will significantly improve the MistKit developer experience. 🚀 diff --git a/.claude/docs/schema-design-workflow.md b/.claude/docs/schema-design-workflow.md new file mode 100644 index 00000000..dc3799da --- /dev/null +++ b/.claude/docs/schema-design-workflow.md @@ -0,0 +1,560 @@ +# CloudKit Schema Design Workflow with Task Master + +**Purpose:** Integrate CloudKit schema design into Task Master workflows for structured, AI-assisted database development. + +--- + +## Table of Contents + +1. [Including Schema in PRD](#including-schema-in-prd) +2. [Task Decomposition Patterns](#task-decomposition-patterns) +3. [Schema Evolution Workflow](#schema-evolution-workflow) +4. [Task Templates](#task-templates) + +--- + +## Including Schema in PRD + +### PRD Structure for Schema-Driven Projects + +When creating a PRD for a project that uses CloudKit, include a dedicated schema section: + +```markdown +# Product Requirements Document: RSS Reader App (Celestra) + +## Overview +Build an RSS feed reader application with CloudKit backend for sync across devices. + +## Features +1. Subscribe to RSS feeds +2. View feed articles +3. Search articles by title +4. Categorize feeds +5. Sync across devices via CloudKit + +## Data Model + +### Record Types + +**Feed** +- Purpose: Represents an RSS feed subscription +- Fields: + - feedURL (STRING, unique, queryable) - The RSS feed URL + - title (STRING, searchable) - Feed title + - description (STRING) - Feed description + - isActive (BOOLEAN) - Whether feed is active + - usageCount (INT) - Number of times feed was accessed + - lastAttempted (TIMESTAMP) - Last fetch attempt +- Permissions: Public read, authenticated create/write +- Indexes: feedURL (equality + sort), isActive (equality), usageCount (sort), lastAttempted (sort) + +**Article** +- Purpose: Represents an article from an RSS feed +- Fields: + - feed (REFERENCE to Feed) - Parent feed + - title (STRING, searchable) - Article title + - link (STRING) - Article URL + - description (STRING) - Article description + - author (STRING) - Article author + - pubDate (TIMESTAMP) - Publication date + - guid (STRING, unique) - RSS GUID + - contentHash (STRING) - Hash for change detection + - fetchedAt (TIMESTAMP) - When article was fetched + - expiresAt (TIMESTAMP) - Cache expiration +- Permissions: Public read, authenticated create/write +- Indexes: feed (equality), pubDate (sort), guid (equality), contentHash (equality) +- Relationships: Article.feed → Feed.recordID + +**Category** (Future) +- Purpose: Organize feeds into categories +- Fields: TBD +- Relationships: Feed.category → Category.recordID + +## Implementation Notes +- Use CloudKit text-based schema (.ckdb file) +- Commit schema to version control +- Validate schema changes in development environment first +- Follow MistKit patterns for Swift models +``` + +### Key PRD Elements for Schema + +1. **Record Types Section**: List all record types with purposes +2. **Field Specifications**: Field name, type, purpose, and indexing +3. **Relationship Diagram**: Document references between record types +4. **Permission Strategy**: Who can read/create/write each record type +5. **Query Patterns**: Expected queries that drive indexing decisions + +### Example: Adding a Feature with Schema Changes + +```markdown +## Feature: Feed Categorization + +### Requirements +- Users can create categories +- Users can assign feeds to categories +- Users can filter feeds by category +- Categories have icons and colors + +### Schema Changes + +**New Record Type: Category** +- name (STRING, queryable, sortable) - Category name +- description (STRING) - Category description +- iconURL (STRING) - Icon image URL +- colorHex (STRING) - Display color +- sortOrder (INT, queryable, sortable) - Display order + +**Modified Record Type: Feed** +- Add: category (REFERENCE to Category, queryable) - Assigned category + +### Implementation Tasks +1. Design and validate Category record type +2. Add category field to Feed record type +3. Create Swift Category model +4. Update Swift Feed model with category reference +5. Implement category management UI +6. Implement feed filtering by category +7. Add category migration for existing feeds +``` + +--- + +## Task Decomposition Patterns + +### Pattern 1: New Feature with Schema + +When a feature requires new record types: + +``` +Task: Implement Feed Categorization +├── Subtask 1: Schema Design +│ ├── Define Category record type in schema.ckdb +│ ├── Add category field to Feed record type +│ ├── Validate schema syntax +│ └── Import to development environment +├── Subtask 2: Swift Model Generation +│ ├── Create Category struct conforming to Codable +│ ├── Add CloudKit conversion extensions (init, toCKRecord) +│ ├── Update Feed model with category reference +│ └── Add relationship helper methods +├── Subtask 3: Data Access Layer +│ ├── Implement CategoryRepository +│ ├── Add category queries to FeedRepository +│ ├── Add category filtering methods +│ └── Write unit tests +├── Subtask 4: UI Implementation +│ ├── Create category management screen +│ ├── Add category picker to feed edit screen +│ ├── Add category filter to feed list +│ └── Update feed list to show categories +└── Subtask 5: Migration & Testing + ├── Create default categories for existing feeds + ├── Test schema changes with real data + ├── Test sync across devices + └── Update documentation +``` + +### Pattern 2: Schema Evolution + +When modifying an existing schema: + +``` +Task: Add Article Read Tracking +├── Subtask 1: Schema Analysis +│ ├── Review existing Article record type +│ ├── Determine field requirements (isRead, readAt) +│ ├── Decide on indexing strategy +│ └── Document schema changes +├── Subtask 2: Schema Modification +│ ├── Add isRead field (INT64, queryable) +│ ├── Add readAt field (TIMESTAMP, queryable, sortable) +│ ├── Validate schema changes +│ └── Test import to development +├── Subtask 3: Code Updates +│ ├── Update Article Swift model +│ ├── Add read/unread methods +│ ├── Update queries to filter by read status +│ └── Handle null values for existing articles +└── Subtask 4: Testing + ├── Test with existing articles (null handling) + ├── Test marking articles as read + ├── Test filtering read/unread articles + └── Verify sync behavior +``` + +### Pattern 3: Performance Optimization + +When adding indexes to improve query performance: + +``` +Task: Optimize Article Queries +├── Subtask 1: Performance Analysis +│ ├── Identify slow queries +│ ├── Review CloudKit dashboard metrics +│ ├── Analyze current indexes +│ └── Determine missing indexes +├── Subtask 2: Schema Updates +│ ├── Add SORTABLE to author field +│ ├── Add QUERYABLE to contentHash field +│ ├── Validate schema changes +│ └── Import to development +├── Subtask 3: Query Optimization +│ ├── Update queries to use new indexes +│ ├── Add sort descriptors where beneficial +│ ├── Benchmark query performance +│ └── Document query patterns +└── Subtask 4: Monitoring + ├── Deploy to production + ├── Monitor CloudKit metrics + ├── Verify performance improvements + └── Update documentation +``` + +--- + +## Schema Evolution Workflow + +### Workflow: Adding a New Field + +Use this task pattern when adding a field to an existing record type: + +``` +Task ID: 5 - Add lastError Field to Feed +Status: pending +Dependencies: none + +Description: +Add error tracking to Feed record type to display fetch failures to users. + +Subtasks: + 5.1 - Update schema.ckdb with lastError field + - Add "lastError" STRING field to Feed record type + - No indexing needed (display only) + - Validate syntax with cktool + + 5.2 - Import schema to development + - Set CLOUDKIT_ENVIRONMENT=development + - Run cktool import-schema schema.ckdb + - Verify in CloudKit Dashboard + + 5.3 - Update Swift Feed model + - Add var lastError: String? property + - Update init(record:) to read field + - Update toCKRecord() to write field + - Handle nil for existing records + + 5.4 - Update UI to display errors + - Add error message label to feed list + - Add error details to feed edit screen + - Style error messages appropriately + + 5.5 - Test with real data + - Create test feed with error + - Verify error displays correctly + - Test with existing feeds (nil handling) + - Verify sync across devices +``` + +### Workflow: Adding a New Record Type + +Use this task pattern when introducing a new entity: + +``` +Task ID: 8 - Add Category Record Type +Status: pending +Dependencies: none + +Description: +Implement feed categorization by adding Category record type and updating Feed. + +Subtasks: + 8.1 - Design Category schema + - Define fields: name, description, iconURL, colorHex, sortOrder + - Determine indexing (name: queryable+sortable, sortOrder: queryable+sortable) + - Define permissions (standard public pattern) + - Add to schema.ckdb + + 8.2 - Update Feed schema + - Add "category" REFERENCE QUERYABLE field + - Validate complete schema + - Document relationship: Feed.category → Category.recordID + + 8.3 - Import schema to development + - Validate syntax + - Import to development environment + - Verify both record types in dashboard + - Test creating sample records + + 8.4 - Create Swift Category model + - Define Category struct + - Add Codable conformance + - Implement CloudKit conversion (init, toCKRecord) + - Add validation logic + + 8.5 - Update Swift Feed model + - Add var category: CKRecord.Reference? property + - Update CloudKit conversion methods + - Add helper to create category reference + + 8.6 - Implement CategoryRepository + - Create, read, update, delete operations + - List all categories query + - Sort by sortOrder + - Unit tests + + 8.7 - Update FeedRepository + - Add category parameter to queries + - Implement filterByCategory method + - Update feed creation to include category + + 8.8 - Implement UI + - Category management screen (list, create, edit, delete) + - Category picker in feed edit + - Category filter in feed list + - Category icons and colors + + 8.9 - Migration and testing + - Create default category + - Migrate existing feeds to default category + - Test all CRUD operations + - Test sync across devices + - Performance testing +``` + +### Workflow: Index Optimization + +Use this task pattern when adding indexes to existing fields: + +``` +Task ID: 12 - Optimize Article Author Queries +Status: pending +Dependencies: none + +Description: +Add SORTABLE index to author field to enable "sort by author" feature. + +Subtasks: + 12.1 - Analyze current performance + - Measure current query time for author sorting + - Review CloudKit metrics for author queries + - Document baseline performance + + 12.2 - Update schema + - Change "author" from QUERYABLE to QUERYABLE SORTABLE + - Validate schema change + - Import to development + + 12.3 - Update queries + - Add sort descriptor: NSSortDescriptor(key: "author", ascending: true) + - Update ArticleRepository methods + - Add "sort by author" option to UI + + 12.4 - Test and benchmark + - Create test data with varied authors + - Measure new query performance + - Compare to baseline + - Document improvement + - Verify no regressions + + 12.5 - Deploy to production + - Import schema to production + - Monitor CloudKit metrics + - Verify performance improvement + - Update documentation +``` + +--- + +## Task Templates + +### Template: New Record Type + +```markdown +**Task: Add [RecordTypeName] Record Type** + +**Description:** +Implement [RecordTypeName] to support [feature description]. + +**Schema Design:** +- Fields: [list fields with types and indexes] +- Permissions: [permission strategy] +- Relationships: [references to/from other types] + +**Subtasks:** +1. Define schema in schema.ckdb +2. Validate and import to development +3. Create Swift model struct +4. Implement CloudKit conversion extensions +5. Create repository/data access layer +6. Add UI components +7. Write tests +8. Documentation + +**Acceptance Criteria:** +- [ ] Schema imported to development successfully +- [ ] Swift model compiles and tests pass +- [ ] Can create, read, update, delete records +- [ ] Syncs correctly across devices +- [ ] UI displays data correctly +- [ ] Documentation updated +``` + +### Template: Add Field to Existing Type + +```markdown +**Task: Add [fieldName] to [RecordTypeName]** + +**Description:** +Add [fieldName] field to support [feature description]. + +**Field Specification:** +- Name: [fieldName] +- Type: [CloudKit type] +- Indexing: [QUERYABLE/SORTABLE/SEARCHABLE or none] +- Purpose: [why this field is needed] + +**Subtasks:** +1. Add field to schema.ckdb +2. Validate and import to development +3. Update Swift model +4. Handle null values for existing records +5. Update UI if needed +6. Test with existing and new data + +**Acceptance Criteria:** +- [ ] Schema imported successfully +- [ ] Swift model updated +- [ ] Existing records handle null gracefully +- [ ] New records populate field correctly +- [ ] Tests pass +``` + +### Template: Schema Validation + +```markdown +**Task: Validate Schema Changes** + +**Description:** +Ensure all schema modifications are valid before production deployment. + +**Checklist:** +- [ ] Run `cktool validate-schema schema.ckdb` +- [ ] Import to development environment +- [ ] Create test records with new schema +- [ ] Query test records successfully +- [ ] Verify indexes in CloudKit Dashboard +- [ ] Test with existing data (migration) +- [ ] Verify permissions work correctly +- [ ] Check for data loss warnings +- [ ] Document any issues found +- [ ] Get approval for production import +``` + +### Template: Performance Optimization + +```markdown +**Task: Optimize [QueryType] Performance** + +**Description:** +Improve performance of [query description] by adding/modifying indexes. + +**Analysis:** +- Current performance: [baseline metrics] +- Bottleneck: [identified issue] +- Proposed solution: [index changes] + +**Schema Changes:** +- [Field]: Add/modify [index type] + +**Subtasks:** +1. Benchmark current performance +2. Update schema with new indexes +3. Import to development +4. Update query code to use indexes +5. Benchmark new performance +6. Document improvement +7. Deploy to production +8. Monitor metrics + +**Success Metrics:** +- Query time reduced by [target %] +- CloudKit operation count reduced +- User-perceived performance improvement +``` + +--- + +## Integration with Task Master Commands + +### Workflow Commands + +```bash +# 1. Parse PRD with schema requirements +task-master parse-prd .taskmaster/docs/prd.txt + +# 2. Analyze complexity of schema tasks +task-master analyze-complexity --research + +# 3. Expand schema design task into subtasks +task-master expand --id=5 --research + +# 4. Get next schema task to work on +task-master next + +# 5. Update subtask with implementation notes +task-master update-subtask --id=5.1 --prompt="Added lastError field, validated successfully" + +# 6. Mark subtask complete +task-master set-status --id=5.1 --status=done + +# 7. Research best practices +task-master research \ + --query="CloudKit schema indexing best practices for article queries" \ + --save-to=12.1 +``` + +### Example Session + +```bash +# Start working on schema tasks +$ task-master next +📋 Next Available Task: #8 - Add Category Record Type + +# Show task details +$ task-master show 8 +Task 8: Add Category Record Type +Status: pending +Description: Implement feed categorization... +Subtasks: + 8.1 - Design Category schema [pending] + 8.2 - Update Feed schema [pending] + ... + +# Expand subtask 8.1 if needed +$ task-master expand --id=8.1 --research + +# Mark as in progress +$ task-master set-status --id=8.1 --status=in-progress + +# Work on schema file... +# Edit Examples/Celestra/schema.ckdb + +# Log progress +$ task-master update-subtask --id=8.1 --prompt="Defined Category record type with name (queryable sortable), description, iconURL, colorHex, and sortOrder (queryable sortable). Used standard public permissions." + +# Complete subtask +$ task-master set-status --id=8.1 --status=done + +# Move to next subtask +$ task-master set-status --id=8.2 --status=in-progress +``` + +--- + +## See Also + +- **Schema Workflow Guide:** [Examples/Celestra/AI_SCHEMA_WORKFLOW.md](../../Examples/Celestra/AI_SCHEMA_WORKFLOW.md) +- **Quick Reference:** [Examples/SCHEMA_QUICK_REFERENCE.md](../../Examples/SCHEMA_QUICK_REFERENCE.md) +- **Claude Reference:** [.claude/docs/cloudkit-schema-reference.md](../../.claude/docs/cloudkit-schema-reference.md) +- **Task Master Guide:** [.taskmaster/CLAUDE.md](../CLAUDE.md) diff --git a/.claude/docs/sosumi-cloudkit-schema-source.md b/.claude/docs/sosumi-cloudkit-schema-source.md new file mode 100644 index 00000000..97e6dbda --- /dev/null +++ b/.claude/docs/sosumi-cloudkit-schema-source.md @@ -0,0 +1,193 @@ +# CloudKit Schema Language Reference (sosumi.ai) + +**Source:** https://sosumi.ai/documentation/cloudkit/integrating-a-text-based-schema-into-your-workflow +**Original:** https://developer.apple.com/documentation/cloudkit/integrating-a-text-based-schema-into-your-workflow +**Downloaded:** 2025-11-11 + +--- + +# Integrating a Text-Based Schema into Your Workflow + +> Define and update your schema with the CloudKit Schema Language. + +## Overview + +CloudKit's textual representation enables you to simultaneously manage your schema and the application source code that depends on it. The CloudKit command line tools download, verify, and install a schema to your container's sandbox environment, while the CloudKit dashboard promotes a schema to the production environment. + +When publishing a schema, CloudKit attempts to apply changes to the existing schema, if one exists, to convert it to the form specifed in the new schema. If the modifications required would result in potential data loss with respect to the current production schema (like removing a record type or field name that exists already), then the schema isn't valid and CloudKit makes no changes. + +For containers with an existing schema, use the CloudKit command line tools to download the container's schema. Manually constructing your existing schema by hand isn't recommended, as any mistakes may result in your existing sandbox data becoming inaccessible. A good practice is to integrate the schema into your source code repository. + +### Learn the CloudKit Schema Language Grammar + +The grammar for the CloudKit Schema Language contains all the elements to define your schema. Use the grammar to create roles, declare record types and their permissions, as well as specify data types and options for each field in the record. + +``` +create-schema: + DEFINE SCHEMA + [ { create-role | record-type } ";" ] ... + +create-role: + CREATE ROLE %role-name% + +record-type: + RECORD TYPE %type-name% ( + { + [ %field-name% data-type [ field-options [..] ] ] + | + [ GRANT { READ | CREATE | WRITE } [, ... ] TO %role-name% ] + } ["," ... ] + ) + +field-options: + | QUERYABLE + | SORTABLE + | SEARCHABLE + +data-type: + primitive-type | list-type + +primitive-type: + | ASSET + | BYTES + | DOUBLE + | [ ENCRYPTED ] { BYTES | STRING | DOUBLE | INT64 | LOCATION | TIMESTAMP } + | INT64 + | LOCATION + | NUMBER [ PREFERRED AS { INT64 | DOUBLE } ] + | REFERENCE + | STRING + | TIMESTAMP + +list-type: + | LIST "<" primitive-type ">" +``` + +Additional details and guidelines for creating roles, record types, type names, field names, data types and permissions are listed below. + +`QUERYABLE` - Maintains an index to optimize equality lookups on the field. + +`SORTABLE` - Maintains an index optimizing for range searches on the field. + +`SEARCHABLE` - Maintains a text search index on the field. + +Avoid using the `NUMBER` type, which is only for when a field is implicitly added to a schema by a record modification on a sandbox container. If such a field has been implicitly added to a type in your schema, the `PREFERRED AS` syntax allows you to explicitly indicate which type the `NUMBER` should be treated as (`INT64` or `DOUBLE`). Once you assign `NUMBER` as a `PREFERRED AS` type, future definitions must not change that type. + +The grammar uses these conventions: + +- Brackets indicate optional parts. +- Braces and vertical bars indicate that you must choose one alternative. +- An ellipsis indicates that the preceding element can be repeated. +- Names surrounded by percent signs indicate identifiers. + +Identifiers must follow existing CloudKit naming conventions and restrictions. User-defined identifiers must follow these rules: + +- The first character must be one of `a-z` or `A-Z`. +- Subsequent characters must be one of `a-z`, `A-Z`, `0-9`, or `_` (underscore). +- Use double quotes around identifiers to include keywords and reserved words in the syntax definition. For example, to create a type called *grant*, define it as "grant". The reserved words in the CloudKit Schema Language are: grant, preferred, queryable, sortable, and searchable. + +Also, CloudKit reserves identifiers starting with a leading underscore as system-defined identifiers. For example, all record types have an implicitly defined `___recordID` field. Use double quotes when referring to such system fields as well. + +The language allows comments in these forms: + +``` +// Single-line comment +-- Single-line comment +/* +Multi-line comment +*/ +``` + +CloudKit doesn't preserve the comments in your schema when you upload them to CloudKit. Additionally, when you retreive the schema, the order of the elements may differ from the order when the schema was created or updated. + +### Recognize Implicit Fields and Roles + +All record types have the following implicitly defined fields: + +- `"___createTime" TIMESTAMP` +- `"___createdBy" REFERENCE` +- `"___etag" STRING` +- `"___modTime" TIMESTAMP` +- `"___modifiedBy" REFERENCE` +- `"___recordID" REFERENCE` + +These field names are always present within the record time so it's not necessary to explicitly provide them. If you wish to make any of these fields queryable, sortable, or searchable, then your type must explicitly specify the field and the attribute. You can't change the type of these system fields. + +Though CloudKit won't remove the system field names, it doesn't maintain the field options if the field isn't mentioned in later schema updates. For example, if the following is in your schema: + +``` +RECORD TYPE ApplicationType ( + "___createTime" TIMESTAMP QUERYABLE, + name STRING, + ... +) +``` + +Then CloudKit builds an index for efficient searches on the record creation time field. Later, if you modify the schema to no longer mention the creation time field: + +``` +RECORD TYPE ApplicationType ( + name STRING, + ... +) +``` + +Then the `__createTime` field remains on the record type (since it's a required system field), but CloudKit drops the index on the field, and the user query performance may degrade or fail as a result. + +Additionally, all record types have these implicitly defined roles: + +For types that you wish to use in a `PUBLIC` database, include the following grants: + +``` +GRANT WRITE TO "_creator" +GRANT CREATE TO "_icloud" +GRANT READ TO "_world" +``` + +### View an Example Schema + +This sample schema defines a simple company department and employee information. It demonstrates extending the attributes of system fields and the double quotes necessary for referring to system identifiers. + +``` +DEFINE SCHEMA + CREATE ROLE DeptManager; + + RECORD TYPE Department ( + "___createTime" TIMESTAMP QUERYABLE SORTABLE, + "___recordID" REFERENCE QUERYABLE, + name STRING, + address STRING, + phone LIST, + employees LIST, + GRANT WRITE TO "_creator", + GRANT CREATE TO "_icloud", + GRANT READ TO "_world", + GRANT WRITE, CREATE, READ TO DeptManager + ); + + RECORD TYPE Employee ( + "___createTime" TIMESTAMP QUERYABLE SORTABLE, + "___recordID" REFERENCE QUERYABLE, + name STRING, + address STRING, + hiredate TIMESTAMP, + salary INT64, + GRANT WRITE TO "_creator", + GRANT CREATE TO "_icloud", + GRANT READ TO "_world" + ); +``` + +## See Also + +- [Designing and Creating a CloudKit Database](https://developer.apple.com/documentation/cloudkit/designing-and-creating-a-cloudkit-database) +- [Managing iCloud Containers with CloudKit Database App](https://developer.apple.com/documentation/cloudkit/managing-icloud-containers-with-cloudkit-database-app) +- [CKRecordZone](https://developer.apple.com/documentation/cloudkit/ckrecordzone) +- [CKRecord](https://developer.apple.com/documentation/cloudkit/ckrecord) +- [CKRecord.Reference](https://developer.apple.com/documentation/cloudkit/ckrecord/reference) +- [CKAsset](https://developer.apple.com/documentation/cloudkit/ckasset) + +--- + +*Extracted by sosumi.ai - Making Apple docs AI-readable.* +*This is unofficial content. All documentation belongs to Apple Inc.* diff --git a/.claude/docs/webservices.md b/.claude/docs/webservices.md new file mode 100644 index 00000000..dc9ab676 --- /dev/null +++ b/.claude/docs/webservices.md @@ -0,0 +1,3181 @@ + + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/index.html + +CloudKit Web Services Reference + +## About CloudKit Web Services + +You use the CloudKit native framework to take your app’s existing data and store it in the cloud so that the user can access it on multiple devices. Then you can use CloudKit web services or CloudKit JS to provide a web interface for users to access the same data as your app. To use CloudKit web services, you must have the schema for your databases already created. CloudKit web services provides an HTTP interface to fetch, create, update, and delete records, zones, and subscriptions. You also have access to discoverable users and contacts. Alternatively, you can use the JavaScript API to access these services from a web app. + +This document assumes that you are already familiar with CloudKit and CloudKit Dashboard. The following resources provide more information about CloudKit: + +- _CloudKit Quick Start_ and _CloudKit Framework Reference_ teach you how to create a CloudKit app and use CloudKit Dashboard. + +- _CloudKit JavaScript Reference_ describes an alternative JavaScript API for accessing your app’s CloudKit databases from a web app. + +- _CloudKit Catalog: An Introduction to CloudKit (Cocoa and JavaScript)_ sample code demonstrates CloudKit web services and CloudKit JS. For the interactive hosted version of this sample, go to CloudKit Catalog. + +- _iCloud Design Guide_ provides an overview of all the iCloud services available to apps submitted to the store. + +Composing Web Service Requests + +[](http://www.apple.com/legal/terms/site.html) \| +[](http://www.apple.com/privacy/) \| +Updated: 2016-06-13 + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/Art/webservices_intro_2x.png + +�PNG + + +ޤ A�פ��T�o�xR�}x���A�\\�n��'��B^���t"��5��mgIRH� Ho��@������o �- .��e�.A��NZ d�$�� +��A��N�5�\`I���O'�SX�G�cM�+C�, �$�9��0�O� B!EmO�������t +"�V A�IA�IA�&A�&A�DA�DDr!�% �������Ƿ֒&�l��N�o�j�ud5�n1;�~o�\\��s��$������"���阌�.�}��ྑ&�t�ނ�&u(�����U5�\|7����d�\]����\|7��������s�:���3H��r:�I1�0�m �{�萖�����á�&� ��8�ٔ7�B�$� � �$� H�� H�� M"� M"�4� �4� �$� �$� H�� H�� M"� M"� M"���nO����I�40�d�J�S!M"���&�Z�r�iA$��&�b�7����\_mV�$� fH�x\`�~}���8���?��D���j"�Uv�\_���kN�e38�ͤ�&1mr4:��\_-����z6�p�3��K�DĴ�Q�z�GB�πFd�z�È8\\���4� �^Կ����?@Ї^d§J0p�^������d��7�HX����l���S@�O���̀��cL�ӥ%�uQ:� �2\|��� + +��f�� JO��0qd-!���g�m �\_\*��(��p�{X��O�NpM�t�� (� ��\\�e�����n�6"X���B�D$&\*���T2vq+�ٙ%g��2���L�c�L�T�֤�s� + +���^�h�՗�w�m@�������N$ k��J��p��b,������N�NTM�=��� ����\ +Y�<�D/h&��q/�ۋ�/x�����8�X��Ql<��Cx�T�TF�4��������\*x�Uh��\]� "�,�I�������j��r"�h�����r��D�. h�+��s���tw��9g��\\���s;dpp���9�9ؽpp�nίVxѿS� �๟�vN$��Ԥ�����AE(Qj� +H��r'�&}:K�����f��E��g���q�{\\��3wG�ą��0$rp�I{��:� 0�h{�vn���C�XJ,�� �Yߟ��%�&}2�Ok���z��zp���B6 1������k�@�D$\|S���=(� + +&H\_��&�� X�X�S���?��(��㫷�7�5��M�4������\[�1�HP@s"\ +�������)́+�4h.���D�H��\]g�<�J%�\`14��?��}";o �IO�\*�"@�������)(あ��Q\|����\\��&\*R���< +Y(Q�H C��fve9�o҂��C�㵫�$�HM����v��f)�{e%��H +�O�ͤ,�b<�� +~��,J���܉D\`�CnZ~��X0MB ��:si:�� +��ʝ\`��.� i���r�nR8�.�0X�µ�ܴ ý�܉D��Ȫ����5��,���r8�%�RB�r'�&�wi�d�ܙlPp.h4iah�f��Ҵm�(��Q�4)�Z;�T9�\]6���)\*�P��7r�g��8�;�4��y n9Cc����ij����� + +������\[����()5��;�T�d\]iVW���WR����f܃V�+�iK��N��o��4ٛ�Ѕ��N���۶.fj}�ȷ��c@�2����U�y�����h�/�?�^���?��{F}��+S�V��,�� +^�7�9�N;�� �ʝ@�d3���罪ےg���6�� + +����BD���������? ���!U���<Ѱc��q�����\_��@J�����@: ��o���\*.�%+���\_v��ı�� �j + +�V<�5���e@�\`?�& �����{��6̘�CQ�2�� ����O0�KR���#Y��w�b�3w\|�}چy��s�J"�2OM�/�eIޡ��K���K��$���\_�?O\[���83���I���^×�!j'P�\`. A�%4G}ÿ�b�\ +� ��96�sp� �Hܘ��cRYVfffff�{�B�fw���!3;N��ث�����X�3��s�k(�;�4����3�+�am��7�o��Ĭo��mH�\]/%�\ + +�m�A��iL0� N�s���MIʔ�H�:� q� /\|3�r��RlDI;���,\ + +�ˡ5��\ +<��c���c�+1s�;�€ �A:�07l�^+��~Y�q���J� ���?�jRs��f%��⃚�9l%a�$;-�6�1�FcJ1%��.�\ +�-�T��ց�W��T���K����������� �?y/��M�k�1�z\[���\_����\ +�ű�$\|T�NRS���ϋ��ق\ + +���Ty�;�8�T�dLfBkU�FU4)s�\|�F�HH��!�a���)y�x�k����\\�\\����˪:�׹~�j��?�\]J��Î7����SKN�~ܟ����U�I��% ,O�;�7.�p��E��z \_�}�dd�WX� ��ATaP u8\ +�\_w�T&A�\]�t� ���ܽ+/�\ +�~@�sp�n��o��cw\_=����v�\ +%���y�:o a'�S93}$�g��e<���=e� B��q\\���3�g�4��ˣ3�\\�1u�L��ְNP�R34Khۚ�mk�\ +��X��u3^�'IN�-Ou��fE��&�e��h���ԓ�i���~���w{+��\[~E�L#M����U�\_b���^�)U6\\%������~���8���Of�I�5)������\|?���B�� @=�\ +@�s��bRIwR3פ:&�����C�j�˵��i�;���ޛ�󝏻�\[����C�;<�a����Ĕ\|�:F�^�����ؑ~��6L�\_JS��⨠2(�Ų���A3�\ +q((G�W���<^� �'W��\ +"���c2�'&F�W�=e�wf.��L�����\_a}��a2œb˹NQEQ�{��y�\ + +H;�a��Kƙ��jyu�~�����\`y��y�Qo(�\_�r\],��6b����8�\_�CUd�j��O/0��㭎�$Hؿ����JRw���rm�ނ��$�����AU��~9��UN�B�S�������$�Rc"J�!y=���2�UVx\[r��l�h����ټ��m���c߮fwd�!��g4�M�%�Y "�}7��3�B�������d�-h~�셰xg�����9.v@JWLv�va��sP�fG˯�Zl��eI��N�Â'ƅt�,��%�M�W�jf���ج�ۿ+{���$�&�;�\`n\_�N�+@W��O� �t-\ +�1��9�-��8VR�/����\ +���S�B���(\[X�����Js�����P wdT��Q$�/\\I����������<���$��vh�Ks~�;��8������\\���k�CfA6𢜚�Y���Ƞ�~\ + +,j�q3iȗL��t��z�1����J�\ +Akn\ +Z��%�����rV={�N)��{�9�Z����ZK�-�T4��9W\`����u���K9�52\`X��?��#�D��hҭo ��7Gm�g@C��uv6��ܢ���4\ +�ΏT-�\*��;��3l�R,i�h��q��!Y�;r�‡G%�淃K88B���u$\_P9��f�-=���X���\*qv���+��-��ZT��o�-h������Czl)�\`�KŒf�&=^��P�p� ׍��/}ye�zA��;,�m �?ç��4��G��Y�+#\ +j�(�VX2�aЬ�PlB�ǾѰ������\\�H\[™��bI�H��<\[\`!�s+�&t���U/\ + +~W\` ��85w�\\�T:2�8�e�"h��I,I����6Y�� s�F䱤����B�QњѤ���E���meG��΍���Òd��I~nQx��=g��;��\|ѹE+g���:'�٦��\`CO��'��YǼ)Y:��$�yZ D��4�p-;Yiǐ+ص���vLı��Ҹ�C�c�M�f�+C�e/X�Z ӶUJڕ��܄3�� ��\|��Ȇ�,:c(k�v8���ӗ9��0�\[�i�;:�Q\`�0��e\_�\]BIyK ~�?��v��r�\ +/���M��$�=�d�HK;�^%��8yX��n�5R��\`�Wc��5�����#F� F�E�a0Y ۉC�U4V��C���o���Y��-M�glW�P�h8�Zz��\|�\_}5�֜6��zI���W $������,�c�axH����bJ�I!ǻ�,?��"cL;U ���E����WL����+�i���'��7䭈�yIy�Z��W�'M�\ +8�@\]����݅��<�ȉw�V�,�f�,�4 �j䀱����;��g�n�d�H��{V�%�P�@\*�?̼&�.u\|g��:P��Z�m�bG��p�H��E),��Z�������r�c -kM��L�I�˟m�x� ;\`p������0&�&a�g\\����7��C8 �\`.;���v��g0?k�M���6<n4�r�\_P\]7�k�k���W���Y�q&�ҸY1���rH 6 n�ǫ+I�aK��noN@Az��{�f�gL�l\_o���~���{"�<٫횶�k�8Ӵ�V�&����"���Z�H�W#� &��k���(@��Á۝8�C�������z�a���6F=K��U��V��Z\ +��\[\] X�C�,D;���!��mQMӒ��&���X��\[���5r�)c�1ͱ8�X;\\a�n@O�= �I;̺9���D�4ij����\*I+�:�\`Y��!�V&�5�W�5-�\_���\ +O���o��I�Z���i�45�I&H�E����&+�Ke����j�;��e�#��h�x���Tɳ���FH��\ +<U��\*H��p7��b2�\]r���g�ԅ^�\ +A�Q��$7�$�\]$d'M�{�Ѭ@��W\`��#�\ + +T7O�"�0�b�:f��=R��� �1=}f�+դd'E��e�� R�� �i��QK㲘Dp�Ϭ���ٝj�G���Z�ޡઔ@4f�,4=\`�G?nI�)N�6<�2��G!v̅��f��\`f7��A�8��'e��{=É�r����c�S�ث�H\]��zkӓ!�Kg~f��$��b×�˖�98��\`\|U��\_���ɔM�bƏ�\\9�會�ee=M�G\`˕�c(U�l�΄?��n\]I�P�I11�۳l뀗��񡻽0��\`�f���)�Sz�U� %9�$i���IS=!VsK�mO��)pqI:C���&!�c��^���%�֜b��F\|R?��������S�PiK��ȩ�;5QG�h�m�k�re5 �ɣ��G��xڷ \|f����$ا�4��Ԅ}����PB������S���#��%���V��i���<�T�%�3��<�w2H�f�&�V�x�}LU�/�, +��UG\ + +��~R\[ƌF�S&��\ +�@�D���� �s�d\`�D�Mt�"ܤI�,�n���\\0S�d�h&ɏ�$%(4����j����\ + +$IQ��iC���$�i8���� �A�.H���DL=tS�\ +��#��2j�4H�mv�m�\[���S�W�f��?;�g��)��9�M�$E����0\_�ri��\ + +S%��\`��Bk�\*�o�-E�bA�&A�םݍn�r�l��W������z (��~�kӭI+O�͚��b��\]Qj4�U��b��W���!�&\]��nLtɔ@��Zv�c����:n+15�\_��&���v�v�r,���a���p&�5\_/�t;ݚ7�M+ݙ(r��-����﹤\ +���Ү��� ����\*\ +Pź��w�i�vM"��%Qj^{FDcx��!f�^�~wPujh\ +ݛ(�蚠犆%�<u��b\ + +Tҝ\ + +s�i�g�G����F��!� �7�M< w�5g�艒�Q6�˛ԯy\*�Nx8 \[h\ +~+7 �� ����{�X����\]e�#�o�V�Gh.��7��j\[7e;� &I-�g)e \\7ݑwvr��u�ω�a�������D��uf��#ݶ��e��A�\]�J =�,�d��"��텋���ұ}\_mw�����~��iR�%z�fAM��޺ۭ�-t?�@��2�-������n� @���o�{��7��9����.��\ +��a�'L�i�e ��\\0����#��C0�/���+��=�� ������u\ +�%��h�ʆ%�k\_kR���GQ��(�c���=A\|�����Kw�l����w�4V�ԭ@Z�m�sO\]�߰Ҏ ��3��A6�� D%��\|��d��X&������¨̐� \*ua�Z���@a��E\_��au�ڷ�ۦ��l��e���x�\\Y�׀r��r��Q�$��,5�s�-%�ٽ�ն�w��:�\\���3�M���%��µ�9\\���לH������c� A�i8������l�4�/���׵�Y� \`p��,\ + +h�^��̱/���\*3�g�'a�,�4��Bi��\\��BQ�޻���S$��<�Jt���I�j�V� b\*��̕)�4Mq c�n�������#�h�ϛ���H�\|����W\\\ݼQE� ʑּ̰������WV IP<��I��"��.Q�^~7���0�!��W; ~m{e£-VX}& o�ҁ�Π���j�P\|�! ����̕�ꧫ#���!s\`u��g���e�E�����W~udx�9�@�r&�̥�j�iHM������� \_���;��C�Նr X��Ws��nR'x.Y�n-K���1�\]S�j��pJQ\\�1�u��R o�\[${pTj.\]0�<���o�����N�;��H�0ä&� �\[�/J��gjwM��MG�C�4�u}f�Z���m�j.h-��K��r9g�zX'Nq�5�m$�.�&���n���}mH~�~�þ$�r����'}��G�=.�"ۨ���4��B�^�Gн��~n�����\*\ + +O%�$���<;�6=$���W‹�L�uS���V�����c�1\ + +����\_\]�fqR�T�\\�Q&�\[����mU\|��U��K��/-pM��%z� ;�C��o-\ +�1�X�v�������l\]s�@��j,���\ + +�߫'\] 6\`�~ù�\_n��D��<�;9?JbcB\_w-P�ک�O�vdp�w��"0��5��n'�%#��ٗV�k\]����q{L<�� ����\`���"��֘��w�U��v�Ls��{"��}�p�$\_$�;#\`Kas4�'w��� 7�;k��8j�((Ҩ�lV\_y�T9���7D2шӣM�Ǿ�Kx̗P�F�%��Ԏ�4��%iu�u�d4@����M��c�6�B�k/�g��)ǔ�\\"L2f�\`�0�ٚZ��ձ��V���Z7O㝩RC.İ7�a���\*5��7G�q��B���)v8 +��1�Z���y��zy3��++&S��1�!BN\]��;��BN�T�q��xmj������N?�h�F!��\[�^��Ɣ�Q�̳�!i62���7�ZveD�\|yJ�IU��1ţ�xc�:�ޛ\*��h&�dn�LÃalS�1\`���M��sG�A4�I����;�Uu�4M�KF��+c 6�x�F��\*=S��ge���A� �}��u�������;j�3-O=��?�$ߍ�vj:��u����j\`��4�@�N6 s-������ɕy�iR�vژ�Dᾙ���k,p䰉!8f\ +Y�d$h�I�"ԟ���{�@��%ǰ$���x<�����I����/\\��e��Tc� saV�X����R���'�C�U<�0W���rm���x� ��Q-M�}���&#��\_����z9{�I�Я�@�M"�q$�ܳ�I����j��p\\w8�?T���RG��6�5/�\\�.:‹"�=���6��I�xUWS�!�o)�9c�}����\*a� ���\ +G����n�~n�ed i1���@�?G��W�0�=��p7���� L����H)3IR-b���t��#a��ڧh��P@���8+�g��4C��\ + +�� '���cE{�I)S#��mg�3E�Eq ���I��o�\[��~8�MN�K��i�8H�2p�O�� �\`\_�����n�60Q��?�<~��~Y4��AĆ��2�}v�a�\]��m�D��� +RX@Lj��V�g���c\_e����3�%I�<�H8�0Is����DO�������W�3g��A�z࿾3q���uÿ�(i3lw6M�P��'J�w�d�\[}y�{�HD�w�r�+��c���I5�\ +ƙ�v\]~GU\]4�D�;��i� +(�Od�U�R�\`����CE\_�\]����X�7�^�����,�$b��j����e� +o�g�dw�:�w�D�yϵͺ˥M�i�M�PC�$c���ġ�6L���3�{\[D��"s�G�����}�RF��\\�\`Y�)\`��ݞ�~��\_��'΢�'��ID��͑�\ + +iS���D�����Sf���\*�l񫥤���$ �� �����?8���w���v��u\*�,u1� �zXgC3��c;�0k�o��0~��A�o�\`4�;��^��� �܏��R�9�H�o�J& + +���i���&M����t�GI��L��ù��K\_���.1Џl��A�DLw���$\]p�zo��!!�37�V���t��y$ k�R�fq������R� ߍ�fN�������OY"�������%������s�)�� �$Y��N�4��nI\ +c���O:��J�nX���Z�lb��}���њ�P���\ +)�)�T��^�vx��s���6�nĴ7�P�T�W�����o�JhK�Kw��4�� ��'�x\ +5��Y��T0\\qL����:���5s5��h��$�$b�������鼼���:/�oid&u��sGJ �����tF��a�������\`1���� ��Q� F�����#�����䛤ID8\\�˂Ã�'�3�A�4��������g�ٲkb���F�o~��k��ܢ�#�s/g@���i���}WI����R��m���A7.G�����W\_���4:w���%ƻVjzT�ln�\]���D����Q��������֙3�KN�� ��\`p?�� IǬ�ܞP�;2F�q;D�ᷔ6\\��ya6gPR�7� }IR�F,IXk�y�. ��&��MS�&� a�km� o����$�Ox\*�b���\|�& w����H�D�Ru���r;��=���t-اi��BM���9����Č�f}��J�\[�9��\[Z\ +�ȹ૟��c�ID(~�\[��������P�Z�1��N�&D��5Q=y}I���ߏx�C(\]\]s�mn\] +�� + +\\\[g�i�l=3i�x�{�zYIIZ��5��}\[�f���� � 0���u� k��Z�,�,{�f�"CPa�W�$"8\ + +�h.k.��8Z���\\��e�e��N"M"��\_�+���Lj�\\k\*��\\�⮌ʱ˷��M-���\ + +��c~2�w\ +g�=��k�k r=5��bܳ��;&?teb����l���c��3}Tǃß��:V��� �IĴ����Ī"��S���Aj�fc�$1}t�\[k9od'3��w&.���v �ãz���\`\ +N��v�\\���6f֤ �$�������;�&gJ�z�����\ +Sݓ��p��e���o�5�:���c�8H��IČaO��7u~�a�\ + +�&��E!��Zi����5��:������{��HJ�vd���n}x��\|�=c4��/�@7i����;!V���xuU2NC��9#e���bd {�/�P���/�\_�\[b-�RJ\ ++�\ +�\*C�+�N9��ۦs�W({}(���3�3 �r�xo�n�^4 �s#��'ﮤ�������+�צG���mz��+�N9��A���$��Z�ħ��{調��x�����l-�66��w��a���\[V��f�$��;:��I�ӯ��{��=zk�F�\ +����a%z\ + +XU��)����ThCQ��Q\]�唫{��ɖ���Q\]j\ + +O ����F��� &�e��j����@��b�������n5-aǛ�&%�\]��\ +l<��@�d���)2ðfI\`M2�'���4qI�؜펔�Ko�W\]"MJ&��O\\5&}��\ +�S���Ol���ӎ7\ +h' ���n?�e��ec�H����Q7/\`sķE�d��S'Gvk\[�Ré��e&��v��������m���o �nn���nS���է�g��w+&MJ&�����8�GO��o�ie���B�֭z�P�=��y�2�s\|x�������˺i��1�\*��Z?��9Z\|�b�ݒ��)����mN\_���ԇ���\_�/zZ��Ė^�xz�\ +��^z�$��k�:����eO\\�n�)�&3\ +�G���)�ݴ@cp�i�h�p:s\`o�V�:m\`��vh\*�����ڰ��;�� њk�5\ +/j���\|��to�ٟ�B�Μ�1��'TJ�I�l���۳f��{�;t���yɁ�\\�RU\ + +���%� � F��Y����9\*C9WN�4K��W����x8��kR��������l�J=���j������i$R��������UG��\ +���k����d��Z����5S�'�/a��7g���4z�� 1<۟��\ + +6��Y�����h�Z�ö��Y�h}W�7/�'㝗��y���?�MX���������Ѥ�75M����򓫣^B$�I�f��K�"���.�j"�6Y����L�nn.��QS<)��Y���Q�Q������-�6Z��S���'l�0F�u\*U:��4�4\ +P�溵I�Xϼ\\7к�i��%��^Ț�CZ}qÔ���s��1��#���\_7�C3����(��3�D� k��q�?�vN��᝷�C��LҤ$D�&2���\ +aAl�yχ�l9�����@�\ +�@���aZ�q�X�M��7�)ܘ��\ +ē٤ID@��ʙe�g���%\\Z5}��w���5��(kR�΋\`q�4�U����8U��O�x��4���,�g��\*��S/�ѹ�\_Z��Ԩ�ܸ,�&�Ңz�M)aګ�F�O���S�˲B��(e��&%#=z��y&E���m7�7Ŧ���6o\[�7�c���7���hV�Uk#\[��\*+���Җ <�(\ + +�����K�y���o�=��V�.�\_�.\_�� �E�uv^f�t~ɀ��ZF���{o?���GG�+O����G%I^�9j!\]�g� �DZ�(.(t��6gt�a 0Z?G�w��\\{���/ln���+��X��?�Ůύ����\]�&�3̣K�?�V�Rz���#��:�۞;F��G�,��E8��t=�D�,����f���&8e����\ + +�M��81O�����c$I�m'������ztT�FY}G\[^�ˣ!�?ti�{�R�R�x��#M���?p���ZUB�R���CT���eo�Suc=�ݝ��F��l1�7 �D����$5X��@��^� :\|e1��$�)��?euPQ�i�7l)���o�\`�ڶaN����������/=\ +S��\\��.�}z}5h' ��%9�v�J9��xJſM�'��}n��\ +\[����œ�\\��4�\]$IJ7I�'�\_LO7������������!8�I�N�S���o�I�Y�K?V�����u����S��vi�ʩw��O��Ă���F��6Zy;�c�?Z��&%=�������<���$���&�o��BNJ\_�:�A�Jb�nϼe�)�mG?���\|����\ +'�\_�����7�܎�I�������l���'����LyɻW�?4��e��X\_a��\ + +����s��\[SN�����4/I,u�q~���/.s\\�iC�\*!;i6����\`�Fh'����\*\`�� {����ؼ�I����u������{.sy����u��ԘR�T���$U����8������ȷ�9�)���N�d�}!��W�1��n�m���xn�Nu��w���VO��=u3�n�8\|�D��B�IB��?��x�)�����c��Av1��'�)\]����r;�'�\ +��2�Bϒ\*�2�/�19 �-�,�$m~\*��$���P4l&MJ&�~�/�':"���q���^ܔ�S}�Dv#\]��ؚs� �Z\ +�O<�l���l�O�N�\ + +�u���{�� ޲�DȾ��U,Xٿ&�<�J�����M�ů)�C+�\ +�Kk���N�qe�ݬ����(�#��O�=�����"Ć%�1U2P<)w����4WP!j�v���� ���ƢS\`��I���J�FW!,\|+���O���\|7�\\t�.^tc\ +\|a���MҤ�DOW\]���+I5��1���R��r֢tE��2 �!M�UT�v��\]<\]I��66z��q��B�F '���\`Y����H�C�I��S�x�\*D���"�Ni���Ox����\ +�Ύޓ����E�4i�Q�y�f�\ +��ۥ&\]m�1:tq���T��c�\[�F�� �X��&�M%��U�\ + +�Q���\|�.�\[B����sE��?X1�폥Z�wјE.�dQ\ +��I�RAvADi�x<'�Ĥ)/'U�vu�$�� <pv�D�\]2��� f9\ + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitQuickStart/Introduction/Introduction.html + +Documentation Archive Developer + +Search + +Search Documentation Archive + +Next + +# About This Document + +This document gets you started creating a CloudKit app that stores structured app and user data in iCloud. Using CloudKit, instances of your app—launched by different users on different devices—have access to the records stored in the app’s database. Use CloudKit if you have model objects that you want to persist and share between multiple apps running on multiple devices. These model objects are stored as records in the database and can be provided by you or authored by the user. + +You’ll learn how to: + +- Enable CloudKit in your Xcode project and create a schema programmatically or with CloudKit Dashboard + +- Fetch records and subscribe to changes in your code + +- Use field types that are optimized for large data files and location data + +- Subscribe to record changes to improve performance + +- Test your CloudKit app on multiple devices before uploading it to the App Store, Mac App Store, or Apple TV App Store. + +- Deploy the schema to production and keep it current with each release of your app + +See Glossary for the definition of database terms used in this book. + +## See Also + +The following WWDC sessions provide more CloudKit architecture and API details: + +- WWDC 2014: Introducing CloudKit introduces the basic architecture and APIs used to save and fetch records. + +- WWDC 2014: Advanced CloudKit covers topics such as private data, custom record zones, ensuring data integrity, and effectively modeling your data. + +- WWDC 2015: CloudKit Tips and Tricks explore some of its lesser-known features and best practices for subscriptions and queries. + +- WWDC 2016: What's New with CloudKit covers the new sharing APIs that lets you share private data between iCloud users. + +- WWDC 2016: CloudKit Best Practices best practices from the CloudKit engineering team about how to take advantage of the APIs and push notifications in order to provide your users with the best experience. + +The following documents describe web app APIs you can use to access the same data as your native app: + +- _CloudKit JS Reference_ describes the JavaScript library you can use to access data from a web app. + +- _CloudKit Web Services Reference_ describes equivalent web services requests that you can use to access data from a web app. + +The following documents provide more information about related topics: + +- Designing for CloudKit in _iCloud Design Guide_ provides an overview of CloudKit. + +- _App Distribution Quick Start_ teaches you how to provision your app for development and run your app on devices. + +- _App Distribution Guide_ contains all the provisioning steps including configuring app services and submitting your app to the store. + +- _Start Developing iOS Apps (Swift)_ introduces you to Xcode and the steps to create a basic iOS app. + +* * * + +[](http://www.apple.com/legal/internet-services/terms/site.html) \| [](http://www.apple.com/privacy/) \| Updated: 2017-09-19 + +--- + +# https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/Chapters/Introduction.html + +Documentation Archive Developer + +Search + +Search Documentation Archive + +Next + +# About Incorporating iCloud into Your App + +iCloud is a free service that lets users access their personal content on all their devices—wirelessly and automatically via Apple ID. iCloud does this by combining network-based storage with dedicated APIs, supported by full integration with the operating system. Apple provides server infrastructure, backup, and user accounts, so you can focus on building great iCloud-enabled apps. + +There are three iCloud storage services: key-value storage, document storage, and CloudKit. The core idea behind key-value and document storage is to eliminate explicit synchronization between devices. A user never needs to think about syncing, and your app never interacts directly with iCloud servers. When you adopt these APIs as described in this document, changes appear automatically on all the devices attached to an iCloud account. Your users get safe, consistent, and transparent access to their personal content everywhere. + +CloudKit allows you to store app and user data as records in a public database, that is shared between users of your app, or a private database accessible only by the current user. However, it’s your responsibility to determine when to fetch and save records. Because the data is shared, your app also needs to keep local records synchronized. For native apps, CloudKit provides the CloudKit framework, and for web apps, the CloudKit JS library and web services to access these databases. + +To check the availability of iCloud services for your type of app, see Supported Capabilities in _App Distribution Guide_. + +## At a Glance + +iCloud is all about content, so your integration effort focuses on the model layer of your app. Because instances of your app running on a user’s other devices can change the local app instance’s data model, you design your app to handle such changes. You might also need to modify the user interface for presenting iCloud-based files and data. + +In one important case, Cocoa adopts iCloud for you: A document-based app for OS X v10.8 or later requires very little iCloud adoption work, thanks to the capabilities of the `NSDocument` class. + +There are many different ways you can use iCloud storage, and a variety of technologies available to access it. This document introduces all the iCloud storage APIs and offers guidance in how to design your app in the context of iCloud. + +### iCloud Supports User Workflows + +Adopting iCloud key-value and document storage in your app lets your users begin a workflow on one device and finish it on another. + +Say you provide a podcast app. A commuter subscribes to a podcast on his iPhone and listens to the first 20 minutes on his way to work. At the office, he launches your app on his iPad. The episode automatically downloads and the play head advances to the point he was listening to. + +For a drawing app, an architect creates some sketches on her iPad while visiting a client. On returning to her studio, she launches your app on her iMac. All the new sketches are already there, waiting to be opened and worked on. + +To store state information for the podcast app in iCloud, you’d use iCloud key-value storage. To store the architectural drawings in iCloud, you’d use iCloud document storage. + +### Many Kinds of iCloud Storage + +There are four iCloud storage APIs to choose from. To pick the right one (or combination) for your app, make sure you understand the purpose and capabilities of each. The iCloud storage types are: + +- **Key-value storage** for discrete values, such as preferences, settings, and simple app state. + +- **iCloud document storage** for user-visible file-based information such as word-processing documents, drawings, and complex app state. + +- _Core Data storage_ for shoebox-style apps and server-based, multidevice database solutions for structured content. iCloud Core Data storage is built on iCloud document storage and employs the same iCloud APIs. + +- _CloudKit storage_ for managing structured data in iCloud yourself and for sharing data among all of your users. + +## See Also + +This guide assumes you are already familiar with the software and tools you use to write code. If not, start by reading a number of platform-specific tutorials. Next, read the technology overview documents and then the specific iCloud technology documents. + +| | iOS, tvOS | Mac | +| --- | --- | --- | + +| To learn about iCloud key-value storage | _NSUbiquitousKeyValueStore Class Reference_ | _NSUbiquitousKeyValueStore Class Reference_ | +| To learn about iCloud document storage | _Document-Based App Programming Guide for iOS_ | _Document-Based App Programming Guide for Mac_ | + +* * * + +[](http://www.apple.com/legal/internet-services/terms/site.html) \| [](http://www.apple.com/privacy/) \| Updated: 2015-12-17 + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/SettingUpWebServices.html + +CloudKit Web Services Reference + +On This Page + +- The Web Service URL +- Accessing CloudKit Using an API Token +- Accessing CloudKit Using a Server-to-Server Key + +## Composing Web Service Requests + +CloudKit web service URLs have common components. Always begin the endpoints with the CloudKit web service path followed by `database`, the protocol version number, container ID, and environment. Then pass the operation subpath containing the credentials to access CloudKit using either an API Token or server-to-server key. + +Use an API Token from a website or an embedded web view in a native app, or when you need to authenticate the user, described in Accessing CloudKit Using an API Token. If the request requires user authentication, use the information in the response to authenticate the user. Use a server-to-server key to access the public database from a server process or script, described in Accessing CloudKit Using a Server-to-Server Key. + +Read the following chapters for the operation-specific JSON request and response dictionaries associated with each web service call. + +### The Web Service URL + +This is the path and common parameters used in all the CloudKit web service URLs: + +`[path]/database/[version]/[container]/[environment]/[operation-specific subpath]` + +_path_ + +The URL to the CloudKit web service, which is `https://api.apple-cloudkit.com`. + +_version_ + +The protocol version—currently, 1. + +_container_ + +A unique identifier for the app’s container. The container ID begins with `iCloud.`. + +_environment_ + +The version of the app’s container. Pass `development` to use the environment that is not accessible by apps available on the store. Pass `production` to use the environment that is accessible by development apps and apps available on the store. + +_operation-specific subpath_ + +The operation-specific subpath (provided in the following chapters). + +### Accessing CloudKit Using an API Token + +To access a container as a user, append this subpath to the end of the web service URL. Provide an API token you created using CloudKit Dashboard and optionally, a web token to authenticate the user. + +1. `?ckAPIToken=[API token]&ckWebAuthToken=[Web Auth Token]` + +_API token_ + +An API token allowing access to the container. The `ckAPIToken` key is required. + +To create an API token, read Creating an API Token. + +_Web Auth Token_ + +The identifier of an authenticated user. The `ckWebAuthToken` key is optional, but if omitted and required, the request fails. + +To authenticate the user and retrieve this token, read Getting the Web Authentication Token. + +### Creating an API Token + +Use CloudKit Dashboard to create the API token. + +**To create an API token** + +01. Sign in to CloudKit Dashboard. + +02. In the upper left, from the pop-up menu, choose the container used by your app. + +API tokens are associated with a container. + +03. In the left column, click API Access. + +04. In the heading of the second column, choose API Tokens from the pop-up menu. + +05. Click the Add button (+) in the upper-left corner of the detail area. + +06. Enter a name for the API token. + +!image: ../Art/1_create_api_token.pdf +07. (Optional) Specify a custom URL that is loaded after the user signs in using his or her Apple ID. + +In the Sign In Callback field, choose `http://` and enter a custom URL. + +08. (Optional) Restrict the domains that can access your app’s container using CloudKit web services. + +In the Allowed Origins field, choose "Specific domains” and enter a domain. + +09. (Optional) Enter a description in the Notes field. + +10. Click Save. + +### Use and Duration of the Web Authentication Token + +Each token is intended for a single round trip to the server. Whenever a token is sent to the server, a new token is provided in the response from the server. Once the response is received, the previous token is no longer valid. It must be discarded and the new, returned token used in the next request. + +By default, the web authentication token expires 30 minutes after it is created. If the user selects “Keep me signed in” during the sign-in window, the duration of the token is 2 weeks. + +### Getting the Web Authentication Token + +Some database operations require that users sign in using their Apple ID. Your web app will need to handle these authentication errors and present the user with a dialog to sign in. Apple will present the actual sign-in page through a redirect URL so that the user’s credentials remain confidential. If the user chooses to sign in, the response contains a web authentication token that you use in the subpath of subsequent requests. + +**To authenticate a user** + +1. Send a request (specifying the API token in the subpath) that requires a user to sign in. + +An `AUTHENTICATION_REQUIRED` error occurs, and the response contains a redirect URL. + +For example, send a request to get the current user, and append the API token. + +1. `curl "https://api.apple-cloudkit.com/database/1/[container]/[environment]/[database]/users/current?ckAPIToken=[API token]"` + +The response contains a dictionary similar to this one: + +1. `{` +2. ` "uuid":"4f02f7aa-fbb5-4cf8ae8e-4dd463793841",` +3. ` "serverErrorCode":"AUTHENTICATION_REQUIRED",` +4. ` "reason":"request needs authorization",` +5. ` "redirectURL":"[redirect URL]"` +6. `}` + +2. If you did not specify a custom URL when creating the API token, register an event listener with the window object to be notified when the user signs in. + +1. `window.addEventListener('message', function(e) {` +2. ` console.log(e.data.ckWebAuthToken);` +3. `})` + +3. Open the value for the `redirectURL` key that you received in the response. + +The Apple sign-in dialog appears displaying your app icon and name. If the user enters the Apple ID and password, the response contains a `ckWebAuthToken` string. If you specified a custom URL when creating the API token, the `ckWebAuthToken` string is passed to the custom URL, as in `https://[my-callback-url]/?ckWebAuthToken=[Web Auth Token]`. + +4. Encode and append the `ckWebAuthToken` string that you received to future requests. + +To URL encode the `ckWebAuthToken` string, replace '+' with '%2B', '/' with '%2F', and '=' with '%3D'. For example, send a request to get the current user by appending the `ckWebAuthToken` string. + +1. `curl "https://api.apple-cloudkit.com/database/1/[container]/[environment]/[database]/users/current?ckAPIToken=[API token]&ckWebAuthToken=[Web Auth Token]"` + +The request succeeds and the response contains the `userRecordName` key, described in Fetching Current User (users/current). + +### Accessing CloudKit Using a Server-to-Server Key + +Use a server-to-server key to access the public database of a container as the developer who created the key. You create the server-to-server certificate (that includes the private and public key) locally. Then use CloudKit Dashboard to enter the public key and create a key ID that you include in the subpath of your web services requests. + +See _CloudKit Catalog: An Introduction to CloudKit (Cocoa and JavaScript)_ for a JavaScript sample that uses a server-to-server key. + +### Creating a Server-to-Server Certificate + +You create the certificate, containing the private and public key, on your Mac. The certificate never expires but you can revoke it. + +**To create a server-to-server certificate** + +1. Launch Terminal. + +2. Enter this command: + +1. `openssl ecparam -name prime256v1 -genkey -noout -out eckey.pem` + +A `eckey.pem` file appears in the current folder. + +You’ll need the public key from the certificate to enter in CloudKit Dashboard later. + +**To get the public key for a server-to-server certificate** + +1. In Terminal, enter this command: + +1. `openssl ec -in eckey.pem -pubout` + +The public key appears in the output. + +1. `read EC key` +2. `writing EC key` +3. `-----BEGIN PUBLIC KEY-----` +4. `MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExnKj6w8e3pxjtaOUfaNNjsnXHgWH` +5. `nQA3TzMT5P32tK8PjLHzpPm6doaDvGKZcS99YAXjO+u5pe9PtsmBKWTuWA==` +6. `-----END PUBLIC KEY-----` + +### Storing the Server-to-Server Public Key and Getting the Key Identifier + +To enable server-to-server API access, enter the public key in CloudKit Dashboard. Later, you’ll use the key ID generated by CloudKit Dashboard in the subpath of your web services requests. + +**To add a server-to-server key to the container** + +1. Sign in to CloudKit Dashboard. + +2. In the upper left, from the pop-up menu, choose the container used by your app. + +3. In the left column, click API Access. + +4. In the heading of the second column, choose Server-to-Server Keys from the pop-up menu. + +5. Click the Add button (+) in the upper-left corner of the detail area. + +6. Enter the public key for the server-to-server key that you created in Creating a Server-to-Server Certificate. + +7. (Optional) Enter notes. + +8. Click Save. + +Use the identifier that appears in the Key ID field in your requests. If you are using web services, pass the key ID as the `X-Apple-CloudKit-Request-KeyID` property in the header of your signed requests, described in Authenticate Web Service Requests. If you are using CloudKit JS, set the `serverToServerKeyAuth.keyID` field in the `CloudKit.ContainerConfig` structure to the key ID. + +### Authenticate Web Service Requests + +When using a server-to-server key, you sign the web service request. + +**To create a signed request using the server-to-server certificate in your keychain** + +1. Concatenate the following parameters and separate them with colons. + +1. `[Current date]:[Request body]:[Web service URL subpath]` + +_Current date_ + +The ISO8601 representation of the current date (without milliseconds)—for example, `2016-01-25T22:15:43Z`. + +_Request body_ + +The base64 string encoded SHA-256 hash of the body. + +_Web service URL subpath_ + +The URL described in The Web Service URL but without the `[path]` component, as in: + +1. `/database/1/iCloud.com.example.gkumar.MyApp/development/public/records/query` + +2. Compute the ECDSA signature of this message with your private key. + +3. Add the following request headers. + +1. `X-Apple-CloudKit-Request-KeyID: [keyID]` +2. `X-Apple-CloudKit-Request-ISO8601Date: [date]` +3. `X-Apple-CloudKit-Request-SignatureV1: [signature]` + +_keyID_ + +The identifier for the server-to-server key obtained from CloudKit Dashboard, described in Storing the Server-to-Server Public Key and Getting the Key Identifier. + +_date_ + +The ISO8601 representation of the current date (without milliseconds). + +_signature_ + +The signature created in Step 2. + +For example, this `curl` command creates a signed request to lookup email addresses. + +1. `curl -X POST -H "content-type: text/plain" -H "X-Apple-CloudKit-Request-KeyID: [keyID]” -H "X-Apple-CloudKit-Request-ISO8601Date: [date]" -H "X-Apple-CloudKit-Request-SignatureV1: [signature]" -d '{"users":[{"emailAddress":"[user email]"}]}' .com/database/1/[container ID]/development/public/users/lookup/email` + +About CloudKit Web Services + +Modifying Records (records/modify) + +[](http://www.apple.com/legal/terms/site.html) \| +[](http://www.apple.com/privacy/) \| +Updated: 2016-06-13 + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/RevisionHistory.html + +CloudKit Web Services Reference + +## Document Revision History + +This table describes the changes to _CloudKit Web Services Reference_. + +| Date | Notes | +| --- | --- | +| 2016-06-13 | Added sharing support and deprecated some endpoints. | +| 2016-02-04 | Added "Accessing CloudKit Using a Server-to-Server Key" section. | +| 2015-12-10 | Applied minor edits throughout. | +| 2015-11-05 | Applied minor edits throughout. | +| 2015-09-16 | First revision that describes the CloudKit web services protocol. | + +[](http://www.apple.com/legal/terms/site.html) \| +[](http://www.apple.com/privacy/) \| +Updated: 2016-06-13 + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/Art/webservices_intro_2x.png) + +View in English#) + +# The page you’re looking for can’t be found. + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/Art/1_create_api_token_2x.png + +�PNG + + +\ + +U˶e\\�.3��Mї=GGG\[�'\*�?hP��mU\`�#e��74����\\9Ke�����Rk��1�)}����V\]Q)�e�\\m�\\�:�-:�!2)�o\[��M�B}\ +�$7�R7�rE����+�m0t���ͧ���$7���1oW���!c�lOt��y^�l��~̸��1�xz��r�F\[\[;�g\]o��4U;ї7�<$����d;��\*E���:CY˛}����{Ϟ\ +F@�t!ܱ���A�r�jT�Y�����5��\]��\_\ + +��!KMMMFZ/����I��\ + +�\`�nh��\|�te\]~�~mKo�\ +����"7SX\|\`{��񛬫��jBVP�z��za�\ + +=\[YE�$�G�� c�h-��B\_��H�{�' �e��������\ +���N�\ + +������&V�11�\ +�Ď���Uù�:}��m��t�ͻ�J��T�k$ �ZI���Z��z'��뤻�0\ +�����9�p��?�ݎ�##��VR$-�D��sUtD�W�Gm),,����zz��g\ +'��$���t��r�J�8WCB$Z�{�u\|e��\*4@���}��&t@F�@G�6z�/�2�":�/×L��Z�h\]C3���y%j�s�^����K�m�iumݞ=�"� ���v��o+}n�=�"�V�I��s�9����?QAAɗos��lݺ���N󐫏sw\ +4@F?NCFdמ>+�sϒ�Qݤ����g����W}^B\|�����A��(�T\_o��c����\`��(���k\]�ڢ��Df.jܪV�8T�y��~�� v�\]T��f��\_a��F����+�W"WSR�;W�2�g�TS��jj7S\_9���9W)y)�H�jT�cG���Y�P��tF�����c�ɹΤ̋�M��0"W3"�;k�I�?��HU$�5k��^3��s��1Y�����8WKJJ(>>�8Y�u�>���c�SHA�%�����0F������j�Qw� + +3�?OK�=���������ߦ�g��gr�g +���-���b8{����+x�XPMW\[K�k�6��\]�I��u����\]\]�&��( �" ��W\]u��Jl�…$� D���H�w�m۶��$Wd�3ż�zO������ ��g��\|S�ݾո�����2�n��1+\["S������@����R�3�;�{ۗ�q����\|�?�@q�����O}Y\]\_���V2U�6l�vV}Q��'t\]i�}QQ2s}r����Wz���@��� +"y���w�'��q��ς�9�ŁzK� + +{۳������t��{�e�/�9YUmC\`�Y��\*}5&}s\[�)����N- ��� ��Q�T\[��\]f���ӝ�j\*jO����o����;\ +?���u��� ��x���a@�;��\ +�� k�\`v�F�y�ݸ�,HA�+���������G\`4~���Yy:�Y�y������W}^��;�eE&E��Vg��L�RdLɕ�1����Ss��1���jeS-n�EWdJ�ϵ�)}o��;��e}3�NǏ���s�����"��ҡ�Z�o�\ +�A\`x �����VA@@F�����#M��m�g�\|V��{��RX=?��\ +�#�iĬ�=�Z�I\[9D�-E��d2��J�\\��m���\[�͋\ + +\]&m)vu���q���Zܣ�Šy�JE��}�\\ƭ�������@@@@@@@@@\`���#��/\ + +УX�RShт�� Nb;\]q{����C==�o\|�E��"iƴ)$�Z\[Z�ÑctD��������,W��^/+3�0WYUM�U�oJsf͠}�Q{�Oڱ�\|�@�!���5�PEc;�\`m��3��pű%�-�y���E9IQ���=�ա �j���Ɏ��h���,k��Z�iİ�D�6pN"q(���MӲb)���V�о�&#E�O����QF�D���K�lvDW5��6���i�T�FFK&%QFB$I~���M��~�&� 0.��\|�93�:��������KI�qI�Jn\|(��/0�����}8\] �����<�B��,��!�M��\[f'��j��i��}�\ + +g�仅mta��^�'9w�K\_\ + +��MYW��4ω�z�������0UE�O�\|�Tj�\|���Pb�:����K�p�j����#UΛ�F+ء����SI��k\\�\_Y=�����$�����U������;V��\[K��.�j8i���즥�e��֋�ʌ��y���=v �CVX{+��8��ɔ�Ek7qS���.�ISs�i�j�cn\ +��:�:���\[��sU��t� �������$�E������p\*H 3.ߒ/�3�Nm8��L��BmS�rD�9O�8���=ɳ�,/ژ.���%�Y �\ + +��9�s��$�̹\[\_�U��tBÈ4=#���S��\\�'jZi-;:���w�U�/��:�R������������륜t\\:/�^�V:h�o�4��˴~I$�+;�H9Wem1��@��ѭ��q\ +��z���j9b��=�a�Q�1��5���ї�ZH�!�����Z����94!5�\]��\*��F0�G@\`� H�+�����^J�q�$��n�,O�w\ + +Ҽ���h�ђ�\ + +e@8Y�e�����8Xe��3���Iq����\ + +e���;ճ��g�����)����Z��q�mu\*7�ڽ��R���\\g����-綷�Ǟ�m�+;{ L�r�auM�q3\*�Q���n��}�1�C/w�q�ޥ�D�=��M�D��\*NI�^�(W�E�R��2h�왖S$��ષ��H NPs��ít�~�:���%�R�rd�&St�y�U\_�NVNE0�����F�j��V�ƌ̸�;J%"�S�Nt;.q�Cq��4�ۦ�nc��\[8�7l�H��\_����o�eU:��8ɫ��z��:?/��\\�E;��8?��9�Vw$��E��߼��}(Ѧ\*W��)�Y�~��=�Ȍ�g�s�{3�\ +��yT����+���zߜ��u-����8�u��t#��8\]��\|�ӿ3�8U�����J�T�ӯD=�%�e��kgE���q{\ +G���Er��s% ��������\ + +\_�5���S&�s'N�o�UN?\]�EY��a$K���85�'�������V�\ +�2ؙ�t����F��eL��UmV��)3�Hߩ��\\C��hm�Y����Tlj�n�c\[�ȥ�q��4����D�N�:�#Z۩������K�=��4&NK��~ƴ)����T��4N)PYٟ�r�$�Q�=w�D����\*��r�+)\_\`�����M}���ݸ�vJm}=M��d�\*G��,9Q����-\]b8X%�ANN��c���v\ +��}����\\Dk\_z�HW��P�M��(��v�1��\*{Ki��dz��"KǢ՜�u�ɀ�\ +��Yz�mU$�k�� 31�~��a����b�܅��s�\\�W�؎��{���L�����?\_�8b������Q1�&EӔ�v�&Ӫ�81�\[GmyۭS^��d������=T�l���\|�AN=���Oaƙ�D��ec����ɭZ͎�v�fDž�X}\\��1"���L�ϧfG@@@��#0+=�p��\ +��ܢVG"߄��Y�X�+����E��W�\|��tZ��r���S{���:��5�j\]�9Q�������fgD��v�����&�şcU�2��Cr�?q��y����~������3(1A1��f�}lkz�g\[�9�W(�j�Tܺ�#O���D��\|ט�ٶK<"\ + +��.��KI�hn�DrcL��Ŭ���P?����^��5����~�a\ + +iii��Hn�#7�\ + +o}\`���H.�s��VV{tHʴ�\ + +�(��Ȏ�gf.�sU�H�I�I��̖e��E���؈d��ode.�oZJ$'i��nj������enF\|��KuXOje�m\_җ��Ҷ�L��ոj뵴�}YO�H��U\[�%�a��e���k�南�r��ՐC�zN=���jV����lι���F\|S+�kW���7�je\]q�JD��%44�r�3\ + +  �-q�JԆ�Dqniɓb��WE��S��\[�5�����TN#��չ���\ +t��E���\\XC��#\\)�ĩ\*� �:�i1��V�✫����h��\[t����hp���)�VrG��\_�+W�"ɝ:E�O� �����s/����ӡ�XA@@\`��ȃm���O�r攟86�H0�^�8 �QB@��4�qV�y������C���?�KI���"��h�r���V��T9�T�IwD�F��uH�c�z���麫WɎ��Ϯ\]G��x\*�����pq�   0� �s4y������?rS�@ɻ{��8�(�������N�ݛ���������%�4�\]�/렀������������\`��Rn�����%�{�-���Kh�����H �~?�\ +\ +�T�7�ڳ��y�q��78L�q@\`L9X��%�K�ձ�9c\*E��a�J          @+^          �'8X��i          0��Axz@@@@@@@@@@� �Z\_�hv��         ��������@@@@@@@@@F38XG󳃽����������j��zw�����ѾE��%����qy�8he�e�a6A@@@@F���w�&$��, � ���"JMO�e\ +tA@l4�TQVv��(�     ��R��g���\`�O\ + +U�(��)���˩�������7^M��M���H�m4u�Bv�^D\ + +���)>>��JdD8͙;�R�����:A'N�Szz2��gSKs+�M̦F��688��ΝJ�����J�C  ���Σ��8��i$Y#'7����-{\ + +�̤��L�G�т �SrvՖ��F�5����8t������TS�@UU��D�062o�4� ����\ +���%�٩�fD���%Q����G����\ +��:x��\*\*�S��G��O;�4�� N����!v�Θ�˽���A&d�F��p�P�AT�w�sV�t�Cvv:}�y'��wҲsPVf\ + +u�yOԙ}�ɔ&8~\`���p�� O\|�E靐佪��(-�7��2�����QS$��y�W?�ʲ"S� Df���L\_�9��\ +��5UR^\ ��n���\|{�O�'�s�t"� � p��\`�Y��@�;����\_�Tv�\|\[�f��yv�?~Mm\[%�}�-��\_�����\[��/HYq� \_���7% 0H���?��r�,x���\_?e��~~����<%S�~�W s/�sz�kg��;?y\]����\ +�MK\ +�Ț�!��'����2��߬�PX�����5� � ��t�7��"� ��#/O\|�M�\ + +������O'�Λj�l\_��#=�ii�6 � �-�t�AG��#� �t��3�{Iv�yǔ\ +��:f��j �a3B5+�y$����=m�?�Dՙ��;%u�4d=�{�\\���s����q3\]��5���8�-���2�۳��޿�ʵ��W�n;�:?�<�����94X5�ֽi+\ + +@@�c�΀V���Lw� �ٝYYY���+��/��A�r�D;RN:��97Y �O�ܛ�K��̿�{nyw�W��٢J׊=C�$&$H�j�$�򪫿���5� � � � �ܱV�������<��v#Co����6F�������d���G�x�nbR�L�8Ib{�JIq��9sN�N��چ@P3����d��D3�o�ʞ={�Rf�k?�<��������:L�S�� �?w^���q���X�z�F8 ZΠ�-!!AF�)�֬m���K�Ȯ�;e��y��$ӦO���$\ + +Znذ^�y��&��� �����r����&su�ʕr���r���ԍSL��&�U�f�M�.}��\ + +Yg\\ղ��~����p��z��Wu^����\*l&kT������\]��\]T\`p�ȿm�&ߛӽ�^!�� � Е��\|vM1�a�b�#�?x�&\_��.kr��Xp8���j��\*N�L𲩩�ܲ�kwI�I�k�����A�������\|�L\ +\ +�\ + +S�u� �j��;MɁ��e�xH� 2Y�L�U�� ��P�3� �\]�Q�T������R�6�W�Li\ + +���kL����w\\��yh��ON+���?e��cf0��.N��&�h��"C��UW�Ue��R�M�\ +�,s �=d�j�m�2\[W@�-�Z'oΖ/��/�j�z?�\ + +\`��ׅ�B@@@@��@��m�"q� � � � � ��X��u�@@@@@�6 �z�H�" � � � ���V�\|\]8+@@@@�\ +��/�� � � � ��)@��?\_�\ +@@@@n�����)"� � � � ��\ +��iqV � �� ��I\`�,z�ܶ����k� � �:�~���nE�B@@� �ڡ�\ +; p:O�����Ƒ@@@@?���8� � � � ���V�~}8;@@@@�L�.@IDAT�c�~��pj � � � � ��X�����@@@@@�����é!� � � � �� \`��ׇ�C@@@@? ���/�� � � � ��-@�տ\_�@@@@�X Џϭ�O��/~�u����k� @@@@@�5d��F�u@@@@@X}�Ѕ � � � ��F�˗H:X}������В�ҏʇ����\]d��� Ў��ry��r���m�A@@@@T��X5���eȅ����E�R\]\]#�Y�w��A��'����?mK � � � � ������+��/��Y�d��T��;N�m�����;��Jt � �\]\\���^�^�\*!!!ҭ\[�.~�\\ � �m����8��G/7��ÖEGG�/(�RRRb2h�:�8�@�,555r��1).n��'00P�\*���e�v���j�\|������)h{����R�\ +�(���rٽ{����Cf̘�z�����۷K���e�ܹm:��\ +d�رr��59z��̙3G\*++E�����dĈr��I�9sf��{��y)((��'�zVD��wt���s6�G���4y�L0�JKK���������+�e�&),,lz�N\\2q�D����uk�٣���O\ +\ +��jMu��bP� y��G������l��v��I?t�cYK3��������A�\ + +�0�uz�����Ӓ���z/MOO���f�j6��~��1))��=���C�f�������:M�C�c�N �@�\ +t������fN��)'5z�Xٱc�+����@vl�a�W�\ +�)���AΞ9-����hU� ���~(\]F���� � �J\ +h�w'��l��E\_3P/\]�d�5h�\_�5�YX\`��W���A\]\_�\`���o絖�3f�͒mj{���Y�o\\\���9-a���h �@G ��Y^^�}?����?�����u8����q�D�Ҡ�ŋmPU���@w�u��w{4H�?�{ZBB�\ +�jy��ch��W͜�LW��J���e\ + +��{�~�Ҧ��~e�L橾�i9��P�\_ݗ�su��F�-E���զ�z,\ +�jPV��ѫW/��D\ +��@n���� �������G\ +�,�y���z.�N��y��ɦM�m�P��8������y�sO��"��B� Ǩ�Q����ҷ��A�4@��SO�ES�l�ҥ�J����"������W���K0���C��yN0�^���6��a�e���Q��s�L��5Xu~}�:S;�aٷw��c������Tƌ����h�}r�d���i�ys��6�k��b�s�%�y�&9u�d�C���aL޵c�,�x��^oc\|𡇬��6"mUG遌V��J ���� t0�u����m۶٬)�\*�pզV�\`��}׀�^�9B�\`5�Ko�wJ\ +�\ +?�����j�i�O �Y�,V\ + +��j����$&%JllO������6DF6\|�n�&�� �C��G�?tiV��!���뭫z���\]զ\\���i����T��\_�D���N��7y�d�4w�h}@�9���Y��k{\ +jhvv�-)�A�hՒ��\|t�\|��7� ������}���@��7j&��4�U�j檾����{�Iu\]��I������M=�{�tu��M���d��\`����4��ɨ�c뺚�JC�\\�;.��b� 1Y�'�i$�o��X��Q����/{vﲏ�ec���8\`�7�a)4�˭4IJ�2I2������6�3�6�\]S����^�uͼۖ�7��˚�?\|�m�V�n��L�t�:x��vh�P�l�Z@@w{۠�y��d?\|�N)���M���͏�qq�D\[2�\`u� Hk쾽�̇�\\{�,���t�F@7\ + +�j�V���@�\_ߧ�x��0\ +���N�-���;.����}��\ + +@\| h Um�/�ZR����aÆyl�\_�O�nK\ + +Nji\_Mo���:Xu��{�j��:hS�)CཎK������zo�����A���G���3���ɓ'Z������f����׾Z2�l؆A��䪏lX\_�������L�̏/�@���3Nɩw�������l�l� � ��-л���Ll�Y���2��OP�i�g�����i��̙w���y}hs���~����j�����J���\|)jMP�� x�\_M�U\\\�kQ��t?޷�k�Vk��^��M�j���\]\[S�i�L�#/�q����G? � � � �� \`mN�e�BBBe��ҧO\_پm���h%:@@@@�C�\|����\\\ +� /��%4���4-o�v\]y�ݽs���Z��k�ve'�\ + +�.&@���k0� � \`���dȐ!��\|t�a��@xx8�\]����@��/���o�@@��^@��/���m\\ ��ۣ�6 ���+@��^��ʊN8\ +�@@@@@�� �� �aa�p�@� ��v��8 � � � ������85@@@@@��������!� � � � ��? \`��W�sC@@@@� ���/'� � � � ��,@�՟\_�\ +@@@@�Z��\_�<� � � � ���V~u87@@@@�k�~��pr � � � � ��X�����@@@@@��������!� � � � ��? ���ݪs��+�Γ!)��N�� ��l��¢\[uJ@@@@�P��׋�+��\|�/HHH�kɨ�28y���ׯJ~A��� @@@@����{Fjppp���+�S��5�#�ꬬ�Ewϕ7�~���@@@@�p�.\`Ռԯ~��q�v���RYU��K���kr����&��@@@@�<�.\`լS\ + +@@n�@�\[\ + +�j�5,�q��zMM9�.�G�4e�w�r���&�z̵ɥK�l��a&���Ly���ol�{Ƽ&�)ɶL@� hk�޽�8���H�ɤ�!� � � ��~�����b�\ +nj\ +ԅ��t\[�tY3g� ��:j���\_��ǥ�d���mo�׬�������4c5\*:RJJn�����Yo�o�UV�7ZE��u\]CBB'�W��%%%��v^��M�Y�UW�8��g-�������B�z� �ֱ8h�)P������kwou\_�x�G\ + +<� N�A�իV�ෳ\_�@@@@nϴ���o��,\*.��955EDD��\[�Y����׳W�kLH��їп����ے��Ds�y��y��G�����4Щ���X����PX�ڟ�uۺar��?:n��F��u$���\[b� S#6�gF���zνzʼn���l��9ޛ��y���pcbc�@Zhuo���3�0(�qI�a;� H�28E��^�n5����cr��A3�X��� @@@@��G�k'�V::�����h�H\\\��{��m�Z GM��Ӛ��+ ��������t�� �s���� \\uCu��S�2��3��\ +�P����S�{b�����j��Zi��}k�i��0q����jճ��ׯ�k\]�ϴ��eϞ}��\ + +��}z���;���\\;j�ĖM�챴������e�9}ʵu�4j�ܹ�Xo����ߙغe�\ + +\ +�}zȪ+�����\ + +\[�\ ++ݞcǍ��C�JpH�lܰ����@@@@��t���j��f��K^%??��ޱue��4�<��g�JVV���Nt�+�q,Ct0\* � � � ��wD����������7w�����J6��\_4@@@@\| � S4@@@@@�v\`m� � � � � �\*@���@@@@@�v\ +\`m'�!� � � � �X�o@@@@h��v± � � � � @���@@@@@�v\ +\`m'�!� � � � �X�o@@@@h��v± � � � � @���@@@@@�v\ +�s�N۬���ӎŁ@@@@@���}�5,,�-�ú � e%��p� � � ���%��5� @@@@@�O��� �i!� � � � ��� \`��׈3D@@@@? ��/ �� � � � ��/���\\�?!g� �t=��\[��իW\]ؐ!CdРA��O�:%UUU2f̘F��@@@�+ \`�W�{��)U�R\_W�G\`� � �@�\ +�?^�\_�.W�\\�K�.�ĉ����;���@@��L��X#��d��ϸ��jk�('W���$e���\|Gv�V.�p��П}M�m�%������������ʙ��qX�}�}m�e��� ����rr�~� ��ϒ�1#E�u�DN�O�C�zl�l����N�r����풟��Z7�G�<�祲�LV�򆤌-�u-w&�Lv��?����\_�>��=��k6:�yF@�,n�)..������T:$f>;���Jtt���srrlP6--M���ǏKQQ�\]����:w�ԙ�+++E�ٻwo�e��ӧOKJJ�DFFz�@@�Q��Xܭ�},%��(L0r�=�e��˜��>g��+g1��n&H:J�Λ)��O7����q fK\|�@Y��;�rM�s��z��()3��C��i�x���y��;�~�׺����u�\[�Xl�f�>o��,�QӧH�L����f�����\|��X+ 0�\|a���ƣ�z��3��>>����\ +S{5 (P\*M6H\`�@I:X�\ +�&�i��H� 0���lZ-=PUV��0t � ��pj���}�����<T�lU�ժY���5U������\\��l�jFF�ݶ��WWWKvv����֦۬�s�����/����4 � ��&�����~�h \*�����!.X�J��z��ӊͭ���7d��ss�}��<~�Y���ҼB�n�7z\ +����нRg�����Mn�,�K�7�Kv6)m�\ +��x�;\_w���i�og;�ѪٮU�:g}=��Q#���=�j<#� ��I@o�1�\|�0�S�J3Vu\`���\`��6Lv��-YYYv�#G���˗my�J3\[�j\`��4h�eh � ���@� �6���eK䜽h�\*�!��\[�\ +�n�61�GG�\]��O���0�1#�:-�g� ��pA�:���G=�~L�̙&e���+���g��$�63��O3M�~kdl�l��8�;B����&�n�?u�L{��\_镕�h�\]ˋKdů^uf�ݳm@���� @h��f���i}���޽{�A�4���گ��;Moٟ;w�3k�ҁ�4��� �{�:u�kv����i&@@�w�;&�z� �4��%���g�kR\[Sk뛺I�O�(�0�¤��RNH�s��HxlC\]Ի����\\�����k9�ٲ����\ + +�����@@@@�%\\L � � � � �m ��6/�F@@@@\\X\]L � � � � �m ��6/�F@@@@\\X\]L � � � � �m ��6/�F@@@@\\X\]L � � � � �m ��6/�F@@@@\\X\]L � � � � �m ��6/�F@@@@\\���;d�\_\|7&M\ + +����weێ=���a&{սi�U�{��w�v�=\ + +�:���\\UY)G����9r8Vw�@���l��G~pJ� � �- +DFF�����B�����j��7q��d�:���ɪ��F}���v���sr�� �wd��q�%m�( ���:9f���w��" +3�3gϖ~&�V\[�ɮݺe��'\[a�\ +!ݻw�% �F�ITT�-Q\`�����2lx��#F����1%����܎9�ZG3^�Ϙ&&J@@�\\̼ �2$;�Ff��:A=���P����QB�G���{\_RS�IrJ��8q\\Ο;/CS�ʸq�$:&V�^���HUe���:ђ���� � p\ +��z�}�\ +/�SF@@�Kt����\_\\\��E���h��t��֊./-+w��s^~�������ș#G���0\[O��d��9�{���6l�ؿO��C���=%���~�Z\[?uT�(y��e�\[KM-�\*P�0����Qr�¹v�Q:t� j�s\]�� �E�oՊ�RPP 111�x�\[F@�- 0@�\|�I�x�,\[�T��j%99E�3���^����F�h߀�~6o�$�N����o�R�\ +���F�Z�G�J���&�&O��WHn�k3c�L\ +\ +s�cK~��@@@@@�3\ +t�������RQ�8\[5 ��K\ +\ +�3��w�2ː����O� �Ξ\ +�j+//�۶I�O��cƎ�,�\ +��^��3��&��n���6�X��Ѳm�Vs{�^i�6 �&�;��1z�h��������k�5�t��)���OlpU;u �O�/� 'H�)�0v�x)+-�͛6�@���LO?n��m����2��\_�� \`3gϴY���������b=m�q���L�6\]V�Xe���\\mt��p����װ�"� � � � ���lkM�U  m��z9+��\*L�cx#�J�=s�B��Ps�~u��-�V���/ɜ�s��dҞ={�f}jRڒ��d׮��x��i�k�Tٷw�\]���+99-�gӠ�A�<�ףG��N��˳�������6�Z\\T䱮�UZRl��3٪�r��A��:�e�fW\_S���\]�&��@=\|8ݵ\]\\�^R\[w�d�6���O�����-��v� � � � ��Q��X �L�0�Q�U�Z�v�<��}��֬�l�A���+����m��v��#3�{c�Uz��u�}���5�E�L�l\ + +��\\��������:u�n�^b�u�Q���tښ�s�DҮp\ + +_�}���t��v��Æ\|7؅0��)b��<��)")�qJr�_\ +_6Զ",��V�L�~��N\\%��^g���� �\_1D�����:q�4<^�0�ڶkkY7��e" " " " " " " " "���xdr8�\` D�\]�"$��Ǯð�ݘ����N�ܳ�އ �Db�bd�#6'�P�Bֳ�I.�����4Y�j�@�dK�.I����)S�þ�q�l�\_� Q9l��m����.�Z��NPE\\B��uk��_\ +_��ɺ�l#�ن6c�.S6�L\]�_\ +_�.S�N���yyFײa���$�\\�@kӦ�5h�0�z\_�y��X��RR6�̟61kt�\]�Zm�y�\[��e��_\ + +_%/^,����V��XժU\\��X5$��j���gjrpxW��z�(����\_$ZD�D@D@D@D@D@D@D@D@D \[d��b�t����R�ʆ:f��n�x�S5ښ�haG}Tt�{�\_�����oi���!R�J���߼y�U�P)��ojԨ�o3u�Y��v�a�����ح�ly0�J�\*:����_\ +_6����q�WnU�R��b_\ +_g"��9�c�˔'�^D@D@D@D@D@D@D@D@����lC�~�lc�\\����p;���헟�$5~�x�#�Z�ݱD�ީ�w����U3�Mk�ܝ���:wl�4�ʕߵ�~���V#�S�\|�H�7r!" Q7�6�Xɒ�b�F�r�l�?�G��P�!i��Λ�)٦L�l\]O�F=����nݺƘ���������_\ +_ܵ� \*d:v��+WZ�0_\ +_�֯\|" " " " " " " " "�(�H�T�;�Kュ��ښ�kAp����3\[�rE��UA���Z��z��_\ +_��\`�����ȟ��1�����'Y�_\ +_l۶A��26⧑A�\]�+���e�S�Ǝ��/���(ݾ}��X������ծ\]7�~�f��ivL��N����ï�=�n%%��^'��ǻp‹Ͽ\`#G���Ga\\t��Z�tIw�U�O?������ذ!Cݸ�^rq�n�U�^�V�Zm �H5�+" " " " " " " " �D�S�_\ + +_�QDM�N2D°!�!�"~!�qJlV���!��n�ډac�S�E5j���Ũ�W OXx��q�{�S�?��K^b���-�����~ �������_\ + +_oV�S��D ��Q3��-�l�����a�x�x�"�"�"p!zz��~Svo�b�_\ +_c�8ުԏ��X�<���a�;�#B#a��2���Nċ���sX��\[���=~��(_\ + +_�_\ +_oSB�M�B�D��\*������D�% �C�FP�\[�kx�"�"�r��fD��a�l„ nky�\]v�۠�_\ +_��j˂0�E�vQa ��_\ +_cnw{�Y�@�<.(���ʚ�۷���_\ +_��"�bl���g����w\[����/�ؽG�뮻\\y8�O\_ ���x?z�h'ԺB�?z���D�^�z�Rw߲.Y/��B�O�k�\[nq��k�E�q���\*� ��_\ + +_���s��x���"1q5z,��tPtr�Q�^�z����Xz�YG���3s�Gr%j��D4�w�P��q\`�,6���!�Dn�l��s�����h��@#�������������Ws�T�#" " qH\`�&��/��r�n�g\]�v�#�:2�k��������������������B_\ + +_�w�ٳ�='�?��_\ +_f;w͚Z�nݬB���i�&(��d�V�r�m��ݭh�b��HF݈������������������A��X�Bl�5k��9���ʌmܸ�~��gk\|pc7�u�� �Q�8�T?�ӦN �:�ʖ-k�֭�v���� ҈��&N�J�+GVD���f�~�\]��U�v�Z�v�;�sl򤉶}�v߄�" " " " " " " " " Q8�5j���qႿ�����_\ +_mΜ��e�f\[�p���� �'��w��$�^�Z�uZĊ+�\[g5kնQ���&3g̴F_\ +_��jժ��W}�_\ +_6��uk�:�G���t�M@�n�z����_\ +_\*�_\ +_ޥ��t�g���mۺŚ�laG#����γ����͛S�@�֦M\[kа�/Q�y��X��RR6G�/U��mڔy�7ɛ6�\[+\]��U�\\�.���H����\]b�O�UD@D@D@D@D ��P�b�_\ +_k۶m� v��޼ys�9��֩S�Ȼ�q��}3f�լY�jԨ�%� �J�¥K��O\|����\_ٔ�Ϣ��C��s/7n�g��6g5�?���\*V�h�\*UJthF�S.?\[f�����\_�cp� �-�}!Pp\__\ + +_W\]uU$=�n8��\[nq��Ǭ���9����?��O�_\ + +_ސ��Ye��裏fUu��������fxDg�x��ƪ����Ƀ5�V��kԨim۵O���dɒvB�n��Vsm���7lq���+R�H�w���v!R���ï6\[i�G�qXU��_\ + +_Y��I6����?�����oР�m۶�ʖ+c#~ik�\_����F�\]�f�}��vx��֣g۾#�f͜e�gϱ:u���lؐ��L�K.�U+W\[��U��\\W���CV&" " " " "���= �1�pa��׏�0Ny���C�A�$�)e_\ +_����1c\\�t�����8�\`���u�W���8\`�pb�S�:���@����� \_��+O����s�(�\]{���@w�:�_\ + +_�E��D�)�J�\*n^�7��9C�����7�����\]m��npp���#rq����z�7C�Ch��=ބxΚ5ˉ\_�BW,щ�훸�~�=��\_{�5c<��\[����\]����B��T�R��x1Ο?߉�0�H�T��m����wު��k׮�#�8‰��<�x������8iժU �_\ +_v.wޤi�2R�2l�52��s�V�ܫ�\\W���#�X��X�ɘ���!��e_\ +_���;�bŊ�߷�X�Q��}�\`�͊��u����6��U�^݅߈^��\|�������hޘ�ݽ��?������'�@�B�!\[u!u�M�€�\[ԝ���������@F ~"����_\ + +_��'����?�����b�w�����w��-��;�wl���q��5�#��3"1a���ߔ�"p����˥��J�Ҟ�\["p�ذn��;x�\\D@D@D@����\*V�L'Vp�_\ +_��\]�"I˖-�C�WD7��M�6�7)�\*ֹsg�����sF�?�!����t����ǣ�o<�Z�{�U�^�gu}GL�6�5k�8q�w�w�q���L�b��\_~q�Q�u&����������F�c�Ѱ��$k׮��Z�n�Ң��-�.y/\_DC�@��K�(a�~��!�b�����H�=�%K�tޙ/����b�+z�_\ +_SRR��;�tB�?ޢ����Y����9�jz�@IDAT�;蠃���#+�x�"ce˖u���P����a��a4lxr�}(W�����b�G�y���zc^��� F���.��'�RG�ڵ_\ + +_�N�XF��M�4I�1��=^�l-G��Y�fD�OS �kM6m�ԭU��W�_\ + +_qh ˁ�<^��_\ +_����~r�oɓ^}�v�fI Y~,����雠U " " " " " ���� xp��F�LĘ��:���H�{���㠢�2��84_\ +_û����x�A0F��kCȤn�O��V�ZΣχ /1N9�)�(��~��2Rgz�L�Ox ���kF�\]�hoA�_\ + +_6��\_l��\|ƏoO<�z�Ƹ)������G_\ + +_!��������=�\\����OmٲeV�F_\ + +_���?��\]y�����(\]D gH\`��jED@D@D@D@D@��K!O9 ����G��a_\ + +_����t�D ���\|�U�'���H�Xy2 U�#�iΏЇ�)\\���<�9�\[�� �&(���x<=��$�lq�\[��\\ \|�w�ٳ�;� !�9� ��4��ޫ���\_�7�����kzec�C���\|�ɏ_\ + +_7��h�P_\ +_m۶u޵���-�$�e�W�����L��u���{�Lo}�y�{���^��7޵����;�~�.X��ķ���)���}��< j��r��W������\_�}���"��7x��G�b����8$���ęe�,6�Tm�C�޻;�}�g��9p�K�.�(\]D ���s�Jy��W�c=������Wiϧs���+�D\*�ڮS����LD X�d�r�}��G����\]�ϴ��nͻP�E �@\`��۹?���$ۂ��q#R��я9��Q�A �җ^z�řD�a�u"����ەc�!\\���G�_\ + +_�����-" " " " " " " " "�A��ڭKg�\_�����;�k�+Q��u���n��\*{���-9E"kב�������������������I��X\[6ob�����\]��Mz����wR������#��\`���s�N��$f����^��D���o��c헟N�O" " " " " " " " " ��@�X۴jn�4nh6n�1c'ز�+�l$%%� �njYvr�"3ֺe3k��\`۶u��?���\[y���g�~&M� �^d#~is��N����E �r�T���hv�)R�\*�/km\[�����u�\\�2�gS�X1�����-�5�_\ +_Z�ŭM��ϯ��������������������M �z�n۾-����#V�P!۾#5��o�m�fE_\ + +_�ڎ6xР,����@�X�@��� &������� �_\ +_b���({뽏#i�sdG㝷i�gX��ں�����Y~m٪�-^��ƍ�=R�����B�J֬ys�^�N-��˯#^�ɛ�m���V�V��J�ŋ���߰a����OkԸ����\[$Y��d�}��v���0p������������<v����k׮_\ +_�\*v;z�\|OԢ��d�@��ŭT��g�,����6���� �%_\ +_"\`�J(&����و��������-&_\ +_"���HwHw���~�Þ�93g���s��uf�z�k�w��D�\_��\\Ԃ@!�gV�P-SzW�Պ�ۢ�K�wh�~��ݷ� �_\ + +_�T����8�f̜mY��Y�T kߡc�8��֮sc(\_��Ҫ�U�\\ɶl��V�Zm\[�Hp�W�b}��߃���Q6Z�_\ + +_@� d��� \\l՚5k�\[WeV�Xa���ݙ5���'����ړ��u�\]gM�6��o�ݦL���~���Ov��G۷�~��\\y�v�UW���jC�~��g��\]��_\ +_7��D0�K��~�iWvӦMָqc��m�2���_\ + +_P�re'�z�4Vy ���m���)/z���ߣ… G<^����\\�\\���_\ +_���z�!��s� �� ����W��A� @{L@����x�5�x\[�c���K䕇�O8�{���6�I�&��\_n�q��5^޳�íb�Ŭ����\*qUb��e#�ȭ��_\ +_��$�4(V�KSUo_\ + +_m�WLT�P<�T��(.垆Ho"mڴ����tJ��?�R���ꫯ�����UW<�����g�}��#�Ȟ={���\*��/���;�I^�ʿ�曝�'Q���~2mc��W�n\]S�No'N�-�������V�l�ر6w�\\�U\_B��ެ�\`U\_��:t�P7�m����+�iӦ -��_\ + +_�I��5~}♶�G\[���2��,�Q��L�� ������bl�V�p�=���.�i�ԇ �W �x�uݚ�1j��0/@� @ ����=Ws�%���1��<�1@�@N#��֚� ���1$3�)�$���; @��:v����!@y��b�b� @� @� � ���F@� @� @"���{@� @ �dx��A� �� ����c�� @�@.$���K�,i˗/�-\[���0d@f��ϷB�_\ +_�IO �r��+@� @ O(W���\[��V�X�ȚVxڴi9\` ��@�"E�t�ҹkЌ{��^�J�� @��#�&J�\*e���Oz����_\ +_��{1�Cȳ�$�.-� @�r2� �G����+��!{GA�� �\[ ��֕c�� @�@�!���g���@�@���$\\t� @� @� d_\ +_֬�H+� @� @�@H��K���W\]bmma_\ +_,�}�v6b�=��۶z��$\|_\ +_�2 @� @� �I)��w�_\ + +_��"E�Xɒ%M��6~�x���7�\|�S�b�\\�����.��r����B)h\\���줓Nr�T�{�v�r�� ����V�Z�8\_q�nH���駟��;�yA���^r��?��A��^{��CTsS���Ʈ��8g�w~��Gm��rK�Yw�9������?�\|;ꨣ"��5�knS:� ��z߼)�� /�?����\_^�_\ + +_:\`��_\ + +_���3#�X��5�T_\ + +_\*b:�^��HtThy��\[��k(�#�9(܂�H��\*Shy�\*Ƭ���i��@e՟����#�<�y��%�Xm\*}ٲe��+-3�転�Y�a�I��7��+y�Ʋ��K��XijK\[�=^�� ���I���\|��..�/�9�Q�i��/��5޻WՎ� л���4y��=�g�⼆M\_(x!W��æg1�֜}��@��f7\\s�^� ���~��?�,��ٗ�r��Ohwx��န.��cϼ��O�ᵷ?t���y��-Sz�1(�@���\\�ֲev�&\\�\|���H�¶f�� \|�T;���}�^x�_\ +_:�US�7zb�^{�\]xE� }��zÕvh�� ���� @y��_\ + +_�R!�cTH��S��xO�-��X��X�W�׮���2ͩW�^.,�Be(Ԁ�닃x��9�k�td�@�;s^P^�q�Z����qUZ8\]�r���g��k��O �\\^��O���\`_\ +_\|��w����X�^���Ǧ�/����(�ӟ_\ +_�U$�i����w�W�\`�����Y�Z�\*�C��Y���\`���Z��=#�\]�����sV���k�X���O8oU��ꃏ��lg:���k/�w���͙;�7�k������꒥+�'^�gO�+.�f�\_�Sˆ��þ�i� 0�V��+ @�������5gyCf��K\\U;b w����֎:hKi��^t��ָ\|����\`��$Zַ}��}~Zk��Ļƛ�b����%^���Xk�9�����b��i��+\*�/ �A�/,��@t߱xE�\]'�s��P�rJߓw+��X��%�{���ҳ��9�vɇ@^ ��&y�z����cUe��x�T����U����ϧ���W��3V}s����A���)\]\*�h-m .�-���Ѧ�75��l-�h�V���v���W�jT��b��X;y�ŭJ�_\ +_N��\|�m��G��y���u߱�'@ ���5�13�Yr�k΢�h ��@@��Yabـ��-Oi 9�@����\`�r����V�Yk��3m��x��e\[�l���U$h7،���ˏW�t@� @�@�P,\[}�Y�v��e�d���� @Hr�pܴiS\*_\ + +_#�%��rֳ�����}����g���u����_\ + +_� @� @�+� @� @� �L@\`�$8�A� @� @H_\ +_���{o��ҙ͋� � @� @�@�H_\ + +_�x�l�2cyۼy���c�M�0�j��_\ + +_V%z%\|֫\_�j�Lq��7\_�\[�ա��S���w�_\ +_:�V�j��խC�N�h�"W/�9�\*\]\*h�����w?�y\*��)����-\\l��l��~ZNaT $/�C�_\ + +_�u�WUp̘Q�gk%�5s��\\�ҵ=�\|�=k�թ\[ǵ��J�\*e� �ʼn��(�v�ԩ�x�J̕g쎀Ǻu�ܽk�� @� @�&I-���������u��������@��ٲ��)Sv��k��V��ڑ�3fE��ʹ�Ӝ��Wm�߸q�-^��'E�'L �Jq�Ə���av������������V��7 �_\ +_1�d���+V��ĕMtN �/p޸�֬YgŊ'q@� @� �A χH�����uU(�촒�Jۚ5��J�\*a�;tt���cZ�v\]$i���{�~�z+P��)R4��~�!� �� 輝�f�9\`E+T�l�od���Ͳ�K�f����ǩi�fV�l� ��\`W�VJ\`ip0U�j�� �Z����Ҡ�_\ +_�\[ɒ%we'uѢőf��ȣ��2e���5��8���L�$:�L6O5@�@�ȋ�0M�Ed��B@�\*�?ق�N!@y��.�<;���1O�5~ɬϑ�i�J�u����.6tȰȡM��Út�U��K�/S�LP��;�ʏF�X��8�x����l��ѾH�q�F�0~����+\\x�Hz��_\ + +_6Y���dM�e @� @��.���\`�V�W��AV���#�!Q�V����W�g�~n+�/���������'��u,�\|&�u�oCR�Q�-\[�\|�_\ + +_9au۶m�_\ +_�p��?�ȉ����U�V��^��Ql֡C���aìl��A���.�k�@�F�J���š��9bd�Ԯۗ\_\|i�ÿw���� ��7�߇�\*��6�\]��I'�� .l�wWi� @� @� ��$���V�����%Z�vm�\]�^�:�2��_\ + +_� @� @�@X�D@� @� @� �ƢB @� @� � �&�"� @� @�b@\`�E�4@� @� @ @\`ME @� @� �"���_\ +_i� @� @� ���$�@� @� @�E�5� @� @� $@�5H� @� @� �@�X�9)m��_\ +_9i8�� @� @�@�@�X�+,7�@� �n�ʜ1F@� @���!�y�� @� @ȽXs��1r@� @� @ � �f��= @� @� �{ ��޵c�� @� @�@6@\`���{@� @� @ �@\`ͽk��!@� @� �l&���� @�� @� @�@�%���{׎�C� @� @�L�5���!@� ��G��\`��OV����b�Xv��=3�W@�@�(�uM� @� ��K@��E�؀�;l�B�+vεny�������oV͗)�6m�O<�N=�T�ٳg���l%�����/���E�f��L���Ol���v��Wg�_\ + +_ ��b-OϹs�ZӦMs���\]�p�\_�իg_\ + +_�g�BT�R�4΂ :�Vu$�}���TG�u�_\ + +_��Xo��ʒ@� �\`� �� @�r=yXJ�\*\]���ēH�0~�t� \*֩�y�\]�����4�K޼ �u�m��t����\*/g����U��x ��{��N��$B�r��K��1@� ��^�(&1�o��W��S�'�0�I\|�06={QV��\*T\[���Lq0%rI(��)�i��L^��$j�-��e?$����4\]%�i۸�)����+ ����P���I����d��qjNT՞8HDԼ��W?+��7���,���b����<�o��� ���\_,_\ +_Xֈt�=Hk�I��ѫm��V�,\_z�%�\*��Lk�-�_\ + +_�p��׻���o<��S�B(�o�=ܗ��ٳ�=�����Ϻ/\|���V���r�߼�\]�N׽�����g��k��O �\\^��O��ߨ��� @�@v�x�\`���'�X�v$LfD\\U�� �aUZ"��t���w�Y)aS�{�5�6�e2;�p{r޿������ku�S��\_�U1W@��\]�e��:r�H�N������HN�/7�1s�jχ�H� y� ��H��q�3 @�r8�JU��N��d�_\ + +_@� �!��O^2 �VUD��a�\|V�T � ��#�oe�<�� @� @�@�@\`�r�4@� @� $ �dYi� @� @� d9�,GJ�� @� @�@�@\`M��f�� @� @�@�@\`�r�4@� @� $ �dYi� @� @� d9�,GJ�� @� @�@�@\`M��f�� @� @�@�@\`�r�4@� @� $ �dYi� @� @� d9�,GJ�� @� @�@�@\`M��f�� @� @�@�@\`�r�4@� @� $ �dYi� @� @� d9�,GJ�� @� @�@�@\`M��f�� @� @�@�@\`�r�4@� @� $ �dYi� @� @� d9�,GJ�� @� @�@�@\`M��f�� @�@�$��?�ئM�l�̙�b�_\ + +_�O�DVyK8�)t���g�2�t�+Vy?�{/�p=�+\]���j�����:a̘1֩S'�z�Yg��ٳ�E#��֍g��/� W����+{��\]8�!^\]�!@ �d�\__\ + +_���͚5s��۶m�ۛn��z���\]���V�Zy�^v�eN@���i�&�ɪ���U"1@��ޝ��U�?@!,���H��}�7A��_\ + +_;u��'L�0�cs\`f��1XI���~_\ +_v�@�3.�� �i�_\ +_ /m=�'@���+ \`�c�g @�tQ !\`���T�ڣ�ə��1�9�,@7���陉ٍ��M}�  @���_\ +_X��6 @�F�@�gG.�\*�W?���-�0�  @��a��_\ + +_̙3��w���8���4֥�r, @��$�\`��.��{Ռ;����������\]~�mO;� 0��#h0u� @���#0cƌ���x����+��7��w��ٳ˹�����\|q�e������\\b�m���o��r�)�����j�g�z�%�_\ + +_��;.�m��ƭ��Ś� ɳ�B�򻬛?ӽ�gm\\������:�z<\\=��uO �m���:�y4�;�7����u���U����ٞ�bk�� @���@g��^t�}� �I�&-��'N�g�vP��h\[�c��� ����i��Ι��l��+�\\��FI@���t�:� @���_\ +_X��6 @��F\`�5׬o oM�4��@�T\]"@� @�@^��W� @��e���� @� @� @��2X��) @� @������ @� @��( \`\]F8� @� @���;����\\ �����\[�.�aЀ��� �& @� 0�&M�TfΜY�ϟ?�:?}��Q�g&0ƍW�L!0������ @� �������o<,�vQ @�{�螥� @� @�e�Q6�K� @� @�@��ݳT @� @��L@�:�\\w  @� @�螀��{�j"@� @� @\`� XGـ�. @� @���v�RM @� @��2�(p�%@� @� @�{��Y�� @� @��Q& \`e�� @� @�tO@��=K5 @� @� 0���l�u� @� @��� X�g�& @� @�F���u�_\ +_�� @� @� �=k�,�D� @� @��(����\] @� @��' \`힥� @� @�e�Q6�K� @� @�@��ݳT @� @��L@�:�\\w  @� @�螀��{�j"@� @� @\`� XGـ�. @� @���v�RM @� @��2�(p�%@� @� @�{��Y�� @� @��Q& \`e�� @� @�tO@��=K5 @� @� 0���l�u� @� @��� ��^Uj"@�X^3g�\\^�r#N��ψR"@���Al���/�dv�\`�ŝg\_wb���uw���#@��v��V @��@�k����w�y}���:��t�I��+�� ur����?"z�%��믿~оt��\|�i�裏�s�=�5�sf�u�jg�s��H���;�=�ܳ���c�}�)�)������p�_\ + +_�$ ��/4X�\_����S$yn�Լn��z��n��y��u�׼�s��9�����\]�=��ճB�@�fͼ�l��϶�E�B��������u?^8k�w{���=��v����� t�ڂ�n\[�5a�\[�J_\ + +_XG��4 @� @���vCQ @� @��J�v�&@� @� @��n(�� @� @��Q) \`�î� @� @�tC@��_\ +_Eu @� @� 0\*��r�u� @� @��nX��� @� @�F���uT�N @� @� �_\ +_k7�A� @� @������a�i @� @��! \`톢: @� @���Q9�:M� @� @�@7��PT @� @��R@�:\*�\]�  @� @�膀���� @� @� @\`T_\ +_XG��4 @� @���vCQ @� @��J�v�&@� @� @�c�Q�: @� 0��͛W��2����M}#@��R �7����e���Ku�� �4�HQ�!@� @���f�\*���z����%? \]�T_\ + +_��uX{�e�����_\ +_7ܰ^� a�Z2�5��~��˺�;�um$@�,o3X���� @��q�W\\�����;�, R��{���e���. \`�\[o�:T�񫮺j�\|���S&O�\\6�h�:�=�s�m{�GI�z��Y�fՏ�ӧ���ڪ���%�N� x @�@�\`m�(h @���4iRI@�Y� P;ˍ7�X�4�i���͙m���Y�u�_\ + +_ڹ��kl�q��رcK_\ +_ @�m�\`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @� @�=# \`홡�P @� @��& \`mۈh @��;vl���{\[�._\ +_"@��p_\ +_��b~?\*F������ @�X���I��=��#d\]���\*�q�ƕ�~T�v�h��? @�K?~\|�x㍗x� @���'\`���7�zL� @� @�@��\]�T_\ + +_X\_��ה_\ + +_Gu���Y���Vo�q�e�5W/o<�UY�\\\|��G��{�Y^򒗕�z�_\ +_{ϫ��p�_\ +_�!/yI�9sfئ\]���u;N9����{�-kU3-y���+�R.���%^�;�����~���� .(w�}O��˺�\_��w謹�/6\`�l�\]�S�߱�f�7���"��?���:��v�5�\]��}��ji����\]��?��̫��\_���c��hJ�<����~/r��I\_�j\\~�_\ + +_헶��\_/߯�^�Dն,հ�+\_Y���g��� @� @���&pKn\\ͪ\\�_\ +_:�Rι��r𦫕m�z��Gl=�\|����՗?Myj��,(�;�Z\*�)�;W�R�fn�y�Ce�\*$=���9��2���z}��x�5Jf\|~�9�}{�S����&����栣���j���^5���_\ +_y�w٬_\ +_D������3g�k�v\|�����2�2LH��\]&�ͪ��)gU}\]c���\[��w�������;~�rf��Ѳ^9����3�.��B�yվ��?�x9�_\ + +_��/�pL�۾�\[W뤮��������r���\|�o\_^$P��E\|���oRς�lأ�kf)��YȗV��L�j�2��?կ���/\[V!j�R\]y�¿�;��g�=v/WU�ko�֗��\_����;w�mo��ϕ�gy�_\ + +_�����\|��_\ +_<�\_\\ye�r��1~�+:\]}㹗\\�\]\]�-�ǻ�� YZ�����V����n�m�u��w֞��������NWk�����~w�?���?����l����N�dž��\|��+����X�u����wL\_h��Ż @� �K@���ś��\|vg�������8�I�����=o�������7�?��k�^i������л�S�c�����<�����Vq�Go���q���\[�G���eC��J�Qn��ǝn/5o��:��\[o��37v\_._\ + +_�n\[a�d�2�x� W5K�Z^'�y�1�'����Z��W���;�p�ϳ��\`͍V7T�Ust�_\ +_��(������������1uC됇 @� @8��R��z���\_����&�� ��qz������\]\]V�=��i��t�_\ +_���k��S^��wh�goZ���{�c���K�q�Ԭ�Tֶ�kU���ô����jZ��C� @� @G�_\ + +_Em�����赤���g����^Cyk�m5O�Σ���� ��gv�uY_\ +_�?I���h����C� @� @\`�\_�֨�V�Y����{�ok�Vz�c�t\_�g�e�dxN��g��lU�}i9�j_\ +_VO�V�k��!ݛz�bϱ?�_\ +_����^9_\ +_�\]����ƪr֢�٤�/�ʽ\[����þ��_\ +_��Ր� @� @�����R^/�E\_y�55��K}��;�UN~�c��Y��r+{��p����~TS-}M�,_\ +_�<ٛ�5U�f�\|��׺�\[V��<��x_\ + +_r���\|��Zk��~j9���X\_uq��QLJ @� @���D��gsC���9皖m5\[\]?�w\]���t��\[k�fml���� �9��jsk�e��rcG����CMU��Ks��,���٨e\_��כF��15���� @� @X����\\�&j5�Z�ٯ���fm�����q��9s�q���b�5�\|M�k:��Uk\_�ŹQW�6jM�ړ��뽵G�����16��׈�1U���T�A� @� @������\\�폱��u���۟���y��5Y_\ +_��'b��s��P�U ՚��\[V;8g\_��k�f�Qk�j-����o��\|��\|ۨe\_�F��\*�߱u�٨� @� @X���\\�.j5�Z�}~�)^�eBy��g?�E9Ǯ�m�\|n����!X��i��k:��g͹1�{k�xeݱ�t��h���S�5� @� @x�h���oM6��a-�Q��s\]-�{x��ۗ�#�Z�i�ɮ��k,�� �b�g�u�ih�a�&?���z\]7Hm=ױ�F-��}Y�8o�L�\[˱�h���z\|@� @�  C=8�!״�ۗ����z+�׈Z���F��iE�L�y���z���Z�U������l�a�{m�c��{^��s1���x������s�jbnȯ�74�< @� @���'6���Z�폱�&��X�/ݏ�h��X�5�'�~=j�ˣ�Ś5�Z�5N�����\`M���4/kZ׺\|�O�����b<�;/��5l�6)5����@� @� ����jg͹۷�\|�ю�s�ⱚ��s�n\_6�5�-}U\]���ɹq�����u\[��q���l�8��5��l\[Z��k�9Se���P @� @� pp �g64rM+����miQ��H�{�kX�������{^M�Z_\ +_VO�Z07��Y��y�F���i����Vcl��U�b���\_\ + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/GetCurrentUser.html + +CloudKit Web Services Reference + +On This Page + +- Path +- Parameters +- Response +- Discussion + +## Fetching Current User (users/current) + +You can get information about the user who is currently signed in. + +### Path + +`GET [path]/database/[version]/[container]/[environment]/public/users/current` + +### Parameters + +_path_ + +The URL to the CloudKit web service, which is `https://api.apple-cloudkit.com`. + +_version_ + +The protocol version—currently, 1. + +_container_ + +A unique identifier for the app’s container. The container ID begins with `iCloud.`. + +_environment_ + +The version of the app’s container. Pass `development` to use the environment that is not accessible by apps available on the store. Pass `production` to use the environment that is accessible by development apps and apps available on the store. + +### Response + +If the user is discoverable, this request returns the user’s name in a dictionary with the following keys: + +| Key | Description | +| --- | --- | +| `userRecordName` | The name of the user record. | +| `firstName` | The user’s first name. | +| `lastName` | The user’s last name. | + +### Discussion + +Fetching current users returns the user ID and their name if they are discoverable. + +Discovering All User Identities (GET users/discover) + +Fetching Contacts (users/lookup/contacts) + +[](http://www.apple.com/legal/terms/site.html) \| +[](http://www.apple.com/privacy/) \| +Updated: 2016-06-13 + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/Art/1_create_server_to_server_key_2x.png + +�PNG + + +����m�         �@�NK���G��o�\ +��1P���EW諾8��X�Ȝ�@@@@@@@@\`b�c�T��닾/�VS����@�;�l=3D����Pp��I�\_����7�c ����߾N�KG���00���a(4��������������h1\[\_l9�\ + +�rO�vmVr'2+���r'sW:����,��        0q xt����ڝʭ���d�V� + +}}}������ؿ~���kooo敉�U��t'�^6�Y��d���fNC�U�L\]�J��������,��vec+;X�7o~�?�����K}�}��?d + +)$8E �K�vtt��OοW����h~��P�e�ʟ�ʪ��ۤ.I�j�����=��:���K�����z��U\]�enQS�L=��\[��H         ��C�?�k�󚔓U�~DU��沓��H���$��z����RwG��Y����Ŭ��!�"�����\ +�}�b$��@@����~�NVq\*��\*+'�ȭ�,6��6���$�6\\eb�Ԅ\\5����z��6����h����yw0�:H         0 �e���d5����L�%WI�%��J�$7l���F�:\[�e��M�2�\*�s�"1pЕ�S9��������L�?4���Ҧv�����^vR���U\ + +� + +-���P��b���;X����J, ����Z7�m�޾8�ή��Z�O=�����ꫯf�L���N�Q��8NEEET\\\l�v4m�4G�V\_�Q�!���3�&�7���\_�İh��w ���w����ߡ}��g-�F��ƶ��rW����OrqN\|M$�N\_����qjz ����\`��曇�DêU�\\߉xO�\_\\;��7�@� ������������aR���o��x����������Ρ{���{���6O��W���Ǐ۪���aľ$��v05x���v�9��+4���kδa��ũґ��u�.�۔1+�j�\|X������U2�UݜK\_��rUW2\]Go���Z\|��u D�gO��Q�<��-���g\]~U�d6���s��/����R�q�\_(���.�aK.��=��1X\ +\[���8m�1loG��^�'����\*o�+���fϞ��˰v\_ߌb %%���}ƶu��܉�uޤ������?�s�9��n�����V�yKǫߦ-� ��#���\*�����.!�G��\]��l�\ + +��U�'������r1��v�i\ +�:!��\ + +�q:�lZ�th=��\]F3�:魲m�w}jR!��J�����vQu�L��Y�y����\\K��{��RZT�g���E3�v�K�O�f\_DS�:\`���������ͣܕ��\`�\]N �w��u����}z��-�ŵ�%AƐ�x�N����d��<Ş��������O�2��\|f��.7�EWd��l\_���Fݛ�U�d���&e�.���ꪏ���u�-ZD-랥��x��8�Ló�U.�\[�"���E^x!igPkͻ.{���\*���ʻ=������Y)����\].{lˈ��?�b����������b���l�\_{�����O�K/�d�\_��\|MNƱ�Y\[\[k좕 ���B+�!2�WC � �7��~�� A'p��=��E���4���yITVY�NV�˔�?�c�k�htx<�v�R��ʗ=�&g��;��� ��ӝB����";���=;(�\*� ��0O;O�(ָ.�n}�܃�����ۏSo�LR#��'ӹ9��m� 02��㩹���e7BCC��\]µ��AƊ@0�ӄ��'X���e0�l5߶�6+�W��9Kg\_��◺����)����S��4��;�D\_%���\*�JO��\]� +9�J +�n� + +�wGB�s\[�tza�J��f;��/<���<#�F�S��֓�ZH�~���\_��)\|����r����������BQ\ +\]qt--�\[k�\|0�3tAXut��\*����?B.�@�E@�կ��\*#���ŋI������v��E\[�n%98Wd�3�<�zO�娃��X��sI}Ʃ�n�\]�vzVr�c��S��-�)\[---��@���R�3�;�{���v���s�C��@q����KP}X\]\_��\\V2��6l�vNV}P��\ +������(�9�nۮ����9;Q�.��HAH�D�\|#�<��,(��\\���d�\`<�� =�Q\*K�֭���\ + +'� + +~t�}q�\*���꒛�G�Y.uIv��M�N�r����ɕCV���l�EW�T?�         ��� %)��9�� EMW�)��+��̓�YϽ�Uo0��zYEG�\\�u�^Wr�\\��@@@@@@@@@&6+ߡ�LQRmz\]�f�j7碧�^��n�dU��ɇ +00�.��z؍���~v��������������� �t��L'�~GO������t�{�+���=$��K���P���\\O��JW׳++\]#��d�h�(��\\���z\]���+�9W:�A@@@@@@@@&&��P�+"�Lʒ�rW��v��1'�ܣ�E�y�JE��u�\\ڭ�������@@@@@@@@@\`b��'��1 +�G劘\]�,W��r��IC����u}���A�vO2�ϧ\|��9t��Ҽ93)-5���}�+766Qm\]=�ڳ�ּ�2�عGoF@@@@@@@@@\`t���z\]f�ץ�o��.��&5˪G}oNVK�6BH%U6�\]�\]��L�6�yxx8}�{麫WSH�ٴ�� + +v�^��q�qN}bA�~})������������J.6��U\]d\*�u +���E�91�)��Ve\]��e�ҳ�SS�-垄uu��}�v�����f���x�� � �۫:)�/r�<Џ���H}7�{��2b�yg��RKr�o.m3����Gs?�/v�@@@N}eMݴ����.=�����\\a=� + +��(��� +�RT@W�\]L5�����������M�\_eĈ}��7�\`r.}�;���:��HX15�n=���ۻ +�W;LN���.� + +��+;Oo��r�������7t��1�օN 0� LɈ��ΛB�o:Fo��2Uq��{��ɿ�sj���NI����s��yn��N=����y�R\\T8}��ן�x:=�v/U4v��S:?���b&/蘒g?,;�׊Ł�7SS"i ��/;X=9W��H?9k �\|E8���O�PF�q��o��9�ѕa��\\�16o\|���}�=ɷzKg�.�4D�h�?�9 �'�� � + +ơ�I���9�9w������xױU����@��J$Ʃ��a�׏4Ӫ�Á�7�3���ׁ.���j�ׇ9�p��\ +��5�y��\]�f=����P�\[t3��#�F$\ + +���X.WE7�\_��O����Rm����r㨌wĪ��k=��M��:׫���������\|���m����Ngf9��sX��I���k�ݾ�C������O�)%��D�\_;�������0�fӦ�n2"�k�1�8�g�鄝��+���\]g\`GG�q�TTT$���ў={��R��p�4�4)�$�@}}�q8Vy���!V��\\o����(̞9�����!����iێ\]��??A{���\|��C�eW��ɹF��R��cgΘJ;v� W���!��1��a+I�o�=t����޸�.Xy�'�iKұ�eC����T\]SK������5<<�������+H������8t��'\[h;�ȎRq\ +�cDz��O3��\*ޕz����������t&;B��4R�\|\*��v �D����\_I��b���!Z��5t;ku'��"-�i�\ + +�Օ�A9����I)��9�k�)���TB\*7������k\]2)��6Y\_{�=�4=5���\ + +\_ךǡ�IS��G�7ި�\\�M��a4S���yӏ'Ǩ�y���V�VY��������yI���������"7?ef�;ճ�k�<�ֶ�e��bte�:N�t��@v�%p��vZzJ��t��i�������)??߸��SOm⸔\[�g͘Fn��I�h���UU�yS��A\*��I����76P1�2�ï$}��NSww}��6z��Ͷ\]�h�'�U1\[ue������� '��A���v�&ݎ\*�r\|���� \]~Ʌ���W���\ +��G ;9�n�����slX\|TY��P���iq��(�p�����,��\]���8��=\|�+���p\\1=�����w�F��1����!��@����;Y��\ + +�a��q��Hs�q<�g�/3�t��6�ݟ��e\|+��^P��E\_v!p��Ξ�a���\]�y)����ʜ����K��m�&����T��:������4��\*\\���8�\_�Mu-ֻ +\|� ݉M@�qR�q%);E��1��'��Z���Zv��$��X�\]�-�kDvĞ9�u׀�u��������\*�H�F�V#�<�\[o��W2���g�S;oy�LZ��v�Iۓ����<��5�n\]�1R?���~�a-�͊"'�x�����&�ɟ��a�������~�����(��Ň��b��ْ�uq;���{���4϶L}9�U٤2�\*:�yJNt<�w� +��v�G��H@��\]��8,(��0u�$\\���\|V=;<��t������x�rp���͡ + +͏2�տ(3v�m,ʎ��s��N�۽���tޑ���v�.H�G�r�\|Д��  c��\]���O�f����D�\ +�a+I��붥�B$�N^Y��$L%��\]I���0�F���.���K����~5���k��N+J�{a��~ �h��Y�k�y�ĉf�/��U���\[���Q���j��������(�� �~�a�W����\ +�}�˪���Z�A��j���v�ʀ��J�z����L�s��௼V������������@m\|���\ + +e��:ZR��!��Fq�� �U;��Q�۰\*o/n0���@����8N���5�nS/�#N����r��� ���/Ȣ�DznǪ\|�o��\]�rk�\]����g��j���\`�w��Z�WvD����F���\\8��Z�u�r��s����i�Q{͈�����a�� q\[cmn32��A@���n� /q���÷w�\`G��A8u����2hgM'}s}����juM\|W˷�W�/�U\_�w��V�#S⿚��ہ& #�K��C��{���4{I�\| ���fq;&��3�PŸ�Xk����-���<% �gu���G�돵�\*���\_Q�<ûL���U��LؗI�zY��S������\ + +��}���z-~���zr\*dddPl��o��!�^c'���������gt�U���$9��������\*���om�u����X�� + +ݳ4���{ � �\_�f����C�i��Օ��˲���+���!�C�8\_g�J�\`�h�����SC?�z ivz}��,����?ヶ�?=����\_.�s��g�$�s��~�ƇF�lu��\ + +.���ސ��\*.��/w��uƤ��C�F+��� ��z��m��� �@�6�k�g�'N�06�ӷ����\|��8=��k����ҏ7���ʣ�)�K� + +��Q�ɇ\\}�c�J�vI�q=�A�/z��i<8Y�$ �+��\|� �Е�/"��:IƛH����! 5��g\_�=�L��c� ���y�����)���tH�€�N��\`kE���\\9&��NU� +�/f,@@@\`���T�7�I�m�����\`\]'�����8�AR�\[˻\]��9���ڔP�tG�m<9YZ�������^��^�'��Y��d���~��M��b� �����@!�C�������$ ��+I�˧'�\`�<� �v2��4��~� ��M��Vž��         B����\*��C����?�u��AW\_q ͛;��R�)))Q��J��MTˇ\\�޳��<�����4t� D��r���Mn�h��#\]�T���E��@@@@@@@@@@�NV� +@@@@@@@@@@ p�\]A@@@@@@@@@\`<;YC�������������q�/�NV�z@@@@@@@@@@\`���u�?E� ����������x&'�x~v07�qO \|�ϰ��f�O�� I���aB���� P~�\|$��&������(�N֤��QB�a@��(?N��Nա  ��@Km5e�d{�@������x'�p����@@@@@@@@@�58Y��ӃɁ���������wp���g���d�O&         0� ��:ޟ!�@@@@@@@@@\`\\8圬�����L�Q���##(.)�BBB,�!��H 6&���'ⳏ5�����J �=D�򳩩���ٸ��墋VЁ���XI�\[�������%�S�ɚ��Is�:�����.)��iEtֵ�SMY��;@��t5�55� ��=u����e�� z!5N�~G��{/�F�55n���6ʛ5�p�fO)4v��tu�g��ne.�%'֖�ʟ;�����ތ2���:�ٳ�P'�\`�a�V��%KgӢE�h���4�)S󨮮i���'#6�ɩ�T��=�N՘�(��J�c�\*,g)�M��G�K\*����RB�S��)�d���6��(�-#;UO��C�  0"�"��?��B\ +����(11ޘJtT$͛?��3�����,���\ + +��cWVU�2\ +���kj�~� ��9��@���I&�:�f˦��(�fO�٭{w'����h � � � ��X�h��L�)w-���k��m���+i3q���z�a����^p�X��\_���#�N�\|'��W���q�8uN�9�z\]����RVXd뻎�:��u��Y��5����h��z�����\`�x�A�ƇA� + +$ �.ON��g����'����)W� ��� h֫<�3����y\]\\ � ���/@M�;�r � � � � p��F\|� � � � �w�A�;�r � � � � p��F\|� �t��w� ���\_����/� ��f��L�k�������좲�X^�����@@�Y{�\]�@@#���� �Gn�EyI���{OȤ9����\[υ�#� � �UY�J��"� ��Yྦྷ�#/��R{�涜Iia���w��K����m9� � �@wd�e�� ��������F��?�}�G/ˏ������V����)�J;m�?�k�ly��۾��������'9g=������}L�xL�<�7�j�+������������@pQ�e���~�c\]�ٳ�u9��&�t � � �-Y��Np � ��-�+O}���o�-�\ +���+rb�&���!��F�H��˯�������1�d���\\gU\[S-��Ɂ��\\}��j��\ +V�^N�����7UM𶺲���N��ګ����\\�w�����I�勲�c; /\]H���(�8���@@� ��u��B@n��ܻ��������c\ +�j�خ�e���s��s2��ٓv݄�k$q�;�\|�T�.������ßھ�}\[d��{���g�Ɍ\]���)\_�\_���� �~\[�\_��Z�a�T}�\\�r��ק�\\:R�,{X��~"u&����we���sm� � ��(@���\ +� ��b�'����mS6�kϵW�ŷ���x�b�����\`���R��K�/qS�˔yw�Ƀ�ʵ�:��zD�����5f��K��\_����J�lx�g��Z{�?0��xz��k���mF��K���\ +&8{MN�\* V��g@@o��Ɠ�s����or�\|��&}t � �=A 4b�\|���\*��we��F���pSJ@�3�z@��\]�y��Q))ȵ��GO0�9�Nj��75S���F� �̳'�J��9��{�OJ\ + +-S����O8��w�\ +����N/��)y���.��Qv�� � ��,@&�7��\ + +��g�o�����\`\ +0֟�ϐO�/f@� ���;ٿy��2����#�K@@n�@�\ +��z���Q����3����ԛ0q�L�x����}~�����K}�@@���z��\ +�HzzC�s���2a�Dٴa�HDD�h R��ǎ�g���͟'�6n�l�\ + +��A~�WyUF�����\`��PW�uŘ(��$�Mp4�l�4'��5Xj���X��~�� g��.�5eg�Z+/̔�Ss�RY��7@V��d\]m�"��������s\\�@@@@���AV\ + +��2�fu:Vg岲2)-)�ei-���\ +W��Y���R~��\_��ѣG���ǝE�w\ +�^�&5�DM2%�����\]5�M@�O�1��;�v�\]K�5\|�ݳW�\]�f��qqq��ͷ\\�:w�i��gL��\|�N{\|2�}�k�\]Rn�.\\�Y�z���y�@���Ak������M�����Z\]g���5��ƜRi2���A��lUm���׳G�c���^�}�%�\`�@P�\|�@� +�땚��)&���\*2�� + +,�9j\]����6/^�/ +L8Ȕ\`�)=���������5�U盒�L$\[6���۳��P}5n��NеL\*L}��&��MK �7�N料G��$��I�a����{~Yq�����\`�4����n2k���\ + +����U;��m��l�����̠O�2x�\`\[�����t����<��c���f���5eE٬���G�:��}Nv��3� \|���¾GDF��aR��\|����v�,W�m��Q�c<�ՙ���x�b3PW��0��m�ⱛ�Q�\\�΂�Q��%�Z��s��+�Сr��e��޵� "��o~CM��Z���y�}��7G.�����\]�qb�Uuv^�w��X᳙Z)=h�O5 uat���'�WL�����:$Df�G�/��ִ��fH˩��b�!�L���w�(��3���"3P�PS����j2h���y��7� J��L�5L���L��\\a�\\(�<�\]�� �X=�GfG\_���z�7?�ܿ4��X@@�.�$8�dgH��D���pdϼ�.�g�5;���6�@\[74=#\]�.\_&\[6o��K�Q�y��I~~�̪�Q��$Ya�����&s�!;w�\\IO�0�\]�������OKFF��ճ֌�+V����٬��D�?��"��^.�?�Ht�\*m��L����N\|����^N�J�{��k�O +0���f�K��m���4�;�3X�;\_ZZjJ?���\[ ��}��m�۩� ��-V�����G�uP\*}�߽�/��:D�h��E��S������l�3��&@{��i\ + +&��i�w���ǧ�}�f����z�ղ��\ +v���\ +y��wd��2w�<�2ٯ$11Q<����ݻvʒ���\_\|�/%/7O�#�$�J�\ +tN����6�LNJ��3f��mۚl�k�\[GU�ᨩ��t�ۻ��Ϻ�m�Ǟ����������3�;����?r� ���� ��Cm�R�L5{�ϩ���ꇫ�d���n�נ���3��gUSG��dc#�$�d�j�U� �ͪ%��1Y�m��&(��Ù��y1��ԡr$�LRr��u3��J����)���l�ׄ!a��t~�d�e�j�Y\ +�N6�a\ +�l��\|��΅� �@c��/ � ��~���tֽ�f�Gڼi�k�f\_nܰA�D@d�H �\ + +���d�4Y���7\_C"""�o߾RTT��������e�e�(�ɉ�q\[2L\`T��6��K&S���J}b�\`�e���1��̀WN����j��0XA�2@IDATu�s��T&8Zh2aSM��=�����Nl�������}�j����(�u��W��r�to���ٷ�8SP!q&���K��4@@@�YY��~���I�ZӀh� ������<&����r\[�u��͘9C��X�������k�OAA도��o��G�\[�O�x�?�}��:����dz���22,��H�6٦�߸�����2����\\u���T^�����.����u��R��a�� W�M6땊��5e\[k��@X4@@@�y=:�� r��m����E\_��%L�q�Ɖ@�ɔ��}��\\3A�t�G�Y�ۺ4��\\p�ϧ� ���A6�5�a�e�\]���N�!� � � ��-��A�\[�Ďn����$++K\ +M}Y�q{g�۶�l�~��"�ɯ�hO\]k��x�R��w�q� � � � �)@��Ӄ�.(++}�Բ�Fnoi9��Ie&���f�S�.'���bq՝t��+ � � �t@� k�Xh����~꭯i��� � � �t�@��;GB@@@@z�A֞wO�"@@@@�F��݈͡@@@@@�� d�y��+B@@@@�n �ڍ�\ +@@@@z�A֞wO�"@@@@�F��݈͡@@@@@�� d�y��+B@@@@�n �ڍ�\ +@@@@z��oϻ$�@��gΜ���"� ��H����w\]Y��VVVt�Q8 ��&��C�����Z@@�j���p{�����(��(+)쾃q$@@@@������7��C@@@@� ������C@@@@/ ���7��C@@@@� ������C@@@@/ ���7��C@@@@� ������C@@@@/ ���7��C@@@@� ������C@@@@/�����������w����5� � � � � �^2Y�+�z � � � � �@3Y�A� @@@@h�@�/7n��}�^\ +\ +�0��'O�o�׬����hGYY����9s��Ƕ� � � � � ��@��j���u�Kz�%�\]�E�R\]\]#�\]\[㺬1�#� �?,/���m�@@@@@�z\|�U3X� �\*�\]�����880J�n���b�u���MV�@�����r��U �>}�����@@�@���F�O���wٲ��p�!%PJJJL&mU��#� �7#PSS#)))R\\��ԏ����7N� r3���VWW��˗%66�C��cǎ��-���@��HJJ���<����#F����\*���2f����q��5���&2s�L9t� >>���.�)�6�y�D�f�~���P��\[���Cʖ-\[���RY�����{���2:v������ ��6�\ +�-!�Х˖�r���;o����m�����7- ��4h�і�}YƛȜ�~m��\|��\|\[\|��a�dQl��e�%.Zh�\]��������.c�����.�G@�� 8��!�û�lpp�}�\_?����骏��r\ +h�3ly ��u4��5p�M�z��׬X݇�/���o��� ��̙�=\_����J\ +����˪��皾k� ��\\5j�\ + +&h��Ru;}�Uכ={���5��4\`����^�Ǵ\_kjpA��ݥ��j���iF�vTyG��ПQ�sO릎2��ͩ}�٦�3K3\\��ZXX��������\_Di��yٞ���m4��O��gD��? 5���/����%�~1��Z����=�b@�\[#о���X^��\ +��K���9cj��9r4Q6l�֤�Vt�/�C�W���1���1r�$LX\ + +�2}�\_�լT͌� �ro��\ +�E�5P�A\\� �4S�PKdu�L#�@WhU��w��?��&th�i�ܧ?���~NIJJ�ݻw�lS\ + +h�T��w}��������ΠY��Ə�.3u�i �@W L�2ŵk\ +��X��i9�\*՟o�?�tZkJ��O���������%�-\]�ԙ����V���mq���X��J���po˗/w�e@�z\]�Um#�ceaa��9�R��1��ka'��m�/��X�x����x\]��ܳ{�<������&����1���:�&�T�kܴ�i� Z6W�L��\_���ǽu&�\|�d���A��/��\*sL׀\[��n�t�����T3��dm��t\_�mlEeE�ݶ�L��k2e�����1�m0{󦍦lZ�}ҁ �7��荞��40۸��5�t;�u���R��:L#��K@�-��j��#��u����V��� Z�oJ�T���r%�%��B�k�4A^�8���a͵��m�x��%�/6%!\ + +��4 +e� L�@NŦ$A�u�X:X����C��O������H���g�˙3�۵�����d�6;Xs�k�L�b+���d�6�O�� + +�j���7uh\_Y��kki?m��u��6-9����G@@@@�-��m ��C PV�Z!� + +h��?re@j6�������%9��N��ZwT��t�}fp��f�-mӦM���r�i���U6\[���3r��)3@� ���g�)�g�n9\|�dgg���'jkk$99�pkm0��ُf��5^�Zc��L𵬬�N�o�����3��d��\ +�u��\ +PV��޶u�ԙ}N�<ٵI��,IOK��h��a�Z53�����^N��\ + +pjM��V�jx\[�ֺV��3�8��l����mgN��Z�E:y����f\_�\]L�li�jXx����xD��G�w}d��VYQ�d=��y\ +l�l���I())i�m�?�ԣuZuu�3�z�R�L+,,4���B����葦t@�G�����\]�{���U�=j�:������׽%�g̐U��2Y��&38˖��BC@@@�3�v�}������ٺ������ٽG�~�i�ȼ\]��z��L��ߣ/ �!3գ��h=ת�jW�ŋ�@UmR�'g͞)=���������Ը�c��&0�ARmכ��c�@�E�8�ٳׯ\_��\]=VnfFK��cs-��WVT4���%%��%4�?QRR<3R=���{WUUɧ۶�XRA��u���\ +���s��60�y�Fw��; � � � ���#��y��u�E�Ev���� �uL5���Z��hr}Æ\ +��6\|����ے����y��y���2\|D�v��G�uP���J� �j-�1cƹm�09��#M��Ф����\|�3\*�Ԍ�k6���z�DIs�ˍ;�.sorK絆��Ǎ����ki�ս��;�\\CtL��Z�v��,vL��{��n5�8�d�?v� 86��� � � � ���%@��Z��Y3���q�����t��m��ɕaÇ�z����tt��F��%��e��v�Օgϙk�Qg2"��c���-����UU�&۵�d��� ��4�9c�L9v���ծw�9:t�P׺��� ȡCG\\}�����U++\*%9)IV�\\aK(8��/8���8۷�\]�O�J�{��k��m�W�m�k��ON�V\]��\[�qZ�t2�CDD��K��3g�j5:ֵk-�0������w�1� � � � pg ��r555f@�@�4�iw��55W;���6\[�l1��ϖ�� W��Za���H~\`P�$%&ʁ����W�SG��/���ݩ:���:��M0.Ƶϴ�4,���������LY}�����s��{�N\[�U�Ѻ���i}� Y��Gv�\ +���o�#+W���@�~�����^;H�kG�صc�=��EU�v���κ�N5Iݵt�=�k�����L�޵�f�~���/!��6�uL5볫\[rR����}۶&��̼l�'�ʳ�%)(�oֻ��@6m� k�\_#�e�ק�\]O�A8�f7\|���;�%�/�¢�}��y\`NnrL:@@@@� )���T�����u��y��LXg�3���Ӎ��xN��;���:h^�g.\\�4g��=������!{n�&�-Y8OF�&����Ggg4�e��hUU��{�e7�gfq:�}KM�׿���Vk�j�l�\`\_��i���ؔ6��:Ҿ��o��~���񪙛��Yd�������USs�nl�ut���Q�k��a�xyWͫ���W\_~�����6�,L�o�j�\]�Q\[��w�����5�i�x�L��b�q"^4s%;S��/:#N�s�R��ٷ��� h\\ ��;\`@@n�@s�"�:Szʬsż4O�e�ҠZ�w�s��i\ +R9���N��7�v��"���ӯ���3Y?ٺC��%�"�N���vfDj���i�dт9���T������CQ\[�4����r �}�A�Vkk}^\_7�4c��֞��4�\\����n�dٌ�3LF��V���im۶Ziii��������mu',D@@@�\ +�d��/�\_��UYy�R�g����k��8w!�n�\_PخmX����0Mƍ'����O�̋�@@@@n�@����Io�����Ny��Y���3�ŧ��\]8A������;���ԔT��h � � � �4'�+���\]8}�N ;;����6쩭�\ +: \ +@@@@��t�) � � � � �@'�v��@@@@@ �ʿ@@@@@�&���"� � � � �Y�7� � � � �܄A֛�cS@@@@@� +�@@@@@�� �zxl� � � � �d�� � � � � pYo�M@@@@@���@@@@@nB��&��M+++��8@@@@茀�Y���;s\]l�\](PVR؅{g� � � � ���%@��;�~q� � � � � �eY��p: � � � � pg d���g� � � � �^&@���n�� � � � �w���\|ugqr� � �@�����ȬY�$,,L�\]�&'N���W�ʌ3�\_�~���ݻwKtt�}��S�������Ș1c$""���gC@@�\[�L�.�۷��D���/1�.�e� � ��\`MJJ�%��N=&&F,X ,ǎ\ + +��S&���="�~��\ +�\ + +"\_�^/��\ +�惌f��?V�n�ak�\ +7ֵ&@@��\ +h�S�fdd� Sݏ�(0O\ +i�U���f�����f��/�56//�\[;zl��is�̑�#G:��z�gd�ڵ�����۵+!� � �Y���1h� ���~�~k�/4��m� :\`��A�� 9�Lk\*��/�F���6 �~�p2M��2S�8�m�f���v�\`S�u��ard�v)/\*��+�ɉm���\|&�Xk5s$�\\:}�e3SO�yLV@@Z�0a�DFF�kJJ�̞=�P�����q�����X��T� �c�:���sZ.@����ʄ�}0�Vg%�@@��=.�:m����9-45YOl��^ )6uQ�Υ��5�u҂9���i��=���2.��g꫏�� ��H\]mè����g��0�X}��J��\ + +�.\|�;\_w���m��ط�\]�gY�U�^����K̤ rj�!g5�@@�N hm�1c�؁�h��: ��˗m�T����i6� �\]\* ==\]��Aې�;����---͖+�H��n�@@�F�dm�./3˖ȹ�a�\*��3���� �n��7�����\]D +&A�AR�٠ ��?�Ro &�u\_�Vc�^HL��w͗2�xɕ\\j�Cccd�����O3N��khd��}�c3�;D��ꏶF�n;�汞3�OK�R�����L�?G�M�Ҕ pZ��K�Yc&O��}�n��Y��'Oy�e��5�hM�(S׵�R��2f@@�\[%����ѣGm�V-/@C@@��hцB\[\ + +\ +��I����)���2/}�\\\_�k��}��:�� 9���N��7�v��"���ӯ��k2Y�՚��TVٗ3��������\]�o�� �x�@g�\`�����@@h��f��@@@@@:)@���pl� � � � ��AV� � � � � �7!@��&��@@@@����\*++�K � � � � ���\ +x}�5((�k�81z�@YIao�t�@@@h"@��&$t � � � � �� ��~+�D@@@@�dmBB � � � � �~����bM@@@@@��A�&$t � � � � �� ��~+�D@@@@�dmBB � � � � �~����bM@@@@@��A�&$t � � � � �� ��~+�D@@@@��6���C� ����%&z����Jpp�TTTJIi��g\\��ɒ�����<@@@@�U�&��?2BV�\\.Æ ��'�d��mRTT,�U(��G��qc䋟T.g\_��fy�YNC@@@@Z�Aָ�����5�k�yc��r��5�Ҳr�WZz�\|�m�̟;S���������̹ �2� � � � �� ����Ə��W^G��;�$�d�Xݛ\`u��\_{�n���@@@@@��zt&k�)�������l���g��s%22��d=u���ؽO\ +\ + +���{ 3 �ۀ1��� ��L7M�6��?��Չ�6�/��i�&m��qb��x46f��,��7�{����(�r�t��DW�����9�9�y�9�\`���~ϒ�KM��zٻg�����Ï����,ٴa���:~�xY�Ѓ��啦�k� �F�q�& u��={��uUG�i��\]�;u�T��\[�f�J\\\�,Z�ؖ�k\ +��W<,�Ξ�WW����Z��&w�����\_�˗k��Ѿ���y���Y�?f�7��=Fƍkj��ܜ\\?a�L�i��Y�F��r�͜�s%<<�u���s\ + +���ew7�{w���tGbb��4�n�vCC�G�fӃ�viC�U�}���5�F'�l�yl5ٚZ�t���6;4ڔX�h�-�t��rW�f���i���� + +�d������C@@@@���6�z�\|u~�� �ҥ��l� +��iG���魍4�9{�ۮV�U��\`���E�S\]�t-C󴩃� +^�d���)�-�O^y�e���7��b =�f�v�im�#G� ��6Ȫe.�2��}\_-�\\����i�Z���c-��m�n�<4��K����ӪM���� + +\ + +�����%5%I�O�,#G �/�ү����JYy�?qJv��D�s��!H?$�+ � � � ��� �C�Է�y��d� � � � �tH@\_���������L~���}�g � � � �=Y� �u��f�vV۸a�:x�N&��ђ��!�/@v���\|v��TC҆HBb���7�\ +�vU�sᝲ~�z����y�����}j����IJ.x��@@@@�wt^�wxܰ��l2C�SP�/'��G���9sN\ + +hg�)70l�0� ͌�-(8H�g�-Gp���S&''��p���d{����� ��uն�.���\[ii�DDDڮ��dT��{�\`pYi�)�����: � � � �\]\*@��.�m���1�&C��% -�ٞMg(/+o�e����#S�N��#F����l���<����:޳�sb�/�\*���+-��ޚ�ǚ��N���쬺�W�֋ޣ6͖M�(\_x�I�~gE�ܨ��sN� � � � ��-@��O����͋� + +�d�6�n2T�� �Z۪͋�.�r + +��\|u&�z��ȭ�3%�RX\]/\`M��q!2!9\\���'�D\]�l��'@����93 � � � 0 +�N�/����ɬ��74J�� ���&��l���\|�gL�,-\|���� + +��1�.G�j5���� + +n�@yiэ;gB@@������2��=�\|^���~�S5)���S��޺(w������yFv �5� �WfE@@��.\_�,yyy��� +�zU��y�VWWg��y�5�����ƶԧ�XVV�1���ڞ���ܣ� +@��#���JY4�E}�\`�Z}p�JjM0�d���9�f��f�MfN�(@��� +ׄ � �@+ + +d�Ν��7ʦM�D���kUUU����b�C����{�S�z��N�r�����-\[�����%$����\]YA���}�sx��{8eJ���w.��y��5W�����dG7 �������@@@��3gΔ��$������xJJ�\|g^����9�c�wD��tN�(@��� + +���Mh�wŜ���C�\]�r��#� � ��4\`�V'H�5O���Ӵ�jii��i��U~ +hj ���Fv��!�to�������Z�u�F�:�3f̐#F��������u + +lf�f����6����\[5�y��A�"+���4���\[�F�@�M8�\ +��:��2e��g�{�Χ��:���eZ6l��X=&55Վחsi֭� \[g~� ��!\`��'\*��-��~e{�k����+����\*��v^.�\\g�Xo��9i������T�&@@Z)��-5�՗ai�R3F���l���\ + +����uL�4Iv��m��n9�i��6}�՘1c�\`u\[�E�%�@�G��#�����+��O�kv̓b��/2���P����?k�}�̱��d�!�����^���Iu\_꺷m��lp�;��K\]o���s�u�l�/u=�\|�3�,z�,i �G���ẹ?�+�R@��+p�y#���z�\ +p�=F@�������\_�f�j����S���Z�V9\_��5�-�UUU��Xz��M��ϟ�E��:c��xg\]�n53���رc�����X�#��\]���#5@��\ +9��8���.��������;R�u<���ɧ͝�O��h�#�4xYj�{��돢�������gv�}M��~\]�\`�\] �?�(�� d �@@�w + +�.Z�X�� ��r +d@@@@� + +M3Y��lf��T<$so�'���RZZ\*�ӧ��s�<�Y�dI�� �R��4C^\]�RJ���T%%%��������?����sN�@@@@�\\�Ջ��u�?wAn��T�WȩS����9������ۻ���#"$55�d��Hhh��W\*��w���Ǐ��#F����dѠ�\`u���KYi��3�uNgK@@@@� ����e\[\ +\ + +��������l����""#L 5Qrr�����\|���/���˕���T�����.;w\|�\` + +�Ҭ�����YG@@@@ �zu�՟�~���A2-s��Nu�-22R.Zd^tuZ���m���j֬�%$$�&C҆�r�UU�X�2hP�k���j���L�������{��@휹sLm�- + +�9���N�.��;}f���t��ץ��L�g������~�G�3�ЀhaAci���WXX�u���HOϐ���ɪWW��uզ/�6,ݖ&h:�r�rM��� � � � ��zu��3�� �s��#GL9�a�ȊGL���&�d^�5�d���'����EsU � � � ��@�^d�ϣ�.Y3\]���\[���\*I�I6�uǶmr���N;!� � � � �@//���ɶ,@@@@@�k��S4@@@@@�v\ +dm'�!� � � � �\*@���@@@@@�Y;�ǡ � � � � �AV~@@@@@�d��"� � � � �Y�@@@@@: @��x� � � � �d�g@@@@�A��q( � � � � @���@@@@@��8��ZUUyC��I@@@@@���}�5""�=��1 Ѕ�E\]8;S#� � � �=K�r=�yq� � � � � �gY��p9 � � � � г������"� � � � ��� d���� � � � � �@� �ڳ�W� � � � �~&@����� � � � �=K �g\]���v@� ���9�w��y�}����$4"�n���Iq^��߲C + +��Og�Ts$�=K\ +%y� �����\\1�紺�Z�x┤�i��!!�w�L���U���<����9S�D@@@@��5A�(�r��J �s�=2f�t�jJ ?��L�b뷺8w�� 3�Z�9n�p��m���R\]^)n��m7} � � � � Ћ�{˽\ +5/��()�5���떦�1O2Lɀ#\|l�BM�i�y��f��<^���d�����X\ +�'çL�ͯ���׆�0k�����=�k� � � � � �KzM�5}�9{���c:w�y��dI0����ʴ���:)�˗�\_~Cʋ�=�i��7�\\�KJF�}AVXd��~\_��9r\*�\ + +@@@@@��Y� �a � � � � �� +d��@@@@�A��q( � � � � ��UU��~�\\ � � � ����Y#""��p���@yi�^W� � � �t����S"� � � � �@� ��{�%w� � � � �� @���9% � � � ������Yr' � � � � � +Y��S"� � �@� ���žu�\\- p��F�;��@� :�� � �\\O 99Y + +�^�� paaa�G�t������#� � ��u"""$--���� ��)@���\|��5 � � � �t�A�N�d@@@@L����ܹk@@@@�$����4 � � � � �Y�s� � � � � �Id + +5٭�M���M3p���ܻK����JC@@@@�� ��r\\1,\]&��^E�I�%X�+�'O����E2g� ���V+�9u���^ FjP6ch�K7#}�$%%���G���Ӣ���բc�d��^뾖����$$$���n���$�\|����e@ +3/�ro�����e^��¬f��@@@@@�c�.�:n�(�6e�K���N��8%G�����J��zϒ�r��%W�Uk�{��X!o��N� +e��d��2j�0�,��:릩&�yYΞ��:GGW�����M�R�^�Ҍ�~H6��Y�\]���?~� 1��1��$�z=!�#� � � � �:�^d��/���7m�.�y��4 A.�UF O�=��ˆ?g��~�r�m���DΙ ��{o�d�������\]6 �\|�?�d�6 +�N�8Q�M���65\[�9�\]IL�� � � � ��x�^d��~��һ��Æ�Y��\_��}W�u +������3�=,G� ��Y�Q^xiU���ձw�^Y��Crּ�+'�1�5..NfΚ%�V����xIH ��a&��ƞvh�P2d��jՠ��,�� � � � �7^��Y�j�֙�+����O\]\_�o:�۶����.��W�h����tV\_aa��\[�F�,\]"��7��h�u���RZZj?�ϟ�ǟx�d�^2/芑��2y�Oo�.���a����a@@@@h�@��FFDHee����6���¨�&/�j��ƾ����:{����7�ILL���b�uuu�q�\]/���m��ԗ����������Yu-����Zw\_��\_��}�u@@@@h�@����\`dYy�\|�\_k�i���4C�W���4�J\_��G@�hZ�=�n�\[E����ÄL� �@�RSS;t�?�냬�����?�sM � �@�z�/����@� �V���0�"� �@���j�@@@@@�\ +d��B' � � � � �:���sb � � � � �U� �W:@@@@@�� dm��@@@@@�Y��Љ � � � ��N� k�� � � � �x �ꕅN@@@@@�uY\[��(@@@@@��AV�,t"� � � � �� ��:'F!� � � � �^�ze�@@@@h�A��91\ +@@@@�\*�׏:�K ��j�@@@@@�S�i��x^1\[ ��G���k�@@@@�\\��< �@@@@z�A��ظh@@@@�����$�@@@@�Y{�c�@@@@@�\_��˓�:@@@@@�G\ +�ȫ�@@@�(PUU%RSSs�ʩ@� ���D�������\ +�B��\]��� � � �;rss%\*\*JRSS{�\ +q �@' ���������I32\ + +d�566J�������D�ť��^v~�G~��祤���v�C@@@@$ ������e��Q�٫�ѯ�̝}�����מz� @@@@@��W�u���ȘQ�-�\_\|�\[�p��~�nk��!� � � � ���L�G�/�/<��8�X���kםm-����h}嵷\[k�8@@@@\`��\ + +\_�W^{�֘�j��5�Xmz\\K�� �@@� �fݸq����ݛ����u�ۚ��i�����5�ݺ��Z\ +�5JΞ=�\ +Ҧ���رc\]cYA@�\[� �y/���\]��M'��I�G�8Wll��Q�,��)7�\\j+\*.�/�{�ڻ�Ԕ\ + +�j���HHH0�\*H�6} � ��\ + +�'��"� � � � ��\ + �zC�9 � � � ��6�^duj�:����@@@@�^���=}ןݩ����<���?��3<��#�������� �E�RPX({w���<׾�\\��������異��3��ֹRSS���\]�\\ӭ���@@@@P�^dm�cv2\_uy���49n�\ +r��!�&��ђ��!�/@v���\|v79�Mow.�S֯\_/9�9�vӇ � � � ��\ + +�2��M���U!?a�,�A����\ +,�n�/������a�G�2\|}��%?/���7Nf͞e��$��%�\ +�ٳo�~���������{�=�w�z���%�{5�9r�HIKK��շ��'l�,7͘)w�u� ���;��X\ + +Rg��y���m�����=c2L���-\[�l�V�g�.��$�N����";�� ����2\|�p;Wk�):&F����\ +���=v���� \\ + +@@@@?� �?=���J����V\]\]-��W�\[j���O��O�����ʽU����A�M�h՟\_�����P�d�Ynj'�\]�bu������\[{Oן� � � � �����(�\]W@\]���ޝ�KV���\_@O4��<@��< 2�e4" + +=�\`8��SèQ������/̞=;�V�E\[�?�h8��3�s��)��jc�뾧:��\\�Z�a��ZNJ9 � � � �C/0��/�����Y�\\\_nu�)��T��QK/ .\ +W\|��a��W����0�k�\ +g����ꊕa��� J��q�}��zۭ��N:�x^�5k¤I��\]w��<}���o�~��E����n��ua�q��/���{����V�y����a�~z��~��뾧:x4~ ׉'�T$�/��\[u�0@@@@�!�I�!S�l���\|'-͙3'\\��o�q�ƅ�#G������Y�/��η//��n�mX�dI��\|��5��Y�w�qG��\]w� '�簾Z<��9�5�ES���c4\|�/�v�65��������u�}���\]��{����foj��l}��ã�9����M�i!� � � � �y�E���q�\\����\[^j�ҥ-�� ����9�Ǭ}��ǻY�nG�:��s\_��j\ +� � � � � ���H�V=\`�cC�atÞ�zH�g�}��1c�-?����@@@@�j�a�d��O\`��������Q\]=���˞y��0���x���y��3A@@@@ �d��? ,���X�"�EA@@@@�z�֛�,@@@@@��I֜ +1@@@@@��I֚PLC@@@@r$Ys\*�@@@@@��$YkB1 +@@@@� �dͩC@@@@j +�d� �4@@@@@ '@�5�B @@@@�)@��&�@@@@@��I֜ + +�\]�$�p���G@@��cǎ\ +�f�j9�  � 0<x\\����y� � � � � �!���d@@@@�$Y���λF@@@@� �d�$� � � � � ��� �:C�ͪU+�lo6F@�A��'��cp����+��{�"� �����$�ر;l ���V,\[\\{.@Z �ﾭ'1@@�V��t�G��@@@@@�H��§�@@@@@�kH�v�G��@@@@@�H��§�@@@@@�kH�v�G��@@@@@�H��§�@@@@@�kH�v�G��@@@@@�H��§�@@@@@�kH�v�G��@@@@@�H��§�@@@@@�kH�v�G��@@@@@�H��§�@@@@���ܹs��{��7L��W?9΍ � � � �\]!0�+N�?Ć\|��V%��6\[����7����z���� � � �l�\]����$����b�ÝgL���԰瑇����ی�nklٷ�a��a��ᙻ�\ + +߽�;ſ(�9k֬�$&H���qg������U���e7n�8g�"���x�ڵk‘G�8��\_'VĄ�\]��\]w�5�~�a��E�V�<��Ês\\w�O¢E���x����xG5jt���\_�ת�/��b�y�M�=g�'��W�\ + +ӦO\ +z.������%��g�\ +{��W�L�ԷyTL�^S�AWPw�^s����#o��Uu}%tu���?P�G�����憫��&�+�Z e뉻Wu����?�d���7��� 'ƿ�������1)�h�Cx�k��}7�F���w��\\�l�3�֩�a�K��,��m��U���,Z\_�w8�̋�����y��C�'\_�j�9�u�"4}����/�'c���\_�2�s�Q��Y�:�o��=���rKsM;�����;���h8�����O��~G�f�(c@@@��%0oyL�����;��o��돈��~�7& ֧��O�����ÇO��;\[���^��w\ +������W?�<\\���Kg�(�\|�������J����#!W���W<FŽ/?g�p�����.�f^Xϣ�<~�o�9�O�:o�p�v��g�~��/�eqlK%6U�l��Z�P}�����J������U1W�;\_uS���1)��2\*� ��c�\[Ѿ���荿%��\*'���n���/��B����gkio��z^/���bu~Vѧ�~��U�ܒ��3T����( �d���� �ys�}b������\*��ox:&5�\_�Z�\|��fH���j���� �1k<���a�}� �\_?W��\_�2,�w����\_\|��s3^�\_������K6����ӦO+��c���O�j@���˖Ƅq#�V��ņ��b��S1 :DE��>^������߼�Γ'5�Ǽ�=��8<\|�ϊ$����ݿ���w �����W{��H�d�\|{̀��\|=>>@�2��\|��Ù\\hCE�Ī�\\��w���\ + +a��7b����ѻ�m&XQ\ + +��=�5��ٻ���#� � � ��v��M�����L�\ +a��ҫ� \_���p�c�SƄ�oi����ů��7\*cS��������O���S,��B��u��t�\*��׿Fl�)�����U�b�ί��\\��\* �;R��ң��XJ�����~S�q3��~�RbUIV�6�ڪU�V�����v�8V l�a \[@ې�.ۢ�xٺA���i�v��nʎU/�"(����-��J��Gy,�R���ɓ'���=3u��}hH� \_Y�M�V\|ɕ��jE�n�s�9���l��Q���p�{��ݮ�\_j}��X���?���{���?���Y�iq\\�����g�Ǿ���$k�s�������\_�5jl�\_L4Y�^�ߢ��O}���C���8���v�2�H���τe�/��\]���ˬ4t���5����J1��~�\[���.�eq��<��q�\_\_v۷/�������\|\| m={���yQ@@@���wv�� ��S+�o��6��P��X\]��E�=���֗���ֆ:mF3ѩ�����q�U�;e�aѪM� ��51ٻ4�;5�krL���I��alޖ������\]v٥�\`�Y����kUIVK�\*o�\|�~�Z� �%i��\_� �����V�\ +P�;a5\_Ec\*J�ꋮ��l���H�v�s�Gx䡇�;�<�H����?������I�\_?5&�����y#ɹ��������������^��\[���vǍ�)�'�w^�jn�4�����ȥ�7���?�uW3^u�3.� �eeL���+O唠W�<���ꫮ�\ +ec�V�u��}ё����o�=<�w��\*�q������n�������~�{�\ + +�M �楱���Y��X�ݺ�Z?������bgj���l5�@@@@�\[�UB17��\|�U���ZJi�n?����V�������ۧ�D��}3�ܼ4Vշ1�u k\[��٘�Us�XU;S\_�\_����jl�,Z � � � ���@����(7��\|�U�ƭֵ�\]V�洊i\\��l���sslnZo�IC�N'Z�lN���1k\[��X��������T����ϲ�������ki#� � � � �9�Dc�k����}��vn�\`bzO~}��9��,��b�O\ + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/ModifyRecords.html + +CloudKit Web Services Reference + +On This Page + +- Path +- Parameters +- Request +- Response +- Discussion +- Related Framework API + +## Modifying Records (records/modify) + +Apply multiple types of operations—such as creating, updating, replacing, and deleting records— to different records in a single request. + +### Path + +`POST [path]/database/[version]/[container]/[environment]/[database]/records/modify` + +### Parameters + +_path_ + +The URL to the CloudKit web service, which is `https://api.apple-cloudkit.com`. + +_version_ + +The protocol version—currently, 1. + +_container_ + +A unique identifier for the app’s container. The container ID begins with `iCloud.`. + +_environment_ + +The version of the app’s container. Pass `development` to use the environment that is not accessible by apps available on the store. Pass `production` to use the environment that is accessible by development apps and apps available on the store. + +_database_ + +The database to store the data within the container. The possible values are: + +`public` + +The database that is accessible to all users of the app. + +`private` + +The database that contains private data that is visible only to the current user. + +`shared` + +The database that contains records shared with the current user. + +### Request + +The POST request is a JSON dictionary containing the following keys: + +| Key | Description | +| --- | --- | +| `operations` | An array of dictionaries defining the operations to apply to records in the database. The dictionary keys are described in Record Operation Dictionary. See Data Size Limits for maximum number of operations allowed. This key is required. | +| `zoneID` | A dictionary that identifies a record zone in the database, described in Zone ID Dictionary. | + +| `desiredKeys` | An array of strings containing record field names that limit the amount of data returned in the enclosing operation dictionaries. Only the fields specified in the array are returned. The default is `null`, which fetches all record fields. | +| `numbersAsStrings` | A Boolean value indicating whether number fields should be represented by strings. The default value is `false`. | + +### Record Operation Dictionary + +The operation dictionary keys are: + +| Key | Description | +| --- | --- | +| `operationType` | The type of operation. Possible values are described in Operation Type Values. This key is required. | +| `record` | A dictionary representing the record to modify, as described in Record Dictionary. This key is required. | + +### Operation Type Values + +The possible values for the `operationType` key are: + +| Value | Description | +| --- | --- | +| `create` | Create a new record. This operation fails if a record with the same record name already exists. | +| `update` | Update an existing record. Only the fields you specify are changed. | +| `forceUpdate` | Update an existing record regardless of conflicts. Creates a record if it doesn’t exist. | +| `replace` | Replace a record with the specified record. The fields whose values you do not specify are set to `null`. | +| `forceReplace` | Replace a record with the specified record regardless of conflicts. Creates a record if it doesn’t exist. | +| `delete` | Delete the specified record. | +| `forceDelete` | Delete the specified record regardless of conflicts. | + +### Response + +The response is an array of dictionaries describing the results of the operation. The dictionary contains a single key: + +| Key | Description | +| --- | --- | +| `records` | An array containing a result dictionary for each operation in the request. If successful, the result dictionary contains the keys described in Record Dictionary. If unsuccessful, the result dictionary contains the keys described in Record Fetch Error Dictionary. | + +### Record Fetch Error Dictionary + +The error dictionary describing a failed operation with the following keys: + +| Key | Description | +| --- | --- | +| `recordName` | The name of the record that the operation failed on. | +| `reason` | A string indicating the reason for the error. | +| `serverErrorCode` | A string containing the code for the error that occurred. For possible values, see Error Codes. | +| `retryAfter` | The suggested time to wait before trying this operation again. If this key is not set, the operation can’t be retried. | +| `uuid` | A unique identifier for this error. | +| `redirectURL` | A redirect URL for the user to securely sign in using their Apple ID. This key is present when `serverErrorCode` is `AUTHENTICATION_REQUIRED`. | + +### Discussion + +A request to modify records applies multiple types of operations to different types of records in a single request. Changes are saved to the database in a single operation. If the `atomic` key is `true` and one operation fails, the entire request fails. If the `atomic` key is `false`, some of the operations may succeed even when others fail. The operations are applied in the order in which they appear in the `operations` dictionary. One operation per record is allowed in the `operations` dictionary. The contents of an operation dictionary depends on the type of operation. + +For example, to modify records in the Gallery app’s public database in the development environment, compose the URL as follows: + +`https://apple-cloudkit.com/database/1/iCloud.com.example.gkumar.Gallery/development/public/records/modify` + +Then, construct the request depending on the types of operations you want to apply. + +### Creating the JSON Dictionary + +Create a JSON dictionary representing the changes you want to make to multiple records in a database. For example, if you want to modify records in the default zone, simply include the operations key and insert the appropriate operation dictionary for the type of operation, described below. + +1. `{` +2. ` "operations" : [`\ +3. ` // Insert Operation dictionaries in this array`\ +4. ` ],` +5. `}` + +### Creating Records + +To create a single record in the specified database, use the `create` operation type. + +1. Create an operation dictionary with these key-value pairs: + +1. Set the `operationType` key to `create`. + +2. Set the `record` key to a record dictionary describing the new record. +2. Create a record dictionary with these key-value pairs: + +1. Set the `recordType` key to the record’s type. + +2. Set the `recordName` key to the record’s name. + +If you don’t provide a record name, CloudKit assigns one for you. + +3. Set the `fields` key to a dictionary of key-value pairs used to set the record’s fields, as described in Record Field Dictionary. + +The keys are the field names and the values are the initial values for the fields. +3. Add the operation dictionary to the `operations` array. + +For example, this operation dictionary creates an `Artist` record with the first name “Mei” and last name “Chen”: + +01. `{` +02. ` "operationType" : "create",` +03. ` "record" : {` +04. ` "recordType" : "Artist",` +05. ` "fields" : {` +06. ` "firstName" : {"value" : "Mei"},` +07. ` "lastName" : {"value" : "Chen"}` +08. ` }` +09. ` "recordName" : "Mei Chen"` +10. ` },` +11. `}` + +### Updating Records + +To update the specified fields of an existing record, use the `update` or `forceUpdate` operation type. + +1. Set the `operationType` key to `update` or `forceUpdate`. + +If you want the operation to fail when there is a conflict, use `update`; otherwise, use `forceUpdate`. The `forceUpdate` operation updates the record regardless of a conflict. + +2. Set the `record` key to a record dictionary describing the new field values. +2. Create a record dictionary with these key-value pairs: + +1. If `operationType` is `forceUpdate`, set the `recordType` key to the record’s type. + +3. Set the `fields` key to a dictionary of key-value pairs used to set the record’s fields. + +The keys are the field names and the values are the new values for the fields. + +4. If `operationType` is `update`, set the `recordChangeTag` key to the value of the existing record. +3. Add the operation dictionary to the `operations` array in the JSON dictionary. + +For example, this operation dictionary changes the `width` and `height` fields of an existing `Artwork` record: + +01. `{` +02. ` "operationType" : "update",` +03. ` "record" : {` +04. ` "fields" : {` +05. ` "width": {"value": 18},` +06. ` "height": {"value": 24}` +07. ` }` +08. ` "recordName" : "101",` +09. ` "recordChangeTag" : "e"` +10. ` },` +11. `}` + +### Replacing Records + +To replace an entire record, use the `replace` or `forceReplace` operation type. + +1. Set the `operationType` key to `replace` or `forceReplace`. + +If you want the operation to fail when there is a conflict, use `replace`; otherwise, use `forceReplace`. + +2. Set the `record` key to a record dictionary identifying the record to replace and containing the replacement record field values. +2. Create a record dictionary with these key-value pairs: + +1. Set the `recordName` key to the name of the record you want to replace. + +2. Set the `fields` key to a dictionary of key-value pairs used to set the replacement record’s fields. Fields that you omit from the dictionary are set to `null`. + +3. If `operationType` is `replace`, set the `recordChangeTag` key to the value of the existing record. +3. Add the operation dictionary to the `operations` array. + +### Deleting Records + +To delete a record, use the `delete` or `forceDelete` operation type. + +1. Set the `operationType` key to `delete` or `forceDelete`. + +If you want the operation to fail when there is a conflict, use `delete`; otherwise, use `forceDelete`. + +2. Set the `record` key to a record dictionary identifying the record to delete. +2. Create a record dictionary with a single key-value pair, whose key is `recordName`. + +3. Add the operation dictionary to the `operations` array. + +### Sharing Records + +Shared records must have a short GUID. To create a record that will be shared, add the `createShortGUID` key to the record dictionary in the request when you create the record as in: + +01. `{` +02. ` "operations": [{`\ +03. ` "operationType": "create",`\ +04. ` "record": {`\ +05. ` "recordName": "RecordA",`\ +06. ` "recordType": "myType",`\ +07. ` "createShortGUID": true`\ +08. ` }`\ +09. ` }],` +10. ` "zoneID": {` +11. ` "zoneName": "myCustomZone"` +12. ` }` +13. `}` + +In the response, the `shortGUID` key will be set in the record dictionary. + +To share this record, create a record of type `cloudKit.share`. If the original record has no `shortGUID` key, one will be created for you. In the request, specify the public permissions and participants as in: + +01. `{` +02. ` "operations": [{`\ +03. ` "operationType": "create",`\ +04. ` "record": {`\ +05. ` "recordType": "cloudKit.share",`\ +06. ` "fields": {},`\ +07. ` "forRecord": {`\ +08. ` "recordName": "RecordA",`\ +09. ` "recordChangeTag": "2"`\ +10. ` },`\ +11. ` "publicPermission": "NONE",`\ +12. ` "participants": [{`\ +13. ` "type": "USER",`\ +14. ` "permission": "READ_WRITE",`\ +15. ` "acceptanceStatus": "INVITED",`\ +16. ` "userIdentity": {`\ +17. ` "lookupInfo": {`\ +18. ` "emailAddress": "gkumar@mac.com"`\ +19. ` }`\ +20. ` }`\ +21. ` }]`\ +22. ` }`\ +23. ` }],` +24. ` "zoneID": {` +25. ` "zoneName": "myCustomZone"` +26. ` }` +27. `}` + +In the response, the record will have these keys set that are present only in a share, described in Record Dictionary: + +- `shortGUID` + +- `share` + +- `publicPermission` + +- `participants` + +- `owner` + +- `currentUserParticipant` + +### Related Framework API + +This request is similar to using the `CKModifyRecordsOperation` class in the CloudKit framework. + +Composing Web Service Requests + +Fetching Records Using a Query (records/query) + +[](http://www.apple.com/legal/terms/site.html) \| +[](http://www.apple.com/privacy/) \| +Updated: 2016-06-13 + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/Art/1_create_api_token_2x.png) + +View in English#) + +# The page you’re looking for can’t be found. + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/Art/1_create_server_to_server_key_2x.png) + +View in English#) + +# The page you’re looking for can’t be found. + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitQuickStart/EnablingiCloudandConfiguringCloudKit/EnablingiCloudandConfiguringCloudKit.html + +- CloudKit +- Enabling CloudKit in Your App + +Article + +# Enabling CloudKit in Your App + +Configure your app to store data in iCloud using CloudKit. + +## Overview + +Once you’ve determined that CloudKit is right for your app, you’re ready to set up your Xcode project to enable CloudKit development. + +### Add the iCloud capability to your Xcode project + +Adding the iCloud capability to your project sets up the initial project entitlements. Before you proceed, verify that your Apple Developer Program membership is active and has admin permissions. + +To add the iCloud capability: + +1. In the Xcode Project navigator, select your project and your project target. + +2. Click the “Signing and Capabilities” tab and select “Automatically manage signing.” + +3. Specify your development team. + +4. Make sure that your bundle identifier is one you want to use for your app. (This identifier determines the name of the iCloud container created in a later step.) + +5. Click the + Capability button, then search for iCloud in the Add Capability editor and select that capability. An iCloud section appears on your app’s Signing and Capabilities page. + +### Create your container + +Next, add the CloudKit service to add the appropriate entitlements to your project and tell iCloud to create a container for your app data: + +1. Select the CloudKit checkbox. In addition to adding the CloudKit capability to your app, this selection also creates an iCloud container and adds the Push Notifications capability. The name of the container is your app’s bundle identifier prefixed with “iCloud.” + +2. Check the box next to the container name. + +Multiple apps and users have access to iCloud, but each app’s data and schema, together, are typically in separate containers. Although an app can have multiple containers or share a container, each app has one default container. Once you’ve created a container, you can’t delete or rename it. + +### Select or create an iCloud account for development + +You need an iCloud account to save records to a container. In your app or the simulator on which you test your app during development, enter the credentials for this iCloud account. If you don’t have an iCloud account, create one for use during development. In macOS, launch System Preferences and click Sign In. Click Create Apple ID under the Apple ID text field and follow the instructions. + +Note that your iCloud account is distinct from your Apple Developer account; however, you can use the same email address for both. Doing so gives you access to your iCloud account’s private user data in CloudKit Dashboard, which can be helpful for debugging. + +### Enter iCloud credentials before running your app + +Enter your iCloud account credentials on a simulator or app-testing device. Entering the iCloud credentials enables reading from—and writing to—users’ own private and shared databases and, potentially, writing to the container’s public database. + +To enter your credentials on an iOS or iPadOS device: + +1. Launch the Settings app and click “Sign in to your iPhone/iPad.” + +2. Enter your Apple ID and password. + +3. Click Next. Wait until the system verifies your iCloud account. + +4. To enable iCloud Drive, choose iCloud and then click the iCloud Drive switch. If the switch doesn’t appear, iCloud Drive is already enabled. + +To enter your credentials for macOS, go to System Preferences. + +### View your container in CloudKit Console + +CloudKit Console is a web-based tool that lets you manage your app’s iCloud containers. It appears within the Apple Developer web portal, and you can use it to ensure that your container exists. + +1. Using a web browser, such as Safari, navigate to the CloudKit Console webpage at + +2. If you’re asked to sign in, enter your credentials and click Sign In. + +3. On the subsequent page, verify that your container appears in the container list. + +For more information on CloudKit Console, see Managing iCloud Containers with CloudKit Database App. + +## See Also + +### Essentials + +Deciding whether CloudKit is right for your app + +Explore the various options you have for using iCloud to store and sync your app’s data. + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitQuickStart/Art/intro_2x.png + +�PNG + + +IHDR\]gK pHYs  ��8+iTXtXML:com.adobe.xmpAdobe Photoshop CC 2015 (Macintosh)2015-11-03T11:47:04-08:002015-11-03T11:48:56-08:002015-11-03T11:48:56-08:00image/png2xmp.iid:6270138d-821e-40a7-8704-299226f10258xmp.did:6270138d-821e-40a7-8704-299226f10258xmp.did:6270138d-821e-40a7-8704-299226f10258createdxmp.iid:6270138d-821e-40a7-8704-299226f102582015-11-03T11:47:04-08:00Adobe Photoshop CC 2015 (Macintosh)1720000/10000720000/100002655351308605a&� cHRMz%������u0�\`:�o�\_�FPLTE�����������������������ȹ����������������������������������������������������������˻����������������������������Ŀ�¿�ý����������������������������������������������������������������������������������Ȼ�û����ɻ����������������������������þ����̻�˻�ӻ�л�������������˿�ɾ�ź�������ڻ�ռ������������������������������ڻ�׾�ʻ����������˺����������������������������������������������������������������ý���������������������������������������B��C��D��F��H��K��L��L��N��P��P��S��U��X��Z��\]��b��e��g��i��l��q��t��u��x��{�ǀ�Ʌ�̌�Β�ї�ӛ�֢�ا�ڬ�ݲ�߸������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������v���tRNS���������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������S�%eIDATx���y\|\[՝����dɻd\[^��Nb;��6��$aM ��-$a+mg\ + +��l��p�f�!lV�"<�f��\]�:mD�X�l�:Gq1!��Hfm��<)����Z�Q�8۾��H�9�7\[���ƽ�unЩ��V#Z?z�{�z���dG��jQ��p��,��ƚ��f�%$��S���\ + +���1)կOa\]!ǹ���wM��� ��;��\_ډ��T�ⱎj�Q�T�X��!�\*Y�Q;��Zz��rcUm�Ԍ�-���H�pKBq���\_Y\`��b\_������E��,}Q\*���?���)�y��G�f^l��B@y\\͞qn�Z��ڼe!I��ģװ�z�ތ:'ر7ږ��L�f��/ + +�i��'��������\]^mF��븑���s�\\J#l��wvMm�yσV��y�����b-����Re�\` ߘ�ܛ�0�t�\|��B+����N�� + +�Z ��u?ٵ&��lR�le�=o�\ +J� S~��8���dV;Bqt,�\`�&���q&pH�lѮ�X�jGجv{r%��t��6��\ +�����ׯ=�–�j\_V;BqtvY��{���y�$�.nM\\d�o���֑�3o������Y�����������a��C&\[+;y�+Na��\_9�V<)���i�������ǚՅ�a�j�������g�Tͬ�\[��s���w\_.O��B�.��$5B4�ˌ���F�q��E�� ����%�f�A�8f%X\|�Em�y����H�r��<�7��8OQ�0�X1�\ + +9p�\]�\|؎�!G����g�ۚ�{����,�=Bq�0q�;5��\ +\\�R�����������\[c9.�ʩ���\\�����S�2�7)����;�m9�縓oQ\[\\U4�m�BY��mC\`�9\ +lW��g9�� ���WYY�3;\_H�N��u;;gY� �ѣXo)�3q�OQ\]�g�R�\*��,�4�\ +�';�K�P݇�)ߙ�\[)���, ͝�̳TE�U��\*?w�U�d�����X��\\NN\`�Eڥ�!P��!�qh��Ήғ�#��$Wˋ�\[���!?��\ +H�9�'Eqˁ� 3\_�J�@uQD\]�\\H-�S����r�9'O��X.���҄�jݿ�z�eWk ���d\_\[�(�:!�����h�� ��m;b��/��B\]��N �~�k�iaMt�٤\ +��,P���{��\*G(��@^�\]eVN�tI#B^����E�S�� X\ +kW��ra��\[P\]�\ +9j��J�Xg�bf�d �8��������!�����gў��j7"W��=�g��\*;ڰ���n�F�D���ֺ/2hWB��dUĪ'%}��jk�lC�/�������� ��5��-���ZJ�ُOA;I��;\[0p�Q?Ϫ+ C9Z{��V�Ą���ȉ��煴���������uد���YypD\\�&�f&�\]AiX�\]םM��&zwke�K=�9?���\`Mz�r1�� Z�Pg��k#X.q�O�r��4\`����S�$۞�0B �V����?�Y��p������F�ݢ)1�/ܟ�4��;�������GQ9�՝N�S�����׊Y�h0�l�\\.���n��䚜��u��WM��\]����'�e@q$�@A����/ +suޝ����m�L��u�� +�����^�Y�o�p��N��PG\|Ř=G2�����%���7^��;z�)�b��u��@0WC�\`\`���B�W#e2Ķ�l��x� + +���yT�l�Է-� 6(P�<�S\\sJEQa��B����u�A&$U������\]N��\_�a��< +��^�&���#���� �"�Sp\*�˴�ء˘�gp�T��@���礽k���U�)��C�Y�٬&N� + +�\_9?���է^1��\ +�����r�j�\|�Y�s&�z�kf���S��d�J�g���AgG�C��1CY�QH�-�Z�aP�o�5��Cq��8;6㬊#��!�N�$��S��H�p���. ���E�5�Ϭk�}#�\ + +ו9���VU�:�n�3\\� ����u�6fb%̦�{�%�2�/e�r�ϸ@ِ����A�����<��+�TWY��9�(���Mǜ��\]�!'��NA���S����qd�Tf���.v5�����YXG2��Y��8\]U�.����Ȓ.���1-錭Uo���. Y�p����(�Ă4�9;z.�q�˄�� 2��?��2}�\`I�ӷ�#O�����Տ�Qe��R�8�#�H�e����槈\]7~��e" �l� @@06\|\ ���!�ض�1�:b��;oޖQ + +(p�Y����F������p���O��Ă�n�Λ\|�d� �.6 x\ + +v:R�0,R�/�����J���mM��Y�{s����/G��"e��6H�pH\|� C�o6ys�KL����ő��ئw�'L���Y�ɮ\|�\_8���o.��A������8��x̠�=a�O���o�Uiܩ:2�}@z�W����f5ő c٣fp�'\|�Jl���vŦ�g�q}�nՅ�'�@����oم�����������'� ���w@ޜ\|��vU��3�UI�ʆ�κ�g����t}�i+�5^\\���-��ő�.tw�1=mm�� +�WG�ޛ�; �\[}��B��;��Nf������\\�\_-\_�.�ς�H� (�ـL\|K��1m���������CG�Fg��v�̧F.��n�<#������m��W7�-���WAq$��81���n��0��4��2W�C��^��l�n�k����2!��m�L��O2�L3�W��-2�X��� �YP�Ԉ���N����k�\ + +���7Eq$���H1��Sf�ʲ�6/I��i�����\]؂�̾�u���̅ + +)�8�O�A\ +r�E�I�"D�����p@1������$1��\]7Z�bٍ��? �#,wa��K�ٰ�aKYh��Ɩ���߅7���UY4�̲C��V G���i��m� 8ݭ=��YHG"��ȦQf���ȿ�U+�"eK�;^�4��=G9�2�J�3��t�~��=G"&���I�����ӭ�rp� K��#��-�Uh��V�F�����n�-x�� Bq�����6���Ve��!�g�n������Hq$R,���DZř�r�Dzr,�9���v�g�9�,3�#�T�#Gd����?$��^q@�ֲ�C캀�G'��f�Q ˽�4�tqx�.�fyq�&\ +@��7���y�X$}���Hq$R�"Xl\*��e��e �/v�K!�۵kt�.B0�� A&ʅ��Mï�����z\]��^7���j�V5���H�=Gy�����9\\��ܵ�� h�}I3�d~��t�/F������ݿ�Y;^���8'�L�41!�R�a�s�B���d +���S&6u�Ϝ�ebM�X/FE���Ɲ;���1x�@�<���n�n�? +�#�� �\[4!���X�x,t�ܴ�\\0�,��s\_�����'��vE�8zk��&�.)~\ +�@@\_Y�\ +��}\\�H��Q(�^�6O\]��BW�v�� ?����Ҽކ��Jh6����kD��%��1���-�۟qL��OL���E�A��ifo"�rV��V���ed-\_�3��k����mu��.uD-��L�D��'�ij/b�\]��s�\`r�ߡX�\|hO/ m� ��d��i�#2u1~t�}�h���Ӭ���ނ�n(�V�8z���E�?�X$�Lڶ�=�?�41�/{�$��t�\]��&��K��r�Q(�^��OD�i���Q� +:u,�֧��'�S������~�:Z�+ު~lU{-�s�~���ukq�NU\ + +.�F�:�~Jm�J7e�)��q��֨C���U��V\ + +'���n=G�Xi~ϯ�l-�Jb��#��%ZR/(�{��͓��\|V�l\[\[�}��Rl2�c�gh���B� ���Wx���jB�T o���Yj���T�ž?풇� D\\<'BX�㛪�����;��W#h��5� �z�=�)��d�4��Mڥ�������z:����?�%}m}U�=$w��o\ + +�e{��m�j���K-'2�\ +��C���x�ح����m��''��(�L͝�B�WL� \*B(�5#!�cj���0�\ + +@�v֣�\*��h��1;��gq8�{Ϗ��ȅC����Y��.6Ǟ(��1k(b�Z�欍���=�����I/�Kߺ���jMl{��'�G�qUԞ\\�(Ÿ� ��ڈ��-K�u̲�l�����G^�q�=��N��ڐ8�������hW7�79���g$W�G�w�(�SC���V��� �ίb���h�K\ + +�U�IȲc~3=̏\_t(��.�#td�@TW�6oM(:j��ʻ�ۯ�b�����96Z��P%\_9��x��FU/�F����+7P�� Y��Vv5LP:\]��W�45�C^���}k�'�2�d8��?47\ +dN��\_=<��ϝe��Z��k�l����7E���ӡ;c�O��+^5^0������U�Ꞧ�j���\ +'���K-��Y���ѫ�Q�@s׸���&�tO�YC-�����K�d��鶕i3�S�\[�f�����9ެƏ�ĝ�8��s�z��&&�~��FQ�<�3\ +��v���{��Xi�=�\[#��\ +��\|�5�vUz��'�ʒ������8��@c������y�e=��)9ڎ�O;\*�^³!/�I~b��+:::n@��~�S �8D��㞣3���<�^���v�\ + +9���Z?�h$��4w���}m�3�8�2�8r�� �1\\X���)<��SY�\*«ڽg��R�F��J/�j��Ɩ�a�����-�o\ +w�^Ln��q�,���\*��0�N ����� ��l\[�'k}�\]jT����j#p⺿A6�:�\|kz��0���jV�9�9�K�d\ + +����m眙�՚�Z��K��Kk#� �P�a�X�呩T�wg �7�/�Ff��\\u�!��q��vU\`����^�\|r�,���S�<�z�/��Zj����'�R���yFZ�ݕS�d}� ����!g�������.��6\ + +�!����D}�\[z����\_�\|��b�Ym�6�!V�\ +���:�I:j#�q:���g-\ +8w��)\]��ʗ\ +ȱ#��v�1�'�(˕I&obmؽO��\|ZM��\ + +@l��Z�N��e���IUq�w�����7G��v?ʅx���s�O��^�z�M���F���L2i�������Ϣ����J��\\�ӷcj����������B���Zr��&�I �Il�����(y�����bEP����}@���2i#p��W��y����T(�\*�<���p�9c�l8����\|��G�ײG2\]sВī���&�^��4�S~ugv�pY�����1�ˈ�o-��&O���8J��nm�����ϊ���EG'\[�xfu�,���G��<��W�B�\ +�ƭG�6��u)�V���r�\*�)dɶ� �A{?%�Y o\|\_��L��}V�\ +��4��w#� \|ͱ�nٓ\\�7��?�����Iɢ8N�\ +���c�kځl:~�VQ�d;�cAWϛG�JT�L5� ?�mx�3K��eA�\\aJ�ꇶ��5mT5�'��.�\*������I�p��\_��\*��T���Ƴ�@�Ev{��㚺E��$ph��3�c��������4"���oe��@İ�V�$���d�#��1�l���(��0�妶���n($�m�o�~�e����1�q�<�yI��\`�m��eّH��ah��~�M/�h�����H�7Z/v�A�ʩ�x\[�s���N�)\ +� Ȋ�\]4J�����q��~�����M�8�Y=eV�D�9:��ϡLR�7�\]�u�Z��q���io����"\_V�����/�4��)�Zl^j0��k�{���GwI�W�# �\]�P=�omh����G@���iX�R�8:��x5���#�ߝ�ݲt��L�5���ɻ��#+�X�\ + +�����\`o�ٗ�e:�d�S�y�Fu�L꘴ �Oh���ͿcQg�\ +���V�D�upwb7 ��ʷ����;�t�ڼTnڻ\ + +��8��h��zn-C�qn��S�R{���p \[:������d�9���������v�k�{\ + +,�~��?�\|\_�0,�@3���H���\\�M���a�S���q����~D\[�YM�'��1�$�$��ΰ��Lm�\ + +6�8${��dZ��s4sJ������\`�^��o��0�5�śKi\*Bq4�o\`��n0���m�b�^\]���W����B�"�O�B�z'�a���{&���ꯖ���\\�c��sL��#���nz#����lS�È����aJI���׈� ���\\��w��� ��x�%�#���F����t�Ѹ^�\ + +�N0�f�p�F��Y\ +d��u�i"!����j�mD��nӱXD�o�,���B��=�'ԙ\_�уV�\\,7��Ni�YA��G�\ + +m�����Cw�p��H��&sW��l^ٹ�t8���#^լ&Ă �ۍ�E��ꄋ���H����G�\|l^l~�F��p��H��B����+\ +��sY�őx{m�7\ +6���d:\\�����H�1�tb��(���H��x��uخ9��6h8Bq$�̀�t8�m�J�&ӡ<��#G����m�F��Xl: �LBq$^�!�������8�N��p��H�������򳦰���H�P�w��x��x��� ۺL�k���#G�ݤk"L�C\_Yw��I  �x$\\\[M�@w�9Ʒ��\`%F��i����E�z���yC 4�{���U����W\ +�4�8o'm�:�����qh������F(���Y�Xn:���X���@���ܼ��:�\ +4�8���y����Y��M��Nky��ߪ�G�1q邧i4Bq$s��� &m���� :�c�j:������1��MF<��V e4���˄UgG�0�mU����v �KYS\\\|�\`���{�p�\[;MF(�S��B�c��%��j#��H��%^�P���<2rѰ:&-�ߗA����,T8�I�c,1W���zI�j�6����ow�=o\\Y��2�P�\ +��t^�o�Xm�f����7�R���2U�jV L�1�/���V��st/UDꌋN��rqkZ��4ɠZ�&�'h\*B��IS����X=��������E�l�t�ߝKC��s�ݿ�u��ށKw�\`ܼe��!\|�u�1m�������IT v�׳\`ܜ\_}�Z��bZ{s\\�K��H(��␲�<\`P\_��qw2�\ + +��H$�&58I��#q\[�ڃ�J�0(���\ +S/\`SI�عP\[:��v�\`04;䙎�c�H$���� ��r$�G�8�\\�I�N�$�#�E�����iݫ#\ +����$���\[\|���"-J���/Y~��#qqt��8�O�f5!�P !��H!GB�8BőB(��Bq$�Bq$��#!�P !��H!GB�8BőB(��Bq$��#!�P !��H!GB�82�d���H<#�6\[���8�8�@�ֽ䀞'G����ֽAZ�P�GpPT�έ��a�� őx�z�g�V�@-N(��3螵N����&G�!t�¬��}�ڛP���5Y�l�(D@\_;�M(��C�l�f�TM47�8��u�Y�����IkOÇ&�����;�wi�\[imBϑx���zf�Q�6P őx!\[\\5�M���҄�H<��\\#���\`�JM���ZAK�Ch��\]e0��T�c�Z���qi���/\ + +�{&���:V١�!@{+��\`�#�^% ����vld�L!�K�oT\ +�z��E3Bd0XJq$.�}��B#�t;%��ѝ��N�����!(&�+����j�R2��=���c\_cx�"+�j--��Y��1�a����W�S��N\_i�%�gؾ&wEx�� 2���6�#!��YM!GB�8BőB(��Bq$�Bq$��#!�P !��H!GB�8BőB(��Bq$����L�l;�IEND�B\`� + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitQuickStart/Glossary/Glossary.html + +Documentation Archive Developer + +Search + +Search Documentation Archive + +Previous + +# Glossary + +- **ad hoc provisioning profile** +A type of distribution provisioning profile used for distributing iOS, tvOS, and watchOS apps for testing. + +- **Apple Developer Program** +Subscription services that offer Apple developers access to technical resources and support to develop iOS, watchOS, tvOS, and Mac apps for the store. + +- **Apple Push Notification service (APNs)** +Apple service for propagating information to apps running on different platform devices. + +- **Apple ID** +An Apple-issued developer account with a name and password. Developers use their Apple ID credentials to sign in to any of the Apple Developer Program tools. A developer or Apple ID can belong to multiple teams. + +- **CloudKit** +An app service that stores structured application and user data in iCloud. + +- **container** +A data store containing multiple database used by one or more apps. The default container ID matches the app’s bundle ID. + +- **container ID** +A unique identifier for an app’s iCloud container. + +- **database** +The portion of a container used to store records. There’s one public database for the app and multiple private databases—one private database for each user. + +- **development environment** +Databases used to develop your app and evolve the schema that is not accessible by apps sold on the store. + +- **field** +A property of a record type that can be set using a key-value pair. + +- **iOS App file** +A type of OS X file that can be installed on iOS and tvOS devices. + +- **just-in-time schema** +Development environment feature that allows an app to create a schema by saving records. + +- **predicate** +An object that defines logical conditions for searching for objects conforming to key-value coding. + +- **private database** +A database for storing records owned by the current user that are not readable by the app unless the user enters their iCloud credentials on the device. + +- **production environment** +Databases accessed by apps sold on the store. + +- **public database** +A database for storing records owned by the app that are shared between users. An iCloud account is not required to read records but is required to write records. + +- **push notifications** +A notification from a provider to a device transported by APNs. + +- **record** +An instance of a record type that can be created, read, and written to a database. + +- **record identifier** +An identifier for the location of a record in a database. Contains a record name and zone. + +- **record name** +A unique identifier for a record within a given zone. The record name is supplied by the app and can be used as a foreign key in another data source. + +- **record type** +A template for a set of records that have common fields. + +- **record zone** +A partition of a database to store records. Each database has a default zone and allows additional custom zones. + +- **relationship** +A record type field that associates one record to another. + +- **schema** +A collection of metadata that describes the organization of records, fields, and relationships in a database. In CloudKit, the schema includes record types, security roles, and subscription types. + +- **security role** +Permissions for a group of users to create, read, and write records in the public database. The possible roles are world, authenticated, and creator. + +- **store** +Used as a short form of the App Store, Apple TV App Store, or the Mac App Store when there’s no distinction between them. + +- **subscription** +A persistent query on the server that triggers notifications when records change. + +- **to-many relationship** +An association between a single record and one or more other records. + +- **to-one relationship** +An association between a single record and another single record. + +- **tvOS** +The operating system the runs on an Apple TV device. + +* * * + +[](http://www.apple.com/legal/internet-services/terms/site.html) \| [](http://www.apple.com/privacy/) \| Updated: 2017-09-19 + +--- + +# https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/DesigningforCloudKit/DesigningforCloudKit.html + +Documentation Archive Developer + +Search + +Search Documentation Archive + +Next Previous + +# Designing for CloudKit + +CloudKit provides a way to store data as records in a database that users of your app can share. Record types are used to differentiate between records storing different types of information. Each record is a dictionary of key-value pairs, with each key representing one field of the record. Fields can contain simple types (such as strings, numbers, and dates) or more complex types (such as locations, references, and assets). + +You can represent all the persistent model objects in your app using a CloudKit schema. However, the CloudKit framework should not be used to replace model objects in your app and should not be used for storing objects locally. It is a service for moving data to and from iCloud and sharing data between users of your app. It’s your responsibility to convert model objects to records that you save using CloudKit, and to fetch changes made by other users and apply those changes to your model objects. + +With CloudKit, you decide when to move data from your app to iCloud and from iCloud to your app. Although CloudKit provides facilities to keep you informed when changes occur, you must still fetch those changes explicitly. Because you decide when to fetch and save data, you are responsible for ensuring that data is fetched at the right times and in the right order, and you are responsible for handling any errors that arise. + +Once you have a native CloudKit app, you can provide a web app that accesses the same containers as your native CloudKit app. To get started creating a native CloudKit app and using the developer tools, read _CloudKit Quick Start_. To create a web app, see _CloudKit JS Reference_ or _CloudKit Web Services Reference_. + +## Enabling CloudKit + +Before you can use CloudKit, you must enable your app’s target in the Xcode project to use iCloud and CloudKit. Using Xcode to configure CloudKit adds the necessary entitlements to your app and configures your app to use a default container based on its bundle ID. You can create additional containers and also share them between your apps. As soon as Xcode creates the containers for you, you can access them using the CloudKit Dashboard web tool. To enable CloudKit in your Xcode project and to use CloudKit Dashboard, read Enabling CloudKit in Your App. + +## Containers and Databases + +Like other iCloud technologies, CloudKit organizes data using containers. A container represents your app’s iCloud storage. At runtime, you can perform tasks against a specific container using a `CKContainer` object. + +Each container is divided into public and private databases, each of which is represented by a `CKDatabase` object. Any data written to the private database is visible only to the current user and is stored in that user’s iCloud account. Data written to the public database is visible to all users of the app and is stored in the app’s iCloud storage. + +For a running CloudKit app, a container’s public database is always readable, even when the user is not signed in to their iCloud account on the device. Saving records to the public database and accessing the private database requires that the user be signed in. If your app does more than read data from the public database, check to see whether the user is signed in before saving records. To avoid errors, disable the parts of your user interface that save records until the user signs in. + +To check the iCloud credentials for a CloudKit app, read Alert the User to Enter iCloud Credentials. + +## Managing Data in CloudKit + +Inside the public and private databases, you organize your app’s data using records, represented by instances of the `CKRecord` class. You fetch and save records using either operation objects or convenience methods in the `CKContainer` and `CKDatabase` classes. Operation objects can operate on multiple records at once and can be configured with dependencies to ensure that records are saved in the proper order. Operation objects are based on the `NSOperation` class and can be integrated with your app’s other workflows. + +If you know the ID of the record you want, use a fetch operation. If you do not know the ID of a record, CloudKit provides the ability to query for records using a predicate. A predicate-based query lets you locate records whose fields contain certain values. You use this predicate with a `CKQuery` object to specify both the search criteria and sorting options for the returned records. You then execute the query using a `CKQueryOperation` object. + +Alternatively, use subscriptions to let the server notify you when certain parts of the database change. Subscriptions act like a persistent query on the server. You configure a `CKSubscription` object much as you do a `CKQuery` object, but instead of executing that query explicitly, you save the subscription to the server. After that, the server sends push notifications to your app whenever a change occurs that matches the predicate. For example, you can use subscriptions to detect the creation or deletion of records or to detect when the field of a record changes to a specific value. Upon receiving the push notification from the server, you can fetch the changed record and update your object model. + +To save and fetch records, read Creating a Database Schema by Saving Records and Fetching Records. To subscribe to record changes, read Subscribing to Record Changes. + +## The Development and Production Environments + +CloudKit provides separate development and production environments for storing your container’s schema and records. The development environment is a more flexible environment that is available to members of your development team. In the development environment, your app can save records. Or you can add fields to records that aren’t in the schema and then CloudKit creates the corresponding record types and fields for you. This feature is not available in the production environment. + +When you are ready to distribute your app for testing, you migrate the development schema to the production environment using CloudKit Dashboard. (CloudKit Dashboard does not copy the records from the development to the production environment.) After you deploy the schema to the production environment, you can still modify the schema in the development environment but can’t delete record types and fields that were previously deployed. When exporting your app from Xcode to distribute it for testing, you can choose whether to target the CloudKit development or production environment. + +When you are ready to upload your app to iTunes Connect to distribute your app using TestFlight or the store, Xcode automatically configures your app to use the production environment. An app uploaded to iTunes Connect can be configured to use only the production environment. + +To perform these tasks, read Testing Your CloudKit App and Deploying the Schema. + +## The Basic CloudKit Workflow + +Most CloudKit operations are performed asynchronously and require that you provide a completion handler to process the results. All operations rely on the user being connected to the network, so you should be prepared to handle errors that may occur. Your app should also be mindful of the number of requests it makes and size of the data that is transmitted back and forth to iCloud. Here’s the basic workflow of a typical CloudKit app: + +1. Fetch records needed to launch your app and initially present data to the user. + +2. Perform queries based on the user’s actions or preferences. + +3. Save changes to either the private or public database. + +4. Batch multiple save and fetch operations in a single operation. + +5. Create subscriptions to receive push notifications when records of interest change. + +6. Update the object model and views when the app receives changes to records. + +7. Handle errors that may occur when executing asynchronous operations. + +CloudKit saves each record atomically. If you need to save a group of records in a single atomic transaction, save them to a custom zone, which you can create using the `CKRecordZone` class. Zones are a useful way to arrange a discrete group of records, but they are supported only in private databases. Zones cannot be created in a public database. + +To batch operations, read Batch Operations to Save and Fetch Multiple Records. + +## Tips for Designing Your Schema + +When defining your app’s record types, it helps to understand how you use those record types in your app. Here are some tips to help you make better choices during the design process: + +- **Organize your records around a central record type.** A good organization strategy is to define one primary record type and additional record types to support the primary type. Using this type of organization lets you focus your queries on your primary record type and then fetch any supporting objects as needed. For example, a calendar app might define a single calendar record (the primary record type), as well as multiple event records (a secondary record type) corresponding to events on that calendar. + +- **Use references to represent relationships between your model objects.** Use a `CKReference` object to represent a formal one-to-one or one-to-many relationship between model objects. References also let you establish an ownership model between records that can make deleting records easier. + +- **Include version information in your records.** A version number can help you decide at runtime what information might be available in a given record. + +- **Handle missing keys gracefully in your code.** For each record you create, you are not required to provide values for all keys contained in the record type. For any keys you do not specify, CloudKit sets the corresponding value to `nil`. Your app should be able to handle keys with `nil` values in an appropriate way. Being able to handle these “missing keys” becomes important when new versions of your app access records created by an older version. + +- **Avoid complex graphs of records.** Creating a complex network of references between records may result in problems later when you need to update or delete records. If the owner references among your records are complex, it might be difficult to delete records later without leaving other records in an inconsistent state. + +- **Use assets for discrete data files.** When you want to associate images or other discrete files with a record, use an Asset type (a `CKAsset` object in your code) to represent that field in the record. The total size of a record’s data is limited to 1 MB, though assets do not count against that limit. + +To add references to your record types, read Adding Reference Fields. To store large files or location data, read Using Asset and Location Fields. For data size limits, see “Data Size Limits” in _CloudKit Web Services Reference_. + +## Tips for Migrating Records to a New Schema + +As you design the record types for your app, make sure those records meet your needs but do not restrict you from making changes to the schema in the future. After you deploy the schema to the production environment, you can add fields to a record, but you cannot delete a field or change its data type. Follow these tips to make updating your schema easier in the future: + +- **Add new fields to represent new data types.** A new version of your app can add the missing keys to records as it fetches and saves them to the database. + +- **Define record types that do not lose data integrity easily.** Each new version of your app must create records that do not break older versions of the app. The best way to ensure data integrity is to minimize the amount of validation required for a record: + +- Avoid fields that have a narrow range of acceptable values, the changing of which might cause older versions of the app to treat the data as invalid. + +- Avoid fields whose values are dependent on the values of other fields. Creating dependent fields means you have to write validation logic to ensure the values of those fields are correct. Once created, this kind of validation logic is difficult to change later without breaking older versions of your app. + +- Minimize the number of required fields for a given record. As soon as you require the presence of a field, every version of your app after that must populate that field with data. Treating fields as optional gives you more flexibility to modify your schema later. +- **Handle missing keys gracefully.** If a record is missing a key, add it in the background. + +To modify your schema using CloudKit Dashboard, read Using CloudKit Dashboard to Manage Databases. + +* * * + +[](http://www.apple.com/legal/internet-services/terms/site.html) \| [](http://www.apple.com/privacy/) \| Updated: 2015-12-17 + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitQuickStart/EnablingiCloudandConfiguringCloudKit/EnablingiCloudandConfiguringCloudKit.html) + +- CloudKit +- Enabling CloudKit in Your App + +Article + +# Enabling CloudKit in Your App + +Configure your app to store data in iCloud using CloudKit. + +## Overview + +Once you’ve determined that CloudKit is right for your app, you’re ready to set up your Xcode project to enable CloudKit development. + +### Add the iCloud capability to your Xcode project + +Adding the iCloud capability to your project sets up the initial project entitlements. Before you proceed, verify that your Apple Developer Program membership is active and has admin permissions. + +To add the iCloud capability: + +1. In the Xcode Project navigator, select your project and your project target. + +2. Click the “Signing and Capabilities” tab and select “Automatically manage signing.” + +3. Specify your development team. + +4. Make sure that your bundle identifier is one you want to use for your app. (This identifier determines the name of the iCloud container created in a later step.) + +5. Click the + Capability button, then search for iCloud in the Add Capability editor and select that capability. An iCloud section appears on your app’s Signing and Capabilities page. + +### Create your container + +Next, add the CloudKit service to add the appropriate entitlements to your project and tell iCloud to create a container for your app data: + +1. Select the CloudKit checkbox. In addition to adding the CloudKit capability to your app, this selection also creates an iCloud container and adds the Push Notifications capability. The name of the container is your app’s bundle identifier prefixed with “iCloud.” + +2. Check the box next to the container name. + +Multiple apps and users have access to iCloud, but each app’s data and schema, together, are typically in separate containers. Although an app can have multiple containers or share a container, each app has one default container. Once you’ve created a container, you can’t delete or rename it. + +### Select or create an iCloud account for development + +You need an iCloud account to save records to a container. In your app or the simulator on which you test your app during development, enter the credentials for this iCloud account. If you don’t have an iCloud account, create one for use during development. In macOS, launch System Preferences and click Sign In. Click Create Apple ID under the Apple ID text field and follow the instructions. + +Note that your iCloud account is distinct from your Apple Developer account; however, you can use the same email address for both. Doing so gives you access to your iCloud account’s private user data in CloudKit Dashboard, which can be helpful for debugging. + +### Enter iCloud credentials before running your app + +Enter your iCloud account credentials on a simulator or app-testing device. Entering the iCloud credentials enables reading from—and writing to—users’ own private and shared databases and, potentially, writing to the container’s public database. + +To enter your credentials on an iOS or iPadOS device: + +1. Launch the Settings app and click “Sign in to your iPhone/iPad.” + +2. Enter your Apple ID and password. + +3. Click Next. Wait until the system verifies your iCloud account. + +4. To enable iCloud Drive, choose iCloud and then click the iCloud Drive switch. If the switch doesn’t appear, iCloud Drive is already enabled. + +To enter your credentials for macOS, go to System Preferences. + +### View your container in CloudKit Console + +CloudKit Console is a web-based tool that lets you manage your app’s iCloud containers. It appears within the Apple Developer web portal, and you can use it to ensure that your container exists. + +1. Using a web browser, such as Safari, navigate to the CloudKit Console webpage at + +2. If you’re asked to sign in, enter your credentials and click Sign In. + +3. On the subsequent page, verify that your container appears in the container list. + +For more information on CloudKit Console, see Managing iCloud Containers with CloudKit Database App. + +## See Also + +### Essentials + +Deciding whether CloudKit is right for your app + +Explore the various options you have for using iCloud to store and sync your app’s data. + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitQuickStart/Art/intro_2x.png) + +View in English#) + +# The page you’re looking for can’t be found. + +--- + +# https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/Chapters/iCloudFundametals.html + +Documentation Archive Developer + +Search + +Search Documentation Archive + +Next Previous + +# iCloud Fundamentals (Key-Value and Document Storage) + +From the perspective of users, iCloud is a simple feature that automatically makes their personal content available on all their devices. To allow your app to participate in this “magic,” you design and implement your app somewhat differently than you would otherwise; in particular, you need to learn about your app’s roles when it participates with iCloud. + +These roles, and the specifics of your iCloud adoption process, depend on your app. You design how your app manages its data, so only you can decide which iCloud supporting technologies your app needs and which ones it does not. + +This chapter gets you started with the fundamental elements of iCloud key-value and document storage that all developers need to know. + +## First, Provision Your Development Devices + +To start developing an iCloud app, you must create an App ID and provisioning profile, described in _App Distribution Quick Start_. Then enable the iCloud service you want to use, described in Adding iCloud Support in _App Distribution Guide_. For a list of the app services that are available for your platform and type of developer program membership, see Supported Capabilities. + +## iCloud Data Transfer Proceeds Automatically and Securely + +For most iCloud services, your app does not communicate directly with iCloud servers. Instead, the operating system initiates and manages uploading and downloading of data for the devices attached to an iCloud account. For all iCloud services, the high-level process for using those services is as follows: + +1. Configure the access to your app’s _iCloud containers_. Configuration involves requesting entitlements and programmatically initializing those containers before using them. + +2. Design your app to respond appropriately to changes in the availability of iCloud (such as if a user signs out of iCloud) and to changes in the locations of files (because instances of your app on other devices can rename, move, duplicate, or delete files). + +3. Read and write using the APIs of the technology you are using. + +4. The operating system coordinates the transfer of data to and from iCloud as needed. + +The iCloud services encrypt data prior to transit and iCloud servers continue to store the data in an encrypted format, using secure tokens for authentication. For more information about data security and privacy concerns related to iCloud, see iCloud security and privacy overview. + +## The iCloud Container, iCloud Storage, and Entitlements + +To save data to iCloud, your app places data in special file system locations known as iCloud containers. An _iCloud container_ (also referred to as a _ubiquity container_) serves as the local representation of the corresponding iCloud storage. It is separate from the rest of your app’s data, as shown in Figure 1-1. + +**Figure 1-1**  Your app’s main iCloud (ubiquity) container in context![](https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/Art/iCloud_architecture_2x.png) + +To enable access to any iCloud containers, you request the appropriate entitlements. + +### Request Access to iCloud Using Xcode Capabilities + +The Capabilities tab of your Xcode project manages the creation of the entitlements and containers your app needs to access iCloud. After enabling the iCloud capability, Xcode creates an entitlements file (if one does not already exist) and configures it with the entitlements for the services you selected. As needed, Xcode can also handle any additional configuration, such as the creation of your app’s associated containers. + +When you enable iCloud Documents, Xcode configures your app to access the iCloud container whose name is based on the app’s bundle ID. Most apps should only need access to the default container. If your apps share data among each other, configure your targets to share containers, described in Specifying Custom Containers. When an app has access to multiple container IDs, the first ID in the access list is special because it is the app’s primary iCloud container. In OS X, it is also the container whose contents are displayed in the `NSDocument` open and save dialogs. + +For information about how to choose the correct iCloud technology for your app, see Choose the Proper iCloud Storage API. + +### Configuring a Common iCloud Container for Multiple Apps + +In the Xcode target editor’s Summary pane, you can request access to as many iCloud containers as you need for your app. This feature is useful if you want multiple apps to share documents. For example, if you provide a free and paid version of your app, you might want users to retain access to their iCloud documents when they upgrade from the free version to the paid version. In such a scenario, configure both apps to write their data to the same iCloud container. + +To configure a common iCloud container + +1. Designate one of your iCloud-enabled apps as the primary app. That app’s iCloud container becomes the common container. + +For example, in the case of a free and paid app, you might designate the paid app as the primary app. + +2. Enable the iCloud capability for each app. + +3. Configure the primary app with only the default container identifier. + +4. For each secondary app, enable the “Specify custom container identifiers” option and add the container identifier of the primary app to the list of containers. + +When reading and writing files in both your primary and secondary apps, build URLs and search for files only in the common storage container. To retrieve the URL for the common storage container, pass the container identifier of your primary app to the `URLForUbiquityContainerIdentifier:` method of `NSFileManager`. Do not pass `nil` to that method because doing so returns the app’s default container, which is different for each app. Explicitly specifying the container identifier always yields the correct container directory. + +For more information about how to configure app capabilities, see Adding Capabilities in _App Distribution Guide_. + +### Configuring Common Key-Value Storage for Multiple Apps + +If you provide a free and paid version of your app, and want to use the same key-value storage for both, you can do that. + +To configure common key-value storage for multiple apps + +1. Designate one of your iCloud-enabled apps as the primary app. + +That app’s iCloud container becomes the common container. For example, in the case of a free and paid app, you might designate the paid app as the primary app. + +3. Enable the key-value storage option for both apps. + +Xcode automatically adds entitlements to each app and assigns an iCloud container based on the app’s bundle ID. + +4. For all but the primary app, change the iCloud container ID manually in the app’s `.entitlements` file. + +Set the value of the `com.apple.developer.ubiquity-kvstore-identifier` key to the ID of your primary app. + +## iCloud Containers Have Minimal Structure + +The structure of a newly created iCloud container is minimal—having only a `Documents` subdirectory. For document storage, you can arrange files inside the container in whatever way you choose. This allows you to define the structure as needed for your app, such as by adding custom directories and custom files at the top level of the container, as indicated in Figure 1-2. + +**Figure 1-2**  The structure of an iCloud container directory![](https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/Art/icloud_directories_2x.png) + +You can write files and create subdirectories within the `Documents` subdirectory. You can create files or additional subdirectories in any directory you create. Perform all such operations using an `NSFileManager` object using file coordination. See The Role of File Coordinators and Presenters in _File System Programming Guide_. + +The `Documents` subdirectory is the public face of an iCloud container. When a user examines the iCloud storage for your app (using Settings in iOS or System Preferences in OS X), files or file packages in the `Documents` subdirectory are listed and can be deleted individually. Files outside of the `Documents` subdirectory are treated as private to your app. If users want to delete anything outside of the `Documents` subdirectories of your iCloud containers, they must delete _everything_ outside of those subdirectories. + +To see the user’s view of iCloud storage, do the following, first ensuring that you have at least one iCloud-enabled app installed: + +- In OS X, open System Preferences. Then open the iCloud preferences pane and click Manage. + +## A User’s iCloud Storage Is Limited + +Each iCloud user receives an allotment of complimentary storage space and can purchase more as needed. Because this space is shared by a user’s iCloud-enabled iOS and Mac apps, a user with many apps can run out of space. For this reason, to be a good iCloud citizen, it’s important that your app saves to iCloud only what is needed in iCloud. Specifically: + +- **DO** store the following in iCloud: + +- User documents + +- App-specific files containing user-created data + +- Preferences and app state (using key-value storage, which does not count against a user’s iCloud storage allotment) + +- Change log files for a SQLite database (a SQLite database’s store file must never be stored in iCloud) +- **DO NOT** store the following in iCloud: + +- Cache files + +- Temporary files + +- App support files that your app creates and can recreate + +- Large downloaded data files + +There may be times when a user wants to delete content from iCloud. Provide UI to help your users understand that deleting a document from iCloud removes it from the user’s iCloud account _and_ from all of their iCloud-enabled devices. Provide users with the opportunity to confirm or cancel deletion. + +One way to prevent files and directories from being stored in iCloud is to add the `.nosync` extension to the file or directory name. When iCloud encounters files and directories with that extension in the local container directory, it does not transfer them to the server. You might use this extension on temporary files that you want to store inside a file package, but that you do not want transferred with the rest of that package’s contents. Although items with the `.nosync` extension are not transferred to the server, they are still bound to their parent directory. When you delete the parent directory in iCloud, or when you evict the parent directory and its contents locally, the entire contents of that directory are deleted, including any `.nosync` items. + +### The System Manages Local iCloud Storage + +iCloud data lives on Apple’s iCloud servers, but the system maintains a local cache of data on each of the user’s devices, as shown in Figure 1-3. Local caching of iCloud data allows users to continue working even when the network is unavailable, such as when they turn on airplane mode. + +**Figure 1-3**  iCloud files are cached on local devices and stored in iCloud![](https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/Art/syncing_overview_2x.png) + +Because the local cache of iCloud data shares space with the other files on a device, in some cases there is not sufficient local storage available for all of a user’s iCloud data. The system addresses this issue by maintaining an optimized subset of files and other data objects locally. At the same time, the system keeps all file-related metadata local, thereby ensuring that your app’s users can access all their files, local or not. For example, the system might evict a file from its iCloud container if that file is not being used and local space is needed for another file that the user wants now; but updated metadata for the evicted file remains local. The user can still see the name and other information for the evicted file, and, if connected to the network, can open it. + +### Your App Can Help Manage Local Storage in Some Cases + +Document-based apps usually do not need to manage the local availability of iCloud files and should let the system handle eviction of files. There are two exceptions: + +- If a user file is not currently needed and unlikely to be needed soon, you can help the system by explicitly evicting that file from the iCloud container by calling the `NSFileManager` method `evictUbiquitousItemAtURL:error:`. + +- Conversely, if you explicitly want to ensure that a file is available locally, you can initiate a download to an iCloud container by calling the `NSFileManager` method `startDownloadingUbiquitousItemAtURL:error:`. For more information about this process, see App Responsibilities for Using iCloud Documents. + +## Prepare Your App to Use iCloud + +When users launch your iCloud-enabled app for the first time, invite them to use iCloud. The choice should be all-or-none. In particular, it is best practice to: + +- Use iCloud exclusively or use local storage exclusively; in other words, do not attempt to mirror documents between your iCloud container and your app’s local data container. + +- Don’t prompt users again about whether they want to use iCloud vs. local storage, unless they delete and reinstall your app. + +Early in your app launch process—in the `application:didFinishLaunchingWithOptions:` method (iOS) or `applicationDidFinishLaunching:` method (OS X)—check for iCloud availability by getting the value of the `ubiquityIdentityToken` property of `NSFileManager`, as shown in Listing 1-1. + +**Listing 1-1**  Obtaining the iCloud token + +| | +| --- | + +Access this property from your app’s main thread. The value of the property is a unique token representing the currently active iCloud account. You can compare tokens to detect if the current account is different from the previously used one, as explained in Handle Changes in iCloud Availability. To enable comparisons, archive the newly acquired token in the user defaults database, using code like that shown in Listing 1-2. This code takes advantage of the fact that the `ubiquityIdentityToken` property conforms to the `NSCoding` protocol. + +**Listing 1-2**  Archiving iCloud availability in the user defaults database + +If the user enables airplane mode on a device, iCloud itself becomes inaccessible but the current iCloud account remains signed in. Even in airplane mode, the `ubiquityIdentityToken` property contains the token for the current iCloud account. + +If a user signs out of iCloud, such as by turning off Documents & Data in Settings, the value of the `ubiquityIdentityToken` property changes to `nil`. To detect when a user signs in or out of iCloud, register as an observer of the `NSUbiquityIdentityDidChangeNotification` notification, using code such as that shown in Listing 1-3. Execute this code at launch time or at any point before actively using iCloud. + +**Listing 1-3**  Registering for iCloud availability change notifications + +After obtaining and archiving the iCloud token and registering for the iCloud notification, your app is ready to invite the user to use iCloud. If this is the user’s first launch of your app with an iCloud account available, display an alert by using code like that shown in Listing 1-4. Save the user’s choice to the user defaults database and use that value to initialize the `firstLaunchWithiCloudAvailable` variable during subsequent launches. This code in the listing is simplified to focus on the sort of language you would display. In an app you intend to provide to customers, you would internationalize this code by using the `NSLocalizedString` (or similar) macro, rather than using strings directly. + +**Listing 1-4**  Inviting the user to use iCloud + +Although the `ubiquityIdentityToken` property lets you know if a user is signed in to an iCloud account, it does not prepare iCloud for use by your app. In iOS, apps that use document storage must call the `URLForUbiquityContainerIdentifier:` method of the `NSFileManager` method for each supported iCloud container. Always call the `URLForUbiquityContainerIdentifier:` method from a background thread—not from your app’s main thread. This method depends on local and remote services and, for this reason, does not always return immediately. Listing 1-5 shows an example of how to initialize your app’s default container on a background thread. + +**Listing 1-5**  Obtaining the URL to your iCloud container + +This example assumes that you have previously defined `myContainer` as an instance variable of type `NSURL` prior to executing this code. + +## Handle Changes in iCloud Availability + +There are times when iCloud may not be available to your app, such as when the user disables the Documents & Data feature or signs out of iCloud. If the current iCloud account becomes unavailable while your app is running or in the background, your app must remove references to user-specific iCloud files and data and to reset or refresh user interface elements that show that data, as depicted in Figure 1-4. + +**Figure 1-4**  Timeline for responding to changes in iCloud availability![](https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/Art/changed_iCloud_availability_2x.png) + +To handle changes in iCloud availability, register to receive the `NSUbiquityIdentityDidChangeNotification` notification. The handler method you register must do the following: + +1. Retrieve the new value from the `ubiquityIdentityToken` property. + +2. Compare the new value to the previous value, to find out if the user signed out of the account or signed in to a different account. + +3. If the values are different, the previously used account is now unavailable. Discard any changes, empty your iCloud-related data caches, and refresh all iCloud-related user interface elements. + +If you want to allow users to continue creating content with iCloud unavailable, store that content in your app’s local data container. When the account is again available, move the new content to iCloud. It’s usually best to do this without notifying the user or requiring any interaction from the user. + +## Choose the Proper iCloud Storage API + +Apple provides the following iCloud storage APIs, each with a different purpose: + +- **Key-value storage** is for discrete values such as preferences, settings, and simple app state. + +Use iCloud key-value storage for small amounts of data: stocks or weather information, locations, bookmarks, a recent documents list, settings and preferences, and simple game state. Every app submitted to the App Store or Mac App Store should take advantage of key-value storage. + +- **iCloud document storage** is for user-visible file-based content, Core Data storage, or for other complex file-based content. + +Use iCloud document storage for apps that work with file-based content, such as word-processing documents, diagrams or drawings, or games that need to keep track of complex game state. + +- **CloudKit storage** is for storing data as individual records in a private or public database accessible by all your app’s users. + +Use CloudKit in situations where key-value storage and document storage are insufficient for your needs. To learn more about CloudKit, read Designing for CloudKit. + +Many apps benefit from using key-value storage with other types of storage. For example, say you develop a task management app that lets users apply keywords for organizing their tasks. You could employ iCloud document storage to store the task information and use key-value storage to save the user-entered keywords. + +If your app uses Core Data, either for documents or for a shoebox-style app like iPhoto, use iCloud document storage. To learn how to adopt iCloud in your Core Data app, see Designing for Core Data in iCloud. + +If your app needs to store passwords, do not use iCloud storage APIs for that. The correct API for storing and managing passwords is Keychain Services, as described in _Keychain Services Reference_. + +Use Table 1-1 to help you pick the iCloud storage scheme that is right for each of your app’s needs. + +| Element | iCloud document storage | Key-value storage | CloudKit | +| --- | --- | --- | --- | +| Purpose | User documents, complex private app data, and files containing complex app- or user-generated data. | Preferences and configuration data that can be expressed using simple data types. | Complex private app data and files, structured data, user-generated data, data that you want to share among users. | +| Entitlement keys | `com.apple.developer.` `icloud-services`, `com.apple.developer.` `icloud-container-identifiers` | `com.apple.developer.` `ubiquity-kvstore-identifier` | `com.apple.developer.` `icloud-services`, `com.apple.developer.` `icloud-container-identifiers` | +| Data format | Files and file packages | Property-list data types only (numbers, strings, dates, and so on) | Records, represented as collections of key-value pairs where values are a subset of property-list data types, files, or references to other records. | +| Capacity | Limited only by the space available in the user’s iCloud account. | Limited to a total of 1 MB per app, with a per-key limit of 1 MB. | Limited only by the space available in the user’s iCloud account (private database) and the app’s allotted storage quota (public database). | +| Detecting availability | Call the `URLForUbiquityContainerIdentifier:` method for one of your ubiquity containers. If the method returns `nil`, document storage is not available. | Key-value storage is effectively always available. If a device is not attached to an account, changes created on the device are pushed to iCloud as soon as the device is attached to the account. | The public database is always available. The private database is available only when the value in the `ubiquityIdentityToken` property is not `nil`. | +| Locating data | Use an `NSMetadataQuery` object to obtain live-updated information on available iCloud files. | Use the shared `NSUbiquitousKeyValueStore` object to retrieve values. | Use a `CKQuery` object with a `CKQueryOperation` to search for records matching the predicate you specify. Use other operation objects to fetch records by ID. | +| Managing data | Use the `NSFileManager` class to work directly with files and directories. | Use the default `NSUbiquitousKeyValueStore` object to manipulate values. | Use the classes of the CloudKit framework to manage data. | +| Resolving conflicts | Documents, as file presenters, automatically handle conflicts; in OS X, `NSDocument` presents versions to the user if necessary. For files, you manually resolve conflicts using file presenters. | The most recent value set for a key wins and is pushed to all devices attached to the same iCloud account. The timestamps provided by each device are used to compare modification times. | When saving records, assign an appropriate value to the `savePolicy` property of a `CKModifyRecordsOperation` object to specify how you want to handle conflicts. | + +| Metadata transfer | Automatic, in response to local file system changes. | Not applicable (key-value storage doesn’t use metadata). | Not applicable | + +**Table 1-1**  Differences between document and key-value storage + +* * * + +[](http://www.apple.com/legal/internet-services/terms/site.html) \| [](http://www.apple.com/privacy/) \| Updated: 2015-12-17 + +--- + +# https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/Art/iCloud_intro_2x.png + +�PNG + + +IHDR%���� pHYs  �� +OiCCPPhotoshop ICC profilexڝSgTS�=���BK���KoR RB���&\*! J�!��Q�EEȠ�����Q, � + +�b@q��S�(R�jJ��4�e�2AU��Rݨ�T5�ZB���R�Q��4u�9̓IK�����hh�i��t�ݕN��W���G���w\ +��Ljg(�gw��L�Ӌ�T071���oUX\*�\*\|��\ +�J�&�\*/T����ު U�U�T��^S}�FU3S� Ԗ�U��P�SSg�;���g�oT?�~Y��Y�L�OC�Q��\_�� c�x,!k\ +��u�5�&���\|v\*�����=���9C3J3W�R�f?�q��tN �(���~���)�)�4L�1e\\k����X�H�Q�G�6������E�Y��A�J'\\'Gg����S�Sݧ\ +�M=:��.�k���Dw�n��^��Lo��y���}/�T�m���G X� $� �<�5qo</���QC\]�@C�a�a�ᄑ��<��F�F�i�\\�$�m�mƣ&&!&KM�M�RM��)�;L;L���͢�֙5�=1�2��כ߷\`ZxZ,����eI��Z�Yn�Z9Y�XUZ\]�F���%ֻ�����N�N���gð�ɶ�����ۮ�m�}agbg�Ů��}�}��= + +y��g"/�6ш�C\\\*N�H\*Mz�쑼5y$�3�,幄'���L +Lݛ:��v m2=:�1����qB�!M��g�g�fvˬe����n��/��k���Y- +�B��TZ(�\*�geWf�͉�9���+��̳�ې7�����ᒶ��KW-X潬j9�������(�x��oʿ�ܔ���Ĺd�f�f���-�\[����n\ +�ڴ\ + +6\ +U����#pDy��� ��\ + +�D��\*2\*�wD1iXY���Z@��Wʋ��GE��/Q { ����עL�(��Sũ"\ +�� z�+W�t{f Ռ��&��l\_3��DI�+L�\ + +3C�f��Zy�d�'q�@/� T�ZK��y����q�.��h5$h�-��A��J��H��ٻ�u ^�2�:fI�\|��QC����\*�K���7����\|�\_rM�<ҿU\*�6�J "���Ku1H���oqςrc�$�h��Kp&"��C�����b�~��G��l��öO#�\ + +�%ig\_��Y�N�(xT4������K��I\ + +����ۍ\ +���YJ '��#����X2�g\[P���b�@�yGБ@Q�~��pHrx����,��\[\*Dz�G�\ +C%B ����8���?�x��L� � �S�~�O����dʁ����,�<����MC�ș���)���RvAE:��"TBDD�sr��k�:�g��w��~���W\ +8��hcsP�����3S���mDh�}�I}����Oߪ��,O��� �bTb����\|k��^���\_��\\�\]Qg� ��Id�ӴJZܡO�����\*��\ +ч�^�\_Q�T��QӅj�\]����S�q~��c�;���汬v9��X����l?RiKE�fg��H\|/qYV5���s1�K�\*i�W���D7J����Q/���kP%�{}NƖ�n�ݾ�U���,6�y{���9���K��u�LV��<�{�y�ֆ��)���t���m9��G��\|Bj��Z\\��e�A�7ND�\\��e�PVWq����6��L��\\Ziq���\[$4�}�7��ˊ�CQ��2�=�9�%��i�Т6ⒽE���˫TPf��\[e!��\|��X~� �A$��y��P�3�@�xTQf�a�Q�N�f����f�zU��ж���(\ +3���K��E�%0<л�����S���й���\ +�y�J\ +m��YGwnGuV�/��ԭM� +YJ�����Ys��J��\_dm���PI��)��S��Ob�{\[\]�t�e�z��2sEl\]��ԫ�5x7U���ދ���{Y$�4q��"k��=��j�Kڞ�)�gV<� �Hȳp��Vѳ#\*\*��'XG�cdQ����ͱ4�i$�Ņ����Օ,�5���<&��J� D����Լ���;s���j3k%:�U�����<��ܬŎ���\*��)���\\D��Ƹd��H�&�1��cZt��TVp����F�P%-�J��UMR�m�vM���U\[�\ +E�P�U��:&��$�<�i�ͅ�����V\]ѱl��t���%{�DRۙ�\\�ƅ}�\_�#�+:�wrQ�զW�����R���%\[n�cG�Wt�4�����\\�C=)w׸7\]O8�SaC��5�ތ)�2���;����23��U����FY�C\\�2\_�Y$D��W'Տ���V�����ӪR�n���t�q\_ݽ����N����8�ڊJ�&�< zf$}�wk�JDo���1��ZEq����@:��ܶ��֨�����u����N<ӕ��H+��^Ui���8�CT괓����N��Ş4Ց��TZzm�X��6Tk���^���\ + +Ay����%.ʩ��HE\*Q�J�V�~:�"O؉� K\]��y�\|\*Q�Jv�.�9��܎g��B��\[(�Z �޹�?uh��O�?�֔ J��X�/ ǻ�����j��\[�j��g�\`�"3і�ck^k@%W�Jv�<����Ҳ�T���n=��/lVHק�r zrNҜ)���:�ܬ�^Y�Ѭ�Q�-TPSG���8{�5\]�\*�UiK���λDD3�%���� v���ใm��ɛXƦN����C33��\]%�˫ˈ S���V:1����W\ + +ج)��d�J;J;�N""�\*�\`8� ��͑�1��%B�K�ܕa������ )"lL�JXo���\[���d��߲7�Ϊ���g���R�H�.��H��M���&Q}���R�i��� ���U{2V��\[)�.�/��8���Pe�\|\_�o��h4��-A��%͆��b!c\*9��������8N%�r}G�����M���Kj6j��gB��#�N2�������+)��8�̓��l ���M��~���=��'d\ +ta����%�X3M����dQ��#�������/\]��3���Sۡ� �d�#1���'Wh�ƅ&�)������\\�o���\_a���\*ivJ�D��jק�x�,dz��\ +�f\_\\Oz��eP��ǵ^z��3��(�\ +ǎ�{����=�j��k�=#R��35Ѓ����"�Ӿ:���\_��k.CVMP�#'�g"\]\_��ŵC�{kP�=(��!��h=s�b(:g+!�J���H+i~����,���ًc�ʧ+�S�\]�$��3/ :����菱��Ob�x�TRP qr˒�2��t��K�ҟhsb7yTҜ+��g�02Qg���\_�~�b�naK!\ + +�rA�4�63"���$G�������K�.ӍGJ����\|�3�b\ +�C%��d��3+ \[e��U��oK�O"�O=.�a91�\]���\[�?x3b�4�Dl@$����\_��9�U�)��\\b�\ +k�Ν+�n�iF�a�T}I�ȥ��V�A�A��p&��Dl�� ��x Mz���ȣ����+0\*o��X��z�\ + +�${V�L�M.3T���<@%��/Y �$���!��zT2�eN ��J��{��15�ffi�G�����UL�x/B%R���\]��;\*� ��隻P���K�#&F�$a�)�¨b\*�a5ހ�Q�~��7Q���9}/T�0������ߢ!�ދ̣Wj�Y�T;�� \_��X�{'T�p˕����Xq��P��/A�2�J���G}��\ + +�\\���J�d�yt'�b��Jص�5�$� �^Xxu�\_�=��۠�d/t��\\�11�\[������L� � XG�Z��\ +;\*�J�b����z���² }�-\_"�N����&V0�DE2��W%\ + +�g�Z?4�t��4�1��Y":Z�x$t������#Q�=ሻcD…/��Pr��0}f݈�;��W\*!���\\3�P2Ė/��b��\*!��%G�����Y��V%DDm援"��O!/�᫃xW Q�G=N}+�\_iȓ��^E�ը�������\`��t(����H$��\ +���B�ܐ����֢\`����H�ЄJ@hz�T$��\ +��\`Q�P��y�W@D���a\ +1,k��B""��c0\| ��Wղ� �\_��^�cl.��I\_�Ԏ}��ᣁk��?��\` Oםn��b3:�\`ݍ� �'1q8c\*� �Ζ��97�ذKX)D��4X�κ��Ű\ +��P�k}Q�7�;{���L����\`�-���Eb�HX�2!w�������E?S���}DD�Oh��\]kX~Ed̗T���'0�;��^�Q��+ʎޮ��u߂+����"c\*ij�ya{���\]mPv�KwuЀh�DJ�H�y \\lq��'\ +u笩��P�\ + +���"(@�P��q�5ZD���c�Q\ + +��ɵv�wWu�DDGf�N��n�"X!��)��۱�9�$��xhdL�s����W��\ +�dž���tO@%)�{Dl3���X�z;�uRq, VM�q�vf�˷V�сa�f 9��Wl��HȬ����+z�d�y�\_A�ㆦ���W��� �w���~S'C+�w�ֱ�$�h�V�(wv��J^D����Z͂Mc�'���� K�J��R\|<�?X�:�+�9A%�f�t�n��� ����;�t�Xs\[-f&�:ݥ���K��\[ꎰ�\\���#3P�6F���I�k���J FF���D��o��M��܎����&/}�Ril�\[)z��b�&��3����I�\]�)���8���pV�ەepg��{&�\\x�Rq�p��y�kuO�L��p�w�obsw���RY�籎^,�E�~?�9���NZ�;\|SQ̛�8hv�\\�&��.?GִO�g^�W{���so���y��Z\ +�9ԗ3iW,��֘�=���U�I2��}Z\]�)�xM����G����=�\ + +.���G�9�\|�;�����S�7IǨb���������ڞ�\ +��dS8�O.ӞH�t��������\]7&UD�?\_���7% ���3ק:?�"����~��:ɖ�����\]z�t���wٍ��<�)�EG�(���9� B���s7��"=�F�}��\]�N +\|��=��?�ON���r�D�U�bJC�kkG���J^��!��c��A �\|�o�b-��\_��1��<���1?0'O��I y�6rb{ل�g���Qღ��%�z ����R�zI�%�LE�1+��4��/ۯ�'M�ŵ�詎9 + +C&\*�q�ȨX�q��r$��o�!T"�N�O��/�������AGD�d�#��q^��!T"�C �<6<����1��C��{�Ⱥ��� �����j��4v�C'#D��D� �M\]�۳�� g�3$uv0G +��/\]\]��; + +���( +ho�� +go�#d�l���ņ�)�,n� + +-��zG"鹕��Yd:�z�-�\\\_����dM�'�GR Ot�93�2�J�͜cc�IIEo�1Y^Du�J4†�U!�X(o��b5��GM�J�G����;��3��Ng2��� B9�PGֽ7yw-:� �D�Y��z�W�}�T@��7K ��-��\|IkQ�91/�\ + +�Q�'�\*�r�\|=���X&��L�\_��0�p��\] +��a�xI�<���Ϭ~\]�dp4���%��;LD�,At� wE��6�7ɗ�N�N�ϗiP\\D� + +������h�%���?M����iN�X6�%\_B��D��8ÿ5��k�f�N�xU�M��E�S���=@$\*-. ݩ�L#���,�J��q�S��M��T\ +�(��Od�k\_F�%)�v����P�RX���\|��j��O���U���H9 �O4B%Ja�{��;T� \|t,�kg҈���7C\[�bKK=T�^����N���qR�����-���vP� ����f�Vo�J���B9�-P �tu�T���\|�(�?�@% ��E�� T2�ػD���� �^"����P b\|���ƗL�G���~땗oCq��J�3 ��QIs�X����y����%�vT\ +}�jQ s��1�P� ��d(�ҷ͝����)Uw\\���Y�(�U�+�� \*�R{���\_\ +K�.�h�D%�\*W E���=<є�Y���C����cϜ�/g�x�p԰�R��t�EOD���Tv�J%\*�od������ �����ʧ\\T�J:�f�̟yn��r�8H�+�t��9�\\�4U�dZ;��t��U�(rM1���ߣ�;W�(�/\*?�}5�Do�h��J�j���S����m�xd�\]��g��BL�V��������� S��Iڗ�����ڦt}�\\�T�6H��u���랯��{� ����&�Q�P�����ӷ��A2!�Wu^}ˉ9����9��\_:���\ +<(y?C�u��Ϋw�ϹJ.I����yT�n�ݖ�ǿ�,�Wx�\|�Bb��~���jTg��ݤjhY��Ь+��L�\ +�CZ�W�Eu����UB�G�qL�)d�P�C���?{����W�aZ�Q,���^"�N�k��G�׆#��N�h��uv�Y%<К�<��������X��frPFd4Q#��� d�.���,Q~U�6I�\ + +jTr�:��E�v�n�}�V�n�?�\[��Z}��\]�ە�ԘǕ�/��\`M�$��P \*\*\*\*@Qhi��� �;\\�����)��z�7�� Z\\���$ ���.YPc�u�K� Z\\���:f�R�tL�P%���J\`2'd\[���\_��������A%Zjq=ѓĽ�s�%@�,xE�w�U���O\|\]\ + +߳��"���D�F�=.��t�lD���M�\ + +��ޗ4~�(\_$�x��R����,6��k!�-l\ + +5\*�F\_��ғ� �Gj�Tzkk\*r΃4��hQYbw�cj��?��Sci.��5z;�; ��@%\*'؎�hq��������ҏ���{�S���(j T�n�~4�;� ���и/�3�@�{�E���T��ڸ�m�D8�\ +��K@ֹ�W2ݸ+\*\*!���J Z\\@%@%@%@%(��q9Mi�Y�\ +T�F���hq\_�\ +�����˨9P����4G�P P �K�<��L}�Txms\|�)���~T�#W�Ϗ���������\ +��U��60@%@��߆\ + +--- + +# https://developer.apple.com/library/archive/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/Introduction/Introduction.html + +Framework + +# UIKit + +Construct and manage a graphical, event-driven user interface for your iOS, iPadOS, or tvOS app. + +## Overview + +UIKit provides a variety of features for building apps, including components you can use to construct the core infrastructure of your iOS, iPadOS, or tvOS apps. The framework provides the window and view architecture for implementing your UI, the event-handling infrastructure for delivering Multi-Touch and other types of input to your app, and the main run loop for managing interactions between the user, the system, and your app. + +UIKit also includes support for animations, documents, drawing and printing, text management and display, search, app extensions, resource management, and getting information about the current device. You can also customize accessibility support, and localize your app’s interface for different languages, countries, or cultural regions. + +UIKit works seamlessly with the SwiftUI framework, so you can implement parts of your UIKit app in SwiftUI or mix interface elements between the two frameworks. For example, you can place UIKit views and view controllers inside SwiftUI views, and vice versa. + +To build a macOS app, you can use SwiftUI to create an app that works across all of Apple’s platforms, or use AppKit to create an app for Mac only. Alternatively, you can bring your UIKit iPad app to the Mac with Mac Catalyst. + +## Topics + +### Essentials + +Adopting Liquid Glass + +Find out how to bring the new material to your app. + +UIKit updates + +Learn about important changes to UIKit. + +About App Development with UIKit + +Learn about the basic support that UIKit and Xcode provide for your iOS and tvOS apps. + +Secure personal data, and respect user preferences for how data is used. + +### App structure + +UIKit manages your app’s interactions with the system and provides classes for you to manage your app’s data and resources. + +Manage life-cycle events and your app’s UI scenes, and get information about traits and the environment in which your app runs. + +Organize your app’s data and share that data on the pasteboard. + +Manage the images, strings, storyboards, and nib files that you use to implement your app’s interface. + +Extend your app’s basic functionality to other parts of the system. + +Display activity-based services to people. + +Create a version of your iPad app that users can run on a Mac device. + +### User interface + +Views help you display content onscreen and facilitate user interactions; view controllers help you manage views and the structure of your interface. + +Present your content onscreen and define the interactions allowed with that content. + +Manage your interface using view controllers and facilitate navigation around your app’s content. + +Use stack views to lay out the views of your interface automatically. Use Auto Layout when you require precise placement of your views. + +Apply Liquid Glass to views, support Dark Mode in your app, customize the appearance of bars, and use appearance proxies to modify your UI. + +Provide feed + +Responders and gesture recognizers help you handle touches and other events. Drag and drop, focus, peek and pop, and accessibility handle other user interactions. + +Encapsulate your app’s event-handling logic in gesture recognizers so that you can reuse that code throughout your app. + +Simplify interactions with your app using menu systems, contextual menus, Home Screen quick actions, and keyboard shortcuts. + +Bring drag and drop to your app by using interaction APIs with your views. + +Support pointer interactions in your custom controls and views. + +Handle user interactions like double tap and squeeze on Apple Pencil. + +Navigate the interface of your UIKit app using a remote, game controller, or keyboard. + +Make your UIKit apps accessible to everyone who uses iOS and tvOS. + +### Graphics, drawing, and printing + +UIKit provides classes and protocols that help you configure your drawing environment and render your content. + +Create and manage images, including those that use bitmap and PDF formats. + +Configure your app’s drawing environment using colors, renderers, draw paths, strings, and shadows. + +Display the system print panels and manage the printing process. + +### Text + +In addition to text views that simplify displaying text in your app, UIKit provides custom text management and rendering that supports the system keyboards. + +Display text, manage fonts, and check spelling. + +Manage text storage and perform custom layout of text-based content in your app’s views. + +Configure the system keyboard, create your own keyboards to handle input, or detect key presses on a physical keyboard. + +Add support for Writing Tools to your app’s text views. + +Configure text fields and custom views that accept text to handle input from Apple Pencil. + +### Deprecated + +Avoid using deprecated classes and protocols in your apps. + +Review unsupported symbols and their replacements. + +### Reference + +This document describes constants that are used throughout the UIKit framework. + +The UIKit framework defines data types that are used in multiple places throughout the framework. + +The UIKit framework defines a number of functions, many of them used in graphics and drawing operations. + +### Classes + +`class UIColorEffect` + +A visual effect that applies a solid color background. + +--- + +# https://developer.apple.com/library/archive/documentation/General/Conceptual/AppleTV_PG/index.html + +App Programming Guide for tvOS + +On This Page + +- Apple TV Hardware +- Traditional Apps +- Client-Server Apps +- Top Shelf +- Focus and Layered Images +- New tvOS Frameworks +- New User Interface Challenges +- Local Storage for Your App Is Limited +- Targeting Apple TV in Your Apps +- Adopting Light and Dark Themes +- Implementing Universal Purchase +- Creating a Background Audio App + +## Apple TV and tvOS + +With Apple TV on tvOS, users can now play games, use productivity and social apps, watch movies, and enjoy shared experiences. All of these new features bring new opportunities for developers. + +tvOS is derived from iOS but is a distinct OS, including some frameworks that are supported only on tvOS. You’ll find that the familiarity of iOS development, combined with support for a shared, multiuser experience, opens up areas of possibilities for app development that you won’t find on iOS devices. You can create new apps or use your iOS code as a starting point for a tvOS app. Either way, you use tools (Xcode) and languages (Objective-C, Swift, and JavaScript) that you are already familiar with. This document describes the unique capabilities of Apple TV and provides pointers to in-depth information that will get you started developing a tvOS app. + +When porting an existing project, you can include an additional target in your Xcode project to simplify sharing of resources, but you need to create new storyboards for tvOS. Likely, you will need to look at how users navigate through your app and adapt your app’s user interface to Apple TV. For more information, see _Apple TV Human Interface Guidelines_. + +A new Apple TV-specific provisioning profile is required for Apple TV development and distribution, which is used with your existing iOS development and distribution signing identities. You create a new Apple TV provisioning profile the same way that you create an iOS provisioning profile, using Fix Issue in Xcode, or through the developer portal website. For information on capabilities supported by Apple TV, see Supported Capabilities. + +Although iOS and tvOS apps are distinct entities (meaning there isn’t a single binary that runs on both platforms), you can create a universal purchase that bundles these apps. The user purchases an app once, and gets the iOS version for their iOS devices and a tvOS version for Apple TV. For more information, see _App Distribution Guide_. + +### Apple TV Hardware + +Apple TV has the following hardware specifications: + +- 64-bit A8 processor + +- 32 GB or 64 GB of storage + +- 2 GB of RAM + +- 10/100 Mbps Ethernet + +- WiFi 802.11a/b/g/n/ac + +- 1080p resolution + +- HDMI + +- New Siri Remote / Apple TV Remote + +The Apple TV Remote comes in two flavors—one with Siri built in and the other with onscreen search capabilities. The Siri Remote is available in the following countries: + +- Australia + +- Canada + +- France + +- Germany + +- Japan + +- Spain + +- United Kingdom + +- United States + +Apple TVs in all other countries are packaged with the Apple TV Remote. Figure 1-1 shows the new remote. It has the following buttons: + +1. Touch surface. Swipe to navigate. Press to select. Press and hold for contextual menus. + +2. Menu. Press to + +### Traditional Apps + +The process for creating apps for Apple TV is similar to the process for creating iOS apps. You can create games, utility apps, media apps, and more using the same techniques and frameworks used by iOS. New and existing apps can target both iOS and the new Apple TV, allowing for unprecedented multiplayer options. + +### Client-Server Apps + +Apple TV makes it easier to create client-server apps, whose primary purpose is to stream media, using web technologies such as HTTPS, XMLHTTPRequest, DOM, and JavaScript. You use Apple’s custom markup language, TVML, to create interfaces, and you specify app behaviors using JavaScript. The TVMLKit framework provides the bridge between your native code and the JavaScript code in your user interface. + +You specify your app’s initial launch behavior in a JavaScript file. Create your binary app as you typically would, and then use the TVMLKit framework to load the JavaScript file. Your JavaScript file loads TVML pages and displays them on the screen. Create TVML pages using templates supplied by Apple. Each template produces a unique, full-screen display of information. You modify a page by adding or removing elements from a template. For a list of Apple-supplied TVML templates and elements, see _Apple TV Markup Language Reference_. + +All video playback on Apple TV is based on HTTP Live Streaming and FairPlay Streaming. See _About HTTP Live Streaming_ and _FairPlay Streaming Overview_. For HTTP Live Streaming authoring specifications, see HLS Authoring Specification for Apple TV. + +### Top Shelf + +Users can place any Apple TV app in the top row of their app’s menu, which can contain up to five icons. When a user selects an app icon in the top row, the top of the screen shows content related to that app. This area is called the top shelf. The top shelf can showcase an app’s content, give people a preview of the content they care about, or let them jump straight into a particular part of the app. + +### Focus and Layered Images + +A UI element is _in focus_ when the user highlights an item, but has not selected an item. When a user brings focus to a layered image, the image responds to the user’s touches on the glass touch surface of the remote. Each layer of the image rotates at a slightly different rate to create a parallax effect. This subtle effect creates a sense of depth, realism, and vitality, and emphasizes that the focused item is the closest thing to the user. + +Your layered images are going to be created by your designers. But how do you get them into your app? The `UIImageView` class has been modified to support layered images, so in most cases you only need to make minimal coding changes. Your workflow is going to change depending on whether you are adding the images directly to your app or loading them from a server at runtime. + +### New tvOS Frameworks + +Apple tvOS introduces the following new frameworks that are specific to tvOS: + +- TVMLJS. Describes the JavaScript APIs used to load the TVML pages that are used to display information in client-server apps. See _Apple TV JavaScript Framework Reference_. + +- TVMLKit. Provides a way to incorporate JavaScript and TVML elements into your app. See _TVMLKit Framework Reference_. + +- TVServices. Describes how to add a top shelf extension to your app. See _TVServices Framework Reference_. + +### New User Interface Challenges + +Apple TV does not have a mouse that allows users to directly select and interact with an app, nor are users able to use gestures and touch to interact with an app. Instead, they use the new Siri Remote or a game controller to move around the screen. + +In addition to the new controls, the overall user experience is drastically different. Macs and iOS devices are generally a single-person experience. A user may interact with others through your app, but that user is still the only person using the device. With the new Apple TV, the user experience becomes much more social. Several people can be sitting on the couch and interacting with your app and each other. Designing apps to take advantage of these changes is crucial to designing a great app. + +### Local Storage for Your App Is Limited + +The maximum size for a tvOS app bundle 4 GB. Moreover, your app can only access 500 KB of persistent storage that is local to the device (using the `NSUserDefaults` class). Outside of this limited local storage, all other data must be purgeable by the operating system when space is low. You have a few options for managing these resources: + +- Your app can store and retrieve user data in iCloud. + +- Your app can download the data it needs into its cache directory. Downloaded data is not deleted while the app is running. However, when space is low and your app is not running, this data may be deleted. Do not use the entire cache space as this can cause unpredictable results. + +- Your app can package read-only assets using on-demand resources. Then, at runtime, your app requests the resources it needs, and the operating system automatically downloads and manages those resources. Knowing how and when to load new assets while keeping your users engaged is critical to creating a successful app. For information on on-demand resources, see _On-Demand Resources Guide_. + +This means that every app developed for the new Apple TV must be able to store data in iCloud and retrieve it in a way that provides a great customer experience. + +### Targeting Apple TV in Your Apps + +To conditionalize code so that it is only compiled for tvOS, use the `TARGET_OS_TV` macro or one of the tvOS version constants defined in `Availability.h`. In an app written in Swift, use a build configuration statement or an API availability statement. + +**Listing 1-1** Conditionalizing code for tvOS in Objective-C + +1. `#if TARGET_OS_TV + +2. ` NSLog(@"Code compiled only when building for tvOS."); + +3. `#endif + +**Listing 1-2** Conditionalizing code for tvOS in Swift + +1. `#if os(tvOS)` +2. `NSLog(@"Code compiled only when building for tvOS.");` +3. `#endif` +4. ` ` +5. `if #available(tvOS 9.1,*) {` +6. ` print("Code that executes only on tvOS 9.1 or later.")` +7. `}` + +### Adopting Light and Dark Themes + +Starting in tvOS 10.0, you are able to personalize your app using light and dark themes. Apps automatically adopt a light theme unless you specifically tell your app to adopt dark themes. To adopt a dark theme, set the UIUserInterfaceStyle property in your apps info.plist to either `Dark` or `Automatic`. If you create a new app using Xcode 8.0, the UIUserInterfaceStyle property is automatically set to `Automatic`. + +### Implementing Universal Purchase + +By linking the iOS and tvOS versions of your app in iTunes Connect, you can enable universal purchase for your app. Universal purchase allows users to download both iOS and tvOS versions of your app with a single purchase, providing a seamless experience for your users. See Universal Purchase of iOS and tvOS Apps to learn how to set up universal purchase. + +### Creating a Background Audio App + +You must declare that your tvOS app provides specific background services and must be allowed to continue running while in the background. To do this, add the `UIBackgroundModes` key in your app’s `info.plist` file. The key’s value is an array that contains one or more strings identifying which background tasks your app supports. Specify the string value `audio` to indicate your app plays audible content to the user while in the background. + +Creating a Client-Server App + +[](http://www.apple.com/legal/terms/site.html) \| +[](http://www.apple.com/privacy/) \| +Updated: 2017-01-12 + +--- + +# https://developer.apple.com/library/archive/documentation/General/Conceptual/MOSXAppProgrammingGuide/Introduction/Introduction.html + +Documentation Archive Developer + +Search + +Search Documentation Archive + +Next + +# About OS X App Design + +This document is the starting point for learning how to create Mac apps. It contains fundamental information about the OS X environment and how your apps interact with that environment. It also contains important information about the architecture of Mac apps and tips for designing key parts of your app. + +## At a Glance + +Cocoa is the application environment that unlocks the full power of OS X. Cocoa provides APIs, libraries, and runtimes that help you create fast, exciting apps that automatically inherit the beautiful look and feel of OS X, as well as standard behaviors users expect. + +### Cocoa Helps You Create Great Apps for OS X + +You write apps for OS X using Cocoa, which provides a significant amount of infrastructure for your program. Fundamental design patterns are used throughout Cocoa to enable your app to interface seamlessly with subsystem frameworks, and core application objects provide key behaviors to support simplicity and extensibility in app architecture. Key parts of the Cocoa environment are designed particularly to support ease of use, one of the most important aspects of successful Mac apps. Many apps should adopt iCloud to provide a more coherent user experience by eliminating the need to synchronize data explicitly between devices. + +### Common Behaviors Make Apps Complete + +During the design phase of creating your app, you need to think about how to implement certain features that users expect in well-formed Mac apps. Integrating these features into your app architecture can have an impact on the user experience: accessibility, preferences, Spotlight, services, resolution independence, fast user switching, and the Dock. Enabling your app to assume full-screen mode, taking over the entire screen, provides users with a more immersive, cinematic experience and enables them to concentrate fully on their content without distractions. + +### Get It Right: Meet System and App Store Requirements + +Configuring your app properly is an important part of the development process. Mac apps use a structured directory called a _bundle_ to manage their code and resource files. And although most of the files are custom and exist to support your app, some are required by the system or the App Store and must be configured properly. The application bundle also contains the resources you need to provide to internationalize your app to support multiple languages. + +### Finish Your App with Performance Tuning + +As you develop your app and your project code stabilizes, you can begin performance tuning. Of course, you want your app to launch and respond to the user’s commands as quickly as possible. A responsive app fits easily into the user’s workflow and gives an impression of being well crafted. You can improve the performance of your app by speeding up launch time and decreasing your app’s code footprint. + +## How to Use This Document + +This guide introduces you to the most important technologies that go into writing an app. In this guide you will see the whole landscape of what's needed to write one. That is, this guide shows you all the "pieces" you need and how they fit together. There are important aspects of app design that this guide does not cover, such as user interface design. However, this guide includes many links to other documents that provide details about the technologies it introduces, as well as links to tutorials that provide a hands-on approach. + +In addition, this guide emphasizes certain technologies introduced in OS X v10.7, which provide essential capabilities that set your app apart from older ones and give it remarkable ease of use, bringing some of the best features from iOS to OS X. + +## See Also + +The following documents provide additional information about designing Mac apps, as well as more details about topics covered in this document: + +- To work through a tutorial showing you how to create a Cocoa app, see _Start Developing Mac Apps Today_. + +- For information about user interface design enabling you to create effective apps using OS X, see _OS X Human Interface Guidelines_. + +- To understand how to create an explicit app ID, create provisioning profiles, and enable the correct entitlements for your application, so you can sell your application through the Mac App Store or use iCloud storage, see _App Distribution Guide_. + +- For a general survey of OS X technologies, see _Mac Technology Overview_. + +- To understand how to implement a document-based app, see _Document-Based App Programming Guide for Mac_. + +* * * + +[](http://www.apple.com/legal/internet-services/terms/site.html) \| [](http://www.apple.com/privacy/) \| Updated: 2015-03-09 + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/DocumentBasedAppPGiOS/Introduction/Introduction.html + +Documentation Archive Developer + +Search + +Search Documentation Archive + +Next + +# About Document-Based Applications in iOS + +The UIKit framework offers support for applications that manage multiple documents, with each document containing a unique set of data that is stored in a file located either in the application sandbox or in iCloud. + +Central to this support is the `UIDocument` class, introduced in iOS 5.0. A document-based application must create a subclass of `UIDocument` that loads document data into its in-memory data structures and supplies `UIDocument` with the data to write to the document file. `UIDocument` takes care of many details related to document management for you. Besides its integration with iCloud, `UIDocument` reads and writes document data in the background so that your application’s user interface does not become unresponsive during these operations. It also saves document data automatically and periodically, freeing your users from the need to explicitly save. + +## At a Glance + +Although a document-based application is responsible for a range of behaviors, making an application document-based is usually not a difficult task. + +### Document Objects Are Model Controllers + +In the Model-View-Controller design pattern, document objects—that is, instances of subclasses of `UIDocument`—are model controllers. A document object manages the data associated with a document, specifically the model objects that internally represent what the user is viewing and editing. A document object, in turn, is typically managed by a view controller that presents a document to users. + +**Relevant Chapter:** Designing a Document-Based Application + +### When Designing an Application, Consider Document-Data Format and Other Issues + +Before you write a line of code you should consider aspects of design specific to document-based applications. Most importantly, what is the best format of document data for your application, and how can you make that format work for your application in iOS _and_ Mac OS X? What is the most appropriate document type? + +You also need to plan for the view controllers (and views) managing such tasks as opening documents, indicating errors, and moving selected documents to and from iCloud storage. + +**Relevant Chapters:** Designing a Document-Based Application, Document-Based Application Preflight + +### Creating a Subclass of UIDocument Requires Two Method Overrides + +The primary role of a document object is to be the “conduit” of data between a document file and the model objects that internally represent document data. It gives the `UIDocument` class the data to write to the document file and, after the document file is read, it initializes its model objects with the data that `UIDocument` gives it. To fulfill this role, your subclass of `UIDocument` must override the `contentsForType:error:` method and the `loadFromContents:ofType:error:` method, respectively. + +**Relevant Chapter:** Creating a Custom Document Object + +### An Application Manages a Document Through Its Life Cycle + +An application is responsible for managing the following events during a document’s lifetime: + +- Creation of the document + +- Opening and closing the document + +- Monitoring changes in document state and responding to errors or version conflicts + +- Moving documents to iCloud storage (and removing them from iCloud storage) + +- Deletion of the document + +**Relevant Chapter:** Managing the Life Cycle of a Document + +### An Application Stores Document Files in iCloud Upon User Request + +Applications give their users the option for putting all document files in iCloud storage or all document files in the local sandbox. To move document files to iCloud, they compose a file URL locating the document in an iCloud container directory of the application and then call a specific method of the `NSFileManager` class, passing in the file URL. Moving document files from iCloud storage to the application sandbox follows a similar procedure. + +### An Application Ensures That Document Data is Saved Automatically + +`UIDocument` follows the saveless model and automatically saves a document’s data at specific intervals. A user usually never has to save a document explicitly. However, your application must play its part in order for the saveless model to work, either by implementing undo and redo or by tracking changes to the document. + +**Relevant Chapter:** Change Tracking and Undo Operations + +### An Application Resolves Conflicts Between Different Document Versions + +When documents are stored in iCloud, conflicts between versions of a document can occur. When a conflict occurs, UIKit informs the application about it. The application must attempt to resolve the conflict itself or invite the user to pick the version he or she prefers. + +**Relevant Chapter:** Resolving Document Version Conflicts + +## How to Use This Document + +Before you start writing any code for your document-based application, you should at least read the first two chapters, Designing a Document-Based Application and Document-Based Application Preflight. These chapters talk about design and configuration issues, and give you an overview of the tasks required for well-designed document-based applications + +## Prerequisites + +Before you read _Document-Based Application Programming Guide for iOS_ you should become familiar with the information presented in _App Programming Guide for iOS_. + +## See Also + +The following documents are related in some way to _Document-Based Application Programming Guide for iOS_: + +- _Uniform Type Identifiers Overview_ and the related reference discuss Uniform Type Identifiers (UTIs), which are the primary identifiers of document types. + +- _File Metadata Search Programming Guide_ describes how to conduct searches using the `NSMetadataQuery` class and related classes. You use metadata queries to locate an application’s documents stored in iCloud. + +- _iCloud Design Guide_ provides an introduction to iCloud document support. + +* * * + +[](http://www.apple.com/legal/internet-services/terms/site.html) \| [](http://www.apple.com/privacy/) \| Updated: 2012-09-19 + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/DocBasedAppProgrammingGuideForOSX/Introduction/Introduction.html + +Documentation Archive Developer + +Search + +Search Documentation Archive + +Next + +# About the Cocoa Document Architecture + +In OS X, a Cocoa subsystem called the _document architecture_ provides support for apps that manage documents, which are containers for user data that can be stored in files locally and in iCloud. + +## At a Glance + +Document-based apps handle multiple documents, each in its own window, and often display more than one document at a time. Although these apps embody many complex behaviors, the document architecture provides many of their capabilities “for free,” requiring little additional effort in design and implementation. + +### The Model-View-Controller Pattern Is Basic to a Document-Based App + +The Cocoa document architecture uses the Model-View-Controller (MVC) design pattern in which model objects encapsulate the app’s data, view objects display the data, and controller objects act as intermediaries between the view and model objects. A document, an instance of an `NSDocument` subclass, is a controller that manages the app’s data model. Adhering to the MVC design pattern enables your app to fit seamlessly into the document architecture. + +### Xcode Supports Coding and Configuring Your App + +Taking advantage of the support provided by Xcode, including a document-based application template and interfaces for configuring app data, you can create a document-based app without having to write much code. In Xcode you design your app’s user interface in a graphical editor, specify entitlements for resources such as the App Sandbox and iCloud, and configure the app’s property list, which specifies global app keys and other information, such as document types. + +### You Must Subclass NSDocument + +Document-based apps in Cocoa are built around a subclass of `NSDocument` that you implement. In particular, you must override one document reading method and one document writing method. You must design and implement your app’s data model, whether it is simply a single text-storage object or a complex object graph containing disparate data types. When your reading method receives a request, it takes data provided by the framework and loads it appropriately into your object model. Conversely, your writing method takes your app’s model data and provides it to the framework’s machinery for writing to a document file, whether it is located only in your local file system or in iCloud. + +### NSDocument Provides Core Behavior and Customization Opportunities + +The Cocoa document architecture provides your app with many built-in features, such as autosaving, asynchronous document reading and writing, file coordination, and multilevel undo support. In most cases, it is trivial to opt-in to these behaviors. If your app has particular requirements beyond the defaults, the document architecture provides many opportunities for extending and customizing your app’s capabilities through mechanisms such as delegation, subclassing and overriding existing methods with custom implementations, and integration of custom objects. + +## Prerequisites + +Before you read this document, you should be familiar with the information presented in _Mac App Programming Guide_. + +## See Also + +See _Document-Based App Programming Guide for iOS_ for information about how to develop a document-based app for iOS using the `UIDocument` class. + +For information about iCloud, see _iCloud Design Guide_. + +_File Metadata Search Programming Guide_ describes how to conduct searches using the `NSMetadataQuery` class and related classes. You use metadata queries to locate an app’s documents stored in iCloud. + +For information about how to publish your app in the App Store, see _App Distribution Guide_. + +* * * + +[](http://www.apple.com/legal/internet-services/terms/site.html) \| [](http://www.apple.com/privacy/) \| Updated: 2012-12-13 + +--- + +# https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/CoreData/index.html + +Core Data Programming Guide + +## What Is Core Data? + +Core Data is a framework that you use to manage the model layer objects in your application. It provides generalized and automated solutions to common tasks associated with object life cycle and object graph management, including persistence. + +Core Data typically decreases by 50 to 70 percent the amount of code you write to support the model layer. This is primarily due to the following built-in features that you do not have to implement, test, or optimize: + +- Change tracking and built-in management of undo and redo beyond basic text editing. + +- Maintenance of change propagation, including maintaining the consistency of relationships among objects. + +- Lazy loading of objects, partially materialized futures (faulting), and copy-on-write data sharing to reduce overhead. + +- Automatic validation of property values. Managed objects extend the standard key-value coding validation methods to ensure that individual values lie within acceptable ranges, so that combinations of values make sense. + +- Schema migration tools that simplify schema changes and allow you to perform efficient in-place schema migration. + +- Optional integration with the application’s controller layer to support user interface synchronization. + +- Grouping, filtering, and organizing data in memory and in the user interface. + +- Automatic support for storing objects in external data repositories. + +- Sophisticated query compilation. Instead of writing SQL, you can create complex queries by associating an NSPredicate object with a fetch request. + +- Version tracking and optimistic locking to support automatic multiwriter conflict resolution. + +- Effective integration with the macOS and iOS tool chains. + +Creating a Managed Object Model + +[](http://www.apple.com/legal/terms/site.html) \| +[](http://www.apple.com/privacy/) \| +Updated: 2017-03-27 + +--- + +# https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/UsingCoreDataWithiCloudPG/Introduction/Introduction.html + +Documentation Archive Developer + +Search + +Search Documentation Archive + +Next + +# Retired Document + +**Important:** +The use of iCloud with Core Data has been deprecated and is no longer being supported. + +# About Using iCloud with Core Data + +iCloud is a cloud service that gives your users a consistent and seamless experience across all of their iCloud-enabled devices. iCloud works with ubiquity containers—special folders that your app stores data in—to manage your app’s cloud storage. When you add, delete, or make changes to a file in your app’s ubiquity container, the system uploads the changes to iCloud. Other peers download the changes to keep your app up to date. + +To help you persist managed objects to the cloud, iCloud is integrated with Core Data. To use Core Data with iCloud, you simply tell Core Data to create an iCloud-enabled persistent store. The iCloud service and Core Data take care of the rest: The system manages the files in the ubiquity container that make up your persistent store, and Core Data helps you keep your app up to date. To let you know when the content in your container changes, Core Data posts notifications. + +## At a Glance + +When you use Core Data, you have several storage models to choose from. Using Core Data with iCloud, you have a subset of these options, as follows: + +- Atomic stores (for example, the binary store) load and save all of your managed objects in one go. Atomic stores work best for smaller storage requirements. + +- Transactional stores (for example, the SQLite store) load and save only the managed objects that you’re using and offer high–performance querying and merging. Transactional stores work best for larger, more complex storage requirements. + +- Document storage (iOS only) works best for apps designed to use a document-based design paradigm. Use document storage in combination with either an atomic or a transactional store. + +When you decide on a storage model, consider the strengths of each store as well as the iCloud-specific strengths discussed below. + +### Use Core Data Atomic Stores for Small, Simple Storage + +iCloud supports XML (OS X only) and binary atomic persistent stores. Useful for small, simple storage requirements, Core Data’s atomic-store support sacrifices merging and network efficiency for simplicity of use for when your data rarely changes. When you use iCloud with an atomic persistent store, you work directly in the ubiquity container. Binary (and XML) store files are themselves transferred to the iCloud servers; so whenever a change is made to the data, the system uploads the entire store and pushes it to all connected devices. This means that changes on one peer can overwrite changes made on the others. + +iCloud treats Core Data atomic stores like any other file added to your app’s ubiquity container. You can learn more about managing files in your app’s ubiquity container in _iCloud Design Guide_. + +### Use Core Data Transactional Stores for Large, Complex Storage + +Core Data provides ubiquitous persistent storage for SQLite-backed stores. Core Data takes advantage of the SQLite transactional persistence mechanism, saving and retrieving transaction logs—logs of changes—in your app’s ubiquity container. The Core Data framework’s reliability and performance extend to iCloud, resulting in dependable, fault-tolerant storage across multiple peers. Continue reading this document to learn more about how to use iCloud with an SQLite store. + +### (iOS Only) Use Core Data Document Stores to Manage Documents in iCloud + +The `UIManagedDocument` class is the primary mechanism through which Core Data stores managed documents in iCloud on iOS. The `UIManagedDocument` class manages the entire Core Data stack for each document in a document-based app. Changes to managed documents are automatically persisted to iCloud. By default, managed documents are backed by SQLite-type persistent stores, but you can choose to use atomic stores instead. While the steps you take to integrate the `UIManagedDocument` class into your app differ, the model-specific guidelines and best practices you follow are generally the same. You can find additional implementation strategies and tips in Using Document Storage with iCloud. + +## Prerequisites + +iCloud is a service that stores your app’s data in the cloud and makes it available to your users’ iCloud-enabled devices. Before using Core Data’s iCloud integration, you should read more about iCloud in _iCloud Design Guide_. In addition, this guide assumes a working knowledge of Core Data, a powerful object graph and data persistence framework. For more information about the Core Data framework, see Introduction to Core Data Programming Guide in _Core Data Programming Guide_. + +* * * + +[](http://www.apple.com/legal/internet-services/terms/site.html) \| [](http://www.apple.com/privacy/) \| Updated: 2017-06-06 + +--- + +# https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/Chapters/iCloudFundametals.html) + +View in English#) + +# The page you’re looking for can’t be found. + +--- + +# https://developer.apple.com/library/archive/documentation/General/Conceptual/iCloudDesignGuide/Art/iCloud_intro_2x.png) + + + +--- + diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index bdb65e11..6fed9bab 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,6 +1,6 @@ { - "name": "Swift 6.1", - "image": "swift:6.1", + "name": "Swift 6.2", + "image": "swift:6.2", "features": { "ghcr.io/devcontainers/features/common-utils:2": { "installZsh": "false", diff --git a/.devcontainer/swift-6.1-nightly/devcontainer.json b/.devcontainer/swift-6.1-nightly/devcontainer.json deleted file mode 100644 index 7949dc97..00000000 --- a/.devcontainer/swift-6.1-nightly/devcontainer.json +++ /dev/null @@ -1,32 +0,0 @@ -{ - "name": "Swift 6.1 Nightly", - "image": "swiftlang/swift:nightly-6.1-noble", - "features": { - "ghcr.io/devcontainers/features/common-utils:2": { - "installZsh": "false", - "username": "vscode", - "upgradePackages": "false" - }, - "ghcr.io/devcontainers/features/git:1": { - "version": "os-provided", - "ppa": "false" - } - }, - "postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}", - "runArgs": [ - "--cap-add=SYS_PTRACE", - "--security-opt", - "seccomp=unconfined" - ], - "customizations": { - "vscode": { - "settings": { - "lldb.library": "/usr/lib/liblldb.so" - }, - "extensions": [ - "sswg.swift-lang" - ] - } - }, - "remoteUser": "root" -} \ No newline at end of file diff --git a/.github/workflows/MistKit.yml b/.github/workflows/MistKit.yml index b3bee8a2..7eb3037d 100644 --- a/.github/workflows/MistKit.yml +++ b/.github/workflows/MistKit.yml @@ -17,8 +17,6 @@ jobs: swift: - version: "6.1" - version: "6.2" - - version: "6.1" - nightly: true - version: "6.2" nightly: true @@ -93,7 +91,7 @@ jobs: runs-on: macos-15 xcode: "/Applications/Xcode_26.0.app" deviceName: "iPhone 17 Pro" - osVersion: "26.0" + osVersion: "26.0.1" download-platform: true - type: ios @@ -161,7 +159,6 @@ jobs: env: MINT_PATH: .mint/lib MINT_LINK_PATH: .mint/bin - LINT_MODE: STRICT steps: - uses: actions/checkout@v4 - name: Cache mint diff --git a/.gitignore b/.gitignore index 35ee31d8..46a5ec69 100644 --- a/.gitignore +++ b/.gitignore @@ -170,9 +170,6 @@ dev-debug.log *.sw? # OS specific -# Task files -# tasks.json -# tasks/ .mint/ /Keys/ .claude/settings.local.json @@ -190,3 +187,7 @@ dev-debug.log # Allow placeholder docs/samples in Keys !Keys/README.md !Keys/*.example.* + +# Task files +# tasks.json +# tasks/ diff --git a/CLAUDE.md b/CLAUDE.md index df5f8969..6fbee1a5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -106,6 +106,35 @@ MistKit/ 3. **Error Handling**: Use typed errors conforming to LocalizedError 4. **Sendable Compliance**: Ensure all types are Sendable for concurrency safety +### Logging +MistKit uses [swift-log](https://github.com/apple/swift-log) for cross-platform logging support, enabling usage on macOS, Linux, Windows, and other platforms. + +**Key Logging Components:** +- `MistKitLogger` - Centralized logging infrastructure with subsystems for `api`, `auth`, and `network` +- Environment-based privacy control via `MISTKIT_DISABLE_LOG_REDACTION` environment variable +- `SecureLogging` utilities for token masking and safe message formatting +- Structured logging in `LoggingMiddleware` for HTTP request/response debugging (DEBUG builds only) + +**Logging Subsystems:** +```swift +MistKitLogger.api // CloudKit API operations +MistKitLogger.auth // Authentication and token management +MistKitLogger.network // Network operations +``` + +**Helper Methods:** +```swift +MistKitLogger.logError(_:logger:shouldRedact:) // Error level +MistKitLogger.logWarning(_:logger:shouldRedact:) // Warning level +MistKitLogger.logInfo(_:logger:shouldRedact:) // Info level +MistKitLogger.logDebug(_:logger:shouldRedact:) // Debug level +``` + +**Privacy Controls:** +- By default, logs use `SecureLogging.safeLogMessage()` to redact sensitive information +- Set `MISTKIT_DISABLE_LOG_REDACTION=1` to disable redaction for debugging +- Tokens, keys, and secrets are automatically masked in logged messages + ### CloudKit Web Services Integration - Base URL: `https://api.apple-cloudkit.com` - Authentication: API Token + Web Auth Token or Server-to-Server Key Authentication @@ -115,10 +144,13 @@ MistKit/ - Environments: `development`, `production` ### Testing Strategy +- Use Swift Testing framework (`@Test` macro) for all tests - Unit tests for all public APIs - Integration tests using mock URLSession -- Use `XCTAssertThrowsError` for error path testing +- Use `#expect()` and `#require()` for assertions - Async test support with `async let` and `await` +- Parameterized tests for testing multiple scenarios +- See `testing-enablinganddisabling.md` for Swift Testing patterns ## Important Implementation Notes @@ -146,8 +178,57 @@ Key endpoints documented in the OpenAPI spec: - Assets: `/assets/upload` - Tokens: `/tokens/create`, `/tokens/register` +## Reference Documentation + +Apple's official CloudKit documentation is available in `.claude/docs/` for offline reference during development: + +### When to Consult Each Document + +**webservices.md** (289 KB) - CloudKit Web Services REST API +- **Primary use**: Implementing REST API endpoints +- **Contains**: Authentication, request formats, all endpoints, data types, error codes +- **Consult when**: Writing API client code, handling authentication, debugging responses + +**cloudkitjs.md** (188 KB) - CloudKit JS Framework +- **Primary use**: Understanding CloudKit concepts and operation flows +- **Contains**: Container/database patterns, operations, response objects, error handling +- **Consult when**: Designing Swift types, implementing queries, working with subscriptions + +**testing-enablinganddisabling.md** (126 KB) - Swift Testing Framework +- **Primary use**: Writing modern Swift tests +- **Contains**: `@Test` macros, async testing, parameterization, migration from XCTest +- **Consult when**: Writing or organizing tests, testing async code + +**swift-openapi-generator.md** (235 KB) - Swift OpenAPI Generator Documentation +- **Primary use**: Understanding code generation configuration and features +- **Contains**: Generator configuration, type overrides, middleware system, transport protocols, API stability +- **Consult when**: Configuring openapi-generator-config.yaml, implementing middleware, troubleshooting generated code + +See `.claude/docs/README.md` for detailed topic breakdowns and integration guidance. + +### CloudKit Schema Language + +**cloudkit-schema-reference.md** - CloudKit Schema Language Quick Reference +- **Primary use**: Working with text-based .ckdb schema files +- **Contains**: Complete grammar, field options, data types, permissions, common patterns, MistKit-specific notes +- **Consult when**: Reading/modifying schemas, understanding indexing, designing record types + +**sosumi-cloudkit-schema-source.md** - Apple's Official Schema Language Documentation +- **Primary use**: Authoritative reference for CloudKit Schema Language +- **Contains**: Full grammar specification, identifier rules, system fields, permission model +- **Consult when**: Understanding schema fundamentals, resolving syntax questions + +### Comprehensive Schema Guides + +For detailed schema workflows and integration: + +- **AI Schema Workflow** (`Examples/Celestra/AI_SCHEMA_WORKFLOW.md`) - Comprehensive guide for understanding, designing, modifying, and validating CloudKit schemas with text-based tools +- **Quick Reference** (`Examples/SCHEMA_QUICK_REFERENCE.md`) - One-page cheat sheet with syntax, patterns, cktool commands, and troubleshooting +- **Task Master Integration** (`.taskmaster/docs/schema-design-workflow.md`) - Integrate schema design into Task Master PRDs and task decomposition + ## Task Master AI Instructions **Import Task Master's development workflow commands and guidelines, treat as if import is in the main CLAUDE.md file.** @./.taskmaster/CLAUDE.md - We are using explicit ACLs in the Swift code -- type order is based on the default in swiftlint: https://realm.github.io/SwiftLint/type_contents_order.html \ No newline at end of file +- type order is based on the default in swiftlint: https://realm.github.io/SwiftLint/type_contents_order.html +- Anything inside [CONTENT] [/CONTENT] is written by me \ No newline at end of file diff --git a/Examples/Bushel/.gitignore b/Examples/Bushel/.gitignore new file mode 100644 index 00000000..375e0152 --- /dev/null +++ b/Examples/Bushel/.gitignore @@ -0,0 +1,16 @@ +# CloudKit Server-to-Server Private Keys +*.pem + +# Environment variables +.env + +# Build artifacts +.build/ +.swiftpm/ + +# Xcode +xcuserdata/ +*.xcworkspace + +# macOS +.DS_Store diff --git a/Examples/Bushel/CLOUDKIT-SETUP.md b/Examples/Bushel/CLOUDKIT-SETUP.md new file mode 100644 index 00000000..d3bd3ec6 --- /dev/null +++ b/Examples/Bushel/CLOUDKIT-SETUP.md @@ -0,0 +1,855 @@ +# CloudKit Server-to-Server Authentication Setup Guide + +This guide documents the complete process for setting up CloudKit Server-to-Server (S2S) authentication to sync data from external sources to CloudKit's public database. This was implemented for the Bushel demo application, which syncs Apple restore images, Xcode versions, and Swift versions to CloudKit. + +## Table of Contents + +1. [Overview](#overview) +2. [Prerequisites](#prerequisites) +3. [Server-to-Server Key Setup](#server-to-server-key-setup) +4. [Schema Configuration](#schema-configuration) +5. [Understanding CloudKit Permissions](#understanding-cloudkit-permissions) +6. [Common Issues and Solutions](#common-issues-and-solutions) +7. [Implementation Details](#implementation-details) +8. [Testing and Verification](#testing-and-verification) + +--- + +## Overview + +### What is Server-to-Server Authentication? + +Server-to-Server (S2S) authentication allows your backend services, scripts, or command-line tools to interact with CloudKit **without requiring a signed-in iCloud user**. This is essential for: + +- Automated data syncing from external APIs +- Scheduled batch operations +- Server-side data processing +- Command-line tools that manage CloudKit data + +### How It Works + +1. **Generate a Server-to-Server key** in CloudKit Dashboard +2. **Download the private key** (.pem file) and securely store it +3. **Sign requests** using the private key and key ID +4. **CloudKit authenticates** your requests as the developer/creator +5. **Permissions are checked** against the schema's security roles + +### Key Characteristics + +- Operates at the **developer/application level**, not user level +- Authenticates as the **"_creator"** role in CloudKit's permission model +- Requires explicit permissions in your CloudKit schema +- Works with the **public database** only (not private or shared databases) + +--- + +## Prerequisites + +### 1. Apple Developer Account + +- Active Apple Developer Program membership +- Access to [CloudKit Dashboard](https://icloud.developer.apple.com/) + +### 2. CloudKit Container + +- A configured CloudKit container (e.g., `iCloud.com.yourcompany.YourApp`) +- Container must be set up in your Apple Developer account + +### 3. Tools + +- **Xcode Command Line Tools** (for `cktool`) +- **Swift** (for building and running your sync tool) +- **OpenSSL** (for generating the key pair) + +### 4. Development Environment + +```bash +# Verify you have the required tools +xcode-select --version +swift --version +openssl version +``` + +--- + +## Server-to-Server Key Setup + +### Step 1: Generate the Key Pair + +Open Terminal and generate an ECPRIME256V1 key pair: + +```bash +# Generate private key +openssl ecparam -name prime256v1 -genkey -noout -out eckey.pem + +# Extract public key +openssl ec -in eckey.pem -pubout -out eckey_pub.pem +``` + +**Important:** Keep `eckey.pem` (private key) **secure and confidential**. Never commit it to version control. + +### Step 2: Add Key to CloudKit Dashboard + +1. **Navigate to CloudKit Dashboard** + - Go to [CloudKit Dashboard](https://icloud.developer.apple.com/) + - Select your Team + - Select your Container + +2. **Navigate to Tokens & Keys** + - In the left sidebar, under "Settings" + - Click "Tokens & Keys" + +3. **Create New Server-to-Server Key** + - Click the "+" button to create a new key + - **Name:** Give it a descriptive name (e.g., "MistKit Demo for Restore Images") + - **Public Key:** Paste the contents of `eckey_pub.pem` + +4. **Save and Record Key ID** + - After saving, CloudKit will display a **Key ID** (long hexadecimal string) + - **Copy this Key ID** - you'll need it for authentication + - Example: `3e76ace055d2e3881a4e9c862dd1119ea85717bd743c1c8c15d95b2280cd93ab` + +### Step 3: Secure Storage + +Store your private key securely: + +```bash +# Option 1: iCloud Drive (encrypted) +mv eckey.pem ~/Library/Mobile\ Documents/com~apple~CloudDocs/Keys/your-app-cloudkit.pem + +# Option 2: Environment variable (for CI/CD) +export CLOUDKIT_PRIVATE_KEY=$(cat eckey.pem) + +# Option 3: Secure keychain (macOS) +# Store in macOS Keychain as a secure note +``` + +**Never:** +- Commit the private key to Git +- Share it in Slack/email +- Store it in plain text in your repository + +--- + +## Schema Configuration + +### Understanding the Schema File + +CloudKit schemas define your data structure and **security permissions**. For S2S authentication to work, you must explicitly grant permissions in your schema. + +### Schema File Format + +Create a `schema.ckdb` file: + +```text +DEFINE SCHEMA + +RECORD TYPE YourRecordType ( + "field1" STRING QUERYABLE SORTABLE SEARCHABLE, + "field2" TIMESTAMP QUERYABLE SORTABLE, + "field3" INT64 QUERYABLE, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); +``` + +### Critical Permissions for S2S + +**For Server-to-Server authentication to work, you MUST include:** + +```text +GRANT READ, CREATE, WRITE TO "_creator", +GRANT READ, CREATE, WRITE TO "_icloud", +``` + +**Why both roles are required:** +- `_creator` - S2S keys authenticate as the developer/creator +- `_icloud` - Provides additional context for authenticated operations + +**Our testing showed:** +- ❌ Only `_icloud` → `ACCESS_DENIED` errors +- ❌ Only `_creator` → `ACCESS_DENIED` errors +- ✅ **Both `_creator` AND `_icloud`** → Success + +### Example: Bushel Schema + +```text +DEFINE SCHEMA + +RECORD TYPE RestoreImage ( + "version" STRING QUERYABLE SORTABLE SEARCHABLE, + "buildNumber" STRING QUERYABLE SORTABLE, + "releaseDate" TIMESTAMP QUERYABLE SORTABLE, + "downloadURL" STRING, + "fileSize" INT64, + "sha256Hash" STRING, + "sha1Hash" STRING, + "isSigned" INT64 QUERYABLE, + "isPrerelease" INT64 QUERYABLE, + "source" STRING, + "notes" STRING, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); + +RECORD TYPE XcodeVersion ( + "version" STRING QUERYABLE SORTABLE SEARCHABLE, + "buildNumber" STRING QUERYABLE SORTABLE, + "releaseDate" TIMESTAMP QUERYABLE SORTABLE, + "isPrerelease" INT64 QUERYABLE, + "downloadURL" STRING, + "fileSize" INT64, + "minimumMacOS" REFERENCE, + "includedSwiftVersion" REFERENCE, + "sdkVersions" STRING, + "notes" STRING, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); + +RECORD TYPE SwiftVersion ( + "version" STRING QUERYABLE SORTABLE SEARCHABLE, + "releaseDate" TIMESTAMP QUERYABLE SORTABLE, + "isPrerelease" INT64 QUERYABLE, + "downloadURL" STRING, + "notes" STRING, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); +``` + +### Importing the Schema + +Use `cktool` to import your schema to CloudKit: + +```bash +xcrun cktool import-schema \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.yourcompany.YourApp \ + --environment development \ + --file schema.ckdb +``` + +**Note:** You'll be prompted to authenticate with your Apple ID. This requires a management token, which `cktool` will help you obtain. + +### Verifying the Schema + +Export and verify your schema was imported correctly: + +```bash +xcrun cktool export-schema \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.yourcompany.YourApp \ + --environment development \ + > current-schema.ckdb + +# Check the permissions +cat current-schema.ckdb | grep -A 2 "GRANT" +``` + +You should see: +```text +GRANT READ, CREATE, WRITE TO "_creator", +GRANT READ, CREATE, WRITE TO "_icloud", +GRANT READ TO "_world" +``` + +--- + +## Understanding CloudKit Permissions + +### Security Roles + +CloudKit uses a role-based permission system with three built-in roles: + +| Role | Who | Typical Use | +|------|-----|-------------| +| `_world` | Everyone (including unauthenticated users) | Public read access | +| `_icloud` | Any signed-in iCloud user | User-level operations | +| `_creator` | The developer/owner of the container | Admin/server operations | + +### Permission Types + +| Permission | What It Allows | +|------------|----------------| +| `READ` | Query and fetch records | +| `CREATE` | Create new records | +| `WRITE` | Update existing records | + +### How S2S Authentication Maps to Roles + +When you use Server-to-Server authentication: + +1. Your private key + key ID authenticate you **as the developer** +2. CloudKit treats this as the **`_creator`** role +3. For public database operations, **both `_creator` and `_icloud`** permissions are needed + +### Common Permission Patterns + +**Public read-only data:** +```text +GRANT READ TO "_world" +``` + +**User-generated content:** +```text +GRANT READ, CREATE, WRITE TO "_creator", +GRANT READ, WRITE TO "_icloud", +GRANT READ TO "_world" +``` + +**Server-managed data (our use case):** +```text +GRANT READ, CREATE, WRITE TO "_creator", +GRANT READ, CREATE, WRITE TO "_icloud", +GRANT READ TO "_world" +``` + +**Admin-only data:** +```text +GRANT READ, CREATE, WRITE TO "_creator" +``` + +### CloudKit Dashboard UI vs Schema Syntax + +The CloudKit Dashboard shows permissions with checkboxes: +- ☑️ Create +- ☑️ Read +- ☑️ Write + +In the schema file, these map to: +```text +GRANT READ, CREATE, WRITE TO "role_name" +``` + +**Important:** The Dashboard and schema file should match. Always verify by exporting the schema after making Dashboard changes. + +--- + +## Common Issues and Solutions + +### Issue 1: ACCESS_DENIED - "CREATE operation not permitted" + +**Symptom:** +```json +{ + "recordName": "YourRecord-123", + "reason": "CREATE operation not permitted", + "serverErrorCode": "ACCESS_DENIED" +} +``` + +**Root Causes:** + +1. **Missing `_creator` permissions in schema** + + **Solution:** Update schema to include: + ```text + GRANT READ, CREATE, WRITE TO "_creator", + ``` + +2. **Missing `_icloud` permissions in schema** + + **Solution:** Update schema to include: + ```text + GRANT READ, CREATE, WRITE TO "_icloud", + ``` + +3. **Schema not properly imported to CloudKit** + + **Solution:** Re-import schema using `cktool import-schema` + +4. **Server-to-Server key not active** + + **Solution:** Check CloudKit Dashboard → Tokens & Keys → Verify key is active + +### Issue 2: AUTHENTICATION_FAILED (HTTP 401) + +**Symptom:** +```text +HTTP 401: Authentication failed +``` + +**Root Causes:** + +1. **Invalid or revoked Key ID** + + **Solution:** Generate a new S2S key in CloudKit Dashboard + +2. **Incorrect private key** + + **Solution:** Verify you're using the correct `.pem` file + +3. **Key ID and private key mismatch** + + **Solution:** Ensure the private key matches the public key registered for that Key ID + +### Issue 3: Schema Syntax Errors + +**Symptom:** +```text +Was expecting LIST +Encountered "QUERYABLE" at line X, column Y +``` + +**Root Causes:** + +1. **System fields cannot have modifiers** + + **Bad:** + ```text + ___recordName QUERYABLE + ``` + + **Good:** Omit system fields entirely (CloudKit adds them automatically) + +2. **Invalid field type** + + **Solution:** Use CloudKit's supported types: + - `STRING` + - `INT64` (not `BOOLEAN` - use `INT64` with 0/1) + - `DOUBLE` + - `TIMESTAMP` + - `REFERENCE` + - `ASSET` + - `LOCATION` + - `LIST` + +### Issue 4: JSON Parsing Error (HTTP 500) + +**Symptom:** +```text +HTTP 500: The data couldn't be read because it isn't in the correct format +``` + +**Root Cause:** +Response payload is too large (>500KB). This is a **client-side** parsing limitation, **not a CloudKit error**. + +**Evidence it still worked:** +- HTTP 200 response received +- Record data present in response body +- Records exist in CloudKit when queried + +**Solutions:** + +1. **Reduce batch size** (CloudKit allows up to 200 operations per request) + ```swift + let batchSize = 100 // Instead of 200 + ``` + +2. **Don't decode the entire response** - just check for errors + ```swift + // Parse just the serverErrorCode field + let json = try JSONSerialization.jsonObject(with: data) + ``` + +3. **Use streaming JSON parser** for large responses + +4. **Verify success by querying CloudKit** after sync + +### Issue 5: Boolean Fields in CloudKit + +**Symptom:** +CloudKit schema import fails or fields have wrong type + +**Root Cause:** +CloudKit doesn't have a native `BOOLEAN` type in the schema language. + +**Solution:** +Use `INT64` with `0` for false and `1` for true: + +**Schema:** +```text +isPrerelease INT64 QUERYABLE, +isSigned INT64 QUERYABLE, +``` + +**Swift code:** +```swift +fields["isSigned"] = .int64(record.isSigned ? 1 : 0) +fields["isPrerelease"] = .int64(record.isPrerelease ? 1 : 0) +``` + +--- + +## Implementation Details + +### Swift Package Structure + +```text +Sources/ +├── YourApp/ +│ ├── CloudKit/ +│ │ ├── YourAppCloudKitService.swift # Main service wrapper +│ │ ├── RecordBuilder.swift # Converts models to CloudKit operations +│ │ └── Models.swift # Data models +│ └── DataSources/ +│ ├── ExternalAPIFetcher.swift # Fetch from external sources +│ └── ... +``` + +### Initialize CloudKit Service + +```swift +import MistKit + +// Initialize with S2S authentication +let service = try BushelCloudKitService( + containerIdentifier: "iCloud.com.yourcompany.YourApp", + keyID: "3e76ace055d2e3881a4e9c862dd1119ea85717bd743c1c8c15d95b2280cd93ab", + privateKeyPath: "/path/to/your-cloudkit.pem" +) +``` + +**Under the hood** (MistKit implementation): + +```swift +struct BushelCloudKitService { + let service: CloudKitService + + init(containerIdentifier: String, keyID: String, privateKeyPath: String) throws { + // Read PEM file + guard FileManager.default.fileExists(atPath: privateKeyPath) else { + throw BushelCloudKitError.privateKeyFileNotFound(path: privateKeyPath) + } + + let pemString = try String(contentsOfFile: privateKeyPath, encoding: .utf8) + + // Create S2S authentication manager + let tokenManager = try ServerToServerAuthManager( + keyID: keyID, + pemString: pemString + ) + + // Initialize CloudKit service + self.service = try CloudKitService( + containerIdentifier: containerIdentifier, + tokenManager: tokenManager, + environment: .development, + database: .public + ) + } +} +``` + +### Building CloudKit Operations + +Use `.forceReplace` for idempotent operations: + +```swift +static func buildRestoreImageOperation(_ record: RestoreImageRecord) -> RecordOperation { + var fields: [String: FieldValue] = [:] + + fields["version"] = .string(record.version) + fields["buildNumber"] = .string(record.buildNumber) + fields["releaseDate"] = .timestamp(record.releaseDate) + fields["downloadURL"] = .string(record.downloadURL) + fields["fileSize"] = .int64(Int64(record.fileSize)) + fields["sha256Hash"] = .string(record.sha256Hash) + fields["sha1Hash"] = .string(record.sha1Hash) + fields["isSigned"] = .int64(record.isSigned ? 1 : 0) + fields["isPrerelease"] = .int64(record.isPrerelease ? 1 : 0) + fields["source"] = .string(record.source) + if let notes = record.notes { + fields["notes"] = .string(notes) + } + + return RecordOperation( + operationType: .forceReplace, // Create if not exists, update if exists + recordType: "RestoreImage", + recordName: record.recordName, + fields: fields + ) +} +``` + +**Why `.forceReplace`?** +- Idempotent: Running sync multiple times won't create duplicates +- Creates new records if they don't exist +- Updates existing records with new data +- Requires both `CREATE` and `WRITE` permissions + +### Batch Operations + +CloudKit limits operations to **200 per request**: + +```swift +func syncRecords(_ records: [RestoreImageRecord]) async throws { + let operations = records.map { record in + RecordOperation.create( + recordType: RestoreImageRecord.cloudKitRecordType, + recordName: record.recordName, + fields: record.toCloudKitFields() + ) + } + + let batchSize = 200 + let batches = operations.chunked(into: batchSize) + + for (index, batch) in batches.enumerated() { + print("Batch \(index + 1)/\(batches.count): \(batch.count) records...") + let results = try await service.modifyRecords(batch) + + // Check for errors + let failures = results.filter { $0.recordType == "Unknown" } + let successes = results.filter { $0.recordType != "Unknown" } + + print("✓ \(successes.count) succeeded, ❌ \(failures.count) failed") + } +} +``` + +### Error Handling + +CloudKit returns **partial success** - some operations may succeed while others fail: + +```swift +let results = try await service.modifyRecords(batch) + +// CloudKit returns mixed results +for result in results { + if result.recordType == "Unknown" { + // This is an error response + print("❌ Error: \(result.serverErrorCode)") + print(" Reason: \(result.reason)") + } else { + // Successfully created/updated + print("✓ Record: \(result.recordName)") + } +} +``` + +Common error codes: +- `ACCESS_DENIED` - Permissions issue +- `AUTHENTICATION_FAILED` - Invalid key ID or signature +- `CONFLICT` - Record version mismatch (use `.forceReplace` to avoid) +- `QUOTA_EXCEEDED` - Too many operations or storage limit reached + +--- + +## Testing and Verification + +### 1. Test Authentication + +```swift +// Try a simple query to verify auth works +let records = try await service.queryRecords(recordType: "YourRecordType", limit: 1) +print("✓ Authentication successful, found \(records.count) records") +``` + +### 2. Verify Schema Permissions + +```bash +# Export current schema +xcrun cktool export-schema \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.yourcompany.YourApp \ + --environment development + +# Check permissions include _creator and _icloud +# Look for: +# GRANT READ, CREATE, WRITE TO "_creator", +# GRANT READ, CREATE, WRITE TO "_icloud", +``` + +### 3. Test Record Creation + +```swift +// Create a test record +let testRecord = RestoreImageRecord( + version: "18.0", + buildNumber: "22A123", + releaseDate: Date(), + downloadURL: "https://example.com/test.ipsw", + fileSize: 1000000, + sha256Hash: "abc123", + sha1Hash: "def456", + isSigned: true, + isPrerelease: false, + source: "test" +) + +let operation = RecordOperation.create( + recordType: RestoreImageRecord.cloudKitRecordType, + recordName: testRecord.recordName, + fields: testRecord.toCloudKitFields() +) +let results = try await service.modifyRecords([operation]) + +if results.first?.recordType == "Unknown" { + print("❌ Failed: \(results.first?.reason ?? "unknown")") +} else { + print("✓ Success! Record created: \(results.first?.recordName ?? "")") +} +``` + +### 4. Query Records from CloudKit + +```bash +# Using cktool (requires management token) +xcrun cktool query \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.yourcompany.YourApp \ + --environment development \ + --record-type RestoreImage \ + --limit 10 +``` + +Or in Swift: + +```swift +let records = try await service.queryRecords( + recordType: "RestoreImage", + limit: 10 +) + +for record in records { + print("Record: \(record.recordName)") + print(" Version: \(record.fields["version"]?.stringValue ?? "N/A")") + print(" Build: \(record.fields["buildNumber"]?.stringValue ?? "N/A")") +} +``` + +### 5. Verify in CloudKit Dashboard + +1. Go to [CloudKit Dashboard](https://icloud.developer.apple.com/) +2. Select your Container +3. Navigate to **Data** in the left sidebar +4. Select **Public Database** +5. Choose your **Record Type** (e.g., "RestoreImage") +6. You should see your synced records + +--- + +## Complete Setup Checklist + +### Initial Setup + +- [ ] Generate ECPRIME256V1 key pair with OpenSSL +- [ ] Add public key to CloudKit Dashboard → Tokens & Keys +- [ ] Copy and securely store the Key ID +- [ ] Store private key in secure location (not in Git!) +- [ ] Create `schema.ckdb` with proper permissions +- [ ] Import schema using `cktool import-schema` +- [ ] Verify schema with `cktool export-schema` + +### Schema Requirements + +- [ ] All record types have `GRANT READ, CREATE, WRITE TO "_creator"` +- [ ] All record types have `GRANT READ, CREATE, WRITE TO "_icloud"` +- [ ] Public read access: `GRANT READ TO "_world"` (if needed) +- [ ] No system fields (___*) have QUERYABLE modifiers +- [ ] Boolean fields use INT64 type (0/1) +- [ ] All REFERENCE fields point to valid record types + +### Code Implementation + +- [ ] Initialize `ServerToServerAuthManager` with keyID and PEM string +- [ ] Create `CloudKitService` with public database +- [ ] Build `RecordOperation` with `.forceReplace` for idempotency +- [ ] Implement batch processing (max 200 operations per request) +- [ ] Handle partial failures in responses +- [ ] Filter error responses (`recordType == "Unknown"`) + +### Testing + +- [ ] Test authentication with simple query +- [ ] Verify record creation works +- [ ] Check records appear in CloudKit Dashboard +- [ ] Test batch operations with multiple records +- [ ] Verify idempotency (running sync twice doesn't duplicate) +- [ ] Test error handling (invalid data, quota limits) + +### Production Readiness + +- [ ] Switch to `.production` environment +- [ ] Import schema to production container +- [ ] Rotate keys regularly (create new S2S key every 6-12 months) +- [ ] Monitor CloudKit usage and quotas +- [ ] Set up logging/monitoring for sync operations +- [ ] Document key rotation procedure +- [ ] Add rate limiting to avoid quota exhaustion + +--- + +## Additional Resources + +### Apple Documentation + +- [CloudKit Web Services Reference](https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/) +- [CloudKit Console Guide](https://developer.apple.com/documentation/cloudkit/managing_icloud_containers_with_the_cloudkit_database_app) +- [Server-to-Server Authentication](https://developer.apple.com/documentation/cloudkit/ckoperation) + +### MistKit Documentation + +- [MistKit GitHub Repository](https://github.com/brightdigit/MistKit) +- [Server-to-Server Auth Example](https://github.com/brightdigit/MistKit/tree/main/Examples/Bushel) + +### Tools + +- **cktool**: `xcrun cktool --help` +- **OpenSSL**: `man openssl` +- **Swift**: `swift --help` + +--- + +## Troubleshooting Commands + +```bash +# Check cktool is available +xcrun cktool --version + +# List your CloudKit containers +xcrun cktool list-containers + +# Export current schema +xcrun cktool export-schema \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.yourcompany.YourApp \ + --environment development + +# Import updated schema +xcrun cktool import-schema \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.yourcompany.YourApp \ + --environment development \ + --file schema.ckdb + +# Query records +xcrun cktool query \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.yourcompany.YourApp \ + --environment development \ + --record-type YourRecordType + +# Validate private key format +openssl ec -in your-cloudkit.pem -text -noout +``` + +--- + +## Summary + +CloudKit Server-to-Server authentication requires: + +1. **Key pair generation** - ECPRIME256V1 format +2. **CloudKit Dashboard setup** - Register public key, get Key ID +3. **Schema permissions** - Grant to **both** `_creator` and `_icloud` +4. **Swift implementation** - Use MistKit's `ServerToServerAuthManager` +5. **Operation type** - Use `.forceReplace` for idempotency +6. **Error handling** - Parse responses, handle partial failures +7. **Testing** - Verify auth, permissions, and record creation + +The most critical requirement discovered through testing: + +> **Both `_creator` AND `_icloud` must have `READ, CREATE, WRITE` permissions for S2S authentication to work with the public database.** + +This configuration allows your server-side tools to manage CloudKit data programmatically while also enabling public read access for your apps. diff --git a/Examples/Bushel/CLOUDKIT_SCHEMA_SETUP.md b/Examples/Bushel/CLOUDKIT_SCHEMA_SETUP.md new file mode 100644 index 00000000..f0c0d483 --- /dev/null +++ b/Examples/Bushel/CLOUDKIT_SCHEMA_SETUP.md @@ -0,0 +1,285 @@ +# CloudKit Schema Setup Guide + +This guide explains how to set up the CloudKit schema for the Bushel demo application. + +## Two Approaches + +### Option 1: Automated Setup with cktool (Recommended) + +Use the provided script to automatically import the schema. + +#### Prerequisites + +- **Xcode 13+** installed (provides `cktool`) +- **CloudKit container** created in [CloudKit Dashboard](https://icloud.developer.apple.com/) +- **Apple Developer Team ID** (10-character identifier) +- **CloudKit Management Token** (see "Getting a Management Token" below) + +#### Steps + +1. **Save your CloudKit Management Token** + + ```bash + xcrun cktool save-token + ``` + + When prompted, paste your management token from CloudKit Dashboard. + +2. **Set environment variables** + + ```bash + export CLOUDKIT_CONTAINER_ID="iCloud.com.yourcompany.Bushel" + export CLOUDKIT_TEAM_ID="YOUR_TEAM_ID" + export CLOUDKIT_ENVIRONMENT="development" # or "production" + ``` + +3. **Run the setup script** + + ```bash + cd Examples/Bushel + ./Scripts/setup-cloudkit-schema.sh + ``` + + The script will: + - Validate the schema file + - Confirm before importing + - Import the schema to your CloudKit container + - Display success/error messages + +4. **Verify in CloudKit Dashboard** + + Open [CloudKit Dashboard](https://icloud.developer.apple.com/) and verify the three record types exist: + - RestoreImage + - XcodeVersion + - SwiftVersion + +### Option 2: Manual Schema Creation (Development Only) + +For quick development testing, you can use CloudKit's "just-in-time schema" feature. + +#### Steps + +1. **Run the CLI with export command** (no schema needed) + + ```bash + bushel-images export --output test-data.json + ``` + + This fetches data from APIs without CloudKit. + +2. **Temporarily modify SyncCommand to create test records** + + Add this to `SyncCommand.swift`: + + ```swift + // In run() method, before actual sync: + let testImage = RestoreImageRecord( + version: "15.0", + buildNumber: "24A335", + releaseDate: Date(), + downloadURL: "https://example.com/test.ipsw", + fileSize: 1000000, + sha256Hash: "test", + sha1Hash: "test", + isSigned: true, + isPrerelease: false, + source: "test" + ) + + let operation = RecordOperation.create( + recordType: RestoreImageRecord.cloudKitRecordType, + recordName: testImage.recordName, + fields: testImage.toCloudKitFields() + ) + try await service.modifyRecords([operation]) + ``` + +3. **Run sync once** + + ```bash + bushel-images sync + ``` + + CloudKit will auto-create the record types in development. + +4. **Deploy schema to production** (when ready) + + In CloudKit Dashboard: + - Go to Schema section + - Click "Deploy Schema Changes" + - Review and confirm + +⚠️ **Note**: Just-in-time schema creation only works in development environment and doesn't set up indexes. + +## Getting a Management Token + +Management tokens allow `cktool` to modify your CloudKit schema. + +1. Open [CloudKit Dashboard](https://icloud.developer.apple.com/) +2. Select your container +3. Click your profile icon (top right) +4. Select "Manage Tokens" +5. Click "Create Token" +6. Give it a name: "Bushel Schema Management" +7. **Copy the token** (you won't see it again!) +8. Save it using `xcrun cktool save-token` + +## Schema File Format + +The schema is defined in `schema.ckdb` using CloudKit's declarative schema language: + +```text +RECORD TYPE RestoreImage ( + "version" STRING QUERYABLE SORTABLE SEARCHABLE, + "buildNumber" STRING QUERYABLE SORTABLE, + "releaseDate" TIMESTAMP QUERYABLE SORTABLE, + "fileSize" INT64, + "isSigned" INT64 QUERYABLE, + // ... more fields + + GRANT WRITE TO "_creator", + GRANT READ TO "_world" +); +``` + +### Key Features + +- **QUERYABLE**: Field can be used in query predicates +- **SORTABLE**: Field can be used for sorting results +- **SEARCHABLE**: Field supports full-text search +- **GRANT READ TO "_world"**: Makes records publicly readable +- **GRANT WRITE TO "_creator"**: Only creator can modify + +### Database Scope + +**Important**: The schema import applies to the **container level**, making record types available in both public and private databases. However: + +- The **Bushel demo writes to the public database** (`BushelCloudKitService.swift:16`) +- The `GRANT READ TO "_world"` permission ensures public read access +- Other apps (like Bushel itself) query the **public database** directly + +This architecture allows: +- The demo app (MistKit) to populate data in the public database +- Bushel (native CloudKit) to read that data without authentication + +### Field Type Notes + +- **Boolean → INT64**: CloudKit doesn't have a native boolean type, so we use INT64 (0 = false, 1 = true) +- **TIMESTAMP**: CloudKit's date/time field type +- **REFERENCE**: Link to another record (for relationships) + +## Schema Export + +To export your current schema (useful for version control): + +```bash +xcrun cktool export-schema \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.yourcompany.Bushel \ + --environment development \ + --output-file schema-backup.ckdb +``` + +## Validation Without Import + +To validate your schema file without importing: + +```bash +xcrun cktool validate-schema \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.yourcompany.Bushel \ + --environment development \ + schema.ckdb +``` + +## Common Issues + +### Authentication Failed + +**Problem**: "Authentication failed" or "Invalid token" + +**Solution**: +1. Generate a new management token in CloudKit Dashboard +2. Save it: `xcrun cktool save-token` +3. Ensure you're using the correct Team ID + +### Container Not Found + +**Problem**: "Container not found" or "Invalid container" + +**Solution**: +- Verify container ID matches CloudKit Dashboard exactly +- Ensure container exists and you have access +- Check Team ID is correct + +### Schema Validation Errors + +**Problem**: "Schema validation failed" with field type errors + +**Solution**: +- Ensure all field types match CloudKit's supported types +- Remember: Use INT64 for booleans, TIMESTAMP for dates +- Check for typos in field names + +### Permission Denied + +**Problem**: "Insufficient permissions to modify schema" + +**Solution**: +- Verify your Apple ID has Admin role in the container +- Check management token has correct permissions +- Try regenerating the management token + +## CI/CD Integration + +For automated deployment, you can integrate schema management into your CI/CD pipeline: + +```bash +#!/bin/bash +# In your CI/CD script + +# Load token from secure environment variable +echo "$CLOUDKIT_MANAGEMENT_TOKEN" | xcrun cktool save-token --file - + +# Import schema +xcrun cktool import-schema \ + --team-id "$TEAM_ID" \ + --container-id "$CONTAINER_ID" \ + --environment development \ + schema.ckdb +``` + +## Schema Versioning + +Best practices for managing schema changes: + +1. **Version Control**: Keep `schema.ckdb` in git +2. **Development First**: Always test changes in development environment +3. **Schema Export**: Periodically export production schema as backup +4. **Migration Plan**: Document any breaking changes +5. **Backward Compatibility**: Avoid removing fields when possible + +## Next Steps + +After setting up the schema: + +1. **Configure credentials**: See [XCODE_SCHEME_SETUP.md](./XCODE_SCHEME_SETUP.md) +2. **Run data sync**: `bushel-images sync` +3. **Verify data**: Check CloudKit Dashboard for records +4. **Test queries**: Use CloudKit Dashboard's Data section + +## Resources + +- [CloudKit Schema Documentation](https://developer.apple.com/documentation/cloudkit/designing-and-creating-a-cloudkit-database) +- [cktool Reference](https://keith.github.io/xcode-man-pages/cktool.1.html) +- [WWDC21: Automate CloudKit tests with cktool](https://developer.apple.com/videos/play/wwdc2021/10118/) +- [CloudKit Dashboard](https://icloud.developer.apple.com/) + +## Troubleshooting + +For Bushel-specific issues, see the main [README.md](./README.md). + +For CloudKit schema issues: +- Check [Apple Developer Forums](https://developer.apple.com/forums/tags/cloudkit) +- Review CloudKit Dashboard logs +- Verify schema file syntax against Apple's documentation diff --git a/Examples/Bushel/IMPLEMENTATION_NOTES.md b/Examples/Bushel/IMPLEMENTATION_NOTES.md new file mode 100644 index 00000000..3992b7b9 --- /dev/null +++ b/Examples/Bushel/IMPLEMENTATION_NOTES.md @@ -0,0 +1,430 @@ +# Bushel Demo Implementation Notes + +## Session Summary: AppleDB Integration & S2S Authentication Refactoring + +This document captures key implementation decisions, issues encountered, and solutions applied during the development of the Bushel CloudKit demo. Use this as a reference when building similar demos (e.g., Celestra). + +--- + +## Major Changes Completed + +### 1. AppleDB Data Source Integration + +**Purpose**: Fetch comprehensive restore image data with device-specific signing status for VirtualMac2,1 to complement ipsw.me's data. + +**Implementation**: +- Integrated AppleDB API for device-specific restore image information +- Created modern, error-handled implementation with Swift 6 concurrency +- Integrated as an additional fetcher in `DataSourcePipeline` + +**Files Created**: +```text +AppleDB/ +├── AppleDBParser.swift # Fetches from api.appledb.dev +├── AppleDBFetcher.swift # Implements fetcher pattern +└── Models/ + ├── AppleDBVersion.swift # Domain model with CloudKit helpers + └── AppleDBAPITypes.swift # API response types +``` + +**Key Features**: +- Device filtering for VirtualMac variants +- File size parsing (string → Int64 for CloudKit) +- Prerelease detection (beta/RC in version string) +- Robust error handling with custom error types + +**Integration Point**: +```swift +// DataSourcePipeline.swift +async let appleDBImages = options.includeAppleDB + ? AppleDBFetcher().fetch() + : [RestoreImageRecord]() +``` + +### 2. Server-to-Server Authentication Refactoring + +**Motivation**: +- Server-to-Server Keys are the recommended enterprise authentication method +- More secure than API Tokens (private key never transmitted, only signatures) +- Better demonstrates production-ready CloudKit integration + +**What Changed**: + +| Before (API Token) | After (Server-to-Server Key) | +|-------------------|------------------------------| +| Single token string | Key ID + Private Key (.pem file) | +| `APITokenManager` | `ServerToServerAuthManager` | +| `CLOUDKIT_API_TOKEN` env var | `CLOUDKIT_KEY_ID` + `CLOUDKIT_KEY_FILE` | +| `--api-token` flag | `--key-id` + `--key-file` flags | + +**Files Modified**: +1. `BushelCloudKitService.swift` - Switch to `ServerToServerAuthManager` +2. `SyncEngine.swift` - Update initializer parameters +3. `SyncCommand.swift` - New CLI options and env vars +4. `ExportCommand.swift` - New CLI options and env vars +5. `setup-cloudkit-schema.sh` - Updated instructions +6. `README.md` - Comprehensive S2S documentation + +**New Usage**: +```bash +# Command-line flags +bushel-images sync \ + --key-id "YOUR_KEY_ID" \ + --key-file ./private-key.pem + +# Environment variables (recommended) +export CLOUDKIT_KEY_ID="YOUR_KEY_ID" +export CLOUDKIT_KEY_FILE="$HOME/.cloudkit/bushel-private-key.pem" +bushel-images sync +``` + +--- + +## Critical Issues Solved + +### Issue 1: CloudKit Schema File Format + +**Problem**: `cktool validate-schema` failed with parsing error. + +**Root Cause**: Schema file was missing `DEFINE SCHEMA` header and included CloudKit system fields. + +**Solution**: +```text +# Before (incorrect) +RECORD TYPE RestoreImage ( + "__recordID" RECORD ID, # ❌ System fields shouldn't be in schema + ... +) + +# After (correct) +DEFINE SCHEMA + +RECORD TYPE RestoreImage ( + "version" STRING QUERYABLE, # ✅ Only user-defined fields + ... +) +``` + +**Lesson**: CloudKit automatically adds system fields (`__recordID`, `___createTime`, etc.). Never include them in schema definitions. + +### Issue 2: Authentication Terminology Confusion + +**Problem**: Confusing "API Token", "Server-to-Server Key", "Management Token", and "User Token". + +**Clarification**: + +| Token Type | Used For | Used By | Where to Get | +|-----------|----------|---------|--------------| +| **Management Token** | Schema operations (import/export) | `cktool` | Dashboard → CloudKit Web Services | +| **Server-to-Server Key** | Runtime API operations (server-side) | `ServerToServerAuthManager` | Dashboard → Server-to-Server Keys | +| **API Token** | Runtime API operations (simpler) | `APITokenManager` | Dashboard → API Tokens | +| **User Token** | User-specific operations | Web apps with user auth | OAuth-like flow | + +**For Bushel Demo**: +- Schema setup: **Management Token** (via `cktool save-token`) +- Sync/Export commands: **Server-to-Server Key** (Key ID + .pem file) + +### Issue 3: cktool Command Syntax + +**Problem**: Script used non-existent `list-containers` command and missing `--file` flag. + +**Fixes**: +```bash +# Token check (before - wrong) +xcrun cktool list-containers # ❌ Not a valid command + +# Token check (after - correct) +xcrun cktool get-teams # ✅ Valid command that requires auth + +# Schema validation (before - wrong) +xcrun cktool validate-schema ... "$SCHEMA_FILE" # ❌ Missing --file + +# Schema validation (after - correct) +xcrun cktool validate-schema ... --file "$SCHEMA_FILE" # ✅ Correct syntax +``` + +--- + +## MistKit Authentication Architecture + +### How ServerToServerAuthManager Works + +1. **Initialization**: +```swift +let tokenManager = try ServerToServerAuthManager( + keyID: "YOUR_KEY_ID", + pemString: pemFileContents // Reads from .pem file +) +``` + +2. **What happens internally**: + - Parses PEM string into ECDSA P-256 private key + - Stores key ID and private key data + - Creates `TokenCredentials` with `.serverToServer` method + +3. **Request signing** (handled by MistKit): + - For each CloudKit API request + - Creates signature using private key + - Sends Key ID + signature in headers + - Server verifies with public key + +### BushelCloudKitService Pattern + +```swift +struct BushelCloudKitService { + init(containerIdentifier: String, keyID: String, privateKeyPath: String) throws { + // 1. Validate file exists + guard FileManager.default.fileExists(atPath: privateKeyPath) else { + throw BushelCloudKitError.privateKeyFileNotFound(path: privateKeyPath) + } + + // 2. Read PEM file + let pemString = try String(contentsOfFile: privateKeyPath, encoding: .utf8) + + // 3. Create auth manager + let tokenManager = try ServerToServerAuthManager( + keyID: keyID, + pemString: pemString + ) + + // 4. Create CloudKit service + self.service = try CloudKitService( + containerIdentifier: containerIdentifier, + tokenManager: tokenManager, + environment: .development, + database: .public + ) + } +} +``` + +--- + +## Data Source Integration Pattern + +### Adding a New Data Source (AppleDB Example) + +**Step 1: Create Fetcher** +```swift +struct AppleDBFetcher: Sendable { + func fetch() async throws -> [RestoreImageRecord] { + // Fetch and parse data + // Map to CloudKit record model + // Return array + } +} +``` + +**Step 2: Add to Pipeline Options** +```swift +struct DataSourcePipeline { + struct Options: Sendable { + var includeAppleDB: Bool = true + } +} +``` + +**Step 3: Integrate into Pipeline** +```swift +private func fetchRestoreImages(options: Options) async throws -> [RestoreImageRecord] { + // Parallel fetching + async let appleDBImages = options.includeAppleDB + ? AppleDBFetcher().fetch() + : [RestoreImageRecord]() + + // Collect results + allImages.append(contentsOf: try await appleDBImages) + + // Deduplicate by buildNumber + return deduplicateRestoreImages(allImages) +} +``` + +**Step 4: Add CLI Option** +```swift +struct SyncCommand { + @Flag(name: .long, help: "Exclude AppleDB.dev as data source") + var noAppleDB: Bool = false + + private func buildSyncOptions() -> SyncEngine.SyncOptions { + if noAppleDB { + pipelineOptions.includeAppleDB = false + } + } +} +``` + +### Deduplication Strategy + +Bushel uses **buildNumber** as the unique key: + +```swift +private func deduplicateRestoreImages(_ images: [RestoreImageRecord]) -> [RestoreImageRecord] { + var uniqueImages: [String: RestoreImageRecord] = [:] + + for image in images { + let key = image.buildNumber + + if let existing = uniqueImages[key] { + // Merge records, prefer most complete data + uniqueImages[key] = mergeRestoreImages(existing, image) + } else { + uniqueImages[key] = image + } + } + + return Array(uniqueImages.values).sorted { $0.releaseDate > $1.releaseDate } +} +``` + +**Merge Priority**: +1. ipsw.me (most complete: has both SHA1 + SHA256) +2. AppleDB (device-specific signing status, comprehensive coverage) +3. MESU (freshness detection only) +4. MrMacintosh (beta/RC releases) + +--- + +## Security Best Practices + +### Private Key Management + +**Storage**: +```bash +# Create secure directory +mkdir -p ~/.cloudkit +chmod 700 ~/.cloudkit + +# Store private key securely +mv ~/Downloads/AuthKey_*.pem ~/.cloudkit/bushel-private-key.pem +chmod 600 ~/.cloudkit/bushel-private-key.pem +``` + +**Environment Setup**: +```bash +# Add to ~/.zshrc or ~/.bashrc +export CLOUDKIT_KEY_ID="your_key_id" +export CLOUDKIT_KEY_FILE="$HOME/.cloudkit/bushel-private-key.pem" +``` + +**Git Protection**: +```gitignore +# .gitignore +*.pem +.env +``` + +**Never**: +- ❌ Commit .pem files to version control +- ❌ Share private keys in Slack/email +- ❌ Store in public locations +- ❌ Use same key across development/production + +**Always**: +- ✅ Use environment variables +- ✅ Set restrictive file permissions (600) +- ✅ Store in user-specific locations (~/.cloudkit/) +- ✅ Generate separate keys per environment +- ✅ Rotate keys periodically + +--- + +## Common Error Messages & Solutions + +### "Private key file not found" +```text +BushelCloudKitError.privateKeyFileNotFound(path: "./key.pem") +``` +**Solution**: Use absolute path or ensure working directory is correct. + +### "PEM string is invalid" +```text +TokenManagerError.invalidCredentials(.invalidPEMFormat) +``` +**Solution**: Verify .pem file is valid. Check for: +- Correct BEGIN/END markers +- No corruption during download +- Proper encoding (UTF-8) + +### "Key ID is empty" +```text +TokenManagerError.invalidCredentials(.keyIdEmpty) +``` +**Solution**: Ensure `CLOUDKIT_KEY_ID` is set or `--key-id` is provided. + +### "Schema validation failed: Was expecting DEFINE" +```text +❌ Schema validation failed: Encountered "RECORD" at line 1 +Was expecting: "DEFINE" ... +``` +**Solution**: Add `DEFINE SCHEMA` header at top of schema.ckdb file. + +--- + +## CloudKit Dashboard Navigation + +### Schema Setup (Management Token) +1. Go to [CloudKit Dashboard](https://icloud.developer.apple.com/dashboard/) +2. Select your container +3. Navigate to: **API Access** → **CloudKit Web Services** +4. Click **Generate Management Token** +5. Copy token and run: `xcrun cktool save-token` + +### Runtime Auth (Server-to-Server Key) +1. Go to [CloudKit Dashboard](https://icloud.developer.apple.com/dashboard/) +2. Select your container +3. Navigate to: **API Access** → **Server-to-Server Keys** +4. Click **Create a Server-to-Server Key** +5. Download .pem file (can't download again!) +6. Note the Key ID displayed + +--- + +## Testing Checklist + +Before considering Bushel complete: + +- [ ] Schema imports successfully with `setup-cloudkit-schema.sh` +- [ ] Sync command fetches from all data sources +- [ ] AppleDB fetcher returns VirtualMac2,1 data +- [ ] Deduplication works correctly (no duplicate buildNumbers) +- [ ] Records upload to CloudKit public database +- [ ] Export command retrieves and formats data +- [ ] Error messages are helpful +- [ ] Private keys are properly protected (.gitignore) +- [ ] Documentation is complete and accurate + +--- + +## Lessons for Celestra Demo + +When building the Celestra demo, apply these patterns: + +1. **Authentication**: Start with Server-to-Server Keys from the beginning +2. **Schema**: Always include `DEFINE SCHEMA` header, no system fields +3. **Fetchers**: Use the same pipeline pattern for data sources +4. **Error Handling**: Create custom error types with helpful messages +5. **CLI Design**: Use `--key-id` and `--key-file` flags consistently +6. **Documentation**: Include comprehensive authentication setup section +7. **Security**: Create .gitignore immediately with `*.pem` entry + +### Reusable Patterns + +**BushelCloudKitService pattern** → Can be copied for Celestra +**DataSourcePipeline pattern** → Adapt for Celestra's data sources +**RecordBuilder pattern** → Reuse for Celestra's record types +**CLI structure** → Same flag naming and env var conventions + +--- + +## References + +- MistKit: `Sources/MistKit/Authentication/ServerToServerAuthManager.swift` +- CloudKit Schema: `Examples/Bushel/schema.ckdb` +- Setup Script: `Examples/Bushel/Scripts/setup-cloudkit-schema.sh` +- Pipeline: `Examples/Bushel/Sources/BushelImages/DataSources/DataSourcePipeline.swift` + +--- + +**Last Updated**: Current session +**Status**: AppleDB integration complete, S2S auth refactoring complete, ready for testing diff --git a/Examples/Bushel/Package.resolved b/Examples/Bushel/Package.resolved new file mode 100644 index 00000000..c26c2271 --- /dev/null +++ b/Examples/Bushel/Package.resolved @@ -0,0 +1,123 @@ +{ + "originHash" : "49101adc127b15b12356a82f5e23d4330446434fff2c05a660d994bbea54b871", + "pins" : [ + { + "identity" : "ipswdownloads", + "kind" : "remoteSourceControl", + "location" : "https://github.com/brightdigit/IPSWDownloads.git", + "state" : { + "revision" : "2e8ad36b5f74285dbe104e7ae99f8be0cd06b7b8", + "version" : "1.0.2" + } + }, + { + "identity" : "lrucache", + "kind" : "remoteSourceControl", + "location" : "https://github.com/nicklockwood/LRUCache.git", + "state" : { + "revision" : "0d91406ecd4d6c1c56275866f00508d9aeacc92a", + "version" : "1.2.0" + } + }, + { + "identity" : "osver", + "kind" : "remoteSourceControl", + "location" : "https://github.com/brightdigit/OSVer", + "state" : { + "revision" : "448f170babc2f6c9897194a4b42719994639325d", + "version" : "1.0.0" + } + }, + { + "identity" : "swift-argument-parser", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-argument-parser.git", + "state" : { + "revision" : "cdd0ef3755280949551dc26dee5de9ddeda89f54", + "version" : "1.6.2" + } + }, + { + "identity" : "swift-asn1", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-asn1.git", + "state" : { + "revision" : "40d25bbb2fc5b557a9aa8512210bded327c0f60d", + "version" : "1.5.0" + } + }, + { + "identity" : "swift-atomics", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-atomics.git", + "state" : { + "revision" : "b601256eab081c0f92f059e12818ac1d4f178ff7", + "version" : "1.3.0" + } + }, + { + "identity" : "swift-collections", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-collections", + "state" : { + "revision" : "7b847a3b7008b2dc2f47ca3110d8c782fb2e5c7e", + "version" : "1.3.0" + } + }, + { + "identity" : "swift-crypto", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-crypto.git", + "state" : { + "revision" : "95ba0316a9b733e92bb6b071255ff46263bbe7dc", + "version" : "3.15.1" + } + }, + { + "identity" : "swift-http-types", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-http-types", + "state" : { + "revision" : "45eb0224913ea070ec4fba17291b9e7ecf4749ca", + "version" : "1.5.1" + } + }, + { + "identity" : "swift-log", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-log.git", + "state" : { + "revision" : "ce592ae52f982c847a4efc0dd881cc9eb32d29f2", + "version" : "1.6.4" + } + }, + { + "identity" : "swift-openapi-runtime", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-openapi-runtime", + "state" : { + "revision" : "7722cf8eac05c1f1b5b05895b04cfcc29576d9be", + "version" : "1.8.3" + } + }, + { + "identity" : "swift-openapi-urlsession", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-openapi-urlsession", + "state" : { + "revision" : "279aa6b77be6aa842a4bf3c45fa79fa15edf3e07", + "version" : "1.2.0" + } + }, + { + "identity" : "swiftsoup", + "kind" : "remoteSourceControl", + "location" : "https://github.com/scinfu/SwiftSoup.git", + "state" : { + "revision" : "4206bc7b8bd9a4ff8e9511211e1b4bff979ef9c4", + "version" : "2.11.1" + } + } + ], + "version" : 3 +} diff --git a/Examples/Bushel/Package.swift b/Examples/Bushel/Package.swift new file mode 100644 index 00000000..82ddaa16 --- /dev/null +++ b/Examples/Bushel/Package.swift @@ -0,0 +1,109 @@ +// swift-tools-version: 6.2 +// The swift-tools-version declares the minimum version of Swift required to build this package. + +// swiftlint:disable explicit_acl explicit_top_level_acl + +import PackageDescription + +// MARK: - Swift Settings Configuration + +let swiftSettings: [SwiftSetting] = [ + // Swift 6.2 Upcoming Features (not yet enabled by default) + // SE-0335: Introduce existential `any` + .enableUpcomingFeature("ExistentialAny"), + // SE-0409: Access-level modifiers on import declarations + .enableUpcomingFeature("InternalImportsByDefault"), + // SE-0444: Member import visibility (Swift 6.1+) + .enableUpcomingFeature("MemberImportVisibility"), + // SE-0413: Typed throws + .enableUpcomingFeature("FullTypedThrows"), + + // Experimental Features (stable enough for use) + // SE-0426: BitwiseCopyable protocol + .enableExperimentalFeature("BitwiseCopyable"), + // SE-0432: Borrowing and consuming pattern matching for noncopyable types + .enableExperimentalFeature("BorrowingSwitch"), + // Extension macros + .enableExperimentalFeature("ExtensionMacros"), + // Freestanding expression macros + .enableExperimentalFeature("FreestandingExpressionMacros"), + // Init accessors + .enableExperimentalFeature("InitAccessors"), + // Isolated any types + .enableExperimentalFeature("IsolatedAny"), + // Move-only classes + .enableExperimentalFeature("MoveOnlyClasses"), + // Move-only enum deinits + .enableExperimentalFeature("MoveOnlyEnumDeinits"), + // SE-0429: Partial consumption of noncopyable values + .enableExperimentalFeature("MoveOnlyPartialConsumption"), + // Move-only resilient types + .enableExperimentalFeature("MoveOnlyResilientTypes"), + // Move-only tuples + .enableExperimentalFeature("MoveOnlyTuples"), + // SE-0427: Noncopyable generics + .enableExperimentalFeature("NoncopyableGenerics"), + // One-way closure parameters + // .enableExperimentalFeature("OneWayClosureParameters"), + // Raw layout types + .enableExperimentalFeature("RawLayout"), + // Reference bindings + .enableExperimentalFeature("ReferenceBindings"), + // SE-0430: sending parameter and result values + .enableExperimentalFeature("SendingArgsAndResults"), + // Symbol linkage markers + .enableExperimentalFeature("SymbolLinkageMarkers"), + // Transferring args and results + .enableExperimentalFeature("TransferringArgsAndResults"), + // SE-0393: Value and Type Parameter Packs + .enableExperimentalFeature("VariadicGenerics"), + // Warn unsafe reflection + .enableExperimentalFeature("WarnUnsafeReflection"), + + // Enhanced compiler checking + .unsafeFlags([ + // Enable concurrency warnings + "-warn-concurrency", + // Enable actor data race checks + "-enable-actor-data-race-checks", + // Complete strict concurrency checking + "-strict-concurrency=complete", + // Enable testing support + "-enable-testing", + // Warn about functions with >100 lines + "-Xfrontend", "-warn-long-function-bodies=100", + // Warn about slow type checking expressions + "-Xfrontend", "-warn-long-expression-type-checking=100" + ]) +] + +let package = Package( + name: "Bushel", + platforms: [ + .macOS(.v14) + ], + products: [ + .executable(name: "bushel-images", targets: ["BushelImages"]) + ], + dependencies: [ + .package(name: "MistKit", path: "../.."), + .package(url: "https://github.com/brightdigit/IPSWDownloads.git", from: "1.0.0"), + .package(url: "https://github.com/scinfu/SwiftSoup.git", from: "2.6.0"), + .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.5.0"), + .package(url: "https://github.com/apple/swift-log.git", from: "1.0.0") + ], + targets: [ + .executableTarget( + name: "BushelImages", + dependencies: [ + .product(name: "MistKit", package: "MistKit"), + .product(name: "IPSWDownloads", package: "IPSWDownloads"), + .product(name: "SwiftSoup", package: "SwiftSoup"), + .product(name: "ArgumentParser", package: "swift-argument-parser"), + .product(name: "Logging", package: "swift-log") + ], + swiftSettings: swiftSettings + ) + ] +) +// swiftlint:enable explicit_acl explicit_top_level_acl diff --git a/Examples/Bushel/README.md b/Examples/Bushel/README.md new file mode 100644 index 00000000..d416e66d --- /dev/null +++ b/Examples/Bushel/README.md @@ -0,0 +1,595 @@ +# Bushel Demo - CloudKit Data Synchronization + +A command-line tool demonstrating MistKit's CloudKit Web Services capabilities by syncing macOS restore images, Xcode versions, and Swift compiler versions to CloudKit. + +> 📖 **Tutorial-Friendly Demo** - This example is designed for developers learning CloudKit and MistKit. Use the `--verbose` flag to see detailed explanations of CloudKit operations and MistKit usage patterns. + +## 🎓 What You'll Learn + +This demo teaches practical CloudKit development patterns: + +- ✅ **Server-to-Server Authentication** - How to authenticate CloudKit operations from command-line tools and servers +- ✅ **Batch Record Operations** - Handling CloudKit's 200-operation-per-request limit efficiently +- ✅ **Record Relationships** - Using CKReference to create relationships between records +- ✅ **Multi-Source Data Integration** - Fetching, deduplicating, and merging data from multiple APIs +- ✅ **Modern Swift Patterns** - async/await, Sendable types, and Swift 6 concurrency + +**New to CloudKit?** Start with the [Quick Start Guide](#quick-start) below, then explore verbose mode to see how everything works under the hood. + +## Overview + +Bushel is a comprehensive demo application showcasing how to use MistKit to: + +- Fetch data from multiple sources (ipsw.me, AppleDB.dev, xcodereleases.com, swift.org, MESU, Mr. Macintosh) +- Transform data into CloudKit-compatible record structures +- Batch upload records to CloudKit using the Web Services REST API +- Handle relationships between records using CloudKit References +- Export data for analysis or backup + +## What is "Bushel"? + +In Apple's virtualization framework, **restore images** are used to boot virtual Macintosh systems. These images are essential for running macOS VMs and are distributed through Apple's software update infrastructure. Bushel collects and organizes information about these images along with related Xcode and Swift versions, making it easier to manage virtualization environments. + +## Architecture + +### Data Sources + +The demo integrates with multiple data sources to gather comprehensive version information: + +1. **IPSW.me API** (via [IPSWDownloads](https://github.com/brightdigit/IPSWDownloads)) + - macOS restore images for VirtualMac2,1 + - Build numbers, release dates, signatures, file sizes + +2. **AppleDB.dev** + - Comprehensive macOS restore image database + - Device-specific signing status + - VirtualMac2,1 compatibility information + - Maintained by LittleByte Organization + +3. **XcodeReleases.com** + - Xcode versions and build numbers + - Release dates and prerelease status + - Download URLs and SDK information + +4. **Swift.org** + - Swift compiler versions + - Release dates and download links + - Official Swift toolchain information + +5. **Apple MESU Catalog** (Mobile Equipment Software Update) + - Official macOS restore image catalog + - Asset metadata and checksums + +6. **Mr. Macintosh's Restore Image Archive** + - Historical restore image information + - Community-maintained release data + +### Components + +```text +BushelImages/ +├── DataSources/ # Data fetchers for external APIs +│ ├── IPSWFetcher.swift +│ ├── XcodeReleasesFetcher.swift +│ ├── SwiftVersionFetcher.swift +│ ├── MESUFetcher.swift +│ ├── MrMacintoshFetcher.swift +│ └── DataSourcePipeline.swift +├── Models/ # Data models +│ ├── RestoreImageRecord.swift +│ ├── XcodeVersionRecord.swift +│ └── SwiftVersionRecord.swift +├── CloudKit/ # CloudKit integration +│ ├── BushelCloudKitService.swift +│ ├── RecordBuilder.swift +│ └── SyncEngine.swift +└── Commands/ # CLI commands + ├── BushelImagesCLI.swift + ├── SyncCommand.swift + └── ExportCommand.swift +``` + +## Features Demonstrated + +### MistKit Capabilities + +✅ **Public API Usage** +- Uses only public MistKit APIs (no internal OpenAPI types) +- Demonstrates proper abstraction layer design + +✅ **Record Operations** +- Creating records with `RecordOperation.create()` +- Batch operations with `modifyRecords()` +- Proper field value mapping with `FieldValue` enum + +✅ **Data Type Support** +- Strings, integers, booleans, dates +- CloudKit References (relationships between records) +- Proper date/timestamp conversion (milliseconds since epoch) + +✅ **Batch Processing** +- CloudKit's 200-operation-per-request limit handling +- Progress reporting during sync +- Error handling for partial failures + +✅ **Authentication** +- Server-to-Server Key authentication with `ServerToServerAuthManager` +- ECDSA P-256 private key signing +- Container and environment configuration + +### Swift 6 Best Practices + +✅ **Strict Concurrency** +- All types conform to `Sendable` +- Async/await throughout +- No data races + +✅ **Modern Error Handling** +- Typed errors with `CloudKitError` +- Proper error propagation with `throws` + +✅ **Value Semantics** +- Immutable structs for data models +- No reference types in concurrent contexts + +## Quick Start + +### Prerequisites + +1. **CloudKit Container** - Create a container in CloudKit Dashboard +2. **Server-to-Server Key** - Generate from CloudKit Dashboard → API Access +3. **Private Key File** - Download the `.pem` file when creating the key + +See [CLOUDKIT-SETUP.md](./CLOUDKIT-SETUP.md) for detailed setup instructions. + +### Building + +```bash +# From Bushel directory +swift build + +# Run the demo +.build/debug/bushel-images --help +``` + +### First Sync (Learning Mode) + +Run with `--verbose` to see educational explanations of what's happening: + +```bash +export CLOUDKIT_KEY_ID="YOUR_KEY_ID" +export CLOUDKIT_KEY_FILE="./path/to/private-key.pem" + +# Sync with verbose logging to learn how MistKit works +.build/debug/bushel-images sync --verbose + +# Or do a dry run first to see what would be synced +.build/debug/bushel-images sync --dry-run --verbose +``` + +**What the verbose flag shows:** +- 🔍 How MistKit authenticates with Server-to-Server keys +- 💡 CloudKit batch processing (200 operations/request limit) +- 📊 Data source fetching and deduplication +- ⚙️ Record dependency ordering +- 🌐 Actual CloudKit API calls and responses + +## Usage + +### Sync Command + +Fetch data from all sources and upload to CloudKit: + +```bash +# Basic usage +bushel-images sync \ + --container-id "iCloud.com.brightdigit.Bushel" \ + --key-id "YOUR_KEY_ID" \ + --key-file ./path/to/private-key.pem + +# With verbose logging (recommended for learning) +bushel-images sync --verbose + +# Dry run (fetch data but don't upload to CloudKit) +bushel-images sync --dry-run + +# Selective sync +bushel-images sync --restore-images-only +bushel-images sync --xcode-only +bushel-images sync --swift-only +bushel-images sync --no-betas # Exclude beta/RC releases + +# Use environment variables (recommended) +export CLOUDKIT_KEY_ID="YOUR_KEY_ID" +export CLOUDKIT_KEY_FILE="./path/to/private-key.pem" +bushel-images sync --verbose +``` + +### Export Command + +Query and export CloudKit data to JSON file: + +```bash +# Export to file +bushel-images export \ + --container-id "iCloud.com.brightdigit.Bushel" \ + --key-id "YOUR_KEY_ID" \ + --key-file ./path/to/private-key.pem \ + --output ./bushel-data.json + +# With verbose logging +bushel-images export --verbose --output ./bushel-data.json + +# Pretty-print JSON +bushel-images export --pretty --output ./bushel-data.json + +# Export to stdout for piping +bushel-images export --pretty | jq '.restoreImages | length' +``` + +### Help + +```bash +bushel-images --help +bushel-images sync --help +bushel-images export --help +``` + +### Xcode Setup + +See [XCODE_SCHEME_SETUP.md](./XCODE_SCHEME_SETUP.md) for detailed instructions on: +- Configuring the Xcode scheme +- Setting environment variables +- Getting CloudKit credentials +- Debugging tips + +## CloudKit Schema + +The demo uses three record types with relationships: + +```text +SwiftVersion + ↑ + | (reference) + | +RestoreImage ← XcodeVersion + ↑ ↑ + | (reference) | + |______________| +``` + +### Record Relationships + +- **XcodeVersion → RestoreImage**: Links Xcode to minimum macOS version required +- **XcodeVersion → SwiftVersion**: Links Xcode to included Swift compiler version + +### Example Data Flow + +1. Fetch Swift 6.0.3 → Create SwiftVersion record +2. Fetch macOS 15.2 restore image → Create RestoreImage record +3. Fetch Xcode 16.2 → Create XcodeVersion record with references to both + +## Implementation Highlights + +### CloudKitRecord Protocol Pattern + +Shows how to convert domain models to CloudKit records using the `CloudKitRecord` protocol: + +```swift +extension RestoreImageRecord: CloudKitRecord { + static var cloudKitRecordType: String { "RestoreImage" } + + func toCloudKitFields() -> [String: FieldValue] { + var fields: [String: FieldValue] = [ + "version": .string(version), + "buildNumber": .string(buildNumber), + "releaseDate": .date(releaseDate), + "fileSize": .int64(Int(fileSize)), + "isSigned": .boolean(isSigned), + // ... more fields + ] + return fields + } + + static func from(recordInfo: RecordInfo) -> Self? { + // Parse CloudKit record into domain model + guard let fields = recordInfo.fields else { return nil } + // ... field extraction + return RestoreImageRecord(/* ... */) + } +} +``` + +### Batch Processing + +Demonstrates efficient CloudKit batch operations: + +```swift +private func executeBatchOperations( + _ operations: [RecordOperation], + recordType: String +) async throws { + let batchSize = 200 // CloudKit limit + let batches = operations.chunked(into: batchSize) + + for (index, batch) in batches.enumerated() { + print(" Batch \(index + 1)/\(batches.count)...") + _ = try await service.modifyRecords(batch) + } +} +``` + +### Data Source Pipeline + +Shows async/await parallel data fetching: + +```swift +struct DataSourcePipeline: Sendable { + func fetchAllData() async throws -> ( + restoreImages: [RestoreImageRecord], + xcodeVersions: [XcodeVersionRecord], + swiftVersions: [SwiftVersionRecord] + ) { + async let restoreImages = ipswFetcher.fetch() + async let xcodeVersions = xcodeReleasesFetcher.fetch() + async let swiftVersions = swiftVersionFetcher.fetch() + + return try await (restoreImages, xcodeVersions, swiftVersions) + } +} +``` + +## Requirements + +- macOS 14.0+ (for demonstration purposes; MistKit supports macOS 11.0+) +- Swift 6.2+ +- Xcode 16.2+ (for development) +- CloudKit container with appropriate schema (see setup below) +- CloudKit Server-to-Server Key (Key ID + private .pem file) + +## CloudKit Schema Setup + +Before running the sync command, you need to set up the CloudKit schema. The schema will be created at the container level, but **Bushel writes all records to the public database** for worldwide accessibility. + +You have two options: + +### Option 1: Automated Setup (Recommended) + +Use `cktool` to automatically import the schema: + +```bash +# Save your CloudKit management token +xcrun cktool save-token + +# Set environment variables +export CLOUDKIT_CONTAINER_ID="iCloud.com.yourcompany.Bushel" +export CLOUDKIT_TEAM_ID="YOUR_TEAM_ID" + +# Run the setup script +cd Examples/Bushel +./Scripts/setup-cloudkit-schema.sh +``` + +See [CLOUDKIT_SCHEMA_SETUP.md](./CLOUDKIT_SCHEMA_SETUP.md) for detailed instructions. + +### Option 2: Manual Setup + +Create the record types manually in [CloudKit Dashboard](https://icloud.developer.apple.com/). + +See [XCODE_SCHEME_SETUP.md](./XCODE_SCHEME_SETUP.md#cloudkit-schema-setup) for field definitions. + +## Authentication Setup + +After setting up your CloudKit schema, you need to create a Server-to-Server Key for authentication: + +### Getting Your Server-to-Server Key + +1. Go to [CloudKit Dashboard](https://icloud.developer.apple.com/dashboard/) +2. Select your container +3. Navigate to **API Access** → **Server-to-Server Keys** +4. Click **Create a Server-to-Server Key** +5. Enter a key name (e.g., "Bushel Demo Key") +6. Click **Create** +7. **Download the private key .pem file** - You won't be able to download it again! +8. Note the **Key ID** displayed (e.g., "abc123def456") + +### Secure Your Private Key + +⚠️ **Security Best Practices:** + +- Store the `.pem` file in a secure location (e.g., `~/.cloudkit/bushel-private-key.pem`) +- **Never commit .pem files to version control** (already in `.gitignore`) +- Use appropriate file permissions: `chmod 600 ~/.cloudkit/bushel-private-key.pem` +- Consider using environment variables for the key path + +### Using Your Credentials + +**Method 1: Command-line flags** +```bash +bushel-images sync \ + --key-id "YOUR_KEY_ID" \ + --key-file ~/.cloudkit/bushel-private-key.pem +``` + +**Method 2: Environment variables** (recommended for frequent use) +```bash +# Add to your ~/.zshrc or ~/.bashrc +export CLOUDKIT_KEY_ID="YOUR_KEY_ID" +export CLOUDKIT_KEY_FILE="$HOME/.cloudkit/bushel-private-key.pem" + +# Then simply run +bushel-images sync +``` + +## Dependencies + +- **MistKit** - CloudKit Web Services client (local path dependency) +- **IPSWDownloads** - ipsw.me API wrapper +- **SwiftSoup** - HTML parsing for web scraping +- **ArgumentParser** - CLI argument parsing + +## Data Sources + +Bushel fetches data from multiple external sources including: + +- **ipsw.me** - macOS restore images for VirtualMac devices +- **AppleDB.dev** - Comprehensive restore image database with device-specific signing information +- **xcodereleases.com** - Xcode versions and build information +- **swift.org** - Swift compiler versions +- **Apple MESU** - Official restore image metadata +- **Mr. Macintosh** - Community-maintained release archive + +The `sync` command fetches from all sources, deduplicates records, and uploads to CloudKit. + +The `export` command queries existing records from your CloudKit database and exports them to JSON format. + +## Limitations & Future Enhancements + +### Current Limitations + +- ⚠️ No duplicate detection (will create duplicate records on repeated syncs) +- ⚠️ No incremental sync (always fetches all data) +- ⚠️ No conflict resolution for concurrent updates +- ⚠️ Limited error recovery in batch operations + +### Potential Enhancements + +- [ ] Add `--update` mode to update existing records instead of creating new ones +- [ ] Implement incremental sync with change tracking +- [ ] Add record deduplication logic +- [ ] Support for querying existing records before sync +- [ ] Progress bar for long-running operations +- [ ] Retry logic for transient network errors +- [ ] Validation of record references before upload +- [ ] Support for CloudKit zones for better organization + +## Troubleshooting + +### Common Beginner Issues + +**❌ "Private key file not found"** +```bash +✅ Solution: Check that your .pem file path is correct +export CLOUDKIT_KEY_FILE="$HOME/.cloudkit/bushel-private-key.pem" +ls -la "$CLOUDKIT_KEY_FILE" # Verify file exists +``` + +**❌ "Authentication failed" or "Invalid signature"** +```text +✅ Solutions: +1. Verify Key ID matches the key in CloudKit Dashboard +2. Check that .pem file is the correct private key (not certificate) +3. Ensure key hasn't been revoked in CloudKit Dashboard +4. Try regenerating the key if issues persist +``` + +**❌ "Record type not found" errors** +```bash +✅ Solution: Set up CloudKit schema first +cd Examples/Bushel +./Scripts/setup-cloudkit-schema.sh +# Or manually create record types in CloudKit Dashboard +``` + +**❌ Seeing duplicate records after re-sync** +```text +✅ This is expected behavior - Bushel creates new records each sync +See "Limitations" section for details on incremental sync +``` + +**❌ "Operation failed" with no details** +```bash +✅ Solution: Use --verbose flag to see CloudKit error details +bushel-images sync --verbose +# Look for serverErrorCode and reason in output +``` + +### Getting Help + +**For verbose logging:** +- Always run with `--verbose` flag when troubleshooting +- Check the console for 🔍 (verbose), 💡 (explanations), and ⚠️ (warnings) + +**For CloudKit errors:** +- Review CloudKit Dashboard for schema configuration +- Verify Server-to-Server key is active +- Check container identifier matches your CloudKit container + +**For MistKit issues:** +- See [MistKit repository](https://github.com/brightdigit/MistKit) for documentation +- Check MistKit's test suite for usage examples + +## Learning Resources + +### For Beginners + +**Start Here:** +1. Run `bushel-images sync --dry-run --verbose` to see what happens without uploading +2. Review the code in `SyncEngine.swift` to understand the flow +3. Check `BushelCloudKitService.swift` for MistKit usage patterns +4. Explore `RecordBuilder.swift` to see CloudKit record construction + +**Key Files to Study:** +- `BushelCloudKitService.swift` - Server-to-Server authentication and batch operations +- `SyncEngine.swift` - Overall sync orchestration +- `RecordBuilder.swift` - CloudKit record field mapping +- `DataSourcePipeline.swift` - Multi-source data integration + +### Using Bushel as a Reference + +**This demo is designed to be reusable for your own CloudKit projects:** + +✅ **Copy the authentication pattern** from `BushelCloudKitService.swift` +- Shows how to load private keys from disk +- Demonstrates ServerToServerAuthManager setup +- Handles all ECDSA signing automatically + +✅ **Adapt the batch processing** from `executeBatchOperations()` +- Handles CloudKit's 200-operation limit +- Shows progress reporting +- Demonstrates error handling for partial failures + +✅ **Use the logging pattern** from `Logger.swift` +- os.Logger with subsystems for organization +- Verbose mode for development/debugging +- Educational explanations for documentation + +✅ **Reference record building** from `RecordBuilder.swift` +- Shows CloudKit field mapping +- Demonstrates CKReference relationships +- Handles date conversion (milliseconds since epoch) + +### MistKit Documentation + +- [MistKit Repository](https://github.com/brightdigit/MistKit) +- See main repository's CLAUDE.md for development guidelines + +### Apple Documentation + +- [CloudKit Web Services Reference](https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/) +- [CloudKit Dashboard](https://icloud.developer.apple.com/) +- [Server-to-Server Key Authentication Guide](https://developer.apple.com/documentation/cloudkitjs/ckservertoclientauth) + +### Related Projects + +- [IPSWDownloads](https://github.com/brightdigit/IPSWDownloads) - ipsw.me API client +- [XcodeReleases.com](https://xcodereleases.com/) - Xcode version tracking +- **Celestra** (coming soon) - RSS aggregator using MistKit (sibling demo) + +## Contributing + +This is a demonstration project. For contributions to MistKit itself, please see the main repository. + +## License + +Same as MistKit - MIT License. See main repository LICENSE file. + +## Questions? + +For issues specific to this demo: +- Check [XCODE_SCHEME_SETUP.md](./XCODE_SCHEME_SETUP.md) for configuration help +- Review CloudKit Dashboard for schema and authentication issues + +For MistKit issues: +- Open an issue in the main MistKit repository +- Include relevant code snippets and error messages diff --git a/Examples/Bushel/Scripts/setup-cloudkit-schema.sh b/Examples/Bushel/Scripts/setup-cloudkit-schema.sh new file mode 100755 index 00000000..16d134b2 --- /dev/null +++ b/Examples/Bushel/Scripts/setup-cloudkit-schema.sh @@ -0,0 +1,162 @@ +#!/bin/bash + +# CloudKit Schema Setup Script +# This script imports the Bushel schema into your CloudKit container + +set -eo pipefail + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +echo "========================================" +echo "CloudKit Schema Setup for Bushel" +echo "========================================" +echo "" + +# Check if cktool is available +if ! command -v xcrun &> /dev/null || ! xcrun cktool --version &> /dev/null; then + echo -e "${RED}ERROR: cktool is not available.${NC}" + echo "cktool is distributed with Xcode 13+ and is required for schema import." + echo "Please install Xcode 13 or later." + exit 1 +fi + +echo -e "${GREEN}✓${NC} cktool is available" +echo "" + +# Check for CloudKit Management Token +echo "Checking for CloudKit Management Token..." +if ! xcrun cktool get-teams 2>&1 | grep -qE "^[A-Z0-9]+:"; then + echo -e "${RED}ERROR: CloudKit Management Token not configured.${NC}" + echo "" + echo "You need to save a CloudKit Web Services Management Token for cktool first." + echo "" + echo "Steps to configure:" + echo " 1. Go to: https://icloud.developer.apple.com/dashboard/" + echo " 2. Select your container" + echo " 3. Go to 'API Access' → 'CloudKit Web Services'" + echo " 4. Generate a Management Token (not Server-to-Server Key)" + echo " 5. Copy the token" + echo " 6. Save it with cktool:" + echo "" + echo " xcrun cktool save-token" + echo "" + echo " 7. Paste your Management Token when prompted" + echo "" + echo "Note: Management Token is for schema operations (cktool)." + echo " Server-to-Server Key is for runtime API operations (bushel-images sync)." + echo "" + exit 1 +fi + +echo -e "${GREEN}✓${NC} CloudKit Management Token is configured" +echo "" + +# Check for required parameters +if [ -z "$CLOUDKIT_CONTAINER_ID" ]; then + echo -e "${YELLOW}CLOUDKIT_CONTAINER_ID not set.${NC}" + read -p "Enter your CloudKit Container ID [iCloud.com.brightdigit.Bushel]: " CLOUDKIT_CONTAINER_ID + CLOUDKIT_CONTAINER_ID=${CLOUDKIT_CONTAINER_ID:-iCloud.com.brightdigit.Bushel} +fi + +if [ -z "$CLOUDKIT_TEAM_ID" ]; then + echo -e "${YELLOW}CLOUDKIT_TEAM_ID not set.${NC}" + read -p "Enter your Apple Developer Team ID (10-character ID): " CLOUDKIT_TEAM_ID +fi + +# Validate required parameters +if [ -z "$CLOUDKIT_CONTAINER_ID" ] || [ -z "$CLOUDKIT_TEAM_ID" ]; then + echo -e "${RED}ERROR: Container ID and Team ID are required.${NC}" + exit 1 +fi + +# Default to development environment +ENVIRONMENT=${CLOUDKIT_ENVIRONMENT:-development} + +echo "" +echo "Configuration:" +echo " Container ID: $CLOUDKIT_CONTAINER_ID" +echo " Team ID: $CLOUDKIT_TEAM_ID" +echo " Environment: $ENVIRONMENT" +echo "" + +# Check if schema file exists +SCHEMA_FILE="$(dirname "$0")/../schema.ckdb" +if [ ! -f "$SCHEMA_FILE" ]; then + echo -e "${RED}ERROR: Schema file not found at $SCHEMA_FILE${NC}" + exit 1 +fi + +echo -e "${GREEN}✓${NC} Schema file found: $SCHEMA_FILE" +echo "" + +# Validate schema +echo "Validating schema..." +if xcrun cktool validate-schema \ + --team-id "$CLOUDKIT_TEAM_ID" \ + --container-id "$CLOUDKIT_CONTAINER_ID" \ + --environment "$ENVIRONMENT" \ + --file "$SCHEMA_FILE" 2>&1; then + echo -e "${GREEN}✓${NC} Schema validation passed" +else + echo -e "${RED}✗${NC} Schema validation failed" + exit 1 +fi + +echo "" + +# Confirm before import +echo -e "${YELLOW}Warning: This will import the schema into your CloudKit container.${NC}" +echo "This operation will create/modify record types in the $ENVIRONMENT environment." +echo "" +read -p "Continue? (y/n) " -n 1 -r +echo +if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo "Import cancelled." + exit 0 +fi + +# Import schema +echo "" +echo "Importing schema to CloudKit..." +if xcrun cktool import-schema \ + --team-id "$CLOUDKIT_TEAM_ID" \ + --container-id "$CLOUDKIT_CONTAINER_ID" \ + --environment "$ENVIRONMENT" \ + --file "$SCHEMA_FILE" 2>&1; then + echo "" + echo -e "${GREEN}✓✓✓ Schema import successful! ✓✓✓${NC}" + echo "" + echo "Your CloudKit container now has the following record types:" + echo " • RestoreImage" + echo " • XcodeVersion" + echo " • SwiftVersion" + echo "" + echo "Next steps:" + echo " 1. Get your Server-to-Server Key:" + echo " a. Go to: https://icloud.developer.apple.com/dashboard/" + echo " b. Navigate to: API Access → Server-to-Server Keys" + echo " c. Create a new key and download the private key .pem file" + echo "" + echo " 2. Run 'bushel-images sync' with your credentials:" + echo " bushel-images sync --key-id YOUR_KEY_ID --key-file ./private-key.pem" + echo "" + echo " 3. Verify data in CloudKit Dashboard: https://icloud.developer.apple.com/" + echo "" + echo " Important: Never commit .pem files to version control!" + echo "" +else + echo "" + echo -e "${RED}✗✗✗ Schema import failed ✗✗✗${NC}" + echo "" + echo "Common issues:" + echo " • Authentication token not saved (run: xcrun cktool save-token)" + echo " • Incorrect container ID or team ID" + echo " • Missing permissions in CloudKit Dashboard" + echo "" + echo "For help, see: https://developer.apple.com/documentation/cloudkit" + exit 1 +fi diff --git a/Examples/Bushel/Sources/BushelImages/BushelImagesCLI.swift b/Examples/Bushel/Sources/BushelImages/BushelImagesCLI.swift new file mode 100644 index 00000000..d0ed0cc5 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/BushelImagesCLI.swift @@ -0,0 +1,24 @@ +import ArgumentParser + +@main +internal struct BushelImagesCLI: AsyncParsableCommand { + internal static let configuration = CommandConfiguration( + commandName: "bushel-images", + abstract: "CloudKit version history tool for Bushel virtualization", + discussion: """ + A command-line tool demonstrating MistKit's CloudKit Web Services capabilities. + + Manages macOS restore images, Xcode versions, and Swift compiler versions + in CloudKit for use with Bushel's virtualization workflow. + """, + version: "1.0.0", + subcommands: [ + SyncCommand.self, + StatusCommand.self, + ListCommand.self, + ExportCommand.self, + ClearCommand.self + ], + defaultSubcommand: SyncCommand.self + ) +} diff --git a/Examples/Bushel/Sources/BushelImages/CloudKit/BushelCloudKitError.swift b/Examples/Bushel/Sources/BushelImages/CloudKit/BushelCloudKitError.swift new file mode 100644 index 00000000..84a6a1c7 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/CloudKit/BushelCloudKitError.swift @@ -0,0 +1,19 @@ +import Foundation + +/// Errors that can occur during BushelCloudKitService operations +enum BushelCloudKitError: LocalizedError { + case privateKeyFileNotFound(path: String) + case privateKeyFileReadFailed(path: String, error: Error) + case invalidMetadataRecord(recordName: String) + + var errorDescription: String? { + switch self { + case .privateKeyFileNotFound(let path): + return "Private key file not found at path: \(path)" + case .privateKeyFileReadFailed(let path, let error): + return "Failed to read private key file at \(path): \(error.localizedDescription)" + case .invalidMetadataRecord(let recordName): + return "Invalid DataSourceMetadata record: \(recordName) (missing required fields)" + } + } +} diff --git a/Examples/Bushel/Sources/BushelImages/CloudKit/BushelCloudKitService.swift b/Examples/Bushel/Sources/BushelImages/CloudKit/BushelCloudKitService.swift new file mode 100644 index 00000000..08dea06a --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/CloudKit/BushelCloudKitService.swift @@ -0,0 +1,141 @@ +import Foundation +import MistKit + +/// CloudKit service wrapper for Bushel demo operations +/// +/// **Tutorial**: This demonstrates MistKit's Server-to-Server authentication pattern: +/// 1. Load ECDSA private key from .pem file +/// 2. Create ServerToServerAuthManager with key ID and PEM string +/// 3. Initialize CloudKitService with the auth manager +/// 4. Use service.modifyRecords() and service.queryRecords() for operations +/// +/// This pattern allows command-line tools and servers to access CloudKit without user authentication. +struct BushelCloudKitService: Sendable, RecordManaging, CloudKitRecordCollection { + private let service: CloudKitService + + // MARK: - CloudKitRecordCollection + + /// All CloudKit record types managed by this service (using variadic generics) + static let recordTypes = RecordTypeSet( + RestoreImageRecord.self, + XcodeVersionRecord.self, + SwiftVersionRecord.self, + DataSourceMetadata.self + ) + + // MARK: - Initialization + + /// Initialize CloudKit service with Server-to-Server authentication + /// + /// **MistKit Pattern**: Server-to-Server authentication requires: + /// 1. Key ID from CloudKit Dashboard → API Access → Server-to-Server Keys + /// 2. Private key .pem file downloaded when creating the key + /// 3. Container identifier (begins with "iCloud.") + /// + /// - Parameters: + /// - containerIdentifier: CloudKit container ID (e.g., "iCloud.com.company.App") + /// - keyID: Server-to-Server Key ID from CloudKit Dashboard + /// - privateKeyPath: Path to the private key .pem file + /// - Throws: Error if the private key file cannot be read or is invalid + init(containerIdentifier: String, keyID: String, privateKeyPath: String) throws { + // Read PEM file from disk + guard FileManager.default.fileExists(atPath: privateKeyPath) else { + throw BushelCloudKitError.privateKeyFileNotFound(path: privateKeyPath) + } + + let pemString: String + do { + pemString = try String(contentsOfFile: privateKeyPath, encoding: .utf8) + } catch { + throw BushelCloudKitError.privateKeyFileReadFailed(path: privateKeyPath, error: error) + } + + // Create Server-to-Server authentication manager + let tokenManager = try ServerToServerAuthManager( + keyID: keyID, + pemString: pemString + ) + + self.service = try CloudKitService( + containerIdentifier: containerIdentifier, + tokenManager: tokenManager, + environment: .development, + database: .public + ) + } + + // MARK: - RecordManaging Protocol Requirements + + /// Query all records of a given type + func queryRecords(recordType: String) async throws -> [RecordInfo] { + try await service.queryRecords(recordType: recordType, limit: 200) + } + + /// Execute operations in batches (CloudKit limits to 200 operations per request) + /// + /// **MistKit Pattern**: CloudKit has a 200 operations/request limit. + /// This method chunks operations and calls service.modifyRecords() for each batch. + func executeBatchOperations( + _ operations: [RecordOperation], + recordType: String + ) async throws { + let batchSize = 200 + let batches = operations.chunked(into: batchSize) + + print("Syncing \(operations.count) \(recordType) record(s) in \(batches.count) batch(es)...") + BushelLogger.verbose( + "CloudKit batch limit: 200 operations/request. Using \(batches.count) batch(es) for \(operations.count) records.", + subsystem: BushelLogger.cloudKit + ) + + var totalSucceeded = 0 + var totalFailed = 0 + + for (index, batch) in batches.enumerated() { + print(" Batch \(index + 1)/\(batches.count): \(batch.count) records...") + BushelLogger.verbose( + "Calling MistKit service.modifyRecords() with \(batch.count) RecordOperation objects", + subsystem: BushelLogger.cloudKit + ) + + let results = try await service.modifyRecords(batch) + + BushelLogger.verbose("Received \(results.count) RecordInfo responses from CloudKit", subsystem: BushelLogger.cloudKit) + + // Filter out error responses using isError property + let successfulRecords = results.filter { !$0.isError } + let failedCount = results.count - successfulRecords.count + + totalSucceeded += successfulRecords.count + totalFailed += failedCount + + if failedCount > 0 { + print(" ⚠️ \(failedCount) operations failed (see verbose logs for details)") + print(" ✓ \(successfulRecords.count) records confirmed") + + // Log error details in verbose mode + let errorRecords = results.filter { $0.isError } + for errorRecord in errorRecords { + BushelLogger.verbose( + "Error: recordName=\(errorRecord.recordName), reason=\(errorRecord.recordType)", + subsystem: BushelLogger.cloudKit + ) + } + } else { + BushelLogger.success("CloudKit confirmed \(successfulRecords.count) records", subsystem: BushelLogger.cloudKit) + } + } + + print("\n📊 \(recordType) Sync Summary:") + print(" Attempted: \(operations.count) operations") + print(" Succeeded: \(totalSucceeded) records") + + if totalFailed > 0 { + print(" ❌ Failed: \(totalFailed) operations") + BushelLogger.explain( + "Use --verbose flag to see CloudKit error details (serverErrorCode, reason, etc.)", + subsystem: BushelLogger.cloudKit + ) + } + } +} diff --git a/Examples/Bushel/Sources/BushelImages/CloudKit/CloudKitFieldMapping.swift b/Examples/Bushel/Sources/BushelImages/CloudKit/CloudKitFieldMapping.swift new file mode 100644 index 00000000..f06b15d0 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/CloudKit/CloudKitFieldMapping.swift @@ -0,0 +1,85 @@ +import Foundation +import MistKit + +/// Helper utilities for converting between Swift types and CloudKit FieldValue types +enum CloudKitFieldMapping { + /// Convert a String to FieldValue + static func fieldValue(from string: String) -> FieldValue { + .string(string) + } + + /// Convert an optional String to FieldValue + static func fieldValue(from string: String?) -> FieldValue? { + string.map { .string($0) } + } + + /// Convert a Bool to FieldValue (using INT64 representation: 0 = false, 1 = true) + static func fieldValue(from bool: Bool) -> FieldValue { + .from(bool) + } + + /// Convert an Int64 to FieldValue + static func fieldValue(from int64: Int64) -> FieldValue { + .int64(Int(int64)) + } + + /// Convert an optional Int64 to FieldValue + static func fieldValue(from int64: Int64?) -> FieldValue? { + int64.map { .int64(Int($0)) } + } + + /// Convert a Date to FieldValue + static func fieldValue(from date: Date) -> FieldValue { + .date(date) + } + + /// Convert a CloudKit reference (recordName) to FieldValue + static func referenceFieldValue(recordName: String) -> FieldValue { + .reference(FieldValue.Reference(recordName: recordName)) + } + + /// Convert an optional CloudKit reference to FieldValue + static func referenceFieldValue(recordName: String?) -> FieldValue? { + recordName.map { .reference(FieldValue.Reference(recordName: $0)) } + } + + /// Extract String from FieldValue + static func string(from fieldValue: FieldValue) -> String? { + if case .string(let value) = fieldValue { + return value + } + return nil + } + + /// Extract Bool from FieldValue (from INT64 representation: 0 = false, non-zero = true) + static func bool(from fieldValue: FieldValue) -> Bool? { + if case .int64(let value) = fieldValue { + return value != 0 + } + return nil + } + + /// Extract Int64 from FieldValue + static func int64(from fieldValue: FieldValue) -> Int64? { + if case .int64(let value) = fieldValue { + return Int64(value) + } + return nil + } + + /// Extract Date from FieldValue + static func date(from fieldValue: FieldValue) -> Date? { + if case .date(let value) = fieldValue { + return value + } + return nil + } + + /// Extract reference recordName from FieldValue + static func recordName(from fieldValue: FieldValue) -> String? { + if case .reference(let reference) = fieldValue { + return reference.recordName + } + return nil + } +} diff --git a/Examples/Bushel/Sources/BushelImages/CloudKit/RecordManaging+Query.swift b/Examples/Bushel/Sources/BushelImages/CloudKit/RecordManaging+Query.swift new file mode 100644 index 00000000..c4f6e496 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/CloudKit/RecordManaging+Query.swift @@ -0,0 +1,18 @@ +import Foundation +import MistKit + +extension RecordManaging { + // MARK: - Query Operations + + /// Query a specific DataSourceMetadata record + /// + /// **MistKit Pattern**: Query all metadata records and filter by record name + /// Record name format: "metadata-{sourceName}-{recordType}" + func queryDataSourceMetadata(source: String, recordType: String) async throws -> DataSourceMetadata? { + let targetRecordName = "metadata-\(source)-\(recordType)" + let results = try await query(DataSourceMetadata.self) { record in + record.recordName == targetRecordName + } + return results.first + } +} diff --git a/Examples/Bushel/Sources/BushelImages/CloudKit/SyncEngine.swift b/Examples/Bushel/Sources/BushelImages/CloudKit/SyncEngine.swift new file mode 100644 index 00000000..88e1699c --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/CloudKit/SyncEngine.swift @@ -0,0 +1,190 @@ +import Foundation +import MistKit + +/// Orchestrates the complete sync process from data sources to CloudKit +/// +/// **Tutorial**: This demonstrates the typical flow for CloudKit data syncing: +/// 1. Fetch data from external sources +/// 2. Transform to CloudKit records +/// 3. Batch upload using MistKit +/// +/// Use `--verbose` flag to see detailed MistKit API usage. +struct SyncEngine: Sendable { + let cloudKitService: BushelCloudKitService + let pipeline: DataSourcePipeline + + // MARK: - Configuration + + struct SyncOptions: Sendable { + var dryRun: Bool = false + var pipelineOptions: DataSourcePipeline.Options = .init() + } + + // MARK: - Initialization + + init( + containerIdentifier: String, + keyID: String, + privateKeyPath: String, + configuration: FetchConfiguration = FetchConfiguration.loadFromEnvironment() + ) throws { + let service = try BushelCloudKitService( + containerIdentifier: containerIdentifier, + keyID: keyID, + privateKeyPath: privateKeyPath + ) + self.cloudKitService = service + self.pipeline = DataSourcePipeline( + cloudKitService: service, + configuration: configuration + ) + } + + // MARK: - Sync Operations + + /// Execute full sync from all data sources to CloudKit + func sync(options: SyncOptions = SyncOptions()) async throws -> SyncResult { + print("\n" + String(repeating: "=", count: 60)) + BushelLogger.info("🔄 Starting Bushel CloudKit Sync", subsystem: BushelLogger.sync) + print(String(repeating: "=", count: 60)) + + if options.dryRun { + BushelLogger.info("🧪 DRY RUN MODE - No changes will be made to CloudKit", subsystem: BushelLogger.sync) + } + + BushelLogger.explain( + "This sync demonstrates MistKit's Server-to-Server authentication and bulk record operations", + subsystem: BushelLogger.sync + ) + + // Step 1: Fetch from all data sources + print("\n📥 Step 1: Fetching data from external sources...") + BushelLogger.verbose("Initializing data source pipeline to fetch from ipsw.me, TheAppleWiki, MESU, and other sources", subsystem: BushelLogger.dataSource) + + let fetchResult = try await pipeline.fetch(options: options.pipelineOptions) + + BushelLogger.verbose("Data fetch complete. Beginning deduplication and merge phase.", subsystem: BushelLogger.dataSource) + BushelLogger.explain( + "Multiple data sources may have overlapping data. The pipeline deduplicates by version+build number.", + subsystem: BushelLogger.dataSource + ) + + let stats = SyncResult( + restoreImagesCount: fetchResult.restoreImages.count, + xcodeVersionsCount: fetchResult.xcodeVersions.count, + swiftVersionsCount: fetchResult.swiftVersions.count + ) + + let totalRecords = stats.restoreImagesCount + stats.xcodeVersionsCount + stats.swiftVersionsCount + + print("\n📊 Data Summary:") + print(" RestoreImages: \(stats.restoreImagesCount)") + print(" XcodeVersions: \(stats.xcodeVersionsCount)") + print(" SwiftVersions: \(stats.swiftVersionsCount)") + print(" ─────────────────────") + print(" Total: \(totalRecords) records") + + BushelLogger.verbose("Records ready for CloudKit upload: \(totalRecords) total", subsystem: BushelLogger.sync) + + // Step 2: Sync to CloudKit (unless dry run) + if !options.dryRun { + print("\n☁️ Step 2: Syncing to CloudKit...") + BushelLogger.verbose("Using MistKit to batch upload records to CloudKit public database", subsystem: BushelLogger.cloudKit) + BushelLogger.explain( + "MistKit handles authentication, batching (200 records/request), and error handling automatically", + subsystem: BushelLogger.cloudKit + ) + + // Sync in dependency order: SwiftVersion → RestoreImage → XcodeVersion + // (Prevents broken CKReference relationships) + try await cloudKitService.syncAllRecords( + fetchResult.swiftVersions, // First: no dependencies + fetchResult.restoreImages, // Second: no dependencies + fetchResult.xcodeVersions // Third: references first two + ) + } else { + print("\n⏭️ Step 2: Skipped (dry run)") + print(" Would sync:") + print(" • \(stats.restoreImagesCount) restore images") + print(" • \(stats.xcodeVersionsCount) Xcode versions") + print(" • \(stats.swiftVersionsCount) Swift versions") + BushelLogger.verbose("Dry run mode: No CloudKit operations performed", subsystem: BushelLogger.sync) + } + + print("\n" + String(repeating: "=", count: 60)) + BushelLogger.success("Sync completed successfully!", subsystem: BushelLogger.sync) + print(String(repeating: "=", count: 60)) + + return stats + } + + /// Delete all records from CloudKit + func clear() async throws { + print("\n" + String(repeating: "=", count: 60)) + BushelLogger.info("🗑️ Clearing all CloudKit data", subsystem: BushelLogger.cloudKit) + print(String(repeating: "=", count: 60)) + + try await cloudKitService.deleteAllRecords() + + print("\n" + String(repeating: "=", count: 60)) + BushelLogger.success("Clear completed successfully!", subsystem: BushelLogger.sync) + print(String(repeating: "=", count: 60)) + } + + /// Export all records from CloudKit to a structured format + func export() async throws -> ExportResult { + print("\n" + String(repeating: "=", count: 60)) + BushelLogger.info("📤 Exporting data from CloudKit", subsystem: BushelLogger.cloudKit) + print(String(repeating: "=", count: 60)) + + BushelLogger.explain( + "Using MistKit's queryRecords() to fetch all records of each type from the public database", + subsystem: BushelLogger.cloudKit + ) + + print("\n📥 Fetching RestoreImage records...") + BushelLogger.verbose("Querying CloudKit for recordType: 'RestoreImage' with limit: 1000", subsystem: BushelLogger.cloudKit) + let restoreImages = try await cloudKitService.queryRecords(recordType: "RestoreImage") + BushelLogger.verbose("Retrieved \(restoreImages.count) RestoreImage records", subsystem: BushelLogger.cloudKit) + + print("📥 Fetching XcodeVersion records...") + BushelLogger.verbose("Querying CloudKit for recordType: 'XcodeVersion' with limit: 1000", subsystem: BushelLogger.cloudKit) + let xcodeVersions = try await cloudKitService.queryRecords(recordType: "XcodeVersion") + BushelLogger.verbose("Retrieved \(xcodeVersions.count) XcodeVersion records", subsystem: BushelLogger.cloudKit) + + print("📥 Fetching SwiftVersion records...") + BushelLogger.verbose("Querying CloudKit for recordType: 'SwiftVersion' with limit: 1000", subsystem: BushelLogger.cloudKit) + let swiftVersions = try await cloudKitService.queryRecords(recordType: "SwiftVersion") + BushelLogger.verbose("Retrieved \(swiftVersions.count) SwiftVersion records", subsystem: BushelLogger.cloudKit) + + print("\n✅ Exported:") + print(" • \(restoreImages.count) restore images") + print(" • \(xcodeVersions.count) Xcode versions") + print(" • \(swiftVersions.count) Swift versions") + + BushelLogger.explain( + "MistKit returns RecordInfo structs with record metadata. Use .fields to access CloudKit field values.", + subsystem: BushelLogger.cloudKit + ) + + return ExportResult( + restoreImages: restoreImages, + xcodeVersions: xcodeVersions, + swiftVersions: swiftVersions + ) + } + + // MARK: - Result Types + + struct SyncResult: Sendable { + let restoreImagesCount: Int + let xcodeVersionsCount: Int + let swiftVersionsCount: Int + } + + struct ExportResult { + let restoreImages: [RecordInfo] + let xcodeVersions: [RecordInfo] + let swiftVersions: [RecordInfo] + } +} diff --git a/Examples/Bushel/Sources/BushelImages/Commands/ClearCommand.swift b/Examples/Bushel/Sources/BushelImages/Commands/ClearCommand.swift new file mode 100644 index 00000000..dd241d09 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/Commands/ClearCommand.swift @@ -0,0 +1,113 @@ +import ArgumentParser +import Foundation + +struct ClearCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "clear", + abstract: "Delete all records from CloudKit", + discussion: """ + Deletes all RestoreImage, XcodeVersion, and SwiftVersion records from + the CloudKit public database. + + ⚠️ WARNING: This operation cannot be undone! + """ + ) + + // MARK: - Required Options + + @Option(name: .shortAndLong, help: "CloudKit container identifier") + var containerIdentifier: String = "iCloud.com.brightdigit.Bushel" + + @Option(name: .long, help: "Server-to-Server Key ID (or set CLOUDKIT_KEY_ID)") + var keyID: String = "" + + @Option(name: .long, help: "Path to private key .pem file (or set CLOUDKIT_PRIVATE_KEY_PATH)") + var keyFile: String = "" + + // MARK: - Options + + @Flag(name: .shortAndLong, help: "Skip confirmation prompt") + var yes: Bool = false + + @Flag(name: .shortAndLong, help: "Enable verbose logging to see detailed CloudKit operations and learn MistKit usage patterns") + var verbose: Bool = false + + // MARK: - Execution + + mutating func run() async throws { + // Enable verbose logging if requested + BushelLogger.isVerbose = verbose + + // Get Server-to-Server credentials from environment if not provided + let resolvedKeyID = keyID.isEmpty ? + ProcessInfo.processInfo.environment["CLOUDKIT_KEY_ID"] ?? "" : + keyID + + let resolvedKeyFile = keyFile.isEmpty ? + ProcessInfo.processInfo.environment["CLOUDKIT_PRIVATE_KEY_PATH"] ?? "" : + keyFile + + guard !resolvedKeyID.isEmpty && !resolvedKeyFile.isEmpty else { + print("❌ Error: CloudKit Server-to-Server Key credentials are required") + print("") + print(" Provide via command-line flags:") + print(" --key-id YOUR_KEY_ID --key-file ./private-key.pem") + print("") + print(" Or set environment variables:") + print(" export CLOUDKIT_KEY_ID=\"YOUR_KEY_ID\"") + print(" export CLOUDKIT_PRIVATE_KEY_PATH=\"./private-key.pem\"") + print("") + print(" Get your Server-to-Server Key from:") + print(" https://icloud.developer.apple.com/dashboard/") + print(" Navigate to: API Access → Server-to-Server Keys") + print("") + print(" Important:") + print(" • Download and save the private key .pem file securely") + print(" • Never commit .pem files to version control!") + print("") + throw ExitCode.failure + } + + // Confirm deletion unless --yes flag is provided + if !yes { + print("\n⚠️ WARNING: This will delete ALL records from CloudKit!") + print(" Container: \(containerIdentifier)") + print(" Database: public (development)") + print("") + print(" This operation cannot be undone.") + print("") + print(" Type 'yes' to confirm: ", terminator: "") + + guard let response = readLine(), response.lowercased() == "yes" else { + print("\n❌ Operation cancelled") + throw ExitCode.failure + } + } + + // Create sync engine + let syncEngine = try SyncEngine( + containerIdentifier: containerIdentifier, + keyID: resolvedKeyID, + privateKeyPath: resolvedKeyFile + ) + + // Execute clear + do { + try await syncEngine.clear() + print("\n✅ All records have been deleted from CloudKit") + } catch { + printError(error) + throw ExitCode.failure + } + } + + // MARK: - Private Helpers + + private func printError(_ error: Error) { + print("\n❌ Clear failed: \(error.localizedDescription)") + print("\n💡 Troubleshooting:") + print(" • Verify your API token is valid") + print(" • Check your internet connection") + print(" • Ensure the CloudKit container exists") + } +} diff --git a/Examples/Bushel/Sources/BushelImages/Commands/ExportCommand.swift b/Examples/Bushel/Sources/BushelImages/Commands/ExportCommand.swift new file mode 100644 index 00000000..4d7354ce --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/Commands/ExportCommand.swift @@ -0,0 +1,210 @@ +import ArgumentParser +import Foundation +import MistKit + +struct ExportCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "export", + abstract: "Export CloudKit data to JSON", + discussion: """ + Queries the CloudKit public database and exports all version records + to JSON format for analysis or backup. + """ + ) + + // MARK: - Required Options + + @Option(name: .shortAndLong, help: "CloudKit container identifier") + var containerIdentifier: String = "iCloud.com.brightdigit.Bushel" + + @Option(name: .long, help: "Server-to-Server Key ID (or set CLOUDKIT_KEY_ID)") + var keyID: String = "" + + @Option(name: .long, help: "Path to private key .pem file (or set CLOUDKIT_PRIVATE_KEY_PATH)") + var keyFile: String = "" + + // MARK: - Export Options + + @Option(name: .shortAndLong, help: "Output file path (default: stdout)") + var output: String? + + @Flag(name: .long, help: "Pretty-print JSON output") + var pretty: Bool = false + + @Flag(name: .long, help: "Export only signed restore images") + var signedOnly: Bool = false + + @Flag(name: .long, help: "Exclude beta/RC releases") + var noBetas: Bool = false + + @Flag(name: .shortAndLong, help: "Enable verbose logging to see detailed CloudKit operations and learn MistKit usage patterns") + var verbose: Bool = false + + // MARK: - Execution + + mutating func run() async throws { + // Enable verbose logging if requested + BushelLogger.isVerbose = verbose + + // Get Server-to-Server credentials from environment if not provided + let resolvedKeyID = keyID.isEmpty ? + ProcessInfo.processInfo.environment["CLOUDKIT_KEY_ID"] ?? "" : + keyID + + let resolvedKeyFile = keyFile.isEmpty ? + ProcessInfo.processInfo.environment["CLOUDKIT_PRIVATE_KEY_PATH"] ?? "" : + keyFile + + guard !resolvedKeyID.isEmpty && !resolvedKeyFile.isEmpty else { + print("❌ Error: CloudKit Server-to-Server Key credentials are required") + print("") + print(" Provide via command-line flags:") + print(" --key-id YOUR_KEY_ID --key-file ./private-key.pem") + print("") + print(" Or set environment variables:") + print(" export CLOUDKIT_KEY_ID=\"YOUR_KEY_ID\"") + print(" export CLOUDKIT_PRIVATE_KEY_PATH=\"./private-key.pem\"") + print("") + print(" Get your Server-to-Server Key from:") + print(" https://icloud.developer.apple.com/dashboard/") + print(" Navigate to: API Access → Server-to-Server Keys") + print("") + print(" Important:") + print(" • Download and save the private key .pem file securely") + print(" • Never commit .pem files to version control!") + print("") + throw ExitCode.failure + } + + // Create sync engine + let syncEngine = try SyncEngine( + containerIdentifier: containerIdentifier, + keyID: resolvedKeyID, + privateKeyPath: resolvedKeyFile + ) + + // Execute export + do { + let result = try await syncEngine.export() + let filtered = applyFilters(to: result) + let json = try encodeToJSON(filtered) + + if let outputPath = output { + try writeToFile(json, at: outputPath) + print("✅ Exported to: \(outputPath)") + } else { + print(json) + } + } catch { + printError(error) + throw ExitCode.failure + } + } + + // MARK: - Private Helpers + + private func applyFilters(to result: SyncEngine.ExportResult) -> SyncEngine.ExportResult { + var restoreImages = result.restoreImages + var xcodeVersions = result.xcodeVersions + var swiftVersions = result.swiftVersions + + // Filter signed-only restore images + if signedOnly { + restoreImages = restoreImages.filter { record in + if case .int64(let isSigned) = record.fields["isSigned"] { + return isSigned != 0 + } + return false + } + } + + // Filter out betas + if noBetas { + restoreImages = restoreImages.filter { record in + if case .int64(let isPrerelease) = record.fields["isPrerelease"] { + return isPrerelease == 0 + } + return true + } + + xcodeVersions = xcodeVersions.filter { record in + if case .int64(let isPrerelease) = record.fields["isPrerelease"] { + return isPrerelease == 0 + } + return true + } + + swiftVersions = swiftVersions.filter { record in + if case .int64(let isPrerelease) = record.fields["isPrerelease"] { + return isPrerelease == 0 + } + return true + } + } + + return SyncEngine.ExportResult( + restoreImages: restoreImages, + xcodeVersions: xcodeVersions, + swiftVersions: swiftVersions + ) + } + + private func encodeToJSON(_ result: SyncEngine.ExportResult) throws -> String { + let export = ExportData( + restoreImages: result.restoreImages.map(RecordExport.init), + xcodeVersions: result.xcodeVersions.map(RecordExport.init), + swiftVersions: result.swiftVersions.map(RecordExport.init) + ) + + let encoder = JSONEncoder() + if pretty { + encoder.outputFormatting = [.prettyPrinted, .sortedKeys] + } + + let data = try encoder.encode(export) + guard let json = String(data: data, encoding: .utf8) else { + throw ExportError.encodingFailed + } + + return json + } + + private func writeToFile(_ content: String, at path: String) throws { + try content.write(toFile: path, atomically: true, encoding: .utf8) + } + + private func printError(_ error: Error) { + print("\n❌ Export failed: \(error.localizedDescription)") + print("\n💡 Troubleshooting:") + print(" • Verify your API token is valid") + print(" • Check your internet connection") + print(" • Ensure data has been synced to CloudKit") + print(" • Run 'bushel-images sync' first if needed") + } + + // MARK: - Export Types + + struct ExportData: Codable { + let restoreImages: [RecordExport] + let xcodeVersions: [RecordExport] + let swiftVersions: [RecordExport] + } + + struct RecordExport: Codable { + let recordName: String + let recordType: String + let fields: [String: String] + + init(from recordInfo: RecordInfo) { + self.recordName = recordInfo.recordName + self.recordType = recordInfo.recordType + self.fields = recordInfo.fields.mapValues { fieldValue in + String(describing: fieldValue) + } + } + } + + enum ExportError: Error { + case encodingFailed + } +} diff --git a/Examples/Bushel/Sources/BushelImages/Commands/ListCommand.swift b/Examples/Bushel/Sources/BushelImages/Commands/ListCommand.swift new file mode 100644 index 00000000..a0399164 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/Commands/ListCommand.swift @@ -0,0 +1,100 @@ +// ListCommand.swift +// Created by Claude Code + +import ArgumentParser +import Foundation +import MistKit + +struct ListCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "list", + abstract: "List CloudKit records", + discussion: """ + Displays all records stored in CloudKit across different record types. + + By default, lists all record types. Use flags to show specific types only. + """ + ) + + // MARK: - Required Options + + @Option(name: .shortAndLong, help: "CloudKit container identifier") + var containerIdentifier: String = "iCloud.com.brightdigit.Bushel" + + @Option(name: .long, help: "Server-to-Server Key ID (or set CLOUDKIT_KEY_ID)") + var keyID: String = "" + + @Option(name: .long, help: "Path to private key .pem file (or set CLOUDKIT_PRIVATE_KEY_PATH)") + var keyFile: String = "" + + // MARK: - Filter Options + + @Flag(name: .long, help: "List only restore images") + var restoreImages: Bool = false + + @Flag(name: .long, help: "List only Xcode versions") + var xcodeVersions: Bool = false + + @Flag(name: .long, help: "List only Swift versions") + var swiftVersions: Bool = false + + // MARK: - Display Options + + @Flag(name: .long, help: "Disable log redaction for debugging") + var noRedaction: Bool = false + + // MARK: - Execution + + mutating func run() async throws { + // Disable log redaction for debugging if requested + if noRedaction { + setenv("MISTKIT_DISABLE_LOG_REDACTION", "1", 1) + } + + // Get Server-to-Server credentials from environment if not provided + let resolvedKeyID = keyID.isEmpty ? + ProcessInfo.processInfo.environment["CLOUDKIT_KEY_ID"] ?? "" : + keyID + + let resolvedKeyFile = keyFile.isEmpty ? + ProcessInfo.processInfo.environment["CLOUDKIT_PRIVATE_KEY_PATH"] ?? "" : + keyFile + + guard !resolvedKeyID.isEmpty, !resolvedKeyFile.isEmpty else { + print("❌ Error: CloudKit Server-to-Server Key credentials are required") + print("") + print(" Provide via command-line flags:") + print(" --key-id YOUR_KEY_ID --key-file ./private-key.pem") + print("") + print(" Or set environment variables:") + print(" export CLOUDKIT_KEY_ID=\"YOUR_KEY_ID\"") + print(" export CLOUDKIT_PRIVATE_KEY_PATH=\"./private-key.pem\"") + print("") + throw ExitCode.failure + } + + // Create CloudKit service + let cloudKitService = try BushelCloudKitService( + containerIdentifier: containerIdentifier, + keyID: resolvedKeyID, + privateKeyPath: resolvedKeyFile + ) + + // Determine what to list based on flags + let listAll = !restoreImages && !xcodeVersions && !swiftVersions + + if listAll { + try await cloudKitService.listAllRecords() + } else { + if restoreImages { + try await cloudKitService.list(RestoreImageRecord.self) + } + if xcodeVersions { + try await cloudKitService.list(XcodeVersionRecord.self) + } + if swiftVersions { + try await cloudKitService.list(SwiftVersionRecord.self) + } + } + } +} diff --git a/Examples/Bushel/Sources/BushelImages/Commands/StatusCommand.swift b/Examples/Bushel/Sources/BushelImages/Commands/StatusCommand.swift new file mode 100644 index 00000000..e440d4ea --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/Commands/StatusCommand.swift @@ -0,0 +1,227 @@ +// StatusCommand.swift +// Created by Claude Code + +import ArgumentParser +import Foundation +internal import MistKit + +struct StatusCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "status", + abstract: "Show data source fetch status and metadata", + discussion: """ + Displays information about when each data source was last fetched, + when the source was last updated, record counts, and next eligible fetch time. + + This command queries CloudKit for DataSourceMetadata records to show + the current state of all data sources. + """ + ) + + // MARK: - Required Options + + @Option(name: .shortAndLong, help: "CloudKit container identifier") + var containerIdentifier: String = "iCloud.com.brightdigit.Bushel" + + @Option(name: .long, help: "Server-to-Server Key ID (or set CLOUDKIT_KEY_ID)") + var keyID: String = "" + + @Option(name: .long, help: "Path to private key .pem file (or set CLOUDKIT_PRIVATE_KEY_PATH)") + var keyFile: String = "" + + // MARK: - Display Options + + @Flag(name: .long, help: "Show only sources with errors") + var errorsOnly: Bool = false + + @Flag(name: .long, help: "Show detailed timing information") + var detailed: Bool = false + + @Flag(name: .long, help: "Disable log redaction for debugging (shows actual CloudKit field names in errors)") + var noRedaction: Bool = false + + // MARK: - Execution + + mutating func run() async throws { + // Disable log redaction for debugging if requested + if noRedaction { + setenv("MISTKIT_DISABLE_LOG_REDACTION", "1", 1) + } + + // Get Server-to-Server credentials from environment if not provided + let resolvedKeyID = keyID.isEmpty ? + ProcessInfo.processInfo.environment["CLOUDKIT_KEY_ID"] ?? "" : + keyID + + let resolvedKeyFile = keyFile.isEmpty ? + ProcessInfo.processInfo.environment["CLOUDKIT_PRIVATE_KEY_PATH"] ?? "" : + keyFile + + guard !resolvedKeyID.isEmpty, !resolvedKeyFile.isEmpty else { + print("❌ Error: CloudKit Server-to-Server Key credentials are required") + print("") + print(" Provide via command-line flags:") + print(" --key-id YOUR_KEY_ID --key-file ./private-key.pem") + print("") + print(" Or set environment variables:") + print(" export CLOUDKIT_KEY_ID=\"YOUR_KEY_ID\"") + print(" export CLOUDKIT_PRIVATE_KEY_PATH=\"./private-key.pem\"") + print("") + throw ExitCode.failure + } + + // Create CloudKit service + let cloudKitService = try BushelCloudKitService( + containerIdentifier: containerIdentifier, + keyID: resolvedKeyID, + privateKeyPath: resolvedKeyFile + ) + + // Load configuration to show intervals + let configuration = FetchConfiguration.loadFromEnvironment() + + // Fetch all metadata records + print("\n📊 Data Source Status") + print(String(repeating: "=", count: 80)) + + let allMetadata = try await fetchAllMetadata(cloudKitService: cloudKitService) + + if allMetadata.isEmpty { + print("\n No metadata records found. Run 'bushel-images sync' to populate metadata.") + return + } + + // Filter if needed + let metadata = errorsOnly ? allMetadata.filter { $0.lastError != nil } : allMetadata + + if metadata.isEmpty, errorsOnly { + print("\n ✅ No sources with errors!") + return + } + + // Display metadata + for meta in metadata.sorted(by: { $0.recordTypeName < $1.recordTypeName || ($0.recordTypeName == $1.recordTypeName && $0.sourceName < $1.sourceName) }) { + printMetadata(meta, configuration: configuration, detailed: detailed) + } + + print(String(repeating: "=", count: 80)) + } + + // MARK: - Private Helpers + + private func fetchAllMetadata(cloudKitService: BushelCloudKitService) async throws -> [DataSourceMetadata] { + let records = try await cloudKitService.queryRecords(recordType: "DataSourceMetadata") + + var metadataList: [DataSourceMetadata] = [] + + for record in records { + guard let sourceName = record.fields["sourceName"]?.stringValue, + let recordTypeName = record.fields["recordTypeName"]?.stringValue, + let lastFetchedAt = record.fields["lastFetchedAt"]?.dateValue + else { + continue + } + + let sourceUpdatedAt = record.fields["sourceUpdatedAt"]?.dateValue + let recordCount = record.fields["recordCount"]?.intValue ?? 0 + let fetchDurationSeconds = record.fields["fetchDurationSeconds"]?.doubleValue ?? 0 + let lastError = record.fields["lastError"]?.stringValue + + metadataList.append( + DataSourceMetadata( + sourceName: sourceName, + recordTypeName: recordTypeName, + lastFetchedAt: lastFetchedAt, + sourceUpdatedAt: sourceUpdatedAt, + recordCount: recordCount, + fetchDurationSeconds: fetchDurationSeconds, + lastError: lastError + ) + ) + } + + return metadataList + } + + private func printMetadata( + _ metadata: DataSourceMetadata, + configuration: FetchConfiguration, + detailed: Bool + ) { + let now = Date() + let timeSinceLastFetch = now.timeIntervalSince(metadata.lastFetchedAt) + + // Header + print("\n\(metadata.sourceName) (\(metadata.recordTypeName))") + print(String(repeating: "-", count: 80)) + + // Last fetched + let lastFetchedStr = formatDate(metadata.lastFetchedAt) + let timeAgoStr = formatTimeInterval(timeSinceLastFetch) + print(" Last Fetched: \(lastFetchedStr) (\(timeAgoStr) ago)") + + // Source last updated + if let sourceUpdated = metadata.sourceUpdatedAt { + let sourceUpdatedStr = formatDate(sourceUpdated) + let sourceTimeAgo = formatTimeInterval(now.timeIntervalSince(sourceUpdated)) + print(" Source Updated: \(sourceUpdatedStr) (\(sourceTimeAgo) ago)") + } + + // Record count + print(" Record Count: \(metadata.recordCount)") + + // Fetch duration (if detailed) + if detailed { + print(" Fetch Duration: \(String(format: "%.2f", metadata.fetchDurationSeconds))s") + } + + // Next eligible fetch + if let minInterval = configuration.minimumInterval(for: metadata.sourceName) { + let nextFetchTime = metadata.lastFetchedAt.addingTimeInterval(minInterval) + let timeUntilNext = nextFetchTime.timeIntervalSince(now) + + if timeUntilNext > 0 { + print(" Next Fetch: \(formatDate(nextFetchTime)) (in \(formatTimeInterval(timeUntilNext)))") + } else { + print(" Next Fetch: ✅ Ready now") + } + + if detailed { + print(" Min Interval: \(formatTimeInterval(minInterval))") + } + } else { + print(" Next Fetch: ✅ No throttling") + } + + // Error status + if let error = metadata.lastError { + print(" ⚠️ Last Error: \(error)") + } + } + + private func formatDate(_ date: Date) -> String { + let formatter = DateFormatter() + formatter.dateStyle = .short + formatter.timeStyle = .short + return formatter.string(from: date) + } + + private func formatTimeInterval(_ interval: TimeInterval) -> String { + let absInterval = abs(interval) + + if absInterval < 60 { + return "\(Int(absInterval))s" + } else if absInterval < 3600 { + let minutes = Int(absInterval / 60) + return "\(minutes)m" + } else if absInterval < 86400 { + let hours = Int(absInterval / 3600) + let minutes = Int((absInterval.truncatingRemainder(dividingBy: 3600)) / 60) + return minutes > 0 ? "\(hours)h \(minutes)m" : "\(hours)h" + } else { + let days = Int(absInterval / 86400) + let hours = Int((absInterval.truncatingRemainder(dividingBy: 86400)) / 3600) + return hours > 0 ? "\(days)d \(hours)h" : "\(days)d" + } + } +} diff --git a/Examples/Bushel/Sources/BushelImages/Commands/SyncCommand.swift b/Examples/Bushel/Sources/BushelImages/Commands/SyncCommand.swift new file mode 100644 index 00000000..11f7639d --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/Commands/SyncCommand.swift @@ -0,0 +1,202 @@ +import ArgumentParser +import Foundation + +struct SyncCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "sync", + abstract: "Fetch version data and sync to CloudKit", + discussion: """ + Fetches macOS restore images, Xcode versions, and Swift versions from + external data sources and syncs them to the CloudKit public database. + + Data sources: + • RestoreImage: ipsw.me, TheAppleWiki.com, Mr. Macintosh, Apple MESU + • XcodeVersion: xcodereleases.com + • SwiftVersion: swiftversion.net + """ + ) + + // MARK: - Required Options + + @Option(name: .shortAndLong, help: "CloudKit container identifier") + var containerIdentifier: String = "iCloud.com.brightdigit.Bushel" + + @Option(name: .long, help: "Server-to-Server Key ID (or set CLOUDKIT_KEY_ID)") + var keyID: String = "" + + @Option(name: .long, help: "Path to private key .pem file (or set CLOUDKIT_PRIVATE_KEY_PATH)") + var keyFile: String = "" + + // MARK: - Sync Options + + @Flag(name: .long, help: "Perform a dry run without syncing to CloudKit") + var dryRun: Bool = false + + @Flag(name: .long, help: "Sync only restore images") + var restoreImagesOnly: Bool = false + + @Flag(name: .long, help: "Sync only Xcode versions") + var xcodeOnly: Bool = false + + @Flag(name: .long, help: "Sync only Swift versions") + var swiftOnly: Bool = false + + @Flag(name: .long, help: "Exclude beta/RC releases") + var noBetas: Bool = false + + @Flag(name: .long, help: "Exclude TheAppleWiki.com as data source") + var noAppleWiki: Bool = false + + @Flag(name: .shortAndLong, help: "Enable verbose logging to see detailed CloudKit operations and learn MistKit usage patterns") + var verbose: Bool = false + + @Flag(name: .long, help: "Disable log redaction for debugging (shows actual CloudKit field names in errors)") + var noRedaction: Bool = false + + // MARK: - Throttling Options + + @Flag(name: .long, help: "Force fetch from all sources, ignoring minimum fetch intervals") + var force: Bool = false + + @Option(name: .long, help: "Minimum interval between fetches in seconds (overrides default intervals)") + var minInterval: Int? + + @Option(name: .long, help: "Fetch from only this specific source (e.g., 'appledb.dev', 'ipsw.me')") + var source: String? + + // MARK: - Execution + + mutating func run() async throws { + // Enable verbose logging if requested + BushelLogger.isVerbose = verbose + + // Disable log redaction for debugging if requested + if noRedaction { + setenv("MISTKIT_DISABLE_LOG_REDACTION", "1", 1) + } + + // Get Server-to-Server credentials from environment if not provided + let resolvedKeyID = keyID.isEmpty ? + ProcessInfo.processInfo.environment["CLOUDKIT_KEY_ID"] ?? "" : + keyID + + let resolvedKeyFile = keyFile.isEmpty ? + ProcessInfo.processInfo.environment["CLOUDKIT_PRIVATE_KEY_PATH"] ?? "" : + keyFile + + guard !resolvedKeyID.isEmpty && !resolvedKeyFile.isEmpty else { + print("❌ Error: CloudKit Server-to-Server Key credentials are required") + print("") + print(" Provide via command-line flags:") + print(" --key-id YOUR_KEY_ID --key-file ./private-key.pem") + print("") + print(" Or set environment variables:") + print(" export CLOUDKIT_KEY_ID=\"YOUR_KEY_ID\"") + print(" export CLOUDKIT_PRIVATE_KEY_PATH=\"./private-key.pem\"") + print("") + print(" Get your Server-to-Server Key from:") + print(" https://icloud.developer.apple.com/dashboard/") + print(" Navigate to: API Access → Server-to-Server Keys") + print("") + print(" Important:") + print(" • Download and save the private key .pem file securely") + print(" • Never commit .pem files to version control!") + print("") + throw ExitCode.failure + } + + // Determine what to sync + let options = buildSyncOptions() + + // Build fetch configuration + let configuration = buildFetchConfiguration() + + // Create sync engine + let syncEngine = try SyncEngine( + containerIdentifier: containerIdentifier, + keyID: resolvedKeyID, + privateKeyPath: resolvedKeyFile, + configuration: configuration + ) + + // Execute sync + do { + let result = try await syncEngine.sync(options: options) + printSuccess(result) + } catch { + printError(error) + throw ExitCode.failure + } + } + + // MARK: - Private Helpers + + private func buildSyncOptions() -> SyncEngine.SyncOptions { + var pipelineOptions = DataSourcePipeline.Options() + + // Apply filters based on flags + if restoreImagesOnly { + pipelineOptions.includeXcodeVersions = false + pipelineOptions.includeSwiftVersions = false + } else if xcodeOnly { + pipelineOptions.includeRestoreImages = false + pipelineOptions.includeSwiftVersions = false + } else if swiftOnly { + pipelineOptions.includeRestoreImages = false + pipelineOptions.includeXcodeVersions = false + } + + if noBetas { + pipelineOptions.includeBetaReleases = false + } + + if noAppleWiki { + pipelineOptions.includeTheAppleWiki = false + } + + // Apply throttling options + pipelineOptions.force = force + pipelineOptions.specificSource = source + + return SyncEngine.SyncOptions( + dryRun: dryRun, + pipelineOptions: pipelineOptions + ) + } + + private func buildFetchConfiguration() -> FetchConfiguration { + // Load configuration from environment + var config = FetchConfiguration.loadFromEnvironment() + + // Override with command-line flag if provided + if let interval = minInterval { + config = FetchConfiguration( + globalMinimumFetchInterval: TimeInterval(interval), + perSourceIntervals: config.perSourceIntervals, + useDefaults: true + ) + } + + return config + } + + private func printSuccess(_ result: SyncEngine.SyncResult) { + print("\n" + String(repeating: "=", count: 60)) + print("✅ Sync Summary") + print(String(repeating: "=", count: 60)) + print("Restore Images: \(result.restoreImagesCount)") + print("Xcode Versions: \(result.xcodeVersionsCount)") + print("Swift Versions: \(result.swiftVersionsCount)") + print(String(repeating: "=", count: 60)) + print("\n💡 Next: Use 'bushel-images export' to view the synced data") + } + + private func printError(_ error: Error) { + print("\n❌ Sync failed: \(error.localizedDescription)") + print("\n💡 Troubleshooting:") + print(" • Verify your API token is valid") + print(" • Check your internet connection") + print(" • Ensure the CloudKit container exists") + print(" • Verify external data sources are accessible") + } +} diff --git a/Examples/Bushel/Sources/BushelImages/Configuration/FetchConfiguration.swift b/Examples/Bushel/Sources/BushelImages/Configuration/FetchConfiguration.swift new file mode 100644 index 00000000..39308214 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/Configuration/FetchConfiguration.swift @@ -0,0 +1,121 @@ +// FetchConfiguration.swift +// Created by Claude Code + +import Foundation + +/// Configuration for data source fetch throttling +internal struct FetchConfiguration: Codable, Sendable { + // MARK: - Properties + + /// Global minimum interval between fetches (applies to all sources unless overridden) + let globalMinimumFetchInterval: TimeInterval? + + /// Per-source minimum intervals (overrides global and default intervals) + /// Key is the source name (e.g., "appledb.dev", "ipsw.me") + let perSourceIntervals: [String: TimeInterval] + + /// Whether to use default intervals for known sources + let useDefaults: Bool + + // MARK: - Initialization + + init( + globalMinimumFetchInterval: TimeInterval? = nil, + perSourceIntervals: [String: TimeInterval] = [:], + useDefaults: Bool = true + ) { + self.globalMinimumFetchInterval = globalMinimumFetchInterval + self.perSourceIntervals = perSourceIntervals + self.useDefaults = useDefaults + } + + // MARK: - Methods + + /// Get the minimum fetch interval for a specific source + /// - Parameter source: The source name (e.g., "appledb.dev") + /// - Returns: The minimum interval in seconds, or nil if no restrictions + func minimumInterval(for source: String) -> TimeInterval? { + // Priority: per-source > global > defaults + if let perSourceInterval = perSourceIntervals[source] { + return perSourceInterval + } + + if let globalInterval = globalMinimumFetchInterval { + return globalInterval + } + + if useDefaults { + return Self.defaultIntervals[source] + } + + return nil + } + + /// Should this source be fetched given the last fetch time? + /// - Parameters: + /// - source: The source name + /// - lastFetchedAt: When the source was last fetched (nil means never fetched) + /// - force: Whether to ignore intervals and fetch anyway + /// - Returns: True if the source should be fetched + func shouldFetch( + source: String, + lastFetchedAt: Date?, + force: Bool = false + ) -> Bool { + // Always fetch if force flag is set + if force { return true } + + // Always fetch if never fetched before + guard let lastFetch = lastFetchedAt else { return true } + + // Check if enough time has passed since last fetch + guard let minInterval = minimumInterval(for: source) else { return true } + + let timeSinceLastFetch = Date().timeIntervalSince(lastFetch) + return timeSinceLastFetch >= minInterval + } + + // MARK: - Default Intervals + + /// Default minimum intervals for known sources (in seconds) + static let defaultIntervals: [String: TimeInterval] = [ + // Restore Image Sources + "appledb.dev": 6 * 3600, // 6 hours - frequently updated + "ipsw.me": 12 * 3600, // 12 hours - less frequent updates + "mesu.apple.com": 1 * 3600, // 1 hour - signing status changes frequently + "mrmacintosh.com": 12 * 3600, // 12 hours - manual updates + "theapplewiki.com": 24 * 3600, // 24 hours - deprecated, rarely updated + + // Version Sources + "xcodereleases.com": 12 * 3600, // 12 hours - Xcode releases + "swiftversion.net": 12 * 3600, // 12 hours - Swift releases + ] + + // MARK: - Factory Methods + + /// Load configuration from environment variables + /// - Returns: Configuration with values from environment, or defaults + static func loadFromEnvironment() -> FetchConfiguration { + var perSourceIntervals: [String: TimeInterval] = [:] + + // Check for per-source environment variables (e.g., BUSHEL_FETCH_INTERVAL_APPLEDB) + for (source, _) in defaultIntervals { + let envKey = "BUSHEL_FETCH_INTERVAL_\(source.uppercased().replacingOccurrences(of: ".", with: "_"))" + if let intervalString = ProcessInfo.processInfo.environment[envKey], + let interval = TimeInterval(intervalString) + { + perSourceIntervals[source] = interval + } + } + + // Check for global interval + let globalInterval = ProcessInfo.processInfo.environment["BUSHEL_FETCH_INTERVAL_GLOBAL"] + .flatMap { TimeInterval($0) } + + return FetchConfiguration( + globalMinimumFetchInterval: globalInterval, + perSourceIntervals: perSourceIntervals, + useDefaults: true + ) + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBEntry.swift b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBEntry.swift new file mode 100644 index 00000000..77e2f544 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBEntry.swift @@ -0,0 +1,23 @@ +import Foundation + +/// Represents a single macOS build entry from AppleDB +struct AppleDBEntry: Codable { + let osStr: String + let version: String + let build: String? // Some entries may not have a build number + let uniqueBuild: String? + let released: String // ISO date or empty string + let beta: Bool? + let rc: Bool? + let `internal`: Bool? + let deviceMap: [String] + let signed: SignedStatus + let sources: [AppleDBSource]? + + enum CodingKeys: String, CodingKey { + case osStr, version, build, uniqueBuild, released + case beta, rc + case `internal` = "internal" + case deviceMap, signed, sources + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBFetcher.swift b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBFetcher.swift new file mode 100644 index 00000000..0a4fc937 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBFetcher.swift @@ -0,0 +1,144 @@ +import Foundation + +/// Fetcher for macOS restore images using AppleDB API +struct AppleDBFetcher: DataSourceFetcher, Sendable { + typealias Record = [RestoreImageRecord] + private let deviceIdentifier = "VirtualMac2,1" + + /// Fetch all VirtualMac2,1 restore images from AppleDB + func fetch() async throws -> [RestoreImageRecord] { + // Fetch when macOS data was last updated using GitHub API + let sourceUpdatedAt = await Self.fetchGitHubLastCommitDate() + + // Fetch AppleDB data + let entries = try await Self.fetchAppleDBData() + + // Filter for VirtualMac2,1 and map to RestoreImageRecord + return entries + .filter { $0.deviceMap.contains(deviceIdentifier) } + .compactMap { entry in + Self.mapToRestoreImage(entry: entry, sourceUpdatedAt: sourceUpdatedAt, deviceIdentifier: deviceIdentifier) + } + } + + // MARK: - Private Methods + + /// Fetch the last commit date for macOS data from GitHub API + private static func fetchGitHubLastCommitDate() async -> Date? { + do { + let url = URL(string: "https://api.github.com/repos/littlebyteorg/appledb/commits?path=osFiles/macOS&per_page=1")! + + let (data, _) = try await URLSession.shared.data(from: url) + + let commits = try JSONDecoder().decode([GitHubCommitsResponse].self, from: data) + + guard let firstCommit = commits.first else { + BushelLogger.warning("No commits found in AppleDB GitHub repository", subsystem: BushelLogger.dataSource) + return nil + } + + // Parse ISO 8601 date + let isoFormatter = ISO8601DateFormatter() + guard let date = isoFormatter.date(from: firstCommit.commit.committer.date) else { + BushelLogger.warning("Failed to parse commit date: \(firstCommit.commit.committer.date)", subsystem: BushelLogger.dataSource) + return nil + } + + BushelLogger.verbose("AppleDB macOS data last updated: \(date) (commit: \(firstCommit.sha.prefix(7)))", subsystem: BushelLogger.dataSource) + return date + + } catch { + BushelLogger.warning("Failed to fetch GitHub commit date for AppleDB: \(error)", subsystem: BushelLogger.dataSource) + // Fallback to HTTP Last-Modified header + let appleDBURL = URL(string: "https://api.appledb.dev/ios/macOS/main.json")! + return await HTTPHeaderHelpers.fetchLastModified(from: appleDBURL) + } + } + + /// Fetch macOS data from AppleDB API + private static func fetchAppleDBData() async throws -> [AppleDBEntry] { + let url = URL(string: "https://api.appledb.dev/ios/macOS/main.json")! + + BushelLogger.verbose("Fetching AppleDB data from \(url)", subsystem: BushelLogger.dataSource) + + let (data, _) = try await URLSession.shared.data(from: url) + + let entries = try JSONDecoder().decode([AppleDBEntry].self, from: data) + + BushelLogger.verbose("Fetched \(entries.count) total entries from AppleDB", subsystem: BushelLogger.dataSource) + + return entries + } + + /// Map an AppleDB entry to RestoreImageRecord + private static func mapToRestoreImage(entry: AppleDBEntry, sourceUpdatedAt: Date?, deviceIdentifier: String) -> RestoreImageRecord? { + // Skip entries without a build number (required for unique identification) + guard let build = entry.build else { + BushelLogger.verbose("Skipping AppleDB entry without build number: \(entry.version)", subsystem: BushelLogger.dataSource) + return nil + } + + // Determine if signed for VirtualMac2,1 + let isSigned = entry.signed.isSigned(for: deviceIdentifier) + + // Determine if prerelease + let isPrerelease = entry.beta == true || entry.rc == true || entry.internal == true + + // Parse release date if available + let releaseDate: Date? + if !entry.released.isEmpty { + let isoFormatter = ISO8601DateFormatter() + releaseDate = isoFormatter.date(from: entry.released) + } else { + releaseDate = nil + } + + // Find IPSW source + guard let ipswSource = entry.sources?.first(where: { $0.type == "ipsw" }) else { + BushelLogger.verbose("No IPSW source found for build \(build)", subsystem: BushelLogger.dataSource) + return nil + } + + // Get preferred or first active link + guard let link = ipswSource.links?.first(where: { $0.preferred == true || $0.active == true }) else { + BushelLogger.verbose("No active download link found for build \(build)", subsystem: BushelLogger.dataSource) + return nil + } + + return RestoreImageRecord( + version: entry.version, + buildNumber: build, + releaseDate: releaseDate ?? Date(), // Fallback to current date + downloadURL: link.url, + fileSize: ipswSource.size ?? 0, + sha256Hash: ipswSource.hashes?.sha2_256 ?? "", + sha1Hash: ipswSource.hashes?.sha1 ?? "", + isSigned: isSigned, + isPrerelease: isPrerelease, + source: "appledb.dev", + notes: "Device-specific signing status from AppleDB", + sourceUpdatedAt: sourceUpdatedAt + ) + } +} + +// MARK: - Error Types + +extension AppleDBFetcher { + enum FetchError: LocalizedError { + case invalidURL + case noDataFound + case decodingFailed(Error) + + var errorDescription: String? { + switch self { + case .invalidURL: + return "Invalid AppleDB URL" + case .noDataFound: + return "No data found from AppleDB" + case .decodingFailed(let error): + return "Failed to decode AppleDB response: \(error.localizedDescription)" + } + } + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBHashes.swift b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBHashes.swift new file mode 100644 index 00000000..254a57d0 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBHashes.swift @@ -0,0 +1,12 @@ +import Foundation + +/// Represents file hashes for verification +struct AppleDBHashes: Codable { + let sha1: String? + let sha2_256: String? // JSON key is "sha2-256" + + enum CodingKeys: String, CodingKey { + case sha1 + case sha2_256 = "sha2-256" + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBLink.swift b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBLink.swift new file mode 100644 index 00000000..2fc170cc --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBLink.swift @@ -0,0 +1,8 @@ +import Foundation + +/// Represents a download link for a source +struct AppleDBLink: Codable { + let url: String + let preferred: Bool? + let active: Bool? +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBSource.swift b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBSource.swift new file mode 100644 index 00000000..4ee9ab20 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/AppleDBSource.swift @@ -0,0 +1,11 @@ +import Foundation + +/// Represents an installation source (IPSW, OTA, or IA) +struct AppleDBSource: Codable { + let type: String // "ipsw", "ota", "ia" + let deviceMap: [String] + let links: [AppleDBLink]? + let hashes: AppleDBHashes? + let size: Int? + let prerequisiteBuild: String? +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommit.swift b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommit.swift new file mode 100644 index 00000000..10cb550c --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommit.swift @@ -0,0 +1,7 @@ +import Foundation + +/// Represents a commit in GitHub API response +struct GitHubCommit: Codable { + let committer: GitHubCommitter + let message: String +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommitsResponse.swift b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommitsResponse.swift new file mode 100644 index 00000000..c6c7a6d1 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommitsResponse.swift @@ -0,0 +1,7 @@ +import Foundation + +/// Response from GitHub API for commits +struct GitHubCommitsResponse: Codable { + let sha: String + let commit: GitHubCommit +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommitter.swift b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommitter.swift new file mode 100644 index 00000000..ee07dfea --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/GitHubCommitter.swift @@ -0,0 +1,6 @@ +import Foundation + +/// Represents a committer in GitHub API response +struct GitHubCommitter: Codable { + let date: String // ISO 8601 format +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/SignedStatus.swift b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/SignedStatus.swift new file mode 100644 index 00000000..d461b16d --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/AppleDB/SignedStatus.swift @@ -0,0 +1,54 @@ +import Foundation + +/// Represents the signing status for a build +/// Can be: array of device IDs, boolean true (all signed), or empty array (none signed) +enum SignedStatus: Codable { + case devices([String]) // Array of signed device IDs + case all(Bool) // true = all devices signed + case none // Empty array = not signed + + init(from decoder: Decoder) throws { + let container = try decoder.singleValueContainer() + + // Try decoding as array first + if let devices = try? container.decode([String].self) { + if devices.isEmpty { + self = .none + } else { + self = .devices(devices) + } + } + // Then try boolean + else if let allSigned = try? container.decode(Bool.self) { + self = .all(allSigned) + } + // Default to none if decoding fails + else { + self = .none + } + } + + func encode(to encoder: Encoder) throws { + var container = encoder.singleValueContainer() + switch self { + case .devices(let devices): + try container.encode(devices) + case .all(let value): + try container.encode(value) + case .none: + try container.encode([String]()) + } + } + + /// Check if a specific device identifier is signed + func isSigned(for deviceIdentifier: String) -> Bool { + switch self { + case .devices(let devices): + return devices.contains(deviceIdentifier) + case .all(true): + return true + case .all(false), .none: + return false + } + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/DataSourceFetcher.swift b/Examples/Bushel/Sources/BushelImages/DataSources/DataSourceFetcher.swift new file mode 100644 index 00000000..a23d0946 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/DataSourceFetcher.swift @@ -0,0 +1,81 @@ +import Foundation + +/// Protocol for data source fetchers that retrieve records from external APIs +/// +/// This protocol provides a common interface for all data source fetchers in the Bushel pipeline. +/// Fetchers are responsible for retrieving data from external sources and converting them to +/// typed record models. +/// +/// ## Implementation Requirements +/// - Must be `Sendable` to support concurrent fetching +/// - Should use `HTTPHeaderHelpers.fetchLastModified()` when available to track source freshness +/// - Should log warnings for missing or malformed data using `BushelLogger.dataSource` +/// - Should handle network errors gracefully and provide meaningful error messages +/// +/// ## Example Implementation +/// ```swift +/// struct MyFetcher: DataSourceFetcher { +/// func fetch() async throws -> [MyRecord] { +/// let url = URL(string: "https://api.example.com/data")! +/// let (data, _) = try await URLSession.shared.data(from: url) +/// let items = try JSONDecoder().decode([Item].self, from: data) +/// return items.map { MyRecord(from: $0) } +/// } +/// } +/// ``` +protocol DataSourceFetcher: Sendable { + /// The type of records this fetcher produces + associatedtype Record + + /// Fetch records from the external data source + /// + /// - Returns: Collection of records fetched from the source + /// - Throws: Errors related to network requests, parsing, or data validation + func fetch() async throws -> Record +} + +/// Common utilities for data source fetchers +enum DataSourceUtilities { + /// Fetch data from a URL with optional Last-Modified header tracking + /// + /// This helper combines data fetching with Last-Modified header extraction, + /// allowing fetchers to track when their source data was last updated. + /// + /// - Parameters: + /// - url: The URL to fetch from + /// - trackLastModified: Whether to make a HEAD request to get Last-Modified (default: true) + /// - Returns: Tuple of (data, lastModified date or nil) + /// - Throws: Errors from URLSession or network issues + static func fetchData( + from url: URL, + trackLastModified: Bool = true + ) async throws -> (Data, Date?) { + let lastModified = trackLastModified ? await HTTPHeaderHelpers.fetchLastModified(from: url) : nil + let (data, _) = try await URLSession.shared.data(from: url) + return (data, lastModified) + } + + /// Decode JSON data with helpful error logging + /// + /// - Parameters: + /// - type: The type to decode to + /// - data: The JSON data to decode + /// - source: Source name for error logging + /// - Returns: Decoded object + /// - Throws: DecodingError with context + static func decodeJSON( + _ type: T.Type, + from data: Data, + source: String + ) throws -> T { + do { + return try JSONDecoder().decode(type, from: data) + } catch { + BushelLogger.warning( + "Failed to decode \(T.self) from \(source): \(error)", + subsystem: BushelLogger.dataSource + ) + throw error + } + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/DataSourcePipeline.swift b/Examples/Bushel/Sources/BushelImages/DataSources/DataSourcePipeline.swift new file mode 100644 index 00000000..6acad857 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/DataSourcePipeline.swift @@ -0,0 +1,546 @@ +import Foundation +internal import MistKit + +/// Orchestrates fetching data from all sources with deduplication and relationship resolution +struct DataSourcePipeline: Sendable { + // MARK: - Configuration + + struct Options: Sendable { + var includeRestoreImages: Bool = true + var includeXcodeVersions: Bool = true + var includeSwiftVersions: Bool = true + var includeBetaReleases: Bool = true + var includeAppleDB: Bool = true + var includeTheAppleWiki: Bool = true + var force: Bool = false + var specificSource: String? + } + + // MARK: - Dependencies + + let cloudKitService: BushelCloudKitService? + let configuration: FetchConfiguration + + // MARK: - Initialization + + init( + cloudKitService: BushelCloudKitService? = nil, + configuration: FetchConfiguration = FetchConfiguration.loadFromEnvironment() + ) { + self.cloudKitService = cloudKitService + self.configuration = configuration + } + + // MARK: - Results + + struct FetchResult: Sendable { + var restoreImages: [RestoreImageRecord] + var xcodeVersions: [XcodeVersionRecord] + var swiftVersions: [SwiftVersionRecord] + } + + // MARK: - Public API + + /// Fetch all data from configured sources + func fetch(options: Options = Options()) async throws -> FetchResult { + var restoreImages: [RestoreImageRecord] = [] + var xcodeVersions: [XcodeVersionRecord] = [] + var swiftVersions: [SwiftVersionRecord] = [] + + do { + restoreImages = try await fetchRestoreImages(options: options) + } catch { + print("⚠️ Restore images fetch failed: \(error)") + throw error + } + + do { + xcodeVersions = try await fetchXcodeVersions(options: options) + // Resolve XcodeVersion → RestoreImage references now that we have both datasets + xcodeVersions = resolveXcodeVersionReferences(xcodeVersions, restoreImages: restoreImages) + } catch { + print("⚠️ Xcode versions fetch failed: \(error)") + throw error + } + + do { + swiftVersions = try await fetchSwiftVersions(options: options) + } catch { + print("⚠️ Swift versions fetch failed: \(error)") + throw error + } + + return FetchResult( + restoreImages: restoreImages, + xcodeVersions: xcodeVersions, + swiftVersions: swiftVersions + ) + } + + // MARK: - Metadata Tracking + + /// Check if a source should be fetched based on throttling rules + private func shouldFetch( + source: String, + recordType: String, + force: Bool + ) async -> (shouldFetch: Bool, metadata: DataSourceMetadata?) { + // If force flag is set, always fetch + guard !force else { return (true, nil) } + + // If no CloudKit service, can't check metadata - fetch + guard let cloudKit = cloudKitService else { return (true, nil) } + + // Try to fetch metadata from CloudKit + do { + let metadata = try await cloudKit.queryDataSourceMetadata( + source: source, + recordType: recordType + ) + + // If no metadata exists, this is first fetch - allow it + guard let existingMetadata = metadata else { return (true, nil) } + + // Check configuration to see if enough time has passed + let shouldFetch = configuration.shouldFetch( + source: source, + lastFetchedAt: existingMetadata.lastFetchedAt, + force: force + ) + + return (shouldFetch, existingMetadata) + } catch { + // If metadata query fails, allow fetch but log warning + print(" ⚠️ Failed to query metadata for \(source): \(error)") + return (true, nil) + } + } + + /// Wrap a fetch operation with metadata tracking + private func fetchWithMetadata( + source: String, + recordType: String, + options: Options, + fetcher: () async throws -> [T] + ) async throws -> [T] { + // Check if we should skip this source based on --source flag + if let specificSource = options.specificSource, specificSource != source { + print(" ⏭️ Skipping \(source) (--source=\(specificSource))") + return [] + } + + // Check throttling + let (shouldFetch, existingMetadata) = await shouldFetch( + source: source, + recordType: recordType, + force: options.force + ) + + if !shouldFetch { + if let metadata = existingMetadata { + let timeSinceLastFetch = Date().timeIntervalSince(metadata.lastFetchedAt) + let minInterval = configuration.minimumInterval(for: source) ?? 0 + let timeRemaining = minInterval - timeSinceLastFetch + print(" ⏰ Skipping \(source) (last fetched \(Int(timeSinceLastFetch / 60))m ago, wait \(Int(timeRemaining / 60))m)") + } + return [] + } + + // Perform the fetch with timing + let startTime = Date() + var fetchError: Error? + var recordCount = 0 + + do { + let results = try await fetcher() + recordCount = results.count + + // Update metadata on success + if let cloudKit = cloudKitService { + let metadata = DataSourceMetadata( + sourceName: source, + recordTypeName: recordType, + lastFetchedAt: startTime, + sourceUpdatedAt: existingMetadata?.sourceUpdatedAt, + recordCount: recordCount, + fetchDurationSeconds: Date().timeIntervalSince(startTime), + lastError: nil + ) + + do { + try await cloudKit.sync([metadata]) + } catch { + print(" ⚠️ Failed to update metadata for \(source): \(error)") + } + } + + return results + } catch { + fetchError = error + + // Update metadata on error + if let cloudKit = cloudKitService { + let metadata = DataSourceMetadata( + sourceName: source, + recordTypeName: recordType, + lastFetchedAt: startTime, + sourceUpdatedAt: existingMetadata?.sourceUpdatedAt, + recordCount: 0, + fetchDurationSeconds: Date().timeIntervalSince(startTime), + lastError: error.localizedDescription + ) + + do { + try await cloudKit.sync([metadata]) + } catch { + print(" ⚠️ Failed to update metadata for \(source): \(error)") + } + } + + throw error + } + } + + // MARK: - Private Fetching Methods + + private func fetchRestoreImages(options: Options) async throws -> [RestoreImageRecord] { + guard options.includeRestoreImages else { + return [] + } + + var allImages: [RestoreImageRecord] = [] + + // Fetch from ipsw.me + do { + let ipswImages = try await fetchWithMetadata( + source: "ipsw.me", + recordType: "RestoreImage", + options: options + ) { + try await IPSWFetcher().fetch() + } + allImages.append(contentsOf: ipswImages) + if !ipswImages.isEmpty { + print(" ✓ ipsw.me: \(ipswImages.count) images") + } + } catch { + print(" ⚠️ ipsw.me failed: \(error)") + throw error + } + + // Fetch from MESU + do { + let mesuImages = try await fetchWithMetadata( + source: "mesu.apple.com", + recordType: "RestoreImage", + options: options + ) { + if let image = try await MESUFetcher().fetch() { + return [image] + } else { + return [] + } + } + allImages.append(contentsOf: mesuImages) + if !mesuImages.isEmpty { + print(" ✓ MESU: \(mesuImages.count) image") + } + } catch { + print(" ⚠️ MESU failed: \(error)") + throw error + } + + // Fetch from AppleDB + if options.includeAppleDB { + do { + let appleDBImages = try await fetchWithMetadata( + source: "appledb.dev", + recordType: "RestoreImage", + options: options + ) { + try await AppleDBFetcher().fetch() + } + allImages.append(contentsOf: appleDBImages) + if !appleDBImages.isEmpty { + print(" ✓ AppleDB: \(appleDBImages.count) images") + } + } catch { + print(" ⚠️ AppleDB failed: \(error)") + // Don't throw - continue with other sources + } + } + + // Fetch from Mr. Macintosh (betas) + if options.includeBetaReleases { + do { + let mrMacImages = try await fetchWithMetadata( + source: "mrmacintosh.com", + recordType: "RestoreImage", + options: options + ) { + try await MrMacintoshFetcher().fetch() + } + allImages.append(contentsOf: mrMacImages) + if !mrMacImages.isEmpty { + print(" ✓ Mr. Macintosh: \(mrMacImages.count) images") + } + } catch { + print(" ⚠️ Mr. Macintosh failed: \(error)") + throw error + } + } + + // Fetch from TheAppleWiki + if options.includeTheAppleWiki { + do { + let wikiImages = try await fetchWithMetadata( + source: "theapplewiki.com", + recordType: "RestoreImage", + options: options + ) { + try await TheAppleWikiFetcher().fetch() + } + allImages.append(contentsOf: wikiImages) + if !wikiImages.isEmpty { + print(" ✓ TheAppleWiki: \(wikiImages.count) images") + } + } catch { + print(" ⚠️ TheAppleWiki failed: \(error)") + throw error + } + } + + // Deduplicate by build number (keep first occurrence) + let preDedupeCount = allImages.count + let deduped = deduplicateRestoreImages(allImages) + print(" 📦 Deduplicated: \(preDedupeCount) → \(deduped.count) images") + return deduped + } + + private func fetchXcodeVersions(options: Options) async throws -> [XcodeVersionRecord] { + guard options.includeXcodeVersions else { + return [] + } + + let versions = try await fetchWithMetadata( + source: "xcodereleases.com", + recordType: "XcodeVersion", + options: options + ) { + try await XcodeReleasesFetcher().fetch() + } + + if !versions.isEmpty { + print(" ✓ xcodereleases.com: \(versions.count) versions") + } + + return deduplicateXcodeVersions(versions) + } + + private func fetchSwiftVersions(options: Options) async throws -> [SwiftVersionRecord] { + guard options.includeSwiftVersions else { + return [] + } + + let versions = try await fetchWithMetadata( + source: "swiftversion.net", + recordType: "SwiftVersion", + options: options + ) { + try await SwiftVersionFetcher().fetch() + } + + if !versions.isEmpty { + print(" ✓ swiftversion.net: \(versions.count) versions") + } + + return deduplicateSwiftVersions(versions) + } + + // MARK: - Deduplication + + /// Deduplicate restore images by build number, keeping the most complete record + private func deduplicateRestoreImages(_ images: [RestoreImageRecord]) -> [RestoreImageRecord] { + var uniqueImages: [String: RestoreImageRecord] = [:] + + for image in images { + let key = image.buildNumber + + if let existing = uniqueImages[key] { + // Keep the record with more complete data + uniqueImages[key] = mergeRestoreImages(existing, image) + } else { + uniqueImages[key] = image + } + } + + return Array(uniqueImages.values).sorted { $0.releaseDate > $1.releaseDate } + } + + /// Merge two restore image records, preferring non-empty values + /// + /// This method handles backfilling missing data from different sources: + /// - SHA-256 hashes from AppleDB fill in empty values from ipsw.me + /// - File sizes and SHA-1 hashes are similarly backfilled + /// - Signing status follows MESU authoritative rules + private func mergeRestoreImages( + _ first: RestoreImageRecord, + _ second: RestoreImageRecord + ) -> RestoreImageRecord { + var merged = first + + // Backfill missing hashes and file size from second record + if !second.sha256Hash.isEmpty && first.sha256Hash.isEmpty { + merged.sha256Hash = second.sha256Hash + } + if !second.sha1Hash.isEmpty && first.sha1Hash.isEmpty { + merged.sha1Hash = second.sha1Hash + } + if second.fileSize > 0 && first.fileSize == 0 { + merged.fileSize = second.fileSize + } + + // Merge isSigned with priority rules: + // 1. MESU is always authoritative (Apple's real-time signing status) + // 2. For non-MESU sources, prefer the most recently updated + // 3. If both have same update time (or both nil) and disagree, prefer false + + if first.source == "mesu.apple.com" && first.isSigned != nil { + merged.isSigned = first.isSigned // MESU first is authoritative + } else if second.source == "mesu.apple.com" && second.isSigned != nil { + merged.isSigned = second.isSigned // MESU second is authoritative + } else { + // Neither is MESU, compare update timestamps + let firstUpdated = first.sourceUpdatedAt + let secondUpdated = second.sourceUpdatedAt + + if let firstDate = firstUpdated, let secondDate = secondUpdated { + // Both have dates - use the more recent one + if secondDate > firstDate && second.isSigned != nil { + merged.isSigned = second.isSigned + } else if firstDate >= secondDate && first.isSigned != nil { + merged.isSigned = first.isSigned + } else if first.isSigned != nil { + merged.isSigned = first.isSigned + } else { + merged.isSigned = second.isSigned + } + } else if secondUpdated != nil && second.isSigned != nil { + // Second has date, first doesn't - prefer second + merged.isSigned = second.isSigned + } else if firstUpdated != nil && first.isSigned != nil { + // First has date, second doesn't - prefer first + merged.isSigned = first.isSigned + } else if first.isSigned != nil && second.isSigned != nil { + // Both have values but no dates - prefer false when they disagree + if first.isSigned == second.isSigned { + merged.isSigned = first.isSigned + } else { + merged.isSigned = false + } + } else if second.isSigned != nil { + merged.isSigned = second.isSigned + } else if first.isSigned != nil { + merged.isSigned = first.isSigned + } + } + + // Combine notes + if let secondNotes = second.notes, !secondNotes.isEmpty { + if let firstNotes = first.notes, !firstNotes.isEmpty { + merged.notes = "\(firstNotes); \(secondNotes)" + } else { + merged.notes = secondNotes + } + } + + return merged + } + + /// Resolve XcodeVersion → RestoreImage references by mapping version strings to record names + /// + /// Parses the temporary REQUIRES field in notes and matches it to RestoreImage versions + private func resolveXcodeVersionReferences( + _ versions: [XcodeVersionRecord], + restoreImages: [RestoreImageRecord] + ) -> [XcodeVersionRecord] { + // Build lookup table: version → RestoreImage recordName + var versionLookup: [String: String] = [:] + for image in restoreImages { + // Support multiple version formats: "14.2.1", "14.2", "14" + let version = image.version + versionLookup[version] = image.recordName + + // Also add short versions for matching (e.g., "14.2.1" → "14.2") + let components = version.split(separator: ".") + if components.count > 1 { + let shortVersion = components.prefix(2).joined(separator: ".") + versionLookup[shortVersion] = image.recordName + } + } + + return versions.map { version in + var resolved = version + + // Parse notes field to extract requires string + guard let notes = version.notes else { return resolved } + + let parts = notes.split(separator: "|") + var requiresString: String? + var notesURL: String? + + for part in parts { + if part.hasPrefix("REQUIRES:") { + requiresString = String(part.dropFirst("REQUIRES:".count)) + } else if part.hasPrefix("NOTES_URL:") { + notesURL = String(part.dropFirst("NOTES_URL:".count)) + } + } + + // Try to extract version number from requires (e.g., "macOS 14.2" → "14.2") + if let requires = requiresString { + // Match version patterns like "14.2", "14.2.1", etc. + let versionPattern = #/(\d+\.\d+(?:\.\d+)?(?:\.\d+)?)/# + if let match = requires.firstMatch(of: versionPattern) { + let extractedVersion = String(match.1) + if let recordName = versionLookup[extractedVersion] { + resolved.minimumMacOS = recordName + } + } + } + + // Restore clean notes field + resolved.notes = notesURL + + return resolved + } + } + + /// Deduplicate Xcode versions by build number + private func deduplicateXcodeVersions(_ versions: [XcodeVersionRecord]) -> [XcodeVersionRecord] { + var uniqueVersions: [String: XcodeVersionRecord] = [:] + + for version in versions { + let key = version.buildNumber + if uniqueVersions[key] == nil { + uniqueVersions[key] = version + } + } + + return Array(uniqueVersions.values).sorted { $0.releaseDate > $1.releaseDate } + } + + /// Deduplicate Swift versions by version number + private func deduplicateSwiftVersions(_ versions: [SwiftVersionRecord]) -> [SwiftVersionRecord] { + var uniqueVersions: [String: SwiftVersionRecord] = [:] + + for version in versions { + let key = version.version + if uniqueVersions[key] == nil { + uniqueVersions[key] = version + } + } + + return Array(uniqueVersions.values).sorted { $0.releaseDate > $1.releaseDate } + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/HTTPHeaderHelpers.swift b/Examples/Bushel/Sources/BushelImages/DataSources/HTTPHeaderHelpers.swift new file mode 100644 index 00000000..d8e97410 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/HTTPHeaderHelpers.swift @@ -0,0 +1,37 @@ +import Foundation + +/// Utilities for fetching HTTP headers from data sources +enum HTTPHeaderHelpers { + /// Fetches the Last-Modified header from a URL + /// - Parameter url: The URL to fetch the header from + /// - Returns: The Last-Modified date, or nil if not available + static func fetchLastModified(from url: URL) async -> Date? { + do { + var request = URLRequest(url: url) + request.httpMethod = "HEAD" + + let (_, response) = try await URLSession.shared.data(for: request) + + guard let httpResponse = response as? HTTPURLResponse, + let lastModifiedString = httpResponse.value(forHTTPHeaderField: "Last-Modified") else { + return nil + } + + return parseLastModifiedDate(from: lastModifiedString) + } catch { + BushelLogger.warning("Failed to fetch Last-Modified header from \(url): \(error)", subsystem: BushelLogger.dataSource) + return nil + } + } + + /// Parses a Last-Modified header value in RFC 2822 format + /// - Parameter dateString: The date string from the header + /// - Returns: The parsed date, or nil if parsing fails + private static func parseLastModifiedDate(from dateString: String) -> Date? { + let formatter = DateFormatter() + formatter.dateFormat = "EEE, dd MMM yyyy HH:mm:ss zzz" + formatter.locale = Locale(identifier: "en_US_POSIX") + formatter.timeZone = TimeZone(secondsFromGMT: 0) + return formatter.date(from: dateString) + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/IPSWFetcher.swift b/Examples/Bushel/Sources/BushelImages/DataSources/IPSWFetcher.swift new file mode 100644 index 00000000..81c1f01b --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/IPSWFetcher.swift @@ -0,0 +1,52 @@ +import Foundation +import IPSWDownloads +import OpenAPIURLSession +import OSVer + +/// Fetcher for macOS restore images using the IPSWDownloads package +struct IPSWFetcher: DataSourceFetcher, Sendable { + typealias Record = [RestoreImageRecord] + /// Fetch all VirtualMac2,1 restore images from ipsw.me + func fetch() async throws -> [RestoreImageRecord] { + // Fetch Last-Modified header to know when ipsw.me data was updated + let ipswURL = URL(string: "https://api.ipsw.me/v4/device/VirtualMac2,1?type=ipsw")! + let lastModified = await HTTPHeaderHelpers.fetchLastModified(from: ipswURL) + + // Create IPSWDownloads client with URLSession transport + let client = IPSWDownloads( + transport: URLSessionTransport() + ) + + // Fetch device firmware data for VirtualMac2,1 (macOS virtual machines) + let device = try await client.device( + withIdentifier: "VirtualMac2,1", + type: .ipsw + ) + + return device.firmwares.map { firmware in + RestoreImageRecord( + version: firmware.version.description, // OSVer -> String + buildNumber: firmware.buildid, + releaseDate: firmware.releasedate, + downloadURL: firmware.url.absoluteString, + fileSize: firmware.filesize, + sha256Hash: "", // Not provided by ipsw.me; backfilled from AppleDB during merge + sha1Hash: firmware.sha1sum?.hexString ?? "", + isSigned: firmware.signed, + isPrerelease: false, // ipsw.me doesn't include beta releases + source: "ipsw.me", + notes: nil, + sourceUpdatedAt: lastModified // When ipsw.me last updated their database + ) + } + } +} + +// MARK: - Data Extension + +private extension Data { + /// Convert Data to hexadecimal string + var hexString: String { + map { String(format: "%02x", $0) }.joined() + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/MESUFetcher.swift b/Examples/Bushel/Sources/BushelImages/DataSources/MESUFetcher.swift new file mode 100644 index 00000000..e421a189 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/MESUFetcher.swift @@ -0,0 +1,82 @@ +import Foundation + +/// Fetcher for Apple MESU (Mobile Equipment Software Update) manifest +/// Used for freshness detection of the latest signed restore image +struct MESUFetcher: DataSourceFetcher, Sendable { + typealias Record = RestoreImageRecord? + // MARK: - Internal Models + + fileprivate struct RestoreInfo: Codable { + let BuildVersion: String + let ProductVersion: String + let FirmwareURL: String + let FirmwareSHA1: String? + } + + // MARK: - Public API + + /// Fetch the latest signed restore image from Apple's MESU service + func fetch() async throws -> RestoreImageRecord? { + let urlString = "https://mesu.apple.com/assets/macos/com_apple_macOSIPSW/com_apple_macOSIPSW.xml" + guard let url = URL(string: urlString) else { + throw FetchError.invalidURL + } + + // Fetch Last-Modified header to know when MESU was last updated + let lastModified = await HTTPHeaderHelpers.fetchLastModified(from: url) + + let (data, _) = try await URLSession.shared.data(from: url) + + // Parse as property list (plist) + guard let plist = try PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any] else { + throw FetchError.parsingFailed + } + + // Navigate to the firmware data + // Structure: MobileDeviceSoftwareVersionsByVersion -> "1" -> MobileDeviceSoftwareVersions -> VirtualMac2,1 -> BuildVersion -> Restore + guard let versionsByVersion = plist["MobileDeviceSoftwareVersionsByVersion"] as? [String: Any], + let version1 = versionsByVersion["1"] as? [String: Any], + let softwareVersions = version1["MobileDeviceSoftwareVersions"] as? [String: Any], + let virtualMac = softwareVersions["VirtualMac2,1"] as? [String: Any] else { + return nil + } + + // Find the first available build (should be the latest signed) + for (buildVersion, buildInfo) in virtualMac { + guard let buildInfo = buildInfo as? [String: Any], + let restoreDict = buildInfo["Restore"] as? [String: Any], + let productVersion = restoreDict["ProductVersion"] as? String, + let firmwareURL = restoreDict["FirmwareURL"] as? String else { + continue + } + + let firmwareSHA1 = restoreDict["FirmwareSHA1"] as? String ?? "" + + // Return the first restore image found (typically the latest) + return RestoreImageRecord( + version: productVersion, + buildNumber: buildVersion, + releaseDate: Date(), // MESU doesn't provide release date, use current date + downloadURL: firmwareURL, + fileSize: 0, // Not provided by MESU + sha256Hash: "", // MESU only provides SHA1 + sha1Hash: firmwareSHA1, + isSigned: true, // MESU only lists currently signed images + isPrerelease: false, // MESU typically only has final releases + source: "mesu.apple.com", + notes: "Latest signed release from Apple MESU", + sourceUpdatedAt: lastModified // When Apple last updated MESU manifest + ) + } + + // No restore images found in the plist + return nil + } + + // MARK: - Error Types + + enum FetchError: Error { + case invalidURL + case parsingFailed + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/MrMacintoshFetcher.swift b/Examples/Bushel/Sources/BushelImages/DataSources/MrMacintoshFetcher.swift new file mode 100644 index 00000000..275079fe --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/MrMacintoshFetcher.swift @@ -0,0 +1,176 @@ +import Foundation +import SwiftSoup + +/// Fetcher for macOS beta/RC restore images from Mr. Macintosh database +internal struct MrMacintoshFetcher: DataSourceFetcher, Sendable { + internal typealias Record = [RestoreImageRecord] + // MARK: - Public API + + /// Fetch beta and RC restore images from Mr. Macintosh + internal func fetch() async throws -> [RestoreImageRecord] { + let urlString = "https://mrmacintosh.com/apple-silicon-m1-full-macos-restore-ipsw-firmware-files-database/" + guard let url = URL(string: urlString) else { + throw FetchError.invalidURL + } + + let (data, _) = try await URLSession.shared.data(from: url) + guard let html = String(data: data, encoding: .utf8) else { + throw FetchError.invalidEncoding + } + + let doc = try SwiftSoup.parse(html) + + // Extract the page update date from UPDATED: MM/DD/YY + var pageUpdatedAt: Date? + if let strongElements = try? doc.select("strong"), + let updateElement = strongElements.first(where: { element in + (try? element.text().uppercased().starts(with: "UPDATED:")) == true + }), + let updateText = try? updateElement.text(), + let dateString = updateText.split(separator: ":").last?.trimmingCharacters(in: .whitespaces) { + pageUpdatedAt = parseDateMMDDYY(from: String(dateString)) + if let date = pageUpdatedAt { + BushelLogger.verbose("Mr. Macintosh page last updated: \(date)", subsystem: BushelLogger.dataSource) + } + } + + // Find all table rows + let rows = try doc.select("table tr") + + let records = rows.compactMap { row in + parseTableRow(row, pageUpdatedAt: pageUpdatedAt) + } + + return records + } + + // MARK: - Helpers + + /// Parse a table row into a RestoreImageRecord + private func parseTableRow(_ row: SwiftSoup.Element, pageUpdatedAt: Date?) -> RestoreImageRecord? { + do { + let cells = try row.select("td") + guard cells.count >= 3 else { return nil } + + // Expected columns: Download Link | Version | Date | [Optional: Signed Status] + // Extract filename and URL from first cell + guard let linkElement = try cells[0].select("a").first(), + let downloadURL = try? linkElement.attr("href"), + !downloadURL.isEmpty else { + return nil + } + + let filename = try linkElement.text() + + // Parse filename like "UniversalMac_26.1_25B78_Restore.ipsw" + // Extract version and build from filename + guard filename.contains("UniversalMac") else { return nil } + + let components = filename.replacingOccurrences(of: ".ipsw", with: "") + .components(separatedBy: "_") + guard components.count >= 3 else { return nil } + + let version = components[1] + let buildNumber = components[2] + + // Get version from second cell (more reliable) + let versionFromCell = try cells[1].text() + + // Get date from third cell + let dateStr = try cells[2].text() + let releaseDate = parseDate(from: dateStr) ?? Date() + + // Check if signed (4th column if present) + let isSigned: Bool? = cells.count >= 4 ? try cells[3].text().uppercased().contains("YES") : nil + + // Determine if it's a beta/RC release from filename or version + let isPrerelease = filename.lowercased().contains("beta") || + filename.lowercased().contains("rc") || + versionFromCell.lowercased().contains("beta") || + versionFromCell.lowercased().contains("rc") + + return RestoreImageRecord( + version: version, + buildNumber: buildNumber, + releaseDate: releaseDate, + downloadURL: downloadURL, + fileSize: 0, // Not provided + sha256Hash: "", // Not provided + sha1Hash: "", // Not provided + isSigned: isSigned, + isPrerelease: isPrerelease, + source: "mrmacintosh.com", + notes: nil, + sourceUpdatedAt: pageUpdatedAt // Date when Mr. Macintosh last updated the page + ) + } catch { + BushelLogger.verbose("Failed to parse table row: \(error)", subsystem: BushelLogger.dataSource) + return nil + } + } + + /// Parse date from Mr. Macintosh format (MM/DD/YY or M/D or M/DD) + private func parseDate(from string: String) -> Date? { + let trimmed = string.trimmingCharacters(in: .whitespacesAndNewlines) + + // Try formats with year first + let formattersWithYear = [ + makeDateFormatter(format: "M/d/yy"), + makeDateFormatter(format: "MM/dd/yy"), + makeDateFormatter(format: "M/d/yyyy"), + makeDateFormatter(format: "MM/dd/yyyy") + ] + + for formatter in formattersWithYear { + if let date = formatter.date(from: trimmed) { + return date + } + } + + // If no year, assume current or previous year + let formattersNoYear = [ + makeDateFormatter(format: "M/d"), + makeDateFormatter(format: "MM/dd") + ] + + for formatter in formattersNoYear { + if let date = formatter.date(from: trimmed) { + // Add current year + let calendar = Calendar.current + let currentYear = calendar.component(.year, from: Date()) + var components = calendar.dateComponents([.month, .day], from: date) + components.year = currentYear + + // If date is in the future, use previous year + if let dateWithYear = calendar.date(from: components), dateWithYear > Date() { + components.year = currentYear - 1 + } + + return calendar.date(from: components) + } + } + + return nil + } + + /// Parse date from page update format (MM/DD/YY) + private func parseDateMMDDYY(from string: String) -> Date? { + let trimmed = string.trimmingCharacters(in: .whitespacesAndNewlines) + let formatter = makeDateFormatter(format: "MM/dd/yy") + return formatter.date(from: trimmed) + } + + private func makeDateFormatter(format: String) -> DateFormatter { + let formatter = DateFormatter() + formatter.dateFormat = format + formatter.locale = Locale(identifier: "en_US_POSIX") + return formatter + } + + // MARK: - Error Types + + enum FetchError: Error { + case invalidURL + case invalidEncoding + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/SwiftVersionFetcher.swift b/Examples/Bushel/Sources/BushelImages/DataSources/SwiftVersionFetcher.swift new file mode 100644 index 00000000..5481c0fc --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/SwiftVersionFetcher.swift @@ -0,0 +1,69 @@ +import Foundation +import SwiftSoup + +/// Fetcher for Swift compiler versions from swiftversion.net +struct SwiftVersionFetcher: DataSourceFetcher, Sendable { + typealias Record = [SwiftVersionRecord] + // MARK: - Internal Models + + private struct SwiftVersionEntry { + let date: Date + let swiftVersion: String + let xcodeVersion: String + } + + // MARK: - Public API + + /// Fetch all Swift versions from swiftversion.net + func fetch() async throws -> [SwiftVersionRecord] { + let url = URL(string: "https://swiftversion.net")! + let (data, _) = try await URLSession.shared.data(from: url) + guard let html = String(data: data, encoding: .utf8) else { + throw FetchError.invalidEncoding + } + + let doc = try SwiftSoup.parse(html) + let rows = try doc.select("tbody tr.table-entry") + + var entries: [SwiftVersionEntry] = [] + let dateFormatter = DateFormatter() + dateFormatter.dateFormat = "dd MMM yy" + + for row in rows { + let cells = try row.select("td") + guard cells.count == 3 else { continue } + + let dateStr = try cells[0].text() + let swiftVer = try cells[1].text() + let xcodeVer = try cells[2].text() + + guard let date = dateFormatter.date(from: dateStr) else { + print("Warning: Could not parse date: \(dateStr)") + continue + } + + entries.append(SwiftVersionEntry( + date: date, + swiftVersion: swiftVer, + xcodeVersion: xcodeVer + )) + } + + return entries.map { entry in + SwiftVersionRecord( + version: entry.swiftVersion, + releaseDate: entry.date, + downloadURL: "https://swift.org/download/", // Generic download page + isPrerelease: entry.swiftVersion.contains("beta") || + entry.swiftVersion.contains("snapshot"), + notes: "Bundled with Xcode \(entry.xcodeVersion)" + ) + } + } + + // MARK: - Error Types + + enum FetchError: Error { + case invalidEncoding + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/IPSWParser.swift b/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/IPSWParser.swift new file mode 100644 index 00000000..dd2b86fb --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/IPSWParser.swift @@ -0,0 +1,191 @@ +import Foundation + +// MARK: - Errors + +enum TheAppleWikiError: LocalizedError { + case invalidURL(String) + case networkError(underlying: Error) + case parsingError(String) + case noDataFound + + var errorDescription: String? { + switch self { + case .invalidURL(let url): + return "Invalid URL: \(url)" + case .networkError(let error): + return "Network error: \(error.localizedDescription)" + case .parsingError(let details): + return "Parsing error: \(details)" + case .noDataFound: + return "No IPSW data found" + } + } +} + +// MARK: - Parser + +/// Fetches macOS IPSW metadata from TheAppleWiki.com +@available(macOS 12.0, *) +struct IPSWParser: Sendable { + private let baseURL = "https://theapplewiki.com" + private let apiEndpoint = "/api.php" + + /// Fetch all available IPSW versions for macOS 12+ + /// - Parameter deviceFilter: Optional device identifier to filter by (e.g., "VirtualMac2,1") + /// - Returns: Array of IPSW versions matching the filter + func fetchAllIPSWVersions(deviceFilter: String? = nil) async throws -> [IPSWVersion] { + // Get list of Mac firmware pages + let pagesURL = try buildPagesURL() + let pagesData = try await fetchData(from: pagesURL) + let pagesResponse = try JSONDecoder().decode(ParseResponse.self, from: pagesData) + + var allVersions: [IPSWVersion] = [] + + // Extract firmware page links from content + let content = pagesResponse.parse.text.content + let versionPages = try extractVersionPages(from: content) + + // Fetch versions from each page + for pageTitle in versionPages { + let pageURL = try buildPageURL(for: pageTitle) + do { + let versions = try await parseIPSWPage(url: pageURL, deviceFilter: deviceFilter) + allVersions.append(contentsOf: versions) + } catch { + // Continue on page parse errors - some pages may be empty or malformed + continue + } + } + + guard !allVersions.isEmpty else { + throw TheAppleWikiError.noDataFound + } + + return allVersions + } + + // MARK: - Private Methods + + private func buildPagesURL() throws -> URL { + guard let url = URL(string: baseURL + apiEndpoint + "?action=parse&page=Firmware/Mac&format=json") else { + throw TheAppleWikiError.invalidURL("Firmware/Mac") + } + return url + } + + private func buildPageURL(for pageTitle: String) throws -> URL { + guard let encoded = pageTitle.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed), + let url = URL(string: baseURL + apiEndpoint + "?action=parse&page=\(encoded)&format=json") else { + throw TheAppleWikiError.invalidURL(pageTitle) + } + return url + } + + private func fetchData(from url: URL) async throws -> Data { + do { + let (data, _) = try await URLSession.shared.data(from: url) + return data + } catch { + throw TheAppleWikiError.networkError(underlying: error) + } + } + + private func extractVersionPages(from content: String) throws -> [String] { + let pattern = #"Firmware/Mac/(\d+)\.x"# + guard let regex = try? NSRegularExpression(pattern: pattern) else { + throw TheAppleWikiError.parsingError("Invalid regex pattern") + } + + let matches = regex.matches(in: content, range: NSRange(content.startIndex..., in: content)) + + let versionPages = matches.compactMap { match -> String? in + guard let range = Range(match.range(at: 1), in: content), + let version = Double(content[range]), + version >= 12 else { + return nil + } + return "Firmware/Mac/\(Int(version)).x" + } + + return versionPages + } + + private func parseIPSWPage(url: URL, deviceFilter: String?) async throws -> [IPSWVersion] { + let data = try await fetchData(from: url) + let response = try JSONDecoder().decode(ParseResponse.self, from: data) + + var versions: [IPSWVersion] = [] + + // Split content into rows (basic HTML parsing) + let rows = response.parse.text.content.components(separatedBy: " String? in + // Extract text between td tags, removing HTML + guard let endIndex = cell.range(of: "")?.lowerBound else { return nil } + let content = cell[..]+>", with: "", options: .regularExpression) + } + + guard cells.count >= 6 else { continue } + + let version = cells[0] + let buildNumber = cells[1] + let deviceModel = cells[2] + let fileName = cells[3] + + // Skip if filename doesn't end with ipsw + guard fileName.lowercased().hasSuffix("ipsw") else { continue } + + // Apply device filter if specified + if let filter = deviceFilter, !deviceModel.contains(filter) { + continue + } + + let fileSize = cells[4] + let sha1 = cells[5] + + let releaseDate: Date? = cells.count > 6 ? parseDate(cells[6]) : nil + let url: URL? = parseURL(from: cells[3]) + + versions.append(IPSWVersion( + version: version, + buildNumber: buildNumber, + deviceModel: deviceModel, + fileName: fileName, + fileSize: fileSize, + sha1: sha1, + releaseDate: releaseDate, + url: url + )) + } + + return versions + } + + private func parseDate(_ str: String) -> Date? { + let formatter = DateFormatter() + formatter.dateFormat = "yyyy-MM-dd" + return formatter.date(from: str) + } + + private func parseURL(from text: String) -> URL? { + // Extract URL from possible HTML link in text + let pattern = #"href="([^"]+)"# + guard let match = text.range(of: pattern, options: .regularExpression) else { + return nil + } + + let urlString = String(text[match]) + .replacingOccurrences(of: "href=\"", with: "") + .replacingOccurrences(of: "\"", with: "") + + return URL(string: urlString) + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/Models/IPSWVersion.swift b/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/Models/IPSWVersion.swift new file mode 100644 index 00000000..742065aa --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/Models/IPSWVersion.swift @@ -0,0 +1,61 @@ +import Foundation + +/// IPSW metadata from TheAppleWiki +struct IPSWVersion: Codable, Sendable { + let version: String + let buildNumber: String + let deviceModel: String + let fileName: String + let fileSize: String + let sha1: String + let releaseDate: Date? + let url: URL? + + // MARK: - Computed Properties + + /// Parse file size string to Int for CloudKit + /// Examples: "10.2 GB" -> bytes, "1.5 MB" -> bytes + var fileSizeInBytes: Int? { + let components = fileSize.components(separatedBy: " ") + guard components.count == 2, + let size = Double(components[0]) else { + return nil + } + + let unit = components[1].uppercased() + let multiplier: Double = switch unit { + case "GB": 1_000_000_000 + case "MB": 1_000_000 + case "KB": 1_000 + case "BYTES", "B": 1 + default: 0 + } + + guard multiplier > 0 else { return nil } + return Int(size * multiplier) + } + + /// Detect if this is a VirtualMac device + var isVirtualMac: Bool { + deviceModel.contains("VirtualMac") + } + + /// Detect if this is a prerelease version (beta, RC, etc.) + var isPrerelease: Bool { + let lowercased = version.lowercased() + return lowercased.contains("beta") + || lowercased.contains("rc") + || lowercased.contains("gm seed") + || lowercased.contains("developer preview") + } + + /// Validate that all required fields are present + var isValid: Bool { + !version.isEmpty + && !buildNumber.isEmpty + && !deviceModel.isEmpty + && !fileName.isEmpty + && !sha1.isEmpty + && url != nil + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/Models/WikiAPITypes.swift b/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/Models/WikiAPITypes.swift new file mode 100644 index 00000000..43d07d5f --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/Models/WikiAPITypes.swift @@ -0,0 +1,23 @@ +import Foundation + +// MARK: - TheAppleWiki API Response Types + +/// Root response from TheAppleWiki parse API +struct ParseResponse: Codable, Sendable { + let parse: ParseContent +} + +/// Parse content container +struct ParseContent: Codable, Sendable { + let title: String + let text: TextContent +} + +/// Text content with HTML +struct TextContent: Codable, Sendable { + let content: String + + enum CodingKeys: String, CodingKey { + case content = "*" + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/TheAppleWikiFetcher.swift b/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/TheAppleWikiFetcher.swift new file mode 100644 index 00000000..f860512d --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/TheAppleWiki/TheAppleWikiFetcher.swift @@ -0,0 +1,48 @@ +import Foundation + +/// Fetcher for macOS restore images using TheAppleWiki.com +@available(*, deprecated, message: "Use AppleDBFetcher instead for more reliable and up-to-date data") +internal struct TheAppleWikiFetcher: DataSourceFetcher, Sendable { + internal typealias Record = [RestoreImageRecord] + /// Fetch all macOS restore images from TheAppleWiki + internal func fetch() async throws -> [RestoreImageRecord] { + // Fetch Last-Modified header from TheAppleWiki API + let apiURL = URL(string: "https://theapplewiki.com/api.php?action=parse&page=Firmware/Mac&format=json")! + let lastModified = await HTTPHeaderHelpers.fetchLastModified(from: apiURL) + + let parser = IPSWParser() + + // Fetch all versions without device filtering (UniversalMac images work for all devices) + let versions = try await parser.fetchAllIPSWVersions(deviceFilter: nil) + + // Map to RestoreImageRecord, filtering out only invalid entries + // Deduplication happens later in DataSourcePipeline + return versions + .filter { $0.isValid } + .compactMap { version -> RestoreImageRecord? in + // Skip if we can't get essential data + guard let downloadURL = version.url?.absoluteString, + let fileSize = version.fileSizeInBytes else { + return nil + } + + // Use current date as fallback if release date is missing + let releaseDate = version.releaseDate ?? Date() + + return RestoreImageRecord( + version: version.version, + buildNumber: version.buildNumber, + releaseDate: releaseDate, + downloadURL: downloadURL, + fileSize: fileSize, + sha256Hash: "", // Not available from TheAppleWiki + sha1Hash: version.sha1, + isSigned: nil, // Unknown - will be merged from other sources + isPrerelease: version.isPrerelease, + source: "theapplewiki.com", + notes: "Device: \(version.deviceModel)", + sourceUpdatedAt: lastModified // When TheAppleWiki API was last updated + ) + } + } +} diff --git a/Examples/Bushel/Sources/BushelImages/DataSources/XcodeReleasesFetcher.swift b/Examples/Bushel/Sources/BushelImages/DataSources/XcodeReleasesFetcher.swift new file mode 100644 index 00000000..af4ac7f0 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/DataSources/XcodeReleasesFetcher.swift @@ -0,0 +1,146 @@ +import Foundation + +/// Fetcher for Xcode releases from xcodereleases.com JSON API +struct XcodeReleasesFetcher: DataSourceFetcher, Sendable { + typealias Record = [XcodeVersionRecord] + // MARK: - API Models + + private struct XcodeRelease: Codable { + let checksums: Checksums? + let compilers: Compilers? + let date: ReleaseDate + let links: Links? + let name: String + let requires: String + let sdks: SDKs? + let version: Version + + struct Checksums: Codable { + let sha1: String + } + + struct Compilers: Codable { + let clang: [Compiler]? + let swift: [Compiler]? + } + + struct Compiler: Codable { + let build: String? + let number: String? + let release: Release? + } + + struct Release: Codable { + let release: Bool? + let beta: Int? + let rc: Int? + + var isPrerelease: Bool { + beta != nil || rc != nil + } + } + + struct ReleaseDate: Codable { + let day: Int + let month: Int + let year: Int + + var toDate: Date { + let components = DateComponents(year: year, month: month, day: day) + return Calendar.current.date(from: components) ?? Date() + } + } + + struct Links: Codable { + let download: Download? + let notes: Notes? + + struct Download: Codable { + let url: String + } + + struct Notes: Codable { + let url: String + } + } + + struct SDKs: Codable { + let iOS: [SDK]? + let macOS: [SDK]? + let tvOS: [SDK]? + let visionOS: [SDK]? + let watchOS: [SDK]? + + struct SDK: Codable { + let build: String? + let number: String? + let release: Release? + } + } + + struct Version: Codable { + let build: String + let number: String + let release: Release + } + } + + // MARK: - Public API + + /// Fetch all Xcode releases from xcodereleases.com + func fetch() async throws -> [XcodeVersionRecord] { + let url = URL(string: "https://xcodereleases.com/data.json")! + let (data, _) = try await URLSession.shared.data(from: url) + let releases = try JSONDecoder().decode([XcodeRelease].self, from: data) + + return releases.map { release in + // Build SDK versions JSON (if SDK info is available) + var sdkDict: [String: String] = [:] + if let sdks = release.sdks { + if let ios = sdks.iOS?.first, let number = ios.number { sdkDict["iOS"] = number } + if let macos = sdks.macOS?.first, let number = macos.number { sdkDict["macOS"] = number } + if let tvos = sdks.tvOS?.first, let number = tvos.number { sdkDict["tvOS"] = number } + if let visionos = sdks.visionOS?.first, let number = visionos.number { sdkDict["visionOS"] = number } + if let watchos = sdks.watchOS?.first, let number = watchos.number { sdkDict["watchOS"] = number } + } + + // Encode SDK dictionary to JSON string with proper error handling + let sdkString: String? = { + do { + let data = try JSONEncoder().encode(sdkDict) + return String(data: data, encoding: .utf8) + } catch { + BushelLogger.warning( + "Failed to encode SDK versions for \(release.name): \(error)", + subsystem: BushelLogger.dataSource + ) + return nil + } + }() + + // Extract Swift version (if compilers info is available) + let swiftVersion = release.compilers?.swift?.first?.number + + // Store requires string temporarily for later resolution + // Format: "REQUIRES:|NOTES_URL:" + var notesField = "REQUIRES:\(release.requires)" + if let notesURL = release.links?.notes?.url { + notesField += "|NOTES_URL:\(notesURL)" + } + + return XcodeVersionRecord( + version: release.version.number, + buildNumber: release.version.build, + releaseDate: release.date.toDate, + downloadURL: release.links?.download?.url, + fileSize: nil, // Not provided by API + isPrerelease: release.version.release.isPrerelease, + minimumMacOS: nil, // Will be resolved in DataSourcePipeline + includedSwiftVersion: swiftVersion.map { "SwiftVersion-\($0)" }, + sdkVersions: sdkString, + notes: notesField + ) + } + } + +} diff --git a/Examples/Bushel/Sources/BushelImages/Logger.swift b/Examples/Bushel/Sources/BushelImages/Logger.swift new file mode 100644 index 00000000..164e8748 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/Logger.swift @@ -0,0 +1,73 @@ +import Foundation +import Logging + +/// Centralized logging infrastructure for Bushel demo +/// +/// This demonstrates best practices for logging in CloudKit applications: +/// - Subsystem-based organization for filtering +/// - Educational logging that teaches CloudKit concepts +/// - Verbose mode for debugging and learning +/// +/// **Tutorial Note**: Use `--verbose` flag to see detailed CloudKit operations +enum BushelLogger { + // MARK: - Subsystems + + /// Logger for CloudKit operations (sync, queries, batch uploads) + static let cloudKit = Logger(label: "com.brightdigit.Bushel.cloudkit") + + /// Logger for external data source fetching (ipsw.me, TheAppleWiki, etc.) + static let dataSource = Logger(label: "com.brightdigit.Bushel.datasource") + + /// Logger for sync engine orchestration + static let sync = Logger(label: "com.brightdigit.Bushel.sync") + + // MARK: - Verbose Mode State + + /// Global verbose mode flag - set by command-line arguments + /// + /// Note: This is marked with `nonisolated(unsafe)` because it's set once at startup + /// before any concurrent access and then only read. This pattern is safe for CLI tools. + nonisolated(unsafe) static var isVerbose = false + + // MARK: - Logging Helpers + + /// Log informational message (always shown) + static func info(_ message: String, subsystem: Logger) { + print(message) + subsystem.info("\(message)") + } + + /// Log verbose message (only shown when --verbose is enabled) + static func verbose(_ message: String, subsystem: Logger) { + guard isVerbose else { return } + print(" 🔍 \(message)") + subsystem.debug("\(message)") + } + + /// Log educational explanation (shown in verbose mode) + /// + /// Use this to explain CloudKit concepts and MistKit usage patterns + static func explain(_ message: String, subsystem: Logger) { + guard isVerbose else { return } + print(" 💡 \(message)") + subsystem.debug("EXPLANATION: \(message)") + } + + /// Log warning message (always shown) + static func warning(_ message: String, subsystem: Logger) { + print(" ⚠️ \(message)") + subsystem.warning("\(message)") + } + + /// Log error message (always shown) + static func error(_ message: String, subsystem: Logger) { + print(" ❌ \(message)") + subsystem.error("\(message)") + } + + /// Log success message (always shown) + static func success(_ message: String, subsystem: Logger) { + print(" ✓ \(message)") + subsystem.info("SUCCESS: \(message)") + } +} diff --git a/Examples/Bushel/Sources/BushelImages/Models/DataSourceMetadata.swift b/Examples/Bushel/Sources/BushelImages/Models/DataSourceMetadata.swift new file mode 100644 index 00000000..ad1c1049 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/Models/DataSourceMetadata.swift @@ -0,0 +1,122 @@ +// DataSourceMetadata.swift +// Created by Claude Code + +public import Foundation +public import MistKit + +/// Metadata about when a data source was last fetched and updated +public struct DataSourceMetadata: Codable, Sendable { + // MARK: Lifecycle + + public init( + sourceName: String, + recordTypeName: String, + lastFetchedAt: Date, + sourceUpdatedAt: Date? = nil, + recordCount: Int = 0, + fetchDurationSeconds: Double = 0, + lastError: String? = nil + ) { + self.sourceName = sourceName + self.recordTypeName = recordTypeName + self.lastFetchedAt = lastFetchedAt + self.sourceUpdatedAt = sourceUpdatedAt + self.recordCount = recordCount + self.fetchDurationSeconds = fetchDurationSeconds + self.lastError = lastError + } + + // MARK: Public + + /// The name of the data source (e.g., "appledb.dev", "ipsw.me") + public let sourceName: String + + /// The type of records this source provides (e.g., "RestoreImage", "XcodeVersion") + public let recordTypeName: String + + /// When we last fetched data from this source + public let lastFetchedAt: Date + + /// When the source last updated its data (from HTTP Last-Modified or API metadata) + public let sourceUpdatedAt: Date? + + /// Number of records retrieved from this source + public let recordCount: Int + + /// How long the fetch operation took in seconds + public let fetchDurationSeconds: Double + + /// Last error message if the fetch failed + public let lastError: String? + + /// CloudKit record name for this metadata entry + public var recordName: String { + "metadata-\(sourceName)-\(recordTypeName)" + } +} + +// MARK: - CloudKitRecord Conformance + +extension DataSourceMetadata: CloudKitRecord { + public static var cloudKitRecordType: String { "DataSourceMetadata" } + + public func toCloudKitFields() -> [String: FieldValue] { + var fields: [String: FieldValue] = [ + "sourceName": .string(sourceName), + "recordTypeName": .string(recordTypeName), + "lastFetchedAt": .date(lastFetchedAt), + "recordCount": .int64(recordCount), + "fetchDurationSeconds": .double(fetchDurationSeconds) + ] + + // Optional fields + if let sourceUpdatedAt { + fields["sourceUpdatedAt"] = .date(sourceUpdatedAt) + } + + if let lastError { + fields["lastError"] = .string(lastError) + } + + return fields + } + + public static func from(recordInfo: RecordInfo) -> Self? { + guard let sourceName = recordInfo.fields["sourceName"]?.stringValue, + let recordTypeName = recordInfo.fields["recordTypeName"]?.stringValue, + let lastFetchedAt = recordInfo.fields["lastFetchedAt"]?.dateValue + else { + return nil + } + + return DataSourceMetadata( + sourceName: sourceName, + recordTypeName: recordTypeName, + lastFetchedAt: lastFetchedAt, + sourceUpdatedAt: recordInfo.fields["sourceUpdatedAt"]?.dateValue, + recordCount: recordInfo.fields["recordCount"]?.intValue ?? 0, + fetchDurationSeconds: recordInfo.fields["fetchDurationSeconds"]?.doubleValue ?? 0, + lastError: recordInfo.fields["lastError"]?.stringValue + ) + } + + public static func formatForDisplay(_ recordInfo: RecordInfo) -> String { + let sourceName = recordInfo.fields["sourceName"]?.stringValue ?? "Unknown" + let recordTypeName = recordInfo.fields["recordTypeName"]?.stringValue ?? "Unknown" + let lastFetchedAt = recordInfo.fields["lastFetchedAt"]?.dateValue + let recordCount = recordInfo.fields["recordCount"]?.intValue ?? 0 + + let dateStr = lastFetchedAt.map { formatDate($0) } ?? "Unknown" + + var output = "\n \(sourceName) → \(recordTypeName)\n" + output += " Last fetched: \(dateStr) | Records: \(recordCount)" + return output + } + + private static func formatDate(_ date: Date) -> String { + let formatter = DateFormatter() + formatter.dateStyle = .medium + formatter.timeStyle = .short + return formatter.string(from: date) + } +} diff --git a/Examples/Bushel/Sources/BushelImages/Models/RestoreImageRecord.swift b/Examples/Bushel/Sources/BushelImages/Models/RestoreImageRecord.swift new file mode 100644 index 00000000..145e6b30 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/Models/RestoreImageRecord.swift @@ -0,0 +1,136 @@ +import Foundation +import MistKit + +/// Represents a macOS IPSW restore image for Apple Virtualization framework +struct RestoreImageRecord: Codable, Sendable { + /// macOS version (e.g., "14.2.1", "15.0 Beta 3") + var version: String + + /// Build identifier (e.g., "23C71", "24A5264n") + var buildNumber: String + + /// Official release date + var releaseDate: Date + + /// Direct IPSW download link + var downloadURL: String + + /// File size in bytes + var fileSize: Int + + /// SHA-256 checksum for integrity verification + var sha256Hash: String + + /// SHA-1 hash (from MESU/ipsw.me for compatibility) + var sha1Hash: String + + /// Whether Apple still signs this restore image (nil if unknown) + var isSigned: Bool? + + /// Beta/RC release indicator + var isPrerelease: Bool + + /// Data source: "ipsw.me", "mrmacintosh.com", "mesu.apple.com" + var source: String + + /// Additional metadata or release notes + var notes: String? + + /// When the source last updated this record (nil if unknown) + var sourceUpdatedAt: Date? + + /// CloudKit record name based on build number (e.g., "RestoreImage-23C71") + var recordName: String { + "RestoreImage-\(buildNumber)" + } +} + +// MARK: - CloudKitRecord Conformance + +extension RestoreImageRecord: CloudKitRecord { + static var cloudKitRecordType: String { "RestoreImage" } + + func toCloudKitFields() -> [String: FieldValue] { + var fields: [String: FieldValue] = [ + "version": .string(version), + "buildNumber": .string(buildNumber), + "releaseDate": .date(releaseDate), + "downloadURL": .string(downloadURL), + "fileSize": .int64(fileSize), + "sha256Hash": .string(sha256Hash), + "sha1Hash": .string(sha1Hash), + "isPrerelease": .from(isPrerelease), + "source": .string(source) + ] + + // Optional fields + if let isSigned { + fields["isSigned"] = .from(isSigned) + } + + if let notes { + fields["notes"] = .string(notes) + } + + if let sourceUpdatedAt { + fields["sourceUpdatedAt"] = .date(sourceUpdatedAt) + } + + return fields + } + + static func from(recordInfo: RecordInfo) -> Self? { + guard let version = recordInfo.fields["version"]?.stringValue, + let buildNumber = recordInfo.fields["buildNumber"]?.stringValue, + let releaseDate = recordInfo.fields["releaseDate"]?.dateValue, + let downloadURL = recordInfo.fields["downloadURL"]?.stringValue, + let fileSize = recordInfo.fields["fileSize"]?.intValue, + let sha256Hash = recordInfo.fields["sha256Hash"]?.stringValue, + let sha1Hash = recordInfo.fields["sha1Hash"]?.stringValue, + let source = recordInfo.fields["source"]?.stringValue + else { + return nil + } + + return RestoreImageRecord( + version: version, + buildNumber: buildNumber, + releaseDate: releaseDate, + downloadURL: downloadURL, + fileSize: fileSize, + sha256Hash: sha256Hash, + sha1Hash: sha1Hash, + isSigned: recordInfo.fields["isSigned"]?.boolValue, + isPrerelease: recordInfo.fields["isPrerelease"]?.boolValue ?? false, + source: source, + notes: recordInfo.fields["notes"]?.stringValue, + sourceUpdatedAt: recordInfo.fields["sourceUpdatedAt"]?.dateValue + ) + } + + static func formatForDisplay(_ recordInfo: RecordInfo) -> String { + let build = recordInfo.fields["buildNumber"]?.stringValue ?? "Unknown" + let signed = recordInfo.fields["isSigned"]?.boolValue ?? false + let prerelease = recordInfo.fields["isPrerelease"]?.boolValue ?? false + let source = recordInfo.fields["source"]?.stringValue ?? "Unknown" + let size = recordInfo.fields["fileSize"]?.intValue ?? 0 + + let signedStr = signed ? "✅ Signed" : "❌ Unsigned" + let prereleaseStr = prerelease ? "[Beta/RC]" : "" + let sizeStr = formatFileSize(size) + + var output = " \(build) \(prereleaseStr)\n" + output += " \(signedStr) | Size: \(sizeStr) | Source: \(source)" + return output + } + + private static func formatFileSize(_ bytes: Int) -> String { + let gb = Double(bytes) / 1_000_000_000 + if gb >= 1.0 { + return String(format: "%.2f GB", gb) + } else { + let mb = Double(bytes) / 1_000_000 + return String(format: "%.0f MB", mb) + } + } +} diff --git a/Examples/Bushel/Sources/BushelImages/Models/SwiftVersionRecord.swift b/Examples/Bushel/Sources/BushelImages/Models/SwiftVersionRecord.swift new file mode 100644 index 00000000..81c8ee92 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/Models/SwiftVersionRecord.swift @@ -0,0 +1,84 @@ +import Foundation +import MistKit + +/// Represents a Swift compiler release bundled with Xcode +struct SwiftVersionRecord: Codable, Sendable { + /// Swift version (e.g., "5.9", "5.10", "6.0") + var version: String + + /// Release date + var releaseDate: Date + + /// Optional swift.org toolchain download + var downloadURL: String? + + /// Beta/snapshot indicator + var isPrerelease: Bool + + /// Release notes + var notes: String? + + /// CloudKit record name based on version (e.g., "SwiftVersion-5.9.2") + var recordName: String { + "SwiftVersion-\(version)" + } +} + +// MARK: - CloudKitRecord Conformance + +extension SwiftVersionRecord: CloudKitRecord { + static var cloudKitRecordType: String { "SwiftVersion" } + + func toCloudKitFields() -> [String: FieldValue] { + var fields: [String: FieldValue] = [ + "version": .string(version), + "releaseDate": .date(releaseDate), + "isPrerelease": .from(isPrerelease) + ] + + // Optional fields + if let downloadURL { + fields["downloadURL"] = .string(downloadURL) + } + + if let notes { + fields["notes"] = .string(notes) + } + + return fields + } + + static func from(recordInfo: RecordInfo) -> Self? { + guard let version = recordInfo.fields["version"]?.stringValue, + let releaseDate = recordInfo.fields["releaseDate"]?.dateValue + else { + return nil + } + + return SwiftVersionRecord( + version: version, + releaseDate: releaseDate, + downloadURL: recordInfo.fields["downloadURL"]?.stringValue, + isPrerelease: recordInfo.fields["isPrerelease"]?.boolValue ?? false, + notes: recordInfo.fields["notes"]?.stringValue + ) + } + + static func formatForDisplay(_ recordInfo: RecordInfo) -> String { + let version = recordInfo.fields["version"]?.stringValue ?? "Unknown" + let releaseDate = recordInfo.fields["releaseDate"]?.dateValue + + let dateStr = releaseDate.map { formatDate($0) } ?? "Unknown" + + var output = "\n Swift \(version)\n" + output += " Released: \(dateStr)" + return output + } + + private static func formatDate(_ date: Date) -> String { + let formatter = DateFormatter() + formatter.dateStyle = .medium + formatter.timeStyle = .none + return formatter.string(from: date) + } +} diff --git a/Examples/Bushel/Sources/BushelImages/Models/XcodeVersionRecord.swift b/Examples/Bushel/Sources/BushelImages/Models/XcodeVersionRecord.swift new file mode 100644 index 00000000..a09b07e7 --- /dev/null +++ b/Examples/Bushel/Sources/BushelImages/Models/XcodeVersionRecord.swift @@ -0,0 +1,141 @@ +import Foundation +import MistKit + +/// Represents an Xcode release with macOS requirements and bundled Swift version +struct XcodeVersionRecord: Codable, Sendable { + /// Xcode version (e.g., "15.1", "15.2 Beta 3") + var version: String + + /// Build identifier (e.g., "15C65") + var buildNumber: String + + /// Release date + var releaseDate: Date + + /// Optional developer.apple.com download link + var downloadURL: String? + + /// Download size in bytes + var fileSize: Int? + + /// Beta/RC indicator + var isPrerelease: Bool + + /// Reference to minimum RestoreImage record required (recordName) + var minimumMacOS: String? + + /// Reference to bundled Swift compiler (recordName) + var includedSwiftVersion: String? + + /// JSON of SDK versions: {"macOS": "14.2", "iOS": "17.2", "watchOS": "10.2"} + var sdkVersions: String? + + /// Release notes or additional info + var notes: String? + + /// CloudKit record name based on build number (e.g., "XcodeVersion-15C65") + var recordName: String { + "XcodeVersion-\(buildNumber)" + } +} + +// MARK: - CloudKitRecord Conformance + +extension XcodeVersionRecord: CloudKitRecord { + static var cloudKitRecordType: String { "XcodeVersion" } + + func toCloudKitFields() -> [String: FieldValue] { + var fields: [String: FieldValue] = [ + "version": .string(version), + "buildNumber": .string(buildNumber), + "releaseDate": .date(releaseDate), + "isPrerelease": FieldValue(booleanValue: isPrerelease) + ] + + // Optional fields + if let downloadURL { + fields["downloadURL"] = .string(downloadURL) + } + + if let fileSize { + fields["fileSize"] = .int64(fileSize) + } + + if let minimumMacOS { + fields["minimumMacOS"] = .reference(FieldValue.Reference( + recordName: minimumMacOS, + action: nil + )) + } + + if let includedSwiftVersion { + fields["includedSwiftVersion"] = .reference(FieldValue.Reference( + recordName: includedSwiftVersion, + action: nil + )) + } + + if let sdkVersions { + fields["sdkVersions"] = .string(sdkVersions) + } + + if let notes { + fields["notes"] = .string(notes) + } + + return fields + } + + static func from(recordInfo: RecordInfo) -> Self? { + guard let version = recordInfo.fields["version"]?.stringValue, + let buildNumber = recordInfo.fields["buildNumber"]?.stringValue, + let releaseDate = recordInfo.fields["releaseDate"]?.dateValue + else { + return nil + } + + return XcodeVersionRecord( + version: version, + buildNumber: buildNumber, + releaseDate: releaseDate, + downloadURL: recordInfo.fields["downloadURL"]?.stringValue, + fileSize: recordInfo.fields["fileSize"]?.intValue, + isPrerelease: recordInfo.fields["isPrerelease"]?.boolValue ?? false, + minimumMacOS: recordInfo.fields["minimumMacOS"]?.referenceValue?.recordName, + includedSwiftVersion: recordInfo.fields["includedSwiftVersion"]?.referenceValue?.recordName, + sdkVersions: recordInfo.fields["sdkVersions"]?.stringValue, + notes: recordInfo.fields["notes"]?.stringValue + ) + } + + static func formatForDisplay(_ recordInfo: RecordInfo) -> String { + let version = recordInfo.fields["version"]?.stringValue ?? "Unknown" + let build = recordInfo.fields["buildNumber"]?.stringValue ?? "Unknown" + let releaseDate = recordInfo.fields["releaseDate"]?.dateValue + let size = recordInfo.fields["fileSize"]?.intValue ?? 0 + + let dateStr = releaseDate.map { formatDate($0) } ?? "Unknown" + let sizeStr = formatFileSize(size) + + var output = "\n \(version) (Build \(build))\n" + output += " Released: \(dateStr) | Size: \(sizeStr)" + return output + } + + private static func formatDate(_ date: Date) -> String { + let formatter = DateFormatter() + formatter.dateStyle = .medium + formatter.timeStyle = .none + return formatter.string(from: date) + } + + private static func formatFileSize(_ bytes: Int) -> String { + let gb = Double(bytes) / 1_000_000_000 + if gb >= 1.0 { + return String(format: "%.2f GB", gb) + } else { + let mb = Double(bytes) / 1_000_000 + return String(format: "%.0f MB", mb) + } + } +} diff --git a/Examples/Bushel/XCODE_SCHEME_SETUP.md b/Examples/Bushel/XCODE_SCHEME_SETUP.md new file mode 100644 index 00000000..71b1dd0e --- /dev/null +++ b/Examples/Bushel/XCODE_SCHEME_SETUP.md @@ -0,0 +1,258 @@ +# Xcode Scheme Setup for Bushel Demo + +This guide explains how to set up the Xcode scheme to run and debug the `bushel-images` CLI tool. + +## Opening the Package in Xcode + +1. Open Xcode +2. Go to **File > Open...** +3. Navigate to `/Users/leo/Documents/Projects/MistKit/Examples/Bushel/` +4. Select `Package.swift` and click **Open** + +Alternatively, from Terminal: +```bash +cd /Users/leo/Documents/Projects/MistKit/Examples/Bushel +open Package.swift +``` + +## Creating/Editing the Scheme + +### 1. Open Scheme Editor + +- Click the scheme selector in the toolbar (next to the Run/Stop buttons) +- Select **bushel-images** if it exists, or create a new scheme +- Click **Edit Scheme...** (or press `Cmd+Shift+,`) + +### 2. Configure Run Settings + +In the Scheme Editor, select **Run** in the left sidebar. + +#### Info Tab +- **Executable**: Select `bushel-images` +- **Build Configuration**: Debug +- **Debugger**: LLDB + +#### Arguments Tab + +**Environment Variables**: +Add the following environment variables: + +| Name | Value | Description | +|------|-------|-------------| +| `CLOUDKIT_CONTAINER_ID` | `iCloud.com.yourcompany.Bushel` | Your CloudKit container identifier | +| `CLOUDKIT_API_TOKEN` | `your-api-token-here` | Your CloudKit API token | + +**Arguments Passed On Launch**: +Add command-line arguments for testing different commands: + +For sync command: +``` +sync --container-id $(CLOUDKIT_CONTAINER_ID) --api-token $(CLOUDKIT_API_TOKEN) +``` + +For export command: +``` +export --container-id $(CLOUDKIT_CONTAINER_ID) --api-token $(CLOUDKIT_API_TOKEN) --output ./export.json +``` + +For help: +``` +--help +``` + +#### Options Tab +- **Working Directory**: + - Select **Use custom working directory** + - Set to: `/Users/leo/Documents/Projects/MistKit/Examples/Bushel` + +### 3. Configure Build Settings (Optional) + +In the Scheme Editor, select **Build** in the left sidebar: + +- Ensure `bushel-images` target is checked for **Run** +- Optionally check **Test** if you add tests later +- Ensure `MistKit` is listed as a dependency (should be automatic) + +## Getting CloudKit Credentials + +### CloudKit Container Identifier + +1. Open [CloudKit Dashboard](https://icloud.developer.apple.com/) +2. Sign in with your Apple Developer account +3. Select or create a container +4. The identifier format is: `iCloud.com.yourcompany.YourApp` + +### CloudKit API Token + +#### Option 1: API Token (Recommended for Development) + +1. In CloudKit Dashboard, select your container +2. Go to **API Access** tab +3. Click **API Tokens** +4. Click **Add API Token** +5. Give it a name (e.g., "Bushel Development") +6. Copy the token value + +#### Option 2: Server-to-Server Authentication (Production) + +For production use, you'll need: +- Key ID +- Private key file (.pem) +- Server-to-Server key authentication + +See MistKit documentation for server-to-server setup. + +## Environment Variables File (Alternative) + +Instead of adding environment variables to the scheme, you can create a `.env` file: + +```bash +# Create .env file in Bushel directory +cat > .env << 'EOF' +CLOUDKIT_CONTAINER_ID=iCloud.com.yourcompany.Bushel +CLOUDKIT_API_TOKEN=your-api-token-here +EOF + +# Don't commit this file! +echo ".env" >> .gitignore +``` + +Then modify the scheme to load environment from file (requires additional code). + +## Running the CLI + +### From Xcode + +1. Select the `bushel-images` scheme +2. Press `Cmd+R` to run +3. View output in the Console pane (bottom of Xcode) + +### From Terminal + +After building in Xcode, you can also run from Terminal: + +```bash +# Navigate to build products +cd /Users/leo/Documents/Projects/MistKit/Examples/Bushel/.build/arm64-apple-macosx/debug + +# Run with arguments +./bushel-images sync \ + --container-id "iCloud.com.yourcompany.Bushel" \ + --api-token "your-api-token-here" + +# Or set environment variables +export CLOUDKIT_CONTAINER_ID="iCloud.com.yourcompany.Bushel" +export CLOUDKIT_API_TOKEN="your-api-token-here" +./bushel-images sync --container-id $CLOUDKIT_CONTAINER_ID --api-token $CLOUDKIT_API_TOKEN +``` + +## Debugging Tips + +### Breakpoints + +1. Open relevant source files (e.g., `BushelCloudKitService.swift`) +2. Click in the gutter to set breakpoints +3. Run with `Cmd+R` +4. Execution will pause at breakpoints + +### Console Output + +The CLI uses `print()` statements to show progress: +- "Fetching X from Y..." +- "Syncing N record(s) in M batch(es)..." +- "✅ Synced N records" + +### Common Issues + +**Issue**: "Cannot find container" +- **Solution**: Verify container ID is correct in CloudKit Dashboard + +**Issue**: "Authentication failed" +- **Solution**: Check API token is valid and has correct permissions + +**Issue**: "Cannot find type 'RecordOperation'" +- **Solution**: Clean build folder (`Cmd+Shift+K`) and rebuild + +**Issue**: Module 'MistKit' not found +- **Solution**: Ensure MistKit is built first (should be automatic via dependencies) + +## Testing Without Real CloudKit + +To test the data fetching without CloudKit: + +1. Comment out the CloudKit sync calls in `SyncCommand.swift` +2. Add export of fetched data: + ```swift + // In SyncCommand.run() + let (restoreImages, xcodeVersions, swiftVersions) = try await engine.fetchAllData() + print("Fetched:") + print(" - \(restoreImages.count) restore images") + print(" - \(xcodeVersions.count) Xcode versions") + print(" - \(swiftVersions.count) Swift versions") + ``` + +## CloudKit Schema Setup + +Before running sync, ensure your CloudKit schema has the required record types: + +### RestoreImage Record Type +- `version` (String) +- `buildNumber` (String) +- `releaseDate` (Date/Time) +- `downloadURL` (String) +- `fileSize` (Int64) +- `sha256Hash` (String) +- `sha1Hash` (String) +- `isSigned` (Boolean) +- `isPrerelease` (Boolean) +- `source` (String) +- `notes` (String, optional) + +### XcodeVersion Record Type +- `version` (String) +- `buildNumber` (String) +- `releaseDate` (Date/Time) +- `isPrerelease` (Boolean) +- `downloadURL` (String, optional) +- `fileSize` (Int64, optional) +- `minimumMacOS` (Reference to RestoreImage, optional) +- `includedSwiftVersion` (Reference to SwiftVersion, optional) +- `sdkVersions` (String, optional) +- `notes` (String, optional) + +### SwiftVersion Record Type +- `version` (String) +- `releaseDate` (Date/Time) +- `isPrerelease` (Boolean) +- `downloadURL` (String, optional) +- `notes` (String, optional) + +You can create these schemas in CloudKit Dashboard > Schema section. + +## Next Steps + +1. Set up CloudKit container and get credentials +2. Configure the Xcode scheme with your credentials +3. Run the CLI to test data fetching (comment out CloudKit sync first) +4. Create CloudKit schema (record types) +5. Run full sync to populate CloudKit + +## Troubleshooting + +### Getting More Verbose Output + +Add `--verbose` flag support to commands if needed, or temporarily add debug prints: + +```swift +// In BushelCloudKitService.swift +print("DEBUG: Syncing batch with operations: \(batch.map { $0.recordName })") +``` + +### Viewing Network Requests + +Add logging middleware to MistKit (already configured) by setting environment variable: +``` +MISTKIT_DEBUG_LOGGING=1 +``` + +This will print all HTTP requests/responses to console. diff --git a/Examples/Bushel/schema.ckdb b/Examples/Bushel/schema.ckdb new file mode 100644 index 00000000..8f64548f --- /dev/null +++ b/Examples/Bushel/schema.ckdb @@ -0,0 +1,66 @@ +DEFINE SCHEMA + +RECORD TYPE RestoreImage ( + "___recordID" REFERENCE QUERYABLE, + "version" STRING QUERYABLE SORTABLE SEARCHABLE, + "buildNumber" STRING QUERYABLE SORTABLE, + "releaseDate" TIMESTAMP QUERYABLE SORTABLE, + "downloadURL" STRING, + "fileSize" INT64, + "sha256Hash" STRING, + "sha1Hash" STRING, + "isSigned" INT64 QUERYABLE, + "isPrerelease" INT64 QUERYABLE, + "source" STRING, + "notes" STRING, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); + +RECORD TYPE XcodeVersion ( + "___recordID" REFERENCE QUERYABLE, + "version" STRING QUERYABLE SORTABLE SEARCHABLE, + "buildNumber" STRING QUERYABLE SORTABLE, + "releaseDate" TIMESTAMP QUERYABLE SORTABLE, + "isPrerelease" INT64 QUERYABLE, + "downloadURL" STRING, + "fileSize" INT64, + "minimumMacOS" REFERENCE, + "includedSwiftVersion" REFERENCE, + "sdkVersions" STRING, + "notes" STRING, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); + +RECORD TYPE SwiftVersion ( + "___recordID" REFERENCE QUERYABLE, + "version" STRING QUERYABLE SORTABLE SEARCHABLE, + "releaseDate" TIMESTAMP QUERYABLE SORTABLE, + "isPrerelease" INT64 QUERYABLE, + "downloadURL" STRING, + "notes" STRING, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); + +RECORD TYPE DataSourceMetadata ( + "___recordID" REFERENCE QUERYABLE, + "sourceName" STRING QUERYABLE SORTABLE, + "recordTypeName" STRING QUERYABLE, + "lastFetchedAt" TIMESTAMP QUERYABLE SORTABLE, + "sourceUpdatedAt" TIMESTAMP QUERYABLE SORTABLE, + "recordCount" INT64, + "fetchDurationSeconds" DOUBLE, + "lastError" STRING, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); diff --git a/Examples/Celestra/.env.example b/Examples/Celestra/.env.example new file mode 100644 index 00000000..0ffebfc5 --- /dev/null +++ b/Examples/Celestra/.env.example @@ -0,0 +1,14 @@ +# CloudKit Configuration +# Copy this file to .env and fill in your values + +# Your CloudKit container ID (e.g., iCloud.com.brightdigit.Celestra) +CLOUDKIT_CONTAINER_ID=iCloud.com.brightdigit.Celestra + +# Your CloudKit server-to-server key ID from Apple Developer Console +CLOUDKIT_KEY_ID=your-key-id-here + +# Path to your CloudKit private key PEM file +CLOUDKIT_PRIVATE_KEY_PATH=/path/to/eckey.pem + +# CloudKit environment: development or production +CLOUDKIT_ENVIRONMENT=development diff --git a/Examples/Celestra/AI_SCHEMA_WORKFLOW.md b/Examples/Celestra/AI_SCHEMA_WORKFLOW.md new file mode 100644 index 00000000..70afc825 --- /dev/null +++ b/Examples/Celestra/AI_SCHEMA_WORKFLOW.md @@ -0,0 +1,1068 @@ +# AI Agent CloudKit Schema Workflow Guide + +**Audience:** Claude Code, AI agents, and developers working with text-based CloudKit schemas in MistKit projects. + +**Purpose:** Comprehensive guide for understanding, designing, modifying, and validating CloudKit schemas using text-based `.ckdb` files and command-line tools. + +--- + +## Table of Contents + +1. [Understanding .ckdb Files](#understanding-ckdb-files) +2. [Schema Design Decision Framework](#schema-design-decision-framework) +3. [Modifying Schemas with Text Tools](#modifying-schemas-with-text-tools) +4. [Validation and Testing](#validation-and-testing) +5. [Swift Code Generation](#swift-code-generation) +6. [Common Patterns and Examples](#common-patterns-and-examples) + +--- + +## Understanding .ckdb Files + +### What is a `.ckdb` File? + +A `.ckdb` file is a text-based representation of a CloudKit database schema using the CloudKit Schema Language. It's version-controlled alongside your code and serves as the source of truth for your database structure. + +### Basic Structure + +Every schema file follows this pattern: + +``` +DEFINE SCHEMA + +[Optional: CREATE ROLE statements] + +RECORD TYPE TypeName ( + field-name data-type [options], + ... + GRANT permissions TO roles +); + +[More RECORD TYPE definitions] +``` + +### Reading the Celestra Schema + +Let's analyze the Celestra RSS reader schema line by line: + +**File:** `Examples/Celestra/schema.ckdb` + +``` +DEFINE SCHEMA +``` +**Analysis:** Every schema starts with `DEFINE SCHEMA`. This is required. + +``` +RECORD TYPE Feed ( + "___recordID" REFERENCE QUERYABLE, +``` +**Analysis:** +- `Feed` is the record type name (analogous to a database table) +- `"___recordID"` is a system field (always present, triple underscore) +- Declared explicitly to add `QUERYABLE` index for efficient lookups +- Type is `REFERENCE` (represents a unique record identifier) + +``` + "feedURL" STRING QUERYABLE SORTABLE, +``` +**Analysis:** +- User-defined field storing the RSS feed URL +- Type `STRING` for text data +- `QUERYABLE` - Can filter by exact URL: `feedURL == "https://..."` +- `SORTABLE` - Can sort alphabetically or use range queries +- This is likely a unique identifier, so both indexes make sense + +``` + "title" STRING SEARCHABLE, +``` +**Analysis:** +- Feed title/name +- `SEARCHABLE` enables full-text search: `title CONTAINS "Tech"` +- No `QUERYABLE` because we don't need exact title matching +- Perfect for user search features + +``` + "description" STRING, +``` +**Analysis:** +- Feed description, no indexes +- Used only for display, never queried +- No indexes = lower storage cost, faster writes + +``` + "totalAttempts" INT64, + "successfulAttempts" INT64, +``` +**Analysis:** +- Metrics fields, no indexes needed +- `INT64` for integer counters +- Not queried, just displayed in analytics + +``` + "usageCount" INT64 QUERYABLE SORTABLE, +``` +**Analysis:** +- How many times this feed has been used +- `QUERYABLE SORTABLE` enables: + - Finding feeds by usage: `usageCount > 10` + - Sorting by popularity: `ORDER BY usageCount DESC` + - Use case: "Show top 10 most popular feeds" + +``` + "lastAttempted" TIMESTAMP QUERYABLE SORTABLE, +``` +**Analysis:** +- Last time this feed was fetched +- `TIMESTAMP` stores date/time +- Indexes enable: + - Finding stale feeds: `lastAttempted < date` + - Sorting by freshness: `ORDER BY lastAttempted DESC` + - Use case: "Find feeds not updated in 24 hours" + +``` + "isActive" INT64 QUERYABLE, +``` +**Analysis:** +- Boolean flag (0 = inactive, 1 = active) +- CloudKit doesn't have native boolean, use `INT64` +- `QUERYABLE` enables: `isActive == 1` to find active feeds +- Not `SORTABLE` because sorting boolean doesn't make sense + +``` + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +``` +**Analysis:** +- Standard public database permissions +- `"_creator"` (record owner) - full access +- `"_icloud"` (authenticated users) - can create/edit their own feeds +- `"_world"` (everyone) - can read all feeds (even unauthenticated) +- Public RSS directory pattern + +``` +); +``` + +### Article Record Type Analysis + +``` +RECORD TYPE Article ( + "___recordID" REFERENCE QUERYABLE, + "feed" REFERENCE QUERYABLE, +``` +**Analysis:** +- `feed` field creates a relationship to the Feed record +- Type `REFERENCE` points to another record's `___recordID` +- `QUERYABLE` enables: `feed == feedRecord.recordID` +- This is a foreign key relationship + +``` + "title" STRING SEARCHABLE, + "link" STRING, + "description" STRING, +``` +**Analysis:** +- Article content fields +- Only `title` is searchable (user searches articles by title) +- `link` and `description` are display-only + +``` + "author" STRING QUERYABLE, +``` +**Analysis:** +- Author name as plain string (not reference) +- `QUERYABLE` enables filtering: `author == "John Doe"` +- Use case: "Show all articles by this author" + +``` + "pubDate" TIMESTAMP QUERYABLE SORTABLE, +``` +**Analysis:** +- Article publication date +- Critical field for RSS - most queries sort by date +- Enables: `ORDER BY pubDate DESC` (newest first) +- Also range queries: `pubDate > lastFetchDate` + +``` + "guid" STRING QUERYABLE SORTABLE, +``` +**Analysis:** +- Globally Unique Identifier from RSS feed +- `QUERYABLE` for deduplication: "Does this GUID already exist?" +- `SORTABLE` not strictly needed but allows string range queries +- Prevents duplicate article imports + +``` + "contentHash" STRING QUERYABLE, +``` +**Analysis:** +- Hash of article content for change detection +- `QUERYABLE` to check: "Has this content changed?" +- Use case: Detecting updated articles + +``` + "fetchedAt" TIMESTAMP QUERYABLE SORTABLE, + "expiresAt" TIMESTAMP QUERYABLE SORTABLE, +``` +**Analysis:** +- Caching timestamps +- `fetchedAt` - when we downloaded this article +- `expiresAt` - when to consider it stale +- Both queryable/sortable for cache management queries +- Use case: `expiresAt < now()` to find expired articles + +### Key Observations + +1. **Indexing Strategy:** Only indexed fields that are used in queries +2. **Reference Pattern:** `Article.feed → Feed.___recordID` creates relationship +3. **Boolean Pattern:** Use `INT64` with 0/1 values +4. **Timestamp Pattern:** Track creation, updates, and expiration +5. **Search Pattern:** `SEARCHABLE` on user-facing text fields +6. **Permission Pattern:** Standard public database grants + +--- + +## Schema Design Decision Framework + +### Field Type Selection + +Use this decision tree when choosing data types: + +``` +Is it a relationship to another record? +├─ Yes → REFERENCE +└─ No ↓ + +Is it binary data or a file? +├─ Yes → ASSET (files) or BYTES (small binary data) +└─ No ↓ + +Is it text? +├─ Yes → STRING +└─ No ↓ + +Is it a date/time? +├─ Yes → TIMESTAMP +└─ No ↓ + +Is it a geographic location? +├─ Yes → LOCATION +└─ No ↓ + +Is it a number? +├─ Integer → INT64 +├─ Decimal → DOUBLE +└─ Boolean → INT64 (use 0/1) + +Do you need multiple values? +└─ Yes → LIST +``` + +### Indexing Strategy Decision Framework + +For each field, ask: + +#### Should it be QUERYABLE? + +``` +Will you filter records by this field's exact value? +Examples: + - feedURL == "https://example.com/rss" + - isActive == 1 + - guid == "article-123" + - feed == feedRecord.recordID + +Answer YES → Add QUERYABLE +Answer NO → Skip indexing +``` + +**Cost:** Increases storage ~10-20%, slower writes +**Benefit:** Fast equality lookups, required for filtering + +#### Should it be SORTABLE? + +``` +Will you sort records by this field? +OR +Will you use range queries on this field? + +Examples: + - ORDER BY pubDate DESC + - lastAttempted < date + - usageCount > 10 + - pubDate BETWEEN startDate AND endDate + +Answer YES → Add SORTABLE +Answer NO → Skip +``` + +**Cost:** Increases storage ~15-25%, slower writes +**Benefit:** Fast sorting and range queries + +**Note:** `SORTABLE` implies `QUERYABLE` functionality + +#### Should it be SEARCHABLE? + +``` +Is this a text field that users will search within? +(Full-text search, not exact matching) + +Examples: + - title CONTAINS "Swift" + - description CONTAINS "tutorial" + - Content search in articles + +Answer YES → Add SEARCHABLE (STRING fields only) +Answer NO → Skip +``` + +**Cost:** Increases storage ~30-50%, tokenization overhead +**Benefit:** Full-text search with word stemming and relevance + +### Common Field Patterns + +#### Unique Identifiers + +``` +"feedURL" STRING QUERYABLE SORTABLE // Natural key +"guid" STRING QUERYABLE SORTABLE // External ID +"email" STRING QUERYABLE // User email +``` + +**Pattern:** Always `QUERYABLE`, often `SORTABLE` for range scans + +#### Timestamps + +``` +"createdAt" TIMESTAMP QUERYABLE SORTABLE // When created +"updatedAt" TIMESTAMP QUERYABLE SORTABLE // Last modified +"publishedAt" TIMESTAMP QUERYABLE SORTABLE // Publication time +"expiresAt" TIMESTAMP QUERYABLE SORTABLE // Expiration time +``` + +**Pattern:** Almost always both `QUERYABLE` and `SORTABLE` + +#### Boolean Flags + +``` +"isActive" INT64 QUERYABLE // 0 or 1 +"isPublished" INT64 QUERYABLE // 0 or 1 +"isDeleted" INT64 QUERYABLE // Soft delete flag +``` + +**Pattern:** `QUERYABLE` only, never `SORTABLE` (meaningless to sort booleans) + +#### Counters and Metrics + +``` +"viewCount" INT64 QUERYABLE SORTABLE // Sortable for "top N" +"likeCount" INT64 QUERYABLE SORTABLE // Sortable for popularity +"attempts" INT64 // Display only +``` + +**Pattern:** Index only if used in ranking/filtering + +#### Text Content + +``` +"title" STRING SEARCHABLE // User searches +"name" STRING SEARCHABLE // User searches +"description" STRING // Display only +"notes" STRING // Display only +"body" STRING SEARCHABLE // Full text search +``` + +**Pattern:** `SEARCHABLE` for user-facing search, nothing for display-only + +#### References (Foreign Keys) + +``` +"feed" REFERENCE QUERYABLE // Parent relationship +"author" REFERENCE QUERYABLE // User reference +"category" REFERENCE QUERYABLE // Category reference +``` + +**Pattern:** Always `QUERYABLE` to filter by relationship + +#### Lists + +``` +"tags" LIST // Multiple tags (display) +"imageURLs" LIST // Multiple URLs +"attachments" LIST // Multiple files +"relatedFeeds" LIST QUERYABLE // References (queryable) +``` + +**Pattern:** Rarely indexed unless specific query needs + +### Permission Strategy + +#### Public Database (Celestra Pattern) + +``` +GRANT READ, CREATE, WRITE TO "_creator" // Owner has full control +GRANT READ, CREATE, WRITE TO "_icloud" // Users can create their own +GRANT READ TO "_world" // Public read access +``` + +**Use case:** Public data sharing, RSS directories, blogs + +#### Private Database Pattern + +``` +GRANT READ, CREATE, WRITE TO "_creator" // Only owner can access +``` + +**Use case:** Personal data, user preferences, private content + +#### Shared Database Pattern + +``` +CREATE ROLE Editor; + +GRANT READ, WRITE TO "_creator" // Owner can read/write +GRANT READ TO Editor // Editors can read +GRANT READ TO "_icloud" // Participants can read +``` + +**Use case:** Collaborative documents, shared projects + +#### Admin-Only Pattern + +``` +CREATE ROLE Admin; + +GRANT READ, CREATE, WRITE TO Admin // Only admins +GRANT READ TO "_icloud" // Users can read +``` + +**Use case:** Configuration data, system settings + +--- + +## Modifying Schemas with Text Tools + +### Adding a New Field + +**Scenario:** Add a `lastError` field to track fetch failures + +```diff +RECORD TYPE Feed ( + "___recordID" REFERENCE QUERYABLE, + "feedURL" STRING QUERYABLE SORTABLE, + "title" STRING SEARCHABLE, + "description" STRING, ++ "lastError" STRING, + "totalAttempts" INT64, + ... +); +``` + +**Steps:** +1. Open `schema.ckdb` in text editor +2. Add field in appropriate location (group related fields) +3. Choose type (`STRING` for error messages) +4. Decide on indexing (none needed for error display) +5. Save file +6. Validate (see [Validation](#validation-and-testing)) + +### Adding an Index to Existing Field + +**Scenario:** Make `author` sortable for "sort by author" feature + +```diff +RECORD TYPE Article ( + "___recordID" REFERENCE QUERYABLE, + "feed" REFERENCE QUERYABLE, + "title" STRING SEARCHABLE, + "link" STRING, + "description" STRING, +- "author" STRING QUERYABLE, ++ "author" STRING QUERYABLE SORTABLE, + ... +); +``` + +**Impact:** Safe addition, no data loss + +### Adding a New Record Type + +**Scenario:** Add `Category` record type for feed categorization + +```diff +DEFINE SCHEMA + +RECORD TYPE Feed ( + ... +); + +RECORD TYPE Article ( + ... +); + ++RECORD TYPE Category ( ++ "___recordID" REFERENCE QUERYABLE, ++ "name" STRING QUERYABLE SORTABLE, ++ "description" STRING, ++ "iconURL" STRING, ++ "sortOrder" INT64 QUERYABLE SORTABLE, ++ ++ GRANT READ, CREATE, WRITE TO "_creator", ++ GRANT READ, CREATE, WRITE TO "_icloud", ++ GRANT READ TO "_world" ++); +``` + +**Impact:** Safe addition, no effect on existing data + +### Adding a Reference Field + +**Scenario:** Add `category` field to `Feed` to link feeds to categories + +```diff +RECORD TYPE Feed ( + "___recordID" REFERENCE QUERYABLE, ++ "category" REFERENCE QUERYABLE, + "feedURL" STRING QUERYABLE SORTABLE, + ... +); +``` + +**Considerations:** +- Existing `Feed` records will have `NULL` category +- Update application code to handle optional references +- Set default category for existing records via code + +### Modifying Permissions + +**Scenario:** Add a Moderator role with special permissions + +```diff +DEFINE SCHEMA + ++CREATE ROLE Moderator; + +RECORD TYPE Feed ( + "___recordID" REFERENCE QUERYABLE, + ... + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", ++ GRANT READ, WRITE TO Moderator, + GRANT READ TO "_world" +); +``` + +**Impact:** Safe change, modifies access control only + +### What You CANNOT Do + +#### ❌ Remove Fields (Production) + +```diff +RECORD TYPE Feed ( + "___recordID" REFERENCE QUERYABLE, + "feedURL" STRING QUERYABLE SORTABLE, +- "oldField" STRING, // ❌ Error: Data loss in production + ... +); +``` + +**Error:** CloudKit rejects schema changes that cause data loss in production + +**Workaround:** Deprecate field by removing it from code but leaving in schema + +#### ❌ Change Field Types + +```diff +RECORD TYPE Feed ( +- "usageCount" INT64 QUERYABLE SORTABLE, ++ "usageCount" DOUBLE QUERYABLE SORTABLE, // ❌ Error: Cannot change type + ... +); +``` + +**Error:** Type changes are never allowed + +**Workaround:** Add new field, migrate data, deprecate old field + +#### ❌ Rename Fields + +```diff +RECORD TYPE Feed ( +- "feedURL" STRING QUERYABLE SORTABLE, ++ "url" STRING QUERYABLE SORTABLE, // ❌ This is remove + add + ... +); +``` + +**Error:** Renaming = removing old field + adding new field (data loss) + +**Workaround:** Add new field, copy data via code, keep old field in schema + +--- + +## Validation and Testing + +### Step 1: Syntax Validation + +Validate schema file syntax before attempting import: + +```bash +cktool validate-schema schema.ckdb +``` + +**Expected output (success):** +``` +Schema validation successful +``` + +**Example error:** +``` +Error: Line 15: Unexpected token 'QUERYABL' (typo) +Expected: QUERYABLE, SORTABLE, SEARCHABLE, or field separator +``` + +### Step 2: Environment Setup + +Set required environment variables: + +```bash +export CLOUDKIT_CONTAINER_ID="iCloud.com.yourcompany.app" +export CLOUDKIT_ENVIRONMENT="development" # or "production" +export CLOUDKIT_MANAGEMENT_TOKEN="your_management_token_here" +``` + +**Get Management Token:** +1. Go to CloudKit Dashboard (https://icloud.developer.apple.com/dashboard) +2. Select your container +3. Go to "API Tokens" section +4. Click "CloudKit API Token" → Create management token +5. Copy token (starts with long alphanumeric string) + +### Step 3: Import to Development + +Always test in development environment first: + +```bash +# Ensure development environment +export CLOUDKIT_ENVIRONMENT="development" + +# Import schema +cktool import-schema schema.ckdb +``` + +**Expected output (success):** +``` +Importing schema to container: iCloud.com.yourcompany.app +Environment: development +✓ Schema imported successfully +``` + +**Example error (data loss):** +``` +Error: Cannot remove field 'oldField' from record type 'Feed' +This would result in data loss in existing records +Schema import aborted +``` + +### Step 4: Verify Schema in Dashboard + +1. Open CloudKit Dashboard +2. Select your container +3. Select "Development" environment +4. Go to "Schema" → "Record Types" +5. Verify your changes appear correctly + +### Step 5: Test with Real Data + +Create test records using cktool or MistKit: + +```swift +// Test creating a record with new schema +let feed = Feed() +feed.feedURL = "https://example.com/rss" +feed.title = "Test Feed" +feed.category = categoryReference // New field + +try await mistKit.save(feed) +``` + +### Validation Checklist + +- [ ] Syntax validation passes (`cktool validate-schema`) +- [ ] Environment variables are set correctly +- [ ] Import to development succeeds +- [ ] Schema appears correctly in dashboard +- [ ] Can create new records with new fields +- [ ] Can query using new indexes +- [ ] Existing data still accessible +- [ ] No unexpected errors in logs +- [ ] Swift code compiles with new schema +- [ ] Tests pass with new schema + +### Common Validation Errors + +#### Error: Invalid field type + +``` +Error: Unknown data type 'BOOLEAN' +``` + +**Fix:** Use `INT64` instead of `BOOLEAN` + +#### Error: Invalid index option + +``` +Error: SEARCHABLE option not allowed on INT64 fields +``` + +**Fix:** `SEARCHABLE` only works with `STRING` fields + +#### Error: Missing permission grant + +``` +Warning: Record type 'Feed' has no permission grants +Records will be inaccessible +``` + +**Fix:** Add at least one `GRANT` statement + +#### Error: Invalid identifier + +``` +Error: Identifier 'feed-url' contains invalid character '-' +``` + +**Fix:** Use underscores: `feed_url` or camelCase: `feedURL` + +#### Error: Missing quotes on system field + +``` +Error: Unexpected token '___recordID' +``` + +**Fix:** Add double quotes: `"___recordID"` + +--- + +## Swift Code Generation + +### Mapping Schema to Swift Models + +CloudKit schema fields map to Swift properties with type conversions: + +#### Basic Type Mapping + +```swift +// Schema → Swift + +// STRING → String +"title" STRING +var title: String + +// INT64 → Int64 or Bool +"usageCount" INT64 +var usageCount: Int64 + +"isActive" INT64 // Boolean pattern +var isActive: Bool // Convert in code (0 = false, 1 = true) + +// DOUBLE → Double +"rating" DOUBLE +var rating: Double + +// TIMESTAMP → Date +"pubDate" TIMESTAMP +var pubDate: Date + +// REFERENCE → CKRecord.Reference +"feed" REFERENCE +var feed: CKRecord.Reference + +// ASSET → CKAsset +"image" ASSET +var image: CKAsset + +// LOCATION → CLLocation +"location" LOCATION +var location: CLLocation + +// BYTES → Data +"data" BYTES +var data: Data + +// LIST → [T] +"tags" LIST +var tags: [String] + +"attachments" LIST +var attachments: [CKAsset] +``` + +### Celestra Swift Model Example + +```swift +import Foundation +import CloudKit + +struct Feed: Codable, Sendable { + // System fields (optional to include in model) + var recordID: CKRecord.ID? + var createdAt: Date? + var modifiedAt: Date? + + // Schema fields + var feedURL: String + var title: String + var description: String? + var totalAttempts: Int64 + var successfulAttempts: Int64 + var usageCount: Int64 + var lastAttempted: Date? + var isActive: Bool // Stored as INT64 in CloudKit + + // Computed property for recordName + var recordName: String? { + recordID?.recordName + } +} + +// Extension for CloudKit conversion +extension Feed { + init(record: CKRecord) throws { + self.recordID = record.recordID + self.createdAt = record.creationDate + self.modifiedAt = record.modificationDate + + guard let feedURL = record["feedURL"] as? String else { + throw ConversionError.missingRequiredField("feedURL") + } + self.feedURL = feedURL + + guard let title = record["title"] as? String else { + throw ConversionError.missingRequiredField("title") + } + self.title = title + + self.description = record["description"] as? String + self.totalAttempts = record["totalAttempts"] as? Int64 ?? 0 + self.successfulAttempts = record["successfulAttempts"] as? Int64 ?? 0 + self.usageCount = record["usageCount"] as? Int64 ?? 0 + self.lastAttempted = record["lastAttempted"] as? Date + + // Convert INT64 (0/1) to Bool + let isActiveInt = record["isActive"] as? Int64 ?? 1 + self.isActive = isActiveInt == 1 + } + + func toCKRecord() -> CKRecord { + let record = recordID.map { CKRecord(recordType: "Feed", recordID: $0) } + ?? CKRecord(recordType: "Feed") + + record["feedURL"] = feedURL as CKRecordValue + record["title"] = title as CKRecordValue + record["description"] = description as CKRecordValue? + record["totalAttempts"] = totalAttempts as CKRecordValue + record["successfulAttempts"] = successfulAttempts as CKRecordValue + record["usageCount"] = usageCount as CKRecordValue + record["lastAttempted"] = lastAttempted as CKRecordValue? + + // Convert Bool to INT64 (0/1) + record["isActive"] = (isActive ? 1 : 0) as CKRecordValue + + return record + } +} +``` + +### Article Model with Reference + +```swift +struct Article: Codable, Sendable { + var recordID: CKRecord.ID? + var feed: CKRecord.Reference // Reference to Feed record + var title: String + var link: String? + var description: String? + var author: String? + var pubDate: Date? + var guid: String + var contentHash: String? + var fetchedAt: Date? + var expiresAt: Date? +} + +extension Article { + init(record: CKRecord) throws { + self.recordID = record.recordID + + guard let feed = record["feed"] as? CKRecord.Reference else { + throw ConversionError.missingRequiredField("feed") + } + self.feed = feed + + guard let title = record["title"] as? String else { + throw ConversionError.missingRequiredField("title") + } + self.title = title + + guard let guid = record["guid"] as? String else { + throw ConversionError.missingRequiredField("guid") + } + self.guid = guid + + self.link = record["link"] as? String + self.description = record["description"] as? String + self.author = record["author"] as? String + self.pubDate = record["pubDate"] as? Date + self.contentHash = record["contentHash"] as? String + self.fetchedAt = record["fetchedAt"] as? Date + self.expiresAt = record["expiresAt"] as? Date + } + + func toCKRecord() -> CKRecord { + let record = recordID.map { CKRecord(recordType: "Article", recordID: $0) } + ?? CKRecord(recordType: "Article") + + record["feed"] = feed as CKRecordValue + record["title"] = title as CKRecordValue + record["link"] = link as CKRecordValue? + record["description"] = description as CKRecordValue? + record["author"] = author as CKRecordValue? + record["pubDate"] = pubDate as CKRecordValue? + record["guid"] = guid as CKRecordValue + record["contentHash"] = contentHash as CKRecordValue? + record["fetchedAt"] = fetchedAt as CKRecordValue? + record["expiresAt"] = expiresAt as CKRecordValue? + + return record + } +} +``` + +### Querying with MistKit + +```swift +// Query articles by feed reference +let feedReference = CKRecord.Reference( + recordID: feed.recordID!, + action: .none +) + +let predicate = NSPredicate(format: "feed == %@", feedReference) +let query = CKQuery(recordType: "Article", predicate: predicate) +query.sortDescriptors = [NSSortDescriptor(key: "pubDate", ascending: false)] + +let articles = try await mistKit.performQuery(query) + .map { try Article(record: $0) } + +// Query active feeds +let activePredicate = NSPredicate(format: "isActive == 1") +let activeQuery = CKQuery(recordType: "Feed", predicate: activePredicate) + +let activeFeeds = try await mistKit.performQuery(activeQuery) + .map { try Feed(record: $0) } + +// Full-text search in titles +let searchPredicate = NSPredicate(format: "title CONTAINS[cd] %@", "Swift") +let searchQuery = CKQuery(recordType: "Article", predicate: searchPredicate) + +let searchResults = try await mistKit.performQuery(searchQuery) + .map { try Article(record: $0) } +``` + +--- + +## Common Patterns and Examples + +### Pattern: Timestamped Entities + +``` +RECORD TYPE Post ( + "___recordID" REFERENCE QUERYABLE, + "title" STRING SEARCHABLE, + "content" STRING, + "createdAt" TIMESTAMP QUERYABLE SORTABLE, + "updatedAt" TIMESTAMP QUERYABLE SORTABLE, + "publishedAt" TIMESTAMP QUERYABLE SORTABLE, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ TO "_world" +); +``` + +### Pattern: Soft Delete + +``` +RECORD TYPE Document ( + "___recordID" REFERENCE QUERYABLE, + "title" STRING SEARCHABLE, + "content" STRING, + "isDeleted" INT64 QUERYABLE, // 0 = active, 1 = deleted + "deletedAt" TIMESTAMP QUERYABLE SORTABLE, + + GRANT READ, CREATE, WRITE TO "_creator" +); +``` + +Query for active documents: +```swift +let predicate = NSPredicate(format: "isDeleted == 0") +``` + +### Pattern: Hierarchical Data + +``` +RECORD TYPE Category ( + "___recordID" REFERENCE QUERYABLE, + "name" STRING QUERYABLE SORTABLE, + "parent" REFERENCE QUERYABLE, // Self-reference + "sortOrder" INT64 QUERYABLE SORTABLE, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ TO "_world" +); +``` + +### Pattern: Tagged Content + +``` +RECORD TYPE Article ( + "___recordID" REFERENCE QUERYABLE, + "title" STRING SEARCHABLE, + "content" STRING, + "tags" LIST, // Simple tags + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ TO "_world" +); +``` + +### Pattern: User Profiles + +``` +RECORD TYPE UserProfile ( + "___recordID" REFERENCE QUERYABLE, + "username" STRING QUERYABLE SORTABLE, + "email" STRING QUERYABLE, + "displayName" STRING SEARCHABLE, + "avatarURL" STRING, + "bio" STRING, + "createdAt" TIMESTAMP QUERYABLE SORTABLE, + "lastSeenAt" TIMESTAMP QUERYABLE SORTABLE, + + GRANT READ, WRITE TO "_creator", + GRANT READ TO "_icloud" +); +``` + +--- + +## See Also + +- **Quick Reference:** [.claude/docs/cloudkit-schema-reference.md](../../.claude/docs/cloudkit-schema-reference.md) +- **Setup Guide:** [CLOUDKIT_SCHEMA_SETUP.md](CLOUDKIT_SCHEMA_SETUP.md) +- **Apple Documentation:** [.claude/docs/sosumi-cloudkit-schema-source.md](../../.claude/docs/sosumi-cloudkit-schema-source.md) +- **Celestra README:** [README.md](README.md) +- **Task Master Integration:** [.taskmaster/docs/schema-design-workflow.md](../../.taskmaster/docs/schema-design-workflow.md) diff --git a/Examples/Celestra/BUSHEL_PATTERNS.md b/Examples/Celestra/BUSHEL_PATTERNS.md new file mode 100644 index 00000000..57840e84 --- /dev/null +++ b/Examples/Celestra/BUSHEL_PATTERNS.md @@ -0,0 +1,656 @@ +# Bushel Patterns: CloudKit Integration Reference + +This document captures the CloudKit integration patterns used in the Bushel example project, serving as a reference for understanding MistKit's capabilities and design approaches. + +## Table of Contents + +- [Overview](#overview) +- [CloudKitRecord Protocol Pattern](#cloudkitrecord-protocol-pattern) +- [Schema Design Patterns](#schema-design-patterns) +- [Server-to-Server Authentication](#server-to-server-authentication) +- [Batch Operations](#batch-operations) +- [Relationship Handling](#relationship-handling) +- [Data Pipeline Architecture](#data-pipeline-architecture) +- [Celestra vs Bushel Comparison](#celestra-vs-bushel-comparison) + +## Overview + +Bushel is a production example demonstrating MistKit's CloudKit integration for syncing macOS software version data. It showcases advanced patterns including: + +- Protocol-oriented CloudKit record management +- Complex relationship handling between multiple record types +- Parallel data fetching from multiple sources +- Deduplication strategies +- Comprehensive error handling + +Location: `Examples/Bushel/` + +## CloudKitRecord Protocol Pattern + +### The Protocol + +Bushel uses a protocol-based approach for CloudKit record conversion: + +```swift +protocol CloudKitRecord { + static var cloudKitRecordType: String { get } + var recordName: String { get } + + func toCloudKitFields() -> [String: FieldValue] + static func from(recordInfo: RecordInfo) -> Self? + static func formatForDisplay(_ recordInfo: RecordInfo) -> String +} +``` + +### Implementation Example + +```swift +struct RestoreImageRecord: CloudKitRecord { + static var cloudKitRecordType: String { "RestoreImage" } + + var recordName: String { + "RestoreImage-\(buildNumber)" // Stable, deterministic ID + } + + func toCloudKitFields() -> [String: FieldValue] { + var fields: [String: FieldValue] = [ + "version": .string(version), + "buildNumber": .string(buildNumber), + "releaseDate": .date(releaseDate), + "fileSize": .int64(fileSize), + "isPrerelease": .boolean(isPrerelease) + ] + + // Handle optional fields + if let isSigned { + fields["isSigned"] = .boolean(isSigned) + } + + // Handle relationships + if let minimumMacOSRecordName { + fields["minimumMacOS"] = .reference( + FieldValue.Reference(recordName: minimumMacOSRecordName) + ) + } + + return fields + } + + static func from(recordInfo: RecordInfo) -> Self? { + guard let version = recordInfo.fields["version"]?.stringValue, + let buildNumber = recordInfo.fields["buildNumber"]?.stringValue + else { return nil } + + let releaseDate = recordInfo.fields["releaseDate"]?.dateValue ?? Date() + let fileSize = recordInfo.fields["fileSize"]?.int64Value ?? 0 + + return RestoreImageRecord( + version: version, + buildNumber: buildNumber, + releaseDate: releaseDate, + fileSize: fileSize, + // ... other fields + ) + } +} +``` + +### Benefits + +1. **Type Safety**: Compiler-enforced conversion methods +2. **Reusability**: Generic CloudKit operations work with any `CloudKitRecord` +3. **Testability**: Easy to unit test conversions independently +4. **Maintainability**: Single source of truth for field mapping + +### Generic Sync Pattern + +```swift +extension RecordManaging { + func sync(_ records: [T]) async throws { + let operations = records.map { record in + RecordOperation( + operationType: .forceReplace, + recordType: T.cloudKitRecordType, + recordName: record.recordName, + fields: record.toCloudKitFields() + ) + } + + try await executeBatchOperations(operations, recordType: T.cloudKitRecordType) + } +} +``` + +## Schema Design Patterns + +### Schema File Format + +```text +DEFINE SCHEMA + +RECORD TYPE RestoreImage ( + "version" STRING QUERYABLE SORTABLE SEARCHABLE, + "buildNumber" STRING QUERYABLE SORTABLE, + "releaseDate" TIMESTAMP QUERYABLE SORTABLE, + "fileSize" INT64, + "isSigned" INT64 QUERYABLE, # Boolean as INT64 + "minimumMacOS" REFERENCE, # Relationship + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" # Public read access +); +``` + +### Key Principles + +1. **Always include `DEFINE SCHEMA` header** - Required by `cktool` +2. **Never include system fields** - `__recordID`, `___createTime`, etc. are automatic +3. **Use INT64 for booleans** - CloudKit doesn't have native boolean type +4. **Use REFERENCE for relationships** - Links between record types +5. **Mark query fields appropriately**: + - `QUERYABLE` - Can filter on this field + - `SORTABLE` - Can order results by this field + - `SEARCHABLE` - Enable full-text search + +6. **Set appropriate permissions**: + - `_creator` - Record owner (read/write) + - `_icloud` - Authenticated iCloud users + - `_world` - Public (read-only typically) + +### Indexing Strategy + +```swift +// Fields you'll query on +"buildNumber" STRING QUERYABLE // WHERE buildNumber = "21A5522h" +"releaseDate" TIMESTAMP QUERYABLE SORTABLE // ORDER BY releaseDate DESC +"version" STRING SEARCHABLE // Full-text search +``` + +### Automated Schema Deployment + +Bushel includes `Scripts/setup-cloudkit-schema.sh`: + +```bash +#!/bin/bash +set -euo pipefail + +CONTAINER_ID="${CLOUDKIT_CONTAINER_ID}" +MANAGEMENT_TOKEN="${CLOUDKIT_MANAGEMENT_TOKEN}" +ENVIRONMENT="${CLOUDKIT_ENVIRONMENT:-development}" + +cktool -t "$MANAGEMENT_TOKEN" \ + -c "$CONTAINER_ID" \ + -e "$ENVIRONMENT" \ + import-schema schema.ckdb +``` + +## Server-to-Server Authentication + +### Setup Process + +1. **Generate CloudKit Key** (Apple Developer portal): + - Navigate to Certificates, Identifiers & Profiles + - Keys → CloudKit Web Service + - Download `.p8` file and note Key ID + +2. **Secure Key Storage**: +```bash +mkdir -p ~/.cloudkit +chmod 700 ~/.cloudkit +mv AuthKey_*.p8 ~/.cloudkit/bushel-private-key.pem +chmod 600 ~/.cloudkit/bushel-private-key.pem +``` + +3. **Environment Variables**: +```bash +export CLOUDKIT_KEY_ID="your_key_id_here" +export CLOUDKIT_KEY_FILE="$HOME/.cloudkit/bushel-private-key.pem" +``` + +### Implementation + +```swift +// Read private key from disk +let pemString = try String( + contentsOfFile: privateKeyPath, + encoding: .utf8 +) + +// Create authentication manager +let tokenManager = try ServerToServerAuthManager( + keyID: keyID, + pemString: pemString +) + +// Create CloudKit service +let service = try CloudKitService( + containerIdentifier: "iCloud.com.company.App", + tokenManager: tokenManager, + environment: .development, + database: .public +) +``` + +### Security Best Practices + +- ✅ Never commit `.p8` or `.pem` files to version control +- ✅ Store keys with restricted permissions (600) +- ✅ Use environment variables for key paths +- ✅ Use different keys for development vs production +- ✅ Rotate keys periodically +- ❌ Never hardcode keys in source code +- ❌ Never share keys across projects + +## Batch Operations + +### CloudKit Limits + +- **Maximum 200 operations per request** +- **Maximum 400 operations per transaction** +- **Rate limits apply per container** + +### Batching Pattern + +```swift +func executeBatchOperations( + _ operations: [RecordOperation], + recordType: String +) async throws { + let batchSize = 200 + let batches = operations.chunked(into: batchSize) + + for (index, batch) in batches.enumerated() { + print(" Batch \(index + 1)/\(batches.count)...") + + let results = try await service.modifyRecords(batch) + + // Handle partial failures + let successful = results.filter { !$0.isError } + let failed = results.count - successful.count + + if failed > 0 { + print(" ⚠️ \(failed) operations failed") + + // Log specific failures + for result in results where result.isError { + if let error = result.error { + print(" Error: \(error.localizedDescription)") + } + } + } + } +} +``` + +### Non-Atomic Operations + +```swift +let operations = articles.map { article in + RecordOperation( + operationType: .create, + recordType: "PublicArticle", + recordName: article.recordName, + fields: article.toFieldsDict() + ) +} + +// Non-atomic: partial success possible +let results = try await service.modifyRecords(operations) + +// Check individual results +for (index, result) in results.enumerated() { + if result.isError { + print("Article \(index) failed: \(result.error?.localizedDescription ?? "Unknown")") + } +} +``` + +## Relationship Handling + +### Schema Definition + +```text +RECORD TYPE XcodeVersion ( + "version" STRING QUERYABLE, + "releaseDate" TIMESTAMP QUERYABLE SORTABLE, + "minimumMacOS" REFERENCE, # → RestoreImage + "requiredSwift" REFERENCE # → SwiftVersion +); + +RECORD TYPE RestoreImage ( + "buildNumber" STRING QUERYABLE, + ... +); +``` + +### Using References in Code + +```swift +// Create reference field +let minimumMacOSRef = FieldValue.Reference( + recordName: "RestoreImage-21A5522h" +) + +fields["minimumMacOS"] = .reference(minimumMacOSRef) +``` + +### Syncing Order (Respecting Dependencies) + +```swift +// 1. Sync independent records first +try await sync(swiftVersions) +try await sync(restoreImages) + +// 2. Then sync records with dependencies +try await sync(xcodeVersions) // References swift/restore images +``` + +### Querying Relationships + +```swift +// Query Xcode versions with specific macOS requirement +let filter = QueryFilter.equals( + "minimumMacOS", + .reference(FieldValue.Reference(recordName: "RestoreImage-21A5522h")) +) + +let results = try await service.queryRecords( + recordType: "XcodeVersion", + filters: [filter] +) +``` + +## Data Pipeline Architecture + +### Multi-Source Fetching + +```swift +struct DataSourcePipeline: Sendable { + func fetch(options: Options) async throws -> FetchResult { + // Parallel fetching with structured concurrency + async let ipswImages = IPSWFetcher().fetch() + async let appleDBImages = AppleDBFetcher().fetch() + async let xcodeVersions = XcodeReleaseFetcher().fetch() + + // Collect all results + var allImages = try await ipswImages + allImages.append(contentsOf: try await appleDBImages) + + // Deduplicate and return + return FetchResult( + restoreImages: deduplicateRestoreImages(allImages), + xcodeVersions: try await xcodeVersions, + swiftVersions: extractSwiftVersions() + ) + } +} +``` + +### Individual Fetcher Pattern + +```swift +protocol DataSourceFetcher: Sendable { + associatedtype Record + func fetch() async throws -> [Record] +} + +struct IPSWFetcher: DataSourceFetcher { + func fetch() async throws -> [RestoreImageRecord] { + let client = IPSWDownloads(transport: URLSessionTransport()) + let device = try await client.device(withIdentifier: "VirtualMac2,1") + + return device.firmwares.map { firmware in + RestoreImageRecord( + version: firmware.version.description, + buildNumber: firmware.buildid, + releaseDate: firmware.releasedate, + fileSize: firmware.filesize, + isSigned: firmware.signed + ) + } + } +} +``` + +### Deduplication Strategy + +```swift +private func deduplicateRestoreImages( + _ images: [RestoreImageRecord] +) -> [RestoreImageRecord] { + var uniqueImages: [String: RestoreImageRecord] = [:] + + for image in images { + let key = image.buildNumber // Unique identifier + + if let existing = uniqueImages[key] { + // Merge records, prefer most complete data + uniqueImages[key] = mergeRestoreImages(existing, image) + } else { + uniqueImages[key] = image + } + } + + return Array(uniqueImages.values) + .sorted { $0.releaseDate > $1.releaseDate } +} + +private func mergeRestoreImages( + _ a: RestoreImageRecord, + _ b: RestoreImageRecord +) -> RestoreImageRecord { + // Prefer non-nil values + RestoreImageRecord( + version: a.version, + buildNumber: a.buildNumber, + releaseDate: a.releaseDate, + fileSize: a.fileSize ?? b.fileSize, + isSigned: a.isSigned ?? b.isSigned, + url: a.url ?? b.url + ) +} +``` + +### Graceful Degradation + +```swift +// Don't fail entire sync if one source fails +var allImages: [RestoreImageRecord] = [] + +do { + let ipswImages = try await IPSWFetcher().fetch() + allImages.append(contentsOf: ipswImages) +} catch { + print(" ⚠️ IPSW fetch failed: \(error)") +} + +do { + let appleDBImages = try await AppleDBFetcher().fetch() + allImages.append(contentsOf: appleDBImages) +} catch { + print(" ⚠️ AppleDB fetch failed: \(error)") +} + +// Continue with whatever data we got +return deduplicateRestoreImages(allImages) +``` + +### Metadata Tracking + +```swift +struct DataSourceMetadata: CloudKitRecord { + let sourceName: String + let recordTypeName: String + let lastFetchedAt: Date + let recordCount: Int + let fetchDurationSeconds: Double + let lastError: String? + + var recordName: String { + "metadata-\(sourceName)-\(recordTypeName)" + } +} + +// Check before fetching +private func shouldFetch( + source: String, + recordType: String, + force: Bool +) async -> Bool { + guard !force else { return true } + + let metadata = try? await cloudKit.queryDataSourceMetadata( + source: source, + recordType: recordType + ) + + guard let existing = metadata else { return true } + + let timeSinceLastFetch = Date().timeIntervalSince(existing.lastFetchedAt) + let minInterval = configuration.minimumInterval(for: source) ?? 3600 + + return timeSinceLastFetch >= minInterval +} +``` + +## Celestra vs Bushel Comparison + +### Architecture Similarities + +| Aspect | Bushel | Celestra | +|--------|---------|----------| +| **Schema Management** | `schema.ckdb` + setup script | `schema.ckdb` + setup script | +| **Authentication** | Server-to-Server (PEM) | Server-to-Server (PEM) | +| **CLI Framework** | ArgumentParser | ArgumentParser | +| **Concurrency** | async/await | async/await | +| **Database** | Public | Public | +| **Documentation** | Comprehensive | Comprehensive | + +### Key Differences + +#### 1. Record Conversion Pattern + +**Bushel (Protocol-Based):** +```swift +protocol CloudKitRecord { + func toCloudKitFields() -> [String: FieldValue] + static func from(recordInfo: RecordInfo) -> Self? +} + +struct RestoreImageRecord: CloudKitRecord { ... } + +// Generic sync +func sync(_ records: [T]) async throws +``` + +**Celestra (Direct Mapping):** +```swift +struct PublicArticle { + func toFieldsDict() -> [String: FieldValue] { ... } + init(from recordInfo: RecordInfo) { ... } +} + +// Specific sync methods +func createArticles(_ articles: [PublicArticle]) async throws +``` + +**Trade-offs:** +- Bushel: More generic, reusable patterns +- Celestra: Simpler, more direct for single-purpose tool + +#### 2. Relationship Handling + +**Bushel (CKReference):** +```swift +fields["minimumMacOS"] = .reference( + FieldValue.Reference(recordName: "RestoreImage-21A5522h") +) +``` + +**Celestra (String-Based):** +```swift +fields["feedRecordName"] = .string(feedRecordName) +``` + +**Trade-offs:** +- Bushel: Type-safe relationships, cascade deletes possible +- Celestra: Simpler querying, manual cascade handling + +#### 3. Data Pipeline Complexity + +**Bushel:** +- Multiple external data sources +- Parallel fetching with `async let` +- Complex deduplication (merge strategies) +- Cross-record relationships (Xcode → Swift, RestoreImage) + +**Celestra:** +- Single data source type (RSS feeds) +- Sequential or parallel feed updates +- Simple deduplication (GUID-based) +- Parent-child relationship only (Feed → Articles) + +#### 4. Deduplication Strategy + +**Bushel:** +```swift +// Merge records from multiple sources +private func mergeRestoreImages( + _ a: RestoreImageRecord, + _ b: RestoreImageRecord +) -> RestoreImageRecord { + // Combine data, prefer most complete +} +``` + +**Celestra (Recommended):** +```swift +// Query existing before upload +let existingArticles = try await queryArticlesByGUIDs(guids, feedRecordName) +let newArticles = articles.filter { article in + !existingArticles.contains { $0.guid == article.guid } +} +``` + +### When to Use Each Pattern + +**Use Bushel's Protocol Pattern When:** +- Multiple record types with similar operations +- Building a reusable framework +- Complex relationship graphs +- Need maximum type safety + +**Use Celestra's Direct Pattern When:** +- Simple, focused tool +- Single or few record types +- Straightforward relationships +- Prioritizing simplicity + +### Common Best Practices (Both Projects) + +1. ✅ **Schema-First Design** - Define `schema.ckdb` before coding +2. ✅ **Automated Setup Scripts** - Script schema deployment +3. ✅ **Server-to-Server Auth** - Use PEM keys, not user auth +4. ✅ **Batch Operations** - Respect 200-record limit +5. ✅ **Error Handling** - Graceful degradation +6. ✅ **Documentation** - Comprehensive README and setup guides +7. ✅ **Environment Variables** - Never hardcode credentials +8. ✅ **Structured Concurrency** - Use async/await throughout + +## Additional Resources + +- **Bushel Source**: `Examples/Bushel/` +- **Celestra Source**: `Examples/Celestra/` +- **MistKit Documentation**: Root README.md +- **CloudKit Web Services**: `.claude/docs/webservices.md` +- **Swift OpenAPI Generator**: `.claude/docs/swift-openapi-generator.md` + +## Conclusion + +Both Bushel and Celestra demonstrate effective CloudKit integration patterns using MistKit, with different trade-offs based on project complexity and requirements. Use this document as a reference when designing CloudKit-backed applications with MistKit. + +For blog posts or tutorials: +- **Beginners**: Start with Celestra's direct approach +- **Advanced**: Explore Bushel's protocol-oriented patterns +- **Production**: Consider adopting patterns from both based on your needs diff --git a/Examples/Celestra/CLOUDKIT_SCHEMA_SETUP.md b/Examples/Celestra/CLOUDKIT_SCHEMA_SETUP.md new file mode 100644 index 00000000..d2c57ba5 --- /dev/null +++ b/Examples/Celestra/CLOUDKIT_SCHEMA_SETUP.md @@ -0,0 +1,406 @@ +# CloudKit Schema Setup Guide + +This guide explains how to set up the CloudKit schema for the Celestra RSS reader application. + +## CloudKit Credentials Overview + +Celestra requires **two different types of CloudKit credentials**: + +1. **Management Token** (for schema setup only) + - Used by `cktool` to create/modify record types + - Only needed during initial schema setup + - Generated in CloudKit Dashboard → Profile → "Manage Tokens" + - Used in this guide for schema import + +2. **Server-to-Server Key** (for runtime operations) + - Used by MistKit to authenticate API requests at runtime + - Required for the app to read/write CloudKit data + - Generated in CloudKit Dashboard → API Tokens → "Server-to-Server Keys" + - Configured in `.env` file (see main README) + +This guide focuses on setting up the schema using a **Management Token**. After schema setup, you'll generate a **Server-to-Server Key** for the app. + +## Two Approaches + +### Option 1: Automated Setup with cktool (Recommended) + +Use the provided script to automatically import the schema. + +#### Prerequisites + +- **Xcode 13+** installed (provides `cktool`) +- **CloudKit container** created in [CloudKit Dashboard](https://icloud.developer.apple.com/) +- **Apple Developer Team ID** (10-character identifier) +- **CloudKit Management Token** (see "Getting a Management Token" below) + +#### Steps + +1. **Save your CloudKit Management Token** + + ```bash + xcrun cktool save-token + ``` + + When prompted, paste your management token from CloudKit Dashboard. + +2. **Set environment variables** + + ```bash + export CLOUDKIT_CONTAINER_ID="iCloud.com.brightdigit.Celestra" + export CLOUDKIT_TEAM_ID="YOUR_TEAM_ID" + export CLOUDKIT_ENVIRONMENT="development" # or "production" + ``` + +3. **Run the setup script** + + ```bash + cd Examples/Celestra + ./Scripts/setup-cloudkit-schema.sh + ``` + + The script will: + - Validate the schema file + - Confirm before importing + - Import the schema to your CloudKit container + - Display success/error messages + +4. **Verify in CloudKit Dashboard** + + Open [CloudKit Dashboard](https://icloud.developer.apple.com/) and verify the two record types exist: + - Feed + - Article + +### Option 2: Manual Schema Creation + +For manual setup or if you prefer to use the CloudKit Dashboard directly. + +#### Steps + +1. **Open CloudKit Dashboard** + + Go to [https://icloud.developer.apple.com/](https://icloud.developer.apple.com/) + +2. **Select your container** + + Choose your Celestra container (e.g., `iCloud.com.brightdigit.Celestra`) + +3. **Switch to Development environment** + + Use the environment selector to choose "Development" + +4. **Navigate to Schema section** + + Click on "Schema" in the sidebar + +5. **Create Feed record type** + + - Click "+" to add a new record type + - Name: `Feed` + - Add the following fields: + + | Field Name | Field Type | Options | + |------------|------------|---------| + | feedURL | String | ✓ Queryable, ✓ Sortable | + | title | String | | + | totalAttempts | Int64 | | + | successfulAttempts | Int64 | | + | usageCount | Int64 | ✓ Queryable, ✓ Sortable | + | lastAttempted | Date/Time | ✓ Queryable, ✓ Sortable | + + - Set Permissions: + - Read: World Readable + - Write: Requires Creator + +6. **Create Article record type** + + - Click "+" to add another record type + - Name: `Article` + - Add the following fields: + + | Field Name | Field Type | Options | + |------------|------------|---------| + | feedRecordName | String | ✓ Queryable, ✓ Sortable | + | title | String | | + | link | String | | + | description | String | | + | author | String | | + | pubDate | Date/Time | | + | guid | String | ✓ Queryable, ✓ Sortable | + | fetchedAt | Date/Time | | + | expiresAt | Date/Time | ✓ Queryable, ✓ Sortable | + + - Set Permissions: + - Read: World Readable + - Write: Requires Creator + +7. **Save the schema** + + Click "Save" to apply the changes + +## Getting a Management Token + +Management tokens allow `cktool` to modify your CloudKit schema. + +1. Open [CloudKit Dashboard](https://icloud.developer.apple.com/) +2. Select your container +3. Click your profile icon (top right) +4. Select "Manage Tokens" +5. Click "Create Token" +6. Give it a name: "Celestra Schema Management" +7. **Copy the token** (you won't see it again!) +8. Save it using `xcrun cktool save-token` + +## Schema File Format + +The schema is defined in `schema.ckdb` using CloudKit's declarative schema language: + +``` +RECORD TYPE Feed ( + "feedURL" STRING QUERYABLE SORTABLE, + "title" STRING, + "totalAttempts" INT64, + "successfulAttempts" INT64, + "usageCount" INT64 QUERYABLE SORTABLE, + "lastAttempted" TIMESTAMP QUERYABLE SORTABLE, + + GRANT WRITE TO "_creator", + GRANT READ TO "_world" +); + +RECORD TYPE Article ( + "feedRecordName" STRING QUERYABLE SORTABLE, + "title" STRING, + "link" STRING, + "description" STRING, + "author" STRING, + "pubDate" TIMESTAMP, + "guid" STRING QUERYABLE SORTABLE, + "fetchedAt" TIMESTAMP, + "expiresAt" TIMESTAMP QUERYABLE SORTABLE, + + GRANT WRITE TO "_creator", + GRANT READ TO "_world" +); +``` + +### Key Features + +- **QUERYABLE**: Field can be used in query predicates +- **SORTABLE**: Field can be used for sorting results +- **GRANT READ TO "_world"**: Makes records publicly readable +- **GRANT WRITE TO "_creator"**: Only creator can modify + +### Database Scope + +**Important**: The schema import applies to the **container level**, making record types available in both public and private databases. However: + +- **Celestra writes to the public database** for sharing RSS feeds +- The `GRANT READ TO "_world"` permission ensures public read access +- This allows RSS feeds and articles to be shared across all users + +### Field Type Notes + +- **TIMESTAMP**: CloudKit's date/time field type (maps to Date/Time in Dashboard) +- **INT64**: 64-bit integer for counts and metrics + +### Celestra Record Types Explained + +#### Feed + +Stores RSS feed metadata and usage statistics: + +- `feedURL`: The RSS feed URL (indexed for quick lookups) +- `title`: Feed title from RSS metadata +- `totalAttempts`: Total number of fetch attempts (for reliability tracking) +- `successfulAttempts`: Number of successful fetches +- `usageCount`: Popularity metric (how often this feed is accessed) +- `lastAttempted`: When the feed was last fetched (indexed for update queries) + +#### Article + +Stores individual articles from RSS feeds: + +- `feedRecordName`: Reference to the parent Feed record (indexed for queries) +- `title`: Article title +- `link`: Article URL +- `description`: Article summary/content +- `author`: Article author +- `pubDate`: Publication date from RSS feed +- `guid`: Unique identifier from RSS feed (indexed to prevent duplicates) +- `fetchedAt`: When the article was fetched from the feed +- `expiresAt`: When the article should be considered stale (indexed for cleanup queries) + +## Schema Export + +To export your current schema (useful for version control): + +```bash +xcrun cktool export-schema \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.brightdigit.Celestra \ + --environment development \ + --output-file schema-backup.ckdb +``` + +## Validation Without Import + +To validate your schema file without importing: + +```bash +xcrun cktool validate-schema \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.brightdigit.Celestra \ + --environment development \ + schema.ckdb +``` + +## Common Issues + +### Authentication Failed + +**Problem**: "Authentication failed" or "Invalid token" + +**Solution**: +1. Generate a new management token in CloudKit Dashboard +2. Save it: `xcrun cktool save-token` +3. Ensure you're using the correct Team ID + +### Container Not Found + +**Problem**: "Container not found" or "Invalid container" + +**Solution**: +- Verify container ID matches CloudKit Dashboard exactly +- Ensure container exists and you have access +- Check Team ID is correct + +### Schema Validation Errors + +**Problem**: "Schema validation failed" with field type errors + +**Solution**: +- Ensure all field types match CloudKit's supported types +- Use TIMESTAMP for dates, INT64 for integers +- Check for typos in field names + +### Permission Denied + +**Problem**: "Insufficient permissions to modify schema" + +**Solution**: +- Verify your Apple ID has Admin role in the container +- Check management token has correct permissions +- Try regenerating the management token + +## Deploying to Production + +After testing in development: + +1. **Export development schema** + ```bash + xcrun cktool export-schema \ + --team-id YOUR_TEAM_ID \ + --container-id iCloud.com.brightdigit.Celestra \ + --environment development \ + --output-file celestra-prod-schema.ckdb + ``` + +2. **Import to production** + ```bash + export CLOUDKIT_ENVIRONMENT=production + ./Scripts/setup-cloudkit-schema.sh + ``` + +3. **Verify in Dashboard** + - Switch to Production environment + - Verify record types exist + - Test with a few manual records + +## CI/CD Integration + +For automated deployment, you can integrate schema management into your CI/CD pipeline: + +```bash +#!/bin/bash +# In your CI/CD script + +# Load token from secure environment variable +echo "$CLOUDKIT_MANAGEMENT_TOKEN" | xcrun cktool save-token --file - + +# Import schema +xcrun cktool import-schema \ + --team-id "$TEAM_ID" \ + --container-id "$CONTAINER_ID" \ + --environment development \ + schema.ckdb +``` + +## Schema Versioning + +Best practices for managing schema changes: + +1. **Version Control**: Keep `schema.ckdb` in git +2. **Development First**: Always test changes in development environment +3. **Schema Export**: Periodically export production schema as backup +4. **Migration Plan**: Document any breaking changes +5. **Backward Compatibility**: Avoid removing fields when possible + +## Next Steps + +After setting up the schema: + +1. **Configure credentials**: See main [README.md](./README.md) for .env setup +2. **Generate Server-to-Server Key**: Required for CloudKit authentication +3. **Add your first feed**: `swift run celestra add-feed https://example.com/feed.xml` +4. **Update feeds**: `swift run celestra update` +5. **Verify data**: Check CloudKit Dashboard for records + +## Example Queries Using MistKit + +Once your schema is set up, Celestra demonstrates MistKit's query capabilities: + +### Query by Date +```swift +// Find feeds last attempted before a specific date +let filters: [QueryFilter] = [ + .lessThan("lastAttempted", .date(cutoffDate)) +] +``` + +### Query by Popularity +```swift +// Find popular feeds (minimum usage count) +let filters: [QueryFilter] = [ + .greaterThanOrEquals("usageCount", .int64(10)) +] +``` + +### Combined Filters with Sorting +```swift +// Find stale popular feeds, sorted by popularity +let records = try await queryRecords( + recordType: "Feed", + filters: [ + .lessThan("lastAttempted", .date(cutoffDate)), + .greaterThanOrEquals("usageCount", .int64(5)) + ], + sortBy: [.descending("usageCount")], + limit: 100 +) +``` + +## Resources + +- [CloudKit Schema Documentation](https://developer.apple.com/documentation/cloudkit/designing-and-creating-a-cloudkit-database) +- [cktool Reference](https://keith.github.io/xcode-man-pages/cktool.1.html) +- [WWDC21: Automate CloudKit tests with cktool](https://developer.apple.com/videos/play/wwdc2021/10118/) +- [CloudKit Dashboard](https://icloud.developer.apple.com/) + +## Troubleshooting + +For Celestra-specific issues, see the main [README.md](./README.md). + +For CloudKit schema issues: +- Check Apple Developer Forums: https://developer.apple.com/forums/tags/cloudkit +- Review CloudKit Dashboard logs +- Verify schema file syntax against Apple's documentation diff --git a/Examples/Celestra/IMPLEMENTATION_NOTES.md b/Examples/Celestra/IMPLEMENTATION_NOTES.md new file mode 100644 index 00000000..b5343f2d --- /dev/null +++ b/Examples/Celestra/IMPLEMENTATION_NOTES.md @@ -0,0 +1,837 @@ +# Celestra Implementation Notes + +This document captures the design decisions, implementation patterns, and technical details of the Celestra RSS reader example. + +## Table of Contents + +- [Project Overview](#project-overview) +- [Schema Design Decisions](#schema-design-decisions) +- [Duplicate Detection Strategy](#duplicate-detection-strategy) +- [Data Model Architecture](#data-model-architecture) +- [CloudKit Integration Patterns](#cloudkit-integration-patterns) +- [Comparison with Bushel](#comparison-with-bushel) +- [Web Etiquette Features](#web-etiquette-features) +- [Future Improvements](#future-improvements) + +## Project Overview + +**Purpose**: Demonstrate MistKit's CloudKit integration capabilities through a practical RSS feed reader + +**Key Goals**: +- Show query filtering and sorting APIs +- Demonstrate Server-to-Server authentication +- Provide a real-world example for developers learning MistKit +- Serve as blog post material for MistKit documentation + +**Target Audience**: Developers building CloudKit-backed Swift applications + +## Schema Design Decisions + +### Design Philosophy + +We followed Bushel's schema best practices while keeping Celestra focused on simplicity: + +1. **DEFINE SCHEMA Header**: Required by `cktool` for automated schema deployment +2. **No System Fields**: System fields like `__recordID` are automatically managed by CloudKit +3. **INT64 for Booleans**: CloudKit doesn't have native boolean type, use `INT64` (0 = false, 1 = true) +4. **Field Indexing Strategy**: Mark fields as QUERYABLE, SORTABLE, or SEARCHABLE based on usage patterns + +### PublicFeed Schema + +```text +RECORD TYPE Feed ( + "feedURL" STRING QUERYABLE SORTABLE, + "title" STRING SEARCHABLE, + "description" STRING, + "totalAttempts" INT64, + "successfulAttempts" INT64, + "usageCount" INT64 QUERYABLE SORTABLE, + "lastAttempted" TIMESTAMP QUERYABLE SORTABLE, + "isActive" INT64 QUERYABLE, + + // Web etiquette fields + "lastModified" STRING, + "etag" STRING, + "failureCount" INT64, + "lastFailureReason" STRING, + "minUpdateInterval" DOUBLE, + ... +) +``` + +**Field Decisions**: + +- `feedURL` (QUERYABLE, SORTABLE): Enables querying/sorting by URL +- `title` (SEARCHABLE): Full-text search capability for feed discovery +- `description`: Optional feed description from RSS metadata +- `totalAttempts` / `successfulAttempts`: Track reliability metrics +- `usageCount` (QUERYABLE, SORTABLE): Popularity ranking for filtered queries +- `lastAttempted` (QUERYABLE, SORTABLE): Enable time-based filtering +- `isActive` (QUERYABLE): Allow filtering active/inactive feeds + +**Web Etiquette Fields**: + +- `lastModified`: HTTP Last-Modified header for conditional requests +- `etag`: HTTP ETag header for conditional requests +- `failureCount`: Consecutive failure counter for circuit breaker pattern +- `lastFailureReason`: Last error message for debugging +- `minUpdateInterval`: Minimum seconds between updates (from RSS `` or syndication metadata) + +### PublicArticle Schema + +```text +RECORD TYPE PublicArticle ( + "feedRecordName" STRING QUERYABLE SORTABLE, + "title" STRING SEARCHABLE, + "link" STRING, + "description" STRING, + "author" STRING QUERYABLE, + "pubDate" TIMESTAMP QUERYABLE SORTABLE, + "guid" STRING QUERYABLE SORTABLE, + "contentHash" STRING QUERYABLE, + "fetchedAt" TIMESTAMP QUERYABLE SORTABLE, + "expiresAt" TIMESTAMP QUERYABLE SORTABLE, + ... +) +``` + +**Field Decisions**: + +- `feedRecordName` (STRING, QUERYABLE, SORTABLE): Parent reference using string instead of CKReference for simplicity +- `guid` (QUERYABLE, SORTABLE): Enable duplicate detection queries +- `contentHash` (QUERYABLE): SHA256 hash for fallback duplicate detection +- `expiresAt` (QUERYABLE, SORTABLE): TTL-based cleanup (default 30 days) + +**Relationship Design**: +- **Choice**: String-based relationships (`feedRecordName`) vs CloudKit references +- **Rationale**: Simpler querying, easier to understand for developers +- **Trade-off**: Manual cascade delete handling, but clearer code patterns + +## Duplicate Detection Strategy + +### Problem Statement + +RSS feeds often republish the same articles. Without deduplication: +- Running `update` multiple times creates duplicate records +- CloudKit storage bloats with redundant data +- Query results contain duplicate entries + +### Solution Architecture + +**Primary Strategy: GUID-Based Detection** + +1. Extract GUIDs from all fetched articles +2. Query CloudKit for existing articles with those GUIDs +3. Filter out articles that already exist +4. Only upload new articles + +**Implementation** (UpdateCommand.swift:106-133): + +```swift +// Duplicate detection: query existing articles by GUID +if !articles.isEmpty { + let guids = articles.map { $0.guid } + let existingArticles = try await service.queryArticlesByGUIDs( + guids, + feedRecordName: recordName + ) + + // Create set of existing GUIDs for fast lookup + let existingGUIDs = Set(existingArticles.map { $0.guid }) + + // Filter out duplicates + let newArticles = articles.filter { !existingGUIDs.contains($0.guid) } + + if duplicateCount > 0 { + print(" ℹ️ Skipped \(duplicateCount) duplicate(s)") + } + + // Upload only new articles + if !newArticles.isEmpty { + _ = try await service.createArticles(newArticles) + } +} +``` + +**Fallback Strategy: Content Hashing** + +For articles with unreliable or missing GUIDs: + +```swift +// In PublicArticle model +var contentHash: String { + let content = "\(title)|\(link)|\(guid)" + let data = Data(content.utf8) + let hash = SHA256.hash(data: data) + return hash.compactMap { String(format: "%02x", $0) }.joined() +} +``` + +**Performance Considerations**: +- Set-based filtering: O(n) lookup time +- Single query per feed update (not per article) +- Batch CloudKit operations for efficiency + +### Why This Approach? + +**Alternatives Considered**: + +1. **Check each GUID individually** + - ❌ Too many CloudKit API calls + - ❌ Poor performance with large feeds + +2. **Upload all, handle errors** + - ❌ Wastes CloudKit write quotas + - ❌ Error handling complexity + +3. **Local caching/database** + - ❌ Adds complexity + - ❌ Not suitable for command-line tool + +**Chosen Solution Benefits**: +- ✅ Minimal CloudKit queries (one per feed) +- ✅ Simple to understand and maintain +- ✅ Efficient Set-based filtering +- ✅ Works well with MistKit's query API + +## Data Model Architecture + +### Model Design Pattern + +**Choice**: Direct field mapping vs Protocol-oriented (CloudKitRecord) + +Celestra uses **direct field mapping** for simplicity: + +```swift +struct PublicArticle { + let recordName: String? + let feedRecordName: String + let title: String + // ... other fields + + func toFieldsDict() -> [String: FieldValue] { + var fields: [String: FieldValue] = [ + "feedRecordName": .string(feedRecordName), + "title": .string(title), + // ... map fields + ] + return fields + } + + init(from record: RecordInfo) { + // Parse RecordInfo back to model + } +} +``` + +**Why Not CloudKitRecord Protocol?** +- Celestra has only 2 record types (simple) +- Direct mapping is easier for developers to understand +- Protocol approach (like Bushel) better for 5+ record types + +See `BUSHEL_PATTERNS.md` for protocol-oriented alternative. + +### Field Type Conversions + +**Boolean Fields** (isActive): +```swift +// To CloudKit +fields["isActive"] = .int64(isActive ? 1 : 0) + +// From CloudKit +if case .int64(let value) = record.fields["isActive"] { + self.isActive = value != 0 +} else { + self.isActive = true // Default +} +``` + +**Optional Fields** (description): +```swift +// To CloudKit +if let description = description { + fields["description"] = .string(description) +} + +// From CloudKit +if case .string(let value) = record.fields["description"] { + self.description = value +} else { + self.description = nil +} +``` + +## CloudKit Integration Patterns + +### Query Filtering Pattern + +**Location**: CloudKitService+Celestra.swift:26-53 + +```swift +func queryFeeds( + lastAttemptedBefore: Date? = nil, + minPopularity: Int64? = nil, + limit: Int = 100 +) async throws -> [PublicFeed] { + var filters: [QueryFilter] = [] + + // Date comparison filter + if let cutoff = lastAttemptedBefore { + filters.append(.lessThan("lastAttempted", .date(cutoff))) + } + + // Numeric comparison filter + if let minPop = minPopularity { + filters.append(.greaterThanOrEquals("usageCount", .int64(Int(minPop)))) + } + + // Query with filters and sorting + let records = try await queryRecords( + recordType: "PublicFeed", + filters: filters.isEmpty ? nil : filters, + sortBy: [.descending("usageCount")], + limit: limit + ) + + return records.map { PublicFeed(from: $0) } +} +``` + +**Demonstrates**: +- Optional filters pattern +- Date and numeric comparisons +- Query sorting +- Result mapping + +### Batch Operations Pattern + +**Non-Atomic Operations** with chunking and result tracking: + +```swift +func createArticles(_ articles: [PublicArticle]) async throws -> BatchOperationResult { + guard !articles.isEmpty else { + return BatchOperationResult() + } + + // Chunk articles into batches of 200 (CloudKit limit) + let batches = articles.chunked(into: 200) + var result = BatchOperationResult() + + for (index, batch) in batches.enumerated() { + let records = batch.map { article in + (recordType: "PublicArticle", fields: article.toFieldsDict()) + } + + // Use retry policy for each batch + let recordInfos = try await retryPolicy.execute { + try await self.createRecords(records, atomic: false) + } + + result.appendSuccesses(recordInfos) + } + + return result +} +``` + +**Why This Approach?** +- **Non-atomic operations**: If 1 of 100 articles fails, still upload the other 99 +- **200-record batches**: Respects CloudKit's batch operation limits +- **Result tracking**: `BatchOperationResult` provides success/failure counts and rates +- **Retry logic**: Each batch operation uses exponential backoff for transient failures +- **Better UX**: Partial success vs total failure, with detailed progress reporting + +**BatchOperationResult Structure**: +```swift +struct BatchOperationResult { + var successfulRecords: [RecordInfo] = [] + var failedRecords: [(article: PublicArticle, error: Error)] = [] + var successRate: Double // 0-100% +} +``` + +### Server-to-Server Authentication + +**Location**: Celestra.swift (CelestraConfig.createCloudKitService) + +```swift +// Read private key from file +let pemString = try String( + contentsOf: URL(fileURLWithPath: privateKeyPath), + encoding: .utf8 +) + +// Create token manager +let tokenManager = try ServerToServerAuthManager( + keyID: keyID, + pemString: pemString +) + +// Create CloudKit service +let service = try CloudKitService( + containerIdentifier: containerID, + tokenManager: tokenManager, + environment: environment, + database: .public +) +``` + +**Security Best Practices**: +- Never commit `.pem` files +- Store keys with restricted permissions (chmod 600) +- Use environment variables for paths +- Different keys for dev/prod + +## Comparison with Bushel + +### Architecture Similarities + +| Aspect | Bushel | Celestra | +|--------|---------|----------| +| **Schema Management** | schema.ckdb + setup script | schema.ckdb + setup script | +| **Authentication** | Server-to-Server (PEM) | Server-to-Server (PEM) | +| **CLI Framework** | ArgumentParser | ArgumentParser | +| **Concurrency** | async/await | async/await | +| **Database** | Public | Public | + +### Key Differences + +**1. Record Conversion**: +- Bushel: CloudKitRecord protocol (generic, reusable) +- Celestra: Direct field mapping (simple, focused) + +**2. Data Sources**: +- Bushel: Multiple external APIs (IPSW, AppleDB, XcodeReleases) +- Celestra: Single source type (RSS feeds via SyndiKit) + +**3. Relationships**: +- Bushel: CKReference for type-safe relationships +- Celestra: String-based for simplicity + +**4. Deduplication**: +- Bushel: Merge strategies for multiple sources +- Celestra: GUID-based query before upload + +### When to Use Each Pattern + +**Use Bushel Patterns When**: +- 5+ record types with similar operations +- Complex relationship graphs +- Multiple data sources to merge +- Building a reusable framework + +**Use Celestra Patterns When**: +- 2-3 simple record types +- Straightforward relationships +- Single or few data sources +- Focused command-line tool + +See `BUSHEL_PATTERNS.md` for detailed comparison. + +## Error Handling and Retry Logic + +### Implemented Features + +**Comprehensive Error Categorization** (CelestraError.swift): + +```swift +enum CelestraError: LocalizedError { + case cloudKitError(CloudKitError) + case rssFetchFailed(URL, underlying: Error) + case invalidFeedData(String) + case quotaExceeded + case networkUnavailable + + var isRetriable: Bool { + // Smart retry logic based on error type + } +} +``` + +**Exponential Backoff with Jitter** (RetryPolicy.swift): + +```swift +struct RetryPolicy { + let maxAttempts: Int = 3 + let baseDelay: TimeInterval = 1.0 + let maxDelay: TimeInterval = 30.0 + let jitter: Bool = true + + func execute(operation: () async throws -> T) async throws -> T { + // Implements exponential backoff: 1s, 2s, 4s... + // With jitter to avoid thundering herd + } +} +``` + +**Structured Logging** (CelestraLogger.swift): + +```swift +import os + +enum CelestraLogger { + static let cloudkit = Logger(subsystem: "com.brightdigit.Celestra", category: "cloudkit") + static let rss = Logger(subsystem: "com.brightdigit.Celestra", category: "rss") + static let operations = Logger(subsystem: "com.brightdigit.Celestra", category: "operations") + static let errors = Logger(subsystem: "com.brightdigit.Celestra", category: "errors") +} +``` + +**Integration Points**: +- RSS feed fetching with retry and timeout handling +- CloudKit batch operations with per-batch retry +- Query operations with transient error recovery +- User-facing error messages with recovery suggestions + +## Incremental Update System + +### Content Change Detection + +**Implementation** (UpdateCommand.swift): + +```swift +// Separate articles into new vs modified +for article in articles { + if let existing = existingMap[article.guid] { + // Check if content changed + if existing.contentHash != article.contentHash { + modifiedArticles.append(article.withRecordName(existing.recordName!)) + } + } else { + newArticles.append(article) + } +} + +// Create new articles +if !newArticles.isEmpty { + let result = try await service.createArticles(newArticles) + print(" ✅ Created \(result.successCount) new article(s)") +} + +// Update modified articles +if !modifiedArticles.isEmpty { + let result = try await service.updateArticles(modifiedArticles) + print(" 🔄 Updated \(result.successCount) modified article(s)") +} +``` + +**Benefits**: +- Detects content changes using SHA256 contentHash +- Only updates articles when content actually changes +- Reduces unnecessary CloudKit write operations +- Preserves CloudKit metadata (creation date, etc.) + +### Update Operations + +**New Method** (CloudKitService+Celestra.swift): + +```swift +func updateArticles(_ articles: [PublicArticle]) async throws -> BatchOperationResult { + // Filters articles with recordName + // Chunks into 200-record batches + // Uses RecordOperation.update + // Tracks success/failure per batch +} +``` + +## Web Etiquette Features + +Celestra implements comprehensive web etiquette best practices to be a respectful RSS feed client. + +### Rate Limiting + +**Implementation**: Configurable delays between feed fetches to avoid overwhelming feed servers. + +**Default Behavior**: +- 2-second delay between different feeds +- 5-second delay when fetching from the same domain +- Respects feed's `minUpdateInterval` when available + +**Usage**: +```bash +# Use default 2-second delay +celestra update + +# Custom delay (5 seconds) +celestra update --delay 5.0 +``` + +**Technical Details**: +- Implemented via `RateLimiter` Actor for thread-safe delay tracking +- Per-domain tracking prevents hammering same server +- Async/await pattern ensures non-blocking operation + +### Robots.txt Checking + +**Implementation**: Fetches and parses robots.txt before accessing feed URLs. + +**Behavior**: +- Checks robots.txt once per domain, cached for 24 hours +- Matches User-Agent "Celestra" and wildcard "*" rules +- Defaults to "allow" if robots.txt is unavailable (fail-open approach) +- Can be bypassed for testing with `--skip-robots-check` + +**Usage**: +```bash +# Normal operation (checks robots.txt) +celestra update + +# Skip robots.txt for local testing +celestra update --skip-robots-check +``` + +**Technical Details**: +- Implemented via `RobotsTxtService` Actor +- Parses User-Agent sections, Disallow rules, and Crawl-delay directives +- Network errors default to "allow" rather than blocking feeds + +### Conditional HTTP Requests + +**Implementation**: Uses If-Modified-Since and If-None-Match headers to save bandwidth. + +**Benefits**: +- Reduces data transfer when feeds haven't changed +- Returns 304 Not Modified for unchanged content +- Stores `lastModified` and `etag` headers in Feed records + +**Technical Details**: +```swift +// Sends conditional headers +GET /feed.xml HTTP/1.1 +If-Modified-Since: Wed, 13 Nov 2024 10:00:00 GMT +If-None-Match: "abc123-etag" +User-Agent: Celestra/1.0 (MistKit RSS Reader; +https://github.com/brightdigit/MistKit) + +// Server responds with 304 if unchanged +HTTP/1.1 304 Not Modified +``` + +**Feed Model Support**: +- `lastModified: String?` - Stores Last-Modified header +- `etag: String?` - Stores ETag header +- Automatically sent on subsequent requests + +### Failure Tracking + +**Implementation**: Tracks consecutive failures per feed for circuit breaker pattern. + +**Feed Model Fields**: +- `failureCount: Int64` - Consecutive failure counter +- `lastFailureReason: String?` - Last error message +- Reset to 0 on successful fetch + +**Usage**: +```bash +# Skip feeds with more than 3 consecutive failures +celestra update --max-failures 3 +``` + +**Benefits**: +- Identifies problematic feeds +- Prevents wasting resources on persistently broken feeds +- Provides debugging information via `lastFailureReason` + +**Future Enhancement**: Auto-disable feeds after threshold (not yet implemented) + +### Custom User-Agent + +**Implementation**: Identifies as a polite RSS client with contact information. + +**User-Agent String**: +``` +Celestra/1.0 (MistKit RSS Reader; +https://github.com/brightdigit/MistKit) +``` + +**Benefits**: +- Feed publishers can identify traffic source +- Contact URL for questions or concerns +- Follows best practices for web scraping etiquette + +### Feed Update Interval Tracking + +**Implementation**: Infrastructure to respect feed's requested update frequency. + +**Feed Model Field**: +- `minUpdateInterval: TimeInterval?` - Minimum seconds between updates + +**Sources** (Priority Order): +1. RSS `` tag (minutes) +2. Syndication module `` + `` +3. HTTP `Cache-Control: max-age` headers +4. Default: No minimum (respect global rate limit only) + +**Current Status**: +- ✅ Field exists in Feed model +- ✅ Stored and retrieved from CloudKit +- ✅ Respected by RateLimiter when present +- ✅ Used to skip feeds within update window +- ⏳ RSS parsing not yet implemented (TODO in RSSFetcherService) + +**Example Usage**: +```bash +# Feed with minUpdateInterval will be skipped if updated recently +celestra update + +# Output: +# [1/5] 📰 Tech News Feed +# ⏭️ Skipped (update requested in 45 minutes) +``` + +### Command Examples + +```bash +# Basic update with all web etiquette features +celestra update + +# Custom rate limit and failure filtering +celestra update --delay 3.0 --max-failures 5 + +# Update only feeds last attempted before a specific date +celestra update --last-attempted-before 2025-01-01T00:00:00Z + +# Combined filters +celestra update \ + --delay 5.0 \ + --max-failures 3 \ + --last-attempted-before 2025-01-01T00:00:00Z \ + --min-popularity 10 +``` + +## Future Improvements + +### Potential Enhancements + +**1. RSS TTL Parsing** (Recommended): +Parse RSS `` and `` tags to populate `minUpdateInterval`: +```swift +// In RSSFetcherService.parseUpdateInterval() +if let ttl = feed.ttl { + return TimeInterval(ttl * 60) // Convert minutes to seconds +} + +if let period = feed.updatePeriod, let frequency = feed.updateFrequency { + let periodSeconds = periodToSeconds(period) + return periodSeconds / Double(frequency) +} +``` + +**Status**: Infrastructure exists, SyndiKit integration needed + +**2. Article TTL from Feed Interval**: +Use feed's `minUpdateInterval` to calculate article expiration: +```swift +// Instead of hardcoded 30 days +let ttl = feed.minUpdateInterval ?? (30 * 24 * 60 * 60) +let article = Article( + // ... + expiresAt: Date().addingTimeInterval(ttl * 5) // 5x multiplier +) +``` + +**Status**: `expiresAt` field exists, calculation logic needs update + +**3. Cleanup Command**: +Add command to delete expired articles: +```bash +celestra cleanup-expired +``` + +**Status**: Schema supports queries, command not implemented + +**4. Auto-Disable Failed Feeds**: +Automatically set `isActive = false` after reaching failure threshold: +```swift +if feed.failureCount >= 10 { + updatedFeed.isActive = false + print(" 🔴 Feed auto-disabled after 10 consecutive failures") +} +``` + +**Status**: Tracking exists, auto-disable logic not implemented + +**5. CKReference Relationships** (Optional): +Switch from string-based to proper CloudKit references: +```swift +// Instead of: +fields["feedRecordName"] = .string(feedRecordName) + +// Use: +fields["feed"] = .reference(FieldValue.Reference(recordName: feedRecordName)) +``` + +**Trade-off Analysis**: +- **String-based (Current)**: + - ✅ Simpler querying: `filter: .equals("feedRecordName", .string(name))` + - ✅ Easier to understand for developers + - ✅ More explicit relationship handling + - ❌ Manual cascade delete implementation + - ❌ No type safety enforcement + +- **CKReference-based**: + - ✅ Type safety and CloudKit validation + - ✅ Automatic cascade deletes + - ✅ Better relationship queries + - ❌ More complex querying + - ❌ Additional abstraction layer needed + +**Decision**: Kept string-based for educational simplicity and explicit code patterns. For production apps handling complex relationship graphs, CKReference is recommended. + +**3. Circuit Breaker Pattern**: +For feeds with persistent failures: +```swift +actor CircuitBreaker { + private var failureCount = 0 + private let threshold = 5 + + var isOpen: Bool { + failureCount >= threshold + } + + func recordFailure() { + failureCount += 1 + } +} +``` + +## Implementation Timeline + +**Phase 1** (Completed): +- ✅ Schema design with automated deployment +- ✅ RSS fetching with SyndiKit integration +- ✅ Basic CloudKit operations (create, query, update, delete) +- ✅ CLI with ArgumentParser subcommands + +**Phase 2** (Completed): +- ✅ Duplicate detection with GUID-based queries +- ✅ Content hash fallback implementation +- ✅ Schema improvements (description, isActive, contentHash fields) +- ✅ Comprehensive documentation + +**Phase 3** (Completed): +- ✅ Error handling with comprehensive CelestraError types +- ✅ Structured logging using os.Logger +- ✅ Batch operations with 200-record chunking +- ✅ BatchOperationResult for success/failure tracking +- ✅ Incremental update system (create + update) +- ✅ Content change detection via contentHash +- ✅ Relationship design documentation +- ✅ Web etiquette: Rate limiting with configurable delays +- ✅ Web etiquette: Robots.txt checking and parsing +- ✅ Web etiquette: Conditional HTTP requests (If-Modified-Since/ETag) +- ✅ Web etiquette: Failure tracking for circuit breaker pattern +- ✅ Web etiquette: Custom User-Agent header +- ✅ Feed update interval infrastructure (`minUpdateInterval`) + +**Phase 4** (Future): +- ⏳ RSS TTL parsing (``, ``) +- ⏳ Article TTL calculated from feed interval +- ⏳ Cleanup command for expired articles +- ⏳ Auto-disable feeds after failure threshold +- ⏳ Test suite with mock CloudKit service +- ⏳ Performance monitoring and metrics + +## Conclusion + +Celestra successfully demonstrates MistKit's core capabilities while maintaining simplicity for educational purposes. The implementation balances real-world practicality with code clarity, making it an effective reference for developers learning CloudKit integration patterns. + +For more advanced patterns, see the Bushel example and `BUSHEL_PATTERNS.md`. diff --git a/Examples/Celestra/Package.resolved b/Examples/Celestra/Package.resolved new file mode 100644 index 00000000..ada192aa --- /dev/null +++ b/Examples/Celestra/Package.resolved @@ -0,0 +1,95 @@ +{ + "pins" : [ + { + "identity" : "swift-argument-parser", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-argument-parser.git", + "state" : { + "revision" : "cdd0ef3755280949551dc26dee5de9ddeda89f54", + "version" : "1.6.2" + } + }, + { + "identity" : "swift-asn1", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-asn1.git", + "state" : { + "revision" : "40d25bbb2fc5b557a9aa8512210bded327c0f60d", + "version" : "1.5.0" + } + }, + { + "identity" : "swift-collections", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-collections", + "state" : { + "revision" : "7b847a3b7008b2dc2f47ca3110d8c782fb2e5c7e", + "version" : "1.3.0" + } + }, + { + "identity" : "swift-crypto", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-crypto.git", + "state" : { + "revision" : "95ba0316a9b733e92bb6b071255ff46263bbe7dc", + "version" : "3.15.1" + } + }, + { + "identity" : "swift-http-types", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-http-types", + "state" : { + "revision" : "45eb0224913ea070ec4fba17291b9e7ecf4749ca", + "version" : "1.5.1" + } + }, + { + "identity" : "swift-log", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-log.git", + "state" : { + "revision" : "ce592ae52f982c847a4efc0dd881cc9eb32d29f2", + "version" : "1.6.4" + } + }, + { + "identity" : "swift-openapi-runtime", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-openapi-runtime", + "state" : { + "revision" : "7722cf8eac05c1f1b5b05895b04cfcc29576d9be", + "version" : "1.8.3" + } + }, + { + "identity" : "swift-openapi-urlsession", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-openapi-urlsession", + "state" : { + "revision" : "279aa6b77be6aa842a4bf3c45fa79fa15edf3e07", + "version" : "1.2.0" + } + }, + { + "identity" : "syndikit", + "kind" : "remoteSourceControl", + "location" : "https://github.com/brightdigit/SyndiKit.git", + "state" : { + "revision" : "1b7991213a1562bb6d93ffedf58533c06fe626f5", + "version" : "0.6.1" + } + }, + { + "identity" : "xmlcoder", + "kind" : "remoteSourceControl", + "location" : "https://github.com/brightdigit/XMLCoder", + "state" : { + "revision" : "8ba70f27664ea8c8b7f38fb4c6f2fd4c129eb9c5", + "version" : "1.0.0-alpha.1" + } + } + ], + "version" : 2 +} diff --git a/Examples/Celestra/Package.swift b/Examples/Celestra/Package.swift new file mode 100644 index 00000000..0ddd1e25 --- /dev/null +++ b/Examples/Celestra/Package.swift @@ -0,0 +1,104 @@ +// swift-tools-version: 6.2 + +// swiftlint:disable explicit_acl explicit_top_level_acl + +import PackageDescription + +// MARK: - Swift Settings Configuration + +let swiftSettings: [SwiftSetting] = [ + // Swift 6.2 Upcoming Features (not yet enabled by default) + // SE-0335: Introduce existential `any` + .enableUpcomingFeature("ExistentialAny"), + // SE-0409: Access-level modifiers on import declarations + .enableUpcomingFeature("InternalImportsByDefault"), + // SE-0444: Member import visibility (Swift 6.1+) + .enableUpcomingFeature("MemberImportVisibility"), + // SE-0413: Typed throws + .enableUpcomingFeature("FullTypedThrows"), + + // Experimental Features (stable enough for use) + // SE-0426: BitwiseCopyable protocol + .enableExperimentalFeature("BitwiseCopyable"), + // SE-0432: Borrowing and consuming pattern matching for noncopyable types + .enableExperimentalFeature("BorrowingSwitch"), + // Extension macros + .enableExperimentalFeature("ExtensionMacros"), + // Freestanding expression macros + .enableExperimentalFeature("FreestandingExpressionMacros"), + // Init accessors + .enableExperimentalFeature("InitAccessors"), + // Isolated any types + .enableExperimentalFeature("IsolatedAny"), + // Move-only classes + .enableExperimentalFeature("MoveOnlyClasses"), + // Move-only enum deinits + .enableExperimentalFeature("MoveOnlyEnumDeinits"), + // SE-0429: Partial consumption of noncopyable values + .enableExperimentalFeature("MoveOnlyPartialConsumption"), + // Move-only resilient types + .enableExperimentalFeature("MoveOnlyResilientTypes"), + // Move-only tuples + .enableExperimentalFeature("MoveOnlyTuples"), + // SE-0427: Noncopyable generics + .enableExperimentalFeature("NoncopyableGenerics"), + // One-way closure parameters + // .enableExperimentalFeature("OneWayClosureParameters"), + // Raw layout types + .enableExperimentalFeature("RawLayout"), + // Reference bindings + .enableExperimentalFeature("ReferenceBindings"), + // SE-0430: sending parameter and result values + .enableExperimentalFeature("SendingArgsAndResults"), + // Symbol linkage markers + .enableExperimentalFeature("SymbolLinkageMarkers"), + // Transferring args and results + .enableExperimentalFeature("TransferringArgsAndResults"), + // SE-0393: Value and Type Parameter Packs + .enableExperimentalFeature("VariadicGenerics"), + // Warn unsafe reflection + .enableExperimentalFeature("WarnUnsafeReflection"), + + // Enhanced compiler checking + .unsafeFlags([ + // Enable concurrency warnings + "-warn-concurrency", + // Enable actor data race checks + "-enable-actor-data-race-checks", + // Complete strict concurrency checking + "-strict-concurrency=complete", + // Enable testing support + "-enable-testing", + // Warn about functions with >100 lines + "-Xfrontend", "-warn-long-function-bodies=100", + // Warn about slow type checking expressions + "-Xfrontend", "-warn-long-expression-type-checking=100" + ]) +] + +let package = Package( + name: "Celestra", + platforms: [.macOS(.v14)], + products: [ + .executable(name: "celestra", targets: ["Celestra"]) + ], + dependencies: [ + .package(path: "../.."), // MistKit + .package(url: "https://github.com/brightdigit/SyndiKit.git", from: "0.6.0"), + .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.5.0"), + .package(url: "https://github.com/apple/swift-log.git", from: "1.0.0") + ], + targets: [ + .executableTarget( + name: "Celestra", + dependencies: [ + .product(name: "MistKit", package: "MistKit"), + .product(name: "SyndiKit", package: "SyndiKit"), + .product(name: "ArgumentParser", package: "swift-argument-parser"), + .product(name: "Logging", package: "swift-log") + ], + swiftSettings: swiftSettings + ) + ] +) +// swiftlint:enable explicit_acl explicit_top_level_acl diff --git a/Examples/Celestra/README.md b/Examples/Celestra/README.md new file mode 100644 index 00000000..d8d1cf2f --- /dev/null +++ b/Examples/Celestra/README.md @@ -0,0 +1,358 @@ +# Celestra - RSS Reader with CloudKit Sync + +Celestra is a command-line RSS reader that demonstrates MistKit's query filtering and sorting features by managing RSS feeds in CloudKit's public database. + +## Features + +- **RSS Parsing with SyndiKit**: Parse RSS and Atom feeds using BrightDigit's SyndiKit library +- **Add RSS Feeds**: Parse and validate RSS feeds, then store metadata in CloudKit +- **Duplicate Detection**: Automatically detect and skip duplicate articles using GUID-based queries +- **Filtered Updates**: Query feeds using MistKit's `QueryFilter` API (by date and popularity) +- **Batch Operations**: Upload multiple articles efficiently using non-atomic operations +- **Server-to-Server Auth**: Demonstrates CloudKit authentication for backend services +- **Record Modification**: Uses MistKit's new public record modification APIs + +## Prerequisites + +1. **Apple Developer Account** with CloudKit access +2. **CloudKit Container** configured in Apple Developer Console +3. **Server-to-Server Key** generated for CloudKit access +4. **Swift 5.9+** and **macOS 13.0+** (required by SyndiKit) + +## CloudKit Setup + +You can set up the CloudKit schema either automatically using `cktool` (recommended) or manually through the CloudKit Dashboard. + +### Option 1: Automated Setup (Recommended) + +Use the provided script to automatically import the schema: + +```bash +# Set your CloudKit credentials +export CLOUDKIT_CONTAINER_ID="iCloud.com.brightdigit.Celestra" +export CLOUDKIT_TEAM_ID="YOUR_TEAM_ID" +export CLOUDKIT_ENVIRONMENT="development" + +# Run the setup script +cd Examples/Celestra +./Scripts/setup-cloudkit-schema.sh +``` + +For detailed instructions, see [CLOUDKIT_SCHEMA_SETUP.md](./CLOUDKIT_SCHEMA_SETUP.md). + +### Option 2: Manual Setup + +#### 1. Create CloudKit Container + +1. Go to [Apple Developer Console](https://developer.apple.com) +2. Navigate to CloudKit Dashboard +3. Create a new container (e.g., `iCloud.com.brightdigit.Celestra`) + +#### 2. Configure Record Types + +In CloudKit Dashboard, create these record types in the **Public Database**: + +#### Feed Record Type +| Field Name | Field Type | Indexed | +|------------|------------|---------| +| feedURL | String | Yes (Queryable, Sortable) | +| title | String | Yes (Searchable) | +| description | String | No | +| totalAttempts | Int64 | No | +| successfulAttempts | Int64 | No | +| usageCount | Int64 | Yes (Queryable, Sortable) | +| lastAttempted | Date/Time | Yes (Queryable, Sortable) | +| isActive | Int64 | Yes (Queryable) | + +#### Article Record Type +| Field Name | Field Type | Indexed | +|------------|------------|---------| +| feedRecordName | String | Yes (Queryable, Sortable) | +| title | String | Yes (Searchable) | +| link | String | No | +| description | String | No | +| author | String | Yes (Queryable) | +| pubDate | Date/Time | Yes (Queryable, Sortable) | +| guid | String | Yes (Queryable, Sortable) | +| contentHash | String | Yes (Queryable) | +| fetchedAt | Date/Time | Yes (Queryable, Sortable) | +| expiresAt | Date/Time | Yes (Queryable, Sortable) | + +#### 3. Generate Server-to-Server Key + +1. In CloudKit Dashboard, go to **API Tokens** +2. Click **Server-to-Server Keys** +3. Generate a new key +4. Download the `.pem` file and save it securely +5. Note the **Key ID** (you'll need this) + +## Installation + +### 1. Clone Repository + +```bash +git clone https://github.com/brightdigit/MistKit.git +cd MistKit/Examples/Celestra +``` + +### 2. Configure Environment + +```bash +# Copy the example environment file +cp .env.example .env + +# Edit .env with your CloudKit credentials +nano .env +``` + +Update `.env` with your values: + +```bash +CLOUDKIT_CONTAINER_ID=iCloud.com.brightdigit.Celestra +CLOUDKIT_KEY_ID=your-key-id-here +CLOUDKIT_PRIVATE_KEY_PATH=/path/to/eckey.pem +CLOUDKIT_ENVIRONMENT=development +``` + +### 3. Build + +```bash +swift build +``` + +## Usage + +Source your environment variables before running commands: + +```bash +source .env +``` + +### Add a Feed + +Add a new RSS feed to CloudKit: + +```bash +swift run celestra add-feed https://example.com/feed.xml +``` + +Example output: +``` +🌐 Fetching RSS feed: https://example.com/feed.xml +✅ Found feed: Example Blog + Articles: 25 +✅ Feed added to CloudKit + Record Name: ABC123-DEF456-GHI789 + Zone: default +``` + +### Update Feeds + +Fetch and update all feeds: + +```bash +swift run celestra update +``` + +Update with filters (demonstrates QueryFilter API): + +```bash +# Update feeds last attempted before a specific date +swift run celestra update --last-attempted-before 2025-01-01T00:00:00Z + +# Update only popular feeds (minimum 10 usage count) +swift run celestra update --min-popularity 10 + +# Combine filters +swift run celestra update \ + --last-attempted-before 2025-01-01T00:00:00Z \ + --min-popularity 5 +``` + +Example output: +``` +🔄 Starting feed update... + Filter: last attempted before 2025-01-01T00:00:00Z + Filter: minimum popularity 5 +📋 Querying feeds... +✅ Found 3 feed(s) to update + +[1/3] 📰 Example Blog + ✅ Fetched 25 articles + ℹ️ Skipped 20 duplicate(s) + ✅ Uploaded 5 new article(s) + +[2/3] 📰 Tech News + ✅ Fetched 15 articles + ℹ️ Skipped 10 duplicate(s) + ✅ Uploaded 5 new article(s) + +[3/3] 📰 Daily Updates + ✅ Fetched 10 articles + ℹ️ No new articles to upload + +✅ Update complete! + Success: 3 + Errors: 0 +``` + +### Clear All Data + +Delete all feeds and articles from CloudKit: + +```bash +swift run celestra clear --confirm +``` + +## How It Demonstrates MistKit Features + +### 1. Query Filtering (`QueryFilter`) + +The `update` command demonstrates filtering with date and numeric comparisons: + +```swift +// In CloudKitService+Celestra.swift +var filters: [QueryFilter] = [] + +// Date comparison filter +if let cutoff = lastAttemptedBefore { + filters.append(.lessThan("lastAttempted", .date(cutoff))) +} + +// Numeric comparison filter +if let minPop = minPopularity { + filters.append(.greaterThanOrEquals("usageCount", .int64(minPop))) +} +``` + +### 2. Query Sorting (`QuerySort`) + +Results are automatically sorted by popularity (descending): + +```swift +let records = try await queryRecords( + recordType: "Feed", + filters: filters.isEmpty ? nil : filters, + sortBy: [.descending("usageCount")], // Sort by popularity + limit: limit +) +``` + +### 3. Batch Operations + +Articles are uploaded in batches using non-atomic operations for better performance: + +```swift +// Non-atomic allows partial success +return try await modifyRecords(operations: operations, atomic: false) +``` + +### 4. Duplicate Detection + +Celestra automatically detects and skips duplicate articles during feed updates: + +```swift +// In UpdateCommand.swift +// 1. Extract GUIDs from fetched articles +let guids = articles.map { $0.guid } + +// 2. Query existing articles by GUID +let existingArticles = try await service.queryArticlesByGUIDs( + guids, + feedRecordName: recordName +) + +// 3. Filter out duplicates +let existingGUIDs = Set(existingArticles.map { $0.guid }) +let newArticles = articles.filter { !existingGUIDs.contains($0.guid) } + +// 4. Only upload new articles +if !newArticles.isEmpty { + _ = try await service.createArticles(newArticles) +} +``` + +#### How Duplicate Detection Works + +1. **GUID-Based Identification**: Each article has a unique GUID (Globally Unique Identifier) from the RSS feed +2. **Pre-Upload Query**: Before uploading, Celestra queries CloudKit for existing articles with the same GUIDs +3. **Content Hash Fallback**: Articles also include a SHA256 content hash for duplicate detection when GUIDs are unreliable +4. **Efficient Filtering**: Uses Set-based filtering for O(n) performance with large article counts + +This ensures you can run `update` multiple times without creating duplicate articles in CloudKit. + +### 5. Server-to-Server Authentication + +Demonstrates CloudKit authentication without user interaction: + +```swift +let tokenManager = try ServerToServerAuthManager( + keyID: keyID, + pemString: privateKeyPEM +) + +let service = try CloudKitService( + containerIdentifier: containerID, + tokenManager: tokenManager, + environment: environment, + database: .public +) +``` + +## Architecture + +``` +Celestra/ +├── Models/ +│ ├── Feed.swift # Feed metadata model +│ └── Article.swift # Article model +├── Services/ +│ ├── RSSFetcherService.swift # RSS parsing with SyndiKit +│ └── CloudKitService+Celestra.swift # CloudKit operations +├── Commands/ +│ ├── AddFeedCommand.swift # Add feed command +│ ├── UpdateCommand.swift # Update feeds command (demonstrates filters) +│ └── ClearCommand.swift # Clear data command +└── Celestra.swift # Main CLI entry point +``` + +## Documentation + +### CloudKit Schema Guides + +Celestra uses CloudKit's text-based schema language for database management. See these guides for working with schemas: + +- **[AI Schema Workflow Guide](./AI_SCHEMA_WORKFLOW.md)** - Comprehensive guide for AI agents and developers to understand, design, modify, and validate CloudKit schemas +- **[CloudKit Schema Setup](./CLOUDKIT_SCHEMA_SETUP.md)** - Detailed setup instructions for both automated (cktool) and manual schema configuration +- **[Schema Quick Reference](../SCHEMA_QUICK_REFERENCE.md)** - One-page cheat sheet with syntax, patterns, and common operations +- **[Task Master Schema Integration](../../.taskmaster/docs/schema-design-workflow.md)** - Integrate schema design into Task Master workflows + +### Additional Resources + +- **[Claude Code Schema Reference](../../.claude/docs/cloudkit-schema-reference.md)** - Quick reference auto-loaded in Claude Code sessions +- **[Apple's Schema Language Documentation](../../.claude/docs/sosumi-cloudkit-schema-source.md)** - Official CloudKit Schema Language reference from Apple +- **[Implementation Notes](./IMPLEMENTATION_NOTES.md)** - Design decisions and patterns used in Celestra + +## Troubleshooting + +### Authentication Errors + +- Verify your Key ID is correct +- Ensure the private key file exists and is readable +- Check that the container ID matches your CloudKit container + +### Missing Record Types + +- Make sure you created the record types in CloudKit Dashboard +- Verify you're using the correct database (public) +- Check the environment setting (development vs production) + +### Build Errors + +- Ensure Swift 5.9+ is installed: `swift --version` +- Clean and rebuild: `swift package clean && swift build` +- Update dependencies: `swift package update` + +## License + +MIT License - See main MistKit repository for details. diff --git a/Examples/Celestra/Scripts/setup-cloudkit-schema.sh b/Examples/Celestra/Scripts/setup-cloudkit-schema.sh new file mode 100755 index 00000000..0d5ce7a0 --- /dev/null +++ b/Examples/Celestra/Scripts/setup-cloudkit-schema.sh @@ -0,0 +1,161 @@ +#!/bin/bash + +# CloudKit Schema Setup Script +# This script imports the Celestra schema into your CloudKit container + +set -eo pipefail + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +echo "========================================" +echo "CloudKit Schema Setup for Celestra" +echo "========================================" +echo "" + +# Check if cktool is available +if ! command -v xcrun &> /dev/null || ! xcrun cktool --version &> /dev/null; then + echo -e "${RED}ERROR: cktool is not available.${NC}" + echo "cktool is distributed with Xcode 13+ and is required for schema import." + echo "Please install Xcode 13 or later." + exit 1 +fi + +echo -e "${GREEN}✓${NC} cktool is available" +echo "" + +# Check for CloudKit Management Token +echo "Checking for CloudKit Management Token..." +if ! xcrun cktool get-teams 2>&1 | grep -qE "^[A-Z0-9]+:"; then + echo -e "${RED}ERROR: CloudKit Management Token not configured.${NC}" + echo "" + echo "You need to save a CloudKit Web Services Management Token for cktool first." + echo "" + echo "Steps to configure:" + echo " 1. Go to: https://icloud.developer.apple.com/dashboard/" + echo " 2. Select your container" + echo " 3. Go to 'API Access' → 'CloudKit Web Services'" + echo " 4. Generate a Management Token (not Server-to-Server Key)" + echo " 5. Copy the token" + echo " 6. Save it with cktool:" + echo "" + echo " xcrun cktool save-token" + echo "" + echo " 7. Paste your Management Token when prompted" + echo "" + echo "Note: Management Token is for schema operations (cktool)." + echo " Server-to-Server Key is for runtime API operations (celestra commands)." + echo "" + exit 1 +fi + +echo -e "${GREEN}✓${NC} CloudKit Management Token is configured" +echo "" + +# Check for required parameters +if [ -z "$CLOUDKIT_CONTAINER_ID" ]; then + echo -e "${YELLOW}CLOUDKIT_CONTAINER_ID not set.${NC}" + read -p "Enter your CloudKit Container ID [iCloud.com.brightdigit.Celestra]: " CLOUDKIT_CONTAINER_ID + CLOUDKIT_CONTAINER_ID=${CLOUDKIT_CONTAINER_ID:-iCloud.com.brightdigit.Celestra} +fi + +if [ -z "$CLOUDKIT_TEAM_ID" ]; then + echo -e "${YELLOW}CLOUDKIT_TEAM_ID not set.${NC}" + read -p "Enter your Apple Developer Team ID (10-character ID): " CLOUDKIT_TEAM_ID +fi + +# Validate required parameters +if [ -z "$CLOUDKIT_CONTAINER_ID" ] || [ -z "$CLOUDKIT_TEAM_ID" ]; then + echo -e "${RED}ERROR: Container ID and Team ID are required.${NC}" + exit 1 +fi + +# Default to development environment +ENVIRONMENT=${CLOUDKIT_ENVIRONMENT:-development} + +echo "" +echo "Configuration:" +echo " Container ID: $CLOUDKIT_CONTAINER_ID" +echo " Team ID: $CLOUDKIT_TEAM_ID" +echo " Environment: $ENVIRONMENT" +echo "" + +# Check if schema file exists +SCHEMA_FILE="$(dirname "$0")/../schema.ckdb" +if [ ! -f "$SCHEMA_FILE" ]; then + echo -e "${RED}ERROR: Schema file not found at $SCHEMA_FILE${NC}" + exit 1 +fi + +echo -e "${GREEN}✓${NC} Schema file found: $SCHEMA_FILE" +echo "" + +# Validate schema +echo "Validating schema..." +if xcrun cktool validate-schema \ + --team-id "$CLOUDKIT_TEAM_ID" \ + --container-id "$CLOUDKIT_CONTAINER_ID" \ + --environment "$ENVIRONMENT" \ + --file "$SCHEMA_FILE" 2>&1; then + echo -e "${GREEN}✓${NC} Schema validation passed" +else + echo -e "${RED}✗${NC} Schema validation failed" + exit 1 +fi + +echo "" + +# Confirm before import +echo -e "${YELLOW}Warning: This will import the schema into your CloudKit container.${NC}" +echo "This operation will create/modify record types in the $ENVIRONMENT environment." +echo "" +read -p "Continue? (y/n) " -n 1 -r +echo +if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo "Import cancelled." + exit 0 +fi + +# Import schema +echo "" +echo "Importing schema to CloudKit..." +if xcrun cktool import-schema \ + --team-id "$CLOUDKIT_TEAM_ID" \ + --container-id "$CLOUDKIT_CONTAINER_ID" \ + --environment "$ENVIRONMENT" \ + --file "$SCHEMA_FILE" 2>&1; then + echo "" + echo -e "${GREEN}✓✓✓ Schema import successful! ✓✓✓${NC}" + echo "" + echo "Your CloudKit container now has the following record types:" + echo " • Feed" + echo " • Article" + echo "" + echo "Next steps:" + echo " 1. Get your Server-to-Server Key:" + echo " a. Go to: https://icloud.developer.apple.com/dashboard/" + echo " b. Navigate to: API Access → Server-to-Server Keys" + echo " c. Create a new key and download the private key .pem file" + echo "" + echo " 2. Configure your .env file with CloudKit credentials" + echo " 3. Run 'swift run celestra add-feed ' to add an RSS feed" + echo " 4. Run 'swift run celestra update' to fetch and sync articles" + echo " 5. Verify data in CloudKit Dashboard: https://icloud.developer.apple.com/" + echo "" + echo " Important: Never commit .pem files to version control!" + echo "" +else + echo "" + echo -e "${RED}✗✗✗ Schema import failed ✗✗✗${NC}" + echo "" + echo "Common issues:" + echo " • Authentication token not saved (run: xcrun cktool save-token)" + echo " • Incorrect container ID or team ID" + echo " • Missing permissions in CloudKit Dashboard" + echo "" + echo "For help, see: https://developer.apple.com/documentation/cloudkit" + exit 1 +fi diff --git a/Examples/Celestra/Sources/Celestra/Celestra.swift b/Examples/Celestra/Sources/Celestra/Celestra.swift new file mode 100644 index 00000000..adccb26f --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Celestra.swift @@ -0,0 +1,66 @@ +import ArgumentParser +import Foundation +import MistKit + +@main +struct Celestra: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "celestra", + abstract: "RSS reader that syncs to CloudKit public database", + discussion: """ + Celestra demonstrates MistKit's query filtering and sorting features by managing \ + RSS feeds in CloudKit's public database. + """, + subcommands: [ + AddFeedCommand.self, + UpdateCommand.self, + ClearCommand.self + ] + ) +} + +// MARK: - Shared Configuration + +/// Shared configuration helper for creating CloudKit service +enum CelestraConfig { + /// Create CloudKit service from environment variables + @available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) + static func createCloudKitService() throws -> CloudKitService { + // Validate required environment variables + guard let containerID = ProcessInfo.processInfo.environment["CLOUDKIT_CONTAINER_ID"] else { + throw ValidationError("CLOUDKIT_CONTAINER_ID environment variable required") + } + + guard let keyID = ProcessInfo.processInfo.environment["CLOUDKIT_KEY_ID"] else { + throw ValidationError("CLOUDKIT_KEY_ID environment variable required") + } + + guard let privateKeyPath = ProcessInfo.processInfo.environment["CLOUDKIT_PRIVATE_KEY_PATH"] + else { + throw ValidationError("CLOUDKIT_PRIVATE_KEY_PATH environment variable required") + } + + // Read private key from file + let privateKeyPEM = try String(contentsOfFile: privateKeyPath, encoding: .utf8) + + // Determine environment (development or production) + let environment: MistKit.Environment = + ProcessInfo.processInfo.environment["CLOUDKIT_ENVIRONMENT"] == "production" + ? .production + : .development + + // Create token manager for server-to-server authentication + let tokenManager = try ServerToServerAuthManager( + keyID: keyID, + pemString: privateKeyPEM + ) + + // Create and return CloudKit service + return try CloudKitService( + containerIdentifier: containerID, + tokenManager: tokenManager, + environment: environment, + database: .public + ) + } +} diff --git a/Examples/Celestra/Sources/Celestra/Commands/AddFeedCommand.swift b/Examples/Celestra/Sources/Celestra/Commands/AddFeedCommand.swift new file mode 100644 index 00000000..cc5f3fc9 --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Commands/AddFeedCommand.swift @@ -0,0 +1,55 @@ +import ArgumentParser +import Foundation +import MistKit + +struct AddFeedCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "add-feed", + abstract: "Add a new RSS feed to CloudKit", + discussion: """ + Fetches the RSS feed to validate it and extract metadata, then creates a \ + Feed record in CloudKit's public database. + """ + ) + + @Argument(help: "RSS feed URL") + var feedURL: String + + @available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) + func run() async throws { + print("🌐 Fetching RSS feed: \(feedURL)") + + // 1. Validate URL + guard let url = URL(string: feedURL) else { + throw ValidationError("Invalid feed URL") + } + + // 2. Fetch RSS content to validate and extract title + let fetcher = RSSFetcherService() + let response = try await fetcher.fetchFeed(from: url) + + guard let feedData = response.feedData else { + throw ValidationError("Feed was not modified (unexpected)") + } + + print("✅ Found feed: \(feedData.title)") + print(" Articles: \(feedData.items.count)") + + // 3. Create CloudKit service + let service = try CelestraConfig.createCloudKitService() + + // 4. Create Feed record with initial metadata + let feed = Feed( + feedURL: feedURL, + title: feedData.title, + description: feedData.description, + lastModified: response.lastModified, + etag: response.etag, + minUpdateInterval: feedData.minUpdateInterval + ) + let record = try await service.createFeed(feed) + + print("✅ Feed added to CloudKit") + print(" Record Name: \(record.recordName)") + } +} diff --git a/Examples/Celestra/Sources/Celestra/Commands/ClearCommand.swift b/Examples/Celestra/Sources/Celestra/Commands/ClearCommand.swift new file mode 100644 index 00000000..e5b9a814 --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Commands/ClearCommand.swift @@ -0,0 +1,45 @@ +import ArgumentParser +import Foundation +import MistKit + +struct ClearCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "clear", + abstract: "Delete all feeds and articles from CloudKit", + discussion: """ + Removes all Feed and Article records from the CloudKit public database. \ + Use with caution as this operation cannot be undone. + """ + ) + + @Flag(name: .long, help: "Skip confirmation prompt") + var confirm: Bool = false + + @available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) + func run() async throws { + // Require confirmation + if !confirm { + print("⚠️ This will DELETE ALL feeds and articles from CloudKit!") + print(" Run with --confirm to proceed") + print("") + print(" Example: celestra clear --confirm") + return + } + + print("🗑️ Clearing all data from CloudKit...") + + let service = try CelestraConfig.createCloudKitService() + + // Delete articles first (to avoid orphans) + print("📋 Deleting articles...") + try await service.deleteAllArticles() + print("✅ Articles deleted") + + // Delete feeds + print("📋 Deleting feeds...") + try await service.deleteAllFeeds() + print("✅ Feeds deleted") + + print("\n✅ All data cleared!") + } +} diff --git a/Examples/Celestra/Sources/Celestra/Commands/UpdateCommand.swift b/Examples/Celestra/Sources/Celestra/Commands/UpdateCommand.swift new file mode 100644 index 00000000..725637e9 --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Commands/UpdateCommand.swift @@ -0,0 +1,304 @@ +import ArgumentParser +import Foundation +import Logging +import MistKit + +struct UpdateCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "update", + abstract: "Fetch and update RSS feeds in CloudKit with web etiquette", + discussion: """ + Queries feeds from CloudKit (optionally filtered by date and popularity), \ + fetches new articles from each feed, and uploads them to CloudKit. \ + This command demonstrates MistKit's QueryFilter functionality and implements \ + web etiquette best practices including rate limiting, robots.txt checking, \ + and conditional HTTP requests. + """ + ) + + @Option(name: .long, help: "Only update feeds last attempted before this date (ISO8601 format)") + var lastAttemptedBefore: String? + + @Option(name: .long, help: "Only update feeds with minimum popularity count") + var minPopularity: Int64? + + @Option(name: .long, help: "Delay between feed fetches in seconds (default: 2.0)") + var delay: Double = 2.0 + + @Flag(name: .long, help: "Skip robots.txt checking (for testing)") + var skipRobotsCheck: Bool = false + + @Option(name: .long, help: "Skip feeds with failure count above this threshold") + var maxFailures: Int64? + + @available(macOS 13.0, *) + func run() async throws { + print("🔄 Starting feed update...") + print(" ⏱️ Rate limit: \(delay) seconds between feeds") + if skipRobotsCheck { + print(" ⚠️ Skipping robots.txt checks") + } + + // 1. Parse date filter if provided + var cutoffDate: Date? + if let dateString = lastAttemptedBefore { + let formatter = ISO8601DateFormatter() + guard let date = formatter.date(from: dateString) else { + throw ValidationError( + "Invalid date format. Use ISO8601 (e.g., 2025-01-01T00:00:00Z)" + ) + } + cutoffDate = date + print(" Filter: last attempted before \(formatter.string(from: date))") + } + + // 2. Display popularity filter if provided + if let minPop = minPopularity { + print(" Filter: minimum popularity \(minPop)") + } + + // 3. Display failure threshold if provided + if let maxFail = maxFailures { + print(" Filter: maximum failures \(maxFail)") + } + + // 4. Create services + let service = try CelestraConfig.createCloudKitService() + let fetcher = RSSFetcherService() + let robotsService = RobotsTxtService() + let rateLimiter = RateLimiter(defaultDelay: delay) + + // 5. Query feeds with filters (demonstrates QueryFilter and QuerySort) + print("📋 Querying feeds...") + var feeds = try await service.queryFeeds( + lastAttemptedBefore: cutoffDate, + minPopularity: minPopularity + ) + + // Filter by failure count if specified + if let maxFail = maxFailures { + feeds = feeds.filter { $0.failureCount <= maxFail } + } + + print("✅ Found \(feeds.count) feed(s) to update") + + // 6. Process each feed + var successCount = 0 + var errorCount = 0 + var skippedCount = 0 + var notModifiedCount = 0 + + for (index, feed) in feeds.enumerated() { + print("\n[\(index + 1)/\(feeds.count)] 📰 \(feed.title)") + + // Check if feed should be skipped based on minUpdateInterval + if let minInterval = feed.minUpdateInterval, + let lastAttempted = feed.lastAttempted { + let timeSinceLastAttempt = Date().timeIntervalSince(lastAttempted) + if timeSinceLastAttempt < minInterval { + let remainingTime = Int((minInterval - timeSinceLastAttempt) / 60) + print(" ⏭️ Skipped (update requested in \(remainingTime) minutes)") + skippedCount += 1 + continue + } + } + + // Apply rate limiting + guard let url = URL(string: feed.feedURL) else { + print(" ❌ Invalid URL") + errorCount += 1 + continue + } + + await rateLimiter.waitIfNeeded(for: url, minimumInterval: feed.minUpdateInterval) + + // Check robots.txt unless skipped + if !skipRobotsCheck { + do { + let isAllowed = try await robotsService.isAllowed(url) + if !isAllowed { + print(" 🚫 Blocked by robots.txt") + skippedCount += 1 + continue + } + } catch { + print(" ⚠️ robots.txt check failed, proceeding anyway: \(error.localizedDescription)") + } + } + + // Track attempt - start with existing values + var totalAttempts = feed.totalAttempts + 1 + var successfulAttempts = feed.successfulAttempts + var failureCount = feed.failureCount + var lastFailureReason: String? = feed.lastFailureReason + var lastModified = feed.lastModified + var etag = feed.etag + var minUpdateInterval = feed.minUpdateInterval + + do { + // Fetch RSS with conditional request support + let response = try await fetcher.fetchFeed( + from: url, + lastModified: feed.lastModified, + etag: feed.etag + ) + + // Update HTTP metadata + lastModified = response.lastModified + etag = response.etag + + // Handle 304 Not Modified + if !response.wasModified { + print(" ✅ Not modified (saved bandwidth)") + notModifiedCount += 1 + successfulAttempts += 1 + failureCount = 0 // Reset failure count on success + lastFailureReason = nil + } else { + guard let feedData = response.feedData else { + throw CelestraError.invalidFeedData("No feed data in response") + } + + print(" ✅ Fetched \(feedData.items.count) articles") + + // Update minUpdateInterval if feed provides one + if let interval = feedData.minUpdateInterval { + minUpdateInterval = interval + } + + // Convert to PublicArticle + guard let recordName = feed.recordName else { + print(" ❌ No record name") + errorCount += 1 + continue + } + + let articles = feedData.items.map { item in + Article( + feed: recordName, + title: item.title, + link: item.link, + description: item.description, + content: item.content, + author: item.author, + pubDate: item.pubDate, + guid: item.guid, + ttlDays: 30 + ) + } + + // Duplicate detection and update logic + if !articles.isEmpty { + let guids = articles.map { $0.guid } + let existingArticles = try await service.queryArticlesByGUIDs( + guids, + feedRecordName: recordName + ) + + // Create map of existing articles by GUID for fast lookup + let existingMap = Dictionary( + uniqueKeysWithValues: existingArticles.map { ($0.guid, $0) } + ) + + // Separate articles into new vs modified + var newArticles: [Article] = [] + var modifiedArticles: [Article] = [] + + for article in articles { + if let existing = existingMap[article.guid] { + // Check if content changed + if existing.contentHash != article.contentHash { + // Content changed - need to update + modifiedArticles.append(article.withRecordName(existing.recordName!)) + } + // else: content unchanged - skip + } else { + // New article + newArticles.append(article) + } + } + + let unchangedCount = articles.count - newArticles.count - modifiedArticles.count + + // Upload new articles + if !newArticles.isEmpty { + let createResult = try await service.createArticles(newArticles) + if createResult.isFullSuccess { + print(" ✅ Created \(createResult.successCount) new article(s)") + CelestraLogger.operations.info("Created \(createResult.successCount) articles for \(feed.title)") + } else { + print(" ⚠️ Created \(createResult.successCount)/\(createResult.totalProcessed) article(s)") + CelestraLogger.errors.warning("Partial create failure: \(createResult.failureCount) failures") + } + } + + // Update modified articles + if !modifiedArticles.isEmpty { + let updateResult = try await service.updateArticles(modifiedArticles) + if updateResult.isFullSuccess { + print(" 🔄 Updated \(updateResult.successCount) modified article(s)") + CelestraLogger.operations.info("Updated \(updateResult.successCount) articles for \(feed.title)") + } else { + print(" ⚠️ Updated \(updateResult.successCount)/\(updateResult.totalProcessed) article(s)") + CelestraLogger.errors.warning("Partial update failure: \(updateResult.failureCount) failures") + } + } + + // Report unchanged articles + if unchangedCount > 0 { + print(" ℹ️ Skipped \(unchangedCount) unchanged article(s)") + } + + // Report if nothing to do + if newArticles.isEmpty && modifiedArticles.isEmpty { + print(" ℹ️ No new or modified articles") + } + } + + successfulAttempts += 1 + failureCount = 0 // Reset failure count on success + lastFailureReason = nil + } + + successCount += 1 + + } catch { + print(" ❌ Error: \(error.localizedDescription)") + errorCount += 1 + failureCount += 1 + lastFailureReason = error.localizedDescription + } + + // Update feed with new metadata + let updatedFeed = Feed( + recordName: feed.recordName, + recordChangeTag: feed.recordChangeTag, + feedURL: feed.feedURL, + title: feed.title, + description: feed.description, + totalAttempts: totalAttempts, + successfulAttempts: successfulAttempts, + usageCount: feed.usageCount, + lastAttempted: Date(), + isActive: feed.isActive, + lastModified: lastModified, + etag: etag, + failureCount: failureCount, + lastFailureReason: lastFailureReason, + minUpdateInterval: minUpdateInterval + ) + + // Update feed record in CloudKit + if let recordName = feed.recordName { + _ = try await service.updateFeed(recordName: recordName, feed: updatedFeed) + } + } + + // 7. Print summary + print("\n✅ Update complete!") + print(" Success: \(successCount)") + print(" Not Modified: \(notModifiedCount)") + print(" Skipped: \(skippedCount)") + print(" Errors: \(errorCount)") + } +} diff --git a/Examples/Celestra/Sources/Celestra/Models/Article.swift b/Examples/Celestra/Sources/Celestra/Models/Article.swift new file mode 100644 index 00000000..4fcbe81b --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Models/Article.swift @@ -0,0 +1,164 @@ +import Foundation +import MistKit +import CryptoKit + +/// Represents an RSS article stored in CloudKit's public database +struct Article { + let recordName: String? + let feed: String // Feed record name (stored as REFERENCE in CloudKit) + let title: String + let link: String + let description: String? + let content: String? + let author: String? + let pubDate: Date? + let guid: String + let fetchedAt: Date + let expiresAt: Date + + /// Computed content hash for duplicate detection fallback + var contentHash: String { + let content = "\(title)|\(link)|\(guid)" + let data = Data(content.utf8) + let hash = SHA256.hash(data: data) + return hash.compactMap { String(format: "%02x", $0) }.joined() + } + + /// Convert to CloudKit record fields dictionary + func toFieldsDict() -> [String: FieldValue] { + var fields: [String: FieldValue] = [ + "feed": .reference(FieldValue.Reference(recordName: feed)), + "title": .string(title), + "link": .string(link), + "guid": .string(guid), + "contentHash": .string(contentHash), + "fetchedAt": .date(fetchedAt), + "expiresAt": .date(expiresAt) + ] + if let description = description { + fields["description"] = .string(description) + } + if let content = content { + fields["content"] = .string(content) + } + if let author = author { + fields["author"] = .string(author) + } + if let pubDate = pubDate { + fields["pubDate"] = .date(pubDate) + } + return fields + } + + /// Create from CloudKit RecordInfo + init(from record: RecordInfo) { + self.recordName = record.recordName + + // Extract feed reference + if case .reference(let ref) = record.fields["feed"] { + self.feed = ref.recordName + } else { + self.feed = "" + } + + if case .string(let value) = record.fields["title"] { + self.title = value + } else { + self.title = "" + } + + if case .string(let value) = record.fields["link"] { + self.link = value + } else { + self.link = "" + } + + if case .string(let value) = record.fields["guid"] { + self.guid = value + } else { + self.guid = "" + } + + // Extract optional string values + if case .string(let value) = record.fields["description"] { + self.description = value + } else { + self.description = nil + } + + if case .string(let value) = record.fields["content"] { + self.content = value + } else { + self.content = nil + } + + if case .string(let value) = record.fields["author"] { + self.author = value + } else { + self.author = nil + } + + // Extract date values + if case .date(let value) = record.fields["pubDate"] { + self.pubDate = value + } else { + self.pubDate = nil + } + + if case .date(let value) = record.fields["fetchedAt"] { + self.fetchedAt = value + } else { + self.fetchedAt = Date() + } + + if case .date(let value) = record.fields["expiresAt"] { + self.expiresAt = value + } else { + self.expiresAt = Date() + } + } + + /// Create new article record + init( + recordName: String? = nil, + feed: String, + title: String, + link: String, + description: String? = nil, + content: String? = nil, + author: String? = nil, + pubDate: Date? = nil, + guid: String, + ttlDays: Int = 30 + ) { + self.recordName = recordName + self.feed = feed + self.title = title + self.link = link + self.description = description + self.content = content + self.author = author + self.pubDate = pubDate + self.guid = guid + self.fetchedAt = Date() + self.expiresAt = Date().addingTimeInterval(TimeInterval(ttlDays * 24 * 60 * 60)) + } + + /// Create a copy of this article with a specific recordName + /// - Parameter recordName: The CloudKit record name to set + /// - Returns: New Article instance with the recordName set + func withRecordName(_ recordName: String) -> Article { + Article( + recordName: recordName, + feed: self.feed, + title: self.title, + link: self.link, + description: self.description, + content: self.content, + author: self.author, + pubDate: self.pubDate, + guid: self.guid, + ttlDays: 30 // Use default TTL since we can't calculate from existing dates + ) + } +} diff --git a/Examples/Celestra/Sources/Celestra/Models/BatchOperationResult.swift b/Examples/Celestra/Sources/Celestra/Models/BatchOperationResult.swift new file mode 100644 index 00000000..0899bb0e --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Models/BatchOperationResult.swift @@ -0,0 +1,60 @@ +import Foundation +import MistKit + +/// Result of a batch CloudKit operation +struct BatchOperationResult { + /// Successfully created/updated records + var successfulRecords: [RecordInfo] = [] + + /// Records that failed to process + var failedRecords: [(article: Article, error: Error)] = [] + + /// Total number of records processed (success + failure) + var totalProcessed: Int { + successfulRecords.count + failedRecords.count + } + + /// Number of successful operations + var successCount: Int { + successfulRecords.count + } + + /// Number of failed operations + var failureCount: Int { + failedRecords.count + } + + /// Success rate as a percentage (0-100) + var successRate: Double { + guard totalProcessed > 0 else { return 0 } + return Double(successCount) / Double(totalProcessed) * 100 + } + + /// Whether all operations succeeded + var isFullSuccess: Bool { + failureCount == 0 && successCount > 0 + } + + /// Whether all operations failed + var isFullFailure: Bool { + successCount == 0 && failureCount > 0 + } + + // MARK: - Mutation + + /// Append results from another batch operation + mutating func append(_ other: BatchOperationResult) { + successfulRecords.append(contentsOf: other.successfulRecords) + failedRecords.append(contentsOf: other.failedRecords) + } + + /// Append successful records + mutating func appendSuccesses(_ records: [RecordInfo]) { + successfulRecords.append(contentsOf: records) + } + + /// Append a failure + mutating func appendFailure(article: Article, error: Error) { + failedRecords.append((article, error)) + } +} diff --git a/Examples/Celestra/Sources/Celestra/Models/Feed.swift b/Examples/Celestra/Sources/Celestra/Models/Feed.swift new file mode 100644 index 00000000..3f3eb0dd --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Models/Feed.swift @@ -0,0 +1,179 @@ +import Foundation +import MistKit + +/// Represents an RSS feed stored in CloudKit's public database +struct Feed { + let recordName: String? // nil for new records + let recordChangeTag: String? // CloudKit change tag for optimistic locking + let feedURL: String + let title: String + let description: String? + let totalAttempts: Int64 + let successfulAttempts: Int64 + let usageCount: Int64 + let lastAttempted: Date? + let isActive: Bool + + // Web etiquette fields + let lastModified: String? // HTTP Last-Modified header for conditional requests + let etag: String? // ETag header for conditional requests + let failureCount: Int64 // Consecutive failure count + let lastFailureReason: String? // Last error message + let minUpdateInterval: TimeInterval? // Minimum seconds between updates (from RSS or ) + + /// Convert to CloudKit record fields dictionary + func toFieldsDict() -> [String: FieldValue] { + var fields: [String: FieldValue] = [ + "feedURL": .string(feedURL), + "title": .string(title), + "totalAttempts": .int64(Int(totalAttempts)), + "successfulAttempts": .int64(Int(successfulAttempts)), + "usageCount": .int64(Int(usageCount)), + "isActive": .int64(isActive ? 1 : 0), + "failureCount": .int64(Int(failureCount)) + ] + if let description = description { + fields["description"] = .string(description) + } + if let lastAttempted = lastAttempted { + fields["lastAttempted"] = .date(lastAttempted) + } + if let lastModified = lastModified { + fields["lastModified"] = .string(lastModified) + } + if let etag = etag { + fields["etag"] = .string(etag) + } + if let lastFailureReason = lastFailureReason { + fields["lastFailureReason"] = .string(lastFailureReason) + } + if let minUpdateInterval = minUpdateInterval { + fields["minUpdateInterval"] = .double(minUpdateInterval) + } + return fields + } + + /// Create from CloudKit RecordInfo + init(from record: RecordInfo) { + self.recordName = record.recordName + self.recordChangeTag = record.recordChangeTag + + // Extract string values + if case .string(let value) = record.fields["feedURL"] { + self.feedURL = value + } else { + self.feedURL = "" + } + + if case .string(let value) = record.fields["title"] { + self.title = value + } else { + self.title = "" + } + + if case .string(let value) = record.fields["description"] { + self.description = value + } else { + self.description = nil + } + + // Extract Int64 values + if case .int64(let value) = record.fields["totalAttempts"] { + self.totalAttempts = Int64(value) + } else { + self.totalAttempts = 0 + } + + if case .int64(let value) = record.fields["successfulAttempts"] { + self.successfulAttempts = Int64(value) + } else { + self.successfulAttempts = 0 + } + + if case .int64(let value) = record.fields["usageCount"] { + self.usageCount = Int64(value) + } else { + self.usageCount = 0 + } + + // Extract boolean as Int64 + if case .int64(let value) = record.fields["isActive"] { + self.isActive = value != 0 + } else { + self.isActive = true // Default to active + } + + // Extract date value + if case .date(let value) = record.fields["lastAttempted"] { + self.lastAttempted = value + } else { + self.lastAttempted = nil + } + + // Extract web etiquette fields + if case .string(let value) = record.fields["lastModified"] { + self.lastModified = value + } else { + self.lastModified = nil + } + + if case .string(let value) = record.fields["etag"] { + self.etag = value + } else { + self.etag = nil + } + + if case .int64(let value) = record.fields["failureCount"] { + self.failureCount = Int64(value) + } else { + self.failureCount = 0 + } + + if case .string(let value) = record.fields["lastFailureReason"] { + self.lastFailureReason = value + } else { + self.lastFailureReason = nil + } + + if case .double(let value) = record.fields["minUpdateInterval"] { + self.minUpdateInterval = value + } else { + self.minUpdateInterval = nil + } + } + + /// Create new feed record + init( + recordName: String? = nil, + recordChangeTag: String? = nil, + feedURL: String, + title: String, + description: String? = nil, + totalAttempts: Int64 = 0, + successfulAttempts: Int64 = 0, + usageCount: Int64 = 0, + lastAttempted: Date? = nil, + isActive: Bool = true, + lastModified: String? = nil, + etag: String? = nil, + failureCount: Int64 = 0, + lastFailureReason: String? = nil, + minUpdateInterval: TimeInterval? = nil + ) { + self.recordName = recordName + self.recordChangeTag = recordChangeTag + self.feedURL = feedURL + self.title = title + self.description = description + self.totalAttempts = totalAttempts + self.successfulAttempts = successfulAttempts + self.usageCount = usageCount + self.lastAttempted = lastAttempted + self.isActive = isActive + self.lastModified = lastModified + self.etag = etag + self.failureCount = failureCount + self.lastFailureReason = lastFailureReason + self.minUpdateInterval = minUpdateInterval + } +} diff --git a/Examples/Celestra/Sources/Celestra/Services/CelestraError.swift b/Examples/Celestra/Sources/Celestra/Services/CelestraError.swift new file mode 100644 index 00000000..754129ec --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Services/CelestraError.swift @@ -0,0 +1,107 @@ +import Foundation +import MistKit + +/// Comprehensive error types for Celestra RSS operations +enum CelestraError: LocalizedError { + /// CloudKit operation failed + case cloudKitError(CloudKitError) + + /// RSS feed fetch failed + case rssFetchFailed(URL, underlying: Error) + + /// Invalid feed data received + case invalidFeedData(String) + + /// Batch operation failed + case batchOperationFailed([Error]) + + /// CloudKit quota exceeded + case quotaExceeded + + /// Network unavailable + case networkUnavailable + + /// Permission denied for CloudKit operation + case permissionDenied + + /// Record not found + case recordNotFound(String) + + // MARK: - Retriability + + /// Determines if this error can be retried + var isRetriable: Bool { + switch self { + case .cloudKitError(let ckError): + return isCloudKitErrorRetriable(ckError) + case .rssFetchFailed, .networkUnavailable: + return true + case .quotaExceeded, .invalidFeedData, .batchOperationFailed, + .permissionDenied, .recordNotFound: + return false + } + } + + // MARK: - LocalizedError Conformance + + var errorDescription: String? { + switch self { + case .cloudKitError(let error): + return "CloudKit operation failed: \(error.localizedDescription)" + case .rssFetchFailed(let url, let error): + return "Failed to fetch RSS feed from \(url.absoluteString): \(error.localizedDescription)" + case .invalidFeedData(let reason): + return "Invalid feed data: \(reason)" + case .batchOperationFailed(let errors): + return "Batch operation failed with \(errors.count) error(s)" + case .quotaExceeded: + return "CloudKit quota exceeded. Please try again later." + case .networkUnavailable: + return "Network unavailable. Check your connection." + case .permissionDenied: + return "Permission denied for CloudKit operation." + case .recordNotFound(let recordName): + return "Record not found: \(recordName)" + } + } + + var recoverySuggestion: String? { + switch self { + case .quotaExceeded: + return "Wait a few minutes for CloudKit quota to reset, then try again." + case .networkUnavailable: + return "Check your internet connection and try again." + case .rssFetchFailed: + return "Verify the feed URL is accessible and try again." + case .permissionDenied: + return "Check your CloudKit permissions and API token configuration." + case .invalidFeedData: + return "Verify the feed URL returns valid RSS/Atom data." + case .cloudKitError, .batchOperationFailed, .recordNotFound: + return nil + } + } + + // MARK: - CloudKit Error Classification + + /// Determines if a CloudKit error is retriable based on error type + private func isCloudKitErrorRetriable(_ error: CloudKitError) -> Bool { + switch error { + case .httpError(let statusCode), + .httpErrorWithDetails(let statusCode, _, _), + .httpErrorWithRawResponse(let statusCode, _): + // Retry on server errors (5xx) and rate limiting (429) + // Don't retry on client errors (4xx) except 429 + return statusCode >= 500 || statusCode == 429 + case .invalidResponse, .underlyingError: + // Network-related errors are retriable + return true + case .networkError: + // Network errors are retriable + return true + case .decodingError: + // Decoding errors are not retriable (data format issue) + return false + } + } +} diff --git a/Examples/Celestra/Sources/Celestra/Services/CelestraLogger.swift b/Examples/Celestra/Sources/Celestra/Services/CelestraLogger.swift new file mode 100644 index 00000000..13878f43 --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Services/CelestraLogger.swift @@ -0,0 +1,16 @@ +import Logging + +/// Centralized logging infrastructure for Celestra using swift-log +enum CelestraLogger { + /// Logger for CloudKit operations + static let cloudkit = Logger(label: "com.brightdigit.Celestra.cloudkit") + + /// Logger for RSS feed operations + static let rss = Logger(label: "com.brightdigit.Celestra.rss") + + /// Logger for batch and async operations + static let operations = Logger(label: "com.brightdigit.Celestra.operations") + + /// Logger for error handling and diagnostics + static let errors = Logger(label: "com.brightdigit.Celestra.errors") +} diff --git a/Examples/Celestra/Sources/Celestra/Services/CloudKitService+Celestra.swift b/Examples/Celestra/Sources/Celestra/Services/CloudKitService+Celestra.swift new file mode 100644 index 00000000..34f397d5 --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Services/CloudKitService+Celestra.swift @@ -0,0 +1,307 @@ +import Foundation +import Logging +import MistKit + +/// CloudKit service extensions for Celestra operations +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +extension CloudKitService { + // MARK: - Feed Operations + + /// Create a new Feed record + func createFeed(_ feed: Feed) async throws -> RecordInfo { + CelestraLogger.cloudkit.info("📝 Creating feed: \(feed.feedURL)") + + let operation = RecordOperation.create( + recordType: "Feed", + recordName: UUID().uuidString, + fields: feed.toFieldsDict() + ) + let results = try await self.modifyRecords([operation]) + guard let record = results.first else { + throw CloudKitError.invalidResponse + } + return record + } + + /// Update an existing Feed record + func updateFeed(recordName: String, feed: Feed) async throws -> RecordInfo { + CelestraLogger.cloudkit.info("🔄 Updating feed: \(feed.feedURL)") + + let operation = RecordOperation.update( + recordType: "Feed", + recordName: recordName, + fields: feed.toFieldsDict(), + recordChangeTag: feed.recordChangeTag + ) + let results = try await self.modifyRecords([operation]) + guard let record = results.first else { + throw CloudKitError.invalidResponse + } + return record + } + + /// Query feeds with optional filters (demonstrates QueryFilter and QuerySort) + func queryFeeds( + lastAttemptedBefore: Date? = nil, + minPopularity: Int64? = nil, + limit: Int = 100 + ) async throws -> [Feed] { + var filters: [QueryFilter] = [] + + // Filter by last attempted date if provided + if let cutoff = lastAttemptedBefore { + filters.append(.lessThan("lastAttempted", .date(cutoff))) + } + + // Filter by minimum popularity if provided + if let minPop = minPopularity { + filters.append(.greaterThanOrEquals("usageCount", .int64(Int(minPop)))) + } + + // Query with filters and sort by feedURL (always queryable+sortable) + let records = try await queryRecords( + recordType: "Feed", + filters: filters.isEmpty ? nil : filters, + sortBy: [.ascending("feedURL")], // Use feedURL since usageCount might have issues + limit: limit + ) + + return records.map { Feed(from: $0) } + } + + // MARK: - Article Operations + + /// Query existing articles by GUIDs for duplicate detection + /// - Parameters: + /// - guids: Array of article GUIDs to check + /// - feedRecordName: Optional feed record name filter to scope the query + /// - Returns: Array of existing Article records matching the GUIDs + func queryArticlesByGUIDs( + _ guids: [String], + feedRecordName: String? = nil + ) async throws -> [Article] { + guard !guids.isEmpty else { + return [] + } + + var filters: [QueryFilter] = [] + + // Add feed filter if provided + if let feedName = feedRecordName { + filters.append(.equals("feed", .reference(FieldValue.Reference(recordName: feedName)))) + } + + // For small number of GUIDs, we can query directly + // For larger sets, might need multiple queries or alternative strategy + if guids.count <= 10 { + // Create OR filter for GUIDs + let guidFilters = guids.map { guid in + QueryFilter.equals("guid", .string(guid)) + } + + // Combine with feed filter if present + if !filters.isEmpty { + // When we have both feed and GUID filters, we need to do multiple queries + // or fetch all for feed and filter in memory + filters.append(.equals("guid", .string(guids[0]))) + + let records = try await queryRecords( + recordType: "Article", + filters: filters, + limit: 200, + desiredKeys: ["guid", "contentHash", "___recordID"] + ) + + // For now, fetch all articles for this feed and filter in memory + let allFeedArticles = records.map { Article(from: $0) } + let guidSet = Set(guids) + return allFeedArticles.filter { guidSet.contains($0.guid) } + } else { + // Just GUID filter - need to query each individually or use contentHash + // For simplicity, query by feedRecordName first then filter + let records = try await queryRecords( + recordType: "Article", + limit: 200, + desiredKeys: ["guid", "contentHash", "___recordID"] + ) + + let articles = records.map { Article(from: $0) } + let guidSet = Set(guids) + return articles.filter { guidSet.contains($0.guid) } + } + } else { + // For large GUID sets, fetch all articles for the feed and filter in memory + if let feedName = feedRecordName { + filters = [.equals("feed", .reference(FieldValue.Reference(recordName: feedName)))] + } + + let records = try await queryRecords( + recordType: "Article", + filters: filters.isEmpty ? nil : filters, + limit: 200, + desiredKeys: ["guid", "contentHash", "___recordID"] + ) + + let articles = records.map { Article(from: $0) } + let guidSet = Set(guids) + return articles.filter { guidSet.contains($0.guid) } + } + } + + /// Create multiple Article records in batches with retry logic + /// - Parameter articles: Articles to create + /// - Returns: Batch operation result with success/failure tracking + func createArticles(_ articles: [Article]) async throws -> BatchOperationResult { + guard !articles.isEmpty else { + return BatchOperationResult() + } + + CelestraLogger.cloudkit.info("📦 Creating \(articles.count) article(s)...") + + // Chunk articles into batches of 10 to keep payload size manageable with full content + let batches = articles.chunked(into: 10) + var result = BatchOperationResult() + + for (index, batch) in batches.enumerated() { + CelestraLogger.operations.info(" Batch \(index + 1)/\(batches.count): \(batch.count) article(s)") + + do { + let operations = batch.map { article in + RecordOperation.create( + recordType: "Article", + recordName: UUID().uuidString, + fields: article.toFieldsDict() + ) + } + + let recordInfos = try await self.modifyRecords(operations) + + result.appendSuccesses(recordInfos) + CelestraLogger.cloudkit.info(" ✅ Batch \(index + 1) complete: \(recordInfos.count) created") + } catch { + CelestraLogger.errors.error(" ❌ Batch \(index + 1) failed: \(error.localizedDescription)") + + // Track individual failures + for article in batch { + result.appendFailure(article: article, error: error) + } + } + } + + CelestraLogger.cloudkit.info( + "📊 Batch operation complete: \(result.successCount)/\(result.totalProcessed) succeeded (\(String(format: "%.1f", result.successRate))%)" + ) + + return result + } + + /// Update multiple Article records in batches with retry logic + /// - Parameter articles: Articles to update (must have recordName set) + /// - Returns: Batch operation result with success/failure tracking + func updateArticles(_ articles: [Article]) async throws -> BatchOperationResult { + guard !articles.isEmpty else { + return BatchOperationResult() + } + + CelestraLogger.cloudkit.info("🔄 Updating \(articles.count) article(s)...") + + // Filter out articles without recordName + let validArticles = articles.filter { $0.recordName != nil } + if validArticles.count != articles.count { + CelestraLogger.errors.warning( + "⚠️ Skipping \(articles.count - validArticles.count) article(s) without recordName" + ) + } + + guard !validArticles.isEmpty else { + return BatchOperationResult() + } + + // Chunk articles into batches of 10 to keep payload size manageable with full content + let batches = validArticles.chunked(into: 10) + var result = BatchOperationResult() + + for (index, batch) in batches.enumerated() { + CelestraLogger.operations.info(" Batch \(index + 1)/\(batches.count): \(batch.count) article(s)") + + do { + let operations = batch.compactMap { article -> RecordOperation? in + guard let recordName = article.recordName else { return nil } + + return RecordOperation.update( + recordType: "Article", + recordName: recordName, + fields: article.toFieldsDict(), + recordChangeTag: nil + ) + } + + let recordInfos = try await self.modifyRecords(operations) + + result.appendSuccesses(recordInfos) + CelestraLogger.cloudkit.info(" ✅ Batch \(index + 1) complete: \(recordInfos.count) updated") + } catch { + CelestraLogger.errors.error(" ❌ Batch \(index + 1) failed: \(error.localizedDescription)") + + // Track individual failures + for article in batch { + result.appendFailure(article: article, error: error) + } + } + } + + CelestraLogger.cloudkit.info( + "📊 Update complete: \(result.successCount)/\(result.totalProcessed) succeeded (\(String(format: "%.1f", result.successRate))%)" + ) + + return result + } + + // MARK: - Cleanup Operations + + /// Delete all Feed records + func deleteAllFeeds() async throws { + let feeds = try await queryRecords( + recordType: "Feed", + limit: 200, + desiredKeys: ["___recordID"] + ) + + guard !feeds.isEmpty else { + return + } + + let operations = feeds.map { record in + RecordOperation.delete( + recordType: "Feed", + recordName: record.recordName, + recordChangeTag: record.recordChangeTag + ) + } + + _ = try await modifyRecords(operations) + } + + /// Delete all Article records + func deleteAllArticles() async throws { + let articles = try await queryRecords( + recordType: "Article", + limit: 200, + desiredKeys: ["___recordID"] + ) + + guard !articles.isEmpty else { + return + } + + let operations = articles.map { record in + RecordOperation.delete( + recordType: "Article", + recordName: record.recordName, + recordChangeTag: record.recordChangeTag + ) + } + + _ = try await modifyRecords(operations) + } +} diff --git a/Examples/Celestra/Sources/Celestra/Services/RSSFetcherService.swift b/Examples/Celestra/Sources/Celestra/Services/RSSFetcherService.swift new file mode 100644 index 00000000..d491a655 --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Services/RSSFetcherService.swift @@ -0,0 +1,182 @@ +import Foundation +import Logging +import SyndiKit + +/// Service for fetching and parsing RSS feeds using SyndiKit with web etiquette +@available(macOS 13.0, *) +struct RSSFetcherService { + private let urlSession: URLSession + private let userAgent: String + + struct FeedData { + let title: String + let description: String? + let items: [FeedItem] + let minUpdateInterval: TimeInterval? // Parsed from or + } + + struct FeedItem { + let title: String + let link: String + let description: String? + let content: String? + let author: String? + let pubDate: Date? + let guid: String + } + + struct FetchResponse { + let feedData: FeedData? // nil if 304 Not Modified + let lastModified: String? + let etag: String? + let wasModified: Bool + } + + init(userAgent: String = "Celestra/1.0 (MistKit RSS Reader; +https://github.com/brightdigit/MistKit)") { + self.userAgent = userAgent + + // Create custom URLSession with proper configuration + let configuration = URLSessionConfiguration.default + configuration.httpAdditionalHeaders = [ + "User-Agent": userAgent, + "Accept": "application/rss+xml, application/atom+xml, application/xml;q=0.9, text/xml;q=0.8, */*;q=0.7" + ] + + self.urlSession = URLSession(configuration: configuration) + } + + /// Fetch and parse RSS feed from URL with conditional request support + /// - Parameters: + /// - url: Feed URL to fetch + /// - lastModified: Optional Last-Modified header from previous fetch + /// - etag: Optional ETag header from previous fetch + /// - Returns: Fetch response with feed data and HTTP metadata + func fetchFeed( + from url: URL, + lastModified: String? = nil, + etag: String? = nil + ) async throws -> FetchResponse { + CelestraLogger.rss.info("📡 Fetching RSS feed from \(url.absoluteString)") + + // Build request with conditional headers + var request = URLRequest(url: url) + if let lastModified = lastModified { + request.setValue(lastModified, forHTTPHeaderField: "If-Modified-Since") + } + if let etag = etag { + request.setValue(etag, forHTTPHeaderField: "If-None-Match") + } + + do { + // 1. Fetch RSS XML from URL + let (data, response) = try await urlSession.data(for: request) + + guard let httpResponse = response as? HTTPURLResponse else { + throw CelestraError.invalidFeedData("Non-HTTP response") + } + + // Extract response headers + let responseLastModified = httpResponse.value(forHTTPHeaderField: "Last-Modified") + let responseEtag = httpResponse.value(forHTTPHeaderField: "ETag") + + // Handle 304 Not Modified + if httpResponse.statusCode == 304 { + CelestraLogger.rss.info("✅ Feed not modified (304)") + return FetchResponse( + feedData: nil, + lastModified: responseLastModified ?? lastModified, + etag: responseEtag ?? etag, + wasModified: false + ) + } + + // Check for error status codes + guard (200...299).contains(httpResponse.statusCode) else { + throw CelestraError.rssFetchFailed(url, underlying: URLError(.badServerResponse)) + } + + // 2. Parse feed using SyndiKit + let decoder = SynDecoder() + let feed = try decoder.decode(data) + + // 3. Parse RSS metadata for update intervals + let minUpdateInterval = parseUpdateInterval(from: feed) + + // 4. Convert Feedable to our FeedData structure + let items = feed.children.compactMap { entry -> FeedItem? in + // Get link from url property or use id's description as fallback + let link: String + if let url = entry.url { + link = url.absoluteString + } else if case .url(let url) = entry.id { + link = url.absoluteString + } else { + // Use id's string representation as fallback + link = entry.id.description + } + + // Skip if link is empty + guard !link.isEmpty else { + return nil + } + + return FeedItem( + title: entry.title, + link: link, + description: entry.summary, + content: entry.contentHtml, + author: entry.authors.first?.name, + pubDate: entry.published, + guid: entry.id.description // Use id's description as guid + ) + } + + let feedData = FeedData( + title: feed.title, + description: feed.summary, + items: items, + minUpdateInterval: minUpdateInterval + ) + + CelestraLogger.rss.info("✅ Successfully fetched feed: \(feed.title) (\(items.count) items)") + if let interval = minUpdateInterval { + CelestraLogger.rss.info(" 📅 Feed requests updates every \(Int(interval / 60)) minutes") + } + + return FetchResponse( + feedData: feedData, + lastModified: responseLastModified, + etag: responseEtag, + wasModified: true + ) + + } catch let error as DecodingError { + CelestraLogger.errors.error("❌ Failed to parse feed: \(error.localizedDescription)") + throw CelestraError.invalidFeedData(error.localizedDescription) + } catch { + CelestraLogger.errors.error("❌ Failed to fetch feed: \(error.localizedDescription)") + throw CelestraError.rssFetchFailed(url, underlying: error) + } + } + + /// Parse minimum update interval from RSS feed metadata + /// - Parameter feed: Parsed feed from SyndiKit + /// - Returns: Minimum update interval in seconds, or nil if not specified + private func parseUpdateInterval(from feed: Feedable) -> TimeInterval? { + // Try to access raw XML for custom elements + // SyndiKit may not expose all RSS extensions directly + + // For now, we'll use a simple heuristic: + // - If feed has tag (in minutes), use that + // - If feed has and (Syndication module), use that + // - Otherwise, default to nil (no preference) + + // Note: SyndiKit's Feedable protocol doesn't expose these directly, + // so we'd need to access the raw XML or extend SyndiKit + // For this implementation, we'll parse common values if available + + // Default: no specific interval (1 hour minimum is reasonable) + // This could be enhanced by parsing the raw XML data + return nil // TODO: Implement RSS and parsing if needed + } +} diff --git a/Examples/Celestra/Sources/Celestra/Services/RateLimiter.swift b/Examples/Celestra/Sources/Celestra/Services/RateLimiter.swift new file mode 100644 index 00000000..a9fa8738 --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Services/RateLimiter.swift @@ -0,0 +1,78 @@ +import Foundation + +/// Actor-based rate limiter for RSS feed fetching +actor RateLimiter { + private var lastFetchTimes: [String: Date] = [:] + private let defaultDelay: TimeInterval + private let perDomainDelay: TimeInterval + + /// Initialize rate limiter with configurable delays + /// - Parameters: + /// - defaultDelay: Default delay between any two feed fetches (seconds) + /// - perDomainDelay: Additional delay when fetching from the same domain (seconds) + init(defaultDelay: TimeInterval = 2.0, perDomainDelay: TimeInterval = 5.0) { + self.defaultDelay = defaultDelay + self.perDomainDelay = perDomainDelay + } + + /// Wait if necessary before fetching a URL + /// - Parameters: + /// - url: The URL to fetch + /// - minimumInterval: Optional minimum interval to respect (e.g., from RSS ) + func waitIfNeeded(for url: URL, minimumInterval: TimeInterval? = nil) async { + guard let host = url.host else { + return + } + + let now = Date() + let key = host + + // Determine the required delay + var requiredDelay = defaultDelay + + // Use per-domain delay if we've fetched from this domain before + if let lastFetch = lastFetchTimes[key] { + requiredDelay = max(requiredDelay, perDomainDelay) + + // If feed specifies minimum interval, respect it + if let minInterval = minimumInterval { + requiredDelay = max(requiredDelay, minInterval) + } + + let timeSinceLastFetch = now.timeIntervalSince(lastFetch) + let remainingDelay = requiredDelay - timeSinceLastFetch + + if remainingDelay > 0 { + let nanoseconds = UInt64(remainingDelay * 1_000_000_000) + try? await Task.sleep(nanoseconds: nanoseconds) + } + } + + // Record this fetch time + lastFetchTimes[key] = Date() + } + + /// Wait with a global delay (between any two fetches, regardless of domain) + func waitGlobal() async { + // Get the most recent fetch time across all domains + if let mostRecent = lastFetchTimes.values.max() { + let timeSinceLastFetch = Date().timeIntervalSince(mostRecent) + let remainingDelay = defaultDelay - timeSinceLastFetch + + if remainingDelay > 0 { + let nanoseconds = UInt64(remainingDelay * 1_000_000_000) + try? await Task.sleep(nanoseconds: nanoseconds) + } + } + } + + /// Clear all rate limiting history + func reset() { + lastFetchTimes.removeAll() + } + + /// Clear rate limiting history for a specific domain + func reset(for host: String) { + lastFetchTimes.removeValue(forKey: host) + } +} diff --git a/Examples/Celestra/Sources/Celestra/Services/RobotsTxtService.swift b/Examples/Celestra/Sources/Celestra/Services/RobotsTxtService.swift new file mode 100644 index 00000000..5f063af1 --- /dev/null +++ b/Examples/Celestra/Sources/Celestra/Services/RobotsTxtService.swift @@ -0,0 +1,174 @@ +import Foundation +import Logging + +/// Service for fetching and parsing robots.txt files +actor RobotsTxtService { + private var cache: [String: RobotsRules] = [:] + private let userAgent: String + + /// Represents parsed robots.txt rules for a domain + struct RobotsRules { + let disallowedPaths: [String] + let crawlDelay: TimeInterval? + let fetchedAt: Date + + /// Check if a given path is allowed + func isAllowed(_ path: String) -> Bool { + // If no disallow rules, everything is allowed + guard !disallowedPaths.isEmpty else { + return true + } + + // Check if path matches any disallow rule + for disallowedPath in disallowedPaths { + if path.hasPrefix(disallowedPath) { + return false + } + } + + return true + } + } + + init(userAgent: String = "Celestra") { + self.userAgent = userAgent + } + + /// Check if a URL is allowed by robots.txt + /// - Parameter url: The URL to check + /// - Returns: True if allowed, false if disallowed + func isAllowed(_ url: URL) async throws -> Bool { + guard let host = url.host else { + // If no host, assume allowed + return true + } + + // Get or fetch robots.txt for this domain + let rules = try await getRules(for: host) + + // Check if the path is allowed + return rules.isAllowed(url.path) + } + + /// Get crawl delay for a domain from robots.txt + /// - Parameter url: The URL to check + /// - Returns: Crawl delay in seconds, or nil if not specified + func getCrawlDelay(for url: URL) async throws -> TimeInterval? { + guard let host = url.host else { + return nil + } + + let rules = try await getRules(for: host) + return rules.crawlDelay + } + + /// Get or fetch robots.txt rules for a domain + private func getRules(for host: String) async throws -> RobotsRules { + // Check cache first (cache for 24 hours) + if let cached = cache[host], + Date().timeIntervalSince(cached.fetchedAt) < 86400 { + return cached + } + + // Fetch and parse robots.txt + let rules = try await fetchAndParseRobotsTxt(for: host) + cache[host] = rules + return rules + } + + /// Fetch and parse robots.txt for a domain + private func fetchAndParseRobotsTxt(for host: String) async throws -> RobotsRules { + let robotsURL = URL(string: "https://\(host)/robots.txt")! + + do { + let (data, response) = try await URLSession.shared.data(from: robotsURL) + + guard let httpResponse = response as? HTTPURLResponse else { + // Default to allow if we can't get a response + return RobotsRules(disallowedPaths: [], crawlDelay: nil, fetchedAt: Date()) + } + + // If robots.txt doesn't exist, allow everything + guard httpResponse.statusCode == 200 else { + return RobotsRules(disallowedPaths: [], crawlDelay: nil, fetchedAt: Date()) + } + + guard let content = String(data: data, encoding: .utf8) else { + // Can't parse, default to allow + return RobotsRules(disallowedPaths: [], crawlDelay: nil, fetchedAt: Date()) + } + + return parseRobotsTxt(content) + + } catch { + // Network error - default to allow (fail open) + CelestraLogger.rss.warning("⚠️ Failed to fetch robots.txt for \(host): \(error.localizedDescription)") + return RobotsRules(disallowedPaths: [], crawlDelay: nil, fetchedAt: Date()) + } + } + + /// Parse robots.txt content + private func parseRobotsTxt(_ content: String) -> RobotsRules { + var disallowedPaths: [String] = [] + var crawlDelay: TimeInterval? + var isRelevantUserAgent = false + + let lines = content.components(separatedBy: .newlines) + + for line in lines { + let trimmed = line.trimmingCharacters(in: .whitespaces) + + // Skip empty lines and comments + guard !trimmed.isEmpty, !trimmed.hasPrefix("#") else { + continue + } + + // Split on first colon + let parts = trimmed.split(separator: ":", maxSplits: 1, omittingEmptySubsequences: true) + guard parts.count == 2 else { + continue + } + + let directive = parts[0].trimmingCharacters(in: .whitespaces).lowercased() + let value = parts[1].trimmingCharacters(in: .whitespaces) + + switch directive { + case "user-agent": + // Check if this section applies to us + let agentPattern = value.lowercased() + isRelevantUserAgent = agentPattern == "*" || + agentPattern == userAgent.lowercased() || + agentPattern.contains(userAgent.lowercased()) + + case "disallow": + if isRelevantUserAgent && !value.isEmpty { + disallowedPaths.append(value) + } + + case "crawl-delay": + if isRelevantUserAgent, let delay = Double(value) { + crawlDelay = delay + } + + default: + break + } + } + + return RobotsRules( + disallowedPaths: disallowedPaths, + crawlDelay: crawlDelay, + fetchedAt: Date() + ) + } + + /// Clear the robots.txt cache + func clearCache() { + cache.removeAll() + } + + /// Clear cache for a specific domain + func clearCache(for host: String) { + cache.removeValue(forKey: host) + } +} diff --git a/Examples/Celestra/schema.ckdb b/Examples/Celestra/schema.ckdb new file mode 100644 index 00000000..3060cf02 --- /dev/null +++ b/Examples/Celestra/schema.ckdb @@ -0,0 +1,36 @@ +DEFINE SCHEMA + +RECORD TYPE Feed ( + "___recordID" REFERENCE QUERYABLE, + "feedURL" STRING QUERYABLE SORTABLE, + "title" STRING SEARCHABLE, + "description" STRING, + "totalAttempts" INT64, + "successfulAttempts" INT64, + "usageCount" INT64 QUERYABLE SORTABLE, + "lastAttempted" TIMESTAMP QUERYABLE SORTABLE, + "isActive" INT64 QUERYABLE, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); + +RECORD TYPE Article ( + "___recordID" REFERENCE QUERYABLE, + "feed" REFERENCE QUERYABLE, + "title" STRING SEARCHABLE, + "link" STRING, + "description" STRING, + "content" STRING SEARCHABLE, + "author" STRING QUERYABLE, + "pubDate" TIMESTAMP QUERYABLE SORTABLE, + "guid" STRING QUERYABLE SORTABLE, + "contentHash" STRING QUERYABLE, + "fetchedAt" TIMESTAMP QUERYABLE SORTABLE, + "expiresAt" TIMESTAMP QUERYABLE SORTABLE, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); diff --git a/Examples/MistDemo/.gitignore b/Examples/MistDemo/.gitignore new file mode 100644 index 00000000..2d9f16e2 --- /dev/null +++ b/Examples/MistDemo/.gitignore @@ -0,0 +1,2 @@ +.build/ +.swiftpm/ diff --git a/Examples/Package.resolved b/Examples/MistDemo/Package.resolved similarity index 73% rename from Examples/Package.resolved rename to Examples/MistDemo/Package.resolved index 1988c319..1b91678f 100644 --- a/Examples/Package.resolved +++ b/Examples/MistDemo/Package.resolved @@ -1,12 +1,13 @@ { + "originHash" : "d4fde87d8245c3f3c5c41860c01c9566414072a1647c3636b53da691c462ea42", "pins" : [ { "identity" : "async-http-client", "kind" : "remoteSourceControl", "location" : "https://github.com/swift-server/async-http-client.git", "state" : { - "revision" : "60235983163d040f343a489f7e2e77c1918a8bd9", - "version" : "1.26.1" + "revision" : "b2faff932b956df50668241d14f1b42f7bae12b4", + "version" : "1.30.0" } }, { @@ -14,8 +15,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/hummingbird-project/hummingbird.git", "state" : { - "revision" : "3ae359b1bb1e72378ed43b59fdcd4d44cac5d7a4", - "version" : "2.16.0" + "revision" : "63689a57cbebf72c50cb9d702a4c69fb79f51d5d", + "version" : "2.17.0" } }, { @@ -32,8 +33,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-argument-parser.git", "state" : { - "revision" : "309a47b2b1d9b5e991f36961c983ecec72275be3", - "version" : "1.6.1" + "revision" : "cdd0ef3755280949551dc26dee5de9ddeda89f54", + "version" : "1.6.2" } }, { @@ -41,8 +42,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-asn1.git", "state" : { - "revision" : "f70225981241859eb4aa1a18a75531d26637c8cc", - "version" : "1.4.0" + "revision" : "40d25bbb2fc5b557a9aa8512210bded327c0f60d", + "version" : "1.5.0" } }, { @@ -50,8 +51,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-async-algorithms.git", "state" : { - "revision" : "042e1c4d9d19748c9c228f8d4ebc97bb1e339b0b", - "version" : "1.0.4" + "revision" : "2773d4125311133a2f705ec374c363a935069d45", + "version" : "1.1.0" } }, { @@ -68,8 +69,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-certificates.git", "state" : { - "revision" : "c059d9c9d08d6654b9a92dda93d9049a278964c6", - "version" : "1.12.0" + "revision" : "66a8512c4e7466582bab21e0e0c333f01974e5b6", + "version" : "1.16.0" } }, { @@ -77,8 +78,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-collections", "state" : { - "revision" : "8c0c0a8b49e080e54e5e328cc552821ff07cd341", - "version" : "1.2.1" + "revision" : "7b847a3b7008b2dc2f47ca3110d8c782fb2e5c7e", + "version" : "1.3.0" } }, { @@ -86,8 +87,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-crypto.git", "state" : { - "revision" : "334e682869394ee239a57dbe9262bff3cd9495bd", - "version" : "3.14.0" + "revision" : "95ba0316a9b733e92bb6b071255ff46263bbe7dc", + "version" : "3.15.1" } }, { @@ -95,8 +96,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-distributed-tracing.git", "state" : { - "revision" : "b78796709d243d5438b36e74ce3c5ec2d2ece4d8", - "version" : "1.2.1" + "revision" : "baa932c1336f7894145cbaafcd34ce2dd0b77c97", + "version" : "1.3.1" } }, { @@ -104,8 +105,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-http-structured-headers.git", "state" : { - "revision" : "1625f271afb04375bf48737a5572613248d0e7a0", - "version" : "1.4.0" + "revision" : "76d7627bd88b47bf5a0f8497dd244885960dde0b", + "version" : "1.6.0" } }, { @@ -113,8 +114,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-http-types", "state" : { - "revision" : "a0a57e949a8903563aba4615869310c0ebf14c03", - "version" : "1.4.0" + "revision" : "45eb0224913ea070ec4fba17291b9e7ecf4749ca", + "version" : "1.5.1" } }, { @@ -131,8 +132,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-metrics.git", "state" : { - "revision" : "4c83e1cdf4ba538ef6e43a9bbd0bcc33a0ca46e3", - "version" : "2.7.0" + "revision" : "0743a9364382629da3bf5677b46a2c4b1ce5d2a6", + "version" : "2.7.1" } }, { @@ -140,8 +141,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-nio.git", "state" : { - "revision" : "1c30f0f2053b654e3d1302492124aa6d242cdba7", - "version" : "2.86.0" + "revision" : "3eea09220e07d34ace722221cbda90306f48c86c", + "version" : "2.90.1" } }, { @@ -149,8 +150,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-nio-extras.git", "state" : { - "revision" : "a55c3dd3a81d035af8a20ce5718889c0dcab073d", - "version" : "1.29.0" + "revision" : "7ee281d816fa8e5f3967a2c294035a318ea551c7", + "version" : "1.31.0" } }, { @@ -158,8 +159,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-nio-http2.git", "state" : { - "revision" : "5e9e99ec96c53bc2c18ddd10c1e25a3cd97c55e5", - "version" : "1.38.0" + "revision" : "c2ba4cfbb83f307c66f5a6df6bb43e3c88dfbf80", + "version" : "1.39.0" } }, { @@ -167,8 +168,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-nio-ssl.git", "state" : { - "revision" : "385f5bd783ffbfff46b246a7db7be8e4f04c53bd", - "version" : "2.33.0" + "revision" : "173cc69a058623525a58ae6710e2f5727c663793", + "version" : "2.36.0" } }, { @@ -176,8 +177,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-nio-transport-services.git", "state" : { - "revision" : "e645014baea2ec1c2db564410c51a656cf47c923", - "version" : "1.25.1" + "revision" : "60c3e187154421171721c1a38e800b390680fb5d", + "version" : "1.26.0" } }, { @@ -185,8 +186,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-numerics.git", "state" : { - "revision" : "e0ec0f5f3af6f3e4d5e7a19d2af26b481acb6ba8", - "version" : "1.0.3" + "revision" : "0c0290ff6b24942dadb83a929ffaaa1481df04a2", + "version" : "1.1.1" } }, { @@ -203,8 +204,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-openapi-urlsession", "state" : { - "revision" : "6fac6f7c428d5feea2639b5f5c8b06ddfb79434b", - "version" : "1.1.0" + "revision" : "279aa6b77be6aa842a4bf3c45fa79fa15edf3e07", + "version" : "1.2.0" } }, { @@ -221,8 +222,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/swift-server/swift-service-lifecycle.git", "state" : { - "revision" : "e7187309187695115033536e8fc9b2eb87fd956d", - "version" : "2.8.0" + "revision" : "1de37290c0ab3c5a96028e0f02911b672fd42348", + "version" : "2.9.1" } }, { @@ -230,10 +231,10 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-system.git", "state" : { - "revision" : "890830fff1a577dc83134890c7984020c5f6b43b", - "version" : "1.6.2" + "revision" : "395a77f0aa927f0ff73941d7ac35f2b46d47c9db", + "version" : "1.6.3" } } ], - "version" : 2 + "version" : 3 } diff --git a/Examples/MistDemo/Package.swift b/Examples/MistDemo/Package.swift new file mode 100644 index 00000000..c25cd56e --- /dev/null +++ b/Examples/MistDemo/Package.swift @@ -0,0 +1,107 @@ +// swift-tools-version: 6.2 + +// swiftlint:disable explicit_acl explicit_top_level_acl + +import PackageDescription + +// MARK: - Swift Settings Configuration + +let swiftSettings: [SwiftSetting] = [ + // Swift 6.2 Upcoming Features (not yet enabled by default) + // SE-0335: Introduce existential `any` + .enableUpcomingFeature("ExistentialAny"), + // SE-0409: Access-level modifiers on import declarations + .enableUpcomingFeature("InternalImportsByDefault"), + // SE-0444: Member import visibility (Swift 6.1+) + .enableUpcomingFeature("MemberImportVisibility"), + // SE-0413: Typed throws + .enableUpcomingFeature("FullTypedThrows"), + + // Experimental Features (stable enough for use) + // SE-0426: BitwiseCopyable protocol + .enableExperimentalFeature("BitwiseCopyable"), + // SE-0432: Borrowing and consuming pattern matching for noncopyable types + .enableExperimentalFeature("BorrowingSwitch"), + // Extension macros + .enableExperimentalFeature("ExtensionMacros"), + // Freestanding expression macros + .enableExperimentalFeature("FreestandingExpressionMacros"), + // Init accessors + .enableExperimentalFeature("InitAccessors"), + // Isolated any types + .enableExperimentalFeature("IsolatedAny"), + // Move-only classes + .enableExperimentalFeature("MoveOnlyClasses"), + // Move-only enum deinits + .enableExperimentalFeature("MoveOnlyEnumDeinits"), + // SE-0429: Partial consumption of noncopyable values + .enableExperimentalFeature("MoveOnlyPartialConsumption"), + // Move-only resilient types + .enableExperimentalFeature("MoveOnlyResilientTypes"), + // Move-only tuples + .enableExperimentalFeature("MoveOnlyTuples"), + // SE-0427: Noncopyable generics + .enableExperimentalFeature("NoncopyableGenerics"), + // One-way closure parameters + // .enableExperimentalFeature("OneWayClosureParameters"), + // Raw layout types + .enableExperimentalFeature("RawLayout"), + // Reference bindings + .enableExperimentalFeature("ReferenceBindings"), + // SE-0430: sending parameter and result values + .enableExperimentalFeature("SendingArgsAndResults"), + // Symbol linkage markers + .enableExperimentalFeature("SymbolLinkageMarkers"), + // Transferring args and results + .enableExperimentalFeature("TransferringArgsAndResults"), + // SE-0393: Value and Type Parameter Packs + .enableExperimentalFeature("VariadicGenerics"), + // Warn unsafe reflection + .enableExperimentalFeature("WarnUnsafeReflection"), + + // Enhanced compiler checking + .unsafeFlags([ + // Enable concurrency warnings + "-warn-concurrency", + // Enable actor data race checks + "-enable-actor-data-race-checks", + // Complete strict concurrency checking + "-strict-concurrency=complete", + // Enable testing support + "-enable-testing", + // Warn about functions with >100 lines + "-Xfrontend", "-warn-long-function-bodies=100", + // Warn about slow type checking expressions + "-Xfrontend", "-warn-long-expression-type-checking=100" + ]) +] + +let package = Package( + name: "MistDemo", + platforms: [ + .macOS(.v14) + ], + products: [ + .executable(name: "mistdemo", targets: ["MistDemo"]) + ], + dependencies: [ + .package(path: "../.."), // MistKit + .package(url: "https://github.com/hummingbird-project/hummingbird.git", from: "2.0.0"), + .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.5.0") + ], + targets: [ + .executableTarget( + name: "MistDemo", + dependencies: [ + .product(name: "MistKit", package: "MistKit"), + .product(name: "Hummingbird", package: "hummingbird"), + .product(name: "ArgumentParser", package: "swift-argument-parser") + ], + resources: [ + .copy("Resources") + ], + swiftSettings: swiftSettings + ) + ] +) +// swiftlint:enable explicit_acl explicit_top_level_acl diff --git a/Examples/Sources/MistDemo/MistDemo.swift b/Examples/MistDemo/Sources/MistDemo/MistDemo.swift similarity index 99% rename from Examples/Sources/MistDemo/MistDemo.swift rename to Examples/MistDemo/Sources/MistDemo/MistDemo.swift index 2ae23fb8..c7de0b34 100644 --- a/Examples/Sources/MistDemo/MistDemo.swift +++ b/Examples/MistDemo/Sources/MistDemo/MistDemo.swift @@ -2,6 +2,7 @@ import Foundation import MistKit import Hummingbird import ArgumentParser +import Logging #if canImport(AppKit) import AppKit #endif diff --git a/Examples/Sources/MistDemo/Models/AuthModels.swift b/Examples/MistDemo/Sources/MistDemo/Models/AuthModels.swift similarity index 100% rename from Examples/Sources/MistDemo/Models/AuthModels.swift rename to Examples/MistDemo/Sources/MistDemo/Models/AuthModels.swift diff --git a/Examples/Sources/MistDemo/Resources/index.html b/Examples/MistDemo/Sources/MistDemo/Resources/index.html similarity index 100% rename from Examples/Sources/MistDemo/Resources/index.html rename to Examples/MistDemo/Sources/MistDemo/Resources/index.html diff --git a/Examples/Sources/MistDemo/Utilities/AsyncChannel.swift b/Examples/MistDemo/Sources/MistDemo/Utilities/AsyncChannel.swift similarity index 94% rename from Examples/Sources/MistDemo/Utilities/AsyncChannel.swift rename to Examples/MistDemo/Sources/MistDemo/Utilities/AsyncChannel.swift index 51d15929..740f110f 100644 --- a/Examples/Sources/MistDemo/Utilities/AsyncChannel.swift +++ b/Examples/MistDemo/Sources/MistDemo/Utilities/AsyncChannel.swift @@ -8,10 +8,10 @@ public import Foundation /// AsyncChannel for communication between server and main thread -actor AsyncChannel { +actor AsyncChannel { private var value: T? private var continuation: CheckedContinuation? - + func send(_ newValue: T) { if let continuation = continuation { continuation.resume(returning: newValue) @@ -20,13 +20,13 @@ actor AsyncChannel { value = newValue } } - + func receive() async -> T { if let value = value { self.value = nil return value } - + return await withCheckedContinuation { continuation in self.continuation = continuation } diff --git a/Examples/Sources/MistDemo/Utilities/BrowserOpener.swift b/Examples/MistDemo/Sources/MistDemo/Utilities/BrowserOpener.swift similarity index 100% rename from Examples/Sources/MistDemo/Utilities/BrowserOpener.swift rename to Examples/MistDemo/Sources/MistDemo/Utilities/BrowserOpener.swift diff --git a/Examples/Sources/MistDemo/Utilities/FieldValueFormatter.swift b/Examples/MistDemo/Sources/MistDemo/Utilities/FieldValueFormatter.swift similarity index 96% rename from Examples/Sources/MistDemo/Utilities/FieldValueFormatter.swift rename to Examples/MistDemo/Sources/MistDemo/Utilities/FieldValueFormatter.swift index 1e807f88..23b3a044 100644 --- a/Examples/Sources/MistDemo/Utilities/FieldValueFormatter.swift +++ b/Examples/MistDemo/Sources/MistDemo/Utilities/FieldValueFormatter.swift @@ -34,8 +34,6 @@ struct FieldValueFormatter { return "\(int)" case .double(let double): return "\(double)" - case .boolean(let bool): - return "\(bool)" case .bytes(let bytes): return "bytes(\(bytes.count) chars, base64: \(bytes))" case .date(let date): diff --git a/Examples/Package.swift b/Examples/Package.swift deleted file mode 100644 index 7cbb5411..00000000 --- a/Examples/Package.swift +++ /dev/null @@ -1,32 +0,0 @@ -// swift-tools-version: 5.9 -// The swift-tools-version declares the minimum version of Swift required to build this package. - -import PackageDescription - -let package = Package( - name: "MistKitExamples", - platforms: [ - .macOS(.v14) - ], - products: [ - .executable(name: "MistDemo", targets: ["MistDemo"]) - ], - dependencies: [ - .package(path: "../"), - .package(url: "https://github.com/hummingbird-project/hummingbird.git", from: "2.0.0"), - .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.5.0") - ], - targets: [ - .executableTarget( - name: "MistDemo", - dependencies: [ - .product(name: "MistKit", package: "MistKit"), - .product(name: "Hummingbird", package: "hummingbird"), - .product(name: "ArgumentParser", package: "swift-argument-parser") - ], - resources: [ - .copy("Resources") - ] - ) - ] -) diff --git a/Examples/SCHEMA_QUICK_REFERENCE.md b/Examples/SCHEMA_QUICK_REFERENCE.md new file mode 100644 index 00000000..6afdd6e8 --- /dev/null +++ b/Examples/SCHEMA_QUICK_REFERENCE.md @@ -0,0 +1,291 @@ +# CloudKit Schema Quick Reference + +One-page cheat sheet for CloudKit Schema Language (.ckdb files) + +--- + +## Basic Syntax + +``` +DEFINE SCHEMA + +RECORD TYPE TypeName ( + "fieldName" DataType [QUERYABLE] [SORTABLE] [SEARCHABLE], + GRANT READ, CREATE, WRITE TO "role" +); +``` + +## Data Types + +| CloudKit | Swift | Example | +|----------|-------|---------| +| `STRING` | `String` | `"title" STRING` | +| `INT64` | `Int64` or `Bool` | `"count" INT64` | +| `DOUBLE` | `Double` | `"rating" DOUBLE` | +| `TIMESTAMP` | `Date` | `"pubDate" TIMESTAMP` | +| `REFERENCE` | `CKRecord.Reference` | `"feed" REFERENCE` | +| `ASSET` | `CKAsset` | `"image" ASSET` | +| `LOCATION` | `CLLocation` | `"location" LOCATION` | +| `BYTES` | `Data` | `"data" BYTES` | +| `LIST` | `[Type]` | `"tags" LIST` | + +## Field Options + +| Option | Use When | Example | +|--------|----------|---------| +| `QUERYABLE` | Filtering by exact value | `feedURL == "..."` | +| `SORTABLE` | Sorting or range queries | `pubDate > date` | +| `SEARCHABLE` | Full-text search (STRING only) | `title CONTAINS "Swift"` | + +## Common Patterns + +### Boolean Fields +``` +"isActive" INT64 QUERYABLE // 0 = false, 1 = true +``` + +### Timestamps +``` +"createdAt" TIMESTAMP QUERYABLE SORTABLE +"updatedAt" TIMESTAMP QUERYABLE SORTABLE +``` + +### References (Foreign Keys) +``` +"feed" REFERENCE QUERYABLE // Article → Feed +``` + +### Text Search +``` +"title" STRING SEARCHABLE // Full-text search +``` + +### Unique Identifiers +``` +"guid" STRING QUERYABLE SORTABLE +``` + +### Counters +``` +"usageCount" INT64 QUERYABLE SORTABLE // For ranking/sorting +``` + +### Lists +``` +"tags" LIST +"images" LIST +``` + +## System Fields (Auto-included) + +``` +"___recordID" REFERENCE // Unique ID +"___createTime" TIMESTAMP // Created at +"___modTime" TIMESTAMP // Modified at +"___createdBy" REFERENCE // Creator +"___modifiedBy" REFERENCE // Last modifier +"___etag" STRING // Conflict resolution +``` + +**Note:** Only declare system fields if adding indexes + +## Permissions + +### Standard Public Database +``` +GRANT READ, CREATE, WRITE TO "_creator", // Record owner +GRANT READ, CREATE, WRITE TO "_icloud", // Authenticated users +GRANT READ TO "_world" // Everyone (unauthenticated) +``` + +### Private Database +``` +GRANT READ, CREATE, WRITE TO "_creator" // Owner only +``` + +### Custom Roles +``` +CREATE ROLE Moderator; + +GRANT READ, WRITE TO Moderator, +GRANT READ TO "_world" +``` + +## cktool Commands + +### Validation +```bash +# Validate syntax +cktool validate-schema schema.ckdb +``` + +### Export/Import +```bash +# Export existing schema +cktool export-schema > schema.ckdb + +# Import to development +export CLOUDKIT_ENVIRONMENT=development +cktool import-schema schema.ckdb + +# Import to production (careful!) +export CLOUDKIT_ENVIRONMENT=production +cktool import-schema schema.ckdb +``` + +### Required Environment Variables +```bash +export CLOUDKIT_CONTAINER_ID="iCloud.com.example.app" +export CLOUDKIT_ENVIRONMENT="development" # or "production" +export CLOUDKIT_MANAGEMENT_TOKEN="your_token_here" +``` + +## Indexing Decision Tree + +``` +Need to filter by exact value? +├─ Yes → QUERYABLE +└─ No → No index + +Need to sort or use range queries? +├─ Yes → SORTABLE (also gives QUERYABLE) +└─ No → Check QUERYABLE above + +Is it a STRING field users search within? +├─ Yes → SEARCHABLE +└─ No → Check above +``` + +## Type Mapping Examples + +### Feed Record +``` +RECORD TYPE Feed ( + "___recordID" REFERENCE QUERYABLE, + "feedURL" STRING QUERYABLE SORTABLE, + "title" STRING SEARCHABLE, + "isActive" INT64 QUERYABLE, // Boolean + "lastAttempted" TIMESTAMP QUERYABLE SORTABLE, + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ TO "_world" +); +``` + +### Swift Model +```swift +struct Feed: Codable { + var recordID: CKRecord.ID? + var feedURL: String + var title: String + var isActive: Bool // Convert INT64 0/1 + var lastAttempted: Date? +} +``` + +## Safe vs Unsafe Operations + +### ✅ Safe (Development & Production) +- Add new fields +- Add new record types +- Add indexes to fields +- Change permissions + +### ⚠️ Safe in Development Only +- Remove fields +- Remove record types +- Remove indexes + +### 🚫 Never Allowed +- Change field types +- Rename fields (delete + add = data loss) + +## Common Errors + +### Invalid identifier +``` +❌ "feed-url" // Hyphens not allowed +✅ "feedURL" // Use camelCase or underscores +``` + +### Wrong index on type +``` +❌ "count" INT64 SEARCHABLE // SEARCHABLE only for STRING +✅ "count" INT64 QUERYABLE // Use QUERYABLE or SORTABLE +``` + +### Missing quotes on system fields +``` +❌ ___recordID REFERENCE // Missing quotes +✅ "___recordID" REFERENCE // Must quote system fields +``` + +### Missing permissions +``` +❌ RECORD TYPE Feed ( ... ); // No grants +✅ RECORD TYPE Feed ( + ... + GRANT READ TO "_world" // At least one grant + ); +``` + +## Validation Checklist + +- [ ] Syntax validates: `cktool validate-schema schema.ckdb` +- [ ] Environment variables set correctly +- [ ] Tested import to development first +- [ ] Schema appears in CloudKit Dashboard +- [ ] Can create test records +- [ ] Queries work with new indexes +- [ ] No data loss warnings +- [ ] Swift models updated +- [ ] Tests pass +- [ ] Schema committed to git + +## Example Complete Schema (Celestra) + +``` +DEFINE SCHEMA + +RECORD TYPE Feed ( + "___recordID" REFERENCE QUERYABLE, + "feedURL" STRING QUERYABLE SORTABLE, + "title" STRING SEARCHABLE, + "description" STRING, + "totalAttempts" INT64, + "successfulAttempts" INT64, + "usageCount" INT64 QUERYABLE SORTABLE, + "lastAttempted" TIMESTAMP QUERYABLE SORTABLE, + "isActive" INT64 QUERYABLE, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); + +RECORD TYPE Article ( + "___recordID" REFERENCE QUERYABLE, + "feed" REFERENCE QUERYABLE, + "title" STRING SEARCHABLE, + "link" STRING, + "description" STRING, + "author" STRING QUERYABLE, + "pubDate" TIMESTAMP QUERYABLE SORTABLE, + "guid" STRING QUERYABLE SORTABLE, + "contentHash" STRING QUERYABLE, + "fetchedAt" TIMESTAMP QUERYABLE SORTABLE, + "expiresAt" TIMESTAMP QUERYABLE SORTABLE, + + GRANT READ, CREATE, WRITE TO "_creator", + GRANT READ, CREATE, WRITE TO "_icloud", + GRANT READ TO "_world" +); +``` + +--- + +## See Also + +- **Detailed Guide:** [Celestra/AI_SCHEMA_WORKFLOW.md](Celestra/AI_SCHEMA_WORKFLOW.md) +- **Claude Reference:** [.claude/docs/cloudkit-schema-reference.md](../.claude/docs/cloudkit-schema-reference.md) +- **Task Master Integration:** [.taskmaster/docs/schema-design-workflow.md](../.taskmaster/docs/schema-design-workflow.md) +- **Setup Guide:** [Celestra/CLOUDKIT_SCHEMA_SETUP.md](Celestra/CLOUDKIT_SCHEMA_SETUP.md) diff --git a/Mintfile b/Mintfile index c58e2475..3586a2be 100644 --- a/Mintfile +++ b/Mintfile @@ -1,4 +1,4 @@ -swiftlang/swift-format@601.0.0 -realm/SwiftLint@0.59.1 +swiftlang/swift-format@602.0.0 +realm/SwiftLint@0.62.2 peripheryapp/periphery@3.2.0 -apple/swift-openapi-generator@1.10.0 +apple/swift-openapi-generator@1.10.3 diff --git a/Package.resolved b/Package.resolved index ea141e6b..a789e793 100644 --- a/Package.resolved +++ b/Package.resolved @@ -1,5 +1,5 @@ { - "originHash" : "350673c83b32ba6e83db1d441282b5bd7c676925eae7a546743131e0b3bc47cf", + "originHash" : "5772f4a3fc82aa266a22f0fba10c8e939829aaad63cfdfce1504d281aca64e03", "pins" : [ { "identity" : "swift-asn1", @@ -37,6 +37,15 @@ "version" : "1.4.0" } }, + { + "identity" : "swift-log", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-log.git", + "state" : { + "revision" : "ce592ae52f982c847a4efc0dd881cc9eb32d29f2", + "version" : "1.6.4" + } + }, { "identity" : "swift-openapi-runtime", "kind" : "remoteSourceControl", diff --git a/Package.swift b/Package.swift index 75f5f4af..63701890 100644 --- a/Package.swift +++ b/Package.swift @@ -100,6 +100,8 @@ let package = Package( .package(url: "https://github.com/apple/swift-openapi-urlsession", from: "1.1.0"), // Crypto library for cross-platform cryptographic operations .package(url: "https://github.com/apple/swift-crypto.git", from: "3.0.0"), + // Logging library for cross-platform logging + .package(url: "https://github.com/apple/swift-log.git", from: "1.0.0"), ], targets: [ // Targets are the basic building blocks of a package, defining a module or a test suite. @@ -110,6 +112,7 @@ let package = Package( .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"), .product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession"), .product(name: "Crypto", package: "swift-crypto"), + .product(name: "Logging", package: "swift-log"), ], swiftSettings: swiftSettings ), diff --git a/Scripts/convert-conversations.py b/Scripts/convert-conversations.py new file mode 100755 index 00000000..4a6de784 --- /dev/null +++ b/Scripts/convert-conversations.py @@ -0,0 +1,285 @@ +#!/usr/bin/env python3 +""" +Convert Claude Code conversation markdown files to timeline format. + +Usage: + ./Scripts/convert-conversations.py # Convert single file + ./Scripts/convert-conversations.py --all # Convert all files + ./Scripts/convert-conversations.py --all --output-dir timeline # Custom output dir +""" + +import argparse +import json +import re +import sys +from pathlib import Path +from datetime import datetime + + +def parse_conversation_file(filepath: Path) -> dict: + """Parse a conversation markdown file into structured data.""" + content = filepath.read_text() + + # Extract header info + session_id_match = re.search(r'\*\*Session ID:\*\* ([a-f0-9-]+)', content) + exported_match = re.search(r'\*\*Exported:\*\* (.+)', content) + + session_id = session_id_match.group(1) if session_id_match else "unknown" + exported = exported_match.group(1) if exported_match else "unknown" + + # Split into messages + message_pattern = r'## (User|Assistant)\n\*(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\*\n\n(.*?)(?=\n## (?:User|Assistant)\n|\Z)' + messages = re.findall(message_pattern, content, re.DOTALL) + + parsed_messages = [] + for role, timestamp, content in messages: + parsed_messages.append({ + 'role': role.upper(), + 'timestamp': timestamp, + 'content': content.strip() + }) + + return { + 'session_id': session_id, + 'exported': exported, + 'messages': parsed_messages + } + + +def summarize_tool_call(tool_name: str, tool_input: dict) -> str: + """Create a brief summary of a tool call.""" + if tool_name == "Read": + path = tool_input.get("file_path", "unknown") + return f"[Read: {Path(path).name}]" + + elif tool_name == "Grep": + pattern = tool_input.get("pattern", "")[:30] + path = tool_input.get("path", ".") + return f'[Grep: "{pattern}" in {Path(path).name}]' + + elif tool_name == "Glob": + pattern = tool_input.get("pattern", "") + return f"[Glob: {pattern}]" + + elif tool_name == "Bash": + cmd = tool_input.get("command", "")[:50] + desc = tool_input.get("description", cmd)[:40] + return f"[Bash: {desc}]" + + elif tool_name == "WebFetch": + url = tool_input.get("url", "") + from urllib.parse import urlparse + domain = urlparse(url).netloc if url else "unknown" + return f"[WebFetch: {domain}]" + + elif tool_name in ("Edit", "Write"): + path = tool_input.get("file_path", "unknown") + return f"[{tool_name}: {Path(path).name}]" + + elif tool_name == "TodoWrite": + todos = tool_input.get("todos", []) + count = len(todos) + return f"[TodoWrite: {count} items]" + + elif tool_name == "Task": + agent_type = tool_input.get("subagent_type", "unknown") + return f"[Task: {agent_type} agent]" + + else: + return f"[{tool_name}]" + + +def parse_json_content(content: str) -> list: + """Parse JSON array from message content.""" + try: + # Try to parse as JSON array + content = content.strip() + if content.startswith('['): + return json.loads(content) + except json.JSONDecodeError: + pass + + # Return as plain text if not JSON + return [{"type": "text", "text": content}] + + +def format_message_content(content: str) -> tuple[str, list]: + """ + Format message content into readable text and tool summaries. + Returns (text_content, tool_summaries) + """ + items = parse_json_content(content) + + text_parts = [] + tool_summaries = [] + + for item in items: + if isinstance(item, dict): + item_type = item.get("type", "") + + if item_type == "text": + text = item.get("text", "").strip() + if text: + text_parts.append(text) + + elif item_type == "tool_use": + tool_name = item.get("name", "Unknown") + tool_input = item.get("input", {}) + tool_summaries.append(summarize_tool_call(tool_name, tool_input)) + + elif item_type == "tool_result": + # Skip tool results in the timeline (they're implementation details) + pass + + return "\n".join(text_parts), tool_summaries + + +def convert_to_timeline(parsed_data: dict) -> str: + """Convert parsed conversation data to timeline markdown format.""" + lines = [] + + # Header + first_timestamp = parsed_data['messages'][0]['timestamp'] if parsed_data['messages'] else "unknown" + lines.append(f"# Session Timeline: {first_timestamp.split()[0]}") + lines.append(f"**Session ID:** {parsed_data['session_id']}") + lines.append(f"**Exported:** {parsed_data['exported']}") + lines.append("") + lines.append("---") + lines.append("") + + # Messages + prev_role = None + prev_time = None + pending_tools = [] + + for msg in parsed_data['messages']: + role = msg['role'] + timestamp = msg['timestamp'] + time_only = timestamp.split()[1] if ' ' in timestamp else timestamp + + text_content, tool_summaries = format_message_content(msg['content']) + + # Skip empty tool result messages from user + if role == "USER" and not text_content and not tool_summaries: + continue + + # Group consecutive assistant messages + if role == "ASSISTANT" and prev_role == "ASSISTANT": + # If this is just tool calls, append to pending + if tool_summaries and not text_content: + pending_tools.extend(tool_summaries) + continue + elif text_content: + # Flush pending tools first + if pending_tools: + lines.append(f"### {prev_time} - ASSISTANT") + for tool in pending_tools: + lines.append(tool) + lines.append("") + pending_tools = [] + else: + # New speaker, flush pending tools + if pending_tools: + lines.append(f"### {prev_time} - ASSISTANT") + for tool in pending_tools: + lines.append(tool) + lines.append("") + pending_tools = [] + + # Handle current message + if tool_summaries and not text_content: + # Just tools, save for later grouping + pending_tools.extend(tool_summaries) + prev_time = time_only + elif text_content: + lines.append(f"### {time_only} - {role}") + if tool_summaries: + for tool in tool_summaries: + lines.append(tool) + lines.append("") + # Truncate long text + if len(text_content) > 2000: + text_content = text_content[:2000] + "\n\n... [truncated]" + lines.append(text_content) + lines.append("") + + prev_role = role + prev_time = time_only + + # Flush any remaining pending tools + if pending_tools: + lines.append(f"### {prev_time} - ASSISTANT") + for tool in pending_tools: + lines.append(tool) + lines.append("") + + return "\n".join(lines) + + +def convert_file(input_path: Path, output_dir: Path = None) -> Path: + """Convert a single conversation file to timeline format.""" + if output_dir is None: + output_dir = input_path.parent / "timeline" + + output_dir.mkdir(parents=True, exist_ok=True) + + parsed = parse_conversation_file(input_path) + timeline = convert_to_timeline(parsed) + + output_path = output_dir / f"timeline_{input_path.name}" + output_path.write_text(timeline) + + return output_path + + +def main(): + parser = argparse.ArgumentParser(description="Convert Claude Code conversations to timeline format") + parser.add_argument("file", nargs="?", help="Single file to convert") + parser.add_argument("--all", action="store_true", help="Convert all conversation files") + parser.add_argument("--output-dir", default=None, help="Output directory (default: timeline/ in same dir)") + parser.add_argument("--conversations-dir", default=".claude/conversations", + help="Directory containing conversation files") + + args = parser.parse_args() + + if args.all: + conv_dir = Path(args.conversations_dir) + if not conv_dir.exists(): + print(f"Error: Conversations directory not found: {conv_dir}") + sys.exit(1) + + output_dir = Path(args.output_dir) if args.output_dir else conv_dir / "timeline" + + files = list(conv_dir.glob("*.md")) + # Exclude already converted files and index files + files = [f for f in files if not f.name.startswith("timeline_") + and f.name not in ("INDEX.md", "SUMMARY.md")] + + print(f"Converting {len(files)} conversation files...") + + for i, file in enumerate(files, 1): + try: + output_path = convert_file(file, output_dir) + print(f"[{i}/{len(files)}] {file.name} -> {output_path.name}") + except Exception as e: + print(f"[{i}/{len(files)}] Error converting {file.name}: {e}") + + print(f"\nDone! Timeline files saved to: {output_dir}") + + elif args.file: + input_path = Path(args.file) + if not input_path.exists(): + print(f"Error: File not found: {input_path}") + sys.exit(1) + + output_dir = Path(args.output_dir) if args.output_dir else None + output_path = convert_file(input_path, output_dir) + print(f"Converted: {input_path.name} -> {output_path}") + + else: + parser.print_help() + sys.exit(1) + + +if __name__ == "__main__": + main() diff --git a/Scripts/export-conversations.sh b/Scripts/export-conversations.sh new file mode 100755 index 00000000..0ab896d4 --- /dev/null +++ b/Scripts/export-conversations.sh @@ -0,0 +1,163 @@ +#!/bin/bash + +# Export all Claude Code conversations to markdown format +# Usage: ./export-conversations.sh [output_directory] +# Default output: .claude/conversations + +set -euo pipefail + +# Configuration +CLAUDE_DIR="$HOME/.claude/projects" +OUTPUT_DIR="${1:-.claude/conversations}" +CURRENT_DIR="$(pwd)" +CURRENT_PROJECT_NAME="$(basename "$CURRENT_DIR")" + +# Create output directory +mkdir -p "$OUTPUT_DIR" + +echo "=== Claude Code Conversation Exporter ===" +echo "Exporting conversations to: $OUTPUT_DIR" +echo "" + +# Function to convert JSONL to readable markdown +convert_conversation() { + local jsonl_file="$1" + local output_file="$2" + local session_id="$(basename "$jsonl_file" .jsonl)" + + echo "# Claude Code Conversation" > "$output_file" + echo "" >> "$output_file" + echo "**Session ID:** $session_id" >> "$output_file" + echo "**Exported:** $(date)" >> "$output_file" + echo "" >> "$output_file" + echo "---" >> "$output_file" + echo "" >> "$output_file" + + # Parse JSONL and extract messages + while IFS= read -r line; do + # Check if line is valid JSON + if ! echo "$line" | jq empty 2>/dev/null; then + continue + fi + + local msg_type=$(echo "$line" | jq -r '.type // empty') + local role=$(echo "$line" | jq -r '.message.role // empty') + local content=$(echo "$line" | jq -r '.message.content // empty') + local timestamp=$(echo "$line" | jq -r '.timestamp // empty') + local is_meta=$(echo "$line" | jq -r '.isMeta // false') + + # Skip meta messages + if [ "$is_meta" = "true" ]; then + continue + fi + + # Format timestamp + if [ -n "$timestamp" ] && [ "$timestamp" != "null" ]; then + formatted_time=$(date -j -f "%Y-%m-%dT%H:%M:%S" "${timestamp%.*}" "+%Y-%m-%d %H:%M:%S" 2>/dev/null || echo "$timestamp") + else + formatted_time="" + fi + + # Output based on role + if [ "$role" = "user" ]; then + echo "## User" >> "$output_file" + if [ -n "$formatted_time" ]; then + echo "*$formatted_time*" >> "$output_file" + fi + echo "" >> "$output_file" + echo "$content" >> "$output_file" + echo "" >> "$output_file" + elif [ "$role" = "assistant" ]; then + echo "## Assistant" >> "$output_file" + if [ -n "$formatted_time" ]; then + echo "*$formatted_time*" >> "$output_file" + fi + echo "" >> "$output_file" + echo "$content" >> "$output_file" + echo "" >> "$output_file" + fi + + done < "$jsonl_file" +} + +# Find all project directories related to this git repository +# This includes the main project and all git worktrees +PROJECT_DIRS=() + +# Get the base project name (e.g., "MistKit") +BASE_PROJECT_NAME="$CURRENT_PROJECT_NAME" + +# Find all directories that contain this project name +while IFS= read -r dir; do + PROJECT_DIRS+=("$dir") +done < <(find "$CLAUDE_DIR" -type d -name "*$BASE_PROJECT_NAME*" 2>/dev/null) + +if [ ${#PROJECT_DIRS[@]} -eq 0 ]; then + echo "Warning: Could not find any Claude project directories for: $BASE_PROJECT_NAME" + echo "Falling back to searching all projects..." + PROJECT_DIRS=("$CLAUDE_DIR") +fi + +echo "Found ${#PROJECT_DIRS[@]} project directory(ies):" +for dir in "${PROJECT_DIRS[@]}"; do + echo " - $(basename "$dir")" +done +echo "" + +# Counter +count=0 + +# Find and convert all JSONL files from all related project directories +for PROJECT_DIR in "${PROJECT_DIRS[@]}"; do + echo "Searching in: $(basename "$PROJECT_DIR")" + + while IFS= read -r jsonl_file; do + if [ ! -f "$jsonl_file" ]; then + continue + fi + + session_id="$(basename "$jsonl_file" .jsonl)" + + # Get first message timestamp for filename + first_timestamp=$(head -1 "$jsonl_file" | jq -r '.timestamp // empty' 2>/dev/null || echo "") + + if [ -n "$first_timestamp" ] && [ "$first_timestamp" != "null" ]; then + date_prefix=$(date -j -f "%Y-%m-%dT%H:%M:%S" "${first_timestamp%.*}" "+%Y%m%d-%H%M%S" 2>/dev/null || echo "unknown") + else + date_prefix="unknown" + fi + + output_file="$OUTPUT_DIR/${date_prefix}_${session_id}.md" + + echo " Exporting: $session_id" + convert_conversation "$jsonl_file" "$output_file" + + ((count++)) + done < <(find "$PROJECT_DIR" -name "*.jsonl" -type f 2>/dev/null | sort) +done + +echo "" +echo "=== Export Complete ===" +echo "Exported $count conversation(s) to: $OUTPUT_DIR" +echo "" + +# Create an index file +index_file="$OUTPUT_DIR/INDEX.md" +echo "# Claude Code Conversations Index" > "$index_file" +echo "" >> "$index_file" +echo "**Project:** $CURRENT_PROJECT_NAME" >> "$index_file" +echo "**Exported:** $(date)" >> "$index_file" +echo "**Total Conversations:** $count" >> "$index_file" +echo "" >> "$index_file" +echo "## Conversations" >> "$index_file" +echo "" >> "$index_file" + +# List all exported files +for md_file in "$OUTPUT_DIR"/*.md; do + if [ "$(basename "$md_file")" != "INDEX.md" ]; then + filename=$(basename "$md_file") + echo "- [$filename](./$filename)" >> "$index_file" + fi +done + +echo "Index created: $index_file" diff --git a/Sources/MistKit/Authentication/SecureLogging.swift b/Sources/MistKit/Authentication/SecureLogging.swift index 710690e7..d7ebfd16 100644 --- a/Sources/MistKit/Authentication/SecureLogging.swift +++ b/Sources/MistKit/Authentication/SecureLogging.swift @@ -65,8 +65,13 @@ internal enum SecureLogging { /// Creates a safe logging string that masks sensitive information /// - Parameter message: The message to log - /// - Returns: A safe version of the message with sensitive data masked + /// - Returns: The message as-is (redaction disabled by default, enable with MISTKIT_ENABLE_LOG_REDACTION) internal static func safeLogMessage(_ message: String) -> String { + // Redaction disabled by default - enable with environment variable if needed + guard ProcessInfo.processInfo.environment["MISTKIT_ENABLE_LOG_REDACTION"] != nil else { + return message + } + var safeMessage = message // Use static regex patterns for better performance diff --git a/Sources/MistKit/CustomFieldValue.CustomFieldValuePayload.swift b/Sources/MistKit/CustomFieldValue.CustomFieldValuePayload.swift index e7db7d61..9c01fc00 100644 --- a/Sources/MistKit/CustomFieldValue.CustomFieldValuePayload.swift +++ b/Sources/MistKit/CustomFieldValue.CustomFieldValuePayload.swift @@ -27,7 +27,7 @@ // OTHER DEALINGS IN THE SOFTWARE. // -public import Foundation +import Foundation extension CustomFieldValue.CustomFieldValuePayload { /// Initialize from decoder @@ -65,9 +65,6 @@ extension CustomFieldValue.CustomFieldValuePayload { if let value = try? container.decode(Double.self) { return .doubleValue(value) } - if let value = try? container.decode(Bool.self) { - return .booleanValue(value) - } return nil } @@ -104,7 +101,8 @@ extension CustomFieldValue.CustomFieldValuePayload { case .int64Value(let val): try container.encode(val) case .booleanValue(let val): - try container.encode(val) + // CloudKit represents booleans as int64 (0 or 1) + try container.encode(val ? 1 : 0) case .doubleValue(let val), .dateValue(let val): try encodeNumericValue(val, to: &container) case .locationValue(let val): diff --git a/Sources/MistKit/CustomFieldValue.swift b/Sources/MistKit/CustomFieldValue.swift index 918f54af..c07355aa 100644 --- a/Sources/MistKit/CustomFieldValue.swift +++ b/Sources/MistKit/CustomFieldValue.swift @@ -51,9 +51,9 @@ internal struct CustomFieldValue: Codable, Hashable, Sendable { case stringValue(String) case int64Value(Int) case doubleValue(Double) - case booleanValue(Bool) case bytesValue(String) case dateValue(Double) + case booleanValue(Bool) case locationValue(Components.Schemas.LocationValue) case referenceValue(Components.Schemas.ReferenceValue) case assetValue(Components.Schemas.AssetValue) @@ -66,7 +66,8 @@ internal struct CustomFieldValue: Codable, Hashable, Sendable { } private static let fieldTypeDecoders: - [FieldTypePayload: @Sendable (KeyedDecodingContainer) throws -> + [FieldTypePayload: + @Sendable (KeyedDecodingContainer) throws -> CustomFieldValuePayload] = [ .string: { .stringValue(try $0.decode(String.self, forKey: .value)) }, .int64: { .int64Value(try $0.decode(Int.self, forKey: .value)) }, @@ -96,6 +97,12 @@ internal struct CustomFieldValue: Codable, Hashable, Sendable { /// The field type internal let type: FieldTypePayload? + /// Internal initializer for constructing field values programmatically + internal init(value: CustomFieldValuePayload, type: FieldTypePayload?) { + self.value = value + self.type = type + } + internal init(from decoder: any Decoder) throws { let container = try decoder.container(keyedBy: CodingKeys.self) let fieldType = try container.decodeIfPresent(FieldTypePayload.self, forKey: .type) @@ -135,10 +142,11 @@ internal struct CustomFieldValue: Codable, Hashable, Sendable { try container.encode(val, forKey: .value) case .doubleValue(let val): try container.encode(val, forKey: .value) - case .booleanValue(let val): - try container.encode(val, forKey: .value) case .dateValue(let val): try container.encode(val, forKey: .value) + case .booleanValue(let val): + // CloudKit represents booleans as int64 (0 or 1) + try container.encode(val ? 1 : 0, forKey: .value) case .locationValue(let val): try container.encode(val, forKey: .value) case .referenceValue(let val): diff --git a/Sources/MistKit/Database.swift b/Sources/MistKit/Database.swift index 6a47e8b0..b42f6a3a 100644 --- a/Sources/MistKit/Database.swift +++ b/Sources/MistKit/Database.swift @@ -35,18 +35,3 @@ public enum Database: String, Sendable { case `private` case shared } - -/// Extension to convert Database enum to Components type -extension Database { - /// Convert to the generated Components.Parameters.database type - internal func toComponentsDatabase() -> Components.Parameters.database { - switch self { - case .public: - return ._public - case .private: - return ._private - case .shared: - return .shared - } - } -} diff --git a/Sources/MistKit/Documentation.docc/AbstractionLayerArchitecture.md b/Sources/MistKit/Documentation.docc/AbstractionLayerArchitecture.md new file mode 100644 index 00000000..705f22b2 --- /dev/null +++ b/Sources/MistKit/Documentation.docc/AbstractionLayerArchitecture.md @@ -0,0 +1,912 @@ +# MistKit Abstraction Layer Architecture + +A comprehensive guide to MistKit's Swift abstraction layer built on top of the swift-openapi-generator client, showcasing modern Swift patterns and concurrency features. + +## Overview + +MistKit provides a friendly Swift abstraction layer that wraps the generated OpenAPI client code, offering improved ergonomics, type safety, and developer experience while leveraging modern Swift 6 concurrency features. This article explores the architectural patterns, design decisions, and implementation details of this abstraction layer. + +## Architecture Philosophy + +### Design Goals + +1. **Hide complexity** without sacrificing functionality +2. **Leverage modern Swift features** (async/await, Sendable, typed throws) +3. **Maintain type safety** throughout the stack +4. **Enable testability** through protocol-oriented design +5. **Support cross-platform** development (macOS, iOS, Linux) +6. **Provide excellent ergonomics** for common operations + +### Layered Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ User Code (Application/Library Consumer) │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ MistKit Abstraction Layer │ +│ ┌───────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ MistKitClient │ │ TokenManager │ │ Middleware │ │ +│ │ Configuration │ │ Hierarchy │ │ Pipeline │ │ +│ └───────────────┘ └──────────────┘ └──────────────┘ │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ Generated OpenAPI Client (Client.swift, Types.swift) │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ OpenAPI Runtime (HTTP transport, serialization) │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ URLSession / Network Layer │ +└─────────────────────────────────────────────────────────┘ +``` + +## Modern Swift Concurrency Integration + +### Async/Await Throughout + +MistKit embraces Swift's structured concurrency with async/await patterns across the entire API surface. + +#### TokenManager Protocol + +```swift +/// Protocol for managing authentication tokens +public protocol TokenManager: Sendable { + /// Checks if credentials are currently available + var hasCredentials: Bool { get async } + + /// Validates the current authentication credentials + func validateCredentials() async throws(TokenManagerError) -> Bool + + /// Retrieves the current token credentials + func getCurrentCredentials() async throws(TokenManagerError) -> TokenCredentials? +} +``` + +**Key features:** + +- ✅ **Async properties**: `hasCredentials` is computed asynchronously +- ✅ **Typed throws**: Uses `throws(TokenManagerError)` for specific error types (Swift 6) +- ✅ **Sendable protocol**: Safe to use across actor boundaries +- ✅ **No completion handlers**: Clean, modern API surface + +**Comparison with completion handler pattern:** + +```swift +// Old pattern (completion handlers) +protocol OldTokenManager { + func hasCredentials(completion: @escaping (Bool) -> Void) + func validateCredentials(completion: @escaping (Result) -> Void) + func getCurrentCredentials(completion: @escaping (Result) -> Void) +} + +// Modern pattern (async/await) +protocol TokenManager: Sendable { + var hasCredentials: Bool { get async } + func validateCredentials() async throws(TokenManagerError) -> Bool + func getCurrentCredentials() async throws(TokenManagerError) -> TokenCredentials? +} +``` + +**Benefits:** + +- ✅ No callback hell or nesting +- ✅ Automatic error propagation +- ✅ Task cancellation support +- ✅ Better IDE autocomplete +- ✅ Easier testing + +### Middleware with Async/Await + +MistKit implements the middleware pattern using OpenAPIRuntime's `ClientMiddleware` protocol: + +```swift +/// Authentication middleware for CloudKit requests +internal struct AuthenticationMiddleware: ClientMiddleware { + internal let tokenManager: any TokenManager + + internal func intercept( + _ request: HTTPRequest, + body: HTTPBody?, + baseURL: URL, + operationID: String, + next: (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?) + ) async throws -> (HTTPResponse, HTTPBody?) { + // Get credentials asynchronously + guard let credentials = try await tokenManager.getCurrentCredentials() else { + throw TokenManagerError.invalidCredentials(.noCredentialsAvailable) + } + + var modifiedRequest = request + // Add authentication based on method type + switch credentials.method { + case .apiToken(let apiToken): + // Add API token to query parameters + addAPITokenAuthentication(apiToken: apiToken, to: &modifiedRequest) + + case .webAuthToken(let apiToken, let webToken): + // Add both API and web auth tokens + addWebAuthTokenAuthentication( + apiToken: apiToken, + webToken: webToken, + to: &modifiedRequest + ) + + case .serverToServer: + // Sign request with ECDSA P-256 signature + modifiedRequest = try await addServerToServerAuthentication( + to: modifiedRequest, + body: body + ) + } + + // Call next middleware in chain + return try await next(modifiedRequest, body, baseURL) + } +} +``` + +**Middleware chain pattern:** + +``` +Request + ↓ +AuthenticationMiddleware.intercept() + ├─ Get credentials (async) + ├─ Modify request (add auth) + └─ next() → LoggingMiddleware.intercept() + ├─ Log request + └─ next() → Transport.send() + ↓ + Network + ↓ +Response ← ← ← ← ← ← ← ← ← ← ← +``` + +**Benefits of async middleware:** + +- ✅ Can perform async operations (fetch credentials, sign requests) +- ✅ Clean error propagation through the chain +- ✅ Composable and testable +- ✅ No blocking operations + +## Sendable Compliance and Concurrency Safety + +All types in MistKit's abstraction layer are `Sendable`, ensuring thread-safety for Swift 6's strict concurrency checking. + +### Configuration as Sendable Struct + +```swift +/// Configuration for MistKit client +internal struct MistKitConfiguration: Sendable { + internal let container: String + internal let environment: Environment + internal let database: Database + internal let apiToken: String + internal let webAuthToken: String? + internal let keyID: String? + internal let privateKeyData: Data? + internal let serverURL: URL + + // All properties are immutable (let), making the struct inherently thread-safe +} +``` + +**Why Sendable matters:** + +```swift +// Safe to use across tasks +func authenticateUser() async throws { + let config = MistKitConfiguration( + container: "iCloud.com.example", + environment: .production, + database: .private, + apiToken: ProcessInfo.processInfo.environment["API_TOKEN"]! + ) + + // Can safely pass config to another task + async let client1 = MistKitClient(configuration: config) + async let client2 = MistKitClient(configuration: config) + + // No data races - config is Sendable + let (c1, c2) = try await (client1, c2) +} +``` + +### Sendable Middleware + +```swift +// Middleware structs are Sendable +internal struct AuthenticationMiddleware: ClientMiddleware { ... } +internal struct LoggingMiddleware: ClientMiddleware { ... } + +// Can be safely shared across actors +actor RequestManager { + let authMiddleware: AuthenticationMiddleware // Safe! + + func makeRequest() async throws { + // Use middleware safely within actor + } +} +``` + +## Protocol-Oriented Design + +MistKit uses protocols extensively to enable flexibility, testability, and clean architecture. + +### TokenManager Hierarchy + +``` + TokenManager + (protocol) + ↑ + ┌────────────────┼────────────────┐ + │ │ │ + APITokenManager WebAuthTokenManager ServerToServerAuthManager + (struct) (struct) (struct) + │ + AdaptiveTokenManager + (actor) +``` + +#### 1. APITokenManager + +```swift +/// Manages API token authentication +public struct APITokenManager: TokenManager { + public let token: String + + public var hasCredentials: Bool { + get async { !token.isEmpty } + } + + public func validateCredentials() async throws(TokenManagerError) -> Bool { + try Self.validateAPITokenFormat(token) + return true + } + + public func getCurrentCredentials() async throws(TokenManagerError) -> TokenCredentials? { + try await validateCredentials() + return TokenCredentials(method: .apiToken(token)) + } +} +``` + +**Use case:** Container-level access, read-only operations on public database + +#### 2. WebAuthTokenManager + +```swift +/// Manages web authentication with both API and web auth tokens +public struct WebAuthTokenManager: TokenManager { + public let apiToken: String + public let webAuthToken: String + + public var hasCredentials: Bool { + get async { !apiToken.isEmpty && !webAuthToken.isEmpty } + } + + public func validateCredentials() async throws(TokenManagerError) -> Bool { + try Self.validateAPITokenFormat(apiToken) + try Self.validateWebAuthTokenFormat(webAuthToken) + return true + } + + public func getCurrentCredentials() async throws(TokenManagerError) -> TokenCredentials? { + try await validateCredentials() + return TokenCredentials(method: .webAuthToken(apiToken, webAuthToken)) + } +} +``` + +**Use case:** User-specific operations, private/shared database access + +#### 3. ServerToServerAuthManager + +```swift +/// Manages server-to-server authentication using ECDSA P-256 signatures +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +public struct ServerToServerAuthManager: TokenManager { + public let keyIdentifier: String + public let privateKeyData: Data + private let privateKey: P256.Signing.PrivateKey + + public init(keyID: String, privateKeyData: Data) throws { + self.keyIdentifier = keyID + self.privateKeyData = privateKeyData + self.privateKey = try P256.Signing.PrivateKey(rawRepresentation: privateKeyData) + } + + public func signRequest( + requestBody: Data?, + webServiceURL: String + ) throws -> RequestSignature { + let currentDate = Date() + let iso8601Date = ISO8601DateFormatter().string(from: currentDate) + + // Create signature payload + let payload = "\(iso8601Date):\(requestBody?.base64EncodedString() ?? ""):\(webServiceURL)" + let payloadData = Data(payload.utf8) + + // Sign with ECDSA P-256 + let signature = try privateKey.signature(for: SHA256.hash(data: payloadData)) + let signatureBase64 = signature.rawRepresentation.base64EncodedString() + + return RequestSignature( + keyID: keyIdentifier, + date: iso8601Date, + signature: signatureBase64 + ) + } +} +``` + +**Use case:** Enterprise/server applications, public database only, no user context + +### Benefits of Protocol-Oriented Design + +**1. Easy testing with mocks:** + +```swift +struct MockTokenManager: TokenManager { + var mockCredentials: TokenCredentials? + var shouldThrow: Bool = false + + var hasCredentials: Bool { + get async { mockCredentials != nil } + } + + func validateCredentials() async throws(TokenManagerError) -> Bool { + if shouldThrow { + throw TokenManagerError.invalidCredentials(.apiTokenEmpty) + } + return mockCredentials != nil + } + + func getCurrentCredentials() async throws(TokenManagerError) -> TokenCredentials? { + mockCredentials + } +} + +// Use in tests +let mockManager = MockTokenManager(mockCredentials: .apiToken("test-token")) +let client = try MistKitClient( + configuration: testConfig, + tokenManager: mockManager, + transport: mockTransport +) +``` + +**2. Flexible implementation swapping:** + +```swift +// Development: Use API token +let devTokenManager = APITokenManager(token: devAPIToken) + +// Production: Use server-to-server auth +let prodTokenManager = try ServerToServerAuthManager( + keyID: prodKeyID, + privateKeyData: prodPrivateKey +) + +// Same client code works with either +let client = try MistKitClient( + configuration: config, + tokenManager: prodTokenManager // or devTokenManager +) +``` + +**3. Protocol extensions for shared logic:** + +```swift +extension TokenManager { + /// Shared validation logic for all token managers + internal static func validateAPITokenFormat(_ apiToken: String) throws(TokenManagerError) { + guard !apiToken.isEmpty else { + throw TokenManagerError.invalidCredentials(.apiTokenEmpty) + } + + let regex = NSRegularExpression.apiTokenRegex + let matches = regex.matches(in: apiToken) + + guard !matches.isEmpty else { + throw TokenManagerError.invalidCredentials(.apiTokenInvalidFormat) + } + } +} +``` + +## Dependency Injection Pattern + +MistKit uses constructor injection to promote testability and flexibility. + +### MistKitClient Initialization + +```swift +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +internal struct MistKitClient { + internal let client: Client + + /// Initialize with explicit dependencies + internal init( + configuration: MistKitConfiguration, + tokenManager: any TokenManager, + transport: any ClientTransport + ) throws { + // Validate configuration + try Self.validateServerToServerConfiguration( + configuration: configuration, + tokenManager: tokenManager + ) + + // Create client with injected dependencies + self.client = Client( + serverURL: configuration.serverURL, + transport: transport, + middlewares: [ + AuthenticationMiddleware(tokenManager: tokenManager), + LoggingMiddleware() + ] + ) + } + + /// Convenience initializer with defaults + internal init(configuration: MistKitConfiguration) throws { + let tokenManager = try configuration.createTokenManager() + try self.init( + configuration: configuration, + tokenManager: tokenManager, + transport: URLSessionTransport() // Default transport + ) + } +} +``` + +**Benefits:** + +1. **Testability**: Inject mock transport and token managers +2. **Flexibility**: Swap implementations without changing client code +3. **Clear dependencies**: Explicit about what the client needs +4. **Defaults available**: Convenience initializers for common cases + +### Testing with Dependency Injection + +```swift +// Production code +let client = try MistKitClient(configuration: prodConfig) + +// Test code - inject mocks +let mockTransport = MockTransport(cannedResponse: mockQueryResponse) +let mockTokenManager = MockTokenManager(mockCredentials: testCredentials) + +let testClient = try MistKitClient( + configuration: testConfig, + tokenManager: mockTokenManager, + transport: mockTransport +) + +// Test without hitting real network +let response = try await testClient.queryRecords(...) +``` + +## Custom Type Mapping: CustomFieldValue + +MistKit overrides the generated `FieldValue` type with a custom implementation that provides better handling of CloudKit field types. + +### Type Override Configuration + +```yaml +# openapi-generator-config.yaml +typeOverrides: + schemas: + FieldValue: CustomFieldValue +``` + +### Implementation + +```swift +/// Custom implementation of FieldValue with proper ASSETID handling +internal struct CustomFieldValue: Codable, Hashable, Sendable { + /// Field type payload for CloudKit fields + public enum FieldTypePayload: String, Codable, Hashable, Sendable, CaseIterable { + case string = "STRING" + case int64 = "INT64" + case double = "DOUBLE" + case bytes = "BYTES" + case reference = "REFERENCE" + case asset = "ASSET" + case assetid = "ASSETID" // Special handling for asset IDs + case location = "LOCATION" + case timestamp = "TIMESTAMP" + case list = "LIST" + } + + /// Custom field value payload supporting various CloudKit types + public enum CustomFieldValuePayload: Codable, Hashable, Sendable { + case stringValue(String) + case int64Value(Int) + case doubleValue(Double) + case booleanValue(Bool) + case bytesValue(String) + case dateValue(Double) + case locationValue(Components.Schemas.LocationValue) + case referenceValue(Components.Schemas.ReferenceValue) + case assetValue(Components.Schemas.AssetValue) + case listValue([CustomFieldValuePayload]) + } + + internal let value: CustomFieldValuePayload + internal let type: FieldTypePayload? + + // Custom Codable implementation with type-specific decoders + private static let fieldTypeDecoders: + [FieldTypePayload: @Sendable (KeyedDecodingContainer) throws + -> CustomFieldValuePayload] = [ + .string: { .stringValue(try $0.decode(String.self, forKey: .value)) }, + .int64: { .int64Value(try $0.decode(Int.self, forKey: .value)) }, + .asset: { .assetValue(try $0.decode(Components.Schemas.AssetValue.self, forKey: .value)) }, + .assetid: { .assetValue(try $0.decode(Components.Schemas.AssetValue.self, forKey: .value)) }, + // ... more decoders + ] +} +``` + +**Why custom implementation?** + +1. **CloudKit-specific handling**: ASSETID type requires special treatment +2. **Better ergonomics**: Enum-based value access instead of dictionaries +3. **Type safety**: Compile-time checking for field value types +4. **Proper encoding**: Handles CloudKit's JSON format correctly + +### Usage Comparison + +**Before (generated FieldValue):** + +```swift +// Hypothetical generated code (generic, not CloudKit-specific) +let fieldValue = FieldValue(value: ["someKey": someValue]) +// Type: Any? - no compile-time safety +``` + +**After (CustomFieldValue):** + +```swift +// Type-safe, CloudKit-aware +let fieldValue = CustomFieldValue( + value: .stringValue("John Doe"), + type: .string +) + +// Pattern matching for safe access +switch fieldValue.value { +case .stringValue(let name): + print("Name: \(name)") +case .int64Value(let age): + print("Age: \(age)") +case .assetValue(let asset): + print("Asset URL: \(asset.downloadURL)") +default: + break +} +``` + +## Error Handling with Typed Throws + +MistKit leverages Swift 6's typed throws for precise error handling. + +### TokenManagerError + +```swift +/// Errors that can occur during token management +public enum TokenManagerError: Error, Sendable { + case invalidCredentials(InvalidCredentialReason) + case internalError(InternalErrorReason) +} + +/// Specific reasons for invalid credentials +public enum InvalidCredentialReason: Sendable { + case apiTokenEmpty + case apiTokenInvalidFormat + case webAuthTokenEmpty + case webAuthTokenTooShort + case noCredentialsAvailable + case serverToServerOnlySupportsPublicDatabase(String) +} +``` + +### Usage with Typed Throws + +```swift +// Function signature with typed throws +func validateCredentials() async throws(TokenManagerError) -> Bool + +// Caller knows exactly what error type to expect +do { + let isValid = try await tokenManager.validateCredentials() +} catch let error as TokenManagerError { + // Can switch on specific error cases + switch error { + case .invalidCredentials(.apiTokenEmpty): + print("API token is empty") + case .invalidCredentials(.apiTokenInvalidFormat): + print("API token format is invalid") + case .internalError(let reason): + print("Internal error: \(reason)") + } +} +``` + +**Comparison with untyped throws:** + +```swift +// Untyped throws - unclear what errors can occur +func validateCredentials() async throws -> Bool + +// Typed throws - explicit error type +func validateCredentials() async throws(TokenManagerError) -> Bool +``` + +## Security and Logging + +### Secure Logging + +MistKit implements secure logging that automatically masks sensitive information: + +```swift +internal enum SecureLogging { + /// Masks tokens and sensitive data in log messages + internal static func maskToken(_ token: String) -> String { + guard token.count > 8 else { + return "***" + } + let prefix = token.prefix(4) + let suffix = token.suffix(4) + return "\(prefix)***\(suffix)" + } + + /// Safely log messages with automatic token masking + internal static func safeLogMessage(_ message: String) -> String { + var safe = message + + // Mask API tokens + safe = safe.replacingOccurrences( + of: #"ckAPIToken=[^&\s]+"#, + with: "ckAPIToken=***", + options: .regularExpression + ) + + // Mask web auth tokens + safe = safe.replacingOccurrences( + of: #"ckWebAuthToken=[^&\s]+"#, + with: "ckWebAuthToken=***", + options: .regularExpression + ) + + return safe + } +} +``` + +### LoggingMiddleware with Security + +```swift +internal struct LoggingMiddleware: ClientMiddleware { + #if DEBUG + private func logRequest(_ request: HTTPRequest, baseURL: URL) { + print("🌐 CloudKit Request: \(request.method.rawValue) \(fullPath)") + + // Log query parameters with masking + for item in queryItems { + let value = formatQueryValue(for: item) // Masks sensitive values + print(" \(item.name): \(value)") + } + } + + private func formatQueryValue(for item: URLQueryItem) -> String { + guard let value = item.value else { return "nil" } + + // Mask sensitive query parameters + if item.name.lowercased().contains("token") || + item.name.lowercased().contains("key") { + return SecureLogging.maskToken(value) + } + + return value + } + #endif +} +``` + +**Output example:** + +``` +🌐 CloudKit Request: POST https://api.apple-cloudkit.com/database/1/iCloud.com.example/production/private/records/query + ckAPIToken: c34a***7d9f + ckWebAuthToken: 9f2e***4b1a +``` + +## Future Architecture Enhancements + +While MistKit's current architecture is robust, several modern Swift features could further enhance the abstraction layer: + +### Potential: Actor-Based Token Management + +```swift +// Future: Actor for thread-safe token caching +actor TokenCacheManager: TokenManager { + private var cachedCredentials: TokenCredentials? + private var lastValidation: Date? + private let validationInterval: TimeInterval = 300 // 5 minutes + + func getCurrentCredentials() async throws(TokenManagerError) -> TokenCredentials? { + // Check cache + if let cached = cachedCredentials, + let lastValidation = lastValidation, + Date().timeIntervalSince(lastValidation) < validationInterval { + return cached + } + + // Fetch and cache new credentials + let credentials = try await fetchCredentials() + self.cachedCredentials = credentials + self.lastValidation = Date() + return credentials + } +} +``` + +**Benefits:** +- ✅ Thread-safe token caching +- ✅ Automatic invalidation +- ✅ No data races + +### Potential: AsyncSequence for Pagination + +```swift +// Future: AsyncSequence for paginated queries +struct RecordQuerySequence: AsyncSequence { + typealias Element = CloudKitRecord + + let query: RecordQuery + let client: MistKitClient + + func makeAsyncIterator() -> Iterator { + Iterator(query: query, client: client) + } + + struct Iterator: AsyncIteratorProtocol { + var continuationMarker: String? + let query: RecordQuery + let client: MistKitClient + + mutating func next() async throws -> CloudKitRecord? { + let response = try await client.queryRecords( + query: query, + continuationMarker: continuationMarker + ) + + continuationMarker = response.continuationMarker + + return response.records.first + } + } +} + +// Usage +for try await record in client.queryRecords(type: "User") { + print(record.name) + // Automatically fetches next page when needed +} +``` + +### Potential: Result Builders for Query Construction + +```swift +// Future: Result builder for declarative queries +@resultBuilder +enum QueryBuilder { + static func buildBlock(_ components: QueryFilter...) -> [QueryFilter] { + components + } +} + +func query(@QueryBuilder _ filters: () -> [QueryFilter]) -> RecordQuery { + RecordQuery(filters: filters()) +} + +// Usage +let userQuery = query { + Filter(field: "age", comparator: .greaterThan, value: 18) + Filter(field: "status", comparator: .equals, value: "active") + Sort(field: "lastName", ascending: true) +} + +// vs. current approach +let userQuery = RecordQuery( + filters: [ + Filter(field: "age", comparator: .greaterThan, value: 18), + Filter(field: "status", comparator: .equals, value: "active") + ], + sorts: [ + Sort(field: "lastName", ascending: true) + ] +) +``` + +### Potential: Property Wrappers for Field Mapping + +```swift +// Future: Property wrappers for model mapping +@propertyWrapper +struct CloudKitField { + let key: String + var wrappedValue: Value + + init(wrappedValue: Value, _ key: String) { + self.key = key + self.wrappedValue = wrappedValue + } +} + +struct User { + @CloudKitField("firstName") var firstName: String + @CloudKitField("lastName") var lastName: String + @CloudKitField("age") var age: Int + @CloudKitField("email") var email: String + + // Automatic mapping to/from CloudKit records +} + +// vs. current approach (manual field mapping) +let record = CloudKitRecord( + fields: [ + "firstName": .stringValue(user.firstName), + "lastName": .stringValue(user.lastName), + "age": .int64Value(user.age), + "email": .stringValue(user.email) + ] +) +``` + +## Summary + +MistKit's abstraction layer provides: + +### Current Implementation + +- ✅ **Async/await integration** throughout the API +- ✅ **Sendable compliance** for Swift 6 concurrency safety +- ✅ **Protocol-oriented design** enabling flexibility and testability +- ✅ **Dependency injection** for loose coupling +- ✅ **Middleware pattern** for cross-cutting concerns +- ✅ **Custom type mapping** for CloudKit-specific needs +- ✅ **Typed throws** for precise error handling +- ✅ **Secure logging** with automatic credential masking + +### Architectural Benefits + +- 🎯 **Type safety** from the generated code through to the API surface +- 🎯 **Testability** through protocol abstractions and dependency injection +- 🎯 **Maintainability** with clear separation of concerns +- 🎯 **Ergonomics** hiding complexity without losing functionality +- 🎯 **Cross-platform** support (macOS, iOS, tvOS, watchOS, Linux) +- 🎯 **Future-proof** leveraging latest Swift features + +### Future Enhancements + +- 🔮 Actor-based token caching for improved concurrency +- 🔮 AsyncSequence for elegant pagination +- 🔮 Result builders for declarative query construction +- 🔮 Property wrappers for simplified model mapping + +## See Also + +- +- +- +- [Swift Concurrency Documentation](https://docs.swift.org/swift-book/LanguageGuide/Concurrency.html) +- [Protocol-Oriented Programming in Swift](https://developer.apple.com/videos/play/wwdc2015/408/) diff --git a/Sources/MistKit/Documentation.docc/Documentation.md b/Sources/MistKit/Documentation.docc/Documentation.md index c73e5624..5b7602ce 100644 --- a/Sources/MistKit/Documentation.docc/Documentation.md +++ b/Sources/MistKit/Documentation.docc/Documentation.md @@ -132,6 +132,13 @@ Server-to-server authentication requires Crypto framework support: ## Topics +### Architecture and Development + +- +- +- +- + ### Services - ``CloudKitService`` diff --git a/Sources/MistKit/Documentation.docc/GeneratedCodeAnalysis.md b/Sources/MistKit/Documentation.docc/GeneratedCodeAnalysis.md new file mode 100644 index 00000000..6ebc30c9 --- /dev/null +++ b/Sources/MistKit/Documentation.docc/GeneratedCodeAnalysis.md @@ -0,0 +1,1140 @@ +# Generated Code Structure Analysis + +A deep dive into the Swift code generated by swift-openapi-generator, with annotated examples showing type safety, architecture patterns, and integration points. + +## Overview + +The swift-openapi-generator produces **10,476 lines** of type-safe Swift code from the CloudKit Web Services OpenAPI specification. This article provides a detailed analysis of the generated code structure, explaining how it achieves compile-time safety, handles HTTP operations, and integrates with MistKit's wrapper layer. + +## Generated File Organization + +### File Structure + +``` +Sources/MistKit/Generated/ +├── Client.swift (3,268 lines) - API client implementation +└── Types.swift (7,208 lines) - Type definitions +``` + +### File Headers + +Both generated files include important header comments: + +```swift +// Generated by swift-openapi-generator, do not modify. +// periphery:ignore:all +// swift-format-ignore-file +@_spi(Generated) import OpenAPIRuntime +``` + +**Header elements explained:** + +- **`// Generated by swift-openapi-generator, do not modify.`** + Warning to developers not to edit generated code (changes would be overwritten) + +- **`// periphery:ignore:all`** + Instructs [Periphery](https://github.com/peripheryapp/periphery) (dead code analyzer) to skip this file, avoiding false positives for unused methods + +- **`// swift-format-ignore-file`** + Prevents [swift-format](https://github.com/apple/swift-format) from reformatting generated code + +- **`@_spi(Generated) import OpenAPIRuntime`** + Imports internal/SPI (System Programming Interface) APIs from OpenAPIRuntime needed for generation + +## Client.swift: API Client Implementation + +### 1. APIProtocol: The Contract + +The `APIProtocol` defines the complete API surface as a Sendable protocol: + +```swift +/// A type that performs HTTP operations defined by the OpenAPI document. +internal protocol APIProtocol: Sendable { + /// Query Records + /// + /// Fetch records using a query with filters and sorting options + /// + /// - Remark: HTTP `POST /database/{version}/{container}/{environment}/{database}/records/query`. + /// - Remark: Generated from `#/paths//database/.../records/query/post(queryRecords)`. + func queryRecords(_ input: Operations.queryRecords.Input) async throws + -> Operations.queryRecords.Output + + /// Modify Records + /// + /// Create, update, or delete records (supports bulk operations) + /// + /// - Remark: HTTP `POST /database/{version}/{container}/{environment}/{database}/records/modify`. + func modifyRecords(_ input: Operations.modifyRecords.Input) async throws + -> Operations.modifyRecords.Output + + // ... 13 more operations (15 total) +} +``` + +**Key characteristics:** + +- ✅ **Sendable conformance**: Thread-safe by default for Swift 6 concurrency +- ✅ **Async/await**: All operations use modern concurrency +- ✅ **Typed errors**: `throws` enables typed error handling +- ✅ **Documentation**: Each method includes HTTP verb, path, and OpenAPI reference +- ✅ **Operation namespacing**: Input/Output types scoped to specific operations + +### 2. Client Struct: The Implementation + +The `Client` struct implements `APIProtocol`: + +```swift +internal struct Client: APIProtocol { + /// The underlying HTTP client + private let client: UniversalClient + + /// Creates a new client + /// - Parameters: + /// - serverURL: The server URL (from Servers enum or custom) + /// - configuration: Client configuration options + /// - transport: HTTP transport layer (URLSession, custom, etc.) + /// - middlewares: Request/response middleware chain + internal init( + serverURL: Foundation.URL, + configuration: Configuration = .init(), + transport: any ClientTransport, + middlewares: [any ClientMiddleware] = [] + ) { + self.client = .init( + serverURL: serverURL, + configuration: configuration, + transport: transport, + middlewares: middlewares + ) + } +} +``` + +**Architecture benefits:** + +- **Dependency injection**: Transport and middlewares are injectable for testing +- **Configuration flexibility**: Optional configuration with sensible defaults +- **Middleware support**: Enables authentication, logging, retry logic, etc. +- **Protocol abstraction**: Implementation hidden behind `APIProtocol` + +### 3. Operation Implementation Pattern + +Each operation follows a consistent pattern. Here's `queryRecords`: + +```swift +internal func queryRecords(_ input: Operations.queryRecords.Input) async throws + -> Operations.queryRecords.Output +{ + try await client.send( + input: input, + forOperation: Operations.queryRecords.id, + serializer: { input in + // Build HTTP request from typed input + let path = try converter.renderedPath( + template: "/database/{}/{}/{}/{}/records/query", + parameters: [ + input.path.version, + input.path.container, + input.path.environment, + input.path.database + ] + ) + + var request: HTTPTypes.HTTPRequest = .init( + soar_path: path, + method: .post + ) + + // Set headers + converter.setAcceptHeader( + in: &request.headerFields, + contentTypes: input.headers.accept + ) + + // Serialize body + let body: OpenAPIRuntime.HTTPBody? + switch input.body { + case let .json(value): + body = try converter.setRequiredRequestBodyAsJSON( + value, + headerFields: &request.headerFields, + contentType: "application/json; charset=utf-8" + ) + } + + return (request, body) + }, + deserializer: { response, responseBody in + // Deserialize HTTP response to typed output + switch response.status.code { + case 200: + let body = try await converter.getResponseBodyAsJSON( + Components.Schemas.QueryResponse.self, + from: responseBody, + transforming: { .json($0) } + ) + return .ok(.init(body: body)) + + case 400: + let body = try await converter.getResponseBodyAsJSON( + Components.Schemas.ErrorResponse.self, + from: responseBody, + transforming: { .json($0) } + ) + return .badRequest(.init(body: body)) + + // ... cases for 401, 403, 404, 409, 412, 413, etc. + + default: + return .undocumented( + statusCode: response.status.code, + .init(headerFields: response.headerFields, body: responseBody) + ) + } + } + ) +} +``` + +**Pattern breakdown:** + +1. **Serializer closure**: Converts typed `Input` → raw HTTP request +2. **Path rendering**: Type-safe path parameter substitution +3. **Header management**: Content-Type and Accept headers automatically set +4. **Body serialization**: Codable JSON encoding with proper content types +5. **Deserializer closure**: Converts raw HTTP response → typed `Output` +6. **Status code switching**: Each HTTP status becomes a distinct enum case +7. **Type-safe deserialization**: JSON decoded to specific schema types +8. **Undocumented fallback**: Handles unexpected status codes gracefully + +### 4. Convenience Extensions + +For better ergonomics, generated code includes convenience overloads: + +```swift +extension APIProtocol { + /// Query Records + /// + /// Convenience overload with parameters instead of Input struct + internal func queryRecords( + path: Operations.queryRecords.Input.Path, + headers: Operations.queryRecords.Input.Headers = .init(), + body: Operations.queryRecords.Input.Body + ) async throws -> Operations.queryRecords.Output { + try await queryRecords(Operations.queryRecords.Input( + path: path, + headers: headers, + body: body + )) + } +} +``` + +**Usage comparison:** + +```swift +// Without convenience extension +let response = try await client.queryRecords(.init( + path: .init(version: "1", container: "iCloud.com.example", + environment: .production, database: ._public), + headers: .init(accept: [.json]), + body: .json(.init(query: .init(recordType: "User"))) +)) + +// With convenience extension (cleaner) +let response = try await client.queryRecords( + path: .init(version: "1", container: "iCloud.com.example", + environment: .production, database: ._public), + body: .json(.init(query: .init(recordType: "User"))) +) +``` + +### 5. Servers Enum + +Server URLs from the OpenAPI spec are codified as type-safe enums: + +```swift +/// Server URLs defined in the OpenAPI document +internal enum Servers { + /// CloudKit Web Services API + internal enum Server1 { + internal static func url() throws -> Foundation.URL { + try Foundation.URL( + validatingOpenAPIServerURL: "https://api.apple-cloudkit.com", + variables: [] + ) + } + } +} +``` + +**Usage:** + +```swift +let serverURL = try Servers.Server1.url() +let client = Client( + serverURL: serverURL, + transport: URLSessionTransport() +) +``` + +This prevents hardcoded URL strings and enables server URL validation. + +## Types.swift: Type Definitions + +### 1. Components Namespace + +All types are organized under the `Components` enum namespace: + +```swift +/// Types generated from the components section of the OpenAPI document +internal enum Components { + /// Types generated from `#/components/schemas` + internal enum Schemas { /* data models */ } + + /// Types generated from `#/components/parameters` + internal enum Parameters { /* parameter types */ } + + /// Types generated from `#/components/requestBodies` + internal enum RequestBodies { /* (empty in CloudKit API) */ } + + /// Types generated from `#/components/responses` + internal enum Responses { /* reusable response types */ } +} +``` + +### 2. Schema Types: Data Models + +Schemas become structs with Codable, Hashable, and Sendable conformance: + +```swift +/// - Remark: Generated from `#/components/schemas/ZoneID` +internal struct ZoneID: Codable, Hashable, Sendable { + /// - Remark: Generated from `#/components/schemas/ZoneID/zoneName` + internal var zoneName: Swift.String? + + /// - Remark: Generated from `#/components/schemas/ZoneID/ownerName` + internal var ownerName: Swift.String? + + /// Creates a new `ZoneID` + /// + /// - Parameters: + /// - zoneName: Zone name + /// - ownerName: Owner name + internal init( + zoneName: Swift.String? = nil, + ownerName: Swift.String? = nil + ) { + self.zoneName = zoneName + self.ownerName = ownerName + } + + internal enum CodingKeys: String, CodingKey { + case zoneName + case ownerName + } +} +``` + +**Generated features:** + +- ✅ Optional properties with nil defaults +- ✅ Explicit CodingKeys for JSON mapping +- ✅ Memberwise initializer with defaults +- ✅ Full protocol conformance (Codable, Hashable, Sendable) +- ✅ OpenAPI reference in documentation + +### 3. Enum Types: Type-Safe Constants + +String enums in OpenAPI become Swift enums with raw values: + +```swift +/// - Remark: Generated from `#/components/schemas/Filter/comparator` +internal enum comparatorPayload: String, Codable, Hashable, Sendable, CaseIterable { + case EQUALS = "EQUALS" + case NOT_EQUALS = "NOT_EQUALS" + case LESS_THAN = "LESS_THAN" + case LESS_THAN_OR_EQUALS = "LESS_THAN_OR_EQUALS" + case GREATER_THAN = "GREATER_THAN" + case GREATER_THAN_OR_EQUALS = "GREATER_THAN_OR_EQUALS" + case NEAR = "NEAR" + case CONTAINS_ALL_TOKENS = "CONTAINS_ALL_TOKENS" + case IN = "IN" + case NOT_IN = "NOT_IN" + case CONTAINS_ANY_TOKENS = "CONTAINS_ANY_TOKENS" + case LIST_CONTAINS = "LIST_CONTAINS" + case NOT_LIST_CONTAINS = "NOT_LIST_CONTAINS" + case BEGINS_WITH = "BEGINS_WITH" + case NOT_BEGINS_WITH = "NOT_BEGINS_WITH" + case LIST_MEMBER_BEGINS_WITH = "LIST_MEMBER_BEGINS_WITH" + case NOT_LIST_MEMBER_BEGINS_WITH = "NOT_LIST_MEMBER_BEGINS_WITH" +} +``` + +**Type safety benefits:** + +- ✅ Autocomplete for all valid values +- ✅ Compile-time checking (can't use invalid comparator) +- ✅ CaseIterable for enumeration +- ✅ Codable for automatic JSON encoding/decoding + +**Before (string literals):** +```swift +// Easy to typo, no autocomplete +let filter = Filter(comparator: "GRETER_THAN", ...) // Typo! +``` + +**After (type-safe enum):** +```swift +// Autocomplete, compile-time safety +let filter = Filter(comparator: .GREATER_THAN, ...) +``` + +### 4. Error Response Types + +Error responses are fully typed with nested enums for error codes: + +```swift +/// - Remark: Generated from `#/components/schemas/ErrorResponse` +internal struct ErrorResponse: Codable, Hashable, Sendable { + internal var uuid: Swift.String? + + /// Server error code enum + internal enum serverErrorCodePayload: String, Codable, Hashable, Sendable { + case ACCESS_DENIED = "ACCESS_DENIED" + case ATOMIC_ERROR = "ATOMIC_ERROR" + case AUTHENTICATION_FAILED = "AUTHENTICATION_FAILED" + case AUTHENTICATION_REQUIRED = "AUTHENTICATION_REQUIRED" + case BAD_REQUEST = "BAD_REQUEST" + case CONFLICT = "CONFLICT" + case EXISTS = "EXISTS" + case INTERNAL_ERROR = "INTERNAL_ERROR" + case NOT_FOUND = "NOT_FOUND" + case QUOTA_EXCEEDED = "QUOTA_EXCEEDED" + case THROTTLED = "THROTTLED" + case TRY_AGAIN_LATER = "TRY_AGAIN_LATER" + case VALIDATING_REFERENCE_ERROR = "VALIDATING_REFERENCE_ERROR" + case ZONE_NOT_FOUND = "ZONE_NOT_FOUND" + } + + internal var serverErrorCode: serverErrorCodePayload? + internal var reason: Swift.String? + internal var redirectURL: Swift.String? +} +``` + +**Error handling example:** + +```swift +do { + let response = try await client.queryRecords(...) +} catch { + // Type-safe error handling + if case let .badRequest(badRequest) = response, + case let .json(errorResponse) = try badRequest.body.json, + errorResponse.serverErrorCode == .AUTHENTICATION_FAILED { + print("Authentication failed: \(errorResponse.reason ?? "Unknown")") + } +} +``` + +### 5. Parameters: Path and Query Parameters + +Parameters are defined as typealiases or enums: + +```swift +internal enum Parameters { + /// Protocol version + /// - Remark: Generated from `#/components/parameters/version` + internal typealias version = Swift.String + + /// Container ID (begins with "iCloud.") + /// - Remark: Generated from `#/components/parameters/container` + internal typealias container = Swift.String + + /// Container environment + /// - Remark: Generated from `#/components/parameters/environment` + internal enum environment: String, Codable, Hashable, Sendable, CaseIterable { + case development = "development" + case production = "production" + } + + /// Database scope + /// - Remark: Generated from `#/components/parameters/database` + internal enum database: String, Codable, Hashable, Sendable, CaseIterable { + case _public = "public" // Leading underscore (Swift keyword) + case _private = "private" // Leading underscore (Swift keyword) + case shared = "shared" + } +} +``` + +**Keyword escaping:** + +Notice `_public` and `_private` have leading underscores because `public` and `private` are Swift keywords. The generator handles this automatically. + +### 6. Operations Namespace + +Each API operation gets a dedicated namespace with Input and Output types: + +```swift +internal enum Operations { + internal enum queryRecords { + internal static let id: Swift.String = "queryRecords" + + // INPUT TYPES + internal struct Input: Sendable, Hashable { + /// Path parameters + internal struct Path: Sendable, Hashable { + internal var version: Components.Parameters.version + internal var container: Components.Parameters.container + internal var environment: Components.Parameters.environment + internal var database: Components.Parameters.database + } + + /// Headers + internal struct Headers: Sendable, Hashable { + internal var accept: [OpenAPIRuntime.AcceptHeaderContentType< + Operations.queryRecords.AcceptableContentType + >] + + internal init( + accept: [OpenAPIRuntime.AcceptHeaderContentType< + Operations.queryRecords.AcceptableContentType + >] = .defaultValues() + ) { + self.accept = accept + } + } + + /// Request body + internal enum Body: Sendable, Hashable { + case json(Components.Schemas.QueryRequest) + } + + internal var path: Path + internal var headers: Headers + internal var body: Body + } + + // OUTPUT TYPES + internal enum Output: Sendable, Hashable { + /// 200 OK response + internal struct Ok: Sendable, Hashable { + internal enum Body: Sendable, Hashable { + case json(Components.Schemas.QueryResponse) + + internal var json: Components.Schemas.QueryResponse { + get throws { + switch self { + case let .json(body): return body + } + } + } + } + internal var body: Body + } + + /// Response cases for each HTTP status + case ok(Ok) + case badRequest(Components.Responses.BadRequest) + case unauthorized(Components.Responses.Unauthorized) + case forbidden(Components.Responses.Forbidden) + case notFound(Components.Responses.NotFound) + case conflict(Components.Responses.Conflict) + case preconditionFailed(Components.Responses.PreconditionFailed) + case requestEntityTooLarge(Components.Responses.RequestEntityTooLarge) + case undocumented(statusCode: Int, UndocumentedPayload) + } + } +} +``` + +**Type hierarchy:** + +``` +Operations +└── queryRecords + ├── id (operation identifier) + ├── Input + │ ├── Path (path parameters) + │ ├── Headers (HTTP headers) + │ └── Body (request body) + └── Output (enum of response cases) + ├── ok(Ok) + ├── badRequest(...) + ├── unauthorized(...) + └── undocumented(...) +``` + +This deep nesting prevents naming conflicts and keeps types organized by operation. + +### 7. Response Body Access Pattern + +Generated response types use throwing computed properties for safe unwrapping: + +```swift +internal enum Body: Sendable, Hashable { + case json(Components.Schemas.QueryResponse) + + /// Safe accessor throwing if wrong case + internal var json: Components.Schemas.QueryResponse { + get throws { + switch self { + case let .json(body): + return body + } + } + } +} +``` + +**Usage:** + +```swift +let response = try await client.queryRecords(...) + +switch response { +case let .ok(okResponse): + // Type-safe access to response body + let queryResponse = try okResponse.body.json + for record in queryResponse.records ?? [] { + print(record) + } + +case let .badRequest(errorResponse): + let error = try errorResponse.body.json + print("Error: \(error.serverErrorCode)") + +default: + print("Unexpected response") +} +``` + +## Type Safety Comparison + +### Before: Manual HTTP + JSON + +```swift +// Manual HTTP client - error-prone, no compile-time safety + +let urlString = "https://api.apple-cloudkit.com/database/1/" + + "\(container)/production/public/records/query" +var request = URLRequest(url: URL(string: urlString)!) +request.httpMethod = "POST" +request.setValue("application/json", forHTTPHeaderField: "Content-Type") + +// Easy to make mistakes - typos, wrong nesting, missing fields +let json: [String: Any] = [ + "query": [ + "recordType": "User", + "filterBy": [ // Typo: should be array of filter objects + "fieldName": "age", + "comparator": "GRETER_THAN", // Typo: GREATER_THAN + "fieldValue": ["value": 18] + ] + ] +] + +let data = try JSONSerialization.data(withJSONObject: json) +request.httpBody = data + +let (responseData, _) = try await URLSession.shared.data(for: request) + +// Manual parsing - type casting everywhere +let responseJSON = try JSONSerialization.jsonObject(with: responseData) as! [String: Any] +let records = responseJSON["records"] as? [[String: Any]] ?? [] +``` + +**Problems:** + +- ❌ No compile-time verification +- ❌ Easy to typo field names +- ❌ Wrong types accepted (e.g., single dict instead of array) +- ❌ Typos in enum values ("GRETER_THAN") +- ❌ Manual JSON serialization/deserialization +- ❌ Type casting hell +- ❌ No autocomplete support + +### After: Generated Type-Safe Client + +```swift +// Type-safe generated client - compile-time safety, autocomplete + +let response = try await client.queryRecords( + path: .init( + version: "1", + container: container, + environment: .production, // Enum - can't typo + database: ._public // Enum - can't typo + ), + body: .json(.init( + query: .init( + recordType: "User", + filterBy: [ // Correctly typed as array + .init( + fieldName: "age", + comparator: .GREATER_THAN, // Enum - autocomplete, can't typo + fieldValue: .init(value: .int64(18)) // Type-safe value + ) + ] + ) + )) +) + +// Type-safe response handling +switch response { +case let .ok(okResponse): + let queryResponse = try okResponse.body.json + // queryResponse is strongly typed as Components.Schemas.QueryResponse + for record in queryResponse.records ?? [] { + // record is strongly typed + print(record.recordName) + } + +case let .badRequest(error): + let errorResponse = try error.body.json + // errorResponse is strongly typed as Components.Schemas.ErrorResponse + if errorResponse.serverErrorCode == .AUTHENTICATION_FAILED { + print("Auth failed: \(errorResponse.reason ?? "")") + } + +default: + print("Unexpected response") +} +``` + +**Benefits:** + +- ✅ Compile-time verification of request structure +- ✅ Autocomplete for all fields and enums +- ✅ Impossible to typo enum values +- ✅ Correct types enforced by compiler +- ✅ Automatic JSON serialization/deserialization +- ✅ Strongly typed responses +- ✅ Exhaustive error handling + +## Swift Language Features + +### 1. Conditional Compilation for Platform Support + +Generated code handles platform differences: + +```swift +#if os(Linux) +@preconcurrency import struct Foundation.URL +@preconcurrency import struct Foundation.Data +@preconcurrency import struct Foundation.Date +#else +import struct Foundation.URL +import struct Foundation.Data +import struct Foundation.Date +#endif +``` + +**Why:** + +- Linux doesn't have full Sendable conformance for Foundation types in older versions +- `@preconcurrency` suppresses concurrency warnings on Linux +- Enables cross-platform compatibility (macOS, iOS, Linux) + +### 2. Sendable Conformance for Concurrency Safety + +All generated types conform to Sendable: + +```swift +internal protocol APIProtocol: Sendable { ... } +internal struct Client: APIProtocol { ... } +internal struct Input: Sendable, Hashable { ... } +internal enum Output: Sendable, Hashable { ... } +``` + +**Benefits:** + +- ✅ Safe to pass across actor boundaries +- ✅ Safe to use in async/await contexts +- ✅ Compile-time data race prevention (Swift 6) +- ✅ No runtime concurrency overhead + +### 3. Async/Await Throughout + +All API methods use modern Swift concurrency: + +```swift +func queryRecords(_ input: Input) async throws -> Output +``` + +**Benefits:** + +- ✅ Structured concurrency support +- ✅ Automatic task cancellation propagation +- ✅ Better error handling than completion closures +- ✅ TaskGroup support for parallel operations + +### 4. Throwing Computed Properties + +Safe access to enum associated values: + +```swift +internal var json: Components.Schemas.QueryResponse { + get throws { + switch self { + case let .json(body): + return body + } + } +} +``` + +**Usage:** + +```swift +// Safe unwrapping with throws +let queryResponse = try okResponse.body.json + +// Compiler enforces error handling +``` + +## Integration with MistKit Wrapper + +### 1. MistKitClient Wraps Generated Client + +```swift +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +internal struct MistKitClient { + /// The underlying OpenAPI client + internal let client: Client // Generated Client struct + + internal init( + configuration: MistKitConfiguration, + transport: any ClientTransport + ) throws { + let tokenManager = try configuration.createTokenManager() + + self.client = Client( + serverURL: configuration.serverURL, + transport: transport, + middlewares: [ + AuthenticationMiddleware(tokenManager: tokenManager), + LoggingMiddleware() + ] + ) + } +} +``` + +**Wrapper responsibilities:** + +- ✅ Configuration management +- ✅ Token manager creation +- ✅ Middleware injection +- ✅ Server URL construction +- ✅ Higher-level convenience APIs + +### 2. AuthenticationMiddleware Integration + +The generated client's middleware support enables authentication: + +```swift +internal struct AuthenticationMiddleware: ClientMiddleware { + private let tokenManager: any TokenManager + + func intercept( + _ request: HTTPRequest, + body: HTTPBody?, + baseURL: URL, + operationID: String, + next: (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?) + ) async throws -> (HTTPResponse, HTTPBody?) { + // Add CloudKit authentication headers/query parameters + var authenticatedRequest = request + + let credentials = try await tokenManager.credentials() + // Add authentication based on credentials type + // ... + + return try await next(authenticatedRequest, body, baseURL) + } +} +``` + +**Middleware chain flow:** + +``` +Request + ↓ +AuthenticationMiddleware (adds auth) + ↓ +LoggingMiddleware (logs request) + ↓ +Transport (URLSession) + ↓ +HTTP Network + ↓ +Response +``` + +### 3. Custom Type Override: CustomFieldValue + +The configuration specifies a type override: + +```yaml +typeOverrides: + schemas: + FieldValue: CustomFieldValue +``` + +Generated code references the custom type: + +```swift +// In generated Types.swift +internal var fieldValue: CustomFieldValue? // Not Components.Schemas.FieldValue +``` + +**MistKit implementation** (`CustomFieldValue.swift`): + +```swift +internal struct CustomFieldValue: Codable, Hashable, Sendable { + // Custom implementation for CloudKit-specific field value handling + internal enum CustomFieldValuePayload { + case string(String) + case int64(Int64) + case double(Double) + case timestamp(Date) + case bytes(Data) + case reference(RecordReference) + case asset(Asset) + case location(Location) + case stringList([String]) + case int64List([Int64]) + case doubleList([Double]) + case timestampList([Date]) + case referenceList([RecordReference]) + case assetList([Asset]) + } + + internal var payload: CustomFieldValuePayload + // Custom Codable implementation... +} +``` + +This allows MistKit to provide CloudKit-specific field value semantics while using the generated code. + +## Architecture Patterns + +### 1. Namespace Organization + +``` +Client.swift +├── APIProtocol (protocol) +├── Client (struct) +├── APIProtocol extension (convenience methods) +└── Servers (enum) + +Types.swift +├── Components (namespace enum) +│ ├── Schemas (data models) +│ ├── Parameters (parameter types) +│ ├── RequestBodies (empty) +│ └── Responses (response types) +└── Operations (namespace enum) + ├── queryRecords + │ ├── id + │ ├── Input + │ └── Output + ├── modifyRecords + │ ├── id + │ ├── Input + │ └── Output + └── ... (13 more operations) +``` + +**Benefits:** + +- ✅ No naming conflicts between operations +- ✅ Clear ownership of types +- ✅ Logical grouping +- ✅ Easy navigation + +### 2. Enum-Based Response Handling + +```swift +internal enum Output: Sendable, Hashable { + case ok(Ok) + case badRequest(BadRequest) + case unauthorized(Unauthorized) + // ... more cases + case undocumented(statusCode: Int, UndocumentedPayload) +} +``` + +**Pattern benefits:** + +- ✅ Exhaustive switch coverage required by compiler +- ✅ Each status code is a distinct type +- ✅ Forces explicit error handling +- ✅ Fallback for unexpected responses (undocumented) + +**Usage:** + +```swift +switch response { +case .ok(let okResponse): + // Handle success + +case .badRequest(let error): + // Handle 400 + +case .unauthorized(let error): + // Handle 401 + +case .undocumented(let statusCode, _): + // Handle unexpected status + print("Unexpected status: \(statusCode)") +} +``` + +### 3. Protocol-Oriented Design + +```swift +// Protocol defines contract +internal protocol APIProtocol: Sendable { + func queryRecords(...) async throws -> Output +} + +// Struct implements protocol +internal struct Client: APIProtocol { + // Implementation +} + +// Middleware uses protocol +internal struct AuthenticationMiddleware: ClientMiddleware { + // Works with any APIProtocol implementation +} +``` + +**Benefits:** + +- ✅ Easy to mock for testing +- ✅ Flexible implementation swapping +- ✅ Clear separation of interface and implementation + +## Performance Considerations + +### 1. Struct Value Semantics + +All types are structs (except protocols and enums): + +```swift +internal struct Client { ... } +internal struct Input { ... } +internal struct ZoneID { ... } +``` + +**Benefits:** + +- ✅ No heap allocation for most types +- ✅ Copy-on-write semantics +- ✅ Better cache locality +- ✅ Automatic memory management + +### 2. Lazy JSON Parsing + +Response bodies use streaming: + +```swift +let body = try await converter.getResponseBodyAsJSON( + Components.Schemas.QueryResponse.self, + from: responseBody // HTTPBody (streaming) +) +``` + +**Benefits:** + +- ✅ Doesn't buffer entire response in memory +- ✅ Efficient for large responses +- ✅ Progressive parsing + +### 3. Minimal Allocations + +Generated code avoids unnecessary allocations: + +```swift +// Reuses converter instance +private var converter: Converter { + client.converter +} + +// Uses inout for mutations +converter.setAcceptHeader( + in: &request.headerFields, // inout - no copy + contentTypes: input.headers.accept +) +``` + +## Testing Considerations + +### 1. Protocol Abstraction Enables Mocking + +```swift +// Test with mock implementation +struct MockClient: APIProtocol { + func queryRecords(_ input: Input) async throws -> Output { + // Return canned response + return .ok(.init(body: .json(mockQueryResponse))) + } +} + +// Use in tests +let mockClient = MockClient() +let wrapper = MistKitClient(client: mockClient) +``` + +### 2. Transport Injection + +```swift +// Custom transport for testing +struct MockTransport: ClientTransport { + func send( + _ request: HTTPRequest, + body: HTTPBody?, + baseURL: URL, + operationID: String + ) async throws -> (HTTPResponse, HTTPBody?) { + // Return mock response + } +} + +let client = Client( + serverURL: testServerURL, + transport: MockTransport() +) +``` + +### 3. Middleware Testing + +```swift +// Test middleware in isolation +let middleware = AuthenticationMiddleware(tokenManager: mockTokenManager) + +let (response, body) = try await middleware.intercept( + request, + body: nil, + baseURL: baseURL, + operationID: "queryRecords", + next: { req, body, url in + // Verify authentication was added + XCTAssertNotNil(req.headerFields[.authorization]) + return (mockResponse, mockBody) + } +) +``` + +## See Also + +- +- [OpenAPI Runtime Documentation](https://github.com/apple/swift-openapi-runtime) +- [HTTPTypes Documentation](https://github.com/apple/swift-http-types) +- ``MistKitClient`` +- ``AuthenticationMiddleware`` +- ``CustomFieldValue`` diff --git a/Sources/MistKit/Documentation.docc/GeneratedCodeWorkflow.md b/Sources/MistKit/Documentation.docc/GeneratedCodeWorkflow.md new file mode 100644 index 00000000..bcf235d8 --- /dev/null +++ b/Sources/MistKit/Documentation.docc/GeneratedCodeWorkflow.md @@ -0,0 +1,1025 @@ +# Development Workflow for Generated Code + +A comprehensive guide to managing swift-openapi-generator code throughout the development lifecycle, including version control, updates, CI/CD integration, and code review best practices. + +## Overview + +MistKit uses a **pre-generation workflow** where generated code is committed to version control. This article covers the complete development workflow for working with generated code, from initial setup through updates, reviews, and deployment. + +## Workflow Philosophy: Pre-Generation vs. Build Plugin + +### MistKit's Approach: Pre-Generation + +``` +Developer Machine Git Repository Consumer Machine +───────────────── ────────────── ──────────────── +1. Edit openapi.yaml +2. Run generate script → 3. Commit generated code → 4. swift build + Sources/Generated/*.swift ↓ + Uses existing + generated code +``` + +**Advantages:** + +- ✅ **Fast consumer builds**: No generation during build time +- ✅ **No tool dependencies for consumers**: swift-openapi-generator not required +- ✅ **Reviewable changes**: Generated code visible in pull requests +- ✅ **Predictable builds**: Same generated code across all environments +- ✅ **Better IDE support**: Generated code always available for autocomplete +- ✅ **Easier debugging**: Can inspect and trace through generated code + +**Disadvantages:** + +- ⚠️ **Developer discipline required**: Must remember to regenerate after spec changes +- ⚠️ **Larger git diffs**: Generated code changes appear in commits +- ⚠️ **Potential for mistakes**: Forgetting to regenerate can cause drift + +### Alternative: Build Plugin (Not Used) + +``` +Developer Machine Git Repository Consumer Machine +───────────────── ────────────── ──────────────── +1. Edit openapi.yaml → 2. Commit spec only → 3. swift build + ↓ + Generates code + during build +``` + +**Why MistKit doesn't use this:** + +- ❌ Requires consumers to install swift-openapi-generator +- ❌ Slower builds for everyone +- ❌ Generated code not visible in code reviews +- ❌ Harder to debug (generated code in derived data) +- ❌ IDE autocomplete delays while generating + +## Development Workflow + +### 1. Initial Project Setup + +When starting a new MistKit-based project or contributing to MistKit: + +```bash +# 1. Clone the repository +git clone https://github.com/your-org/MistKit.git +cd MistKit + +# 2. Install Mint (if not already installed) +brew install mint # macOS +# or follow Linux installation instructions + +# 3. Bootstrap development tools +mint bootstrap -m Mintfile + +# 4. Verify generated code exists +ls -la Sources/MistKit/Generated/ +# Should see: Client.swift, Types.swift + +# 5. Build to verify everything works +swift build + +# 6. Run tests +swift test +``` + +**Expected output:** + +``` +✅ Sources/MistKit/Generated/Client.swift (exists) +✅ Sources/MistKit/Generated/Types.swift (exists) +✅ Build succeeded +✅ Tests passed +``` + +### 2. Making OpenAPI Specification Changes + +#### Step 1: Edit the OpenAPI Specification + +```bash +# Open the OpenAPI spec in your editor +vim openapi.yaml +# or +code openapi.yaml +``` + +**Common changes:** + +- Adding new endpoints +- Modifying request/response schemas +- Updating parameter definitions +- Adding/changing enum values +- Updating documentation strings + +#### Step 2: Validate the OpenAPI Spec (Optional but Recommended) + +```bash +# Install openapi-spec-validator (if not installed) +pip install openapi-spec-validator + +# Validate the spec +openapi-spec-validator openapi.yaml +``` + +**Expected output:** + +``` +✅ openapi.yaml is valid +``` + +#### Step 3: Regenerate Client Code + +```bash +# Run the generation script +./Scripts/generate-openapi.sh +``` + +**Expected output:** + +``` +🔄 Generating OpenAPI code... +✅ OpenAPI code generation complete! +``` + +**What happens:** + +1. Mint ensures swift-openapi-generator@1.10.0 is installed +2. Generator reads `openapi.yaml` and `openapi-generator-config.yaml` +3. Generates new `Client.swift` and `Types.swift` files +4. Overwrites existing files in `Sources/MistKit/Generated/` + +#### Step 4: Verify Generated Code Compiles + +```bash +# Clean build to ensure no cached artifacts +swift package clean + +# Build with fresh generated code +swift build +``` + +**If build fails:** + +1. Check for breaking changes in generated types +2. Update wrapper code (MistKitClient, etc.) to match new types +3. Fix compilation errors +4. Re-run `swift build` + +#### Step 5: Update Tests + +```bash +# Run existing tests +swift test + +# Add new tests for new functionality +# Edit Tests/MistKitTests/*.swift +``` + +#### Step 6: Review Changes + +```bash +# See what changed in generated code +git diff Sources/MistKit/Generated/ + +# See what changed in OpenAPI spec +git diff openapi.yaml +``` + +**Review checklist:** + +- [ ] Generated code compiles successfully +- [ ] Tests pass +- [ ] New types match OpenAPI schema expectations +- [ ] No unexpected changes in generated code +- [ ] Documentation comments are accurate + +### 3. Committing Changes + +#### Commit Strategy: Separate Commits for Clarity + +**Option A: Two commits (recommended for large changes)** + +```bash +# Commit 1: OpenAPI spec change +git add openapi.yaml +git commit -m "feat: add uploadAssets endpoint to OpenAPI spec" + +# Commit 2: Generated code update +git add Sources/MistKit/Generated/ +git commit -m "chore: regenerate client code for uploadAssets endpoint + +Generated with [Claude Code](https://claude.com/claude-code) + +Co-Authored-By: Claude " +``` + +**Option B: Single commit (for small changes)** + +```bash +# Commit both together +git add openapi.yaml Sources/MistKit/Generated/ +git commit -m "feat: add uploadAssets endpoint + +- Added /assets/upload endpoint to OpenAPI spec +- Regenerated client code with swift-openapi-generator + +Generated with [Claude Code](https://claude.com/claude-code) + +Co-Authored-By: Claude " +``` + +#### Commit Message Format + +``` +(): + + + +Generated with [Claude Code](https://claude.com/claude-code) + +Co-Authored-By: Claude +``` + +**Types:** +- `feat`: New feature or endpoint +- `fix`: Bug fix in OpenAPI spec +- `chore`: Regenerating code without spec changes +- `docs`: Documentation updates in OpenAPI spec +- `refactor`: Restructuring schemas without functional changes + +**Examples:** + +```bash +# New endpoint +git commit -m "feat(records): add bulk delete operation" + +# Schema change +git commit -m "fix(schemas): correct FieldValue type definition" + +# Regeneration only (e.g., after generator version update) +git commit -m "chore: regenerate code with swift-openapi-generator 1.10.0" + +# Documentation update +git commit -m "docs(openapi): improve error response descriptions" +``` + +### 4. Code Review Process + +#### What to Review + +When reviewing pull requests with generated code changes: + +**1. OpenAPI Spec Changes (Primary Focus)** + +```diff +# openapi.yaml + paths: ++ /database/{version}/{container}/{environment}/{database}/assets/upload: ++ post: ++ summary: Upload Assets ++ operationId: uploadAssets ++ ... +``` + +**Review checklist:** + +- [ ] Is the endpoint path correct? +- [ ] Are parameter types appropriate? +- [ ] Is the schema well-defined? +- [ ] Are error responses documented? +- [ ] Is the operation ID meaningful? + +**2. Generated Code Changes (Secondary Focus)** + +```diff +# Sources/MistKit/Generated/Types.swift ++ internal enum uploadAssets { ++ internal static let id: Swift.String = "uploadAssets" ++ internal struct Input: Sendable, Hashable { ... } ++ internal enum Output: Sendable, Hashable { ... } ++ } +``` + +**Review checklist:** + +- [ ] Does generated code match OpenAPI spec? +- [ ] Are types correctly generated? +- [ ] No manual edits to generated files? +- [ ] File headers intact (periphery:ignore, swift-format-ignore)? + +**3. Wrapper Code Changes (Detailed Focus)** + +```diff +# Sources/MistKit/MistKitClient.swift ++ internal func uploadAssets( ++ _ assetData: Data, ++ forRecord recordName: String ++ ) async throws -> UploadAssetsResponse { ++ let response = try await client.uploadAssets(...) ++ ... ++ } +``` + +**Review checklist:** + +- [ ] Proper error handling? +- [ ] Follows MistKit conventions? +- [ ] Well-documented? +- [ ] Tests included? + +#### Review Comments Examples + +**Good comments:** + +```markdown +In openapi.yaml, should the `assetData` field be required? + +The generated types look correct, but I notice the error handling +in MistKitClient.swift doesn't account for the new 413 response. +Could we add handling for that case? + +Nice work on the comprehensive test coverage for the new endpoint! +``` + +**Avoid these comments:** + +```markdown +❌ Why did you change line 523 of Types.swift? + (Generated code - should ask about OpenAPI spec instead) + +❌ Can you rename this type to something shorter? + (Generated types follow OpenAPI naming - change the spec) + +❌ This code could be more efficient + (Generated code optimization is out of scope - file upstream issue) +``` + +### 5. Handling Breaking Changes + +#### Identifying Breaking Changes + +Breaking changes occur when generated types change in incompatible ways: + +**Common breaking changes:** + +1. **Required fields added to request schemas** +2. **Required fields removed from response schemas** +3. **Enum cases removed or renamed** +4. **Parameter types changed** +5. **Response status codes changed** + +#### Example: Adding a Required Field + +**Before (`openapi.yaml`):** + +```yaml +RecordQuery: + type: object + properties: + recordType: + type: string + required: + - recordType +``` + +**After (breaking change):** + +```yaml +RecordQuery: + type: object + properties: + recordType: + type: string + zoneID: + $ref: '#/components/schemas/ZoneID' + required: + - recordType + - zoneID # New required field! +``` + +**Impact on generated code:** + +```swift +// Before +internal struct RecordQuery { + internal var recordType: String + internal var zoneID: ZoneID? // Optional + + internal init(recordType: String, zoneID: ZoneID? = nil) { ... } +} + +// After (breaking!) +internal struct RecordQuery { + internal var recordType: String + internal var zoneID: ZoneID // Now required! + + internal init(recordType: String, zoneID: ZoneID) { ... } + // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + // Compile error in existing code that doesn't pass zoneID +} +``` + +#### Managing Breaking Changes + +**Option 1: Major Version Bump** + +```bash +# Update version in Package.swift +# 1.2.3 → 2.0.0 + +git commit -m "feat!: add required zoneID to RecordQuery + +BREAKING CHANGE: RecordQuery now requires zoneID parameter. +Update all query calls to include zoneID. + +Migration: + .init(recordType: \"User\") +→ .init(recordType: \"User\", zoneID: .default) +" +``` + +**Option 2: Provide Default Values (if possible)** + +```yaml +# Add default in OpenAPI spec +zoneID: + $ref: '#/components/schemas/ZoneID' + default: + zoneName: "_defaultZone" +``` + +**Option 3: Migration Period with Deprecations** + +If the old field still exists: + +```swift +// Wrapper layer provides backward compatibility +@available(*, deprecated, message: "Use init(recordType:zoneID:) instead") +internal init(recordType: String) { + self.init(recordType: recordType, zoneID: .default) +} +``` + +#### Documenting Breaking Changes + +**CHANGELOG.md entry:** + +```markdown +## [2.0.0] - 2024-01-15 + +### Breaking Changes + +- **RecordQuery now requires zoneID parameter** + - **Migration**: Add zoneID to all RecordQuery initializations + - **Before**: `.init(recordType: "User")` + - **After**: `.init(recordType: "User", zoneID: .default)` + - **Reason**: CloudKit Web Services now requires explicit zone specification + +### Migration Guide + +Update all code that creates RecordQuery instances: + +\`\`\`swift +// Old code (won't compile) +let query = RecordQuery(recordType: "User") + +// New code +let query = RecordQuery( + recordType: "User", + zoneID: ZoneID(zoneName: "_defaultZone") +) +\`\`\` +``` + +### 6. Version Control Best Practices + +#### .gitignore Configuration + +```gitignore +# DO NOT ignore generated code! +# Sources/MistKit/Generated/ + +# DO ignore build artifacts +.build/ +.swiftpm/ +*.xcodeproj/ +DerivedData/ + +# DO ignore local tools +.mint/ + +# DO ignore sensitive files +.env +*.pem +``` + +**Important:** Generated code must be committed! + +#### Git Attributes for Generated Files + +Create `.gitattributes`: + +```gitattributes +# Mark generated files for better GitHub diffs +Sources/MistKit/Generated/*.swift linguist-generated=true + +# Ensure LF line endings for scripts +*.sh text eol=lf + +# Ensure YAML formatting +*.yaml text +``` + +**Benefits:** + +- GitHub collapses generated code diffs by default +- Scripts work correctly on all platforms +- Consistent YAML formatting + +### 7. CI/CD Integration + +#### GitHub Actions Workflow + +**Purpose:** Verify generated code is up-to-date + +```yaml +# .github/workflows/verify-generated-code.yml +name: Verify Generated Code + +on: + pull_request: + paths: + - 'openapi.yaml' + - 'openapi-generator-config.yaml' + - 'Sources/MistKit/Generated/**' + +jobs: + verify-generated: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: swift-actions/setup-swift@v2 + with: + swift-version: '6.2' + + - name: Install Mint + run: | + git clone https://github.com/yonaskolb/Mint.git + cd Mint + swift run mint bootstrap + + - name: Regenerate OpenAPI code + run: ./Scripts/generate-openapi.sh + + - name: Check for differences + run: | + if ! git diff --exit-code Sources/MistKit/Generated/; then + echo "❌ Generated code is out of date!" + echo "Run: ./Scripts/generate-openapi.sh" + exit 1 + fi + echo "✅ Generated code is up to date" + + - name: Verify build + run: swift build +``` + +**What this does:** + +1. Triggers on changes to OpenAPI spec or generated code +2. Regenerates code from scratch +3. Compares regenerated code to committed code +4. Fails if they don't match +5. Verifies build succeeds + +#### Alternative: Auto-Commit Generated Code + +```yaml +# .github/workflows/auto-regenerate.yml +name: Auto-Regenerate Generated Code + +on: + pull_request: + paths: + - 'openapi.yaml' + - 'openapi-generator-config.yaml' + +jobs: + regenerate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.head_ref }} + + - uses: swift-actions/setup-swift@v2 + with: + swift-version: '6.2' + + - name: Install Mint + run: | + git clone https://github.com/yonaskolb/Mint.git + cd Mint + swift run mint bootstrap + + - name: Regenerate OpenAPI code + run: ./Scripts/generate-openapi.sh + + - name: Commit changes + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + if ! git diff --exit-code Sources/MistKit/Generated/; then + git add Sources/MistKit/Generated/ + git commit -m "chore: regenerate OpenAPI client code [skip ci]" + git push + fi +``` + +**Benefits:** + +- Developers don't need to manually regenerate +- Always up-to-date generated code + +**Drawbacks:** + +- Less visibility into what changed +- Potential for surprise commits + +### 8. Updating swift-openapi-generator Version + +#### When to Update + +- 🆕 New swift-openapi-generator release with desired features +- 🐛 Bug fixes in code generation +- 🔒 Security updates + +#### Update Process + +**Step 1: Update Mintfile** + +```diff +# Mintfile + swiftlang/swift-format@601.0.0 + realm/SwiftLint@0.59.1 + peripheryapp/periphery@3.2.0 +- apple/swift-openapi-generator@1.10.0 ++ apple/swift-openapi-generator@1.11.0 +``` + +**Step 2: Clear Mint Cache** + +```bash +# Remove old version +rm -rf .mint/ +``` + +**Step 3: Bootstrap New Version** + +```bash +mint bootstrap -m Mintfile +``` + +**Step 4: Regenerate Code** + +```bash +./Scripts/generate-openapi.sh +``` + +**Step 5: Review Differences** + +```bash +git diff Sources/MistKit/Generated/ +``` + +**Possible outcomes:** + +- ✅ **No changes**: Generator improvements don't affect output +- ⚠️ **Formatting changes**: Code reformatted but semantically identical +- ⚠️ **New features**: Additional generated code (new helper methods, etc.) +- 🚨 **Breaking changes**: Generated code structure changed + +**Step 6: Test Thoroughly** + +```bash +# Clean build +swift package clean +swift build + +# Run all tests +swift test + +# Integration tests +swift test --filter IntegrationTests +``` + +**Step 7: Commit** + +```bash +git add Mintfile .mint/ Sources/MistKit/Generated/ +git commit -m "chore: update swift-openapi-generator to 1.11.0 + +- Updated Mintfile dependency +- Regenerated client code with new generator version +- Verified all tests pass + +Generator changelog: https://github.com/apple/swift-openapi-generator/releases/tag/1.11.0 +" +``` + +### 9. Troubleshooting Common Issues + +#### Issue: Generated Code Out of Sync + +**Symptoms:** + +- Build errors referencing missing types +- Test failures with type mismatches +- IDE autocomplete shows wrong types + +**Solution:** + +```bash +# 1. Clean everything +swift package clean +rm -rf .build/ + +# 2. Regenerate from scratch +./Scripts/generate-openapi.sh + +# 3. Rebuild +swift build +``` + +#### Issue: Merge Conflicts in Generated Code + +**Symptoms:** + +``` +<<<<<<< HEAD +internal struct User { ... } +======= +internal struct User { ... } +>>>>>>> feature-branch +``` + +**Solution:** + +```bash +# 1. Accept either version (doesn't matter which) +git checkout --theirs Sources/MistKit/Generated/ + +# 2. Merge the OpenAPI specs carefully +git merge-tool openapi.yaml + +# 3. Regenerate from merged spec +./Scripts/generate-openapi.sh + +# 4. Stage the correctly generated code +git add Sources/MistKit/Generated/ +``` + +**Never manually resolve conflicts in generated files!** + +#### Issue: CI Fails with "Generated Code Out of Date" + +**Symptoms:** + +``` +❌ Generated code is out of date! +Run: ./Scripts/generate-openapi.sh +``` + +**Solution:** + +```bash +# Regenerate locally +./Scripts/generate-openapi.sh + +# Verify differences +git status + +# Commit updated generated code +git add Sources/MistKit/Generated/ +git commit -m "chore: update generated code to match OpenAPI spec" +git push +``` + +#### Issue: Generator Version Mismatch + +**Symptoms:** + +``` +Error: swift-openapi-generator version mismatch +Expected: 1.10.0 +Found: 1.9.0 +``` + +**Solution:** + +```bash +# Clear Mint cache +rm -rf .mint/ + +# Reinstall correct version +mint bootstrap -m Mintfile + +# Verify version +mint run swift-openapi-generator --version +``` + +## Best Practices Summary + +### DO ✅ + +- ✅ **Commit generated code** to version control +- ✅ **Regenerate after every OpenAPI spec change** +- ✅ **Review OpenAPI spec changes carefully** in pull requests +- ✅ **Run tests after regeneration** to catch breaking changes +- ✅ **Document breaking changes** in CHANGELOG +- ✅ **Use CI/CD to verify** generated code is up-to-date +- ✅ **Keep generator version** in sync across team (via Mintfile) +- ✅ **Clean build after regeneration** to avoid cached issues + +### DON'T ❌ + +- ❌ **Never manually edit generated files** (changes will be overwritten) +- ❌ **Don't ignore generated code** in .gitignore +- ❌ **Don't merge conflicts** in generated files manually +- ❌ **Don't forget to regenerate** after OpenAPI changes +- ❌ **Don't commit only spec without generated code** +- ❌ **Don't skip testing** after regeneration +- ❌ **Don't use different generator versions** on different machines + +## Real-World Example: Adding a New Endpoint + +Let's walk through a complete example of adding the `uploadAssets` endpoint: + +### 1. Update OpenAPI Spec + +```yaml +# openapi.yaml +paths: + /database/{version}/{container}/{environment}/{database}/assets/upload: + post: + summary: Upload Assets + description: Upload binary assets to CloudKit + operationId: uploadAssets + parameters: + - $ref: '#/components/parameters/version' + - $ref: '#/components/parameters/container' + - $ref: '#/components/parameters/environment' + - $ref: '#/components/parameters/database' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AssetUploadRequest' + responses: + '200': + description: Upload successful + content: + application/json: + schema: + $ref: '#/components/schemas/AssetUploadResponse' +``` + +### 2. Regenerate + +```bash +./Scripts/generate-openapi.sh +``` + +### 3. Verify Generated Code + +```swift +// Sources/MistKit/Generated/Types.swift (auto-generated) +internal enum Operations { + // ... existing operations + + internal enum uploadAssets { + internal static let id: Swift.String = "uploadAssets" + + internal struct Input: Sendable, Hashable { + internal struct Path: Sendable, Hashable { + internal var version: String + internal var container: String + internal var environment: environment + internal var database: database + } + internal var path: Path + internal var body: Body + } + + internal enum Output: Sendable, Hashable { + case ok(Ok) + // ... error cases + } + } +} +``` + +### 4. Add Wrapper Method + +```swift +// Sources/MistKit/MistKitClient.swift +extension MistKitClient { + /// Upload an asset to CloudKit + /// + /// - Parameters: + /// - data: Asset data to upload + /// - recordName: Associated record name + /// - Returns: Upload response with asset URL + /// - Throws: CloudKitError if upload fails + internal func uploadAsset( + _ data: Data, + forRecord recordName: String + ) async throws -> AssetUploadResponse { + let request = AssetUploadRequest( + assetData: data, + recordName: recordName + ) + + let response = try await client.uploadAssets( + path: .init( + version: "1", + container: configuration.container, + environment: configuration.environment, + database: configuration.database + ), + body: .json(request) + ) + + switch response { + case .ok(let okResponse): + return try okResponse.body.json + + case .badRequest(let error): + throw try CloudKitError(from: error.body.json) + + // ... handle other error cases + } + } +} +``` + +### 5. Add Tests + +```swift +// Tests/MistKitTests/AssetUploadTests.swift +import Testing +@testable import MistKit + +struct AssetUploadTests { + @Test func uploadAssetSuccess() async throws { + let mockTransport = MockTransport( + returning: .ok(AssetUploadResponse(assetURL: "https://...")) + ) + + let client = try MistKitClient( + configuration: testConfiguration, + transport: mockTransport + ) + + let assetData = Data("test asset".utf8) + let response = try await client.uploadAsset( + assetData, + forRecord: "testRecord" + ) + + #expect(response.assetURL != nil) + } +} +``` + +### 6. Commit + +```bash +git add openapi.yaml Sources/MistKit/Generated/ \ + Sources/MistKit/MistKitClient.swift \ + Tests/MistKitTests/AssetUploadTests.swift + +git commit -m "feat(assets): add uploadAssets endpoint + +- Added /assets/upload endpoint to OpenAPI spec +- Regenerated client code +- Added MistKitClient.uploadAsset() wrapper method +- Added comprehensive tests + +Closes #123 + +Generated with [Claude Code](https://claude.com/claude-code) + +Co-Authored-By: Claude " +``` + +## See Also + +- +- +- [Git Best Practices](https://git-scm.com/book/en/v2) +- [Semantic Versioning](https://semver.org/) +- [swift-openapi-generator Releases](https://github.com/apple/swift-openapi-generator/releases) diff --git a/Sources/MistKit/Documentation.docc/OpenAPICodeGeneration.md b/Sources/MistKit/Documentation.docc/OpenAPICodeGeneration.md new file mode 100644 index 00000000..1ff4115e --- /dev/null +++ b/Sources/MistKit/Documentation.docc/OpenAPICodeGeneration.md @@ -0,0 +1,543 @@ +# OpenAPI Code Generation Setup + +A comprehensive guide to the swift-openapi-generator integration and code generation workflow in MistKit. + +## Overview + +MistKit uses [swift-openapi-generator](https://github.com/apple/swift-openapi-generator) to automatically generate type-safe Swift client code from the CloudKit Web Services OpenAPI specification. This approach ensures that the API client stays in sync with the OpenAPI schema while providing compile-time safety and excellent tooling support. + +### Why Code Generation? + +- **Type Safety**: Compile-time verification of API requests and responses +- **Maintainability**: Single source of truth (OpenAPI spec) for API definition +- **Documentation**: API structure documented directly in the OpenAPI spec +- **Consistency**: Automated generation eliminates manual coding errors +- **Updates**: Easy updates when CloudKit API changes + +## Architecture Overview + +``` +openapi.yaml (OpenAPI Spec) + ↓ +swift-openapi-generator + ↓ +Generated Swift Code (10,476 lines) + ├─ Client.swift (3,268 lines) + │ ├─ APIProtocol (interface) + │ ├─ Client (implementation) + │ └─ Operations namespaces + └─ Types.swift (7,208 lines) + ├─ Components.Schemas + ├─ Request/Response types + └─ Servers enum + ↓ +MistKit Wrapper Layer + ├─ MistKitClient.swift + ├─ AuthenticationMiddleware.swift + └─ CustomFieldValue.swift +``` + +## Installation and Setup + +### Prerequisites + +- **Swift 6.1+** (MistKit uses Swift 6.2 with experimental features) +- **Mint** package manager for managing command-line tools +- **macOS 10.15+** or **Linux** (Ubuntu 18.04+) + +### Tool Versions + +MistKit uses the following versions (defined in `Mintfile`): + +``` +swift-openapi-generator@1.10.0 +swift-format@601.0.0 +SwiftLint@0.59.1 +periphery@3.2.0 +``` + +### Installing Mint + +**On macOS (via Homebrew):** +```bash +brew install mint +``` + +**On Linux:** +```bash +git clone https://github.com/yonaskolb/Mint.git +cd Mint +swift run mint bootstrap +``` + +### Installing swift-openapi-generator + +The project uses Mint to manage swift-openapi-generator, so no manual installation is needed. The `Scripts/generate-openapi.sh` script automatically bootstraps all required tools: + +```bash +./Scripts/generate-openapi.sh +``` + +This will: +1. Install Mint (if not present) +2. Bootstrap tools from `Mintfile` to `.mint` directory +3. Run swift-openapi-generator with the correct configuration +4. Generate Swift code to `Sources/MistKit/Generated/` + +## Configuration Files + +### openapi-generator-config.yaml + +The configuration file controls how swift-openapi-generator produces Swift code: + +```yaml +generate: + - types # Generate data types (schemas, enums, structs) + - client # Generate API client code + +accessModifier: internal # All generated code uses 'internal' access + +typeOverrides: + schemas: + FieldValue: CustomFieldValue # Override FieldValue with custom type + +additionalFileComments: + - periphery:ignore:all # Ignore in dead code analysis + - swift-format-ignore-file # Skip auto-formatting +``` + +#### Configuration Options Explained + +**`generate`**: Controls what code is generated +- `types`: Generates all schema types, request/response models +- `client`: Generates the API client protocol and implementation +- Other options: `server` (not used in MistKit as we're building a client) + +**`accessModifier`**: Sets visibility for generated code +- `internal`: Code is accessible within the MistKit module but not to consumers (default for libraries) +- `public`: Would expose generated code to library users (not recommended) +- `package`: Swift 6+ package-level access + +**`typeOverrides`**: Custom type mappings +- Used to replace generated types with custom implementations +- MistKit overrides `FieldValue` to provide custom CloudKit field value handling +- Allows integration with hand-written wrapper types + +**`additionalFileComments`**: File-level pragmas +- `periphery:ignore:all`: Prevents false positives in dead code detection (generated code may have unused methods) +- `swift-format-ignore-file`: Preserves generated code formatting exactly as produced + +### Package.swift Integration + +MistKit uses swift-openapi-runtime dependencies but **does not use the build plugin**: + +```swift +dependencies: [ + .package(url: "https://github.com/apple/swift-openapi-runtime", from: "1.8.0"), + .package(url: "https://github.com/apple/swift-openapi-urlsession", from: "1.1.0"), +] +``` + +**Why no build plugin?** + +The build plugin approach can cause friction for library consumers because: +1. It requires consumers to have swift-openapi-generator installed +2. Build times increase for every consumer +3. Generated code appears in build artifacts +4. Harder to debug and inspect generated code + +Instead, MistKit uses a **pre-generation approach**: +- Code is generated during development +- Generated files are committed to version control +- Consumers get pre-generated code without needing the generator +- Faster builds and better IDE support + +### Swift Settings + +MistKit leverages Swift 6.2's cutting-edge features (defined in `Package.swift`): + +```swift +let swiftSettings: [SwiftSetting] = [ + // Upcoming Features + .enableUpcomingFeature("ExistentialAny"), + .enableUpcomingFeature("InternalImportsByDefault"), + .enableUpcomingFeature("FullTypedThrows"), + + // Experimental Features + .enableExperimentalFeature("IsolatedAny"), + .enableExperimentalFeature("SendingArgsAndResults"), + + // Strict Concurrency + .unsafeFlags(["-strict-concurrency=complete"]) +] +``` + +These settings ensure: +- Complete Swift 6 concurrency safety +- Future-proof code with upcoming Swift features +- Type-safe async/await throughout + +## Generation Script: Scripts/generate-openapi.sh + +The shell script orchestrates the code generation process: + +```bash +#!/bin/bash +set -e + +echo "🔄 Generating OpenAPI code..." + +# Detect OS and configure Mint paths +if [ "$(uname)" = "Darwin" ]; then + DEFAULT_MINT_PATH="/opt/homebrew/bin/mint" +elif [ "$(uname)" = "Linux" ]; then + DEFAULT_MINT_PATH="/usr/local/bin/mint" +fi + +MINT_CMD=${MINT_CMD:-$DEFAULT_MINT_PATH} +export MINT_PATH="$PACKAGE_DIR/.mint" + +# Bootstrap tools from Mintfile +$MINT_CMD bootstrap -m Mintfile + +# Run generator +$MINT_CMD run swift-openapi-generator generate \ + --output-directory Sources/MistKit/Generated \ + --config openapi-generator-config.yaml \ + openapi.yaml + +echo "✅ OpenAPI code generation complete!" +``` + +### Script Features + +- **Cross-platform**: Supports both macOS and Linux +- **Environment variable support**: Can override Mint path via `MINT_CMD` +- **Local tool installation**: Installs to `.mint` directory to avoid global dependencies +- **Error handling**: Exits immediately on failure (`set -e`) +- **Clear feedback**: Progress messages for user awareness + +### Running the Script + +```bash +# From project root +./Scripts/generate-openapi.sh + +# With custom Mint location +MINT_CMD=/custom/path/mint ./Scripts/generate-openapi.sh + +# Make executable if needed +chmod +x Scripts/generate-openapi.sh +``` + +## Generated Code Structure + +### File Organization + +``` +Sources/MistKit/Generated/ +├── Client.swift (3,268 lines) +└── Types.swift (7,208 lines) +``` + +Both files include header comments: +```swift +// Generated by swift-openapi-generator, do not modify. +// periphery:ignore:all +// swift-format-ignore-file +``` + +### Client.swift Contents + +**1. APIProtocol** - Protocol defining all API operations: + +```swift +internal protocol APIProtocol: Sendable { + func queryRecords(_ input: Operations.queryRecords.Input) async throws + -> Operations.queryRecords.Output + func modifyRecords(_ input: Operations.modifyRecords.Input) async throws + -> Operations.modifyRecords.Output + // ... 13 more operations +} +``` + +**2. Client Struct** - Implementation of APIProtocol: + +```swift +internal struct Client: APIProtocol { + private let client: UniversalClient + + internal init( + serverURL: Foundation.URL, + configuration: Configuration = .init(), + transport: any ClientTransport, + middlewares: [any ClientMiddleware] = [] + ) +} +``` + +**3. Convenience Extensions** - Overloads for easier method calls: + +```swift +extension APIProtocol { + internal func queryRecords( + path: Operations.queryRecords.Input.Path, + headers: Operations.queryRecords.Input.Headers = .init(), + body: Operations.queryRecords.Input.Body + ) async throws -> Operations.queryRecords.Output +} +``` + +**4. Servers Enum** - Server URL definitions: + +```swift +internal enum Servers { + internal enum Server1 { + internal static func url() throws -> Foundation.URL { + try Foundation.URL( + validatingOpenAPIServerURL: "https://api.apple-cloudkit.com", + variables: [] + ) + } + } +} +``` + +### Types.swift Contents + +**1. Components.Schemas** - Data models from OpenAPI schemas: + +```swift +internal enum Components { + internal enum Schemas { + internal struct ZoneID: Codable, Hashable, Sendable { + internal var zoneName: Swift.String? + internal var ownerName: Swift.String? + } + + internal struct Filter: Codable, Hashable, Sendable { + internal enum comparatorPayload: String, Codable, Sendable { + case EQUALS = "EQUALS" + case NOT_EQUALS = "NOT_EQUALS" + // ... 14 more cases + } + internal var comparator: comparatorPayload? + internal var fieldName: Swift.String? + internal var fieldValue: CustomFieldValue? + } + } +} +``` + +**2. Operations Namespace** - Request/response types for each operation: + +```swift +internal enum Operations { + internal enum queryRecords { + internal static let id: Swift.String = "queryRecords" + + internal struct Input: Sendable { + internal struct Path: Sendable { + internal var version: Swift.String + internal var container: Swift.String + internal var environment: Swift.String + internal var database: Swift.String + } + internal var path: Operations.queryRecords.Input.Path + internal var headers: Operations.queryRecords.Input.Headers + internal var body: Operations.queryRecords.Input.Body + } + + internal enum Output: Sendable { + internal struct Ok: Sendable { + internal var body: Body + } + case ok(Ok) + case badRequest(BadRequest) + // ... more response cases + } + } +} +``` + +### Key Features of Generated Code + +1. **All types are Sendable**: Full Swift 6 concurrency compliance +2. **Async/await throughout**: Modern Swift concurrency patterns +3. **Type-safe enums for responses**: Each HTTP status code is a distinct case +4. **Nested namespacing**: Clean organization preventing naming conflicts +5. **Codable conformance**: Automatic JSON encoding/decoding +6. **Documentation comments**: Remark annotations with OpenAPI paths + +## Integration with MistKit Wrapper Layer + +MistKit wraps the generated client to provide: + +### Custom Type Mappings + +**CustomFieldValue** (overrides generated `FieldValue`): + +```swift +// Custom implementation for CloudKit field values +internal struct CustomFieldValue: Codable, Hashable, Sendable { + // Custom logic for CloudKit-specific field types +} +``` + +Located in: `Sources/MistKit/CustomFieldValue.swift` + +### Authentication Middleware + +**AuthenticationMiddleware**: +- Adds CloudKit authentication headers/query parameters +- Supports API Token, Web Auth, and Server-to-Server auth +- Implemented as OpenAPIRuntime middleware + +Located in: `Sources/MistKit/AuthenticationMiddleware.swift` + +### MistKitClient Wrapper + +**MistKitClient**: +- High-level API wrapping generated `Client` +- Environment and database configuration +- Middleware injection (auth, logging, etc.) +- Convenience methods for common operations + +Located in: `Sources/MistKit/MistKitClient.swift` + +## Swift Language Features + +### Conditional Compilation for Linux + +Generated code handles platform differences: + +```swift +#if os(Linux) +@preconcurrency import struct Foundation.URL +@preconcurrency import struct Foundation.Data +#else +import struct Foundation.URL +import struct Foundation.Data +#endif +``` + +### SPI (System Programming Interface) Imports + +```swift +@_spi(Generated) import OpenAPIRuntime +``` + +This imports internal OpenAPIRuntime APIs needed for generation but not exposed in the public API. + +### Type Safety Benefits + +**Before (manual HTTP client):** +```swift +// Easy to make mistakes - typos, wrong types, missing fields +let json = [ + "recordType": "User", + "fields": ["name": ["value": name]] // Nested dictionaries, no type checking +] +let data = try JSONSerialization.data(withJSONObject: json) +``` + +**After (generated client):** +```swift +// Compile-time safety - impossible to send invalid requests +let response = try await client.queryRecords( + path: .init( + version: "1", + container: containerID, + environment: "production", + database: "public" + ), + body: .json(.init( + query: .init(recordType: "User") + )) +) +``` + +## Troubleshooting + +### Common Issues + +**Problem: "swift-openapi-generator not found"** + +Solution: +```bash +# Bootstrap Mint tools +mint bootstrap -m Mintfile + +# Or install directly +mint install apple/swift-openapi-generator@1.10.0 +``` + +**Problem: "Generated code doesn't compile"** + +Solution: +1. Ensure Swift 6.1+ is installed: `swift --version` +2. Check Package.swift dependencies are resolved: `swift package resolve` +3. Regenerate code: `./Scripts/generate-openapi.sh` +4. Clean build folder: `swift package clean` + +**Problem: "Type 'FieldValue' not found"** + +This is expected! The type override in configuration replaces `FieldValue` with `CustomFieldValue`. Check that: +- `CustomFieldValue.swift` exists and is properly implemented +- The override is specified in `openapi-generator-config.yaml` + +**Problem: "Build plugin errors"** + +MistKit doesn't use the build plugin. If you see plugin-related errors: +- Ensure you're not adding the plugin to Package.swift +- Generated code should be pre-committed to the repository +- Run generation script manually when updating OpenAPI spec + +## Best Practices + +### When to Regenerate Code + +Regenerate generated code when: +- ✅ OpenAPI specification (`openapi.yaml`) changes +- ✅ Configuration (`openapi-generator-config.yaml`) changes +- ✅ Updating swift-openapi-generator version in Mintfile +- ❌ **NOT** on every build (use pre-generated approach) + +### Version Control + +**Always commit generated code:** +```bash +git add Sources/MistKit/Generated/ +git commit -m "Update generated OpenAPI client code" +``` + +This ensures: +- Reviewable changes in pull requests +- No generation required for library consumers +- Faster CI/CD pipelines +- Consistent builds across environments + +### Code Review Guidelines + +When reviewing generated code changes: +1. Verify the OpenAPI spec change is intentional +2. Check that type safety is maintained +3. Ensure backward compatibility (or document breaking changes) +4. Review custom overrides still align with generated types + +### Testing Generated Code + +While generated code itself isn't tested (it's auto-generated), verify: +- Integration tests with MistKit wrapper layer +- Authentication middleware works with generated client +- Custom type overrides (CustomFieldValue) serialize correctly + +## See Also + +- [Swift OpenAPI Generator Documentation](https://swiftpackageindex.com/apple/swift-openapi-generator/1.10.3/documentation/swift-openapi-generator) +- [swift-openapi-generator Repository](https://github.com/apple/swift-openapi-generator) +- [OpenAPI Specification 3.0.3](https://spec.openapis.org/oas/v3.0.3) +- [CloudKit Web Services API](https://developer.apple.com/documentation/cloudkitwebservices) +- ``MistKitClient`` +- ``AuthenticationMiddleware`` +- ``CustomFieldValue`` diff --git a/Sources/MistKit/Environment.swift b/Sources/MistKit/Environment.swift index 3c99a404..a462181e 100644 --- a/Sources/MistKit/Environment.swift +++ b/Sources/MistKit/Environment.swift @@ -34,16 +34,3 @@ public enum Environment: String, Sendable { case development case production } - -/// Extension to convert Environment enum to Components type -extension Environment { - /// Convert to the generated Components.Parameters.environment type - internal func toComponentsEnvironment() -> Components.Parameters.environment { - switch self { - case .development: - return .development - case .production: - return .production - } - } -} diff --git a/Sources/MistKit/Extensions/FieldValue+Convenience.swift b/Sources/MistKit/Extensions/FieldValue+Convenience.swift new file mode 100644 index 00000000..0adabb5f --- /dev/null +++ b/Sources/MistKit/Extensions/FieldValue+Convenience.swift @@ -0,0 +1,154 @@ +// +// FieldValue+Convenience.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +public import Foundation + +/// Convenience extensions for extracting typed values from FieldValue cases +extension FieldValue { + /// Extract a String value if this is a .string case + /// + /// - Returns: The string value, or nil if this is not a .string case + public var stringValue: String? { + if case .string(let value) = self { + return value + } + return nil + } + + /// Extract an Int value if this is an .int64 case + /// + /// - Returns: The integer value, or nil if this is not an .int64 case + public var intValue: Int? { + if case .int64(let value) = self { + return value + } + return nil + } + + /// Extract a Double value if this is a .double case + /// + /// - Returns: The double value, or nil if this is not a .double case + public var doubleValue: Double? { + if case .double(let value) = self { + return value + } + return nil + } + + /// Internal method to extract Bool value with custom assertion handler + /// + /// - Parameter assertionHandler: Custom assertion handler for testing, defaults to system assert + /// - Returns: The boolean value, or nil if this is not an .int64 case + internal func boolValue( + assertionHandler: (_ condition: Bool, _ message: String) -> Void = { condition, message in + assert(condition, message) + } + ) -> Bool? { + if case .int64(let value) = self { + assertionHandler( + value == 0 || value == 1, + "Boolean int64 value must be 0 or 1, got \(value)" + ) + return value != 0 + } + return nil + } + + /// Extract a Bool value from .int64 cases + /// + /// CloudKit represents booleans as INT64 where 0 is false and 1 is true. + /// This method asserts that the value is either 0 or 1. + /// + /// - Returns: The boolean value, or nil if this is not an .int64 case + public var boolValue: Bool? { + boolValue(assertionHandler: { condition, message in + assert(condition, message) + }) + } + + /// Extract a Date value if this is a .date case + /// + /// - Returns: The date value, or nil if this is not a .date case + public var dateValue: Date? { + if case .date(let value) = self { + return value + } + return nil + } + + /// Extract base64-encoded bytes if this is a .bytes case + /// + /// - Returns: The base64 string, or nil if this is not a .bytes case + public var bytesValue: String? { + if case .bytes(let value) = self { + return value + } + return nil + } + + /// Extract a Location value if this is a .location case + /// + /// - Returns: The location value, or nil if this is not a .location case + public var locationValue: Location? { + if case .location(let value) = self { + return value + } + return nil + } + + /// Extract a Reference value if this is a .reference case + /// + /// - Returns: The reference value, or nil if this is not a .reference case + public var referenceValue: Reference? { + if case .reference(let value) = self { + return value + } + return nil + } + + /// Extract an Asset value if this is an .asset case + /// + /// - Returns: The asset value, or nil if this is not an .asset case + public var assetValue: Asset? { + if case .asset(let value) = self { + return value + } + return nil + } + + /// Extract a list of FieldValues if this is a .list case + /// + /// - Returns: The array of field values, or nil if this is not a .list case + public var listValue: [FieldValue]? { + if case .list(let value) = self { + return value + } + return nil + } +} diff --git a/Sources/MistKit/Extensions/OpenAPI/Components+Database.swift b/Sources/MistKit/Extensions/OpenAPI/Components+Database.swift new file mode 100644 index 00000000..0b3a6e23 --- /dev/null +++ b/Sources/MistKit/Extensions/OpenAPI/Components+Database.swift @@ -0,0 +1,46 @@ +// +// Components+Database.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +internal import Foundation + +/// Extension to convert MistKit Database to OpenAPI Components.Parameters.database +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +extension Components.Parameters.database { + /// Initialize from MistKit Database + internal init(from database: Database) { + switch database { + case .public: + self = ._public + case .private: + self = ._private + case .shared: + self = .shared + } + } +} diff --git a/Sources/MistKit/Extensions/OpenAPI/Components+Environment.swift b/Sources/MistKit/Extensions/OpenAPI/Components+Environment.swift new file mode 100644 index 00000000..9d3a18db --- /dev/null +++ b/Sources/MistKit/Extensions/OpenAPI/Components+Environment.swift @@ -0,0 +1,44 @@ +// +// Components+Environment.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +internal import Foundation + +/// Extension to convert MistKit Environment to OpenAPI Components.Parameters.environment +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +extension Components.Parameters.environment { + /// Initialize from MistKit Environment + internal init(from environment: Environment) { + switch environment { + case .development: + self = .development + case .production: + self = .production + } + } +} diff --git a/Sources/MistKit/Extensions/OpenAPI/Components+FieldValue.swift b/Sources/MistKit/Extensions/OpenAPI/Components+FieldValue.swift new file mode 100644 index 00000000..3cbb39e6 --- /dev/null +++ b/Sources/MistKit/Extensions/OpenAPI/Components+FieldValue.swift @@ -0,0 +1,111 @@ +// +// Components+FieldValue.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +internal import Foundation + +/// Extension to convert MistKit FieldValue to OpenAPI Components.Schemas.FieldValue +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +extension Components.Schemas.FieldValue { + /// Initialize from MistKit FieldValue + internal init(from fieldValue: FieldValue) { + switch fieldValue { + case .string(let value): + self.init(value: .stringValue(value), type: .string) + case .int64(let value): + self.init(value: .int64Value(value), type: .int64) + case .double(let value): + self.init(value: .doubleValue(value), type: .double) + case .bytes(let value): + self.init(value: .bytesValue(value), type: .bytes) + case .date(let value): + let milliseconds = Int64(value.timeIntervalSince1970 * 1_000) + self.init(value: .dateValue(Double(milliseconds)), type: .timestamp) + case .location(let location): + self.init(location: location) + case .reference(let reference): + self.init(reference: reference) + case .asset(let asset): + self.init(asset: asset) + case .list(let list): + self.init(list: list) + } + } + + /// Initialize from Location to Components LocationValue + private init(location: FieldValue.Location) { + let locationValue = Components.Schemas.LocationValue( + latitude: location.latitude, + longitude: location.longitude, + horizontalAccuracy: location.horizontalAccuracy, + verticalAccuracy: location.verticalAccuracy, + altitude: location.altitude, + speed: location.speed, + course: location.course, + timestamp: location.timestamp.map { $0.timeIntervalSince1970 * 1_000 } + ) + self.init(value: .locationValue(locationValue), type: .location) + } + + /// Initialize from Reference to Components ReferenceValue + private init(reference: FieldValue.Reference) { + let action: Components.Schemas.ReferenceValue.actionPayload? + switch reference.action { + case .some(.deleteSelf): + action = .DELETE_SELF + case .some(.none): + action = .NONE + case nil: + action = nil + } + let referenceValue = Components.Schemas.ReferenceValue( + recordName: reference.recordName, + action: action + ) + self.init(value: .referenceValue(referenceValue), type: .reference) + } + + /// Initialize from Asset to Components AssetValue + private init(asset: FieldValue.Asset) { + let assetValue = Components.Schemas.AssetValue( + fileChecksum: asset.fileChecksum, + size: asset.size, + referenceChecksum: asset.referenceChecksum, + wrappingKey: asset.wrappingKey, + receipt: asset.receipt, + downloadURL: asset.downloadURL + ) + self.init(value: .assetValue(assetValue), type: .asset) + } + + /// Initialize from List to Components list value + private init(list: [FieldValue]) { + let listValues = list.map { CustomFieldValue.CustomFieldValuePayload($0) } + self.init(value: .listValue(listValues), type: .list) + } +} diff --git a/Sources/MistKit/Extensions/OpenAPI/Components+Filter.swift b/Sources/MistKit/Extensions/OpenAPI/Components+Filter.swift new file mode 100644 index 00000000..de384dc2 --- /dev/null +++ b/Sources/MistKit/Extensions/OpenAPI/Components+Filter.swift @@ -0,0 +1,39 @@ +// +// Components+Filter.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +internal import Foundation + +/// Extension to convert MistKit QueryFilter to OpenAPI Components.Schemas.Filter +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +extension Components.Schemas.Filter { + /// Initialize from MistKit QueryFilter + internal init(from queryFilter: QueryFilter) { + self = queryFilter.filter + } +} diff --git a/Sources/MistKit/Extensions/OpenAPI/Components+RecordOperation.swift b/Sources/MistKit/Extensions/OpenAPI/Components+RecordOperation.swift new file mode 100644 index 00000000..4714597d --- /dev/null +++ b/Sources/MistKit/Extensions/OpenAPI/Components+RecordOperation.swift @@ -0,0 +1,71 @@ +// +// Components+RecordOperation.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +internal import Foundation + +/// Extension to convert MistKit RecordOperation to OpenAPI Components.Schemas.RecordOperation +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +extension Components.Schemas.RecordOperation { + /// Mapping from RecordOperation.OperationType to OpenAPI operationTypePayload + private static let operationTypeMapping: + [RecordOperation.OperationType: Components.Schemas.RecordOperation.operationTypePayload] = [ + .create: .create, + .update: .update, + .forceUpdate: .forceUpdate, + .replace: .replace, + .forceReplace: .forceReplace, + .delete: .delete, + .forceDelete: .forceDelete, + ] + + /// Initialize from MistKit RecordOperation + internal init(from recordOperation: RecordOperation) { + // Convert operation type using dictionary lookup + guard let apiOperationType = Self.operationTypeMapping[recordOperation.operationType] else { + fatalError("Unknown operation type: \(recordOperation.operationType)") + } + + // Convert fields to OpenAPI FieldValue format + let apiFields = recordOperation.fields.mapValues { + fieldValue -> Components.Schemas.FieldValue in + Components.Schemas.FieldValue(from: fieldValue) + } + + // Build the OpenAPI record operation + self.init( + operationType: apiOperationType, + record: .init( + recordName: recordOperation.recordName, + recordType: recordOperation.recordType, + recordChangeTag: recordOperation.recordChangeTag, + fields: .init(additionalProperties: apiFields) + ) + ) + } +} diff --git a/Sources/MistKit/Extensions/OpenAPI/Components+Sort.swift b/Sources/MistKit/Extensions/OpenAPI/Components+Sort.swift new file mode 100644 index 00000000..9278f081 --- /dev/null +++ b/Sources/MistKit/Extensions/OpenAPI/Components+Sort.swift @@ -0,0 +1,39 @@ +// +// Components+Sort.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +internal import Foundation + +/// Extension to convert MistKit QuerySort to OpenAPI Components.Schemas.Sort +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +extension Components.Schemas.Sort { + /// Initialize from MistKit QuerySort + internal init(from querySort: QuerySort) { + self = querySort.sort + } +} diff --git a/Sources/MistKit/Extensions/RecordManaging+Generic.swift b/Sources/MistKit/Extensions/RecordManaging+Generic.swift new file mode 100644 index 00000000..5db8f04c --- /dev/null +++ b/Sources/MistKit/Extensions/RecordManaging+Generic.swift @@ -0,0 +1,128 @@ +// +// RecordManaging+Generic.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +public import Foundation + +/// Generic extensions for RecordManaging protocol that work with any CloudKitRecord type +/// +/// These extensions eliminate the need for type-specific implementations by leveraging +/// the CloudKitRecord protocol's serialization methods. +extension RecordManaging { + // MARK: - Generic Operations + + /// Sync records of any CloudKitRecord-conforming type to CloudKit + /// + /// This generic method eliminates the need for type-specific sync methods. + /// The model's `toCloudKitFields()` method handles field mapping. + /// Operations are automatically batched to respect CloudKit's 200 operations/request limit. + /// + /// ## Example + /// ```swift + /// let swiftRecords: [SwiftVersionRecord] = [...] + /// try await service.sync(swiftRecords) + /// ``` + /// + /// - Parameter records: Array of records conforming to CloudKitRecord + /// - Throws: CloudKit errors if the sync operation fails + public func sync(_ records: [T]) async throws { + let operations = records.map { record in + RecordOperation( + operationType: .forceReplace, + recordType: T.cloudKitRecordType, + recordName: record.recordName, + fields: record.toCloudKitFields() + ) + } + + // Batch operations to respect CloudKit's 200 operations/request limit + let batches = operations.chunked(into: 200) + + for batch in batches { + try await executeBatchOperations(batch, recordType: T.cloudKitRecordType) + } + } + + /// List records of any CloudKitRecord-conforming type with formatted output + /// + /// This generic method queries all records of the specified type and displays + /// them using the type's `formatForDisplay()` implementation. + /// + /// ## Example + /// ```swift + /// try await service.list(XcodeVersionRecord.self) + /// ``` + /// + /// - Parameters: + /// - type: The CloudKitRecord type to list + /// - Throws: CloudKit errors if the query fails + public func list(_ type: T.Type) async throws { + let records = try await queryRecords(recordType: T.cloudKitRecordType) + + print("\n\(T.cloudKitRecordType) (\(records.count) total)") + print(String(repeating: "=", count: 80)) + + guard !records.isEmpty else { + print(" No records found.") + return + } + + for record in records { + print(T.formatForDisplay(record)) + } + } + + /// Query and parse records of any CloudKitRecord-conforming type + /// + /// This generic method fetches raw CloudKit records and converts them + /// to strongly-typed model instances using the type's `from(recordInfo:)` method. + /// + /// ## Example + /// ```swift + /// // Query all Swift versions + /// let allVersions = try await service.query(SwiftVersionRecord.self) + /// + /// // Query with filter + /// let betas = try await service.query(SwiftVersionRecord.self) { record in + /// record.fields["isPrerelease"]?.boolValue == true + /// } + /// ``` + /// + /// - Parameters: + /// - type: The CloudKitRecord type to query + /// - filter: Optional closure to filter RecordInfo results before parsing + /// - Returns: Array of parsed model instances (nil records are filtered out) + /// - Throws: CloudKit errors if the query fails + public func query( + _ type: T.Type, + where filter: (RecordInfo) -> Bool = { _ in true } + ) async throws -> [T] { + let records = try await queryRecords(recordType: T.cloudKitRecordType) + return records.filter(filter).compactMap(T.from) + } +} diff --git a/Sources/MistKit/Extensions/RecordManaging+RecordCollection.swift b/Sources/MistKit/Extensions/RecordManaging+RecordCollection.swift new file mode 100644 index 00000000..8ec39ee0 --- /dev/null +++ b/Sources/MistKit/Extensions/RecordManaging+RecordCollection.swift @@ -0,0 +1,184 @@ +// +// RecordManaging+RecordCollection.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +public import Foundation + +/// Default implementations for RecordManaging when conforming to CloudKitRecordCollection +/// +/// Provides generic implementations using Swift variadic generics (parameter packs) +/// to iterate through CloudKit record types at compile time without runtime reflection. +@available(macOS 14.0, iOS 17.0, tvOS 17.0, watchOS 10.0, *) +extension RecordManaging where Self: CloudKitRecordCollection { + /// Synchronize multiple record types to CloudKit using variadic generics + /// + /// This method uses Swift parameter packs to accept multiple arrays of different + /// CloudKit record types, providing compile-time type safety without dictionaries. + /// + /// - Parameter records: Variadic arrays of CloudKit records (one per record type) + /// - Throws: CloudKit errors or serialization errors + /// + /// ## Example + /// + /// ```swift + /// try await service.syncAllRecords( + /// restoreImages, // [RestoreImageRecord] + /// xcodeVersions, // [XcodeVersionRecord] + /// swiftVersions // [SwiftVersionRecord] + /// ) + /// ``` + /// + /// ## Type Safety Benefits + /// + /// - No string keys to mistype + /// - Compiler enforces concrete types + /// - Each array maintains its specific type + /// - Impossible to pass wrong record type + public func syncAllRecords( + _ records: repeat [each RecordType] + ) async throws { + // Swift 6.0+ pack iteration + // swift-format-ignore: UseWhereClausesInForLoops + for recordArray in repeat each records { + guard !recordArray.isEmpty else { continue } + // Extract type information from first record + let firstRecord = recordArray[0] + let typeName = type(of: firstRecord).cloudKitRecordType + + // Convert records to operations + let operations = recordArray.map { record in + RecordOperation( + operationType: .forceReplace, + recordType: typeName, + recordName: record.recordName, + fields: record.toCloudKitFields() + ) + } + + // Execute batch operation for this record type + try await executeBatchOperations(operations, recordType: typeName) + } + } + + /// List all records across all types defined in RecordTypeSet + /// + /// Uses Swift variadic generics to iterate through record types at compile time. + /// Prints a summary at the end. + /// + /// - Throws: CloudKit errors + public func listAllRecords() async throws { + var totalCount = 0 + var countsByType: [String: Int] = [:] + var recordTypesList: [any CloudKitRecord.Type] = [] + + // Use RecordTypeSet to iterate through types without reflection + try await Self.recordTypes.forEach { recordType in + recordTypesList.append(recordType) + let typeName = recordType.cloudKitRecordType + let records = try await queryRecords(recordType: typeName) + countsByType[typeName] = records.count + totalCount += records.count + + // Display records using the type's formatForDisplay + print("\n\(typeName) (\(records.count) total)") + print(String(repeating: "=", count: 80)) + + for record in records { + print(recordType.formatForDisplay(record)) + } + } + + // Print summary + print("\n📊 Summary") + print(String(repeating: "=", count: 80)) + print(" Total Records: \(totalCount)") + for recordType in recordTypesList { + let typeName = recordType.cloudKitRecordType + let count = countsByType[typeName] ?? 0 + print(" • \(typeName): \(count)") + } + print("") + } + + /// Delete all records across all types defined in RecordTypeSet + /// + /// Uses Swift variadic generics to iterate through record types at compile time. + /// Queries all records for each type and deletes them in batches. + /// + /// - Throws: CloudKit errors + /// + /// ## Example + /// + /// ```swift + /// try await service.deleteAllRecords() + /// ``` + public func deleteAllRecords() async throws { + var totalDeleted = 0 + var deletedByType: [String: Int] = [:] + + print("\n🗑️ Deleting all records across all types...") + + // Use RecordTypeSet to iterate through types without reflection + try await Self.recordTypes.forEach { recordType in + let typeName = recordType.cloudKitRecordType + let records = try await queryRecords(recordType: typeName) + + guard !records.isEmpty else { + print("\n\(typeName): No records to delete") + return + } + + print("\n\(typeName): Deleting \(records.count) record(s)...") + + // Create delete operations for all records + let operations = records.map { record in + RecordOperation( + operationType: .delete, + recordType: typeName, + recordName: record.recordName, + fields: [:] + ) + } + + // Execute batch delete operations + try await executeBatchOperations(operations, recordType: typeName) + + deletedByType[typeName] = records.count + totalDeleted += records.count + } + + // Print summary + print("\n📊 Deletion Summary") + print(String(repeating: "=", count: 80)) + print(" Total Records Deleted: \(totalDeleted)") + for (typeName, count) in deletedByType.sorted(by: { $0.key < $1.key }) { + print(" • \(typeName): \(count)") + } + print("") + } +} diff --git a/Sources/MistKit/FieldValue.swift b/Sources/MistKit/FieldValue.swift index e60d4c4f..d325baef 100644 --- a/Sources/MistKit/FieldValue.swift +++ b/Sources/MistKit/FieldValue.swift @@ -30,11 +30,12 @@ public import Foundation /// Represents a CloudKit field value as defined in the CloudKit Web Services API -public enum FieldValue: Codable, Equatable { +public enum FieldValue: Codable, Equatable, Sendable { + /// Conversion factor from seconds to milliseconds for CloudKit timestamps + private static let millisecondsPerSecond: Double = 1_000 case string(String) case int64(Int) case double(Double) - case boolean(Bool) case bytes(String) // Base64-encoded string case date(Date) // Date/time value case location(Location) @@ -43,7 +44,7 @@ public enum FieldValue: Codable, Equatable { case list([FieldValue]) /// Location dictionary as defined in CloudKit Web Services - public struct Location: Codable, Equatable { + public struct Location: Codable, Equatable, Sendable { /// The latitude coordinate public let latitude: Double /// The longitude coordinate @@ -84,21 +85,27 @@ public enum FieldValue: Codable, Equatable { } /// Reference dictionary as defined in CloudKit Web Services - public struct Reference: Codable, Equatable { + public struct Reference: Codable, Equatable, Sendable { + /// Reference action types supported by CloudKit + public enum Action: String, Codable, Sendable { + case deleteSelf = "DELETE_SELF" + case none = "NONE" + } + /// The record name being referenced public let recordName: String - /// The action to take ("DELETE_SELF" or nil) - public let action: String? + /// The action to take (DELETE_SELF, NONE, or nil) + public let action: Action? /// Initialize a reference value - public init(recordName: String, action: String? = nil) { + public init(recordName: String, action: Action? = nil) { self.recordName = recordName self.action = action } } /// Asset dictionary as defined in CloudKit Web Services - public struct Asset: Codable, Equatable { + public struct Asset: Codable, Equatable, Sendable { /// The file checksum public let fileChecksum: String? /// The file size in bytes @@ -151,7 +158,7 @@ public enum FieldValue: Codable, Equatable { ) } - /// Decode basic field value types (string, int64, double, boolean) + /// Decode basic field value types (string, int64, double) private static func decodeBasicTypes(from container: any SingleValueDecodingContainer) throws -> FieldValue? { @@ -164,9 +171,6 @@ public enum FieldValue: Codable, Equatable { if let value = try? container.decode(Double.self) { return .double(value) } - if let value = try? container.decode(Bool.self) { - return .boolean(value) - } return nil } @@ -188,7 +192,7 @@ public enum FieldValue: Codable, Equatable { } // Try to decode as date (milliseconds since epoch) if let value = try? container.decode(Double.self) { - return .date(Date(timeIntervalSince1970: value / 1_000)) + return .date(Date(timeIntervalSince1970: value / Self.millisecondsPerSecond)) } return nil } @@ -208,10 +212,8 @@ public enum FieldValue: Codable, Equatable { try container.encode(val) case .double(let val): try container.encode(val) - case .boolean(let val): - try container.encode(val) case .date(let val): - try container.encode(val.timeIntervalSince1970 * 1_000) + try container.encode(val.timeIntervalSince1970 * Self.millisecondsPerSecond) case .location(let val): try container.encode(val) case .reference(let val): @@ -223,3 +225,20 @@ public enum FieldValue: Codable, Equatable { } } } + +// MARK: - Helper Methods + +extension FieldValue { + /// Create an int64 FieldValue from a Bool + /// + /// CloudKit represents booleans as INT64 (0/1) on the wire. + /// Creates a FieldValue from a Swift Bool value. + /// + /// This initializer converts Swift Bool to the appropriate int64 representation + /// used by CloudKit (1 for true, 0 for false). + /// + /// - Parameter booleanValue: The boolean value to convert + public init(booleanValue: Bool) { + self = .int64(booleanValue ? 1 : 0) + } +} diff --git a/Sources/MistKit/Generated/Types.swift b/Sources/MistKit/Generated/Types.swift index 270af57b..ea8bd6ce 100644 --- a/Sources/MistKit/Generated/Types.swift +++ b/Sources/MistKit/Generated/Types.swift @@ -656,10 +656,6 @@ internal enum Components { /// /// - Remark: Generated from `#/components/schemas/DoubleValue`. internal typealias DoubleValue = Swift.Double - /// A true or false value - /// - /// - Remark: Generated from `#/components/schemas/BooleanValue`. - internal typealias BooleanValue = Swift.Bool /// Base64-encoded string representing binary data /// /// - Remark: Generated from `#/components/schemas/BytesValue`. @@ -757,6 +753,7 @@ internal enum Components { /// /// - Remark: Generated from `#/components/schemas/ReferenceValue/action`. internal enum actionPayload: String, Codable, Hashable, Sendable, CaseIterable { + case NONE = "NONE" case DELETE_SELF = "DELETE_SELF" } /// Action to perform on the referenced record @@ -850,18 +847,16 @@ internal enum Components { /// - Remark: Generated from `#/components/schemas/ListValue/case3`. case DoubleValue(Components.Schemas.DoubleValue) /// - Remark: Generated from `#/components/schemas/ListValue/case4`. - case BooleanValue(Components.Schemas.BooleanValue) - /// - Remark: Generated from `#/components/schemas/ListValue/case5`. case BytesValue(Components.Schemas.BytesValue) - /// - Remark: Generated from `#/components/schemas/ListValue/case6`. + /// - Remark: Generated from `#/components/schemas/ListValue/case5`. case DateValue(Components.Schemas.DateValue) - /// - Remark: Generated from `#/components/schemas/ListValue/case7`. + /// - Remark: Generated from `#/components/schemas/ListValue/case6`. case LocationValue(Components.Schemas.LocationValue) - /// - Remark: Generated from `#/components/schemas/ListValue/case8`. + /// - Remark: Generated from `#/components/schemas/ListValue/case7`. case ReferenceValue(Components.Schemas.ReferenceValue) - /// - Remark: Generated from `#/components/schemas/ListValue/case9`. + /// - Remark: Generated from `#/components/schemas/ListValue/case8`. case AssetValue(Components.Schemas.AssetValue) - /// - Remark: Generated from `#/components/schemas/ListValue/case10`. + /// - Remark: Generated from `#/components/schemas/ListValue/case9`. case ListValue(Components.Schemas.ListValue) internal init(from decoder: any Decoder) throws { var errors: [any Error] = [] @@ -883,12 +878,6 @@ internal enum Components { } catch { errors.append(error) } - do { - self = .BooleanValue(try decoder.decodeFromSingleValueContainer()) - return - } catch { - errors.append(error) - } do { self = .BytesValue(try decoder.decodeFromSingleValueContainer()) return @@ -939,8 +928,6 @@ internal enum Components { try encoder.encodeToSingleValueContainer(value) case let .DoubleValue(value): try encoder.encodeToSingleValueContainer(value) - case let .BooleanValue(value): - try encoder.encodeToSingleValueContainer(value) case let .BytesValue(value): try encoder.encodeToSingleValueContainer(value) case let .DateValue(value): diff --git a/Sources/MistKit/Helpers/FilterBuilder.swift b/Sources/MistKit/Helpers/FilterBuilder.swift new file mode 100644 index 00000000..ee8b55eb --- /dev/null +++ b/Sources/MistKit/Helpers/FilterBuilder.swift @@ -0,0 +1,275 @@ +// +// FilterBuilder.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation + +/// A builder for constructing CloudKit query filters +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +internal struct FilterBuilder { + // MARK: - Lifecycle + + private init() {} + + // MARK: - Internal + + // MARK: Equality Filters + + /// Creates an EQUALS filter + /// - Parameters: + /// - field: The field name to filter on + /// - value: The value to compare + /// - Returns: A configured Filter + internal static func equals(_ field: String, _ value: FieldValue) -> Components.Schemas.Filter { + .init( + comparator: .EQUALS, + fieldName: field, + fieldValue: .init(from: value) + ) + } + + /// Creates a NOT_EQUALS filter + /// - Parameters: + /// - field: The field name to filter on + /// - value: The value to compare + /// - Returns: A configured Filter + internal static func notEquals(_ field: String, _ value: FieldValue) -> Components.Schemas.Filter + { + .init( + comparator: .NOT_EQUALS, + fieldName: field, + fieldValue: .init(from: value) + ) + } + + // MARK: Comparison Filters + + /// Creates a LESS_THAN filter + /// - Parameters: + /// - field: The field name to filter on + /// - value: The value to compare + /// - Returns: A configured Filter + internal static func lessThan(_ field: String, _ value: FieldValue) -> Components.Schemas.Filter { + .init( + comparator: .LESS_THAN, + fieldName: field, + fieldValue: .init(from: value) + ) + } + + /// Creates a LESS_THAN_OR_EQUALS filter + /// - Parameters: + /// - field: The field name to filter on + /// - value: The value to compare + /// - Returns: A configured Filter + internal static func lessThanOrEquals( + _ field: String, + _ value: FieldValue + ) -> Components.Schemas.Filter { + .init( + comparator: .LESS_THAN_OR_EQUALS, + fieldName: field, + fieldValue: .init(from: value) + ) + } + + /// Creates a GREATER_THAN filter + /// - Parameters: + /// - field: The field name to filter on + /// - value: The value to compare + /// - Returns: A configured Filter + internal static func greaterThan( + _ field: String, + _ value: FieldValue + ) -> Components.Schemas.Filter { + .init( + comparator: .GREATER_THAN, + fieldName: field, + fieldValue: .init(from: value) + ) + } + + /// Creates a GREATER_THAN_OR_EQUALS filter + /// - Parameters: + /// - field: The field name to filter on + /// - value: The value to compare + /// - Returns: A configured Filter + internal static func greaterThanOrEquals( + _ field: String, + _ value: FieldValue + ) -> Components.Schemas.Filter { + .init( + comparator: .GREATER_THAN_OR_EQUALS, + fieldName: field, + fieldValue: .init(from: value) + ) + } + + // MARK: String Filters + + /// Creates a BEGINS_WITH filter for string fields + /// - Parameters: + /// - field: The field name to filter on + /// - value: The prefix value to match + /// - Returns: A configured Filter + internal static func beginsWith(_ field: String, _ value: String) -> Components.Schemas.Filter { + .init( + comparator: .BEGINS_WITH, + fieldName: field, + fieldValue: .init(value: .stringValue(value), type: .string) + ) + } + + /// Creates a NOT_BEGINS_WITH filter for string fields + /// - Parameters: + /// - field: The field name to filter on + /// - value: The prefix value to not match + /// - Returns: A configured Filter + internal static func notBeginsWith(_ field: String, _ value: String) -> Components.Schemas.Filter + { + .init( + comparator: .NOT_BEGINS_WITH, + fieldName: field, + fieldValue: .init(value: .stringValue(value), type: .string) + ) + } + + /// Creates a CONTAINS_ALL_TOKENS filter for string fields + /// - Parameters: + /// - field: The field name to filter on + /// - tokens: The string containing all tokens that must be present + /// - Returns: A configured Filter + internal static func containsAllTokens( + _ field: String, + _ tokens: String + ) -> Components.Schemas.Filter { + .init( + comparator: .CONTAINS_ALL_TOKENS, + fieldName: field, + fieldValue: .init(value: .stringValue(tokens), type: .string) + ) + } + + /// Creates an IN filter to check if field value is in a list + /// - Parameters: + /// - field: The field name to filter on + /// - values: Array of values to match against + /// - Returns: A configured Filter + internal static func `in`(_ field: String, _ values: [FieldValue]) -> Components.Schemas.Filter { + .init( + comparator: .IN, + fieldName: field, + fieldValue: .init( + value: .listValue(values.map { Components.Schemas.FieldValue(from: $0).value }), + type: .list + ) + ) + } + + /// Creates a NOT_IN filter to check if field value is not in a list + /// - Parameters: + /// - field: The field name to filter on + /// - values: Array of values to exclude + /// - Returns: A configured Filter + internal static func notIn(_ field: String, _ values: [FieldValue]) -> Components.Schemas.Filter { + .init( + comparator: .NOT_IN, + fieldName: field, + fieldValue: .init( + value: .listValue(values.map { Components.Schemas.FieldValue(from: $0).value }), + type: .list + ) + ) + } + + // MARK: List Member Filters + + /// Creates a LIST_CONTAINS filter + /// - Parameters: + /// - field: The list field name to filter on + /// - value: The value that should be in the list + /// - Returns: A configured Filter + internal static func listContains( + _ field: String, + _ value: FieldValue + ) -> Components.Schemas.Filter { + .init( + comparator: .LIST_CONTAINS, + fieldName: field, + fieldValue: .init(from: value) + ) + } + + /// Creates a NOT_LIST_CONTAINS filter + /// - Parameters: + /// - field: The list field name to filter on + /// - value: The value that should not be in the list + /// - Returns: A configured Filter + internal static func notListContains( + _ field: String, + _ value: FieldValue + ) -> Components.Schemas.Filter { + .init( + comparator: .NOT_LIST_CONTAINS, + fieldName: field, + fieldValue: .init(from: value) + ) + } + + /// Creates a LIST_MEMBER_BEGINS_WITH filter + /// - Parameters: + /// - field: The list field name to filter on + /// - prefix: The prefix that list members should begin with + /// - Returns: A configured Filter + internal static func listMemberBeginsWith( + _ field: String, + _ prefix: String + ) -> Components.Schemas.Filter { + .init( + comparator: .LIST_MEMBER_BEGINS_WITH, + fieldName: field, + fieldValue: .init(value: .stringValue(prefix), type: .string) + ) + } + + /// Creates a NOT_LIST_MEMBER_BEGINS_WITH filter + /// - Parameters: + /// - field: The list field name to filter on + /// - prefix: The prefix that list members should not begin with + /// - Returns: A configured Filter + internal static func notListMemberBeginsWith( + _ field: String, + _ prefix: String + ) -> Components.Schemas.Filter { + .init( + comparator: .NOT_LIST_MEMBER_BEGINS_WITH, + fieldName: field, + fieldValue: .init(value: .stringValue(prefix), type: .string) + ) + } +} diff --git a/Sources/MistKit/Helpers/SortDescriptor.swift b/Sources/MistKit/Helpers/SortDescriptor.swift new file mode 100644 index 00000000..a93c1233 --- /dev/null +++ b/Sources/MistKit/Helpers/SortDescriptor.swift @@ -0,0 +1,63 @@ +// +// SortDescriptor.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation + +/// A builder for constructing CloudKit query sort descriptors +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +internal struct SortDescriptor { + // MARK: - Lifecycle + + private init() {} + + // MARK: - Public + + /// Creates an ascending sort descriptor + /// - Parameter field: The field name to sort by + /// - Returns: A configured Sort + internal static func ascending(_ field: String) -> Components.Schemas.Sort { + .init(fieldName: field, ascending: true) + } + + /// Creates a descending sort descriptor + /// - Parameter field: The field name to sort by + /// - Returns: A configured Sort + internal static func descending(_ field: String) -> Components.Schemas.Sort { + .init(fieldName: field, ascending: false) + } + + /// Creates a sort descriptor with explicit direction + /// - Parameters: + /// - field: The field name to sort by + /// - ascending: Whether to sort in ascending order + /// - Returns: A configured Sort + internal static func sort(_ field: String, ascending: Bool = true) -> Components.Schemas.Sort { + .init(fieldName: field, ascending: ascending) + } +} diff --git a/Sources/MistKit/Logging/MistKitLogger.swift b/Sources/MistKit/Logging/MistKitLogger.swift new file mode 100644 index 00000000..87be36bf --- /dev/null +++ b/Sources/MistKit/Logging/MistKitLogger.swift @@ -0,0 +1,98 @@ +// +// MistKitLogger.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation +import Logging + +/// Centralized logging infrastructure for MistKit +internal enum MistKitLogger { + // MARK: - Subsystems + + /// Logger for CloudKit API operations + internal static let api = Logger(label: "com.brightdigit.MistKit.api") + + /// Logger for authentication and token management + internal static let auth = Logger(label: "com.brightdigit.MistKit.auth") + + /// Logger for network operations + internal static let network = Logger(label: "com.brightdigit.MistKit.network") + + // MARK: - Log Redaction Control + + /// Check if log redaction is disabled via environment variable + internal static var isRedactionDisabled: Bool { + ProcessInfo.processInfo.environment["MISTKIT_DISABLE_LOG_REDACTION"] == "1" + } + + // MARK: - Logging Helpers + + /// Log error with optional redaction + internal static func logError( + _ message: String, + logger: Logger, + shouldRedact: Bool = true + ) { + let finalMessage = + (isRedactionDisabled || !shouldRedact) ? message : SecureLogging.safeLogMessage(message) + logger.error("\(finalMessage)") + } + + /// Log warning with optional redaction + internal static func logWarning( + _ message: String, + logger: Logger, + shouldRedact: Bool = true + ) { + let finalMessage = + (isRedactionDisabled || !shouldRedact) ? message : SecureLogging.safeLogMessage(message) + logger.warning("\(finalMessage)") + } + + /// Log info with optional redaction + internal static func logInfo( + _ message: String, + logger: Logger, + shouldRedact: Bool = true + ) { + let finalMessage = + (isRedactionDisabled || !shouldRedact) ? message : SecureLogging.safeLogMessage(message) + logger.info("\(finalMessage)") + } + + /// Log debug with optional redaction + internal static func logDebug( + _ message: String, + logger: Logger, + shouldRedact: Bool = true + ) { + let finalMessage = + (isRedactionDisabled || !shouldRedact) ? message : SecureLogging.safeLogMessage(message) + logger.debug("\(finalMessage)") + } +} diff --git a/Sources/MistKit/LoggingMiddleware.swift b/Sources/MistKit/LoggingMiddleware.swift index 18bdf97b..9ed609d8 100644 --- a/Sources/MistKit/LoggingMiddleware.swift +++ b/Sources/MistKit/LoggingMiddleware.swift @@ -29,10 +29,15 @@ public import Foundation import HTTPTypes +import Logging import OpenAPIRuntime /// Logging middleware for debugging internal struct LoggingMiddleware: ClientMiddleware { + #if DEBUG + /// Logger for middleware HTTP request/response logging + private let logger = Logger(label: "com.brightdigit.MistKit.middleware") + #endif internal func intercept( _ request: HTTPRequest, body: HTTPBody?, @@ -58,10 +63,10 @@ internal struct LoggingMiddleware: ClientMiddleware { /// Log outgoing request details private func logRequest(_ request: HTTPRequest, baseURL: URL) { let fullPath = baseURL.absoluteString + (request.path ?? "") - print("🌐 CloudKit Request: \(request.method.rawValue) \(fullPath)") - print(" Base URL: \(baseURL.absoluteString)") - print(" Path: \(request.path ?? "none")") - print(" Headers: \(request.headerFields)") + logger.debug("🌐 CloudKit Request: \(request.method.rawValue) \(fullPath)") + logger.debug(" Base URL: \(baseURL.absoluteString)") + logger.debug(" Path: \(request.path ?? "none")") + logger.debug(" Headers: \(request.headerFields)") logQueryParameters(for: request, baseURL: baseURL) } @@ -76,10 +81,10 @@ internal struct LoggingMiddleware: ClientMiddleware { return } - print(" Query Parameters:") + logger.debug(" Query Parameters:") for item in queryItems { let value = formatQueryValue(for: item) - print(" \(item.name): \(value)") + logger.debug(" \(item.name): \(value)") } } @@ -102,10 +107,11 @@ internal struct LoggingMiddleware: ClientMiddleware { /// Log incoming response details private func logResponse(_ response: HTTPResponse, body: HTTPBody?) async -> HTTPBody? { - print("✅ CloudKit Response: \(response.status.code)") + logger.debug("✅ CloudKit Response: \(response.status.code)") if response.status.code == 421 { - print("⚠️ 421 Misdirected Request - The server cannot produce a response for this request") + logger.warning( + "⚠️ 421 Misdirected Request - The server cannot produce a response for this request") } return await logResponseBody(body) @@ -122,7 +128,7 @@ internal struct LoggingMiddleware: ClientMiddleware { logBodyData(bodyData) return HTTPBody(bodyData) } catch { - print("📄 Response Body: ") + logger.error("📄 Response Body: ") return responseBody } } @@ -130,10 +136,10 @@ internal struct LoggingMiddleware: ClientMiddleware { /// Log the actual body data content private func logBodyData(_ bodyData: Data) { if let jsonString = String(data: bodyData, encoding: .utf8) { - print("📄 Response Body:") - print(SecureLogging.safeLogMessage(jsonString)) + logger.debug("📄 Response Body:") + logger.debug("\(SecureLogging.safeLogMessage(jsonString))") } else { - print("📄 Response Body: ") + logger.debug("📄 Response Body: ") } } #endif diff --git a/Sources/MistKit/Protocols/CloudKitRecord.swift b/Sources/MistKit/Protocols/CloudKitRecord.swift new file mode 100644 index 00000000..2bad8674 --- /dev/null +++ b/Sources/MistKit/Protocols/CloudKitRecord.swift @@ -0,0 +1,120 @@ +// +// CloudKitRecord.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +public import Foundation + +/// Protocol for types that can be serialized to and from CloudKit records +/// +/// Conforming types can be automatically synced, queried, and listed using +/// generic `RecordManaging` extension methods, eliminating the need for +/// model-specific implementations. +/// +/// ## Example Conformance +/// +/// ```swift +/// extension MyRecord: CloudKitRecord { +/// static var cloudKitRecordType: String { "MyRecord" } +/// +/// func toCloudKitFields() -> [String: FieldValue] { +/// var fields: [String: FieldValue] = [ +/// "name": .string(name), +/// "count": .int64(Int64(count)) +/// ] +/// if let optional { fields["optional"] = .string(optional) } +/// return fields +/// } +/// +/// static func from(recordInfo: RecordInfo) -> Self? { +/// guard let name = recordInfo.fields["name"]?.stringValue else { +/// return nil +/// } +/// return MyRecord(name: name, count: recordInfo.fields["count"]?.intValue ?? 0) +/// } +/// +/// static func formatForDisplay(_ recordInfo: RecordInfo) -> String { +/// let name = recordInfo.fields["name"]?.stringValue ?? "Unknown" +/// return " \(name)" +/// } +/// } +/// ``` +public protocol CloudKitRecord: Codable, Sendable { + /// The CloudKit record type name + /// + /// This must match the record type defined in your CloudKit schema. + /// For example: "RestoreImage", "XcodeVersion", "SwiftVersion" + static var cloudKitRecordType: String { get } + + /// The unique CloudKit record name for this instance + /// + /// This is typically computed from the model's primary key or unique identifier. + /// For example: "RestoreImage-23C71" or "XcodeVersion-15.2" + var recordName: String { get } + + /// Convert this model to CloudKit field values + /// + /// Map each property to its corresponding `FieldValue` enum case: + /// - String properties → `.string(value)` + /// - Int properties → `.int64(Int64(value))` + /// - Double properties → `.double(value)` + /// - Bool properties → `.from(value)` or `.int64(value ? 1 : 0)` + /// - Date properties → `.date(value)` + /// - References → `.reference(recordName: "OtherRecord-ID")` + /// + /// Handle optional properties with conditional field assignment: + /// ```swift + /// if let optionalValue { fields["optional"] = .string(optionalValue) } + /// ``` + /// + /// - Returns: Dictionary mapping CloudKit field names to their values + func toCloudKitFields() -> [String: FieldValue] + + /// Parse a CloudKit record into a model instance + /// + /// Extract required fields using `FieldValue` convenience properties: + /// - `.stringValue` for String fields + /// - `.intValue` for Int fields + /// - `.doubleValue` for Double fields + /// - `.boolValue` for Bool fields (handles CloudKit's int64 boolean representation) + /// - `.dateValue` for Date fields + /// + /// Return `nil` if required fields are missing or invalid. + /// + /// - Parameter recordInfo: The CloudKit record information to parse + /// - Returns: A model instance, or `nil` if parsing fails + static func from(recordInfo: RecordInfo) -> Self? + + /// Format a CloudKit record for display output + /// + /// Generate a human-readable string representation for console output. + /// This is used by `list()` methods to display query results. + /// + /// - Parameter recordInfo: The CloudKit record to format + /// - Returns: A formatted string (typically 1-3 lines with indentation) + static func formatForDisplay(_ recordInfo: RecordInfo) -> String +} diff --git a/Sources/MistKit/Protocols/CloudKitRecordCollection.swift b/Sources/MistKit/Protocols/CloudKitRecordCollection.swift new file mode 100644 index 00000000..8827073b --- /dev/null +++ b/Sources/MistKit/Protocols/CloudKitRecordCollection.swift @@ -0,0 +1,62 @@ +// +// CloudKitRecordCollection.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +public import Foundation + +/// Protocol for services that manage a collection of CloudKit record types using variadic generics +/// +/// Conforming types define which record types they manage via a `RecordTypeSet` parameter pack, +/// enabling generic operations that work across all managed types without hardcoding specific types. +/// +/// ## Example +/// +/// ```swift +/// extension MyCloudKitService: CloudKitRecordCollection { +/// static let recordTypes = RecordTypeSet( +/// RestoreImageRecord.self, +/// XcodeVersionRecord.self, +/// SwiftVersionRecord.self +/// ) +/// } +/// +/// // Now listAllRecords() automatically iterates through these types +/// try await service.listAllRecords() +/// ``` +public protocol CloudKitRecordCollection { + /// Type of the record type set (inferred from static property) + /// + /// Must conform to `RecordTypeIterating` to provide `forEach` iteration. + associatedtype RecordTypeSetType: RecordTypeIterating + + /// Parameter pack defining all CloudKit record types managed by this service + /// + /// Define the complete set of record types using `RecordTypeSet`. + /// These types will be used for batch operations like listing all records. + static var recordTypes: RecordTypeSetType { get } +} diff --git a/Sources/MistKit/Protocols/RecordManaging.swift b/Sources/MistKit/Protocols/RecordManaging.swift new file mode 100644 index 00000000..7565d27c --- /dev/null +++ b/Sources/MistKit/Protocols/RecordManaging.swift @@ -0,0 +1,55 @@ +// +// RecordManaging.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +public import Foundation + +/// Protocol defining core CloudKit record management operations +/// +/// This protocol provides a testable abstraction for CloudKit operations. +/// Conforming types must implement the two core operations, while all other +/// functionality (listing, syncing, deleting) is provided through protocol extensions. +public protocol RecordManaging { + /// Query records of a specific type from CloudKit + /// + /// - Parameter recordType: The CloudKit record type to query + /// - Returns: Array of record information for all matching records + /// - Throws: CloudKit errors if the query fails + func queryRecords(recordType: String) async throws -> [RecordInfo] + + /// Execute a batch of record operations + /// + /// Handles batching operations to respect CloudKit's 200 operations/request limit. + /// Provides detailed progress reporting and error tracking. + /// + /// - Parameters: + /// - operations: Array of record operations to execute + /// - recordType: The record type being operated on (for logging) + /// - Throws: CloudKit errors if the batch operations fail + func executeBatchOperations(_ operations: [RecordOperation], recordType: String) async throws +} diff --git a/Sources/MistKit/Protocols/RecordTypeSet.swift b/Sources/MistKit/Protocols/RecordTypeSet.swift new file mode 100644 index 00000000..789b3b0d --- /dev/null +++ b/Sources/MistKit/Protocols/RecordTypeSet.swift @@ -0,0 +1,79 @@ +// +// RecordTypeSet.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +public import Foundation + +/// Protocol for types that provide iteration over CloudKit record types +/// +/// Conforming types provide a `forEach` method for iterating through +/// a collection of CloudKit record types. +public protocol RecordTypeIterating { + /// Iterate through all record types + /// + /// - Parameter action: Closure called for each record type + /// - Throws: Rethrows any errors thrown by the action closure + func forEach(_ action: (any CloudKitRecord.Type) async throws -> Void) async rethrows +} + +/// Lightweight container for CloudKit record types using Swift variadic generics +/// +/// This struct captures a parameter pack of `CloudKitRecord` types and provides +/// type-safe iteration over them without runtime reflection. +/// +/// ## Example +/// +/// ```swift +/// let recordTypes = RecordTypeSet( +/// RestoreImageRecord.self, +/// XcodeVersionRecord.self, +/// SwiftVersionRecord.self +/// ) +/// +/// recordTypes.forEach { recordType in +/// print(recordType.cloudKitRecordType) +/// } +/// ``` +@available(macOS 14.0, iOS 17.0, tvOS 17.0, watchOS 10.0, *) +public struct RecordTypeSet: Sendable, RecordTypeIterating { + /// Initialize with a parameter pack of CloudKit record types + /// + /// - Parameter types: Variadic parameter pack of CloudKit record types + public init(_ types: repeat (each RecordType).Type) {} + + /// Iterate through all record types in the parameter pack + /// + /// This method uses Swift's `repeat each` pattern to iterate through + /// the parameter pack at compile time, providing type-safe access to each type. + /// + /// - Parameter action: Closure called for each record type + /// - Throws: Rethrows any errors thrown by the action closure + public func forEach(_ action: (any CloudKitRecord.Type) async throws -> Void) async rethrows { + try await (repeat action((each RecordType).self)) + } +} diff --git a/Sources/MistKit/PublicTypes/QueryFilter.swift b/Sources/MistKit/PublicTypes/QueryFilter.swift new file mode 100644 index 00000000..716e0ceb --- /dev/null +++ b/Sources/MistKit/PublicTypes/QueryFilter.swift @@ -0,0 +1,129 @@ +// +// QueryFilter.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation + +/// Public wrapper for CloudKit query filters +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +public struct QueryFilter { + // MARK: - Lifecycle + + private init(_ filter: Components.Schemas.Filter) { + self.filter = filter + } + + // MARK: - Public + + // MARK: Equality Filters + + /// Creates an EQUALS filter + public static func equals(_ field: String, _ value: FieldValue) -> QueryFilter { + QueryFilter(FilterBuilder.equals(field, value)) + } + + /// Creates a NOT_EQUALS filter + public static func notEquals(_ field: String, _ value: FieldValue) -> QueryFilter { + QueryFilter(FilterBuilder.notEquals(field, value)) + } + + // MARK: Comparison Filters + + /// Creates a LESS_THAN filter + public static func lessThan(_ field: String, _ value: FieldValue) -> QueryFilter { + QueryFilter(FilterBuilder.lessThan(field, value)) + } + + /// Creates a LESS_THAN_OR_EQUALS filter + public static func lessThanOrEquals(_ field: String, _ value: FieldValue) -> QueryFilter { + QueryFilter(FilterBuilder.lessThanOrEquals(field, value)) + } + + /// Creates a GREATER_THAN filter + public static func greaterThan(_ field: String, _ value: FieldValue) -> QueryFilter { + QueryFilter(FilterBuilder.greaterThan(field, value)) + } + + /// Creates a GREATER_THAN_OR_EQUALS filter + public static func greaterThanOrEquals(_ field: String, _ value: FieldValue) -> QueryFilter { + QueryFilter(FilterBuilder.greaterThanOrEquals(field, value)) + } + + // MARK: String Filters + + /// Creates a BEGINS_WITH filter for string fields + public static func beginsWith(_ field: String, _ value: String) -> QueryFilter { + QueryFilter(FilterBuilder.beginsWith(field, value)) + } + + /// Creates a NOT_BEGINS_WITH filter for string fields + public static func notBeginsWith(_ field: String, _ value: String) -> QueryFilter { + QueryFilter(FilterBuilder.notBeginsWith(field, value)) + } + + /// Creates a CONTAINS_ALL_TOKENS filter for string fields + public static func containsAllTokens(_ field: String, _ tokens: String) -> QueryFilter { + QueryFilter(FilterBuilder.containsAllTokens(field, tokens)) + } + + /// Creates an IN filter to check if field value is in a list + public static func `in`(_ field: String, _ values: [FieldValue]) -> QueryFilter { + QueryFilter(FilterBuilder.in(field, values)) + } + + /// Creates a NOT_IN filter to check if field value is not in a list + public static func notIn(_ field: String, _ values: [FieldValue]) -> QueryFilter { + QueryFilter(FilterBuilder.notIn(field, values)) + } + + // MARK: List Member Filters + + /// Creates a LIST_CONTAINS filter + public static func listContains(_ field: String, _ value: FieldValue) -> QueryFilter { + QueryFilter(FilterBuilder.listContains(field, value)) + } + + /// Creates a NOT_LIST_CONTAINS filter + public static func notListContains(_ field: String, _ value: FieldValue) -> QueryFilter { + QueryFilter(FilterBuilder.notListContains(field, value)) + } + + /// Creates a LIST_MEMBER_BEGINS_WITH filter + public static func listMemberBeginsWith(_ field: String, _ prefix: String) -> QueryFilter { + QueryFilter(FilterBuilder.listMemberBeginsWith(field, prefix)) + } + + /// Creates a NOT_LIST_MEMBER_BEGINS_WITH filter + public static func notListMemberBeginsWith(_ field: String, _ prefix: String) -> QueryFilter { + QueryFilter(FilterBuilder.notListMemberBeginsWith(field, prefix)) + } + + // MARK: - Internal + + internal let filter: Components.Schemas.Filter +} diff --git a/Sources/MistKit/PublicTypes/QuerySort.swift b/Sources/MistKit/PublicTypes/QuerySort.swift new file mode 100644 index 00000000..64481600 --- /dev/null +++ b/Sources/MistKit/PublicTypes/QuerySort.swift @@ -0,0 +1,69 @@ +// +// QuerySort.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation + +/// Public wrapper for CloudKit query sort descriptors +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +public struct QuerySort { + // MARK: - Lifecycle + + private init(_ sort: Components.Schemas.Sort) { + self.sort = sort + } + + // MARK: - Public + + /// Creates an ascending sort descriptor + /// - Parameter field: The field name to sort by + /// - Returns: A configured QuerySort + public static func ascending(_ field: String) -> QuerySort { + QuerySort(SortDescriptor.ascending(field)) + } + + /// Creates a descending sort descriptor + /// - Parameter field: The field name to sort by + /// - Returns: A configured QuerySort + public static func descending(_ field: String) -> QuerySort { + QuerySort(SortDescriptor.descending(field)) + } + + /// Creates a sort descriptor with explicit direction + /// - Parameters: + /// - field: The field name to sort by + /// - ascending: Whether to sort in ascending order + /// - Returns: A configured QuerySort + public static func sort(_ field: String, ascending: Bool = true) -> QuerySort { + QuerySort(SortDescriptor.sort(field, ascending: ascending)) + } + + // MARK: - Internal + + internal let sort: Components.Schemas.Sort +} diff --git a/Sources/MistKit/RecordOperation.swift b/Sources/MistKit/RecordOperation.swift new file mode 100644 index 00000000..f289dc75 --- /dev/null +++ b/Sources/MistKit/RecordOperation.swift @@ -0,0 +1,122 @@ +// +// RecordOperation.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +public import Foundation + +/// Represents a CloudKit record operation (create, update, delete, etc.) +public struct RecordOperation: Sendable { + /// The type of operation to perform + public enum OperationType: Sendable { + /// Create a new record + case create + /// Update an existing record + case update + /// Update an existing record, overwriting any conflicts + case forceUpdate + /// Replace an existing record + case replace + /// Replace an existing record, overwriting any conflicts + case forceReplace + /// Delete an existing record + case delete + /// Delete an existing record, overwriting any conflicts + case forceDelete + } + + /// The type of operation to perform + public let operationType: OperationType + /// The record type (e.g., "RestoreImage", "XcodeVersion") + public let recordType: String + /// The unique record name (optional for creates - CloudKit will generate one if not provided) + public let recordName: String? + /// The record fields as FieldValue types + public let fields: [String: FieldValue] + /// Optional record change tag for optimistic locking + public let recordChangeTag: String? + + /// Initialize a record operation + public init( + operationType: OperationType, + recordType: String, + recordName: String?, + fields: [String: FieldValue] = [:], + recordChangeTag: String? = nil + ) { + self.operationType = operationType + self.recordType = recordType + self.recordName = recordName + self.fields = fields + self.recordChangeTag = recordChangeTag + } + + /// Convenience initializer for creating a new record + public static func create( + recordType: String, + recordName: String? = nil, + fields: [String: FieldValue] + ) -> RecordOperation { + RecordOperation( + operationType: .create, + recordType: recordType, + recordName: recordName, + fields: fields + ) + } + + /// Convenience initializer for updating an existing record + public static func update( + recordType: String, + recordName: String, + fields: [String: FieldValue], + recordChangeTag: String? + ) -> RecordOperation { + RecordOperation( + operationType: .update, + recordType: recordType, + recordName: recordName, + fields: fields, + recordChangeTag: recordChangeTag + ) + } + + /// Convenience initializer for deleting a record + public static func delete( + recordType: String, + recordName: String, + recordChangeTag: String? = nil + ) -> RecordOperation { + RecordOperation( + operationType: .delete, + recordType: recordType, + recordName: recordName, + fields: [:], + recordChangeTag: recordChangeTag + ) + } +} diff --git a/Sources/MistKit/Service/CloudKitError+OpenAPI.swift b/Sources/MistKit/Service/CloudKitError+OpenAPI.swift index c52c3358..dd53e952 100644 --- a/Sources/MistKit/Service/CloudKitError+OpenAPI.swift +++ b/Sources/MistKit/Service/CloudKitError+OpenAPI.swift @@ -28,8 +28,24 @@ // extension CloudKitError { + /// Generic error extractors that work for any CloudKitResponseType + /// Acts as a reusable dictionary mapping response cases to error initializers + private static let errorExtractors: [@Sendable (any CloudKitResponseType) -> CloudKitError?] = [ + { $0.badRequestResponse.map { CloudKitError(badRequest: $0) } }, + { $0.unauthorizedResponse.map { CloudKitError(unauthorized: $0) } }, + { $0.forbiddenResponse.map { CloudKitError(forbidden: $0) } }, + { $0.notFoundResponse.map { CloudKitError(notFound: $0) } }, + { $0.conflictResponse.map { CloudKitError(conflict: $0) } }, + { $0.preconditionFailedResponse.map { CloudKitError(preconditionFailed: $0) } }, + { $0.contentTooLargeResponse.map { CloudKitError(contentTooLarge: $0) } }, + { $0.misdirectedRequestResponse.map { CloudKitError(unprocessableEntity: $0) } }, + { $0.tooManyRequestsResponse.map { CloudKitError(tooManyRequests: $0) } }, + { $0.internalServerErrorResponse.map { CloudKitError(internalServerError: $0) } }, + { $0.serviceUnavailableResponse.map { CloudKitError(serviceUnavailable: $0) } }, + ] + /// Initialize CloudKitError from a BadRequest response - internal init(badRequest response: Components.Responses.BadRequest) { + private init(badRequest response: Components.Responses.BadRequest) { if case .json(let errorResponse) = response.body { self = .httpErrorWithDetails( statusCode: 400, @@ -42,7 +58,7 @@ extension CloudKitError { } /// Initialize CloudKitError from an Unauthorized response - internal init(unauthorized response: Components.Responses.Unauthorized) { + private init(unauthorized response: Components.Responses.Unauthorized) { if case .json(let errorResponse) = response.body { self = .httpErrorWithDetails( statusCode: 401, @@ -55,7 +71,7 @@ extension CloudKitError { } /// Initialize CloudKitError from a Forbidden response - internal init(forbidden response: Components.Responses.Forbidden) { + private init(forbidden response: Components.Responses.Forbidden) { if case .json(let errorResponse) = response.body { self = .httpErrorWithDetails( statusCode: 403, @@ -68,7 +84,7 @@ extension CloudKitError { } /// Initialize CloudKitError from a NotFound response - internal init(notFound response: Components.Responses.NotFound) { + private init(notFound response: Components.Responses.NotFound) { if case .json(let errorResponse) = response.body { self = .httpErrorWithDetails( statusCode: 404, @@ -81,7 +97,7 @@ extension CloudKitError { } /// Initialize CloudKitError from a Conflict response - internal init(conflict response: Components.Responses.Conflict) { + private init(conflict response: Components.Responses.Conflict) { if case .json(let errorResponse) = response.body { self = .httpErrorWithDetails( statusCode: 409, @@ -94,7 +110,7 @@ extension CloudKitError { } /// Initialize CloudKitError from a PreconditionFailed response - internal init(preconditionFailed response: Components.Responses.PreconditionFailed) { + private init(preconditionFailed response: Components.Responses.PreconditionFailed) { if case .json(let errorResponse) = response.body { self = .httpErrorWithDetails( statusCode: 412, @@ -107,7 +123,7 @@ extension CloudKitError { } /// Initialize CloudKitError from a RequestEntityTooLarge response - internal init(contentTooLarge response: Components.Responses.RequestEntityTooLarge) { + private init(contentTooLarge response: Components.Responses.RequestEntityTooLarge) { if case .json(let errorResponse) = response.body { self = .httpErrorWithDetails( statusCode: 413, @@ -120,7 +136,7 @@ extension CloudKitError { } /// Initialize CloudKitError from a TooManyRequests response - internal init(tooManyRequests response: Components.Responses.TooManyRequests) { + private init(tooManyRequests response: Components.Responses.TooManyRequests) { if case .json(let errorResponse) = response.body { self = .httpErrorWithDetails( statusCode: 429, @@ -133,7 +149,7 @@ extension CloudKitError { } /// Initialize CloudKitError from an UnprocessableEntity response - internal init(unprocessableEntity response: Components.Responses.UnprocessableEntity) { + private init(unprocessableEntity response: Components.Responses.UnprocessableEntity) { if case .json(let errorResponse) = response.body { self = .httpErrorWithDetails( statusCode: 422, @@ -146,7 +162,7 @@ extension CloudKitError { } /// Initialize CloudKitError from an InternalServerError response - internal init(internalServerError response: Components.Responses.InternalServerError) { + private init(internalServerError response: Components.Responses.InternalServerError) { if case .json(let errorResponse) = response.body { self = .httpErrorWithDetails( statusCode: 500, @@ -159,7 +175,7 @@ extension CloudKitError { } /// Initialize CloudKitError from a ServiceUnavailable response - internal init(serviceUnavailable response: Components.Responses.ServiceUnavailable) { + private init(serviceUnavailable response: Components.Responses.ServiceUnavailable) { if case .json(let errorResponse) = response.body { self = .httpErrorWithDetails( statusCode: 503, @@ -170,4 +186,32 @@ extension CloudKitError { self = .httpError(statusCode: 503) } } + + /// Generic failable initializer for any CloudKitResponseType + /// Returns nil if the response is .ok (not an error) + internal init?(_ response: T) { + // Check if response is .ok - not an error + if response.isOk { + return nil + } + + // Try each error extractor + for extractor in Self.errorExtractors { + if let error = extractor(response) { + self = error + return + } + } + + // Handle undocumented error + if let statusCode = response.undocumentedStatusCode { + assertionFailure("Unhandled response status code: \(statusCode)") + self = .httpError(statusCode: statusCode) + return + } + + // Should never reach here + assertionFailure("Unhandled response case: \(response)") + self = .invalidResponse + } } diff --git a/Sources/MistKit/Service/CloudKitError.swift b/Sources/MistKit/Service/CloudKitError.swift index dc23a572..51c80499 100644 --- a/Sources/MistKit/Service/CloudKitError.swift +++ b/Sources/MistKit/Service/CloudKitError.swift @@ -36,6 +36,9 @@ public enum CloudKitError: LocalizedError, Sendable { case httpErrorWithDetails(statusCode: Int, serverErrorCode: String?, reason: String?) case httpErrorWithRawResponse(statusCode: Int, rawResponse: String) case invalidResponse + case underlyingError(any Error) + case decodingError(DecodingError) + case networkError(URLError) /// A localized message describing what error occurred public var errorDescription: String? { @@ -55,6 +58,47 @@ public enum CloudKitError: LocalizedError, Sendable { return "CloudKit API error: HTTP \(statusCode)\nRaw Response: \(rawResponse)" case .invalidResponse: return "Invalid response from CloudKit" + case .underlyingError(let error): + return "CloudKit operation failed with underlying error: \(String(reflecting: error))" + case .decodingError(let error): + var message = "Failed to decode CloudKit response" + switch error { + case .keyNotFound(let key, let context): + message += "\nMissing key: \(key.stringValue)" + message += "\nCoding path: \(context.codingPath.map(\.stringValue).joined(separator: "."))" + if let underlyingError = context.underlyingError { + message += "\nUnderlying error: \(underlyingError.localizedDescription)" + } + case .typeMismatch(let type, let context): + message += "\nType mismatch: expected \(type)" + message += "\nCoding path: \(context.codingPath.map(\.stringValue).joined(separator: "."))" + if let underlyingError = context.underlyingError { + message += "\nUnderlying error: \(underlyingError.localizedDescription)" + } + case .valueNotFound(let type, let context): + message += "\nValue not found: expected \(type)" + message += "\nCoding path: \(context.codingPath.map(\.stringValue).joined(separator: "."))" + if let underlyingError = context.underlyingError { + message += "\nUnderlying error: \(underlyingError.localizedDescription)" + } + case .dataCorrupted(let context): + message += "\nData corrupted" + message += "\nCoding path: \(context.codingPath.map(\.stringValue).joined(separator: "."))" + if let underlyingError = context.underlyingError { + message += "\nUnderlying error: \(underlyingError.localizedDescription)" + } + @unknown default: + message += "\nUnknown decoding error: \(error.localizedDescription)" + } + return message + case .networkError(let error): + var message = "Network error occurred" + message += "\nError code: \(error.code.rawValue)" + if let url = error.failureURLString { + message += "\nFailed URL: \(url)" + } + message += "\nDescription: \(error.localizedDescription)" + return message } } } diff --git a/Sources/MistKit/Service/CloudKitResponseProcessor.swift b/Sources/MistKit/Service/CloudKitResponseProcessor.swift index 670d5839..8a92e24f 100644 --- a/Sources/MistKit/Service/CloudKitResponseProcessor.swift +++ b/Sources/MistKit/Service/CloudKitResponseProcessor.swift @@ -39,14 +39,19 @@ internal struct CloudKitResponseProcessor { internal func processGetCurrentUserResponse(_ response: Operations.getCurrentUser.Output) async throws(CloudKitError) -> Components.Schemas.UserResponse { + // Check for errors first + if let error = CloudKitError(response) { + throw error + } + + // Must be .ok case - extract data switch response { case .ok(let okResponse): return try extractUserData(from: okResponse) default: - try await handleGetCurrentUserErrors(response) + // Should never reach here since all errors are handled above + throw CloudKitError.invalidResponse } - - throw CloudKitError.invalidResponse } /// Extract user data from OK response @@ -59,41 +64,31 @@ internal struct CloudKitResponseProcessor { } } - // swiftlint:disable cyclomatic_complexity - /// Handle error cases for getCurrentUser - private func handleGetCurrentUserErrors(_ response: Operations.getCurrentUser.Output) - async throws(CloudKitError) + /// Process lookupRecords response + /// - Parameter response: The response to process + /// - Returns: The extracted lookup response data + /// - Throws: CloudKitError for various error conditions + internal func processLookupRecordsResponse(_ response: Operations.lookupRecords.Output) + async throws(CloudKitError) -> Components.Schemas.LookupResponse { + // Check for errors first + if let error = CloudKitError(response) { + throw error + } + + // Must be .ok case - extract data switch response { - case .ok: - return // This case is handled in the main function - case .badRequest(let badRequestResponse): - throw CloudKitError(badRequest: badRequestResponse) - case .unauthorized(let unauthorizedResponse): - throw CloudKitError(unauthorized: unauthorizedResponse) - case .forbidden(let forbiddenResponse): - throw CloudKitError(forbidden: forbiddenResponse) - case .notFound(let notFoundResponse): - throw CloudKitError(notFound: notFoundResponse) - case .conflict(let conflictResponse): - throw CloudKitError(conflict: conflictResponse) - case .preconditionFailed(let preconditionFailedResponse): - throw CloudKitError(preconditionFailed: preconditionFailedResponse) - case .contentTooLarge(let contentTooLargeResponse): - throw CloudKitError(contentTooLarge: contentTooLargeResponse) - case .tooManyRequests(let tooManyRequestsResponse): - throw CloudKitError(tooManyRequests: tooManyRequestsResponse) - case .misdirectedRequest(let misdirectedResponse): - throw CloudKitError(unprocessableEntity: misdirectedResponse) - case .internalServerError(let internalServerErrorResponse): - throw CloudKitError(internalServerError: internalServerErrorResponse) - case .serviceUnavailable(let serviceUnavailableResponse): - throw CloudKitError(serviceUnavailable: serviceUnavailableResponse) - case .undocumented(let statusCode, _): - throw CloudKitError.httpError(statusCode: statusCode) + case .ok(let okResponse): + switch okResponse.body { + case .json(let lookupData): + return lookupData + } + default: + // Should never reach here since all errors are handled above + assertionFailure("Unexpected response case after error handling") + throw CloudKitError.invalidResponse } } - // swiftlint:enable cyclomatic_complexity /// Process listZones response /// - Parameter response: The response to process @@ -103,6 +98,12 @@ internal struct CloudKitResponseProcessor { async throws(CloudKitError) -> Components.Schemas.ZonesListResponse { + // Check for errors first + if let error = CloudKitError(response) { + throw error + } + + // Must be .ok case - extract data switch response { case .ok(let okResponse): switch okResponse.body { @@ -110,10 +111,10 @@ internal struct CloudKitResponseProcessor { return zonesData } default: - try await processStandardErrorResponse(response) + // Should never reach here since all errors are handled above + assertionFailure("Unexpected response case after error handling") + throw CloudKitError.invalidResponse } - - throw CloudKitError.invalidResponse } /// Process queryRecords response @@ -123,6 +124,18 @@ internal struct CloudKitResponseProcessor { internal func processQueryRecordsResponse(_ response: Operations.queryRecords.Output) async throws(CloudKitError) -> Components.Schemas.QueryResponse { + // Check for errors first + if let error = CloudKitError(response) { + // Log error with full details when redaction is disabled + MistKitLogger.logError( + "CloudKit queryRecords failed with response: \(response)", + logger: MistKitLogger.api, + shouldRedact: false + ) + throw error + } + + // Must be .ok case - extract data switch response { case .ok(let okResponse): switch okResponse.body { @@ -130,19 +143,34 @@ internal struct CloudKitResponseProcessor { return recordsData } default: - try await processStandardErrorResponse(response) + // Should never reach here since all errors are handled above + assertionFailure("Unexpected response case after error handling") + throw CloudKitError.invalidResponse } - - throw CloudKitError.invalidResponse } -} -// MARK: - Error Handling -extension CloudKitResponseProcessor { - /// Process standard error responses common across endpoints - private func processStandardErrorResponse(_: T) async throws(CloudKitError) { - // For now, throw a generic error - specific error handling should be implemented - // per endpoint as needed to avoid the complexity of reflection-based error handling - throw CloudKitError.invalidResponse + /// Process modifyRecords response + /// - Parameter response: The response to process + /// - Returns: The extracted modify response data + /// - Throws: CloudKitError for various error conditions + internal func processModifyRecordsResponse(_ response: Operations.modifyRecords.Output) + async throws(CloudKitError) -> Components.Schemas.ModifyResponse + { + // Check for errors first + if let error = CloudKitError(response) { + throw error + } + + // Must be .ok case - extract data + switch response { + case .ok(let okResponse): + switch okResponse.body { + case .json(let modifyData): + return modifyData + } + default: + // Should never reach here since all errors are handled above + throw CloudKitError.invalidResponse + } } } diff --git a/Sources/MistKit/Service/CloudKitResponseType.swift b/Sources/MistKit/Service/CloudKitResponseType.swift new file mode 100644 index 00000000..3534de70 --- /dev/null +++ b/Sources/MistKit/Service/CloudKitResponseType.swift @@ -0,0 +1,70 @@ +// +// CloudKitResponseType.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +/// Protocol for CloudKit operation response types that support unified error handling +internal protocol CloudKitResponseType { + /// Extract BadRequest response if present + var badRequestResponse: Components.Responses.BadRequest? { get } + + /// Extract Unauthorized response if present + var unauthorizedResponse: Components.Responses.Unauthorized? { get } + + /// Extract Forbidden response if present + var forbiddenResponse: Components.Responses.Forbidden? { get } + + /// Extract NotFound response if present + var notFoundResponse: Components.Responses.NotFound? { get } + + /// Extract Conflict response if present + var conflictResponse: Components.Responses.Conflict? { get } + + /// Extract PreconditionFailed response if present + var preconditionFailedResponse: Components.Responses.PreconditionFailed? { get } + + /// Extract ContentTooLarge response if present + var contentTooLargeResponse: Components.Responses.RequestEntityTooLarge? { get } + + /// Extract MisdirectedRequest response if present + var misdirectedRequestResponse: Components.Responses.UnprocessableEntity? { get } + + /// Extract TooManyRequests response if present + var tooManyRequestsResponse: Components.Responses.TooManyRequests? { get } + + /// Extract InternalServerError response if present + var internalServerErrorResponse: Components.Responses.InternalServerError? { get } + + /// Extract ServiceUnavailable response if present + var serviceUnavailableResponse: Components.Responses.ServiceUnavailable? { get } + + /// Check if response is successful (.ok case) + var isOk: Bool { get } + + /// Extract status code from undocumented response if present + var undocumentedStatusCode: Int? { get } +} diff --git a/Sources/MistKit/Service/CloudKitService+Operations.swift b/Sources/MistKit/Service/CloudKitService+Operations.swift index f7bf265b..75b47c89 100644 --- a/Sources/MistKit/Service/CloudKitService+Operations.swift +++ b/Sources/MistKit/Service/CloudKitService+Operations.swift @@ -47,11 +47,27 @@ extension CloudKitService { return UserInfo(from: userData) } catch let cloudKitError as CloudKitError { throw cloudKitError + } catch let decodingError as DecodingError { + MistKitLogger.logError( + "JSON decoding failed in fetchCurrentUser: \(decodingError)", + logger: MistKitLogger.api, + shouldRedact: false + ) + throw CloudKitError.decodingError(decodingError) + } catch let urlError as URLError { + MistKitLogger.logError( + "Network error in fetchCurrentUser: \(urlError)", + logger: MistKitLogger.network, + shouldRedact: false + ) + throw CloudKitError.networkError(urlError) } catch { - throw CloudKitError.httpErrorWithRawResponse( - statusCode: 500, - rawResponse: error.localizedDescription + MistKitLogger.logError( + "Unexpected error in fetchCurrentUser: \(error)", + logger: MistKitLogger.api, + shouldRedact: false ) + throw CloudKitError.underlyingError(error) } } @@ -78,18 +94,140 @@ extension CloudKitService { } ?? [] } catch let cloudKitError as CloudKitError { throw cloudKitError + } catch let decodingError as DecodingError { + MistKitLogger.logError( + "JSON decoding failed in listZones: \(decodingError)", + logger: MistKitLogger.api, + shouldRedact: false + ) + throw CloudKitError.decodingError(decodingError) + } catch let urlError as URLError { + MistKitLogger.logError( + "Network error in listZones: \(urlError)", + logger: MistKitLogger.network, + shouldRedact: false + ) + throw CloudKitError.networkError(urlError) } catch { - throw CloudKitError.httpErrorWithRawResponse( - statusCode: 500, - rawResponse: error.localizedDescription + MistKitLogger.logError( + "Unexpected error in listZones: \(error)", + logger: MistKitLogger.api, + shouldRedact: false ) + throw CloudKitError.underlyingError(error) } } /// Query records from the default zone - public func queryRecords(recordType: String, limit: Int = 10) async throws(CloudKitError) - -> [RecordInfo] - { + /// + /// Queries CloudKit records with optional filtering and sorting. Supports all CloudKit + /// filter operations (equals, comparisons, string matching, list operations) and field-based sorting. + /// + /// - Parameters: + /// - recordType: The type of records to query (must not be empty) + /// - filters: Optional array of filters to apply to the query + /// - sortBy: Optional array of sort descriptors + /// - limit: Maximum number of records to return (1-200, defaults to `defaultQueryLimit`) + /// - desiredKeys: Optional array of field names to fetch + /// - Returns: Array of matching records + /// - Throws: CloudKitError if validation fails or the request fails + /// + /// # Example: Basic Query + /// ```swift + /// // Query all articles + /// let articles = try await service.queryRecords( + /// recordType: "Article" + /// ) + /// ``` + /// + /// # Example: Query with Filters + /// ```swift + /// // Query published articles from the last week + /// let oneWeekAgo = Date().addingTimeInterval(-7 * 24 * 60 * 60) + /// let recentArticles = try await service.queryRecords( + /// recordType: "Article", + /// filters: [ + /// .greaterThan("publishedDate", .date(oneWeekAgo)), + /// .equals("status", .string("published")), + /// .equals("language", .string("en")) + /// ], + /// limit: 50 + /// ) + /// ``` + /// + /// # Example: Query with Sorting + /// ```swift + /// // Query articles sorted by date (newest first) + /// let sortedArticles = try await service.queryRecords( + /// recordType: "Article", + /// sortBy: [.descending("publishedDate")], + /// limit: 20 + /// ) + /// ``` + /// + /// # Example: Complex Query with String Matching + /// ```swift + /// // Search for articles with titles containing "Swift" + /// let swiftArticles = try await service.queryRecords( + /// recordType: "Article", + /// filters: [ + /// .contains("title", .string("Swift")), + /// .notEquals("status", .string("draft")) + /// ], + /// sortBy: [.descending("publishedDate")], + /// desiredKeys: ["title", "publishedDate", "author"] + /// ) + /// ``` + /// + /// # Example: List Operations + /// ```swift + /// // Query articles with specific tags + /// let taggedArticles = try await service.queryRecords( + /// recordType: "Article", + /// filters: [ + /// .in("category", [.string("Technology"), .string("Programming")]), + /// .greaterThanOrEquals("viewCount", .int64(1000)) + /// ] + /// ) + /// ``` + /// + /// # Available Filter Operations + /// - Equality: `.equals()`, `.notEquals()` + /// - Comparison: `.lessThan()`, `.lessThanOrEquals()`, `.greaterThan()`, `.greaterThanOrEquals()` + /// - String: `.beginsWith()`, `.contains()`, `.endsWith()` + /// - List: `.in()`, `.notIn()` + /// - Negation: `.not()` + /// + /// - Note: For large result sets, consider using pagination (see GitHub issue #145) + /// - Note: To query custom zones, see GitHub issue #146 + public func queryRecords( + recordType: String, + filters: [QueryFilter]? = nil, + sortBy: [QuerySort]? = nil, + limit: Int? = nil, + desiredKeys: [String]? = nil + ) async throws(CloudKitError) -> [RecordInfo] { + // Use provided limit or fall back to default configuration + let effectiveLimit = limit ?? defaultQueryLimit + + // Validate input parameters + guard !recordType.isEmpty else { + throw CloudKitError.httpErrorWithRawResponse( + statusCode: 400, + rawResponse: "recordType cannot be empty" + ) + } + + guard effectiveLimit > 0 && effectiveLimit <= 200 else { + throw CloudKitError.httpErrorWithRawResponse( + statusCode: 400, + rawResponse: "limit must be between 1 and 200, got \(effectiveLimit)" + ) + } + + let componentsFilters = filters?.map { Components.Schemas.Filter(from: $0) } + let componentsSorts = sortBy?.map { Components.Schemas.Sort(from: $0) } + do { let response = try await client.queryRecords( .init( @@ -97,16 +235,13 @@ extension CloudKitService { body: .json( .init( zoneID: .init(zoneName: "_defaultZone"), - resultsLimit: limit, + resultsLimit: effectiveLimit, query: .init( recordType: recordType, - sortBy: [ - // .init( - // fieldName: "modificationDate", - // ascending: false - // ) - ] - ) + filterBy: componentsFilters, + sortBy: componentsSorts + ), + desiredKeys: desiredKeys ) ) ) @@ -117,11 +252,176 @@ extension CloudKitService { return recordsData.records?.compactMap { RecordInfo(from: $0) } ?? [] } catch let cloudKitError as CloudKitError { throw cloudKitError + } catch let decodingError as DecodingError { + // Log detailed decoding error information + MistKitLogger.logError( + "JSON decoding failed in queryRecords: \(decodingError)", + logger: MistKitLogger.api, + shouldRedact: false + ) + + // Log detailed context based on error type + switch decodingError { + case .keyNotFound(let key, let context): + MistKitLogger.logDebug( + "Missing key: \(key), Context: \(context.debugDescription), Coding path: \(context.codingPath)", + logger: MistKitLogger.api, + shouldRedact: false + ) + case .typeMismatch(let type, let context): + MistKitLogger.logDebug( + "Type mismatch: expected \(type), Context: \(context.debugDescription), Coding path: \(context.codingPath)", + logger: MistKitLogger.api, + shouldRedact: false + ) + case .valueNotFound(let type, let context): + MistKitLogger.logDebug( + "Value not found: expected \(type), Context: \(context.debugDescription), Coding path: \(context.codingPath)", + logger: MistKitLogger.api, + shouldRedact: false + ) + case .dataCorrupted(let context): + MistKitLogger.logDebug( + "Data corrupted, Context: \(context.debugDescription), Coding path: \(context.codingPath)", + logger: MistKitLogger.api, + shouldRedact: false + ) + @unknown default: + MistKitLogger.logDebug( + "Unknown decoding error type", + logger: MistKitLogger.api, + shouldRedact: false + ) + } + + throw CloudKitError.decodingError(decodingError) + } catch let urlError as URLError { + // Log network error information + MistKitLogger.logError( + "Network error in queryRecords: \(urlError)", + logger: MistKitLogger.network, + shouldRedact: false + ) + + throw CloudKitError.networkError(urlError) } catch { - throw CloudKitError.httpErrorWithRawResponse( - statusCode: 500, - rawResponse: error.localizedDescription + // Log unexpected errors + MistKitLogger.logError( + "Unexpected error in queryRecords: \(error)", + logger: MistKitLogger.api, + shouldRedact: false + ) + + // Log additional debugging details + MistKitLogger.logDebug( + "Error type: \(type(of: error)), Description: \(String(reflecting: error))", + logger: MistKitLogger.api, + shouldRedact: false + ) + + throw CloudKitError.underlyingError(error) + } + } + + /// Modify (create, update, delete) records + @available( + *, deprecated, + message: "Use modifyRecords(_:) with RecordOperation in CloudKitService+WriteOperations instead" + ) + internal func modifyRecords( + operations: [Components.Schemas.RecordOperation], + atomic: Bool = true + ) async throws(CloudKitError) -> [RecordInfo] { + do { + let response = try await client.modifyRecords( + .init( + path: createModifyRecordsPath(containerIdentifier: containerIdentifier), + body: .json( + .init( + operations: operations, + atomic: atomic + ) + ) + ) + ) + + let modifyData: Components.Schemas.ModifyResponse = + try await responseProcessor.processModifyRecordsResponse(response) + return modifyData.records?.compactMap { RecordInfo(from: $0) } ?? [] + } catch let cloudKitError as CloudKitError { + throw cloudKitError + } catch let decodingError as DecodingError { + MistKitLogger.logError( + "JSON decoding failed in modifyRecords: \(decodingError)", + logger: MistKitLogger.api, + shouldRedact: false + ) + throw CloudKitError.decodingError(decodingError) + } catch let urlError as URLError { + MistKitLogger.logError( + "Network error in modifyRecords: \(urlError)", + logger: MistKitLogger.network, + shouldRedact: false + ) + throw CloudKitError.networkError(urlError) + } catch { + MistKitLogger.logError( + "Unexpected error in modifyRecords: \(error)", + logger: MistKitLogger.api, + shouldRedact: false + ) + throw CloudKitError.underlyingError(error) + } + } + + /// Lookup records by record names + internal func lookupRecords( + recordNames: [String], + desiredKeys: [String]? = nil + ) async throws(CloudKitError) -> [RecordInfo] { + do { + let response = try await client.lookupRecords( + .init( + path: createLookupRecordsPath(containerIdentifier: containerIdentifier), + body: .json( + .init( + records: recordNames.map { recordName in + .init( + recordName: recordName, + desiredKeys: desiredKeys + ) + } + ) + ) + ) + ) + + let lookupData: Components.Schemas.LookupResponse = + try await responseProcessor.processLookupRecordsResponse(response) + return lookupData.records?.compactMap { RecordInfo(from: $0) } ?? [] + } catch let cloudKitError as CloudKitError { + throw cloudKitError + } catch let decodingError as DecodingError { + MistKitLogger.logError( + "JSON decoding failed in lookupRecords: \(decodingError)", + logger: MistKitLogger.api, + shouldRedact: false + ) + throw CloudKitError.decodingError(decodingError) + } catch let urlError as URLError { + MistKitLogger.logError( + "Network error in lookupRecords: \(urlError)", + logger: MistKitLogger.network, + shouldRedact: false + ) + throw CloudKitError.networkError(urlError) + } catch { + MistKitLogger.logError( + "Unexpected error in lookupRecords: \(error)", + logger: MistKitLogger.api, + shouldRedact: false ) + throw CloudKitError.underlyingError(error) } } } diff --git a/Sources/MistKit/Service/CloudKitService+RecordManaging.swift b/Sources/MistKit/Service/CloudKitService+RecordManaging.swift new file mode 100644 index 00000000..cef69be7 --- /dev/null +++ b/Sources/MistKit/Service/CloudKitService+RecordManaging.swift @@ -0,0 +1,76 @@ +// +// CloudKitService+RecordManaging.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation + +/// CloudKitService conformance to RecordManaging protocol +/// +/// This extension makes CloudKitService compatible with the generic RecordManaging +/// operations, enabling protocol-oriented patterns for CloudKit operations. +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +extension CloudKitService: RecordManaging { + /// Query records of a specific type from CloudKit + /// + /// This implementation uses a default limit of 200 records. For more control over + /// query parameters (filters, sorting, custom limits), use the full `queryRecords` + /// method directly on CloudKitService. + /// + /// - Parameter recordType: The CloudKit record type to query + /// - Returns: Array of record information for matching records (up to 200) + /// - Throws: CloudKit errors if the query fails + public func queryRecords(recordType: String) async throws -> [RecordInfo] { + try await self.queryRecords( + recordType: recordType, + filters: nil, + sortBy: nil, + limit: 200 + ) + } + + /// Execute a batch of record operations + /// + /// This implementation delegates to CloudKitService's `modifyRecords` method. + /// The recordType parameter is provided for logging purposes but is not required + /// by the underlying implementation (operation types are embedded in RecordOperation). + /// + /// Note: The caller is responsible for respecting CloudKit's 200 operations/request + /// limit by batching operations. The RecordManaging generic extensions handle this + /// automatically. + /// + /// - Parameters: + /// - operations: Array of record operations to execute + /// - recordType: The record type being operated on (for reference/logging) + /// - Throws: CloudKit errors if the batch operations fail + public func executeBatchOperations( + _ operations: [RecordOperation], + recordType: String + ) async throws { + _ = try await self.modifyRecords(operations) + } +} diff --git a/Sources/MistKit/Service/CloudKitService+WriteOperations.swift b/Sources/MistKit/Service/CloudKitService+WriteOperations.swift new file mode 100644 index 00000000..7d433544 --- /dev/null +++ b/Sources/MistKit/Service/CloudKitService+WriteOperations.swift @@ -0,0 +1,151 @@ +// +// CloudKitService+WriteOperations.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation +import OpenAPIRuntime +import OpenAPIURLSession + +@available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) +extension CloudKitService { + /// Modify (create, update, or delete) CloudKit records + /// - Parameter operations: Array of record operations to perform + /// - Returns: Array of RecordInfo for the modified records + /// - Throws: CloudKitError if the operation fails + public func modifyRecords( + _ operations: [RecordOperation] + ) async throws(CloudKitError) -> [RecordInfo] { + do { + // Convert public RecordOperation types to internal OpenAPI types + let apiOperations = operations.map { Components.Schemas.RecordOperation(from: $0) } + + // Call the underlying OpenAPI client + let response = try await client.modifyRecords( + .init( + path: .init( + version: "1", + container: containerIdentifier, + environment: .init(from: environment), + database: .init(from: database) + ), + body: .json( + .init( + operations: apiOperations, + atomic: false // Continue on individual failures + ) + ) + ) + ) + + // Process the response + let modifyResponse: Components.Schemas.ModifyResponse = + try await responseProcessor.processModifyRecordsResponse(response) + + // Convert response records to RecordInfo + return modifyResponse.records?.compactMap { RecordInfo(from: $0) } ?? [] + } catch let cloudKitError as CloudKitError { + throw cloudKitError + } catch { + // Preserve original error context + throw CloudKitError.underlyingError(error) + } + } + + /// Create a single record in CloudKit + /// - Parameters: + /// - recordType: The type of record to create (e.g., "RestoreImage") + /// - recordName: Optional unique record name (if nil, CloudKit will generate one) + /// - fields: Dictionary of field names to FieldValue + /// - Returns: RecordInfo for the created record + /// - Throws: CloudKitError if the operation fails + public func createRecord( + recordType: String, + recordName: String? = nil, + fields: [String: FieldValue] + ) async throws(CloudKitError) -> RecordInfo { + let operation = RecordOperation.create( + recordType: recordType, + recordName: recordName, + fields: fields + ) + + let results = try await modifyRecords([operation]) + guard let record = results.first else { + throw CloudKitError.invalidResponse + } + return record + } + + /// Update a single record in CloudKit + /// - Parameters: + /// - recordType: The type of record to update + /// - recordName: The unique record name + /// - fields: Dictionary of field names to FieldValue + /// - recordChangeTag: Optional change tag for optimistic locking + /// - Returns: RecordInfo for the updated record + /// - Throws: CloudKitError if the operation fails + public func updateRecord( + recordType: String, + recordName: String, + fields: [String: FieldValue], + recordChangeTag: String? = nil + ) async throws(CloudKitError) -> RecordInfo { + let operation = RecordOperation.update( + recordType: recordType, + recordName: recordName, + fields: fields, + recordChangeTag: recordChangeTag + ) + + let results = try await modifyRecords([operation]) + guard let record = results.first else { + throw CloudKitError.invalidResponse + } + return record + } + + /// Delete a single record from CloudKit + /// - Parameters: + /// - recordType: The type of record to delete + /// - recordName: The unique record name + /// - recordChangeTag: Optional change tag for optimistic locking + /// - Throws: CloudKitError if the operation fails + public func deleteRecord( + recordType: String, + recordName: String, + recordChangeTag: String? = nil + ) async throws(CloudKitError) { + let operation = RecordOperation.delete( + recordType: recordType, + recordName: recordName, + recordChangeTag: recordChangeTag + ) + + _ = try await modifyRecords([operation]) + } +} diff --git a/Sources/MistKit/Service/CloudKitService.swift b/Sources/MistKit/Service/CloudKitService.swift index c0090c9a..399095fb 100644 --- a/Sources/MistKit/Service/CloudKitService.swift +++ b/Sources/MistKit/Service/CloudKitService.swift @@ -33,7 +33,7 @@ import OpenAPIURLSession /// Service for interacting with CloudKit Web Services @available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) -public struct CloudKitService { +public struct CloudKitService: Sendable { /// The CloudKit container identifier public let containerIdentifier: String /// The API token for authentication @@ -43,6 +43,9 @@ public struct CloudKitService { /// The CloudKit database (public, private, or shared) public let database: Database + /// Default limit for query operations (1-200, default: 100) + internal let defaultQueryLimit: Int = 100 + internal let mistKitClient: MistKitClient internal let responseProcessor = CloudKitResponseProcessor() internal var client: Client { @@ -63,8 +66,8 @@ extension CloudKitService { .init( version: "1", container: containerIdentifier, - environment: environment.toComponentsEnvironment(), - database: database.toComponentsDatabase() + environment: .init(from: environment), + database: .init(from: database) ) } @@ -77,8 +80,8 @@ extension CloudKitService { .init( version: "1", container: containerIdentifier, - environment: environment.toComponentsEnvironment(), - database: database.toComponentsDatabase() + environment: .init(from: environment), + database: .init(from: database) ) } @@ -91,8 +94,36 @@ extension CloudKitService { .init( version: "1", container: containerIdentifier, - environment: environment.toComponentsEnvironment(), - database: database.toComponentsDatabase() + environment: .init(from: environment), + database: .init(from: database) + ) + } + + /// Create a standard path for modifyRecords requests + /// - Parameter containerIdentifier: The container identifier + /// - Returns: A configured path for the request + internal func createModifyRecordsPath( + containerIdentifier: String + ) -> Operations.modifyRecords.Input.Path { + .init( + version: "1", + container: containerIdentifier, + environment: .init(from: environment), + database: .init(from: database) + ) + } + + /// Create a standard path for lookupRecords requests + /// - Parameter containerIdentifier: The container identifier + /// - Returns: A configured path for the request + internal func createLookupRecordsPath( + containerIdentifier: String + ) -> Operations.lookupRecords.Input.Path { + .init( + version: "1", + container: containerIdentifier, + environment: .init(from: environment), + database: .init(from: database) ) } } diff --git a/Sources/MistKit/Service/CustomFieldValue.CustomFieldValuePayload+FieldValue.swift b/Sources/MistKit/Service/CustomFieldValue.CustomFieldValuePayload+FieldValue.swift new file mode 100644 index 00000000..ca5f241c --- /dev/null +++ b/Sources/MistKit/Service/CustomFieldValue.CustomFieldValuePayload+FieldValue.swift @@ -0,0 +1,124 @@ +// +// CustomFieldValue.CustomFieldValuePayload+FieldValue.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +internal import Foundation + +/// Extension to convert MistKit FieldValue to CustomFieldValue.CustomFieldValuePayload +extension CustomFieldValue.CustomFieldValuePayload { + /// Initialize from MistKit FieldValue (for list nesting) + internal init(_ fieldValue: FieldValue) { + switch fieldValue { + case .string(let value): + self = .stringValue(value) + case .int64(let value): + self = .int64Value(value) + case .double(let value): + self = .doubleValue(value) + case .bytes(let value): + self = .bytesValue(value) + case .date(let value): + self = .dateValue(value.timeIntervalSince1970 * 1_000) + case .location(let location): + self.init(location: location) + case .reference(let reference): + self.init(reference: reference) + case .asset(let asset): + self.init(asset: asset) + case .list(let nestedList): + self = .listValue(nestedList.map { Self(basicFieldValue: $0) }) + } + } + + /// Initialize from Location to payload value + private init(location: FieldValue.Location) { + self = .locationValue( + Components.Schemas.LocationValue( + latitude: location.latitude, + longitude: location.longitude, + horizontalAccuracy: location.horizontalAccuracy, + verticalAccuracy: location.verticalAccuracy, + altitude: location.altitude, + speed: location.speed, + course: location.course, + timestamp: location.timestamp.map { $0.timeIntervalSince1970 * 1_000 } + ) + ) + } + + /// Initialize from Reference to payload value + private init(reference: FieldValue.Reference) { + let action: Components.Schemas.ReferenceValue.actionPayload? + switch reference.action { + case .some(.deleteSelf): + action = .DELETE_SELF + case .some(.none): + action = .NONE + case nil: + action = nil + } + self = .referenceValue( + Components.Schemas.ReferenceValue( + recordName: reference.recordName, + action: action + ) + ) + } + + /// Initialize from Asset to payload value + private init(asset: FieldValue.Asset) { + self = .assetValue( + Components.Schemas.AssetValue( + fileChecksum: asset.fileChecksum, + size: asset.size, + referenceChecksum: asset.referenceChecksum, + wrappingKey: asset.wrappingKey, + receipt: asset.receipt, + downloadURL: asset.downloadURL + ) + ) + } + + /// Initialize from basic FieldValue types to payload (for nested lists) + private init(basicFieldValue: FieldValue) { + switch basicFieldValue { + case .string(let stringValue): + self = .stringValue(stringValue) + case .int64(let intValue): + self = .int64Value(intValue) + case .double(let doubleValue): + self = .doubleValue(doubleValue) + case .bytes(let bytesValue): + self = .bytesValue(bytesValue) + case .date(let dateValue): + self = .dateValue(dateValue.timeIntervalSince1970 * 1_000) + default: + self = .stringValue("unsupported") + } + } +} diff --git a/Sources/MistKit/Service/FieldValue+Components.swift b/Sources/MistKit/Service/FieldValue+Components.swift new file mode 100644 index 00000000..221ee82a --- /dev/null +++ b/Sources/MistKit/Service/FieldValue+Components.swift @@ -0,0 +1,179 @@ +// +// FieldValue+Components.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +internal import Foundation + +/// Extension to convert OpenAPI Components.Schemas.FieldValue to MistKit FieldValue +extension FieldValue { + /// Initialize from OpenAPI Components.Schemas.FieldValue + internal init?(_ fieldData: Components.Schemas.FieldValue) { + self.init(value: fieldData.value, fieldType: fieldData.type) + } + + /// Initialize from field value and type + private init?( + value: CustomFieldValue.CustomFieldValuePayload, + fieldType: CustomFieldValue.FieldTypePayload? + ) { + switch value { + case .stringValue(let stringValue): + self = .string(stringValue) + case .int64Value(let intValue): + self = .int64(intValue) + case .doubleValue(let doubleValue): + if fieldType == .timestamp { + self = .date(Date(timeIntervalSince1970: doubleValue / 1_000)) + } else { + self = .double(doubleValue) + } + case .booleanValue(let boolValue): + self = .int64(boolValue ? 1 : 0) + case .bytesValue(let bytesValue): + self = .bytes(bytesValue) + case .dateValue(let dateValue): + self = .date(Date(timeIntervalSince1970: dateValue / 1_000)) + case .locationValue(let locationValue): + guard let location = Self(locationValue: locationValue) else { return nil } + self = location + case .referenceValue(let referenceValue): + self.init(referenceValue: referenceValue) + case .assetValue(let assetValue): + self.init(assetValue: assetValue) + case .listValue(let listValue): + self.init(listValue: listValue) + } + } + + /// Initialize from location field value + private init?(locationValue: Components.Schemas.LocationValue) { + guard let latitude = locationValue.latitude, + let longitude = locationValue.longitude + else { + return nil + } + + let location = Location( + latitude: latitude, + longitude: longitude, + horizontalAccuracy: locationValue.horizontalAccuracy, + verticalAccuracy: locationValue.verticalAccuracy, + altitude: locationValue.altitude, + speed: locationValue.speed, + course: locationValue.course, + timestamp: locationValue.timestamp.map { Date(timeIntervalSince1970: $0 / 1_000) } + ) + self = .location(location) + } + + /// Initialize from reference field value + private init(referenceValue: Components.Schemas.ReferenceValue) { + let action: Reference.Action? + switch referenceValue.action { + case .DELETE_SELF: + action = .deleteSelf + case .NONE: + action = Reference.Action.none + case nil: + action = nil + } + let reference = Reference( + recordName: referenceValue.recordName ?? "", + action: action + ) + self = .reference(reference) + } + + /// Initialize from asset field value + private init(assetValue: Components.Schemas.AssetValue) { + let asset = Asset( + fileChecksum: assetValue.fileChecksum, + size: assetValue.size, + referenceChecksum: assetValue.referenceChecksum, + wrappingKey: assetValue.wrappingKey, + receipt: assetValue.receipt, + downloadURL: assetValue.downloadURL + ) + self = .asset(asset) + } + + /// Initialize from list field value + private init(listValue: [CustomFieldValue.CustomFieldValuePayload]) { + let convertedList = listValue.compactMap { Self(listItem: $0) } + self = .list(convertedList) + } + + /// Initialize from individual list item + private init?(listItem: CustomFieldValue.CustomFieldValuePayload) { + switch listItem { + case .stringValue(let stringValue): + self = .string(stringValue) + case .int64Value(let intValue): + self = .int64(intValue) + case .doubleValue(let doubleValue): + self = .double(doubleValue) + case .booleanValue(let boolValue): + self = .int64(boolValue ? 1 : 0) + case .bytesValue(let bytesValue): + self = .bytes(bytesValue) + case .dateValue(let dateValue): + self = .date(Date(timeIntervalSince1970: dateValue / 1_000)) + case .locationValue(let locationValue): + guard let location = Self(locationValue: locationValue) else { return nil } + self = location + case .referenceValue(let referenceValue): + self.init(referenceValue: referenceValue) + case .assetValue(let assetValue): + self.init(assetValue: assetValue) + case .listValue(let nestedList): + self.init(nestedListValue: nestedList) + } + } + + /// Initialize from nested list value (simplified for basic types) + private init(nestedListValue: [CustomFieldValue.CustomFieldValuePayload]) { + let convertedNestedList = nestedListValue.compactMap { Self(basicListItem: $0) } + self = .list(convertedNestedList) + } + + /// Initialize from basic list item types only + private init?(basicListItem: CustomFieldValue.CustomFieldValuePayload) { + switch basicListItem { + case .stringValue(let stringValue): + self = .string(stringValue) + case .int64Value(let intValue): + self = .int64(intValue) + case .doubleValue(let doubleValue): + self = .double(doubleValue) + case .bytesValue(let bytesValue): + self = .bytes(bytesValue) + default: + return nil + } + } +} diff --git a/Sources/MistKit/Service/Operations.getCurrentUser.Output.swift b/Sources/MistKit/Service/Operations.getCurrentUser.Output.swift new file mode 100644 index 00000000..8f376041 --- /dev/null +++ b/Sources/MistKit/Service/Operations.getCurrentUser.Output.swift @@ -0,0 +1,82 @@ +// +// Operations.getCurrentUser.Output.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +extension Operations.getCurrentUser.Output: CloudKitResponseType { + var badRequestResponse: Components.Responses.BadRequest? { + if case .badRequest(let response) = self { return response } else { return nil } + } + + var unauthorizedResponse: Components.Responses.Unauthorized? { + if case .unauthorized(let response) = self { return response } else { return nil } + } + + var forbiddenResponse: Components.Responses.Forbidden? { + if case .forbidden(let response) = self { return response } else { return nil } + } + + var notFoundResponse: Components.Responses.NotFound? { + if case .notFound(let response) = self { return response } else { return nil } + } + + var conflictResponse: Components.Responses.Conflict? { + if case .conflict(let response) = self { return response } else { return nil } + } + + var preconditionFailedResponse: Components.Responses.PreconditionFailed? { + if case .preconditionFailed(let response) = self { return response } else { return nil } + } + + var contentTooLargeResponse: Components.Responses.RequestEntityTooLarge? { + if case .contentTooLarge(let response) = self { return response } else { return nil } + } + + var misdirectedRequestResponse: Components.Responses.UnprocessableEntity? { + if case .misdirectedRequest(let response) = self { return response } else { return nil } + } + + var tooManyRequestsResponse: Components.Responses.TooManyRequests? { + if case .tooManyRequests(let response) = self { return response } else { return nil } + } + + var internalServerErrorResponse: Components.Responses.InternalServerError? { + if case .internalServerError(let response) = self { return response } else { return nil } + } + + var serviceUnavailableResponse: Components.Responses.ServiceUnavailable? { + if case .serviceUnavailable(let response) = self { return response } else { return nil } + } + + var isOk: Bool { + if case .ok = self { return true } else { return false } + } + + var undocumentedStatusCode: Int? { + if case .undocumented(let statusCode, _) = self { return statusCode } else { return nil } + } +} diff --git a/Sources/MistKit/Service/Operations.listZones.Output.swift b/Sources/MistKit/Service/Operations.listZones.Output.swift new file mode 100644 index 00000000..9ca189a7 --- /dev/null +++ b/Sources/MistKit/Service/Operations.listZones.Output.swift @@ -0,0 +1,82 @@ +// +// Operations.listZones.Output.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +extension Operations.listZones.Output: CloudKitResponseType { + var badRequestResponse: Components.Responses.BadRequest? { + if case .badRequest(let response) = self { return response } else { return nil } + } + + var unauthorizedResponse: Components.Responses.Unauthorized? { + if case .unauthorized(let response) = self { return response } else { return nil } + } + + var forbiddenResponse: Components.Responses.Forbidden? { + if case .forbidden(let response) = self { return response } else { return nil } + } + + var notFoundResponse: Components.Responses.NotFound? { + if case .notFound(let response) = self { return response } else { return nil } + } + + var conflictResponse: Components.Responses.Conflict? { + if case .conflict(let response) = self { return response } else { return nil } + } + + var preconditionFailedResponse: Components.Responses.PreconditionFailed? { + if case .preconditionFailed(let response) = self { return response } else { return nil } + } + + var contentTooLargeResponse: Components.Responses.RequestEntityTooLarge? { + if case .contentTooLarge(let response) = self { return response } else { return nil } + } + + var misdirectedRequestResponse: Components.Responses.UnprocessableEntity? { + if case .misdirectedRequest(let response) = self { return response } else { return nil } + } + + var tooManyRequestsResponse: Components.Responses.TooManyRequests? { + if case .tooManyRequests(let response) = self { return response } else { return nil } + } + + var internalServerErrorResponse: Components.Responses.InternalServerError? { + if case .internalServerError(let response) = self { return response } else { return nil } + } + + var serviceUnavailableResponse: Components.Responses.ServiceUnavailable? { + if case .serviceUnavailable(let response) = self { return response } else { return nil } + } + + var isOk: Bool { + if case .ok = self { return true } else { return false } + } + + var undocumentedStatusCode: Int? { + if case .undocumented(let statusCode, _) = self { return statusCode } else { return nil } + } +} diff --git a/Sources/MistKit/Service/Operations.lookupRecords.Output.swift b/Sources/MistKit/Service/Operations.lookupRecords.Output.swift new file mode 100644 index 00000000..47778bbd --- /dev/null +++ b/Sources/MistKit/Service/Operations.lookupRecords.Output.swift @@ -0,0 +1,82 @@ +// +// Operations.lookupRecords.Output.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +extension Operations.lookupRecords.Output: CloudKitResponseType { + var badRequestResponse: Components.Responses.BadRequest? { + if case .badRequest(let response) = self { return response } else { return nil } + } + + var unauthorizedResponse: Components.Responses.Unauthorized? { + if case .unauthorized(let response) = self { return response } else { return nil } + } + + var forbiddenResponse: Components.Responses.Forbidden? { + if case .forbidden(let response) = self { return response } else { return nil } + } + + var notFoundResponse: Components.Responses.NotFound? { + if case .notFound(let response) = self { return response } else { return nil } + } + + var conflictResponse: Components.Responses.Conflict? { + if case .conflict(let response) = self { return response } else { return nil } + } + + var preconditionFailedResponse: Components.Responses.PreconditionFailed? { + if case .preconditionFailed(let response) = self { return response } else { return nil } + } + + var contentTooLargeResponse: Components.Responses.RequestEntityTooLarge? { + if case .contentTooLarge(let response) = self { return response } else { return nil } + } + + var misdirectedRequestResponse: Components.Responses.UnprocessableEntity? { + if case .misdirectedRequest(let response) = self { return response } else { return nil } + } + + var tooManyRequestsResponse: Components.Responses.TooManyRequests? { + if case .tooManyRequests(let response) = self { return response } else { return nil } + } + + var internalServerErrorResponse: Components.Responses.InternalServerError? { + if case .internalServerError(let response) = self { return response } else { return nil } + } + + var serviceUnavailableResponse: Components.Responses.ServiceUnavailable? { + if case .serviceUnavailable(let response) = self { return response } else { return nil } + } + + var isOk: Bool { + if case .ok = self { return true } else { return false } + } + + var undocumentedStatusCode: Int? { + if case .undocumented(let statusCode, _) = self { return statusCode } else { return nil } + } +} diff --git a/Sources/MistKit/Service/Operations.modifyRecords.Output.swift b/Sources/MistKit/Service/Operations.modifyRecords.Output.swift new file mode 100644 index 00000000..8bbabc65 --- /dev/null +++ b/Sources/MistKit/Service/Operations.modifyRecords.Output.swift @@ -0,0 +1,82 @@ +// +// Operations.modifyRecords.Output.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +extension Operations.modifyRecords.Output: CloudKitResponseType { + var badRequestResponse: Components.Responses.BadRequest? { + if case .badRequest(let response) = self { return response } else { return nil } + } + + var unauthorizedResponse: Components.Responses.Unauthorized? { + if case .unauthorized(let response) = self { return response } else { return nil } + } + + var forbiddenResponse: Components.Responses.Forbidden? { + if case .forbidden(let response) = self { return response } else { return nil } + } + + var notFoundResponse: Components.Responses.NotFound? { + if case .notFound(let response) = self { return response } else { return nil } + } + + var conflictResponse: Components.Responses.Conflict? { + if case .conflict(let response) = self { return response } else { return nil } + } + + var preconditionFailedResponse: Components.Responses.PreconditionFailed? { + if case .preconditionFailed(let response) = self { return response } else { return nil } + } + + var contentTooLargeResponse: Components.Responses.RequestEntityTooLarge? { + if case .contentTooLarge(let response) = self { return response } else { return nil } + } + + var misdirectedRequestResponse: Components.Responses.UnprocessableEntity? { + if case .misdirectedRequest(let response) = self { return response } else { return nil } + } + + var tooManyRequestsResponse: Components.Responses.TooManyRequests? { + if case .tooManyRequests(let response) = self { return response } else { return nil } + } + + var internalServerErrorResponse: Components.Responses.InternalServerError? { + if case .internalServerError(let response) = self { return response } else { return nil } + } + + var serviceUnavailableResponse: Components.Responses.ServiceUnavailable? { + if case .serviceUnavailable(let response) = self { return response } else { return nil } + } + + var isOk: Bool { + if case .ok = self { return true } else { return false } + } + + var undocumentedStatusCode: Int? { + if case .undocumented(let statusCode, _) = self { return statusCode } else { return nil } + } +} diff --git a/Sources/MistKit/Service/Operations.queryRecords.Output.swift b/Sources/MistKit/Service/Operations.queryRecords.Output.swift new file mode 100644 index 00000000..f56d20bb --- /dev/null +++ b/Sources/MistKit/Service/Operations.queryRecords.Output.swift @@ -0,0 +1,82 @@ +// +// Operations.queryRecords.Output.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +extension Operations.queryRecords.Output: CloudKitResponseType { + var badRequestResponse: Components.Responses.BadRequest? { + if case .badRequest(let response) = self { return response } else { return nil } + } + + var unauthorizedResponse: Components.Responses.Unauthorized? { + if case .unauthorized(let response) = self { return response } else { return nil } + } + + var forbiddenResponse: Components.Responses.Forbidden? { + if case .forbidden(let response) = self { return response } else { return nil } + } + + var notFoundResponse: Components.Responses.NotFound? { + if case .notFound(let response) = self { return response } else { return nil } + } + + var conflictResponse: Components.Responses.Conflict? { + if case .conflict(let response) = self { return response } else { return nil } + } + + var preconditionFailedResponse: Components.Responses.PreconditionFailed? { + if case .preconditionFailed(let response) = self { return response } else { return nil } + } + + var contentTooLargeResponse: Components.Responses.RequestEntityTooLarge? { + if case .contentTooLarge(let response) = self { return response } else { return nil } + } + + var misdirectedRequestResponse: Components.Responses.UnprocessableEntity? { + if case .misdirectedRequest(let response) = self { return response } else { return nil } + } + + var tooManyRequestsResponse: Components.Responses.TooManyRequests? { + if case .tooManyRequests(let response) = self { return response } else { return nil } + } + + var internalServerErrorResponse: Components.Responses.InternalServerError? { + if case .internalServerError(let response) = self { return response } else { return nil } + } + + var serviceUnavailableResponse: Components.Responses.ServiceUnavailable? { + if case .serviceUnavailable(let response) = self { return response } else { return nil } + } + + var isOk: Bool { + if case .ok = self { return true } else { return false } + } + + var undocumentedStatusCode: Int? { + if case .undocumented(let statusCode, _) = self { return statusCode } else { return nil } + } +} diff --git a/Sources/MistKit/Service/RecordFieldConverter.swift b/Sources/MistKit/Service/RecordFieldConverter.swift deleted file mode 100644 index 0968309f..00000000 --- a/Sources/MistKit/Service/RecordFieldConverter.swift +++ /dev/null @@ -1,207 +0,0 @@ -// -// RecordFieldConverter.swift -// MistKit -// -// Created by Leo Dion. -// Copyright © 2025 BrightDigit. -// -// Permission is hereby granted, free of charge, to any person -// obtaining a copy of this software and associated documentation -// files (the “Software”), to deal in the Software without -// restriction, including without limitation the rights to use, -// copy, modify, merge, publish, distribute, sublicense, and/or -// sell copies of the Software, and to permit persons to whom the -// Software is furnished to do so, subject to the following -// conditions: -// -// The above copyright notice and this permission notice shall be -// included in all copies or substantial portions of the Software. -// -// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, -// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES -// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -// OTHER DEALINGS IN THE SOFTWARE. -// - -public import Foundation - -/// Utilities for converting CloudKit field values to FieldValue types -internal enum RecordFieldConverter { - /// Convert a CloudKit field value to FieldValue - internal static func convertToFieldValue(_ fieldData: Components.Schemas.FieldValue) - -> FieldValue? - { - convertFieldValueByType(fieldData.value, fieldType: fieldData.type) - } - - /// Convert field value based on its type - private static func convertFieldValueByType( - _ value: CustomFieldValue.CustomFieldValuePayload, - fieldType: CustomFieldValue.FieldTypePayload? - ) -> FieldValue? { - switch value { - case .stringValue(let stringValue): - return .string(stringValue) - case .int64Value(let intValue): - return .int64(intValue) - case .doubleValue(let doubleValue): - return fieldType == .timestamp - ? .date(Date(timeIntervalSince1970: doubleValue / 1_000)) : .double(doubleValue) - case .booleanValue(let boolValue): - return .boolean(boolValue) - case .bytesValue(let bytesValue): - return .bytes(bytesValue) - default: - return convertComplexFieldValue(value) - } - } - - /// Convert complex field types (date, location, reference, asset, list) - private static func convertComplexFieldValue( - _ value: CustomFieldValue.CustomFieldValuePayload - ) -> FieldValue? { - switch value { - case .dateValue(let dateValue): - return .date(Date(timeIntervalSince1970: dateValue / 1_000)) - case .locationValue(let locationValue): - return convertLocationFieldValue(locationValue) - case .referenceValue(let referenceValue): - return convertReferenceFieldValue(referenceValue) - case .assetValue(let assetValue): - return convertAssetFieldValue(assetValue) - case .listValue(let listValue): - return convertListFieldValue(listValue) - default: - return nil - } - } - - /// Convert location field value - private static func convertLocationFieldValue( - _ locationValue: Components.Schemas.LocationValue - ) -> FieldValue? { - guard let latitude = locationValue.latitude, - let longitude = locationValue.longitude - else { - return nil - } - - let location = FieldValue.Location( - latitude: latitude, - longitude: longitude, - horizontalAccuracy: locationValue.horizontalAccuracy, - verticalAccuracy: locationValue.verticalAccuracy, - altitude: locationValue.altitude, - speed: locationValue.speed, - course: locationValue.course, - timestamp: locationValue.timestamp.map { Date(timeIntervalSince1970: $0 / 1_000) } - ) - return .location(location) - } - - /// Convert reference field value - private static func convertReferenceFieldValue( - _ referenceValue: Components.Schemas.ReferenceValue - ) -> FieldValue? { - let reference = FieldValue.Reference( - recordName: referenceValue.recordName ?? "", - action: referenceValue.action?.rawValue - ) - return .reference(reference) - } - - /// Convert asset field value - private static func convertAssetFieldValue( - _ assetValue: Components.Schemas.AssetValue - ) -> FieldValue? { - let asset = FieldValue.Asset( - fileChecksum: assetValue.fileChecksum, - size: assetValue.size, - referenceChecksum: assetValue.referenceChecksum, - wrappingKey: assetValue.wrappingKey, - receipt: assetValue.receipt, - downloadURL: assetValue.downloadURL - ) - return .asset(asset) - } - - /// Convert list field value - private static func convertListFieldValue( - _ listValue: [CustomFieldValue.CustomFieldValuePayload] - ) -> FieldValue { - let convertedList = listValue.compactMap { convertListItem($0) } - return .list(convertedList) - } - - /// Convert individual list item - private static func convertListItem(_ listItem: CustomFieldValue.CustomFieldValuePayload) - -> FieldValue? - { - switch listItem { - case .stringValue(let stringValue): - return .string(stringValue) - case .int64Value(let intValue): - return .int64(intValue) - case .doubleValue(let doubleValue): - return .double(doubleValue) - case .booleanValue(let boolValue): - return .boolean(boolValue) - case .bytesValue(let bytesValue): - return .bytes(bytesValue) - default: - return convertComplexListItem(listItem) - } - } - - /// Convert complex list item types - private static func convertComplexListItem( - _ listItem: CustomFieldValue.CustomFieldValuePayload - ) -> FieldValue? { - switch listItem { - case .dateValue(let dateValue): - return .date(Date(timeIntervalSince1970: dateValue / 1_000)) - case .locationValue(let locationValue): - return convertLocationFieldValue(locationValue) - case .referenceValue(let referenceValue): - return convertReferenceFieldValue(referenceValue) - case .assetValue(let assetValue): - return convertAssetFieldValue(assetValue) - case .listValue(let nestedList): - return convertNestedListValue(nestedList) - default: - return nil - } - } - - /// Convert nested list value (simplified for basic types) - private static func convertNestedListValue( - _ nestedList: [CustomFieldValue.CustomFieldValuePayload] - ) -> FieldValue { - let convertedNestedList = nestedList.compactMap { convertBasicListItem($0) } - return .list(convertedNestedList) - } - - /// Convert basic list item types only - private static func convertBasicListItem(_ nestedItem: CustomFieldValue.CustomFieldValuePayload) - -> FieldValue? - { - switch nestedItem { - case .stringValue(let stringValue): - return .string(stringValue) - case .int64Value(let intValue): - return .int64(intValue) - case .doubleValue(let doubleValue): - return .double(doubleValue) - case .booleanValue(let boolValue): - return .boolean(boolValue) - case .bytesValue(let bytesValue): - return .bytes(bytesValue) - default: - return nil - } - } -} diff --git a/Sources/MistKit/Service/RecordInfo.swift b/Sources/MistKit/Service/RecordInfo.swift index 58be347c..2c74503c 100644 --- a/Sources/MistKit/Service/RecordInfo.swift +++ b/Sources/MistKit/Service/RecordInfo.swift @@ -27,27 +27,52 @@ // OTHER DEALINGS IN THE SOFTWARE. // -public import Foundation +internal import Foundation /// Record information from CloudKit -public struct RecordInfo: Encodable { +/// +/// ## Error Detection Pattern +/// CloudKit Web Services returns error responses as records with nil `recordType` and `recordName`. +/// This implementation uses "Unknown" as a sentinel value for error responses, which can be detected +/// using the `isError` property. While this is a fragile pattern, it matches CloudKit's API behavior +/// where failed operations in a batch return incomplete record data. +/// +/// Example: +/// ```swift +/// let results = try await service.modifyRecords(operations) +/// let successfulRecords = results.filter { !$0.isError } +/// let failedRecords = results.filter { $0.isError } +/// ``` +public struct RecordInfo: Encodable, Sendable { /// The record name public let recordName: String /// The record type public let recordType: String + /// The record change tag for optimistic locking + public let recordChangeTag: String? /// The record fields public let fields: [String: FieldValue] + /// Indicates whether this RecordInfo represents an error response + /// + /// CloudKit returns error responses with nil recordType/recordName, which are converted + /// to "Unknown" during initialization. Use this property to detect failed operations + /// in batch modify responses. + public var isError: Bool { + recordType == "Unknown" + } + internal init(from record: Components.Schemas.Record) { self.recordName = record.recordName ?? "Unknown" self.recordType = record.recordType ?? "Unknown" + self.recordChangeTag = record.recordChangeTag // Convert fields to FieldValue representation var convertedFields: [String: FieldValue] = [:] if let fieldsPayload = record.fields { for (fieldName, fieldData) in fieldsPayload.additionalProperties { - if let fieldValue = RecordFieldConverter.convertToFieldValue(fieldData) { + if let fieldValue = FieldValue(fieldData) { convertedFields[fieldName] = fieldValue } } @@ -55,4 +80,26 @@ public struct RecordInfo: Encodable { self.fields = convertedFields } + + /// Public initializer for creating RecordInfo instances + /// + /// This initializer is primarily intended for testing and cases where you need to + /// construct RecordInfo manually rather than receiving it from CloudKit responses. + /// + /// - Parameters: + /// - recordName: The unique record name + /// - recordType: The CloudKit record type + /// - recordChangeTag: Optional change tag for optimistic locking + /// - fields: Dictionary of field names to their values + public init( + recordName: String, + recordType: String, + recordChangeTag: String? = nil, + fields: [String: FieldValue] + ) { + self.recordName = recordName + self.recordType = recordType + self.recordChangeTag = recordChangeTag + self.fields = fields + } } diff --git a/Sources/MistKit/Utilities/Array+Chunked.swift b/Sources/MistKit/Utilities/Array+Chunked.swift new file mode 100644 index 00000000..097c32b4 --- /dev/null +++ b/Sources/MistKit/Utilities/Array+Chunked.swift @@ -0,0 +1,44 @@ +// +// Array+Chunked.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the “Software”), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation + +extension Array { + /// Split array into chunks of specified size + /// + /// This utility is used to batch CloudKit operations which have a limit of 200 operations per request. + /// + /// - Parameter size: The maximum size of each chunk + /// - Returns: Array of arrays, each containing at most `size` elements + public func chunked(into size: Int) -> [[Element]] { + stride(from: 0, to: count, by: size).map { + Array(self[$0.. @Sendable () throws -> + private static func generateTestPrivateKeyClosure() + -> @Sendable () throws -> P256.Signing.PrivateKey { { P256.Signing.PrivateKey() } diff --git a/Tests/MistKitTests/Authentication/ServerToServer/ServerToServerAuthManagerTests+ValidationTests.swift b/Tests/MistKitTests/Authentication/ServerToServer/ServerToServerAuthManagerTests+ValidationTests.swift index 8688f06f..86641900 100644 --- a/Tests/MistKitTests/Authentication/ServerToServer/ServerToServerAuthManagerTests+ValidationTests.swift +++ b/Tests/MistKitTests/Authentication/ServerToServer/ServerToServerAuthManagerTests+ValidationTests.swift @@ -5,7 +5,7 @@ import Testing @testable import MistKit extension ServerToServerAuthManagerTests { - @Suite("Server-to-Server Auth Manager Validation") + @Suite("Server-to-Server Auth Manager Validation", .enabled(if: Platform.isCryptoAvailable)) /// Test suite for ServerToServerAuthManager validation functionality internal struct ValidationTests { private static func generateTestPrivateKey() throws -> P256.Signing.PrivateKey { diff --git a/Tests/MistKitTests/AuthenticationMiddleware/APIToken/AuthenticationMiddlewareAPITokenTests.swift b/Tests/MistKitTests/AuthenticationMiddleware/APIToken/AuthenticationMiddlewareAPITokenTests.swift index 38214015..593ad221 100644 --- a/Tests/MistKitTests/AuthenticationMiddleware/APIToken/AuthenticationMiddlewareAPITokenTests.swift +++ b/Tests/MistKitTests/AuthenticationMiddleware/APIToken/AuthenticationMiddlewareAPITokenTests.swift @@ -6,13 +6,13 @@ import Testing @testable import MistKit -@Suite("Authentication Middleware - API Token") +@Suite("Authentication Middleware - API Token", .enabled(if: Platform.isCryptoAvailable)) /// API Token authentication tests for AuthenticationMiddleware internal enum AuthenticationMiddlewareAPITokenTests {} extension AuthenticationMiddlewareAPITokenTests { /// API Token authentication tests - @Suite("API Token Tests") + @Suite("API Token Tests", .enabled(if: Platform.isCryptoAvailable)) internal struct APITokenTests { // MARK: - Test Data Setup diff --git a/Tests/MistKitTests/AuthenticationMiddleware/Error/AuthenticationMiddlewareTests+ErrorTests.swift b/Tests/MistKitTests/AuthenticationMiddleware/Error/AuthenticationMiddlewareTests+ErrorTests.swift index c33756c6..e703898a 100644 --- a/Tests/MistKitTests/AuthenticationMiddleware/Error/AuthenticationMiddlewareTests+ErrorTests.swift +++ b/Tests/MistKitTests/AuthenticationMiddleware/Error/AuthenticationMiddlewareTests+ErrorTests.swift @@ -8,7 +8,7 @@ import Testing extension AuthenticationMiddlewareTests { /// Error handling tests for AuthenticationMiddleware - @Suite("Error Tests") + @Suite("Error Tests", .enabled(if: Platform.isCryptoAvailable)) internal struct ErrorTests { // MARK: - Test Data Setup diff --git a/Tests/MistKitTests/AuthenticationMiddleware/ServerToServer/AuthenticationMiddlewareTests+ServerToServerTests.swift b/Tests/MistKitTests/AuthenticationMiddleware/ServerToServer/AuthenticationMiddlewareTests+ServerToServerTests.swift index e2b3b577..7d5a599d 100644 --- a/Tests/MistKitTests/AuthenticationMiddleware/ServerToServer/AuthenticationMiddlewareTests+ServerToServerTests.swift +++ b/Tests/MistKitTests/AuthenticationMiddleware/ServerToServer/AuthenticationMiddlewareTests+ServerToServerTests.swift @@ -10,7 +10,7 @@ internal enum AuthenticationMiddlewareTests { } extension AuthenticationMiddlewareTests { /// Server-to-server authentication tests for AuthenticationMiddleware - @Suite("Server-to-Server Tests") + @Suite("Server-to-Server Tests", .enabled(if: Platform.isCryptoAvailable)) internal struct ServerToServerTests { // MARK: - Test Data Setup diff --git a/Tests/MistKitTests/Core/CustomFieldValueTests.swift b/Tests/MistKitTests/Core/CustomFieldValueTests.swift new file mode 100644 index 00000000..70f3165b --- /dev/null +++ b/Tests/MistKitTests/Core/CustomFieldValueTests.swift @@ -0,0 +1,287 @@ +import Foundation +import Testing + +@testable import MistKit + +@Suite("CustomFieldValue Tests") +internal struct CustomFieldValueTests { + // MARK: - Initialization Tests + + @Test("CustomFieldValue init with string value and type") + func initWithStringValue() { + let fieldValue = CustomFieldValue( + value: .stringValue("test"), + type: .string + ) + + #expect(fieldValue.type == .string) + if case .stringValue(let value) = fieldValue.value { + #expect(value == "test") + } else { + Issue.record("Expected stringValue") + } + } + + @Test("CustomFieldValue init with int64 value and type") + func initWithInt64Value() { + let fieldValue = CustomFieldValue( + value: .int64Value(42), + type: .int64 + ) + + #expect(fieldValue.type == .int64) + if case .int64Value(let value) = fieldValue.value { + #expect(value == 42) + } else { + Issue.record("Expected int64Value") + } + } + + @Test("CustomFieldValue init with double value and type") + func initWithDoubleValue() { + let fieldValue = CustomFieldValue( + value: .doubleValue(3.14), + type: .double + ) + + #expect(fieldValue.type == .double) + if case .doubleValue(let value) = fieldValue.value { + #expect(value == 3.14) + } else { + Issue.record("Expected doubleValue") + } + } + + @Test("CustomFieldValue init with boolean value and type") + func initWithBooleanValue() { + let fieldValue = CustomFieldValue( + value: .booleanValue(true), + type: .int64 + ) + + #expect(fieldValue.type == .int64) + if case .booleanValue(let value) = fieldValue.value { + #expect(value == true) + } else { + Issue.record("Expected booleanValue") + } + } + + @Test("CustomFieldValue init with date value and type") + func initWithDateValue() { + let timestamp = 1_000_000.0 + let fieldValue = CustomFieldValue( + value: .dateValue(timestamp), + type: .timestamp + ) + + #expect(fieldValue.type == .timestamp) + if case .dateValue(let value) = fieldValue.value { + #expect(value == timestamp) + } else { + Issue.record("Expected dateValue") + } + } + + @Test("CustomFieldValue init with bytes value and type") + func initWithBytesValue() { + let fieldValue = CustomFieldValue( + value: .bytesValue("base64data"), + type: .bytes + ) + + #expect(fieldValue.type == .bytes) + if case .bytesValue(let value) = fieldValue.value { + #expect(value == "base64data") + } else { + Issue.record("Expected bytesValue") + } + } + + @Test("CustomFieldValue init with reference value and type") + func initWithReferenceValue() { + let reference = Components.Schemas.ReferenceValue( + recordName: "test-record", + action: .DELETE_SELF + ) + let fieldValue = CustomFieldValue( + value: .referenceValue(reference), + type: .reference + ) + + #expect(fieldValue.type == .reference) + if case .referenceValue(let value) = fieldValue.value { + #expect(value.recordName == "test-record") + #expect(value.action == .DELETE_SELF) + } else { + Issue.record("Expected referenceValue") + } + } + + @Test("CustomFieldValue init with location value and type") + func initWithLocationValue() { + let location = Components.Schemas.LocationValue( + latitude: 37.7749, + longitude: -122.4194 + ) + let fieldValue = CustomFieldValue( + value: .locationValue(location), + type: .location + ) + + #expect(fieldValue.type == .location) + if case .locationValue(let value) = fieldValue.value { + #expect(value.latitude == 37.7749) + #expect(value.longitude == -122.4194) + } else { + Issue.record("Expected locationValue") + } + } + + @Test("CustomFieldValue init with asset value and type") + func initWithAssetValue() { + let asset = Components.Schemas.AssetValue( + fileChecksum: "checksum123", + size: 1_024 + ) + let fieldValue = CustomFieldValue( + value: .assetValue(asset), + type: .asset + ) + + #expect(fieldValue.type == .asset) + if case .assetValue(let value) = fieldValue.value { + #expect(value.fileChecksum == "checksum123") + #expect(value.size == 1_024) + } else { + Issue.record("Expected assetValue") + } + } + + @Test("CustomFieldValue init with asset value and assetid type") + func initWithAssetValueAndAssetidType() { + let asset = Components.Schemas.AssetValue( + fileChecksum: "checksum456", + size: 2_048 + ) + let fieldValue = CustomFieldValue( + value: .assetValue(asset), + type: .assetid + ) + + #expect(fieldValue.type == .assetid) + if case .assetValue(let value) = fieldValue.value { + #expect(value.fileChecksum == "checksum456") + #expect(value.size == 2_048) + } else { + Issue.record("Expected assetValue") + } + } + + @Test("CustomFieldValue init with list value and type") + func initWithListValue() { + let list: [CustomFieldValue.CustomFieldValuePayload] = [ + .stringValue("one"), + .int64Value(2), + .doubleValue(3.0), + ] + let fieldValue = CustomFieldValue( + value: .listValue(list), + type: .list + ) + + #expect(fieldValue.type == .list) + if case .listValue(let values) = fieldValue.value { + #expect(values.count == 3) + } else { + Issue.record("Expected listValue") + } + } + + @Test("CustomFieldValue init with empty list") + func initWithEmptyList() { + let fieldValue = CustomFieldValue( + value: .listValue([]), + type: .list + ) + + #expect(fieldValue.type == .list) + if case .listValue(let values) = fieldValue.value { + #expect(values.isEmpty) + } else { + Issue.record("Expected listValue") + } + } + + @Test("CustomFieldValue init with nil type") + func initWithNilType() { + let fieldValue = CustomFieldValue( + value: .stringValue("test"), + type: nil + ) + + #expect(fieldValue.type == nil) + if case .stringValue(let value) = fieldValue.value { + #expect(value == "test") + } else { + Issue.record("Expected stringValue") + } + } + + // MARK: - Encoding/Decoding Tests + + @Test("CustomFieldValue encodes and decodes string correctly") + func encodeDecodeString() throws { + let original = CustomFieldValue( + value: .stringValue("test string"), + type: .string + ) + + let encoded = try JSONEncoder().encode(original) + let decoded = try JSONDecoder().decode(CustomFieldValue.self, from: encoded) + + #expect(decoded.type == .string) + if case .stringValue(let value) = decoded.value { + #expect(value == "test string") + } else { + Issue.record("Expected stringValue") + } + } + + @Test("CustomFieldValue encodes and decodes int64 correctly") + func encodeDecodeInt64() throws { + let original = CustomFieldValue( + value: .int64Value(123), + type: .int64 + ) + + let encoded = try JSONEncoder().encode(original) + let decoded = try JSONDecoder().decode(CustomFieldValue.self, from: encoded) + + #expect(decoded.type == .int64) + if case .int64Value(let value) = decoded.value { + #expect(value == 123) + } else { + Issue.record("Expected int64Value") + } + } + + @Test("CustomFieldValue encodes and decodes boolean correctly") + func encodeDecodeBoolean() throws { + let original = CustomFieldValue( + value: .booleanValue(true), + type: .int64 + ) + + let encoded = try JSONEncoder().encode(original) + let decoded = try JSONDecoder().decode(CustomFieldValue.self, from: encoded) + + #expect(decoded.type == .int64) + // Note: Booleans encode as int64 (0 or 1) + if case .int64Value(let value) = decoded.value { + #expect(value == 1) + } else { + Issue.record("Expected int64Value from boolean encoding") + } + } +} diff --git a/Tests/MistKitTests/Core/FieldValue/FieldValueConversionTests.swift b/Tests/MistKitTests/Core/FieldValue/FieldValueConversionTests.swift new file mode 100644 index 00000000..97b1b512 --- /dev/null +++ b/Tests/MistKitTests/Core/FieldValue/FieldValueConversionTests.swift @@ -0,0 +1,460 @@ +import Foundation +import Testing + +@testable import MistKit + +@Suite("FieldValue Conversion Tests", .enabled(if: Platform.isCryptoAvailable)) +internal struct FieldValueConversionTests { + // MARK: - Basic Type Conversions + + @Test("Convert string FieldValue to Components.FieldValue") + func convertString() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let fieldValue = FieldValue.string("test string") + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .string) + if case .stringValue(let value) = components.value { + #expect(value == "test string") + } else { + Issue.record("Expected stringValue") + } + } + + @Test("Convert int64 FieldValue to Components.FieldValue") + func convertInt64() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let fieldValue = FieldValue.int64(42) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .int64) + if case .int64Value(let value) = components.value { + #expect(value == 42) + } else { + Issue.record("Expected int64Value") + } + } + + @Test("Convert double FieldValue to Components.FieldValue") + func convertDouble() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let fieldValue = FieldValue.double(3.14159) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .double) + if case .doubleValue(let value) = components.value { + #expect(value == 3.14159) + } else { + Issue.record("Expected doubleValue") + } + } + + @Test("Convert boolean FieldValue to Components.FieldValue") + func convertBoolean() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let trueValue = FieldValue(booleanValue: true) + let trueComponents = Components.Schemas.FieldValue(from: trueValue) + #expect(trueComponents.type == .int64) + if case .int64Value(let value) = trueComponents.value { + #expect(value == 1) + } else { + Issue.record("Expected int64Value 1 for true") + } + + let falseValue = FieldValue(booleanValue: false) + let falseComponents = Components.Schemas.FieldValue(from: falseValue) + + #expect(falseComponents.type == .int64) + if case .int64Value(let value) = falseComponents.value { + #expect(value == 0) + } else { + Issue.record("Expected int64Value 0 for false") + } + } + + @Test("Convert bytes FieldValue to Components.FieldValue") + func convertBytes() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let fieldValue = FieldValue.bytes("base64encodedstring") + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .bytes) + if case .bytesValue(let value) = components.value { + #expect(value == "base64encodedstring") + } else { + Issue.record("Expected bytesValue") + } + } + + @Test("Convert date FieldValue to Components.FieldValue") + func convertDate() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let date = Date(timeIntervalSince1970: 1_000_000) + let fieldValue = FieldValue.date(date) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .timestamp) + if case .dateValue(let value) = components.value { + #expect(value == date.timeIntervalSince1970 * 1_000) + } else { + Issue.record("Expected dateValue") + } + } + + // MARK: - Complex Type Conversions + + @Test("Convert location FieldValue to Components.FieldValue") + func convertLocation() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let location = FieldValue.Location( + latitude: 37.7749, + longitude: -122.4194, + horizontalAccuracy: 10.0, + verticalAccuracy: 5.0, + altitude: 100.0, + speed: 2.5, + course: 45.0, + timestamp: Date(timeIntervalSince1970: 1_000_000) + ) + let fieldValue = FieldValue.location(location) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .location) + if case .locationValue(let value) = components.value { + #expect(value.latitude == 37.7749) + #expect(value.longitude == -122.4194) + #expect(value.horizontalAccuracy == 10.0) + #expect(value.verticalAccuracy == 5.0) + #expect(value.altitude == 100.0) + #expect(value.speed == 2.5) + #expect(value.course == 45.0) + #expect(value.timestamp != nil) + } else { + Issue.record("Expected locationValue") + } + } + + @Test("Convert location with minimal fields to Components.FieldValue") + func convertMinimalLocation() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let location = FieldValue.Location(latitude: 0.0, longitude: 0.0) + let fieldValue = FieldValue.location(location) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .location) + if case .locationValue(let value) = components.value { + #expect(value.latitude == 0.0) + #expect(value.longitude == 0.0) + #expect(value.horizontalAccuracy == nil) + #expect(value.verticalAccuracy == nil) + #expect(value.altitude == nil) + #expect(value.speed == nil) + #expect(value.course == nil) + #expect(value.timestamp == nil) + } else { + Issue.record("Expected locationValue") + } + } + + @Test("Convert reference FieldValue without action to Components.FieldValue") + func convertReferenceWithoutAction() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let reference = FieldValue.Reference(recordName: "test-record-123") + let fieldValue = FieldValue.reference(reference) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .reference) + if case .referenceValue(let value) = components.value { + #expect(value.recordName == "test-record-123") + #expect(value.action == nil) + } else { + Issue.record("Expected referenceValue") + } + } + + @Test("Convert reference FieldValue with DELETE_SELF action to Components.FieldValue") + func convertReferenceWithDeleteSelfAction() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let reference = FieldValue.Reference(recordName: "test-record-456", action: .deleteSelf) + let fieldValue = FieldValue.reference(reference) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .reference) + if case .referenceValue(let value) = components.value { + #expect(value.recordName == "test-record-456") + #expect(value.action == .DELETE_SELF) + } else { + Issue.record("Expected referenceValue") + } + } + + @Test("Convert reference FieldValue with NONE action to Components.FieldValue") + func convertReferenceWithNoneAction() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let reference = FieldValue.Reference( + recordName: "test-record-789", action: FieldValue.Reference.Action.none) + let fieldValue = FieldValue.reference(reference) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .reference) + if case .referenceValue(let value) = components.value { + #expect(value.recordName == "test-record-789") + #expect(value.action == .NONE) + } else { + Issue.record("Expected referenceValue") + } + } + + @Test("Convert asset FieldValue with all fields to Components.FieldValue") + func convertAssetWithAllFields() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let asset = FieldValue.Asset( + fileChecksum: "abc123", + size: 1_024, + referenceChecksum: "def456", + wrappingKey: "key789", + receipt: "receipt_xyz", + downloadURL: "https://example.com/file.jpg" + ) + let fieldValue = FieldValue.asset(asset) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .asset) + if case .assetValue(let value) = components.value { + #expect(value.fileChecksum == "abc123") + #expect(value.size == 1_024) + #expect(value.referenceChecksum == "def456") + #expect(value.wrappingKey == "key789") + #expect(value.receipt == "receipt_xyz") + #expect(value.downloadURL == "https://example.com/file.jpg") + } else { + Issue.record("Expected assetValue") + } + } + + @Test("Convert asset FieldValue with minimal fields to Components.FieldValue") + func convertAssetWithMinimalFields() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let asset = FieldValue.Asset() + let fieldValue = FieldValue.asset(asset) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .asset) + if case .assetValue(let value) = components.value { + #expect(value.fileChecksum == nil) + #expect(value.size == nil) + #expect(value.referenceChecksum == nil) + #expect(value.wrappingKey == nil) + #expect(value.receipt == nil) + #expect(value.downloadURL == nil) + } else { + Issue.record("Expected assetValue") + } + } + + // MARK: - List Conversions + + @Test("Convert list FieldValue with strings to Components.FieldValue") + func convertListWithStrings() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let list: [FieldValue] = [.string("one"), .string("two"), .string("three")] + let fieldValue = FieldValue.list(list) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .list) + if case .listValue(let values) = components.value { + #expect(values.count == 3) + } else { + Issue.record("Expected listValue") + } + } + + @Test("Convert list FieldValue with numbers to Components.FieldValue") + func convertListWithNumbers() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let list: [FieldValue] = [.int64(1), .int64(2), .int64(3)] + let fieldValue = FieldValue.list(list) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .list) + if case .listValue(let values) = components.value { + #expect(values.count == 3) + } else { + Issue.record("Expected listValue") + } + } + + @Test("Convert list FieldValue with mixed types to Components.FieldValue") + func convertListWithMixedTypes() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let list: [FieldValue] = [ + .string("text"), + .int64(42), + .double(3.14), + FieldValue(booleanValue: true), + ] + let fieldValue = FieldValue.list(list) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .list) + if case .listValue(let values) = components.value { + #expect(values.count == 4) + } else { + Issue.record("Expected listValue") + } + } + + @Test("Convert empty list FieldValue to Components.FieldValue") + func convertEmptyList() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let list: [FieldValue] = [] + let fieldValue = FieldValue.list(list) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .list) + if case .listValue(let values) = components.value { + #expect(values.isEmpty) + } else { + Issue.record("Expected listValue") + } + } + + @Test("Convert nested list FieldValue to Components.FieldValue") + func convertNestedList() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let innerList: [FieldValue] = [.string("a"), .string("b")] + let outerList: [FieldValue] = [.list(innerList), .string("c")] + let fieldValue = FieldValue.list(outerList) + let components = Components.Schemas.FieldValue(from: fieldValue) + + #expect(components.type == .list) + if case .listValue(let values) = components.value { + #expect(values.count == 2) + } else { + Issue.record("Expected listValue") + } + } + + // MARK: - Edge Cases + + @Test("Convert zero values") + func convertZeroValues() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let intZero = FieldValue.int64(0) + let intComponents = Components.Schemas.FieldValue(from: intZero) + #expect(intComponents.type == .int64) + + let doubleZero = FieldValue.double(0.0) + let doubleComponents = Components.Schemas.FieldValue(from: doubleZero) + #expect(doubleComponents.type == .double) + } + + @Test("Convert negative values") + func convertNegativeValues() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let negativeInt = FieldValue.int64(-100) + let intComponents = Components.Schemas.FieldValue(from: negativeInt) + #expect(intComponents.type == .int64) + + let negativeDouble = FieldValue.double(-3.14) + let doubleComponents = Components.Schemas.FieldValue(from: negativeDouble) + #expect(doubleComponents.type == .double) + } + + @Test("Convert large numbers") + func convertLargeNumbers() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let largeInt = FieldValue.int64(Int.max) + let intComponents = Components.Schemas.FieldValue(from: largeInt) + #expect(intComponents.type == .int64) + + let largeDouble = FieldValue.double(Double.greatestFiniteMagnitude) + let doubleComponents = Components.Schemas.FieldValue(from: largeDouble) + #expect(doubleComponents.type == .double) + } + + @Test("Convert empty string") + func convertEmptyString() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let emptyString = FieldValue.string("") + let components = Components.Schemas.FieldValue(from: emptyString) + #expect(components.type == .string) + } + + @Test("Convert string with special characters") + func convertStringWithSpecialCharacters() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FieldValue is not available on this operating system.") + return + } + let specialString = FieldValue.string("Hello\nWorld\t🌍") + let components = Components.Schemas.FieldValue(from: specialString) + #expect(components.type == .string) + } +} diff --git a/Tests/MistKitTests/Core/FieldValue/FieldValueTests.swift b/Tests/MistKitTests/Core/FieldValue/FieldValueTests.swift index 42b4ecc1..99a2e3a6 100644 --- a/Tests/MistKitTests/Core/FieldValue/FieldValueTests.swift +++ b/Tests/MistKitTests/Core/FieldValue/FieldValueTests.swift @@ -27,11 +27,14 @@ internal struct FieldValueTests { #expect(value == .double(3.14)) } - /// Tests FieldValue boolean type creation and equality - @Test("FieldValue boolean type creation and equality") + /// Tests FieldValue boolean helper creation and equality + @Test("FieldValue boolean helper creation and equality") internal func fieldValueBoolean() { - let value = FieldValue.boolean(true) - #expect(value == .boolean(true)) + let trueValue = FieldValue(booleanValue: true) + #expect(trueValue == .int64(1)) + + let falseValue = FieldValue(booleanValue: false) + #expect(falseValue == .int64(0)) } /// Tests FieldValue date type creation and equality diff --git a/Tests/MistKitTests/Helpers/FilterBuilderTests.swift b/Tests/MistKitTests/Helpers/FilterBuilderTests.swift new file mode 100644 index 00000000..79f8e998 --- /dev/null +++ b/Tests/MistKitTests/Helpers/FilterBuilderTests.swift @@ -0,0 +1,255 @@ +import Foundation +import Testing + +@testable import MistKit + +@Suite("FilterBuilder Tests", .enabled(if: Platform.isCryptoAvailable)) +internal struct FilterBuilderTests { + // MARK: - Equality Filters + + @Test("FilterBuilder creates EQUALS filter") + func equalsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.equals("name", .string("John")) + #expect(filter.comparator == .EQUALS) + #expect(filter.fieldName == "name") + #expect(filter.fieldValue?.type == .string) + } + + @Test("FilterBuilder creates NOT_EQUALS filter") + func notEqualsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.notEquals("age", .int64(25)) + #expect(filter.comparator == .NOT_EQUALS) + #expect(filter.fieldName == "age") + #expect(filter.fieldValue?.type == .int64) + } + + // MARK: - Comparison Filters + + @Test("FilterBuilder creates LESS_THAN filter") + func lessThanFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.lessThan("score", .double(100.0)) + #expect(filter.comparator == .LESS_THAN) + #expect(filter.fieldName == "score") + #expect(filter.fieldValue?.type == .double) + } + + @Test("FilterBuilder creates LESS_THAN_OR_EQUALS filter") + func lessThanOrEqualsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.lessThanOrEquals("count", .int64(50)) + #expect(filter.comparator == .LESS_THAN_OR_EQUALS) + #expect(filter.fieldName == "count") + #expect(filter.fieldValue?.type == .int64) + } + + @Test("FilterBuilder creates GREATER_THAN filter") + func greaterThanFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let date = Date() + let filter = FilterBuilder.greaterThan("createdAt", .date(date)) + #expect(filter.comparator == .GREATER_THAN) + #expect(filter.fieldName == "createdAt") + #expect(filter.fieldValue?.type == .timestamp) + } + + @Test("FilterBuilder creates GREATER_THAN_OR_EQUALS filter") + func greaterThanOrEqualsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.greaterThanOrEquals("priority", .int64(3)) + #expect(filter.comparator == .GREATER_THAN_OR_EQUALS) + #expect(filter.fieldName == "priority") + #expect(filter.fieldValue?.type == .int64) + } + + // MARK: - String Filters + + @Test("FilterBuilder creates BEGINS_WITH filter") + func beginsWithFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.beginsWith("title", "Hello") + #expect(filter.comparator == .BEGINS_WITH) + #expect(filter.fieldName == "title") + #expect(filter.fieldValue?.type == .string) + } + + @Test("FilterBuilder creates NOT_BEGINS_WITH filter") + func notBeginsWithFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.notBeginsWith("email", "spam") + #expect(filter.comparator == .NOT_BEGINS_WITH) + #expect(filter.fieldName == "email") + #expect(filter.fieldValue?.type == .string) + } + + @Test("FilterBuilder creates CONTAINS_ALL_TOKENS filter") + func containsAllTokensFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.containsAllTokens("description", "swift cloudkit") + #expect(filter.comparator == .CONTAINS_ALL_TOKENS) + #expect(filter.fieldName == "description") + #expect(filter.fieldValue?.type == .string) + } + + // MARK: - List Filters + + @Test("FilterBuilder creates IN filter") + func inFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let values: [FieldValue] = [.string("active"), .string("pending")] + let filter = FilterBuilder.in("status", values) + #expect(filter.comparator == .IN) + #expect(filter.fieldName == "status") + #expect(filter.fieldValue?.type == .list) + } + + @Test("FilterBuilder creates NOT_IN filter") + func notInFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let values: [FieldValue] = [.string("deleted"), .string("archived")] + let filter = FilterBuilder.notIn("status", values) + #expect(filter.comparator == .NOT_IN) + #expect(filter.fieldName == "status") + #expect(filter.fieldValue?.type == .list) + } + + @Test("FilterBuilder creates IN filter with numbers") + func inFilterWithNumbers() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let values: [FieldValue] = [.int64(1), .int64(2), .int64(3)] + let filter = FilterBuilder.in("categoryId", values) + #expect(filter.comparator == .IN) + #expect(filter.fieldName == "categoryId") + #expect(filter.fieldValue?.type == .list) + } + + // MARK: - List Member Filters + + @Test("FilterBuilder creates LIST_CONTAINS filter") + func listContainsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.listContains("tags", .string("important")) + #expect(filter.comparator == .LIST_CONTAINS) + #expect(filter.fieldName == "tags") + #expect(filter.fieldValue?.type == .string) + } + + @Test("FilterBuilder creates NOT_LIST_CONTAINS filter") + func notListContainsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.notListContains("tags", .string("spam")) + #expect(filter.comparator == .NOT_LIST_CONTAINS) + #expect(filter.fieldName == "tags") + #expect(filter.fieldValue?.type == .string) + } + + @Test("FilterBuilder creates LIST_MEMBER_BEGINS_WITH filter") + func listMemberBeginsWithFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.listMemberBeginsWith("emails", "admin@") + #expect(filter.comparator == .LIST_MEMBER_BEGINS_WITH) + #expect(filter.fieldName == "emails") + #expect(filter.fieldValue?.type == .string) + } + + @Test("FilterBuilder creates NOT_LIST_MEMBER_BEGINS_WITH filter") + func notListMemberBeginsWithFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.notListMemberBeginsWith("domains", "spam") + #expect(filter.comparator == .NOT_LIST_MEMBER_BEGINS_WITH) + #expect(filter.fieldName == "domains") + #expect(filter.fieldValue?.type == .string) + } + + // MARK: - Complex Value Tests + + @Test("FilterBuilder handles boolean values") + func booleanValueFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let filter = FilterBuilder.equals("isActive", FieldValue(booleanValue: true)) + #expect(filter.comparator == .EQUALS) + #expect(filter.fieldName == "isActive") + } + + @Test("FilterBuilder handles reference values") + func referenceValueFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let reference = FieldValue.Reference(recordName: "user-123") + let filter = FilterBuilder.equals("owner", .reference(reference)) + #expect(filter.comparator == .EQUALS) + #expect(filter.fieldName == "owner") + #expect(filter.fieldValue?.type == .reference) + } + + @Test("FilterBuilder handles location values") + func locationValueFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("FilterBuilder is not available on this operating system.") + return + } + let location = FieldValue.Location( + latitude: 37.7749, + longitude: -122.4194 + ) + let filter = FilterBuilder.equals("location", .location(location)) + #expect(filter.comparator == .EQUALS) + #expect(filter.fieldName == "location") + #expect(filter.fieldValue?.type == .location) + } +} diff --git a/Tests/MistKitTests/Helpers/SortDescriptorTests.swift b/Tests/MistKitTests/Helpers/SortDescriptorTests.swift new file mode 100644 index 00000000..c48942a0 --- /dev/null +++ b/Tests/MistKitTests/Helpers/SortDescriptorTests.swift @@ -0,0 +1,81 @@ +import Foundation +import Testing + +@testable import MistKit + +@Suite("SortDescriptor Tests", .enabled(if: Platform.isCryptoAvailable)) +internal struct SortDescriptorTests { + @Test("SortDescriptor creates ascending sort") + func ascendingSort() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("SortDescriptor is not available on this operating system.") + return + } + let sort = SortDescriptor.ascending("name") + #expect(sort.fieldName == "name") + #expect(sort.ascending == true) + } + + @Test("SortDescriptor creates descending sort") + func descendingSort() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("SortDescriptor is not available on this operating system.") + return + } + let sort = SortDescriptor.descending("age") + #expect(sort.fieldName == "age") + #expect(sort.ascending == false) + } + + @Test("SortDescriptor creates sort with ascending true") + func sortAscendingTrue() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("SortDescriptor is not available on this operating system.") + return + } + let sort = SortDescriptor.sort("score", ascending: true) + #expect(sort.fieldName == "score") + #expect(sort.ascending == true) + } + + @Test("SortDescriptor creates sort with ascending false") + func sortAscendingFalse() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("SortDescriptor is not available on this operating system.") + return + } + let sort = SortDescriptor.sort("rating", ascending: false) + #expect(sort.fieldName == "rating") + #expect(sort.ascending == false) + } + + @Test("SortDescriptor defaults to ascending") + func sortDefaultAscending() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("SortDescriptor is not available on this operating system.") + return + } + let sort = SortDescriptor.sort("title") + #expect(sort.fieldName == "title") + #expect(sort.ascending == true) + } + + @Test("SortDescriptor handles various field name formats") + func variousFieldNameFormats() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("SortDescriptor is not available on this operating system.") + return + } + let sort1 = SortDescriptor.ascending("simple") + #expect(sort1.fieldName == "simple") + + let sort2 = SortDescriptor.ascending("camelCase") + #expect(sort2.fieldName == "camelCase") + + let sort3 = SortDescriptor.ascending("snake_case") + #expect(sort3.fieldName == "snake_case") + + let sort4 = SortDescriptor.ascending("with123Numbers") + #expect(sort4.fieldName == "with123Numbers") + } +} diff --git a/Tests/MistKitTests/NetworkError/Recovery/RecoveryTests.swift b/Tests/MistKitTests/NetworkError/Recovery/RecoveryTests.swift index a3c40385..c4280f1f 100644 --- a/Tests/MistKitTests/NetworkError/Recovery/RecoveryTests.swift +++ b/Tests/MistKitTests/NetworkError/Recovery/RecoveryTests.swift @@ -6,12 +6,12 @@ import Testing @testable import MistKit -@Suite("Network Error") +@Suite("Network Error", .enabled(if: Platform.isCryptoAvailable)) internal enum NetworkErrorTests {} extension NetworkErrorTests { /// Network error recovery and retry mechanism tests - @Suite("Recovery Tests") + @Suite("Recovery Tests", .enabled(if: Platform.isCryptoAvailable)) internal struct RecoveryTests { // MARK: - Error Recovery Tests diff --git a/Tests/MistKitTests/NetworkError/Simulation/SimulationTests.swift b/Tests/MistKitTests/NetworkError/Simulation/SimulationTests.swift index 1840ff04..0dd9043f 100644 --- a/Tests/MistKitTests/NetworkError/Simulation/SimulationTests.swift +++ b/Tests/MistKitTests/NetworkError/Simulation/SimulationTests.swift @@ -8,7 +8,7 @@ import Testing extension NetworkErrorTests { /// Network error simulation tests - @Suite("Simulation Tests") + @Suite("Simulation Tests", .enabled(if: Platform.isCryptoAvailable)) internal struct SimulationTests { // MARK: - Network Error Simulation Tests @@ -34,7 +34,7 @@ extension NetworkErrorTests { _ = try await middleware.intercept( originalRequest, body: nil, - baseURL: URL.MistKit.cloudKitAPI, + baseURL: .MistKit.cloudKitAPI, operationID: "test-operation", next: next ) @@ -70,7 +70,7 @@ extension NetworkErrorTests { _ = try await middleware.intercept( originalRequest, body: nil, - baseURL: URL.MistKit.cloudKitAPI, + baseURL: .MistKit.cloudKitAPI, operationID: "test-operation", next: next ) @@ -111,7 +111,7 @@ extension NetworkErrorTests { _ = try await middleware.intercept( originalRequest, body: nil, - baseURL: URL.MistKit.cloudKitAPI, + baseURL: .MistKit.cloudKitAPI, operationID: "test-operation", next: next ) diff --git a/Tests/MistKitTests/NetworkError/Storage/StorageTests.swift b/Tests/MistKitTests/NetworkError/Storage/StorageTests.swift index ef686c17..45b52ce9 100644 --- a/Tests/MistKitTests/NetworkError/Storage/StorageTests.swift +++ b/Tests/MistKitTests/NetworkError/Storage/StorageTests.swift @@ -8,7 +8,7 @@ import Testing extension NetworkErrorTests { /// Network error storage tests - @Suite("Storage Tests") + @Suite("Storage Tests", .enabled(if: Platform.isCryptoAvailable)) internal struct StorageTests { // MARK: - Test Data Setup diff --git a/Tests/MistKitTests/Protocols/CloudKitRecordTests.swift b/Tests/MistKitTests/Protocols/CloudKitRecordTests.swift new file mode 100644 index 00000000..851e311c --- /dev/null +++ b/Tests/MistKitTests/Protocols/CloudKitRecordTests.swift @@ -0,0 +1,306 @@ +// +// CloudKitRecordTests.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the "Software"), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation +import Testing + +@testable import MistKit + +/// Test record conforming to CloudKitRecord for testing purposes +internal struct TestRecord: CloudKitRecord { + static var cloudKitRecordType: String { "TestRecord" } + + var recordName: String + var name: String + var count: Int + var isActive: Bool + var score: Double? + var lastUpdated: Date? + + // swiftlint:disable:next empty_count + var isEmpty: Bool { count == 0 } + + func toCloudKitFields() -> [String: FieldValue] { + var fields: [String: FieldValue] = [ + "name": .string(name), + "count": .int64(count), + "isActive": FieldValue(booleanValue: isActive), + ] + + if let score { + fields["score"] = .double(score) + } + + if let lastUpdated { + fields["lastUpdated"] = .date(lastUpdated) + } + + return fields + } + + static func from(recordInfo: RecordInfo) -> TestRecord? { + guard + let name = recordInfo.fields["name"]?.stringValue, + let isActive = recordInfo.fields["isActive"]?.boolValue + else { + return nil + } + + let count = recordInfo.fields["count"]?.intValue ?? 0 + let score = recordInfo.fields["score"]?.doubleValue + let lastUpdated = recordInfo.fields["lastUpdated"]?.dateValue + + return TestRecord( + recordName: recordInfo.recordName, + name: name, + count: count, + isActive: isActive, + score: score, + lastUpdated: lastUpdated + ) + } + + static func formatForDisplay(_ recordInfo: RecordInfo) -> String { + let name = recordInfo.fields["name"]?.stringValue ?? "Unknown" + let count = recordInfo.fields["count"]?.intValue ?? 0 + return " \(recordInfo.recordName): \(name) (count: \(count))" + } +} + +@Suite("CloudKitRecord Protocol") +/// Tests for CloudKitRecord protocol conformance +internal struct CloudKitRecordTests { + @Test("CloudKitRecord provides correct record type") + internal func recordTypeProperty() { + #expect(TestRecord.cloudKitRecordType == "TestRecord") + } + + @Test("toCloudKitFields converts required fields correctly") + internal func toCloudKitFieldsBasic() { + let record = TestRecord( + recordName: "test-1", + name: "Test Record", + count: 42, + isActive: true, + score: nil, + lastUpdated: nil + ) + + let fields = record.toCloudKitFields() + + #expect(fields["name"]?.stringValue == "Test Record") + #expect(fields["count"]?.intValue == 42) + #expect(fields["isActive"]?.boolValue == true) + #expect(fields["score"] == nil) + #expect(fields["lastUpdated"] == nil) + } + + @Test("toCloudKitFields includes optional fields when present") + internal func toCloudKitFieldsWithOptionals() { + let date = Date() + let record = TestRecord( + recordName: "test-2", + name: "Test Record", + count: 10, + isActive: false, + score: 98.5, + lastUpdated: date + ) + + let fields = record.toCloudKitFields() + + #expect(fields["name"]?.stringValue == "Test Record") + #expect(fields["count"]?.intValue == 10) + #expect(fields["isActive"]?.boolValue == false) + #expect(fields["score"]?.doubleValue == 98.5) + #expect(fields["lastUpdated"]?.dateValue == date) + } + + @Test("from(recordInfo:) parses valid record successfully") + internal func fromRecordInfoSuccess() { + let recordInfo = RecordInfo( + recordName: "test-3", + recordType: "TestRecord", + fields: [ + "name": .string("Parsed Record"), + "count": .int64(25), + "isActive": FieldValue(booleanValue: true), + "score": .double(75.0), + ] + ) + + let record = TestRecord.from(recordInfo: recordInfo) + + #expect(record?.recordName == "test-3") + #expect(record?.name == "Parsed Record") + #expect(record?.count == 25) + #expect(record?.isActive == true) + #expect(record?.score == 75.0) + } + + @Test("from(recordInfo:) handles missing optional fields") + internal func fromRecordInfoWithMissingOptionals() { + let recordInfo = RecordInfo( + recordName: "test-4", + recordType: "TestRecord", + fields: [ + "name": .string("Minimal Record"), + "isActive": FieldValue(booleanValue: false), + ] + ) + + let record = TestRecord.from(recordInfo: recordInfo) + + #expect(record?.recordName == "test-4") + #expect(record?.name == "Minimal Record") + #expect(record?.isEmpty == true) // Default value (count == 0) + #expect(record?.isActive == false) + #expect(record?.score == nil) + #expect(record?.lastUpdated == nil) + } + + @Test("from(recordInfo:) returns nil when required fields missing") + internal func fromRecordInfoMissingRequiredFields() { + let recordInfo = RecordInfo( + recordName: "test-5", + recordType: "TestRecord", + fields: [ + "count": .int64(10) + // Missing required "name" and "isActive" fields + ] + ) + + let record = TestRecord.from(recordInfo: recordInfo) + #expect(record == nil) + } + + @Test("from(recordInfo:) handles legacy int64 boolean encoding") + internal func fromRecordInfoWithLegacyBooleans() { + let recordInfo = RecordInfo( + recordName: "test-6", + recordType: "TestRecord", + fields: [ + "name": .string("Legacy Record"), + "isActive": .int64(1), // Legacy boolean as int64 + ] + ) + + let record = TestRecord.from(recordInfo: recordInfo) + + #expect(record?.isActive == true) + } + + @Test("formatForDisplay generates expected output") + internal func formatForDisplay() { + let recordInfo = RecordInfo( + recordName: "test-7", + recordType: "TestRecord", + fields: [ + "name": .string("Display Record"), + "count": .int64(99), + ] + ) + + let formatted = TestRecord.formatForDisplay(recordInfo) + #expect(formatted.contains("test-7")) + #expect(formatted.contains("Display Record")) + #expect(formatted.contains("99")) + } + + @Test("Round-trip: record -> fields -> record") + internal func roundTripConversion() { + let original = TestRecord( + recordName: "test-8", + name: "Round Trip", + count: 50, + isActive: true, + score: 88.8, + lastUpdated: Date() + ) + + let fields = original.toCloudKitFields() + let recordInfo = RecordInfo( + recordName: original.recordName, + recordType: TestRecord.cloudKitRecordType, + fields: fields + ) + + let reconstructed = TestRecord.from(recordInfo: recordInfo) + + #expect(reconstructed?.recordName == original.recordName) + #expect(reconstructed?.name == original.name) + #expect(reconstructed?.count == original.count) + #expect(reconstructed?.isActive == original.isActive) + #expect(reconstructed?.score == original.score) + } + + @Test("CloudKitRecord conforms to Codable") + internal func codableConformance() throws { + let record = TestRecord( + recordName: "test-9", + name: "Codable Test", + count: 123, + isActive: true, + score: 99.9, + lastUpdated: Date() + ) + + let encoder = JSONEncoder() + let data = try encoder.encode(record) + + let decoder = JSONDecoder() + let decoded = try decoder.decode(TestRecord.self, from: data) + + #expect(decoded.recordName == record.recordName) + #expect(decoded.name == record.name) + #expect(decoded.count == record.count) + #expect(decoded.isActive == record.isActive) + } + + @Test("CloudKitRecord conforms to Sendable") + internal func sendableConformance() async { + let record = TestRecord( + recordName: "test-10", + name: "Sendable Test", + count: 1, + isActive: true, + score: nil, + lastUpdated: nil + ) + + // This test verifies that TestRecord (CloudKitRecord) is Sendable + // by being able to pass it across async/await boundaries + let task = Task { + record.name + } + + let name = await task.value + #expect(name == "Sendable Test") + } +} diff --git a/Tests/MistKitTests/Protocols/FieldValueConvenienceTests.swift b/Tests/MistKitTests/Protocols/FieldValueConvenienceTests.swift new file mode 100644 index 00000000..b1c987bb --- /dev/null +++ b/Tests/MistKitTests/Protocols/FieldValueConvenienceTests.swift @@ -0,0 +1,207 @@ +// +// FieldValueConvenienceTests.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the "Software"), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation +import Testing + +@testable import MistKit + +@Suite("FieldValue Convenience Extensions") +/// Tests for FieldValue convenience property extractors +internal struct FieldValueConvenienceTests { + @Test("stringValue extracts String from .string case") + internal func stringValueExtraction() { + let value = FieldValue.string("test") + #expect(value.stringValue == "test") + } + + @Test("stringValue returns nil for non-string cases") + internal func stringValueReturnsNilForWrongType() { + #expect(FieldValue.int64(42).stringValue == nil) + #expect(FieldValue.double(3.14).stringValue == nil) + #expect(FieldValue(booleanValue: true).stringValue == nil) + } + + @Test("intValue extracts Int from .int64 case") + internal func intValueExtraction() { + let value = FieldValue.int64(42) + #expect(value.intValue == 42) + } + + @Test("intValue returns nil for non-int cases") + internal func intValueReturnsNilForWrongType() { + #expect(FieldValue.string("42").intValue == nil) + #expect(FieldValue.double(42.0).intValue == nil) + } + + @Test("doubleValue extracts Double from .double case") + internal func doubleValueExtraction() { + let value = FieldValue.double(3.14) + #expect(value.doubleValue == 3.14) + } + + @Test("doubleValue returns nil for non-double cases") + internal func doubleValueReturnsNilForWrongType() { + #expect(FieldValue.string("3.14").doubleValue == nil) + #expect(FieldValue.int64(3).doubleValue == nil) + } + + @Test("boolValue extracts Bool from .int64(0) as false") + internal func boolValueFromInt64Zero() { + let value = FieldValue.int64(0) + #expect(value.boolValue == false) + } + + @Test("boolValue extracts Bool from .int64(1) as true") + internal func boolValueFromInt64One() { + let value = FieldValue.int64(1) + #expect(value.boolValue == true) + } + + @Test("boolValue asserts for .int64 with values other than 0 or 1") + internal func boolValueAssertsForInvalidInt64() async { + await confirmation("Assertion handler called", expectedCount: 1) { assertionCalled in + let value2 = FieldValue.int64(2) + let value = value2.boolValue { condition, message in + assertionCalled() + #expect(condition == false) + #expect(message == "Boolean int64 value must be 0 or 1, got 2") + } + #expect(value == true) // Value is still returned (2 != 0) + } + } + + @Test("boolValue returns nil for non-boolean-compatible cases") + internal func boolValueReturnsNilForWrongType() { + #expect(FieldValue.string("true").boolValue == nil) + #expect(FieldValue.double(1.0).boolValue == nil) + } + + @Test("dateValue extracts Date from .date case") + internal func dateValueExtraction() { + let date = Date() + let value = FieldValue.date(date) + #expect(value.dateValue == date) + } + + @Test("dateValue returns nil for non-date cases") + internal func dateValueReturnsNilForWrongType() { + #expect(FieldValue.string("2024-01-01").dateValue == nil) + #expect(FieldValue.int64(1_704_067_200).dateValue == nil) + } + + @Test("bytesValue extracts String from .bytes case") + internal func bytesValueExtraction() { + let base64 = "SGVsbG8gV29ybGQ=" + let value = FieldValue.bytes(base64) + #expect(value.bytesValue == base64) + } + + @Test("bytesValue returns nil for non-bytes cases") + internal func bytesValueReturnsNilForWrongType() { + #expect(FieldValue.string("test").bytesValue == nil) + } + + @Test("locationValue extracts Location from .location case") + internal func locationValueExtraction() { + let location = FieldValue.Location( + latitude: 37.7749, + longitude: -122.4194, + horizontalAccuracy: 10.0 + ) + let value = FieldValue.location(location) + #expect(value.locationValue == location) + } + + @Test("locationValue returns nil for non-location cases") + internal func locationValueReturnsNilForWrongType() { + #expect(FieldValue.string("37.7749,-122.4194").locationValue == nil) + } + + @Test("referenceValue extracts Reference from .reference case") + internal func referenceValueExtraction() { + let reference = FieldValue.Reference(recordName: "test-record") + let value = FieldValue.reference(reference) + #expect(value.referenceValue == reference) + } + + @Test("referenceValue returns nil for non-reference cases") + internal func referenceValueReturnsNilForWrongType() { + #expect(FieldValue.string("test-record").referenceValue == nil) + } + + @Test("assetValue extracts Asset from .asset case") + internal func assetValueExtraction() { + let asset = FieldValue.Asset( + fileChecksum: "abc123", + size: 1_024, + downloadURL: "https://example.com/file" + ) + let value = FieldValue.asset(asset) + #expect(value.assetValue == asset) + } + + @Test("assetValue returns nil for non-asset cases") + internal func assetValueReturnsNilForWrongType() { + #expect(FieldValue.string("asset").assetValue == nil) + } + + @Test("listValue extracts [FieldValue] from .list case") + internal func listValueExtraction() { + let list: [FieldValue] = [.string("one"), .int64(2), .double(3.0)] + let value = FieldValue.list(list) + #expect(value.listValue == list) + } + + @Test("listValue returns nil for non-list cases") + internal func listValueReturnsNilForWrongType() { + #expect(FieldValue.string("[]").listValue == nil) + } + + @Test("Convenience extractors work in field dictionary") + internal func convenienceExtractorsInDictionary() { + let fields: [String: FieldValue] = [ + "name": .string("Test"), + "count": .int64(42), + "enabled": FieldValue(booleanValue: true), + "legacyFlag": .int64(1), + "score": .double(98.5), + ] + + #expect(fields["name"]?.stringValue == "Test") + #expect(fields["count"]?.intValue == 42) + #expect(fields["enabled"]?.boolValue == true) + #expect(fields["legacyFlag"]?.boolValue == true) + #expect(fields["score"]?.doubleValue == 98.5) + + // Type mismatches return nil + #expect(fields["name"]?.intValue == nil) + #expect(fields["count"]?.stringValue == nil) + } +} diff --git a/Tests/MistKitTests/Protocols/RecordManagingTests.swift b/Tests/MistKitTests/Protocols/RecordManagingTests.swift new file mode 100644 index 00000000..1c0d668d --- /dev/null +++ b/Tests/MistKitTests/Protocols/RecordManagingTests.swift @@ -0,0 +1,386 @@ +// +// RecordManagingTests.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the "Software"), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation +import Testing + +@testable import MistKit + +/// Mock implementation of RecordManaging for testing +internal actor MockRecordManagingService: RecordManaging { + var queryCallCount = 0 + var executeCallCount = 0 + var lastExecutedOperations: [RecordOperation] = [] + var batchSizes: [Int] = [] + var recordsToReturn: [RecordInfo] = [] + + func queryRecords(recordType: String) async throws -> [RecordInfo] { + queryCallCount += 1 + return recordsToReturn + } + + func executeBatchOperations(_ operations: [RecordOperation], recordType: String) async throws { + executeCallCount += 1 + batchSizes.append(operations.count) + lastExecutedOperations.append(contentsOf: operations) + } + + func reset() { + queryCallCount = 0 + executeCallCount = 0 + lastExecutedOperations = [] + batchSizes = [] + recordsToReturn = [] + } + + func setRecordsToReturn(_ records: [RecordInfo]) { + recordsToReturn = records + } +} + +@Suite("RecordManaging Protocol") +/// Tests for RecordManaging protocol and its generic extensions +internal struct RecordManagingTests { + @Test("sync() with small batch (<200 records)") + internal func syncSmallBatch() async throws { + let service = MockRecordManagingService() + + let records: [TestRecord] = (0..<50).map { index in + TestRecord( + recordName: "test-\(index)", + name: "Record \(index)", + count: index, + isActive: true, + score: nil, + lastUpdated: nil + ) + } + + try await service.sync(records) + + let executeCount = await service.executeCallCount + let batchSizes = await service.batchSizes + let lastOperations = await service.lastExecutedOperations + + #expect(executeCount == 1) // Should be a single batch + #expect(batchSizes == [50]) + #expect(lastOperations.count == 50) + #expect(lastOperations.first?.recordName == "test-0") + #expect(lastOperations.last?.recordName == "test-49") + } + + @Test("sync() with large batch (>200 records) uses batching") + internal func syncLargeBatchWithBatching() async throws { + let service = MockRecordManagingService() + + // Create 450 records to test batching (should be split into 200, 200, 50) + let records: [TestRecord] = (0..<450).map { index in + TestRecord( + recordName: "test-\(index)", + name: "Record \(index)", + count: index, + isActive: true, + score: nil, + lastUpdated: nil + ) + } + + try await service.sync(records) + + let executeCount = await service.executeCallCount + let batchSizes = await service.batchSizes + let lastOperations = await service.lastExecutedOperations + + #expect(executeCount == 3) // Should be 3 batches + #expect(batchSizes == [200, 200, 50]) + #expect(lastOperations.count == 450) + #expect(lastOperations.first?.recordName == "test-0") + #expect(lastOperations.last?.recordName == "test-449") + } + + @Test("sync() operations have correct structure") + internal func syncOperationsStructure() async throws { + let service = MockRecordManagingService() + + let records = [ + TestRecord( + recordName: "test-1", + name: "First", + count: 10, + isActive: true, + score: 95.5, + lastUpdated: Date() + ) + ] + + try await service.sync(records) + + let operations = await service.lastExecutedOperations + + #expect(operations.count == 1) + + let operation = operations[0] + #expect(operation.recordType == "TestRecord") + #expect(operation.recordName == "test-1") + #expect(operation.operationType == .forceReplace) + + // Verify fields were converted correctly + let fields = operation.fields + #expect(fields["name"]?.stringValue == "First") + #expect(fields["count"]?.intValue == 10) + #expect(fields["isActive"]?.boolValue == true) + #expect(fields["score"]?.doubleValue == 95.5) + } + + @Test("query() returns parsed records") + internal func queryReturnsParsedRecords() async throws { + let service = MockRecordManagingService() + + // Set up mock data + await service.reset() + let mockRecords = [ + RecordInfo( + recordName: "test-1", + recordType: "TestRecord", + fields: [ + "name": .string("First"), + "count": .int64(10), + "isActive": FieldValue(booleanValue: true), + ] + ), + RecordInfo( + recordName: "test-2", + recordType: "TestRecord", + fields: [ + "name": .string("Second"), + "count": .int64(20), + "isActive": FieldValue(booleanValue: false), + ] + ), + ] + await service.setRecordsToReturn(mockRecords) + + let results: [TestRecord] = try await service.query(TestRecord.self) + + #expect(results.count == 2) + #expect(results[0].recordName == "test-1") + #expect(results[0].name == "First") + #expect(results[0].count == 10) + #expect(results[1].recordName == "test-2") + #expect(results[1].name == "Second") + #expect(results[1].count == 20) + + let queryCount = await service.queryCallCount + #expect(queryCount == 1) + } + + @Test("query() with filter applies filtering") + internal func queryWithFilter() async throws { + let service = MockRecordManagingService() + + await service.reset() + let mockRecords = [ + RecordInfo( + recordName: "test-1", + recordType: "TestRecord", + fields: [ + "name": .string("Active"), + "isActive": FieldValue(booleanValue: true), + ] + ), + RecordInfo( + recordName: "test-2", + recordType: "TestRecord", + fields: [ + "name": .string("Inactive"), + "isActive": FieldValue(booleanValue: false), + ] + ), + RecordInfo( + recordName: "test-3", + recordType: "TestRecord", + fields: [ + "name": .string("Also Active"), + "isActive": FieldValue(booleanValue: true), + ] + ), + ] + await service.setRecordsToReturn(mockRecords) + + // Query only active records + let results: [TestRecord] = try await service.query(TestRecord.self) { record in + record.fields["isActive"]?.boolValue == true + } + + #expect(results.count == 2) + #expect(results[0].name == "Active") + #expect(results[1].name == "Also Active") + #expect(results.allSatisfy { $0.isActive }) + } + + @Test("query() filters out nil parse results") + internal func queryFiltersOutInvalidRecords() async throws { + let service = MockRecordManagingService() + + await service.reset() + let mockRecords = [ + RecordInfo( + recordName: "test-1", + recordType: "TestRecord", + fields: [ + "name": .string("Valid"), + "isActive": FieldValue(booleanValue: true), + ] + ), + RecordInfo( + recordName: "test-2", + recordType: "TestRecord", + fields: [ + // Missing required "name" and "isActive" fields + "count": .int64(10) + ] + ), + RecordInfo( + recordName: "test-3", + recordType: "TestRecord", + fields: [ + "name": .string("Also Valid"), + "isActive": FieldValue(booleanValue: false), + ] + ), + ] + await service.setRecordsToReturn(mockRecords) + + let results: [TestRecord] = try await service.query(TestRecord.self) + + // Should only get 2 valid records (test-2 will fail to parse) + #expect(results.count == 2) + #expect(results[0].name == "Valid") + #expect(results[1].name == "Also Valid") + } + + @Test("sync() with empty array doesn't call executeBatchOperations") + internal func syncWithEmptyArray() async throws { + let service = MockRecordManagingService() + + let records: [TestRecord] = [] + try await service.sync(records) + + let executeCount = await service.executeCallCount + #expect(executeCount == 0) + } + + @Test("query() with no results returns empty array") + internal func queryWithNoResults() async throws { + let service = MockRecordManagingService() + + await service.reset() + await service.setRecordsToReturn([]) + + let results: [TestRecord] = try await service.query(TestRecord.self) + + #expect(results.isEmpty) + + let queryCount = await service.queryCallCount + #expect(queryCount == 1) + } + + @Test("list() calls queryRecords and doesn't throw") + internal func listCallsQueryRecords() async throws { + let service = MockRecordManagingService() + + await service.reset() + let mockRecords = [ + RecordInfo( + recordName: "test-1", + recordType: "TestRecord", + fields: [ + "name": .string("First"), + "count": .int64(1), + "isActive": FieldValue(booleanValue: true), + ] + ) + ] + await service.setRecordsToReturn(mockRecords) + + // list() outputs to console, so we just verify it doesn't throw + try await service.list(TestRecord.self) + + let queryCount = await service.queryCallCount + #expect(queryCount == 1) + } + + @Test("Batch size calculation at boundary (exactly 200)") + internal func syncExactly200Records() async throws { + let service = MockRecordManagingService() + + let records: [TestRecord] = (0..<200).map { index in + TestRecord( + recordName: "test-\(index)", + name: "Record \(index)", + count: index, + isActive: true, + score: nil, + lastUpdated: nil + ) + } + + try await service.sync(records) + + let executeCount = await service.executeCallCount + let batchSizes = await service.batchSizes + + #expect(executeCount == 1) // Exactly 200 should be 1 batch + #expect(batchSizes == [200]) + } + + @Test("Batch size calculation at boundary (201 records)") + internal func sync201Records() async throws { + let service = MockRecordManagingService() + + let records: [TestRecord] = (0..<201).map { index in + TestRecord( + recordName: "test-\(index)", + name: "Record \(index)", + count: index, + isActive: true, + score: nil, + lastUpdated: nil + ) + } + + try await service.sync(records) + + let executeCount = await service.executeCallCount + let batchSizes = await service.batchSizes + + #expect(executeCount == 2) // 201 should be 2 batches + #expect(batchSizes == [200, 1]) + } +} diff --git a/Tests/MistKitTests/PublicTypes/QueryFilterTests.swift b/Tests/MistKitTests/PublicTypes/QueryFilterTests.swift new file mode 100644 index 00000000..09f35534 --- /dev/null +++ b/Tests/MistKitTests/PublicTypes/QueryFilterTests.swift @@ -0,0 +1,327 @@ +import Foundation +import Testing + +@testable import MistKit + +@Suite("QueryFilter Tests", .enabled(if: Platform.isCryptoAvailable)) +internal struct QueryFilterTests { + // MARK: - Equality Filters + + @Test("QueryFilter creates equals filter") + func equalsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.equals("name", .string("Alice")) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .EQUALS) + #expect(components.fieldName == "name") + } + + @Test("QueryFilter creates notEquals filter") + func notEqualsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.notEquals("status", .string("deleted")) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .NOT_EQUALS) + #expect(components.fieldName == "status") + } + + // MARK: - Comparison Filters + + @Test("QueryFilter creates lessThan filter") + func lessThanFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.lessThan("age", .int64(30)) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .LESS_THAN) + #expect(components.fieldName == "age") + } + + @Test("QueryFilter creates lessThanOrEquals filter") + func lessThanOrEqualsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.lessThanOrEquals("score", .double(85.5)) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .LESS_THAN_OR_EQUALS) + #expect(components.fieldName == "score") + } + + @Test("QueryFilter creates greaterThan filter") + func greaterThanFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let date = Date() + let filter = QueryFilter.greaterThan("updatedAt", .date(date)) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .GREATER_THAN) + #expect(components.fieldName == "updatedAt") + } + + @Test("QueryFilter creates greaterThanOrEquals filter") + func greaterThanOrEqualsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.greaterThanOrEquals("rating", .int64(4)) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .GREATER_THAN_OR_EQUALS) + #expect(components.fieldName == "rating") + } + + // MARK: - String Filters + + @Test("QueryFilter creates beginsWith filter") + func beginsWithFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.beginsWith("username", "admin") + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .BEGINS_WITH) + #expect(components.fieldName == "username") + } + + @Test("QueryFilter creates notBeginsWith filter") + func notBeginsWithFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.notBeginsWith("email", "test") + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .NOT_BEGINS_WITH) + #expect(components.fieldName == "email") + } + + @Test("QueryFilter creates containsAllTokens filter") + func containsAllTokensFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.containsAllTokens("content", "apple swift ios") + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .CONTAINS_ALL_TOKENS) + #expect(components.fieldName == "content") + } + + // MARK: - List Filters + + @Test("QueryFilter creates in filter with strings") + func inFilterStrings() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let values: [FieldValue] = [.string("draft"), .string("published")] + let filter = QueryFilter.in("state", values) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .IN) + #expect(components.fieldName == "state") + } + + @Test("QueryFilter creates notIn filter with numbers") + func notInFilterNumbers() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let values: [FieldValue] = [.int64(0), .int64(-1)] + let filter = QueryFilter.notIn("errorCode", values) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .NOT_IN) + #expect(components.fieldName == "errorCode") + } + + @Test("QueryFilter creates in filter with empty array") + func inFilterEmptyArray() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let values: [FieldValue] = [] + let filter = QueryFilter.in("tags", values) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .IN) + #expect(components.fieldName == "tags") + } + + // MARK: - List Member Filters + + @Test("QueryFilter creates listContains filter") + func listContainsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.listContains("categories", .string("technology")) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .LIST_CONTAINS) + #expect(components.fieldName == "categories") + } + + @Test("QueryFilter creates notListContains filter") + func notListContainsFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.notListContains("blockedUsers", .string("user-456")) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .NOT_LIST_CONTAINS) + #expect(components.fieldName == "blockedUsers") + } + + @Test("QueryFilter creates listMemberBeginsWith filter") + func listMemberBeginsWithFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.listMemberBeginsWith("urls", "https://") + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .LIST_MEMBER_BEGINS_WITH) + #expect(components.fieldName == "urls") + } + + @Test("QueryFilter creates notListMemberBeginsWith filter") + func notListMemberBeginsWithFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.notListMemberBeginsWith("paths", "/private") + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .NOT_LIST_MEMBER_BEGINS_WITH) + #expect(components.fieldName == "paths") + } + + // MARK: - Complex Field Types + + @Test("QueryFilter handles boolean field values") + func booleanFieldValue() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + + let filter = QueryFilter.equals("isPublished", FieldValue(booleanValue: true)) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .EQUALS) + #expect(components.fieldName == "isPublished") + } + + @Test("QueryFilter handles reference field values") + func referenceFieldValue() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let reference = FieldValue.Reference(recordName: "parent-record-123") + let filter = QueryFilter.equals("parentRef", .reference(reference)) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .EQUALS) + #expect(components.fieldName == "parentRef") + } + + @Test("QueryFilter handles date comparisons") + func dateComparison() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let now = Date() + let filter = QueryFilter.lessThan("expiresAt", .date(now)) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .LESS_THAN) + #expect(components.fieldName == "expiresAt") + } + + @Test("QueryFilter handles double comparisons") + func doubleComparison() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.greaterThanOrEquals("temperature", .double(98.6)) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .GREATER_THAN_OR_EQUALS) + #expect(components.fieldName == "temperature") + } + + // MARK: - Edge Cases + + @Test("QueryFilter handles empty string") + func emptyStringFilter() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.equals("emptyField", .string("")) + let components = Components.Schemas.Filter(from: filter) + #expect(components.fieldName == "emptyField") + } + + @Test("QueryFilter handles special characters in field names") + func specialCharactersInFieldName() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.equals("field_name_123", .string("value")) + let components = Components.Schemas.Filter(from: filter) + #expect(components.fieldName == "field_name_123") + } + + @Test("QueryFilter handles zero values") + func zeroValues() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let intFilter = QueryFilter.equals("count", .int64(0)) + let intComponents = Components.Schemas.Filter(from: intFilter) + #expect(intComponents.fieldName == "count") + + let doubleFilter = QueryFilter.equals("amount", .double(0.0)) + let doubleComponents = Components.Schemas.Filter(from: doubleFilter) + #expect(doubleComponents.fieldName == "amount") + } + + @Test("QueryFilter handles negative values") + func negativeValues() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.lessThan("balance", .int64(-100)) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .LESS_THAN) + } + + @Test("QueryFilter handles large numbers") + func largeNumbers() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QueryFilter is not available on this operating system.") + return + } + let filter = QueryFilter.greaterThan("views", .int64(1_000_000)) + let components = Components.Schemas.Filter(from: filter) + #expect(components.comparator == .GREATER_THAN) + } +} diff --git a/Tests/MistKitTests/PublicTypes/QuerySortTests.swift b/Tests/MistKitTests/PublicTypes/QuerySortTests.swift new file mode 100644 index 00000000..b11d4afc --- /dev/null +++ b/Tests/MistKitTests/PublicTypes/QuerySortTests.swift @@ -0,0 +1,100 @@ +import Foundation +import Testing + +@testable import MistKit + +@Suite("QuerySort Tests", .enabled(if: Platform.isCryptoAvailable)) +internal struct QuerySortTests { + @Test("QuerySort creates ascending sort") + func ascendingSort() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QuerySort is not available on this operating system.") + return + } + let sort = QuerySort.ascending("createdAt") + let components = Components.Schemas.Sort(from: sort) + #expect(components.fieldName == "createdAt") + #expect(components.ascending == true) + } + + @Test("QuerySort creates descending sort") + func descendingSort() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QuerySort is not available on this operating system.") + return + } + let sort = QuerySort.descending("updatedAt") + let components = Components.Schemas.Sort(from: sort) + #expect(components.fieldName == "updatedAt") + #expect(components.ascending == false) + } + + @Test("QuerySort creates sort with explicit ascending direction") + func sortExplicitAscending() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QuerySort is not available on this operating system.") + return + } + let sort = QuerySort.sort("name", ascending: true) + let components = Components.Schemas.Sort(from: sort) + #expect(components.fieldName == "name") + #expect(components.ascending == true) + } + + @Test("QuerySort creates sort with explicit descending direction") + func sortExplicitDescending() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QuerySort is not available on this operating system.") + return + } + let sort = QuerySort.sort("score", ascending: false) + let components = Components.Schemas.Sort(from: sort) + #expect(components.fieldName == "score") + #expect(components.ascending == false) + } + + @Test("QuerySort defaults to ascending when using sort method") + func sortDefaultsToAscending() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QuerySort is not available on this operating system.") + return + } + let sort = QuerySort.sort("title") + let components = Components.Schemas.Sort(from: sort) + #expect(components.fieldName == "title") + #expect(components.ascending == true) + } + + @Test("QuerySort handles field names with underscores") + func sortFieldWithUnderscores() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QuerySort is not available on this operating system.") + return + } + let sort = QuerySort.ascending("user_id") + let components = Components.Schemas.Sort(from: sort) + #expect(components.fieldName == "user_id") + } + + @Test("QuerySort handles field names with numbers") + func sortFieldWithNumbers() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QuerySort is not available on this operating system.") + return + } + let sort = QuerySort.descending("field123") + let components = Components.Schemas.Sort(from: sort) + #expect(components.fieldName == "field123") + } + + @Test("QuerySort handles camelCase field names") + func sortCamelCaseField() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("QuerySort is not available on this operating system.") + return + } + let sort = QuerySort.ascending("createdAtTimestamp") + let components = Components.Schemas.Sort(from: sort) + #expect(components.fieldName == "createdAtTimestamp") + } +} diff --git a/Tests/MistKitTests/Service/CloudKitServiceQueryTests.swift b/Tests/MistKitTests/Service/CloudKitServiceQueryTests.swift new file mode 100644 index 00000000..c95af2db --- /dev/null +++ b/Tests/MistKitTests/Service/CloudKitServiceQueryTests.swift @@ -0,0 +1,337 @@ +// +// CloudKitServiceQueryTests.swift +// MistKit +// +// Created by Leo Dion. +// Copyright © 2025 BrightDigit. +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the "Software"), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +import Foundation +import Testing + +@testable import MistKit + +/// Integration tests for CloudKitService queryRecords() functionality +@Suite("CloudKitService Query Operations", .enabled(if: Platform.isCryptoAvailable)) +struct CloudKitServiceQueryTests { + // MARK: - Configuration Tests + + @Test("queryRecords() uses default limit from configuration") + func queryRecordsUsesDefaultLimit() async throws { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + // This test verifies that the default limit configuration is respected + // In a real integration test, we would mock the HTTP client and verify the request + let service = try CloudKitService( + containerIdentifier: "iCloud.com.example.test", + apiToken: "test-token" + ) + + // Verify service was created successfully + #expect(service.containerIdentifier == "iCloud.com.example.test") + } + + // MARK: - Validation Tests + + @Test("queryRecords() validates empty recordType") + func queryRecordsValidatesEmptyRecordType() async { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + let service = try! CloudKitService( + containerIdentifier: "iCloud.com.example.test", + apiToken: "test-token" + ) + + do { + _ = try await service.queryRecords(recordType: "") + Issue.record("Expected error for empty recordType") + } catch let error as CloudKitError { + // Verify we get the correct validation error + if case .httpErrorWithRawResponse(let statusCode, let response) = error { + #expect(statusCode == 400) + #expect(response.contains("recordType cannot be empty")) + } else { + Issue.record("Expected httpErrorWithRawResponse error") + } + } catch { + Issue.record("Expected CloudKitError, got \(type(of: error))") + } + } + + @Test("queryRecords() validates limit too small", arguments: [-1, 0]) + func queryRecordsValidatesLimitTooSmall(limit: Int) async { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + let service = try! CloudKitService( + containerIdentifier: "iCloud.com.example.test", + apiToken: "test-token" + ) + + do { + _ = try await service.queryRecords(recordType: "Article", limit: limit) + Issue.record("Expected error for limit \(limit)") + } catch let error as CloudKitError { + if case .httpErrorWithRawResponse(let statusCode, let response) = error { + #expect(statusCode == 400) + #expect(response.contains("limit must be between 1 and 200")) + } else { + Issue.record("Expected httpErrorWithRawResponse error") + } + } catch { + Issue.record("Expected CloudKitError") + } + } + + @Test("queryRecords() validates limit too large", arguments: [201, 300, 1_000]) + func queryRecordsValidatesLimitTooLarge(limit: Int) async { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + let service = try! CloudKitService( + containerIdentifier: "iCloud.com.example.test", + apiToken: "test-token" + ) + + do { + _ = try await service.queryRecords(recordType: "Article", limit: limit) + Issue.record("Expected error for limit \(limit)") + } catch let error as CloudKitError { + if case .httpErrorWithRawResponse(let statusCode, let response) = error { + #expect(statusCode == 400) + #expect(response.contains("limit must be between 1 and 200")) + } else { + Issue.record("Expected httpErrorWithRawResponse error") + } + } catch { + Issue.record("Expected CloudKitError") + } + } + + @Test("queryRecords() accepts valid limit range", arguments: [1, 50, 100, 200]) + func queryRecordsAcceptsValidLimitRange(limit: Int) async { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + let service = try! CloudKitService( + containerIdentifier: "iCloud.com.example.test", + apiToken: "test-token" + ) + + // This test verifies validation passes - actual API call will fail without real credentials + // but we're testing that validation doesn't throw + do { + _ = try await service.queryRecords(recordType: "Article", limit: limit) + Issue.record("Expected network error since we don't have real credentials") + } catch let error as CloudKitError { + // We expect a network/auth error, not a validation error + // Validation errors have status code 400 + if case .httpErrorWithRawResponse(let statusCode, _) = error { + #expect(statusCode != 400, "Validation should not fail for limit \(limit)") + } + // Other CloudKit errors are expected (auth, network, etc.) + } catch { + // Network errors are expected + } + } + + // MARK: - Filter Conversion Tests + + @Test("QueryFilter converts to Components.Schemas format correctly") + func queryFilterConvertsToComponentsFormat() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + // Test equality filter + let equalFilter = QueryFilter.equals("title", .string("Test")) + let componentsFilter = Components.Schemas.Filter(from: equalFilter) + + #expect(componentsFilter.fieldName == "title") + #expect(componentsFilter.comparator == .EQUALS) + + // Test comparison filter + let greaterThanFilter = QueryFilter.greaterThan("count", .int64(10)) + let componentsGT = Components.Schemas.Filter(from: greaterThanFilter) + + #expect(componentsGT.fieldName == "count") + #expect(componentsGT.comparator == .GREATER_THAN) + } + + @Test("QueryFilter handles all field value types") + func queryFilterHandlesAllFieldValueTypes() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + let testCases: [(FieldValue, String)] = [ + (.string("test"), "string"), + (.int64(42), "int64"), + (.double(3.14), "double"), + (FieldValue(booleanValue: true), "boolean"), + (.date(Date()), "date"), + ] + + for (fieldValue, typeName) in testCases { + let filter = QueryFilter.equals("field", fieldValue) + let components = Components.Schemas.Filter(from: filter) + + #expect(components.fieldName == "field") + #expect(components.comparator == .EQUALS, "Failed for \(typeName)") + } + } + + // MARK: - Sort Conversion Tests + + @Test("QuerySort converts to Components.Schemas format correctly") + func querySortConvertsToComponentsFormat() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + // Test ascending sort + let ascendingSort = QuerySort.ascending("createdAt") + let componentsAsc = Components.Schemas.Sort(from: ascendingSort) + + #expect(componentsAsc.fieldName == "createdAt") + #expect(componentsAsc.ascending == true) + + // Test descending sort + let descendingSort = QuerySort.descending("modifiedAt") + let componentsDesc = Components.Schemas.Sort(from: descendingSort) + + #expect(componentsDesc.fieldName == "modifiedAt") + #expect(componentsDesc.ascending == false) + } + + @Test("QuerySort handles various field name formats") + func querySortHandlesVariousFieldNameFormats() { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + let fieldNames = [ + "simpleField", + "camelCaseField", + "snake_case_field", + "field123", + "field_with_multiple_underscores", + ] + + for fieldName in fieldNames { + let sort = QuerySort.ascending(fieldName) + let components = Components.Schemas.Sort(from: sort) + + #expect(components.fieldName == fieldName, "Failed for field name: \(fieldName)") + } + } + + // MARK: - Edge Cases + + @Test("queryRecords() handles nil limit parameter") + func queryRecordsHandlesNilLimitParameter() async { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + let service = try! CloudKitService( + containerIdentifier: "iCloud.com.example.test", + apiToken: "test-token" + ) + + // With nil limit, should use defaultQueryLimit (100) + // This test verifies the parameter handling - actual call will fail without auth + do { + _ = try await service.queryRecords(recordType: "Article", limit: nil as Int?) + } catch let error as CloudKitError { + // Validation should pass (no 400 error) + if case .httpErrorWithRawResponse(let statusCode, _) = error { + #expect(statusCode != 400, "Should not fail validation with nil limit") + } + } catch { + // Other errors are expected + } + } + + @Test("queryRecords() handles empty filters array") + func queryRecordsHandlesEmptyFiltersArray() async { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + let service = try! CloudKitService( + containerIdentifier: "iCloud.com.example.test", + apiToken: "test-token" + ) + + do { + _ = try await service.queryRecords( + recordType: "Article", + filters: [], + limit: 10 + ) + } catch let error as CloudKitError { + // Should not fail validation + if case .httpErrorWithRawResponse(let statusCode, _) = error { + #expect(statusCode != 400, "Should not fail validation with empty filters") + } + } catch { + // Other errors expected + } + } + + @Test("queryRecords() handles empty sorts array") + func queryRecordsHandlesEmptySortsArray() async { + guard #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) else { + Issue.record("CloudKitService is not available on this operating system.") + return + } + let service = try! CloudKitService( + containerIdentifier: "iCloud.com.example.test", + apiToken: "test-token" + ) + + do { + _ = try await service.queryRecords( + recordType: "Article", + sortBy: [], + limit: 10 + ) + } catch let error as CloudKitError { + // Should not fail validation + if case .httpErrorWithRawResponse(let statusCode, _) = error { + #expect(statusCode != 400, "Should not fail validation with empty sorts") + } + } catch { + // Other errors expected + } + } +} diff --git a/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshBasicTests.swift b/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshBasicTests.swift index a724871d..8da9360c 100644 --- a/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshBasicTests.swift +++ b/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshBasicTests.swift @@ -21,7 +21,8 @@ internal struct ConcurrentTokenRefreshBasicTests { } /// Creates a standard next handler that returns success - private func createSuccessNextHandler() -> @Sendable (HTTPRequest, HTTPBody?, URL) async throws + private func createSuccessNextHandler() + -> @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?) { { _, _, _ in (HTTPResponse(status: .ok), nil) } @@ -32,9 +33,10 @@ internal struct ConcurrentTokenRefreshBasicTests { middleware: AuthenticationMiddleware, request: HTTPRequest, baseURL: URL, - next: @escaping @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> ( - HTTPResponse, HTTPBody? - ), + next: + @escaping @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> ( + HTTPResponse, HTTPBody? + ), count: Int ) async -> [Bool] { let tasks = (1...count).map { _ in @@ -130,9 +132,10 @@ internal struct ConcurrentTokenRefreshBasicTests { middlewares: [AuthenticationMiddleware], request: HTTPRequest, baseURL: URL, - next: @escaping @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> ( - HTTPResponse, HTTPBody? - ) + next: + @escaping @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> ( + HTTPResponse, HTTPBody? + ) ) async -> [Bool] { let tasks = middlewares.map { middleware in Task { diff --git a/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshErrorTests.swift b/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshErrorTests.swift index 06ec59ed..5f39470f 100644 --- a/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshErrorTests.swift +++ b/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshErrorTests.swift @@ -21,7 +21,8 @@ internal struct ConcurrentTokenRefreshErrorTests { } /// Creates a standard next handler that returns success - private func createSuccessNextHandler() -> @Sendable (HTTPRequest, HTTPBody?, URL) async throws + private func createSuccessNextHandler() + -> @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?) { { _, _, _ in (HTTPResponse(status: .ok), nil) } @@ -32,9 +33,10 @@ internal struct ConcurrentTokenRefreshErrorTests { middleware: AuthenticationMiddleware, request: HTTPRequest, baseURL: URL, - next: @escaping @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> ( - HTTPResponse, HTTPBody? - ), + next: + @escaping @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> ( + HTTPResponse, HTTPBody? + ), count: Int ) async -> [Bool] { let tasks = (1...count).map { _ in diff --git a/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshPerformanceTests.swift b/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshPerformanceTests.swift index 44923626..19089934 100644 --- a/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshPerformanceTests.swift +++ b/Tests/MistKitTests/Storage/Concurrent/ConcurrentTokenRefresh/ConcurrentTokenRefreshPerformanceTests.swift @@ -21,7 +21,8 @@ internal struct ConcurrentTokenRefreshPerformanceTests { } /// Creates a standard next handler that returns success - private func createSuccessNextHandler() -> @Sendable (HTTPRequest, HTTPBody?, URL) async throws + private func createSuccessNextHandler() + -> @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> (HTTPResponse, HTTPBody?) { { _, _, _ in (HTTPResponse(status: .ok), nil) } @@ -32,9 +33,10 @@ internal struct ConcurrentTokenRefreshPerformanceTests { middleware: AuthenticationMiddleware, request: HTTPRequest, baseURL: URL, - next: @escaping @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> ( - HTTPResponse, HTTPBody? - ), + next: + @escaping @Sendable (HTTPRequest, HTTPBody?, URL) async throws -> ( + HTTPResponse, HTTPBody? + ), count: Int ) async -> [Bool] { let tasks = (1...count).map { _ in diff --git a/openapi.yaml b/openapi.yaml index 5142c415..ba1b74ac 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -23,7 +23,7 @@ info: name: Apple Developer Support url: https://developer.apple.com/support/ servers: - url: https://api.apple-cloudkit.com + - url: https://api.apple-cloudkit.com description: CloudKit Web Services API security: @@ -848,7 +848,6 @@ components: - $ref: '#/components/schemas/StringValue' - $ref: '#/components/schemas/Int64Value' - $ref: '#/components/schemas/DoubleValue' - - $ref: '#/components/schemas/BooleanValue' - $ref: '#/components/schemas/BytesValue' - $ref: '#/components/schemas/DateValue' - $ref: '#/components/schemas/LocationValue' @@ -874,10 +873,6 @@ components: format: double description: A double-precision floating point value - BooleanValue: - type: boolean - description: A true or false value - BytesValue: type: string description: Base64-encoded string representing binary data @@ -933,7 +928,7 @@ components: description: The record name being referenced action: type: string - enum: [DELETE_SELF] + enum: [NONE, DELETE_SELF] description: Action to perform on the referenced record AssetValue: @@ -969,7 +964,6 @@ components: - $ref: '#/components/schemas/StringValue' - $ref: '#/components/schemas/Int64Value' - $ref: '#/components/schemas/DoubleValue' - - $ref: '#/components/schemas/BooleanValue' - $ref: '#/components/schemas/BytesValue' - $ref: '#/components/schemas/DateValue' - $ref: '#/components/schemas/LocationValue' diff --git a/project.yml b/project.yml index 34fbfe2e..63e3ade2 100644 --- a/project.yml +++ b/project.yml @@ -4,8 +4,10 @@ settings: packages: MistKit: path: . - MistKitExamples: - path: Examples + Bushel: + path: Examples/Bushel + Celestra: + path: Examples/Celestra aggregateTargets: Lint: buildScripts: