omnydrive_client library
OmnyDrive client SDK — everything needed to talk to a running hub and the endpoint content servers it routes to, without depending on the engine (providers, servers, persistence).
Start from OmnyClient; drop down to HttpDriveHub / HttpContentSource for finer control. Errors surface as the same DomainException subtypes the engine raises, decoded from the wire by throwApiError.
Classes
- AuthToken
- An opaque bearer token issued by a hub and presented by endpoints on authenticated requests.
- CapabilitySet
- An immutable set of Capability values with convenient wire conversion.
- Conflict
- A structured description of why a synchronization could not proceed, carried by ConflictDetectedException and surfaced through the conflicts API.
- ContentHash
- A content-addressed hash of a file or blob.
- ContentSource
-
Low-level, transport-agnostic read/write access to a directory drive's
content. Backed locally by
dart:ioand remotely by an endpoint's HTTP content API, so the directory provider works the same in both cases. - Drive
- A published source of files.
- DriveCapabilities
- What operations a drive supports, derived from its provider and access mode.
- DriveHub
- The central coordinator. Handles endpoint discovery, authentication, the drive registry, capability negotiation and synchronization routing. A hub never needs direct filesystem access — it only brokers metadata.
- DriveId
-
Identifies a published drive, scoped to its origin endpoint so ids are
unique across the network and human-readable:
<endpointId>/<name-slug>. - DriveRegistration
- The hub-side registry record for a published drive: the drive metadata plus the URL of the endpoint content server that serves its bytes.
- DriveRoute
- Where a drive's content can be fetched from, returned by the hub's sync routing so a peer can talk directly to the serving endpoint.
- EndpointId
- Identifies a device (endpoint) participating in the network.
- EndpointIdentity
- The public identity of an endpoint as advertised to the hub and peers.
- Enrollment
- The credentials handed back to an endpoint when it first enrolls with a hub.
- ErrorCodes
- Stable, machine-readable error codes returned to API consumers and used by the CLI to choose exit codes. Always snake_case.
- FileManifest
- A content-addressed snapshot of a directory: a map of relative path to FileManifestEntry. The manifest's hash is the directory's SyncRef.
- FileManifestEntry
- A single file recorded in a FileManifest.
- HttpContentSource
- A ContentSource backed by a remote endpoint's HTTP content server.
- HttpDriveHub
- A DriveHub that talks to a remote hub server over HTTP. Endpoints use it in place of an in-process LocalDriveHub so the same orchestration code runs against a networked hub.
- HubId
- Identifies a hub (the central coordinator).
- MountId
- Identifies a local mount of a drive.
- MountInfo
- Records a drive mounted at a local path.
- OmnyClient
- A thin, high-level client for talking to a running OmnyDrive hub and the endpoint content servers it routes to.
- OriginUri
- Describes where a drive's content originates: a filesystem directory, an HTTP(S) endpoint URL, or a git URL (https/ssh/file).
- SyncRef
- The universal baseline reference used by the synchronization engine.
- SyncResult
- The outcome of a completed synchronization.
- SyncState
- The persisted synchronization state of a single mount.
Enums
- AccessMode
- Whether a mounted drive may modify (and synchronize back to) its origin.
- Capability
- A discrete operation a drive may support.
- ConflictKind
- The reason a synchronization conflict was raised.
- MountType
- Relationship between a mount and its source drive.
- OriginUriScheme
- How an OriginUri is addressed.
- ProviderType
- The kind of backing store a drive is published from.
- RefKind
- The flavor of reference a SyncRef holds.
- SyncStatus
- The synchronization state of a mount relative to its origin.
Constants
- omnyDriveVersion → const String
-
The OmnyDrive package version, surfaced by the
GET /versionendpoint of both the hub and the endpoint content server. Keep in sync withpubspec.yaml.
Functions
-
throwApiError(
int statusCode, String body) → Never - Translates a non-2xx HTTP response from a hub or content server back into the matching DomainException, so callers of the HTTP clients see the same typed failures they would from an in-process implementation.
Exceptions / Errors
- AccessDeniedException
- The caller is authenticated but not permitted to perform the operation, or the operation violates the drive's access mode (e.g. writing to a read-only mount).
- ConflictDetectedException
- Raised by the synchronization engine when the source reference moved away from the baseline the caller synchronized against, so publishing local changes would silently clobber remote work.
- ConflictException
- A resource cannot be created because it already exists, or a generic state conflict prevents the operation.
- DomainException
- Base type for any expected, user-facing failure raised by the domain or application layers.
- InvalidJsonException
- A request body could not be parsed as a JSON object.
- LockHeldException
- A mount-level lock is currently held by another operation; the caller should retry once the in-flight operation completes.
- NotFoundException
- A referenced resource (drive, endpoint, mount, ...) does not exist.
- ProviderException
-
A provider operation failed (a
gitsubprocess returned non-zero, a file could not be read, a remote was unreachable, etc.). - SyncException
- A synchronization operation failed for a reason other than a detected conflict (transfer error, apply failure, ...).
- The caller is not authenticated (missing or invalid bearer token).
- ValidationException
- Invalid input from a caller (bad value object, malformed DTO, etc.).