omnydrive library

Classes

AtomicFile: Writes file contents atomically: data is written to a sibling temp file, flushed, then renamed over the destination. A crash mid-write therefore leaves the previous file intact instead of a truncated one.
AuthToken: An opaque bearer token issued by a hub and presented by endpoints on authenticated requests.
BranchName: A git branch name with validation and protected-branch awareness.
BranchNamingStrategy: Decides the branch name automation pushes to, so changes never land directly on a protected branch.
CapabilityNegotiator: Pure capability negotiation. Given what a drive supports and the access mode a caller requested, computes the effective capabilities, dropping any write-flavored capability in read-only mode. No I/O.
CapabilitySet: An immutable set of Capability values with convenient wire conversion.
Clock: Time source used by services so tests can fix now.
Conflict: A structured description of why a synchronization could not proceed, carried by ConflictDetectedException and surfaced through the conflicts API.
ConflictDetector: Pure conflict-detection logic shared by all synchronizers. No I/O.
ContentHash: A content-addressed hash of a file or blob.
ContentServer: HTTP server that streams a publishing endpoint's directory drives to peers.
ContentSource: Low-level, transport-agnostic read/write access to a directory drive's content. Backed locally by dart:io and remotely by an endpoint's HTTP content API, so the directory provider works the same in both cases.
DefaultBranchNamingStrategy: Default strategy producing names like omnydrive/update-<n> or, when a label is supplied, omnydrive/<label>.
DirectoryMountedDrive: A directory drive materialized at a local path. Holds the local working-copy source plus the origin source so pulls can be applied.
DirectoryProvider: DriveProvider for filesystem directories, local or remote.
DirectorySynchronizer: Synchronizes a directory drive using manifest-hash references.
Drive: A published source of files.
DriveCapabilities: What operations a drive supports, derived from its provider and access mode.
DriveEndpoint: A device that participates in the network: it can publish, mount, clone and synchronize drives, coordinated through a hub.
DriveEvent: A structured, observable event emitted by drives, mounts and the sync engine. Consumed by the diagnostics API and the CLI's --verbose 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>.
DriveProvider: A pluggable backend that knows how to describe, reference, materialize and synchronize a particular kind of drive (directory, git, ...).
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.
DriveRegistry: Persists the hub's registry of published drives.
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.
EndpointRegistration: The hub-side record for a registered endpoint: its public identity plus the hashed shared secret used to authenticate it.
EndpointRegistry: Persists the hub's registry of known endpoints.
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.
EventBus: Broadcast hub for DriveEvents. Multiple listeners may subscribe; a bounded ring buffer of recent events is retained for the diagnostics API.
FileDriveRegistry: A DriveRegistry persisted as a single JSON document.
FileLock: Advisory cross-process lock backed by an exclusively-created lock file.
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.
FileMountRegistry: A MountRegistry persisted as a single JSON document, so mounts created by one CLI invocation are visible to later sync/mounts commands.
FileSyncStateStore: A SyncStateStore persisted as a single JSON document keyed by mount id.
GitCli: The single chokepoint for all interaction with the system git binary.
GitDivergence: How two git references have diverged, as reported by git rev-list --left-right --count base...head.
GitMountedDrive: A git drive cloned to a local path.
GitProvider: DriveProvider for Git repositories — regular or bare, local path or remote URL. All git interaction is delegated to GitCli.
GitResult: Result of a single git invocation.
GitSynchronizer: Synchronizes a git drive using commit-SHA references.
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).
HubServer: HTTP adapter exposing a LocalDriveHub as a REST API. The server holds no state of its own — it parses requests, delegates to the hub, and renders the result (or any DomainException) through JsonResponse.
IdGenerator: Generates logical identifiers like endpoint_1, token_2, etc.
InMemoryDriveRegistry: In-memory DriveRegistry. The default for tests and single-process hubs.
InMemoryEndpointRegistry: In-memory EndpointRegistry. The default for tests and single-process hubs.
InMemoryMountRegistry: In-memory MountRegistry. The default for tests.
InMemorySyncStateStore: In-memory SyncStateStore. The default for tests.
JsonResponse: Centralized JSON response factory. Keeps the envelope identical across every endpoint of both the hub and endpoint content servers:
LocalContentSource: A ContentSource backed by a local filesystem directory.
LocalDriveEndpoint: In-process DriveEndpoint: the device-side orchestration that ties the provider registry, the local mount/sync stores and a DriveHub together.
LocalDriveHub: In-process DriveHub: the central coordinator's logic, free of any HTTP concerns. The shelf hub server is a thin adapter over this class.
LocalPath: An absolute, normalized local filesystem path.
Logger: Structured logger. Implementations emit a level, a message and an arbitrary context map. A logger can be scoped with child so every record inherits a base context (e.g. the drive or mount id).
ManifestBuilder: Walks a directory tree and produces a content-addressed FileManifest.
ManifestDiff: The set of path-level changes between two FileManifests.
ManifestDiffer: Pure diffing of two directory manifests. No I/O.
MountedDrive: A drive that has been materialized at a local path. Provides access to the local working copy's state and the ability to apply remote changes.
MountId: Identifies a local mount of a drive.
MountInfo: Records a drive mounted at a local path.
MountRegistry: Persists the local endpoint's mounts.
NoopLogger: Discards all log records. The default in libraries and tests.
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).
ProgressEvent: A single progress update emitted during a transfer.
ProgressReporter: Sink for progress updates. Callers that don't care about progress simply pass null where a ProgressReporter is accepted.
ProviderRegistry: Maps a ProviderType to the DriveProvider that handles it.
RandomIdGenerator: Generates random, collision-resistant identifiers using a cryptographically secure RNG. Used for production endpoint ids, tokens and shared secrets so no extra dependency (uuid) is required.
RetryPolicy: Decides whether a failed operation should be retried and how long to wait between attempts. Used by the client transport and remote sync steps to recover from transient connection failures.
SequentialIdGenerator: Deterministic, in-memory counter per prefix. Intended for tests and single-process defaults.
StructuredLogger: Writes one JSON object per line to an IOSink (stderr by default). Records below minLevel are dropped.
Synchronizer: Computes and applies synchronization for a specific provider.
SyncMetrics: Metrics captured for a completed synchronization run, surfaced through the diagnostics API and returned with a sync result.
SyncPlan: A computed description of the work a synchronization will perform.
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.
SyncStateStore: Persists per-mount synchronization state. The baseline reference stored here is the anchor the conflict check compares against; it is updated atomically only after a successful publish.
SystemClock: Production clock returning the current UTC time.

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.
DriveEventKind: Kinds of events published on the EventBus.
LogLevel: Severity levels, ordered from least to most severe.
MountType: Relationship between a mount and its source drive.
OriginUriScheme: How an OriginUri is addressed.
ProgressPhase: Phases a long-running synchronization transfer moves through.
ProviderType: The kind of backing store a drive is published from.
RefKind: The flavor of reference a SyncRef holds.
SyncDirection: The direction of a synchronization operation.
SyncStatus: The synchronization state of a mount relative to its origin.

