sandcrab 0.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
sandcrab/__init__.py ADDED
@@ -0,0 +1,46 @@
1
+ """Native Python client, template helpers, host-call dispatchers and stdio MCP server for Sandcrab."""
2
+ from sandcrab_templates import (
3
+ Checkpoint,
4
+ PublicationUncertain,
5
+ TemplateClient,
6
+ TemplateError,
7
+ recipe_id,
8
+ )
9
+
10
+ from .calls import (
11
+ AsyncHostCallDispatcher,
12
+ CallContext,
13
+ HostCallDispatcher,
14
+ InMemoryReplyLedger,
15
+ ReplyLedger,
16
+ )
17
+ from .client import AsyncSandcrabClient, AsyncSession, SandcrabClient, Session
18
+ from .errors import (
19
+ CommandFailedError,
20
+ ProtocolError,
21
+ SandcrabError,
22
+ TransportUncertainError,
23
+ )
24
+ from .mcp import SandcrabMcpServer
25
+
26
+ __all__ = [
27
+ "AsyncHostCallDispatcher",
28
+ "AsyncSandcrabClient",
29
+ "AsyncSession",
30
+ "CallContext",
31
+ "Checkpoint",
32
+ "CommandFailedError",
33
+ "HostCallDispatcher",
34
+ "InMemoryReplyLedger",
35
+ "ProtocolError",
36
+ "PublicationUncertain",
37
+ "ReplyLedger",
38
+ "SandcrabClient",
39
+ "SandcrabError",
40
+ "SandcrabMcpServer",
41
+ "Session",
42
+ "TemplateClient",
43
+ "TemplateError",
44
+ "TransportUncertainError",
45
+ "recipe_id",
46
+ ]
sandcrab/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ """CLI module entrypoint (`python3 -m sandcrab.mcp` or `python3 -m sandcrab`)."""
2
+ from .mcp import main
3
+
4
+ if __name__ == "__main__":
5
+ raise SystemExit(main())
sandcrab/_wire.py ADDED
@@ -0,0 +1,309 @@
1
+ """Connection resolution, wire bounds, SSE parsing and bounded gzip tar helpers."""
2
+ from __future__ import annotations
3
+
4
+ import hashlib
5
+ import ipaddress
6
+ import json
7
+ import os
8
+ from pathlib import Path
9
+ import re
10
+ import stat
11
+ from typing import AsyncIterator, Iterator, Mapping
12
+ from urllib.parse import urlsplit
13
+ import uuid
14
+ import zlib
15
+
16
+ from .errors import ProtocolError, SandcrabError
17
+
18
+ DIGEST_RE = re.compile(r"[0-9a-f]{64}")
19
+ PROFILE_RE = re.compile(r"[a-z][a-z0-9-]{0,47}")
20
+ CODE_RE = re.compile(r"[A-Z0-9_]{1,64}")
21
+ JSON_BOUND = 16 * 1024 * 1024
22
+ TRANSFER_BOUND = 1 << 30
23
+ TEMPLATE_STREAM_BOUND = 1 << 30
24
+
25
+
26
+ def check_uuid(value: str, label: str = "ID") -> str:
27
+ try:
28
+ parsed = uuid.UUID(value)
29
+ except (ValueError, TypeError, AttributeError) as error:
30
+ raise ValueError(f"Invalid {label}: {value!r}") from error
31
+ if str(parsed) != value:
32
+ raise ValueError(f"Invalid canonical {label}: {value!r}")
33
+ return value
34
+
35
+
36
+ def check_digest(value: str, label: str = "SHA-256") -> str:
37
+ if not isinstance(value, str) or not DIGEST_RE.fullmatch(value):
38
+ raise ValueError(f"Invalid {label}")
39
+ return value
40
+
41
+
42
+ def check_profile(value: str) -> str:
43
+ if not isinstance(value, str) or not PROFILE_RE.fullmatch(value):
44
+ raise ValueError(f"Invalid profile name: {value!r}")
45
+ return value
46
+
47
+
48
+ def check_relative_path(value: str, *, allow_root: bool = False) -> str:
49
+ if not isinstance(value, str) or not value or len(value) > 4096 or "\0" in value or "\\" in value:
50
+ raise ValueError("Invalid workspace path")
51
+ if value == ".":
52
+ if allow_root:
53
+ return value
54
+ raise ValueError("Workspace root '.' is not valid for this operation")
55
+ if value.startswith("/"):
56
+ raise ValueError("Workspace path must be relative")
57
+ parts = value.split("/")
58
+ if any(part in ("", ".", "..") for part in parts):
59
+ raise ValueError("Workspace path must be normalized and relative")
60
+ return value
61
+
62
+
63
+ def normalize_endpoint(value: str) -> str:
64
+ address = urlsplit(value)
65
+ try:
66
+ loopback = ipaddress.ip_address(address.hostname or "").is_loopback
67
+ except ValueError:
68
+ loopback = False
69
+ if (
70
+ address.scheme != "http"
71
+ or address.username is not None
72
+ or address.password is not None
73
+ or address.path not in ("", "/")
74
+ or address.query
75
+ or address.fragment
76
+ or address.port is None
77
+ or not 1 <= address.port <= 65535
78
+ or not loopback
79
+ ):
80
+ raise ValueError("Use an HTTP endpoint with a literal loopback address and port")
81
+ return value.rstrip("/")
82
+
83
+
84
+ def read_token_file(path: str | Path) -> str:
85
+ resolved = Path(path)
86
+ if os.name != "nt":
87
+ info = resolved.lstat()
88
+ if (
89
+ not stat.S_ISREG(info.st_mode)
90
+ or info.st_uid not in (0, os.geteuid())
91
+ or (stat.S_IMODE(info.st_mode) & 0o077) != 0
92
+ ):
93
+ raise ValueError(
94
+ "Service token file must be a private regular file (mode 0400/0600) owned by root or the caller"
95
+ )
96
+ raw = resolved.read_bytes()
97
+ if len(raw) > 256:
98
+ raise ValueError("Service token file exceeds 256 bytes")
99
+ text = raw.decode("utf-8").rstrip("\r\n")
100
+ if not DIGEST_RE.fullmatch(text):
101
+ raise ValueError("Service token must be 64 lowercase hexadecimal characters")
102
+ return text
103
+
104
+
105
+ def check_unix_socket(path: str | Path) -> str:
106
+ resolved = Path(path)
107
+ if not resolved.is_absolute():
108
+ raise ValueError("Unix socket path must be absolute")
109
+ if os.name == "nt":
110
+ raise ValueError("Unix domain socket transport requires a POSIX host")
111
+ info = os.lstat(resolved)
112
+ if not stat.S_ISSOCK(info.st_mode) or info.st_uid != 0:
113
+ raise ValueError(f"Unix control socket must be a root-owned socket: {resolved}")
114
+ return str(resolved)
115
+
116
+
117
+ def resolve_connection(
118
+ *,
119
+ socket_path: str | Path | None = None,
120
+ endpoint: str | None = None,
121
+ token: str | None = None,
122
+ token_file: str | Path | None = None,
123
+ env: Mapping[str, str] | None = None,
124
+ require_socket_stat: bool = True,
125
+ ) -> tuple[str | None, str, dict[str, str]]:
126
+ """Return `(uds_path, base_url, headers)` after checking transport and credential boundaries."""
127
+ environ = os.environ if env is None else env
128
+ if socket_path is not None and endpoint is not None:
129
+ raise ValueError("Pass either socket_path or endpoint, not both")
130
+ if socket_path is None and endpoint is None:
131
+ env_socket = environ.get("SANDCRAB_SOCKET") or None
132
+ env_endpoint = environ.get("SANDCRAB_ENDPOINT") or None
133
+ if env_socket and env_endpoint:
134
+ raise ValueError(
135
+ "Both SANDCRAB_SOCKET and SANDCRAB_ENDPOINT are set; pass socket_path or endpoint explicitly"
136
+ )
137
+ socket_path = env_socket
138
+ endpoint = env_endpoint
139
+ if socket_path is not None:
140
+ uds = check_unix_socket(socket_path) if require_socket_stat else str(Path(socket_path))
141
+ return uds, "http://sandcrab", {}
142
+ if endpoint is not None:
143
+ base_url = normalize_endpoint(endpoint)
144
+ if token is not None and token_file is not None:
145
+ raise ValueError("Pass either token or token_file, not both")
146
+ if token is None:
147
+ chosen_file = token_file if token_file is not None else environ.get("SANDCRAB_TOKEN_FILE")
148
+ if not chosen_file:
149
+ raise ValueError("Loopback HTTP transport requires token, token_file or SANDCRAB_TOKEN_FILE")
150
+ token = read_token_file(chosen_file)
151
+ elif not DIGEST_RE.fullmatch(token):
152
+ raise ValueError("Service token must be 64 lowercase hexadecimal characters")
153
+ return None, base_url, {"Authorization": "Bearer " + token}
154
+ raise ValueError("Configure socket_path, endpoint, SANDCRAB_SOCKET or SANDCRAB_ENDPOINT")
155
+
156
+
157
+ def format_byte_range(spec: tuple[int | None, int | None] | str) -> str:
158
+ if isinstance(spec, str):
159
+ text = spec.removeprefix("bytes=")
160
+ if "," in text or "-" not in text:
161
+ raise ValueError("Byte range must be START-END, START- or -SUFFIX")
162
+ start, end = text.split("-", 1)
163
+ if (not start and not end) or (start and not start.isdigit()) or (end and not end.isdigit()):
164
+ raise ValueError("Invalid byte range bounds")
165
+ return f"bytes={start}-{end}"
166
+ start, end = spec
167
+ if start is None and end is None:
168
+ raise ValueError("Byte range requires at least start or suffix length")
169
+ if start is not None and (type(start) is not int or start < 0):
170
+ raise ValueError("Range start must be a non-negative integer")
171
+ if end is not None and (type(end) is not int or end < 0):
172
+ raise ValueError("Range end must be a non-negative integer")
173
+ if start is None:
174
+ if end == 0:
175
+ raise ValueError("Suffix byte range must be positive")
176
+ return f"bytes=-{end}"
177
+ if end is not None and end < start:
178
+ raise ValueError("Range end must be >= start")
179
+ return f"bytes={start}-{'' if end is None else end}"
180
+
181
+
182
+ def parse_json_response(status: int, raw: bytes | bytearray, *, recovery_id: str | None = None) -> dict:
183
+ try:
184
+ value = json.loads(raw)
185
+ except ValueError as error:
186
+ raise ProtocolError(f"Daemon returned non-JSON body (HTTP {status})") from error
187
+ if not isinstance(value, dict):
188
+ raise ProtocolError("Daemon JSON response must be an object")
189
+ if status >= 400:
190
+ err = value.get("error")
191
+ code = err.get("code") if isinstance(err, dict) else value.get("code")
192
+ if not isinstance(code, str) or not CODE_RE.fullmatch(code):
193
+ code = "API_ERROR"
194
+ raise SandcrabError(status, code, recovery_id=recovery_id)
195
+ return value
196
+
197
+
198
+ def parse_sse_lines(lines: Iterator[str]) -> Iterator[dict]:
199
+ event_id: str | None = None
200
+ event_type = "message"
201
+ data_lines: list[str] = []
202
+ for raw_line in lines:
203
+ line = raw_line.rstrip("\r\n")
204
+ if not line:
205
+ if data_lines:
206
+ payload = "\n".join(data_lines)
207
+ data_lines.clear()
208
+ yield {"id": event_id, "event": event_type, "data": json.loads(payload)}
209
+ event_type = "message"
210
+ continue
211
+ if line.startswith(":"):
212
+ continue
213
+ field, _, rest = line.partition(":")
214
+ if rest.startswith(" "):
215
+ rest = rest[1:]
216
+ if field == "id":
217
+ event_id = rest
218
+ elif field == "event":
219
+ event_type = rest
220
+ elif field == "data":
221
+ data_lines.append(rest)
222
+ if data_lines:
223
+ raise ProtocolError("Incomplete SSE frame before stream EOF")
224
+
225
+
226
+ async def parse_sse_lines_async(lines: AsyncIterator[str]) -> AsyncIterator[dict]:
227
+ event_id: str | None = None
228
+ event_type = "message"
229
+ data_lines: list[str] = []
230
+ async for raw_line in lines:
231
+ line = raw_line.rstrip("\r\n")
232
+ if not line:
233
+ if data_lines:
234
+ payload = "\n".join(data_lines)
235
+ data_lines.clear()
236
+ yield {"id": event_id, "event": event_type, "data": json.loads(payload)}
237
+ event_type = "message"
238
+ continue
239
+ if line.startswith(":"):
240
+ continue
241
+ field, _, rest = line.partition(":")
242
+ if rest.startswith(" "):
243
+ rest = rest[1:]
244
+ if field == "id":
245
+ event_id = rest
246
+ elif field == "event":
247
+ event_type = rest
248
+ elif field == "data":
249
+ data_lines.append(rest)
250
+ if data_lines:
251
+ raise ProtocolError("Incomplete SSE frame before stream EOF")
252
+
253
+
254
+ def is_gzip_tar(source: bytes | Path) -> bool:
255
+ if isinstance(source, (bytes, bytearray)):
256
+ return len(source) >= 2 and source[0] == 0x1F and source[1] == 0x8B
257
+ name = Path(source).name.lower()
258
+ if name.endswith((".tar.gz", ".tgz")):
259
+ return True
260
+ with Path(source).open("rb") as handle:
261
+ head = handle.read(2)
262
+ return len(head) == 2 and head[0] == 0x1F and head[1] == 0x8B
263
+
264
+
265
+ def iter_tar_chunks(source: bytes | Path, *, limit: int = TEMPLATE_STREAM_BOUND) -> Iterator[bytes]:
266
+ """Yield plain tar chunks, streaming gunzip on the client when `source` is gzip-compressed."""
267
+ import io
268
+
269
+ gzipped = is_gzip_tar(source)
270
+ total = 0
271
+
272
+ def emit(chunk: bytes) -> bytes:
273
+ nonlocal total
274
+ total += len(chunk)
275
+ if total > limit:
276
+ raise ValueError(f"Uncompressed template tar exceeds {limit} bytes")
277
+ return chunk
278
+
279
+ if isinstance(source, (bytes, bytearray)) and not gzipped:
280
+ yield emit(bytes(source))
281
+ return
282
+
283
+ stream = io.BytesIO(source) if isinstance(source, (bytes, bytearray)) else Path(source).open("rb")
284
+ with stream as handle:
285
+ if not gzipped:
286
+ while chunk := handle.read(65536):
287
+ yield emit(chunk)
288
+ return
289
+ decoder = zlib.decompressobj(16 + zlib.MAX_WBITS)
290
+ saw_input = False
291
+ while raw := handle.read(65536):
292
+ saw_input = True
293
+ pending = raw
294
+ while pending:
295
+ out = decoder.decompress(pending, 65536)
296
+ if out:
297
+ yield emit(out)
298
+ if decoder.unconsumed_tail:
299
+ pending = decoder.unconsumed_tail
300
+ elif decoder.eof and decoder.unused_data:
301
+ pending = decoder.unused_data
302
+ decoder = zlib.decompressobj(16 + zlib.MAX_WBITS)
303
+ else:
304
+ pending = b""
305
+ tail = decoder.flush()
306
+ if tail:
307
+ yield emit(tail)
308
+ if not saw_input or not decoder.eof:
309
+ raise ValueError("Truncated gzip archive")