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 +46 -0
- sandcrab/__main__.py +5 -0
- sandcrab/_wire.py +309 -0
- sandcrab/calls.py +366 -0
- sandcrab/client.py +1929 -0
- sandcrab/errors.py +41 -0
- sandcrab/mcp.py +488 -0
- sandcrab-0.3.0.dist-info/METADATA +197 -0
- sandcrab-0.3.0.dist-info/RECORD +15 -0
- sandcrab-0.3.0.dist-info/WHEEL +5 -0
- sandcrab-0.3.0.dist-info/entry_points.txt +2 -0
- sandcrab-0.3.0.dist-info/licenses/LICENSE +202 -0
- sandcrab-0.3.0.dist-info/top_level.txt +2 -0
- sandcrab_templates/__init__.py +4 -0
- sandcrab_templates/client.py +255 -0
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
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")
|