Cua Volume storage and sync
Where the drive keeps its bytes, the volume on this machine and in Spaces, sync across devices, and the block cache.
Where the drive keeps its bytes, the volume on this machine and in Spaces, sync across devices, and the block cache.
Runtime methods of the drive on the Spaces registry: Settings > Storage, the mount, sync state and the cache. volume_sync_status also lists the volume mounted in each Space. Files: Cua Volume.
Methods of Spaces.
Spaces.volume_storage#volume_storage: where the drive keeps its bytes.
async def volume_storage(self) -> DriveStorageReturns DriveStorage · Async · Raises CuaError
Spaces.volume_storage_set#volume_storage_set: tests, and unless dry_run saves and switches
to, a storage backend (live, no restart).
async def volume_storage_set(self, update: DriveStorageUpdate) -> DriveStorageCheck| Parameter | Type | Default |
|---|---|---|
update | DriveStorageUpdate | required |
Returns DriveStorageCheck · Async · Raises CuaError
Spaces.volume_mount_status#volume_mount_status: whether the drive is mounted as a volume.
async def volume_mount_status(self) -> DriveMountStatusReturns DriveMountStatus · Async · Raises CuaError
Spaces.volume_mount#volume_mount: turns the mount on (kept across restarts) and mounts.
async def volume_mount(self) -> DriveMountStatusReturns DriveMountStatus · Async · Raises CuaError
Spaces.volume_unmount#volume_unmount: turns the mount off; pending uploads land first.
async def volume_unmount(self) -> DriveMountStatusReturns DriveMountStatus · Async · Raises CuaError
Spaces.volume_sync_status#volume_sync_status: devices, pending uploads and conflicts.
async def volume_sync_status(self) -> DriveSyncStatusReturns DriveSyncStatus · Async · Raises CuaError
Spaces.volume_sync_events#volume_sync_events: events after since_seq, waiting up to
wait_ms (at most 30000) for one.
async def volume_sync_events(self, since_seq: Optional[int], wait_ms: Optional[int]) -> DriveSyncEvents| Parameter | Type | Default |
|---|---|---|
since_seq | Option<u64> | required |
wait_ms | Option<u32> | required |
Returns DriveSyncEvents · Async · Raises CuaError
Spaces.volume_sync_resolve#volume_sync_resolve: clears a conflict from the list (files stay).
async def volume_sync_resolve(self, path: str) -> None| Parameter | Type | Default |
|---|---|---|
path | String | required |
Async · Raises CuaError
Spaces.volume_cache_stats#volume_cache_stats: the block cache's size, cap and hit rate.
async def volume_cache_stats(self) -> DriveCacheStatsReturns DriveCacheStats · Async · Raises CuaError
Spaces.volume_cache_set#volume_cache_set: the cache's size cap (at least 256 MiB).
async def volume_cache_set(self, capacity_bytes: int) -> DriveCacheStats| Parameter | Type | Default |
|---|---|---|
capacity_bytes | u64 | required |
Returns DriveCacheStats · Async · Raises CuaError
Spaces.volume_cache_clear#volume_cache_clear: drops every cached block.
async def volume_cache_clear(self) -> DriveCacheStatsReturns DriveCacheStats · Async · Raises CuaError
DriveStorage record#Where the drive keeps its bytes (Settings > Storage).
Returned by Spaces.volume_storage.
| Field | Type | Default | Description |
|---|---|---|---|
backend | String | fs or s3. | |
fs_path / fsPath | String | Where the fs backend keeps bytes. | |
s3 | Option<DriveS3Settings> | ||
has_keys / hasKeys | bool | S3 keys are saved (they are never returned). | |
cloud_available / cloudAvailable | bool | Always false in this release: hide the Cua cloud option. |
DriveS3Settings record#Where an S3-compatible bucket is (no keys).
| Field | Type | Default | Description |
|---|---|---|---|
endpoint | Option<String> | http://127.0.0.1:9000, https://<account>.r2.cloudflarestorage.com; None for AWS. | |
region | String | us-east-1; auto for R2. | |
bucket | String | ||
root | String | A key prefix inside the bucket (may be empty). | |
path_style / pathStyle | bool | Path-style addressing (MinIO and most self-hosted stores). |
DriveStorageUpdate record#A storage change, or with dry_run a connection test.
| Field | Type | Default | Description |
|---|---|---|---|
backend | String | fs or s3 (cloud is refused). | |
s3 | Option<DriveS3Settings> | ||
access_key_id / accessKeyId | Option<String> | With secret_access_key (both or neither); saved in the credential store. | |
secret_access_key / secretAccessKey | Option<String> | ||
dry_run / dryRun | bool | Only test; change nothing. |
DriveStorageCheck record#What a storage test found.
Returned by Spaces.volume_storage_set.
| Field | Type | Default | Description |
|---|---|---|---|
ok | bool | ||
reachable | bool | ||
authorized | bool | ||
versioning | bool | Bucket versioning is on (required). | |
detail | Option<String> | A sentence when not ok: what is wrong and how to fix it. | |
problem | Option<String> | What is wrong, to key the UI on: unreachable, bad_keys, forbidden, bucket_missing, versioning_off, path_style_needed. | |
applied | bool | Saved and switched live. |
DriveMountStatus record#The drive as a volume.
Returned by Spaces.volume_mount, Spaces.volume_mount_status, Spaces.volume_unmount.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | bool | The user's opt-in (off by default). | |
state | String | off, mounting, mounted, needs_approval, unsupported, error. | |
method | String | nfs (macOS), fuse (Linux), fskit, none. | |
path | Option<String> | The mount point when mounted ("Show in Finder" opens it). | |
volume_name / volumeName | String | ||
detail | Option<String> | ||
settings_url / settingsUrl | Option<String> |
DriveSyncStatus record#Sync across devices.
Returned by Spaces.volume_sync_status.
| Field | Type | Default | Description |
|---|---|---|---|
device_id / deviceId | String | ||
device_name / deviceName | String | ||
feed | String | live, off (a store on this machine), offline (the bucket stopped answering; see last_error). | |
poll_interval_ms / pollIntervalMs | u64 | ||
last_poll_ms / lastPollMs | u64 | ||
last_remote_change_ms / lastRemoteChangeMs | u64 | ||
pending_uploads / pendingUploads | u32 | ||
pending_bytes / pendingBytes | u64 | ||
conflicts | Vec<DriveConflict> | ||
devices | Vec<DriveDevice> | ||
last_error / lastError | Option<String> | ||
pending | Vec<DrivePendingUpload> | The files still uploading, largest first (at most 100). | |
backend | String | fs (This Mac) or s3 (your bucket). | |
mount | String | This machine's mount: off, mounting, mounted, needs_approval, unsupported or error. | |
cache | Option<DriveCacheStats> | The block cache in front of a bucket. | |
volumes | Vec<DriveSpaceVolume> | The volume mounted in Spaces. |
DrivePendingUpload record#A file waiting to upload.
| Field | Type | Default | Description |
|---|---|---|---|
path | String | ||
bytes | u64 |
DriveSpaceVolume record#The volume mounted in a Space's guest.
| Field | Type | Default | Description |
|---|---|---|---|
space | String | ||
mount_path / mountPath | String | /volume (Linux) or ~/Cua Volume (macOS), as the guest sees it. | |
backend | String | fs (FUSE) or nfs. | |
principal | String | Whose view it shows: space:<folder>, or agent:<name> while a persistent agent runs there. |
DriveConflict record#A write that lost to a later one, kept in history and as a copy.
| Field | Type | Default | Description |
|---|---|---|---|
path | String | ||
conflict_path / conflictPath | String | ||
winner_device / winnerDevice | String | ||
loser_device / loserDevice | String | ||
winner_version / winnerVersion | String | ||
loser_version / loserVersion | String | ||
ts_ms / tsMs | u64 |
DriveDevice record#A device sharing the drive's bucket.
| Field | Type | Default | Description |
|---|---|---|---|
id | String | ||
name | String | ||
this_device / thisDevice | bool | ||
last_seen_ms / lastSeenMs | u64 | ||
last_change_ms / lastChangeMs | u64 | ||
changes | u64 |
DriveSyncEvents record#Events after a sequence number, and the sequence to ask after next.
Returned by Spaces.volume_sync_events.
| Field | Type | Default | Description |
|---|---|---|---|
events | Vec<DriveSyncEvent> | ||
next_seq / nextSeq | u64 |
DriveSyncEvent record#One sync event.
| Field | Type | Default | Description |
|---|---|---|---|
seq | u64 | ||
ts_ms / tsMs | u64 | ||
kind | String | remote_change, remote_delete, upload_started, upload_done, upload_failed, conflict, error. | |
path | String | ||
device | String | ||
size | u64 | ||
version | String | ||
detail | String |
DriveCacheStats record#The block cache in front of a remote store.
Returned by Spaces.volume_cache_clear, Spaces.volume_cache_set, Spaces.volume_cache_stats.
| Field | Type | Default | Description |
|---|---|---|---|
dir | String | ||
size_bytes / sizeBytes | u64 | ||
capacity_bytes / capacityBytes | u64 | ||
block_bytes / blockBytes | u64 | ||
blocks | u64 | ||
hits | u64 | ||
misses | u64 | ||
hit_rate / hitRate | f64 | ||
prefetched_bytes / prefetchedBytes | u64 | ||
evictions | u64 |