Remote

Objective-C: also in Python · Node · Go · Rust · Swift · Dart · Java and Kotlin · .NET · C++

Reusable synchronization state for one remote.

A remote is the shared database copy described in Concepts. You own the PLKRemote and can share it among databases and snapshots. Closing a database or snapshot never closes its remote. The remote refuses to close while any open database or snapshot uses it.

At a glance

Construct

• remoteFromDirectory:options:error: – Open a directory remote rooted at path.
• remoteFromStorage:options:error: – Wrap a caller-supplied storage adapter as a remote.

Inspect

• statusWithError: – Return a typed PLKRemoteStatus snapshot of remote-owned state only.

Maintain storage

• collect:error: Advanced – Collect retired revisions under an explicit retention policy and return a PLKCollectionReport.
• recoverAbandonedCollectionWithError: Advanced – Reopen a remote that an interrupted collection left cleaning.

Close

• closeWithError: – Close the remote.

Construct

remoteFromDirectory:options:error:

Open a directory remote rooted at path.

The directory is created on first use. Default options use readConcurrency 32 and bounded retention.

remoteFromStorage:options:error:

Wrap a caller-supplied storage adapter as a remote.

storage implements the bucket storage protocol beneath the storage entry points. This is an integrator API. The S3 adapter is one implementation. Closing the remote never closes the adapter’s underlying transport for you.

Integrator API. This member exists for code that supplies its own storage transport. Application code reaches a bucket through [PLKStorage remoteFromS3Bucket:inNamespace:region:endpoint:forcePathStyle:accessKeyID:secretAccessKey:sessionToken:options:error:], [PLKStorage remoteFromGCSBucket:inNamespace:endpoint:serviceAccount:options:error:] and [PLKStorage remoteFromAzureAccount:container:inNamespace:endpoint:accountKey:options:error:].

Inspect

statusWithError:

Return a typed PLKRemoteStatus snapshot of remote-owned state only.

Maintain storage

collect:error:

Advanced

Collect retired revisions under an explicit retention policy and return a PLKCollectionReport.

Collection starts only above the retained target. It never touches the current head. Concepts explains retention and collection.

recoverAbandonedCollectionWithError:

Advanced

Reopen a remote that an interrupted collection left cleaning.

Collection is interrupted if any of these occurs:

• Its process stops.
• It cannot learn whether its opening head swap took effect.
• Storage fails both a sweep step and its closing head swap.

Until the head reopens, every synchronization and new device initialization fails with temporarily_unavailable.

Active collectors

Call PLKRemote.recoverAbandonedCollectionWithError: only after every collector on this remote has stopped. A collector that still deletes objects can remove data that a new publication needs after recovery reopens the remote.

The next collection completes the sweep. If the head is open, this changes nothing and reports aborted. If there is no head, this changes nothing. It never retires a revision.

This operation is separate from collect:error:. An accidental flag therefore cannot request recovery.

Close

closeWithError:

Close the remote. Repeated calls have the same effect.

closeWithError: fails with invalid_state while an open database or snapshot uses this remote. Refusal changes no state.