toolbound 0.2.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.
toolbound/sync.py ADDED
@@ -0,0 +1,76 @@
1
+ """Blocking wrapper for code that is not async (scripts, sync frameworks)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import threading
7
+ from collections.abc import Coroutine, Mapping
8
+ from typing import Any, TypeVar
9
+
10
+ from toolbound.core.approval import PendingApproval
11
+ from toolbound.core.context import ExecutionContext
12
+ from toolbound.core.gateway import Gateway
13
+ from toolbound.core.result import ToolResult
14
+
15
+ T = TypeVar("T")
16
+
17
+
18
+ class SyncGateway:
19
+ """Runs a :class:`Gateway` on a private event-loop thread.
20
+
21
+ ``with SyncGateway(gateway) as gw: gw.call("get_issue", {...}, ctx=ctx)``.
22
+ Do not use from inside a running event loop; use the async API there.
23
+ """
24
+
25
+ def __init__(self, gateway: Gateway) -> None:
26
+ self.gateway = gateway
27
+ self._loop = asyncio.new_event_loop()
28
+ self._thread = threading.Thread(
29
+ target=self._loop.run_forever, daemon=True, name="toolbound-sync"
30
+ )
31
+ self._thread.start()
32
+
33
+ def _run(self, coro: Coroutine[Any, Any, T]) -> T:
34
+ return asyncio.run_coroutine_threadsafe(coro, self._loop).result()
35
+
36
+ def call(
37
+ self,
38
+ name: str,
39
+ arguments: Mapping[str, Any] | None,
40
+ *,
41
+ ctx: ExecutionContext,
42
+ call_id: str | None = None,
43
+ approval: str | None = None,
44
+ ) -> ToolResult:
45
+ return self._run(
46
+ self.gateway.call(name, arguments, ctx=ctx, call_id=call_id, approval=approval)
47
+ )
48
+
49
+ def resume(
50
+ self,
51
+ request: PendingApproval | str,
52
+ *,
53
+ ctx: ExecutionContext,
54
+ approved_by: str,
55
+ call_id: str | None = None,
56
+ ) -> ToolResult:
57
+ return self._run(
58
+ self.gateway.resume(request, ctx=ctx, approved_by=approved_by, call_id=call_id)
59
+ )
60
+
61
+ def deny(self, request: PendingApproval | str) -> PendingApproval:
62
+ return self._run(self.gateway.deny(request))
63
+
64
+ def close(self) -> None:
65
+ if self._loop.is_closed():
66
+ return
67
+ self._run(self.gateway.aclose())
68
+ self._loop.call_soon_threadsafe(self._loop.stop)
69
+ self._thread.join(timeout=5)
70
+ self._loop.close()
71
+
72
+ def __enter__(self) -> SyncGateway:
73
+ return self
74
+
75
+ def __exit__(self, *exc: object) -> None:
76
+ self.close()
@@ -0,0 +1,19 @@
1
+ """HTTP transports (outbound adapters).
2
+
3
+ ``SecureTransport`` (httpx-based) is imported lazily so that the core and the
4
+ mock transport can be used without httpx.
5
+ """
6
+
7
+ from typing import Any
8
+
9
+ from .mock import MockResponse, MockTransport
10
+
11
+ __all__ = ["MockResponse", "MockTransport", "Resolver", "SecureTransport", "SystemResolver"]
12
+
13
+
14
+ def __getattr__(name: str) -> Any:
15
+ if name in ("SecureTransport", "SystemResolver", "Resolver"):
16
+ from . import http
17
+
18
+ return getattr(http, name)
19
+ raise AttributeError(name)
@@ -0,0 +1,269 @@
1
+ """The default secure transport, built on httpx.
2
+
3
+ For each request it:
4
+
5
+ 1. resolves the host itself and checks **every** returned address against the
6
+ service's network policy (one bad address blocks the request),
7
+ 2. connects only to checked addresses, while TLS still verifies the certificate
8
+ against the original host name (SNI + ``Host`` header), so DNS rebinding
9
+ between "check" and "connect" is not possible. If connecting to one checked
10
+ address fails, the next checked address is tried,
11
+ 3. never follows redirects (the core re-checks each hop), ignores proxy
12
+ environment variables (``trust_env=False``), and **never stores cookies**,
13
+ so state set by an upstream for one user can never be sent on behalf of
14
+ another,
15
+ 4. streams the body and aborts once the *decompressed* size exceeds the limit,
16
+ 5. enforces a total deadline per attempt, defeating slow-drip responses,
17
+ 6. reports whether a failed request may have reached the upstream, so callers
18
+ can tell "certainly not sent" from "outcome unknown".
19
+
20
+ One instance can be shared by several event loops (for example FastAPI test
21
+ clients that each start their own loop): HTTP clients are kept per event loop.
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import asyncio
27
+ import ipaddress
28
+ import socket
29
+ import threading
30
+ import time
31
+ import weakref
32
+ from http.cookiejar import CookieJar, DefaultCookiePolicy
33
+ from typing import Protocol
34
+ from urllib.parse import SplitResult, urlsplit, urlunsplit
35
+
36
+ import httpx
37
+
38
+ from toolbound.core.errors import ErrorCode, NetworkBlocked, ToolFailure
39
+ from toolbound.core.network import check_ip
40
+ from toolbound.core.ports import HttpRequest, HttpResponse
41
+
42
+
43
+ class Resolver(Protocol):
44
+ """Resolves a host name to IP address strings."""
45
+
46
+ async def resolve(self, host: str, port: int) -> list[str]: ...
47
+
48
+
49
+ class SystemResolver:
50
+ """Uses the operating system resolver (``getaddrinfo``)."""
51
+
52
+ async def resolve(self, host: str, port: int) -> list[str]:
53
+ loop = asyncio.get_running_loop()
54
+ infos = await loop.getaddrinfo(host, port, type=socket.SOCK_STREAM)
55
+ return sorted({str(info[4][0]).split("%")[0] for info in infos})
56
+
57
+
58
+ def _no_cookie_jar() -> CookieJar:
59
+ """A cookie jar that refuses to store anything.
60
+
61
+ httpx clients keep cookies by default. A shared client would then replay a
62
+ ``Set-Cookie`` received during one user's call on every later call, for
63
+ every user and tenant. Toolbound never wants that.
64
+ """
65
+ return CookieJar(policy=DefaultCookiePolicy(allowed_domains=[]))
66
+
67
+
68
+ class SecureTransport:
69
+ """SSRF-hardened HTTP transport.
70
+
71
+ Args:
72
+ resolver: Host resolver (injectable for tests).
73
+ verify: TLS verification (``True``, a CA bundle path, or an
74
+ ``ssl.SSLContext``). Disabling it is not supported.
75
+ max_connections: Connection pool size per host and event loop.
76
+ """
77
+
78
+ def __init__(
79
+ self,
80
+ *,
81
+ resolver: Resolver | None = None,
82
+ verify: bool | str = True,
83
+ max_connections: int = 100,
84
+ ) -> None:
85
+ if verify is False:
86
+ raise ValueError("TLS verification cannot be disabled")
87
+ self._resolver: Resolver = resolver if resolver is not None else SystemResolver()
88
+ self._verify = verify
89
+ self._max_connections = max_connections
90
+ # Clients are bound to the event loop that created them, and to one host
91
+ # name: connections are opened to a pinned IP, and a pool keyed by IP must
92
+ # never reuse a TLS session made for another host.
93
+ self._clients: weakref.WeakKeyDictionary[
94
+ asyncio.AbstractEventLoop, dict[str, httpx.AsyncClient]
95
+ ] = weakref.WeakKeyDictionary()
96
+ self._lock = threading.Lock()
97
+
98
+ def _client_for(self, host: str) -> httpx.AsyncClient:
99
+ loop = asyncio.get_running_loop()
100
+ with self._lock:
101
+ per_loop = self._clients.get(loop)
102
+ if per_loop is None:
103
+ per_loop = self._clients[loop] = {}
104
+ client = per_loop.get(host)
105
+ if client is None:
106
+ client = httpx.AsyncClient(
107
+ follow_redirects=False,
108
+ trust_env=False,
109
+ verify=self._verify,
110
+ cookies=_no_cookie_jar(),
111
+ limits=httpx.Limits(
112
+ max_connections=self._max_connections, max_keepalive_connections=20
113
+ ),
114
+ headers={"Accept-Encoding": "gzip, deflate"},
115
+ )
116
+ per_loop[host] = client
117
+ return client
118
+
119
+ async def aclose(self) -> None:
120
+ """Close the clients that belong to the running event loop."""
121
+ loop = asyncio.get_running_loop()
122
+ with self._lock:
123
+ mine = self._clients.pop(loop, {})
124
+ for client in mine.values():
125
+ await client.aclose()
126
+
127
+ async def __aenter__(self) -> SecureTransport:
128
+ return self
129
+
130
+ async def __aexit__(self, *exc: object) -> None:
131
+ await self.aclose()
132
+
133
+ async def send(self, request: HttpRequest) -> HttpResponse:
134
+ parts = urlsplit(request.url)
135
+ host = (parts.hostname or "").rstrip(".")
136
+ port = parts.port or (443 if parts.scheme == "https" else 80)
137
+ started = time.perf_counter()
138
+ sent: bool | None = False # becomes None once bytes may have left
139
+ try:
140
+ async with asyncio.timeout(request.timeout):
141
+ addresses = await self._addresses(host, port, request)
142
+ client = self._client_for(host)
143
+ default_port = 443 if parts.scheme == "https" else 80
144
+ host_header = host if port == default_port else f"{host}:{port}"
145
+ headers = [(k, v) for k, v in request.headers if k.lower() != "host"]
146
+ headers.append(("Host", host_header))
147
+ extensions = {"sni_hostname": host} if parts.scheme == "https" else {}
148
+ timeout = httpx.Timeout(request.timeout, connect=request.connect_timeout)
149
+ response: httpx.Response | None = None
150
+ address = addresses[0]
151
+ sent = None # from here on, bytes may reach the upstream
152
+ for index, address in enumerate(addresses):
153
+ http_request = client.build_request(
154
+ request.method,
155
+ _with_host(parts, address, port),
156
+ headers=headers,
157
+ content=request.body,
158
+ timeout=timeout,
159
+ extensions=extensions,
160
+ )
161
+ try:
162
+ response = await client.send(http_request, stream=True)
163
+ break
164
+ except (httpx.ConnectError, httpx.ConnectTimeout):
165
+ # Nothing was sent; another checked address may work.
166
+ if index == len(addresses) - 1:
167
+ raise
168
+ assert response is not None
169
+ try:
170
+ declared = response.headers.get("content-length")
171
+ if (
172
+ declared
173
+ and declared.isdigit()
174
+ and int(declared) > request.max_response_bytes
175
+ ):
176
+ raise ToolFailure(
177
+ ErrorCode.RESPONSE_TOO_LARGE,
178
+ "upstream response exceeds the size limit",
179
+ retryable=False,
180
+ )
181
+ chunks: list[bytes] = []
182
+ size = 0
183
+ async for chunk in response.aiter_bytes():
184
+ size += len(chunk)
185
+ if size > request.max_response_bytes:
186
+ raise ToolFailure(
187
+ ErrorCode.RESPONSE_TOO_LARGE,
188
+ "upstream response exceeds the size limit",
189
+ retryable=False,
190
+ )
191
+ chunks.append(chunk)
192
+ finally:
193
+ await response.aclose()
194
+ except (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout) as exc:
195
+ code = (
196
+ ErrorCode.UPSTREAM_UNAVAILABLE
197
+ if isinstance(exc, httpx.ConnectError)
198
+ else ErrorCode.TIMEOUT
199
+ )
200
+ raise ToolFailure(
201
+ code, f"could not connect to upstream ({type(exc).__name__})", request_sent=False
202
+ ) from None
203
+ except TimeoutError:
204
+ raise ToolFailure(
205
+ ErrorCode.TIMEOUT,
206
+ "upstream did not respond in time",
207
+ request_sent=_after_connect(sent),
208
+ ) from None
209
+ except httpx.TimeoutException:
210
+ raise ToolFailure(
211
+ ErrorCode.TIMEOUT, "upstream did not respond in time", request_sent=None
212
+ ) from None
213
+ except httpx.DecodingError:
214
+ raise ToolFailure(
215
+ ErrorCode.UPSTREAM_ERROR, "upstream sent an undecodable body", retryable=False
216
+ ) from None
217
+ except (httpx.TransportError, OSError) as exc:
218
+ raise ToolFailure(
219
+ ErrorCode.UPSTREAM_UNAVAILABLE,
220
+ f"could not reach upstream ({type(exc).__name__})",
221
+ request_sent=None,
222
+ ) from None
223
+ return HttpResponse(
224
+ status=response.status_code,
225
+ headers={k.lower(): v for k, v in response.headers.items()},
226
+ body=b"".join(chunks),
227
+ url=request.url,
228
+ elapsed_ms=(time.perf_counter() - started) * 1000,
229
+ extensions={"peer_address": address},
230
+ )
231
+
232
+ async def _addresses(self, host: str, port: int, request: HttpRequest) -> list[str]:
233
+ """All addresses for ``host``, each checked; IPv4 first for predictability."""
234
+ try:
235
+ literal = ipaddress.ip_address(host.strip("[]"))
236
+ except ValueError:
237
+ literal = None
238
+ if literal is not None:
239
+ check_ip(literal, request.network)
240
+ return [str(literal)]
241
+ try:
242
+ addresses = await self._resolver.resolve(host, port)
243
+ except OSError:
244
+ raise ToolFailure(
245
+ ErrorCode.UPSTREAM_UNAVAILABLE,
246
+ "could not resolve upstream host",
247
+ request_sent=False,
248
+ ) from None
249
+ if not addresses:
250
+ raise ToolFailure(
251
+ ErrorCode.UPSTREAM_UNAVAILABLE, "upstream host has no addresses", request_sent=False
252
+ )
253
+ for address in addresses:
254
+ check_ip(address, request.network) # every address must pass
255
+ v4 = [a for a in addresses if ":" not in a]
256
+ v6 = [a for a in addresses if ":" in a]
257
+ return v4 + v6
258
+
259
+
260
+ def _after_connect(sent: bool | None) -> bool | None:
261
+ return False if sent is False else None
262
+
263
+
264
+ def _with_host(parts: SplitResult, address: str, port: int) -> str:
265
+ host = f"[{address}]" if ":" in address else address
266
+ return urlunsplit((parts.scheme, f"{host}:{port}", parts.path, parts.query, ""))
267
+
268
+
269
+ __all__ = ["NetworkBlocked", "Resolver", "SecureTransport", "SystemResolver"]
@@ -0,0 +1,89 @@
1
+ """An in-memory transport for tests, examples and offline development."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import re
7
+ from collections.abc import Callable
8
+ from dataclasses import dataclass, field
9
+ from typing import Any
10
+
11
+ from toolbound.core.network import check_ip
12
+ from toolbound.core.ports import HttpRequest, HttpResponse
13
+
14
+ Handler = Callable[[HttpRequest], "HttpResponse | MockResponse | Any"]
15
+
16
+
17
+ @dataclass(slots=True)
18
+ class MockResponse:
19
+ status: int = 200
20
+ json: Any = None
21
+ body: bytes | None = None
22
+ headers: dict[str, str] = field(default_factory=dict)
23
+
24
+ def to_http(self, url: str) -> HttpResponse:
25
+ headers = {k.lower(): v for k, v in self.headers.items()}
26
+ if self.body is not None:
27
+ body = self.body
28
+ elif self.json is not None:
29
+ body = json.dumps(self.json).encode()
30
+ headers.setdefault("content-type", "application/json")
31
+ else:
32
+ body = b""
33
+ return HttpResponse(status=self.status, headers=headers, body=body, url=url)
34
+
35
+
36
+ class MockTransport:
37
+ """Route requests to Python handlers. Records every request it receives.
38
+
39
+ ``mock.route("GET", "https://api.example.com/items/{id}", handler)`` where the
40
+ handler returns a :class:`MockResponse`, an :class:`HttpResponse`, or any
41
+ JSON-serializable value (sent as ``200 application/json``).
42
+
43
+ IP-literal targets are still checked with :func:`check_ip`, but DNS is not
44
+ resolved, so use :class:`SecureTransport` for end-to-end network tests.
45
+ """
46
+
47
+ def __init__(self) -> None:
48
+ self._routes: list[tuple[str, re.Pattern[str], Handler]] = []
49
+ self.requests: list[HttpRequest] = []
50
+ self.closed = False
51
+
52
+ def route(self, method: str, url_template: str, handler: Handler | Any) -> MockTransport:
53
+ pattern = re.escape(url_template)
54
+ pattern = re.sub(r"\\\{[A-Za-z_][A-Za-z0-9_]*\\\}", r"[^/?#]+", pattern)
55
+ if callable(handler):
56
+ fn: Handler = handler
57
+ else:
58
+ value = handler
59
+
60
+ def fn(_request: HttpRequest) -> Any:
61
+ return value
62
+
63
+ self._routes.append((method.upper(), re.compile(f"^{pattern}(?:\\?.*)?$"), fn))
64
+ return self
65
+
66
+ async def send(self, request: HttpRequest) -> HttpResponse:
67
+ self.requests.append(request)
68
+ from urllib.parse import urlsplit
69
+
70
+ host = urlsplit(request.url).hostname or ""
71
+ try:
72
+ import ipaddress
73
+
74
+ ipaddress.ip_address(host)
75
+ check_ip(host, request.network)
76
+ except ValueError:
77
+ pass
78
+ for method, pattern, handler in self._routes:
79
+ if method == request.method and pattern.match(request.url):
80
+ result = handler(request)
81
+ if isinstance(result, HttpResponse):
82
+ return result
83
+ if isinstance(result, MockResponse):
84
+ return result.to_http(request.url)
85
+ return MockResponse(json=result).to_http(request.url)
86
+ return MockResponse(404, json={"message": "no mock route"}).to_http(request.url)
87
+
88
+ async def aclose(self) -> None:
89
+ self.closed = True