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"}