Constants

omnyDriveVersion → const String: The OmnyDrive package version, surfaced by the GET /version endpoint of both the hub and the endpoint content server. Keep in sync with pubspec.yaml.

Functions

networkedProviderRegistry({required EndpointId endpoint, Client? client, GitCli git = const GitCli(), Clock? clock}) → ProviderRegistry: Builds a ProviderRegistry whose directory provider resolves remote http(s) origins through an HttpContentSource (and still handles local dir/file origins). This is what a networked endpoint uses so it can clone and sync directory drives served by other endpoints.
runWithRetry<T>(Future<T> action(), {RetryPolicy policy = const RetryPolicy(), bool retryable(Object error)?, Random? random}) → Future<T>: Runs action, retrying according to policy while retryable returns true for the thrown error. Re-throws the last error once attempts are exhausted.
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.

Typedefs

ContentSourceResolver = ContentSource Function(OriginUri origin, {required bool writable}): Resolves an OriginUri (and write intent) to a ContentSource. The local resolver handles dir/file origins; an HTTP resolver is supplied for remote drives served by an endpoint content server.
DriveContentResolver = ContentSource Function(DriveRegistration drive): Resolves a published directory drive to the ContentSource that backs it.
ServeUrlBuilder = String Function(EndpointIdentity self, Drive drive): Builds the URL peers should use to fetch a published drive's content.

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 git subprocess 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, ...).
UnauthorizedException: The caller is not authenticated (missing or invalid bearer token).
ValidationException: Invalid input from a caller (bad value object, malformed DTO, etc.).

omnydrive library

Classes

Enums

Constants

Functions

Typedefs

Exceptions / Errors

omnydrive package

omnydrive library