Remote

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

Reusable synchronization state for one remote.

A remote is the shared database copy described in Concepts. You own the Remote 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

• from_directory(): Open a directory remote rooted at path.
• from_directory_with_options(): Open a directory remote with the supplied options.
• from_storage(): Wrap a caller-supplied storage adapter as a remote.
• from_storage_with_options(): Construct a remote from a storage adapter with the supplied options.

Inspect

• status(): Return a typed RemoteStatus snapshot of remote-owned state only.

Maintain storage

• collect() Advanced: Collect retired revisions under an explicit retention policy and return a CollectionReport.
• recover_abandoned_collection() Advanced: Reopen a remote that an interrupted collection left cleaning.

Close

• close(): Close the remote.

Construct

from_directory

Open a directory remote rooted at path.

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

from_directory_with_options

Open a directory remote with the supplied options. from_directory_with_options is from_directory with explicit options.

from_storage

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 potluckdb::storage::from_s3, potluckdb::storage::from_gcs and potluckdb::storage::from_azure.

from_storage_with_options

Construct a remote from a storage adapter with the supplied options. from_storage_with_options is from_storage with explicit options.

Inspect

status

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

Maintain storage

collect

Advanced

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

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

recover_abandoned_collection

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 Remote.recover_abandoned_collection 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. An accidental flag therefore cannot request recovery.

Close

close

Close the remote. Repeated calls have the same effect.

close() fails with invalid_state while an open database or snapshot uses this remote. Refusal changes no state.