Struct Remote 

pub struct Remote { /* private fields */ }

A handle to a git-remote-object-store repository in a cloud backend.

See the module documentation for the on-bucket key layout and usage examples.

Implementations

impl Remote

pub async fn connect(url_str: &str) -> Result<Self, RemoteError>

Parse url_str and open a connection to the backing cloud store.

Runs an eager probe (a low-cost listing call) to verify connectivity and surface auth failures early. Requires a Tokio runtime — call this inside #[tokio::main] or an equivalent async context.

Errors

Returns RemoteError::Url when the URL is not a recognised scheme, and RemoteError::Backend when the backend is unreachable (missing bucket/container, insufficient permissions, invalid credentials).

pub async fn open(url: &RemoteUrl) -> Result<Self, BackendError>

Open a connection from an already-parsed RemoteUrl.

Prefer connect when starting from a string. Use this variant when you need to inspect or route on the URL before connecting.

Errors

Returns BackendError when the backend is unreachable.

pub fn key(&self, suffix: &str) -> String

Compute the storage key for suffix within this repository’s prefix.

Use this to construct keys for direct store operations.

For a repository at s3+https://bucket/my-repo:

• remote.key("HEAD") → "my-repo/HEAD"
• remote.key("refs/heads/main/") → "my-repo/refs/heads/main/"

For a repository at s3+https://bucket (no prefix):

• remote.key("HEAD") → "HEAD"

pub fn store(&self) -> &dyn ObjectStore

The underlying ObjectStore for direct get/put operations.

Combine with key to target the correct storage path:

let metas = remote.store().list(&remote.key("refs/heads/main/")).await?;

pub fn prefix(&self) -> &str

The repository prefix (empty string for bucket-root repositories).

pub fn engine(&self) -> StorageEngine

The storage engine resolved at open time from the FORMAT key combined with any ?engine= URL parameter.

Callers that target engine-specific APIs (notably crate::packchain::read_blob) inspect this to fail fast against a remote of the wrong shape rather than blindly fetching the engine-specific manifest keys.

pub async fn get_head(&self) -> Result<Bytes, ObjectStoreError>

Read the repository’s HEAD ref.

Errors

Returns ObjectStoreError::NotFound when no HEAD object exists.

pub async fn put_head(&self, content: Bytes) -> Result<(), ObjectStoreError>

Write the repository’s HEAD ref.

Errors

Returns ObjectStoreError on backend write failure (auth, network, etc.).

pub async fn list( &self, suffix: &str, ) -> Result<Vec<ObjectMeta>, ObjectStoreError>

List all objects whose storage key starts with <prefix>/<suffix>.

Pass "" to list everything in the repository. Pass "refs/heads/main/" to list all bundles on that branch. Pass "refs/" to list all ref objects.

Errors

Returns ObjectStoreError on backend list failure (auth, network, etc.).