Cua Volume
The versioned volume every Space and agent shares: files, history, grants, requests and audit.
The versioned volume every Space and agent shares: files, history, grants, requests and audit.
Cua Volume methods on the Spaces registry. Access is checked by the runtime; pass a DriveView to see the drive as a persistent agent does. Grants and approvals ask the user for presence. Guide: Cua Volume.
Methods of Spaces.
Spaces.volume_ls#volume_ls: a folder's immediate children (default the root).
async def volume_ls(self, path: Optional[str], view: Optional[DriveView]) -> DriveListing| Parameter | Type | Default |
|---|---|---|
path | Option<String> | required |
view | Option<DriveView> | required |
Returns DriveListing · Async · Raises CuaError
Spaces.volume_read#volume_read: a file (or one of its versions).
async def volume_read(self, path: str, version: Optional[str], view: Optional[DriveView]) -> DriveFile| Parameter | Type | Default |
|---|---|---|
path | String | required |
version | Option<String> | required |
view | Option<DriveView> | required |
Returns DriveFile · Async · Raises CuaError
Spaces.volume_write#volume_write: a new version of a file. if_etag makes it a
compare-and-swap, create_only makes it create-only.
async def volume_write(self, path: str, content: bytes, if_etag: Optional[str], create_only: bool, view: Optional[DriveView]) -> DriveObject| Parameter | Type | Default |
|---|---|---|
path | String | required |
content | Vec<u8> | required |
if_etag | Option<String> | required |
create_only | bool | required |
view | Option<DriveView> | required |
Returns DriveObject · Async · Raises CuaError
Spaces.volume_delete#volume_delete: a delete marker (history stays).
async def volume_delete(self, path: str, if_etag: Optional[str], view: Optional[DriveView]) -> None| Parameter | Type | Default |
|---|---|---|
path | String | required |
if_etag | Option<String> | required |
view | Option<DriveView> | required |
Async · Raises CuaError
Spaces.volume_history#volume_history: a file's versions, newest first.
async def volume_history(self, path: str, view: Optional[DriveView]) -> List[DriveVersion]| Parameter | Type | Default |
|---|---|---|
path | String | required |
view | Option<DriveView> | required |
Returns Vec<DriveVersion> · Async · Raises CuaError
Spaces.volume_restore#volume_restore: makes an old version current again.
async def volume_restore(self, path: str, version: str, view: Optional[DriveView]) -> DriveObject| Parameter | Type | Default |
|---|---|---|
path | String | required |
version | String | required |
view | Option<DriveView> | required |
Returns DriveObject · Async · Raises CuaError
Spaces.volume_grant#volume_grant: widens principal's access (agent:<name> or
space:<id>, mode r or rw). The user confirms with presence.
async def volume_grant(self, principal: str, prefix: str, mode: str, expires_in_secs: Optional[int], note: Optional[str]) -> DriveGrant| Parameter | Type | Default |
|---|---|---|
principal | String | required |
prefix | String | required |
mode | String | required |
expires_in_secs | Option<u64> | required |
note | Option<String> | required |
Returns DriveGrant · Async · Raises CuaError
Spaces.volume_revoke#volume_revoke.
async def volume_revoke(self, grant_id: str) -> DriveGrant| Parameter | Type | Default |
|---|---|---|
grant_id | String | required |
Returns DriveGrant · Async · Raises CuaError
Spaces.volume_grants#volume_grants: live grants (every grant with all).
async def volume_grants(self, all: bool) -> List[DriveGrant]| Parameter | Type | Default |
|---|---|---|
all | bool | required |
Returns Vec<DriveGrant> · Async · Raises CuaError
Spaces.volume_request_access#volume_request_access: agent asks the user for more access.
async def volume_request_access(self, agent: str, prefix: str, mode: str, reason: Optional[str], in_space: Optional[str]) -> DriveAccessRequest| Parameter | Type | Default |
|---|---|---|
agent | String | required |
prefix | String | required |
mode | String | required |
reason | Option<String> | required |
in_space | Option<String> | required |
Returns DriveAccessRequest · Async · Raises CuaError
Spaces.volume_requests#volume_requests: requests waiting for the user.
async def volume_requests(self) -> List[DriveAccessRequest]Returns Vec<DriveAccessRequest> · Async · Raises CuaError
Spaces.volume_approve#volume_approve: the request becomes a grant (with presence).
async def volume_approve(self, request_id: str, expires_in_secs: Optional[int]) -> DriveGrant| Parameter | Type | Default |
|---|---|---|
request_id | String | required |
expires_in_secs | Option<u64> | required |
Returns DriveGrant · Async · Raises CuaError
Spaces.volume_deny#volume_deny.
async def volume_deny(self, request_id: str) -> None| Parameter | Type | Default |
|---|---|---|
request_id | String | required |
Async · Raises CuaError
Spaces.volume_audit#volume_audit: the newest events (default 50) and whether the log
verified.
async def volume_audit(self, limit: Optional[int]) -> DriveAudit| Parameter | Type | Default |
|---|---|---|
limit | Option<u32> | required |
Returns DriveAudit · Async · Raises CuaError
DriveView record#Whose view of the drive a call takes: the user (the default, the whole drive) or a persistent agent in a Space. It only ever narrows.
| Field | Type | Default | Description |
|---|---|---|---|
as_agent / asAgent | Option<String> | None | A persistent agent's name (ada). |
in_space / inSpace | Option<String> | None | The Space id the agent is in (local:work). |
DriveListing record#A folder's listing.
Returned by Spaces.volume_ls.
| Field | Type | Default | Description |
|---|---|---|---|
path | String | ||
principal | String | user or agent:<name>. | |
entries | Vec<DriveEntry> |
DriveEntry record#One row of a drive listing.
| Field | Type | Default | Description |
|---|---|---|---|
path | String | Key (folders end in /). | |
name | String | ||
folder | bool | ||
size | u64 | ||
modified_ms / modifiedMs | u64 | ||
etag | String | ||
mode | String | r or rw: what this view may do there. | |
sync | Option<DriveFileSync> | A file's sync state, when it has something to say (uploading, conflicted, or last written by another device). |
DriveFile record#A file's content and version.
Returned by Spaces.volume_read.
| Field | Type | Default | Description |
|---|---|---|---|
path | String | ||
size | u64 | ||
etag | String | ||
version | String | ||
modified_ms / modifiedMs | u64 | ||
content | Vec<u8> | ||
sync | Option<DriveFileSync> | Its sync state, while the drive's services run. |
DriveObject record#A written version.
Returned by Spaces.volume_restore, Spaces.volume_write.
| Field | Type | Default | Description |
|---|---|---|---|
key | String | ||
size | u64 | ||
etag | String | ||
version | String | ||
modified_ms / modifiedMs | u64 |
DriveVersion record#One version in a file's history.
Returned by Spaces.volume_history.
| Field | Type | Default | Description |
|---|---|---|---|
version | String | ||
size | u64 | ||
modified_ms / modifiedMs | u64 | ||
deleted | bool | ||
latest | bool |
DriveGrant record#A widening of an agent's or a Space's access.
Returned by Spaces.volume_approve, Spaces.volume_grant, Spaces.volume_grants, Spaces.volume_revoke.
| Field | Type | Default | Description |
|---|---|---|---|
id | String | ||
principal | String | ||
prefix | String | ||
mode | String | r or rw. | |
created_ms / createdMs | u64 | ||
expires_ms / expiresMs | Option<u64> | ||
revoked | bool | ||
note | String |
DriveAccessRequest record#An agent's request for more access, waiting for the user.
Returned by Spaces.volume_request_access, Spaces.volume_requests.
| Field | Type | Default | Description |
|---|---|---|---|
id | String | ||
principal | String | ||
prefix | String | ||
mode | String | ||
reason | String | ||
created_ms / createdMs | u64 |
DriveAudit record#The newest audit events and whether the hash chain verified.
Returned by Spaces.volume_audit.
| Field | Type | Default | Description |
|---|---|---|---|
events | Vec<DriveAuditEvent> | ||
verified | bool | ||
error | Option<String> |
DriveAuditEvent record#One audit event.
| Field | Type | Default | Description |
|---|---|---|---|
seq | u64 | ||
ts_ms / tsMs | u64 | ||
principal | String | ||
action | String | ||
path | String | ||
detail | String |
DriveFileSync record#One file's sync state.
| Field | Type | Default | Description |
|---|---|---|---|
state | String | synced, pending_upload (not yet in storage: other devices do not see it), conflict (a write lost to a later one, kept at conflict_path) or conflict_copy (the kept copy of a losing write). | |
written_by / writtenBy | Option<String> | The device that last wrote it, when another one did. | |
conflict_path / conflictPath | Option<String> |