v0.166.0
  1"""Message protocol for portal communication.
  2
  3Messages are JSON dicts encrypted with NaCl before being sent through
  4the relay. The relay only sees opaque bytes.
  5
  6Message types:
  7  exec           - Execute Python code (local → remote)
  8  exec_stdout    - Streaming stdout chunk (remote → local)
  9  exec_result    - Execution result (remote → local)
 10  error          - Error response (remote → local)
 11  file_pull      - Request a file (local → remote)
 12  file_data      - File contents chunk (remote → local)
 13  file_push      - Send a file chunk (local → remote)
 14  file_push_result - File push confirmation (remote → local)
 15  ping           - Keepalive (either direction)
 16  pong           - Keepalive response (either direction)
 17"""
 18
 19import base64
 20import math
 21
 22# Max chunk size for file transfers (256KB).
 23FILE_CHUNK_SIZE = 256 * 1024
 24
 25# Max file size for transfers (50MB).
 26MAX_FILE_SIZE = 50 * 1024 * 1024
 27
 28# Default exec timeout in seconds.
 29DEFAULT_EXEC_TIMEOUT = 120
 30
 31# Relay WebSocket endpoint.
 32DEFAULT_RELAY_HOST = "portal.plainframework.com"
 33RELAY_PATH = "/__portal__"
 34
 35# Protocol version — bumped on breaking changes.
 36PROTOCOL_VERSION = 1
 37
 38
 39def make_relay_url(relay_host: str, channel: str, side: str) -> str:
 40    """Build the relay WebSocket URL."""
 41    scheme = "ws" if relay_host.startswith(("localhost", "127.0.0.1")) else "wss"
 42    return f"{scheme}://{relay_host}{RELAY_PATH}?v={PROTOCOL_VERSION}&channel={channel}&side={side}"
 43
 44
 45def chunk_count(file_size: int) -> int:
 46    """Number of chunks needed to transfer a file."""
 47    return max(1, math.ceil(file_size / FILE_CHUNK_SIZE))
 48
 49
 50def make_exec(
 51    code: str, json_output: bool = False, timeout: int = DEFAULT_EXEC_TIMEOUT
 52) -> dict:
 53    return {
 54        "type": "exec",
 55        "code": code,
 56        "json_output": json_output,
 57        "timeout": timeout,
 58    }
 59
 60
 61def make_exec_stdout(data: str) -> dict:
 62    return {"type": "exec_stdout", "data": data}
 63
 64
 65def make_exec_result(
 66    return_value: str | None, error: str | None, stdout: str = ""
 67) -> dict:
 68    return {
 69        "type": "exec_result",
 70        "stdout": stdout,
 71        "return_value": return_value,
 72        "error": error,
 73    }
 74
 75
 76def make_error(error: str) -> dict:
 77    return {"type": "error", "error": error}
 78
 79
 80def make_file_pull(remote_path: str) -> dict:
 81    return {"type": "file_pull", "remote_path": remote_path}
 82
 83
 84def make_file_data(name: str, chunk: int, chunks: int, data: bytes) -> dict:
 85    return {
 86        "type": "file_data",
 87        "name": name,
 88        "chunk": chunk,
 89        "chunks": chunks,
 90        "data": base64.b64encode(data).decode("ascii"),
 91    }
 92
 93
 94def make_file_push(remote_path: str, chunk: int, chunks: int, data: bytes) -> dict:
 95    return {
 96        "type": "file_push",
 97        "remote_path": remote_path,
 98        "chunk": chunk,
 99        "chunks": chunks,
100        "data": base64.b64encode(data).decode("ascii"),
101    }
102
103
104def make_file_push_result(path: str, total_bytes: int) -> dict:
105    return {"type": "file_push_result", "path": path, "bytes": total_bytes}
106
107
108def make_ping() -> dict:
109    return {"type": "ping"}
110
111
112def make_pong() -> dict:
113    return {"type": "pong"}