Filesystem
cua.env.v1 FilesystemService: stat, list, watch, read, chunked upload and signed URLs.
cua.env.v1 FilesystemService: stat, list, watch, read, chunked upload and signed URLs.
File and directory operations, watchers, chunked transfers and signed HTTP URLs.
Source: libs/cua/proto/cua/env/v1/filesystem.proto.
cua.env.v1.FilesystemService
Guest filesystem access.
Paths are absolute, or relative to the default working directory set by
SystemService.Init. A leading "~" expands to the acting user's home.
Operations run as the Init default user.
Large payloads: there is no total size cap. Reads stream in chunks
(ReadFile). Writes use either the native-gRPC client stream
(WriteFile) or the gRPC-Web-safe, resumable unary chunk protocol
(BeginUpload / UploadChunk / CommitUpload). Browsers and <img> tags
can use signed URLs on the plain-HTTP /files route instead
(CreateSignedUrl).
Writes are atomic: data goes to a temporary file in the destination directory and is renamed into place on success.
/cua.env.v1.FilesystemService/Stat, unary: StatRequest to StatResponse.
Returns metadata for one path.
/cua.env.v1.FilesystemService/ListDir, unary: ListDirRequest to ListDirResponse.
Lists a directory, optionally recursively.
/cua.env.v1.FilesystemService/MakeDir, unary: MakeDirRequest to MakeDirResponse.
Creates a directory.
/cua.env.v1.FilesystemService/Move, unary: MoveRequest to MoveResponse.
Moves or renames a file or directory.
/cua.env.v1.FilesystemService/Remove, unary: RemoveRequest to RemoveResponse.
Removes a file or directory.
/cua.env.v1.FilesystemService/WatchDir, server stream: WatchDirRequest to WatchDirResponse.
Streams change events under a directory. The first message is
WatchStarted, sent once the watch is armed, so changes made after it
arrives are guaranteed to be observed.
/cua.env.v1.FilesystemService/CreateWatcher, unary: CreateWatcherRequest to CreateWatcherResponse.
Polling alternative to WatchDir for clients that cannot hold a stream:
creates a server-side watcher that buffers events.
/cua.env.v1.FilesystemService/GetWatcherEvents, unary: GetWatcherEventsRequest to GetWatcherEventsResponse.
Drains buffered events from a watcher.
/cua.env.v1.FilesystemService/RemoveWatcher, unary: RemoveWatcherRequest to RemoveWatcherResponse.
Deletes a watcher. Watchers not polled for 5 minutes are deleted automatically.
/cua.env.v1.FilesystemService/ReadFile, server stream: ReadFileRequest to ReadFileResponse.
Streams a file (or a byte range of it) in chunks.
/cua.env.v1.FilesystemService/WriteFile, client stream: WriteFileRequest to WriteFileResponse.
Writes a file from a client stream. Native gRPC only; gRPC-Web clients
use BeginUpload / UploadChunk / CommitUpload. The first message
must be a WriteFileHeader.
UploadChunk instead (/cua.env.v1.FilesystemService/UploadChunk)./cua.env.v1.FilesystemService/BeginUpload, unary: BeginUploadRequest to BeginUploadResponse.
Starts, or resumes, a resumable chunked upload.
/cua.env.v1.FilesystemService/UploadChunk, unary: UploadChunkRequest to UploadChunkResponse.
Appends one chunk to an upload.
/cua.env.v1.FilesystemService/CommitUpload, unary: CommitUploadRequest to CommitUploadResponse.
Verifies and atomically publishes an upload at its destination path.
/cua.env.v1.FilesystemService/AbortUpload, unary: AbortUploadRequest to AbortUploadResponse.
Discards an upload and its partial data.
/cua.env.v1.FilesystemService/CreateSignedUrl, unary: CreateSignedUrlRequest to CreateSignedUrlResponse.
Mints a time-limited URL on the plain-HTTP /files route for GET
(download) or PUT (upload) of one path.
cua/env/v1/filesystem.proto#Metadata for one filesystem entry.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Final path component. |
path | 2 | string | Absolute, normalized path. |
type | 3 | FileType | Entry type. |
size | 4 | uint64 | Size in bytes (0 for directories). |
mode | 5 | uint32 | Unix permission bits (for example 0o644). Synthesized on Windows. |
owner | 6 | string | Owning user name. |
group | 7 | string | Owning group name (empty on Windows). |
modified_at | 8 | google.protobuf.Timestamp | Last modification time. |
symlink_target | 9 | string | Target of a symbolic link, when type is FILE_TYPE_SYMLINK. |
Request for FilesystemService.Stat.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Path to inspect. |
no_follow_symlinks | 2 | bool | Report the link itself rather than its target. |
Response for FilesystemService.Stat.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo | The entry. |
Request for FilesystemService.ListDir.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Directory to list. |
depth | 2 | uint32 | Recursion depth. 0 and 1 both list direct children only; 2 includes grandchildren, and so on. Symbolic links are never followed during recursion. |
include_hidden | 3 | bool | Include entries whose name starts with "." (and hidden entries on Windows). |
page_size | 4 | uint32 | Maximum entries per page. 0 means 1000. At most 10000. |
page_token | 5 | string | Continuation token from a previous ListDirResponse. |
Response for FilesystemService.ListDir.
| Field | # | Type | Description |
|---|---|---|---|
entries | 1 | repeated EntryInfo | Entries in depth-first order, directories before their contents. |
next_page_token | 2 | string | Token for the next page, empty on the last page. |
Request for FilesystemService.MakeDir.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Directory to create. |
parents | 2 | bool | Create missing parents too. |
mode | 3 | uint32 | Permission bits. 0 means 0o755. |
Response for FilesystemService.MakeDir.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo | The directory. |
created | 2 | bool | False if it already existed (not an error). |
Request for FilesystemService.Move.
| Field | # | Type | Description |
|---|---|---|---|
source | 1 | string | Existing path. |
destination | 2 | string | New path. |
overwrite | 3 | bool | Replace an existing destination. Without it an existing destination fails with ALREADY_EXISTS / ERROR_REASON_PATH_EXISTS. |
create_parents | 4 | bool | Create missing parents of destination. |
Response for FilesystemService.Move.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo | The entry at its new path. |
Request for FilesystemService.Remove.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Path to remove. |
recursive | 2 | bool | Remove a non-empty directory and its contents. |
missing_ok | 3 | bool | Succeed when the path does not exist. |
Response for FilesystemService.Remove.
No fields.
One filesystem change.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Absolute path of the affected entry. |
type | 2 | FsEventType | What happened. |
old_path | 3 | string | Previous path for renames, when the platform reports it. |
observed_at | 4 | google.protobuf.Timestamp | When the server observed the change. |
Request for FilesystemService.WatchDir.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Directory to watch. |
recursive | 2 | bool | Watch the whole subtree. |
keepalive_interval | 3 | google.protobuf.Duration | Interval between keepalive messages. Unset means 30 seconds. |
Sent once when a watch is armed.
No fields.
Sent when the kernel event queue overflowed and events were lost. Clients should rescan.
No fields.
One message of the FilesystemService.WatchDir stream.
| Field | # | Type | Description |
|---|---|---|---|
started | 1 | WatchStarted (oneof message) | First message: the watch is armed. |
event | 2 | FsEvent (oneof message) | A change. |
overflow | 3 | WatchOverflow (oneof message) | Events were dropped. |
keepalive | 4 | KeepAlive (oneof message) | Idle stream heartbeat. |
Request for FilesystemService.CreateWatcher.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Directory to watch. |
recursive | 2 | bool | Watch the whole subtree. |
Response for FilesystemService.CreateWatcher. The watcher is armed when
this returns.
| Field | # | Type | Description |
|---|---|---|---|
watcher_id | 1 | string | Watcher id for GetWatcherEvents and RemoveWatcher. |
Request for FilesystemService.GetWatcherEvents.
| Field | # | Type | Description |
|---|---|---|---|
watcher_id | 1 | string | Which watcher. |
max_events | 2 | uint32 | Maximum events to return. 0 means all buffered. |
Response for FilesystemService.GetWatcherEvents.
| Field | # | Type | Description |
|---|---|---|---|
events | 1 | repeated FsEvent | Buffered events, oldest first. Returned events are removed from the buffer. |
overflowed | 2 | bool | True if the watcher's buffer (10000 events) overflowed since the last poll and events were dropped. Clients should rescan. |
Request for FilesystemService.RemoveWatcher.
| Field | # | Type | Description |
|---|---|---|---|
watcher_id | 1 | string | Which watcher. |
Response for FilesystemService.RemoveWatcher.
No fields.
Request for FilesystemService.ReadFile.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | File to read. |
offset | 2 | uint64 | First byte to read. |
length | 3 | uint64 | Maximum bytes to read. 0 means to end of file. |
chunk_size | 4 | uint32 | Preferred chunk size. 0 means Limits.preferred_chunk_bytes (1 MiB). Clamped to Limits.max_chunk_bytes. |
compute_sha256 | 5 | bool | Compute the SHA-256 of the bytes sent and report it in ReadFileEnd. |
One message of the FilesystemService.ReadFile stream: entry first,
then zero or more chunks in order, then end.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo (oneof message) | File metadata, sent first. |
chunk | 2 | FileChunk (oneof message) | File content. |
end | 3 | ReadFileEnd (oneof message) | Sent last. |
A slice of file content.
| Field | # | Type | Description |
|---|---|---|---|
offset | 1 | uint64 | Absolute file offset of data[0]. |
data | 2 | bytes | The bytes. |
Final message of a ReadFile stream.
| Field | # | Type | Description |
|---|---|---|---|
bytes_read | 1 | uint64 | Bytes sent in chunks. |
sha256 | 2 | string | Lowercase hex SHA-256 of the bytes sent, when requested. |
Destination and options for a write.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Destination path. |
mode | 2 | WriteMode | How to treat an existing file. |
permissions | 3 | uint32 | Permission bits for a new file. 0 means 0o644. |
create_parents | 4 | bool | Create missing parent directories. |
expected_size | 5 | uint64 | Expected total size in bytes, 0 if unknown. Checked on completion when non-zero. |
expected_sha256 | 6 | string | Expected lowercase hex SHA-256 of the full content. Checked on completion when set; a mismatch discards the data and fails with ERROR_REASON_CHECKSUM_MISMATCH. |
One message of the FilesystemService.WriteFile client stream.
| Field | # | Type | Description |
|---|---|---|---|
header | 1 | WriteFileHeader (oneof message) | First message only. |
data | 2 | bytes (oneof message) | File content, strictly sequential. Each chunk is at most Limits.max_chunk_bytes. |
Response for FilesystemService.WriteFile.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo | The written file. |
sha256 | 2 | string | Lowercase hex SHA-256 of the bytes received. |
Request for FilesystemService.BeginUpload.
| Field | # | Type | Description |
|---|---|---|---|
header | 1 | WriteFileHeader | Destination and options. expected_sha256 is strongly recommended. |
upload_id | 2 | string | Client-chosen id that makes this call idempotent and resumable. If an unexpired upload with this id exists for the same path, the call returns its current received_bytes instead of starting over. Empty lets the server generate an id (not resumable after the response is lost). |
ttl | 3 | google.protobuf.Duration | How long partial data is kept without progress. Unset means 1 hour. At most 24 hours. |
Response for FilesystemService.BeginUpload.
| Field | # | Type | Description |
|---|---|---|---|
upload_id | 1 | string | Upload id for later calls. |
received_bytes | 2 | uint64 | Bytes already received. 0 for a new upload; the resume point otherwise. |
max_chunk_bytes | 3 | uint32 | Largest chunk the server accepts. |
expires_at | 4 | google.protobuf.Timestamp | When the partial upload expires if no further chunks arrive. |
Request for FilesystemService.UploadChunk.
| Field | # | Type | Description |
|---|---|---|---|
upload_id | 1 | string | Which upload. |
offset | 2 | uint64 | Offset of data[0]. Must equal the server's received_bytes; a chunk wholly below it is acknowledged as a duplicate, anything else fails with ERROR_REASON_OFFSET_MISMATCH and metadata["expected_offset"]. |
data | 3 | bytes | The bytes. At most max_chunk_bytes. |
Response for FilesystemService.UploadChunk.
| Field | # | Type | Description |
|---|---|---|---|
received_bytes | 1 | uint64 | Total bytes received so far. |
duplicate | 2 | bool | True if the chunk was a retry and was not written again. |
expires_at | 3 | google.protobuf.Timestamp | New expiry of the partial upload. |
Request for FilesystemService.CommitUpload.
| Field | # | Type | Description |
|---|---|---|---|
upload_id | 1 | string | Which upload. |
sha256 | 2 | string | Expected lowercase hex SHA-256, overriding the header's. Optional. |
Response for FilesystemService.CommitUpload.
| Field | # | Type | Description |
|---|---|---|---|
entry | 1 | EntryInfo | The published file. |
sha256 | 2 | string | Lowercase hex SHA-256 of the committed content. |
Request for FilesystemService.AbortUpload.
| Field | # | Type | Description |
|---|---|---|---|
upload_id | 1 | string | Which upload. |
Response for FilesystemService.AbortUpload.
No fields.
Request for FilesystemService.CreateSignedUrl.
| Field | # | Type | Description |
|---|---|---|---|
path | 1 | string | Path the URL grants access to. Exactly this path; no traversal. |
method | 2 | SignedUrlMethod | Allowed method. |
ttl | 3 | google.protobuf.Duration | Validity. Required; at most 24 hours. |
content_type | 4 | string | For GET: Content-Type to serve. Empty means guessed from the name. |
download_name | 5 | string | For GET: serve with Content-Disposition: attachment using this file name. Empty means inline. |
Response for FilesystemService.CreateSignedUrl.
| Field | # | Type | Description |
|---|---|---|---|
url_path | 1 | string | Path and query to append to the spacesd's base URL, for example "/files?path=%2Fhome%2Fu%2Fa.png&method=GET&exp=1767225600&sig=…". The server does not know how it is addressed (direct, Fleet gateway, relay), so it never returns an absolute URL. The signature is HMAC-SHA256 over method, path and expiry with a key derived from the access token; rotating the token revokes every outstanding URL. |
expires_at | 2 | google.protobuf.Timestamp | When the URL stops working. |
Type of a filesystem entry.
| Value | # | Description |
|---|---|---|
FILE_TYPE_UNSPECIFIED | 0 | Not reported. |
FILE_TYPE_FILE | 1 | Regular file. |
FILE_TYPE_DIRECTORY | 2 | Directory. |
FILE_TYPE_SYMLINK | 3 | Symbolic link (only when not following links). |
FILE_TYPE_OTHER | 4 | Anything else (socket, FIFO, device). |
Kind of filesystem change.
| Value | # | Description |
|---|---|---|
FS_EVENT_TYPE_UNSPECIFIED | 0 | Not reported. |
FS_EVENT_TYPE_CREATE | 1 | Entry created. |
FS_EVENT_TYPE_WRITE | 2 | File content written. |
FS_EVENT_TYPE_REMOVE | 3 | Entry removed. |
FS_EVENT_TYPE_RENAME | 4 | Entry renamed or moved. path is the new path when known. |
FS_EVENT_TYPE_CHMOD | 5 | Permissions or ownership changed. |
How WriteFile and uploads treat an existing destination.
| Value | # | Description |
|---|---|---|
WRITE_MODE_UNSPECIFIED | 0 | Not set. Treated as WRITE_MODE_OVERWRITE. |
WRITE_MODE_OVERWRITE | 1 | Replace any existing file atomically. |
WRITE_MODE_CREATE_NEW | 2 | Fail with ERROR_REASON_PATH_EXISTS if the destination exists. |
WRITE_MODE_APPEND | 3 | Append to the existing file (created if missing). Not atomic. |
HTTP method a signed URL is valid for.
| Value | # | Description |
|---|---|---|
SIGNED_URL_METHOD_UNSPECIFIED | 0 | Not set. Rejected. |
SIGNED_URL_METHOD_GET | 1 | Download with GET (supports Range). |
SIGNED_URL_METHOD_PUT | 2 | Upload with PUT (the body replaces the file atomically). |