Module file_proto 

File-channel vocabulary shared with vm-agent (arcbox_vm_proto::file): the stat/event DTOs and the size caps a caller validates against. File channel: the guest vsock port the agent serves file I/O on.

Frame format is identical to the exec channel: [u8 type][u32 LE len][payload]. One vsock connection per operation; the agent closes after sending the final frame.

Hex	Name	Direction	Payload
0x20	FILE_WRITE_REQ	Host → Agent	JSON {"path": str, "mode": u32}
0x21	FILE_DATA	bidirectional	raw bytes (one chunk)
0x22	FILE_DONE	bidirectional	empty — end of data stream
0x23	FILE_READ_REQ	Host → Agent	JSON {"path": str}
0x24	FILE_STAT_REQ	Host → Agent	JSON StatReq
0x25	FILE_LIST_REQ	Host → Agent	JSON ListDirReq
0x26	FILE_MKDIR_REQ	Host → Agent	JSON MakeDirReq
0x27	FILE_REMOVE_REQ	Host → Agent	JSON RemoveReq
0x28	FILE_MOVE_REQ	Host → Agent	JSON MoveReq
0x29	FILE_WATCH_REQ	Host → Agent	JSON WatchReq
0x30	FILE_ACK	Agent → Host	empty — operation succeeded
0x31	FILE_ERR	Agent → Host	UTF-8 error message
0x32	FILE_STAT	Agent → Host	JSON FileStatDto
0x33	FILE_LIST	Agent → Host	JSON [FileStatDto, ...]
0x34	FILE_EVENT	Agent → Host	JSON FsEventDto

Stat/List answer one data frame; MakeDir/Remove/Move answer FILE_ACK. Watch answers FILE_ACK once the inotify watch is established, then streams FILE_EVENT frames until either side closes the connection — the host closing it is the cancellation signal, the agent side closing it (sandbox stop) is the clean end of the stream.

FILE_ERR payloads carry a machine-readable errno prefix (ERR_NOT_FOUND and friends) on every verb — the path verbs and the read/write flows alike — so the host maps them onto typed errors instead of a blanket transport error.

Write flow

Host  →  FILE_WRITE_REQ  {path, mode}
Host  →  FILE_DATA       [chunk 1..N]
Host  →  FILE_DONE
          ←  FILE_ACK  (success)
          ←  FILE_ERR  (failure)

Read flow

Host  →  FILE_READ_REQ  {path}
          ←  FILE_DATA  [chunk 1..N]
          ←  FILE_DONE  (success — all bytes sent)
          ←  FILE_ERR   (failure)

Structs

FileStatDto

Metadata of one filesystem entry (FILE_STAT / FILE_LIST payload).

FsEventDto

One filesystem event (FILE_EVENT payload). Mirrors arcbox.sandbox.v1.FsEvent: path is the old path for renames, with renamed_to set only then.

ListDirReq

FILE_LIST_REQ payload.

MakeDirReq

FILE_MKDIR_REQ payload. mode carries the Unix permission bits for created directories; 0 defaults to 0o755 on the agent side.

MoveReq

FILE_MOVE_REQ payload.

RemoveReq

FILE_REMOVE_REQ payload.

StatReq

FILE_STAT_REQ payload.

WatchReq

FILE_WATCH_REQ payload.

Constants

ERR_NOT_A_DIRECTORY

FILE_ERR prefix: a directory was expected.

ERR_NOT_EMPTY

FILE_ERR prefix: a non-recursive remove hit a non-empty directory.

ERR_NOT_FOUND

FILE_ERR prefix: the path does not exist.

EVENT_CREATED

FsEventDto::kind: an entry appeared.

EVENT_MODIFIED

FsEventDto::kind: an entry’s contents or attributes changed.

EVENT_REMOVED

FsEventDto::kind: an entry disappeared.

EVENT_RENAMED

FsEventDto::kind: an entry was renamed within the watched tree.

FILE_ACK

The operation succeeded. Empty payload.

FILE_DATA

One chunk of file bytes, in either direction.

FILE_DONE

End of a data stream, in either direction. Empty payload.

FILE_ERR

The operation failed. Payload: UTF-8 message, errno-prefixed.

FILE_EVENT

One filesystem event on a watched tree. Payload: JSON FsEventDto.

FILE_LIST

A directory listing. Payload: JSON array of FileStatDto.

FILE_LIST_REQ

List a directory. Payload: JSON ListDirReq.

FILE_MKDIR_REQ

Create a directory. Payload: JSON MakeDirReq.

FILE_MOVE_REQ

Rename an entry. Payload: JSON MoveReq.

FILE_PORT

Guest-side vsock port for file I/O.

FILE_READ_REQ

Read a file. Payload: JSON {"path": str}.

FILE_REMOVE_REQ

Remove an entry. Payload: JSON RemoveReq.

FILE_STAT

One entry’s metadata. Payload: JSON FileStatDto.

FILE_STAT_REQ

Stat one entry. Payload: JSON StatReq.

FILE_WATCH_REQ

Watch a directory. Payload: JSON WatchReq.

FILE_WRITE_REQ

Open a file for writing. Payload: JSON {"path": str, "mode": u32}.

KIND_DIR

FileStatDto::kind: a directory.

KIND_FILE

FileStatDto::kind: a regular file.

KIND_OTHER

FileStatDto::kind: anything else (device, socket, fifo, …).

KIND_SYMLINK

FileStatDto::kind: a symbolic link (reported, never followed).

MAX_FILE_SIZE

Maximum total file size for file I/O operations (256 MiB).