Skip to main content

Crate cloudkit

Crate cloudkit 

Source
Expand description

§cloudkit

Safe Rust bindings for Apple’s CloudKit framework on macOS.

Status: v0.3.0 keeps the fully audited CloudKit surface from v0.2.1 and adds an optional async feature with Future-based container, database, and selected operation wrappers backed by the Swift bridge. See COVERAGE.md and COVERAGE_AUDIT.md for the audited SDK/header-to-source map.

§Quick start

use cloudkit::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut record = CKRecord::new("Task")?;
    record.set_object("title", "Ship v0.3.0");
    record.set_object("done", false);

    let share = CKShare::new_root_record(&record)?;
    println!(
        "record_type={} share_record_type={} participants={}",
        record.record_type(),
        share.share_record().record_type(),
        share.participants().len()
    );
    Ok(())
}

§Highlights

  • CKContainer default/custom containers, account status, user-record lookup, user-identity discovery, and share-participant lookup
  • CKDatabase record CRUD, first-batch query helpers, fetched query results, record-zone helpers, and subscription helpers
  • Optional async feature with executor-agnostic Future wrappers for container status/identity calls, database queries/record access, and selected record/database-change operations
  • Value-layer Rust wrappers for CKRecord, CKRecordID, CKRecordZone, CKAsset, CKReference, CKNotificationInfo, CKNotification*, CKServerChangeToken, CKUserIdentity, CKShare, CKShareMetadata, and CKSyncEngine
  • Operation builders for generic CKOperation* configuration plus record-zone, subscription, share metadata / acceptance / access-request, web-auth token, and existing record/query/database-change operations
  • Exported CloudKit constants for container, error, query, record, zone, and share keys alongside expanded sharing-option helpers and system-sharing observers
  • Headless numbered examples 01–15 plus per-area integration tests and tests/expanded_surface_tests.rs

§Validation

The v0.3.0 bridge is validated with:

cargo clippy --all-targets -- -D warnings
cargo test
cargo test --all-features
for ex in examples/*.rs; do cargo run --example "$(basename "$ex" .rs)"; done

§Entitlements / caveats

CloudKit requires an entitled app plus an iCloud account for most server-backed operations. Unsigned CLI binaries commonly hit CKErrorMissingEntitlement, CKErrorBadContainer, or CKErrorNotAuthenticated. When CKContainer::default() cannot be resolved because the current process has no iCloud container entitlement, the crate surfaces a bridge error instead of letting CloudKit raise an Objective-C exception. Headless tests and examples can therefore report entitlement/account limitations gracefully instead of crashing.

§Examples

Run the defensive framework smoke test with:

cargo run --example 01_account_status_smoke

Other numbered examples cover the expanded logical areas:

  • 02_database_zones_and_subscriptions
  • 03_record_value_roundtrip
  • 04_record_id_construction
  • 05_zone_construction
  • 06_subscription_builders
  • 07_operation_builders
  • 08_share_local_construction
  • 09_notification_info_builder
  • 10_query_builder
  • 11_fetched_results_smoke
  • 12_reference_utility
  • 13_server_change_token_bytes
  • 14_asset_file_url
  • 15_user_identity_lookup

§License

Licensed under either Apache-2.0 or MIT at your option.

Re-exports§

pub use asset::CKAsset;
pub use container::AccountStatus;
pub use container::CKApplicationPermissionStatus;
pub use container::CKApplicationPermissions;
pub use container::CKContainer;
pub use database::CKDatabase;
pub use database::CKDatabaseScope;
pub use error::CloudKitError;
pub use error::CloudKitErrorCode;
pub use error::CLOUDKIT_BRIDGE_ERROR_DOMAIN;
pub use error::CLOUDKIT_ERROR_DOMAIN;
pub use fetched_results::CKDeletedRecord;
pub use fetched_results::CKFetchDatabaseChangesResult;
pub use fetched_results::CKFetchRecordZoneChangesResult;
pub use fetched_results::CKFetchRecordZoneResult;
pub use fetched_results::CKFetchRecordsResult;
pub use fetched_results::CKFetchedQueryResults;
pub use fetched_results::CKQueryCursor;
pub use fetched_results::CKRecordResult;
pub use notification_info::CKNotificationInfo;
pub use query::CKLocationSortDescriptor;
pub use query::CKQuery;
pub use query::SortDescriptor;
pub use record::CKRecord;
pub use record::CKRecordKeyValueSetting;
pub use record::RecordValue;
pub use record_id::CKRecordID;
pub use reference_utility::CKReference;
pub use reference_utility::CKReferenceAction;
pub use server_change_token::CKServerChangeToken;
pub use subscription::CKAnySubscription;
pub use subscription::CKDatabaseSubscription;
pub use subscription::CKQuerySubscription;
pub use subscription::CKRecordZoneSubscription;
pub use subscription::CKSubscription;
pub use subscription::CKSubscriptionType;
pub use subscription::QuerySubscriptionOptions;
pub use user_identity::CKPersonNameComponents;
pub use user_identity::CKUserIdentity;
pub use user_identity::CKUserIdentityLookupInfo;
pub use zone::CKRecordZone;
pub use zone::CKRecordZoneCapabilities;
pub use zone::CKRecordZoneEncryptionScope;
pub use zone::CKRecordZoneID;
pub use constants::*;
pub use notification::*;
pub use operation::*;
pub use share::*;
pub use sync_engine::*;

Modules§

asset
Exposes CloudKit asset wrappers.
async_apiasync
Exposes async CloudKit wrappers. Async API for cloudkit
constants
Exposes CloudKit framework constants.
container
Exposes CloudKit container wrappers.
database
Exposes CloudKit database wrappers.
error
Exposes CloudKit error wrappers.
fetched_results
Exposes CloudKit fetched-result wrappers.
ffi
Exposes the low-level CloudKit bridge module.
notification
Exposes CloudKit notification wrappers.
notification_info
Exposes CloudKit notification-info wrappers.
operation
Exposes CloudKit operation wrappers.
prelude
Common imports.
query
Exposes CloudKit query wrappers.
record
Exposes CloudKit record wrappers.
record_id
Exposes CloudKit record ID wrappers.
reference_utility
Exposes CloudKit reference wrappers.
server_change_token
Exposes CloudKit server-change-token wrappers.
share
Exposes CloudKit sharing wrappers.
subscription
Exposes CloudKit subscription wrappers.
sync_engine
Exposes CloudKit sync-engine wrappers.
user_identity
Exposes CloudKit user-identity wrappers.
zone
Exposes CloudKit record-zone wrappers.