parasite

Protocol

Wire Format

Messages are serialized with bincode (compact binary) and length-prefixed:

┌────────────────┬──────────────────────────────┐
│ length: u32 LE │ bincode-encoded Message       │
└────────────────┴──────────────────────────────┘

Handshake

Every connection begins with a handshake:

Client → Agent:  HandshakeRequest { protocol_version: 1, auth_token: "..." }
Agent → Client:  HandshakeResponse { success: true, agent_id: "hostname", error: None }

If authentication fails, the agent sends success: false with an error message and closes the connection.

Message Types

Shell Session

Message Direction Fields
ShellOpen C→A session_id, cols, rows, command
ShellData Bidirectional session_id, data: Vec<u8>
ShellResize C→A session_id, cols, rows
ShellClose C→A session_id
ShellExited A→C session_id, exit_code

session_id is a Uuid identifying the PTY session.

Directory Operations

All directory operations use a request_id: Uuid for request-response correlation.

Message Direction Fields
DirList C→A request_id, path
DirListResponse A→C request_id, path, entries: Vec<DirEntry>, error
DirCreate C→A request_id, path
DirCreateResponse A→C request_id, success, error
DirRename C→A request_id, old_path, new_path
DirRenameResponse A→C request_id, success, error
DirDelete C→A request_id, path
DirDeleteResponse A→C request_id, success, error
DirSearch C→A request_id, path, query
DirSearchResponse A→C request_id, results: Vec<String>, error

System Info

Message Direction Fields
SystemInfoRequest C→A (none)
SystemInfoResponse A→C hostname, os_name, os_version, cpu_count, memory/disk stats

File Transfer

Message Direction Fields
FileUploadStart C→A request_id, remote_path, total_size, permissions
FileUploadChunk C→A request_id, offset, data, is_last
FileDownloadRequest C→A request_id, remote_path
FileDownloadResponse A→C request_id, total_size, error
FileDownloadChunk A→C request_id, offset, data, is_last

Keepalive

Message Direction
Ping C→A
Pong A→C

Error

Message Direction Fields
Error A→C message

Types

type SessionId = Uuid;

struct DirEntry {
    name: String,
}

struct ProcessInfo {
    pid: u32,
    name: String,
    cpu_usage: f32,
    memory_bytes: u64,
}