holon-sh 0.0.1.dev13__tar.gz → 0.0.1.dev15__tar.gz

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.
Files changed (27) hide show
  1. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/PKG-INFO +5 -1
  2. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/client.py +5 -1
  3. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/context.py +12 -0
  4. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/ext/events/_server.py +5 -8
  5. holon_sh-0.0.1.dev15/holon/serve.py +220 -0
  6. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/pyproject.toml +10 -2
  7. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/tests/test_events.py +46 -38
  8. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/tests/test_package.py +9 -0
  9. holon_sh-0.0.1.dev15/tests/test_serve.py +379 -0
  10. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/.gitignore +0 -0
  11. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/LICENSE +0 -0
  12. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/README.md +0 -0
  13. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/ext/__init__.py +0 -0
  14. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/ext/events/__init__.py +0 -0
  15. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/ext/events/_client.py +0 -0
  16. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/ext/events/_wire.py +0 -0
  17. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/ext/files/__init__.py +0 -0
  18. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/ext/files/_client.py +0 -0
  19. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/ext/files/_server.py +0 -0
  20. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/ext/files/_wire.py +0 -0
  21. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/holon/py.typed +0 -0
  22. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/scripts/verify_distribution.py +0 -0
  23. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/tests/fixtures/caller/holon/apps/__init__.py +0 -0
  24. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/tests/test_context.py +0 -0
  25. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/tests/test_elicit.py +0 -0
  26. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/tests/test_files.py +0 -0
  27. {holon_sh-0.0.1.dev13 → holon_sh-0.0.1.dev15}/tests/test_runtime.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: holon-sh
3
- Version: 0.0.1.dev13
3
+ Version: 0.0.1.dev15
4
4
  Summary: Typed MCP clients and the caller of an MCP request
5
5
  Project-URL: Repository, https://github.com/holon-sh/sdk-py
6
6
  License-Expression: Apache-2.0
@@ -9,6 +9,10 @@ Requires-Python: >=3.11
9
9
  Requires-Dist: httpx2<3,>=2.10
10
10
  Requires-Dist: jsonschema<5,>=4.26
11
11
  Requires-Dist: mcp<3,>=2.3
12
+ Requires-Dist: opentelemetry-api<2,>=1.28
13
+ Requires-Dist: pydantic<3,>=2.12
14
+ Requires-Dist: starlette<2,>=0.48
15
+ Requires-Dist: uvicorn<1,>=0.31.1
12
16
  Description-Content-Type: text/markdown
13
17
 
14
18
  # Holon Python SDK
@@ -40,6 +40,7 @@ from mcp.types import (
40
40
  )
41
41
  from referencing import Registry
42
42
 
43
+ from holon.context import _request
43
44
  from holon.ext.events import AppEvents
44
45
  from holon.ext.files._client import (
45
46
  FILES,
@@ -283,7 +284,10 @@ class _App:
283
284
  f"Dependency {self._name} is unavailable ({prefix}URL). Set the endpoint or supply a binding."
284
285
  )
285
286
  token = os.environ.get(prefix + "TOKEN")
286
- headers = {"Authorization": f"Bearer {token}"} if token else None
287
+ headers = {"Authorization": f"Bearer {token}"} if token else {}
288
+ request = _request.get()
289
+ if request is not None and not request.ended and request.token:
290
+ headers["X-Holon-Context"] = request.token
287
291
  return endpoint, partial(http_client, headers=headers)
288
292
 
289
293
  # Raises an error from the block as itself, not in the session's ExceptionGroup.
@@ -1,5 +1,6 @@
1
1
  from __future__ import annotations
2
2
 
3
+ from contextvars import ContextVar
3
4
  from dataclasses import dataclass
4
5
  from typing import Any, TypedDict
5
6
 
@@ -90,3 +91,14 @@ def get_context() -> RequestContext:
90
91
  ),
91
92
  caller,
92
93
  )
94
+
95
+
96
+ @dataclass
97
+ class _Request:
98
+ """The MCP request being served. Tasks it spawns share it, and see when it ends."""
99
+
100
+ token: str
101
+ ended: bool = False
102
+
103
+
104
+ _request: ContextVar[_Request | None] = ContextVar("holon_request", default=None)
@@ -413,7 +413,7 @@ class Events(Extension):
413
413
  name: str,
414
414
  *,
415
415
  input_schema: type[A] | TypeAdapter[A],
416
- payload_schema: type[D] | TypeAdapter[D],
416
+ payload_schema: dict[str, Any],
417
417
  description: str | None = None,
418
418
  match: Match[D, A] | None = None,
419
419
  transform: Transform[D, A] | None = None,
@@ -424,9 +424,11 @@ class Events(Extension):
424
424
  ) -> EventType[A, D]:
425
425
  """Declare an event type.
426
426
 
427
+ Annotate the result as ``EventType[Arguments, Data]`` to type ``emit``.
428
+
427
429
  Args:
428
430
  input_schema: Type of a subscription's arguments.
429
- payload_schema: Type of each occurrence's data.
431
+ payload_schema: JSON Schema of each occurrence's data.
430
432
  match: ``(context, event, arguments)``: whether a subscription receives an event. Defaults to all.
431
433
  transform: ``(context, event, arguments)``: the data a subscription receives.
432
434
  delivery: The delivery modes offered.
@@ -443,16 +445,11 @@ class Events(Extension):
443
445
  if isinstance(input_schema, TypeAdapter)
444
446
  else TypeAdapter(input_schema)
445
447
  )
446
- payload = (
447
- payload_schema
448
- if isinstance(payload_schema, TypeAdapter)
449
- else TypeAdapter(payload_schema)
450
- )
451
448
  descriptor = {
452
449
  "name": name,
453
450
  **({"description": description} if description else {}),
454
451
  "inputSchema": arguments.json_schema(),
455
- "payloadSchema": payload.json_schema(),
452
+ "payloadSchema": payload_schema,
456
453
  }
457
454
  declared = EventType(
458
455
  name,
@@ -0,0 +1,220 @@
1
+ """Serves an app at the paths Holon gives it: ``python -m holon.serve server.py``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import base64
7
+ import importlib
8
+ import mimetypes
9
+ import os
10
+ import re
11
+ import sys
12
+ from dataclasses import dataclass
13
+ from pathlib import Path, PurePath
14
+ from typing import Any
15
+
16
+ import uvicorn
17
+ from mcp.server import MCPServer
18
+ from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
19
+ from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
20
+ from mcp.server.auth.provider import AccessToken
21
+ from mcp.server.transport_security import TransportSecuritySettings
22
+ from opentelemetry import context as tracing
23
+ from opentelemetry import propagate
24
+ from pydantic import BaseModel
25
+ from starlette.authentication import AuthCredentials, UnauthenticatedUser
26
+ from starlette.datastructures import Headers
27
+ from starlette.responses import FileResponse, PlainTextResponse, Response
28
+ from starlette.types import ASGIApp, Receive, Scope, Send
29
+
30
+ from holon.context import _Request, _request
31
+ from holon.ext.events import Events
32
+
33
+ __all__ = ["App", "load", "serve"]
34
+
35
+ _MCP = re.compile(r"/mcp(/[^/]+)?")
36
+ _CONTEXT = re.compile(r"[A-Za-z0-9_-]+\.([A-Za-z0-9_-]+)\.[A-Za-z0-9_-]+")
37
+ _CALLER = re.compile(r"([^/]+)/([^/]+)")
38
+ _MALFORMED = PlainTextResponse(
39
+ "Malformed Holon context\n",
40
+ status_code=400,
41
+ headers={"x-content-type-options": "nosniff"},
42
+ )
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class App:
47
+ """An app's module: its MCP server, and the directory of its page."""
48
+
49
+ server: MCPServer[Any]
50
+ frontend: Path | None = None
51
+
52
+
53
+ def load(entry: str) -> App:
54
+ """Import an app's module, such as ``server.py`` or ``src/server.py``, from the current directory.
55
+
56
+ The module defines ``server``, an ``MCPServer``, and may define ``frontend``, the directory of its page.
57
+ """
58
+ sys.path.insert(0, os.getcwd())
59
+ name = ".".join(PurePath(entry.removesuffix(".py")).parts)
60
+ module = importlib.import_module(name)
61
+ server = getattr(module, "server", None)
62
+ if not isinstance(server, MCPServer):
63
+ raise TypeError(f"{entry} must define server, an MCPServer")
64
+ frontend = os.fspath(getattr(module, "frontend", ""))
65
+ return App(server, Path(frontend).absolute() if frontend else None)
66
+
67
+
68
+ async def serve(app: App) -> None:
69
+ """Serve ``app`` on ``HOST`` and ``PORT``, or else on 127.0.0.1:3000.
70
+
71
+ The MCP endpoint is at ``/mcp`` and ``/mcp/<app>``, and the frontend's files are everywhere else.
72
+ """
73
+ config = uvicorn.Config(
74
+ _asgi(app),
75
+ host=os.environ.get("HOST", "127.0.0.1"),
76
+ port=int(os.environ.get("PORT", "3000")),
77
+ lifespan="on",
78
+ h11_max_incomplete_event_size=65536,
79
+ access_log=False,
80
+ proxy_headers=False,
81
+ ws="none",
82
+ timeout_graceful_shutdown=1,
83
+ )
84
+ await uvicorn.Server(config).serve()
85
+
86
+
87
+ def _asgi(app: App) -> ASGIApp:
88
+ server = app.server
89
+ served = server.streamable_http_app(
90
+ stateless_http=True,
91
+ transport_security=TransportSecuritySettings(
92
+ enable_dns_rebinding_protection=False
93
+ ),
94
+ )
95
+ manager = server.session_manager
96
+ events = next(
97
+ (each for each in server.middleware if isinstance(each, Events)), None
98
+ )
99
+ mcp = AuthContextMiddleware(
100
+ manager.handle_request if events is None else events.asgi(manager)
101
+ )
102
+ platform = os.environ.get("HOLON_PLATFORM") == "1"
103
+
104
+ async def dispatch(scope: Scope, receive: Receive, send: Send) -> None:
105
+ if scope["type"] == "lifespan":
106
+ await served(scope, receive, send)
107
+ return
108
+ headers = scope["headers"]
109
+ scope["headers"] = [
110
+ (name, value)
111
+ for name, value in headers
112
+ if not name.startswith(b"x-holon-") and name != b"authorization"
113
+ ]
114
+ if not _MCP.fullmatch(scope["path"]):
115
+ frontend = app.frontend if scope["method"] in ("GET", "HEAD") else None
116
+ await _page(frontend, scope["path"])(scope, receive, send)
117
+ return
118
+ read = _admit(headers) if platform else ("", None)
119
+ if read is None:
120
+ # A context the waypoint could not have sent is a malformed request (RFC 9110 §15.5.1).
121
+ await _MALFORMED(scope, receive, send)
122
+ return
123
+ token, admitted = read
124
+ scope["user"] = UnauthenticatedUser()
125
+ scope["auth"] = AuthCredentials()
126
+ if admitted is not None:
127
+ scope["user"] = AuthenticatedUser(admitted)
128
+ scope["auth"] = AuthCredentials(admitted.scopes)
129
+ request = _Request(token)
130
+ current = _request.set(request)
131
+ # The SDK's server span parents on params._meta, else on this context: the caller's trace headers.
132
+ trace = tracing.attach(propagate.extract(Headers(scope=scope)))
133
+ try:
134
+ await mcp(scope, receive, send)
135
+ finally:
136
+ request.ended = True
137
+ tracing.detach(trace)
138
+ _request.reset(current)
139
+
140
+ return dispatch
141
+
142
+
143
+ class _Principal(BaseModel, strict=True):
144
+ iss: str | None = None
145
+ sub: str | None = None
146
+ client_id: str | None = None
147
+ scope: str | None = None
148
+ claims: dict[str, Any] | None = None
149
+ act: dict[str, Any] | None = None
150
+
151
+
152
+ class _Claims(BaseModel, strict=True):
153
+ principal: _Principal | None = None
154
+
155
+
156
+ def _admit(
157
+ headers: list[tuple[bytes, bytes]],
158
+ ) -> tuple[str, AccessToken | None] | None:
159
+ """The request's context and who it comes from, or None when the waypoint's headers are malformed.
160
+
161
+ The waypoint names the calling app of the session, a lifecycle hook's job as its app.
162
+ """
163
+ contexts = [value for name, value in headers if name == b"x-holon-context"]
164
+ callers = [value for name, value in headers if name == b"x-holon-caller"]
165
+ if len(contexts) > 1 or len(callers) > 1:
166
+ return None
167
+ token, principal, caller = "", None, None
168
+ if contexts:
169
+ token = contexts[0].decode("latin-1")
170
+ if (form := _CONTEXT.fullmatch(token)) is None:
171
+ return None
172
+ payload = form[1] + "=" * (-len(form[1]) % 4)
173
+ try:
174
+ claims = _Claims.model_validate_json(base64.urlsafe_b64decode(payload))
175
+ except ValueError:
176
+ return None
177
+ principal = claims.principal
178
+ if callers and (caller := _CALLER.fullmatch(callers[0].decode("latin-1"))) is None:
179
+ return None
180
+ if principal is None and caller is None:
181
+ return token, None
182
+ extra: dict[str, Any] = {}
183
+ if caller is not None:
184
+ extra["caller"] = {"app": caller[2], "session": caller[1]}
185
+ if principal is not None:
186
+ extra |= {"iss": principal.iss or "", "sub": principal.sub or ""}
187
+ if principal.claims is not None:
188
+ extra["claims"] = principal.claims
189
+ if principal.act is not None:
190
+ extra["act"] = principal.act
191
+ scope = (principal.scope if principal else None) or ""
192
+ return token, AccessToken(
193
+ token=token,
194
+ client_id=(principal.client_id if principal else None) or "",
195
+ scopes=[each for each in scope.split(" ") if each],
196
+ subject=extra.get("sub"),
197
+ claims=extra,
198
+ )
199
+
200
+
201
+ def _page(directory: Path | None, path: str) -> Response:
202
+ if directory is None or "/." in path or "\\" in path:
203
+ return Response(status_code=404)
204
+ try:
205
+ root = directory.resolve()
206
+ name = (root / path.lstrip("/")).resolve()
207
+ if name.is_dir():
208
+ name = (name / "index.html").resolve()
209
+ if name.is_relative_to(root) and name.is_file():
210
+ kind = mimetypes.guess_type(name)[0] or "application/octet-stream"
211
+ return FileResponse(
212
+ name, media_type=kind, headers={"x-content-type-options": "nosniff"}
213
+ )
214
+ except (OSError, ValueError):
215
+ pass
216
+ return Response(status_code=404)
217
+
218
+
219
+ if __name__ == "__main__":
220
+ asyncio.run(serve(load(sys.argv[1])))
@@ -4,13 +4,21 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "holon-sh"
7
- version = "0.0.1.dev13"
7
+ version = "0.0.1.dev15"
8
8
  description = "Typed MCP clients and the caller of an MCP request"
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
11
11
  license-files = ["LICENSE"]
12
12
  requires-python = ">=3.11"
13
- dependencies = ["mcp>=2.3,<3", "jsonschema>=4.26,<5", "httpx2>=2.10,<3"]
13
+ dependencies = [
14
+ "mcp>=2.3,<3",
15
+ "jsonschema>=4.26,<5",
16
+ "httpx2>=2.10,<3",
17
+ "opentelemetry-api>=1.28,<2",
18
+ "pydantic>=2.12,<3",
19
+ "starlette>=0.48,<2",
20
+ "uvicorn>=0.31.1,<1",
21
+ ]
14
22
 
15
23
  [project.urls]
16
24
  Repository = "https://github.com/holon-sh/sdk-py"
@@ -1,4 +1,5 @@
1
1
  import asyncio
2
+ import base64
2
3
  import json
3
4
  import socket
4
5
  import sys
@@ -9,9 +10,6 @@ import httpx2
9
10
  import pytest
10
11
  import uvicorn
11
12
  from mcp.server import MCPServer, Server
12
- from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
13
- from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
14
- from mcp.server.auth.provider import AccessToken
15
13
  from mcp.server.streamable_http import CONTENT_TYPE_JSON, CONTENT_TYPE_SSE
16
14
  from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
17
15
  from mcp.shared.exceptions import MCPError
@@ -27,12 +25,13 @@ from mcp.types import (
27
25
  CallToolResult,
28
26
  ErrorData,
29
27
  )
30
- from pydantic import BaseModel, TypeAdapter
28
+ from pydantic import BaseModel
31
29
  from starlette.applications import Starlette
32
30
  from starlette.routing import Mount
33
31
 
34
32
  from holon.client import Apps
35
- from holon.ext.events import Events, NoCompatibleDeliveryMode, _server
33
+ from holon.ext.events import Events, EventType, NoCompatibleDeliveryMode, _server
34
+ from holon.serve import App, _asgi
36
35
 
37
36
  IDENTITY = {"name": "watcher", "version": "1", "requires": {"boards": {}}}
38
37
 
@@ -54,10 +53,13 @@ def asynchronous(test):
54
53
  return run
55
54
 
56
55
 
57
- def declare(events=None, **hooks):
56
+ def declare(events=None, **hooks) -> tuple[Events, EventType[Board, Change]]:
58
57
  events = events or Events()
59
58
  return events, events.event(
60
- "board.changed", input_schema=Board, payload_schema=Change, **hooks
59
+ "board.changed",
60
+ input_schema=Board,
61
+ payload_schema=Change.model_json_schema(),
62
+ **hooks,
61
63
  )
62
64
 
63
65
 
@@ -90,32 +92,24 @@ async def serve(app, port=0):
90
92
  return sock.getsockname()[1], stop
91
93
 
92
94
 
93
- # An `x-user` header stands in for the caller Holon admits.
95
+ @pytest.fixture(autouse=True)
96
+ def inside_holon(monkeypatch):
97
+ monkeypatch.setenv("HOLON_PLATFORM", "1")
98
+
99
+
94
100
  def mounted(events):
95
- server = MCPServer("boards", extensions=[events], middleware=[events])
96
- server.streamable_http_app(stateless_http=True)
97
- manager = server.session_manager
98
- app = AuthContextMiddleware(
99
- Starlette(
100
- routes=[Mount("/mcp", app=events.asgi(manager))],
101
- lifespan=lambda app: manager.run(),
102
- )
103
- )
101
+ return _asgi(App(MCPServer("boards", extensions=[events], middleware=[events])))
104
102
 
105
- async def admitted(scope, receive, send):
106
- if user := dict(scope.get("headers", [])).get(b"x-user"):
107
- claims = {"iss": "https://id.example", "sub": user.decode()}
108
- token = AccessToken(
109
- token="t",
110
- client_id="c",
111
- scopes=[],
112
- subject=user.decode(),
113
- claims=claims,
114
- )
115
- scope = {**scope, "user": AuthenticatedUser(token)}
116
- await app(scope, receive, send)
117
103
 
118
- return admitted
104
+ def signed_in(user):
105
+ principal = {"iss": "https://id.example", "sub": user, "client_id": "c"}
106
+ claims = {
107
+ "exp": 1900000000,
108
+ "aud": "https://boards.example",
109
+ "principal": principal,
110
+ }
111
+ payload = base64.urlsafe_b64encode(json.dumps(claims).encode()).rstrip(b"=")
112
+ return f"e30.{payload.decode()}.signature"
119
113
 
120
114
 
121
115
  @asynccontextmanager
@@ -127,10 +121,11 @@ async def served(events):
127
121
  await stop()
128
122
 
129
123
 
130
- def client(port, user=None, path="/mcp/"):
124
+ def client(port, user=None, path="/mcp"):
131
125
  binding = {"endpoint": f"http://127.0.0.1:{port}{path}"}
132
126
  if user:
133
- binding["http_client"] = lambda: httpx2.AsyncClient(headers={"x-user": user})
127
+ headers = {"x-holon-context": signed_in(user)}
128
+ binding["http_client"] = lambda: httpx2.AsyncClient(headers=headers)
134
129
  return Apps(IDENTITY, {}, {"boards": binding}).boards.ext.events
135
130
 
136
131
 
@@ -157,7 +152,7 @@ def request(method, params, id=1):
157
152
 
158
153
 
159
154
  async def call(http, port, method, params):
160
- url = f"http://127.0.0.1:{port}/mcp/"
155
+ url = f"http://127.0.0.1:{port}/mcp"
161
156
  return (await http.post(url, **request(method, params))).json()
162
157
 
163
158
 
@@ -300,6 +295,16 @@ async def test_a_subscription_the_app_ends_is_sent_what_was_emitted_to_it_unless
300
295
 
301
296
  @asynchronous
302
297
  async def test_the_messages_on_the_wire_are_the_sketchs():
298
+ recursive = {
299
+ "$ref": "#/$defs/Node",
300
+ "$defs": {
301
+ "Node": {
302
+ "type": "object",
303
+ "properties": {"child": {"$ref": "#/$defs/Node"}},
304
+ }
305
+ },
306
+ }
307
+
303
308
  def shaped(context, event, arguments):
304
309
  if event.data.text == "bad":
305
310
  raise ValueError("cannot be shaped")
@@ -313,14 +318,17 @@ async def test_the_messages_on_the_wire_are_the_sketchs():
313
318
  events.event(
314
319
  "board.locked",
315
320
  input_schema=Board,
316
- payload_schema=Change,
321
+ payload_schema=recursive,
317
322
  delivery=["poll"],
318
323
  authorize=lambda context, arguments: arguments.board != "secret",
319
324
  )
320
325
  async with served(events) as port, httpx2.AsyncClient(timeout=10) as http:
321
326
  discovered = await call(http, port, "server/discover", {})
322
327
  assert discovered["result"]["capabilities"]["events"] == {"listChanged": False}
323
- [listed, _] = (await call(http, port, "events/list", {}))["result"]["events"]
328
+ [listed, locked] = (await call(http, port, "events/list", {}))["result"][
329
+ "events"
330
+ ]
331
+ assert locked["payloadSchema"] == recursive
324
332
  assert listed == {
325
333
  "name": "board.changed",
326
334
  "description": "A board changed",
@@ -376,7 +384,7 @@ async def test_the_messages_on_the_wire_are_the_sketchs():
376
384
  ]:
377
385
  assert (await call(http, port, method, params))["error"]["code"] == code
378
386
 
379
- url, opened = f"http://127.0.0.1:{port}/mcp/", changed.cursor()
387
+ url, opened = f"http://127.0.0.1:{port}/mcp", changed.cursor()
380
388
  async with http.stream(
381
389
  "POST", url, **request("events/stream", changed_on("b1"), id=7)
382
390
  ) as stream:
@@ -517,8 +525,8 @@ async def test_where_push_cannot_be_served_a_subscription_polls(monkeypatch):
517
525
  @asynchronous
518
526
  async def test_a_subscription_from_the_cursor_read_with_a_snapshot_hears_every_change_after_it_on_a_json_endpoint():
519
527
  events, said = Events(), []
520
- changed = events.event(
521
- "board.changed", input_schema=Board, payload_schema=TypeAdapter(Change)
528
+ changed: EventType[Board, Change] = events.event(
529
+ "board.changed", input_schema=Board, payload_schema=Change.model_json_schema()
522
530
  )
523
531
 
524
532
  def tell(text):
@@ -16,6 +16,15 @@ def test_generated_namespace_combines_app_types_with_installed_runtime(tmp_path)
16
16
  import holon
17
17
  import holon.client
18
18
  from holon.apps import apps, Inputs, Outputs
19
+ from holon.ext.events import Events, EventType
20
+
21
+ def emit() -> None:
22
+ changed: EventType[dict[str, str], dict[str, str]] = Events().event(
23
+ "board.changed", input_schema=dict[str, str],
24
+ payload_schema={"type": "object", "additionalProperties": {"type": "string"}},
25
+ )
26
+ changed.emit({"text": "hello"})
27
+ changed.emit("wrong") # type: ignore[arg-type]
19
28
 
20
29
  async def run() -> float:
21
30
  arguments: Inputs.orders.read = {
@@ -0,0 +1,379 @@
1
+ import asyncio
2
+ import base64
3
+ import json
4
+ import os
5
+ import signal
6
+ import socket
7
+ import subprocess
8
+ import sys
9
+ from contextlib import asynccontextmanager
10
+ from functools import wraps
11
+
12
+ import httpx2
13
+ import pytest
14
+ import uvicorn
15
+ from mcp.server import MCPServer
16
+ from mcp.server.auth.middleware.auth_context import get_access_token
17
+ from mcp.server.mcpserver import Context
18
+ from mcp.shared.exceptions import MCPError
19
+ from opentelemetry import propagate
20
+ from starlette.datastructures import Headers
21
+ from starlette.responses import RedirectResponse, Response
22
+
23
+ from holon.client import Apps
24
+ from holon.context import Caller, Principal, RequestContext, _request, get_context
25
+ from holon.serve import App, _asgi
26
+
27
+ PERSON = {"iss": "https://id.example", "sub": "ann", "client_id": "web"}
28
+ PROFILE = {"email": "ann@example.com", "email_verified": True}
29
+ REPORTER = "session/reporter"
30
+ TRACEPARENT = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
31
+ IDENTITY = {"name": "caller", "version": "1", "requires": {"peer": {}}}
32
+
33
+
34
+ def asynchronous(test):
35
+ @wraps(test)
36
+ def run(*args, **kwargs):
37
+ asyncio.run(asyncio.wait_for(test(*args, **kwargs), timeout=20))
38
+
39
+ return run
40
+
41
+
42
+ def context(**payload):
43
+ claims = {"exp": 1900000060.25, "aud": ["https://holon.example"], **payload}
44
+ encoded = base64.urlsafe_b64encode(json.dumps(claims).encode()).rstrip(b"=")
45
+ return f"e30.{encoded.decode()}.signature"
46
+
47
+
48
+ async def until(condition):
49
+ while not condition():
50
+ await asyncio.sleep(0.01)
51
+
52
+
53
+ @asynccontextmanager
54
+ async def served(app):
55
+ sock = socket.create_server(("127.0.0.1", 0))
56
+ server = uvicorn.Server(uvicorn.Config(app, log_level="warning"))
57
+ task = asyncio.create_task(server.serve(sockets=[sock]))
58
+ await until(lambda: server.started)
59
+ try:
60
+ yield f"http://127.0.0.1:{sock.getsockname()[1]}"
61
+ finally:
62
+ server.should_exit = True
63
+ await task
64
+
65
+
66
+ async def call(url, tool, headers):
67
+ binding = {
68
+ "endpoint": url,
69
+ "http_client": lambda: httpx2.AsyncClient(headers=headers),
70
+ }
71
+ result = await Apps(IDENTITY, {}, {"peer": binding}).peer.call_tool(tool)
72
+ assert not result.is_error, result
73
+ return result
74
+
75
+
76
+ def inspector(seen):
77
+ server = MCPServer("inspector")
78
+
79
+ @server.tool()
80
+ async def inspect(ctx: Context) -> str:
81
+ trace = {}
82
+ propagate.inject(trace)
83
+ seen.append(
84
+ (
85
+ get_context(),
86
+ get_access_token(),
87
+ set(ctx.headers),
88
+ trace.get("traceparent"),
89
+ )
90
+ )
91
+ return "seen"
92
+
93
+ return server
94
+
95
+
96
+ @asynchronous
97
+ async def test_inside_holon_a_tool_sees_whom_the_waypoint_admitted_and_not_the_headers_that_said_so(
98
+ monkeypatch,
99
+ ):
100
+ monkeypatch.setenv("HOLON_PLATFORM", "1")
101
+ signed_in = context(
102
+ principal={
103
+ **PERSON,
104
+ "scope": " read write ",
105
+ "claims": PROFILE,
106
+ "act": {"sub": "agent"},
107
+ },
108
+ flowId="flow",
109
+ )
110
+ ann = Principal(
111
+ "https://id.example", "ann", "web", ["read", "write"], PROFILE, {"sub": "agent"}
112
+ )
113
+ seen = []
114
+ async with served(_asgi(App(inspector(seen)))) as origin:
115
+ for path, headers, expected in [
116
+ ("/mcp", {"x-holon-context": signed_in}, RequestContext(ann, None)),
117
+ (
118
+ "/mcp/inspector",
119
+ {"x-holon-context": signed_in, "x-holon-caller": REPORTER},
120
+ RequestContext(ann, Caller("reporter", "session")),
121
+ ),
122
+ (
123
+ "/mcp",
124
+ {"x-holon-caller": REPORTER},
125
+ RequestContext(None, Caller("reporter", "session")),
126
+ ),
127
+ ("/mcp", {"x-holon-context": context()}, RequestContext(None, None)),
128
+ ]:
129
+ forged = {"x-holon-other": "forged", "authorization": "Bearer forged"}
130
+ headers = {**headers, **forged, "traceparent": TRACEPARENT}
131
+ await call(origin + path, "inspect", headers)
132
+ admitted, token, names, traceparent = seen.pop()
133
+ assert admitted == expected
134
+ assert not {name for name in names if name.startswith("x-holon-")}
135
+ assert "authorization" not in names
136
+ assert traceparent == TRACEPARENT
137
+ if expected == RequestContext(None, None):
138
+ assert token is None
139
+ continue
140
+ assert token.token == headers.get("x-holon-context", "")
141
+
142
+
143
+ def token(payload):
144
+ encoded = base64.urlsafe_b64encode(payload.encode()).rstrip(b"=")
145
+ return f"e30.{encoded.decode()}.signature"
146
+
147
+
148
+ @asynchronous
149
+ async def test_a_malformed_context_is_a_bad_request(monkeypatch):
150
+ monkeypatch.setenv("HOLON_PLATFORM", "1")
151
+ person = {**PERSON, "act": {"sub": "agent"}}
152
+ seen = []
153
+ async with served(_asgi(App(inspector(seen)))) as origin:
154
+ for headers in [
155
+ [("x-holon-context", context()), ("x-holon-context", context())],
156
+ [("x-holon-caller", REPORTER), ("x-holon-caller", REPORTER)],
157
+ [("x-holon-caller", "reporter")],
158
+ [("x-holon-context", "header.claims")],
159
+ [("x-holon-context", "e30.e30=.signature")],
160
+ [("x-holon-context", token("person"))],
161
+ [("x-holon-context", token("[]"))],
162
+ [("x-holon-context", token("null"))],
163
+ [("x-holon-context", context(principal="user"))],
164
+ [("x-holon-context", context(principal={"iss": 1}))],
165
+ [("x-holon-context", context(principal={"claims": []}))],
166
+ [("x-holon-context", context(principal={**person, "act": ["agent"]}))],
167
+ ]:
168
+ async with httpx2.AsyncClient() as client:
169
+ response = await client.post(
170
+ origin + "/mcp", headers=headers, content="{}"
171
+ )
172
+ assert (response.status_code, response.text) == (
173
+ 400,
174
+ "Malformed Holon context\n",
175
+ ), headers
176
+ assert seen == []
177
+
178
+
179
+ @asynchronous
180
+ async def test_outside_holon_the_same_headers_make_an_anonymous_request(monkeypatch):
181
+ monkeypatch.delenv("HOLON_PLATFORM", raising=False)
182
+ seen = []
183
+ async with served(_asgi(App(inspector(seen)))) as origin:
184
+ headers = {
185
+ "x-holon-context": context(principal=PERSON),
186
+ "x-holon-caller": REPORTER,
187
+ "authorization": "Bearer forged",
188
+ }
189
+ await call(origin + "/mcp", "inspect", headers)
190
+ [(admitted, token, names, _)] = seen
191
+ assert (admitted, token) == (RequestContext(None, None), None)
192
+ assert not names & {"x-holon-context", "x-holon-caller", "authorization"}
193
+
194
+
195
+ @asynchronous
196
+ async def test_a_peer_call_carries_the_context_until_its_request_ends_and_the_apps_token_always(
197
+ monkeypatch,
198
+ ):
199
+ monkeypatch.setenv("HOLON_PLATFORM", "1")
200
+ monkeypatch.setenv("PEER_MCP_TOKEN", "secret")
201
+ peer, received = MCPServer("peer"), []
202
+
203
+ @peer.tool()
204
+ def ping() -> str:
205
+ return "pong"
206
+
207
+ answer = peer.streamable_http_app(stateless_http=True)
208
+
209
+ async def recording(scope, receive, send):
210
+ if scope["type"] == "http":
211
+ headers = Headers(scope=scope)
212
+ received.append(
213
+ (headers.get("x-holon-context"), headers.get("authorization"))
214
+ )
215
+ await answer(scope, receive, send)
216
+
217
+ server, apps, phases, later = MCPServer("caller"), Apps(IDENTITY, {}), [], []
218
+
219
+ @server.tool()
220
+ async def relay() -> str:
221
+ await apps.peer.call_tool("ping")
222
+ phases.append(len(received))
223
+ bound = {"endpoint": os.environ["PEER_MCP_URL"]}
224
+ await Apps(IDENTITY, {}, {"peer": bound}).peer.call_tool("ping")
225
+ phases.append(len(received))
226
+ request = _request.get()
227
+
228
+ async def afterwards():
229
+ await until(lambda: request.ended)
230
+ await apps.peer.call_tool("ping")
231
+
232
+ later.append(asyncio.create_task(afterwards()))
233
+ return "relayed"
234
+
235
+ token = context(principal=PERSON)
236
+ async with served(recording) as peer_origin, served(_asgi(App(server))) as origin:
237
+ monkeypatch.setenv("PEER_MCP_URL", peer_origin + "/mcp")
238
+ await call(origin + "/mcp", "relay", {"x-holon-context": token})
239
+ await later[0]
240
+ during, bound = received[: phases[0]], received[phases[0] : phases[1]]
241
+ assert set(during) == {(token, "Bearer secret")}
242
+ assert set(bound) == {(None, None)}
243
+ assert set(received[phases[1] :]) == {(None, "Bearer secret")}
244
+
245
+
246
+ @asynchronous
247
+ async def test_a_peer_that_redirects_is_not_followed(monkeypatch):
248
+ reached = []
249
+
250
+ async def elsewhere(scope, receive, send):
251
+ if scope["type"] == "http":
252
+ reached.append(scope["path"])
253
+ await Response("followed")(scope, receive, send)
254
+
255
+ async with served(elsewhere) as target:
256
+
257
+ async def moved(scope, receive, send):
258
+ if scope["type"] == "http":
259
+ await RedirectResponse(target + "/mcp", 307)(scope, receive, send)
260
+
261
+ async with served(moved) as origin:
262
+ monkeypatch.setenv("PEER_MCP_URL", origin + "/mcp")
263
+ with pytest.raises(MCPError):
264
+ await Apps(IDENTITY, {}).peer.call_tool("ping")
265
+ assert reached == []
266
+
267
+
268
+ @asynchronous
269
+ async def test_the_frontend_serves_its_files_and_nothing_hidden_or_outside_it(
270
+ tmp_path,
271
+ ):
272
+ web = tmp_path / "web"
273
+ (web / "nested").mkdir(parents=True)
274
+ (web / "index.html").write_text("<p>Home</p>")
275
+ (web / "nested/index.html").write_text("<p>Nested</p>")
276
+ (web / "style.css").write_text("p {}")
277
+ (web / "data.json").write_text("{}")
278
+ (web / ".private").write_text("Hidden")
279
+ (tmp_path / "secret").write_text("Outside")
280
+ (web / "escape").symlink_to(tmp_path / "secret")
281
+ (web / "linked.css").symlink_to(web / "style.css")
282
+ os.mkfifo(web / "pipe")
283
+ app = _asgi(App(MCPServer("site"), web))
284
+ async with httpx2.AsyncClient(
285
+ transport=httpx2.ASGITransport(app=app), base_url="http://app"
286
+ ) as http:
287
+ for path, body, kind in [
288
+ ("/", "<p>Home</p>", "text/html; charset=utf-8"),
289
+ ("/index.html", "<p>Home</p>", "text/html; charset=utf-8"),
290
+ ("/nested", "<p>Nested</p>", "text/html; charset=utf-8"),
291
+ ("/nested/", "<p>Nested</p>", "text/html; charset=utf-8"),
292
+ ("/style.css", "p {}", "text/css; charset=utf-8"),
293
+ ("/linked.css", "p {}", "text/css; charset=utf-8"),
294
+ ("/data.json", "{}", "application/json"),
295
+ ]:
296
+ response = await http.get(path)
297
+ assert (response.status_code, response.text) == (200, body), path
298
+ assert response.headers["content-type"] == kind
299
+ assert response.headers["x-content-type-options"] == "nosniff"
300
+ head = await http.head("/style.css")
301
+ assert (head.status_code, head.content) == (200, b"")
302
+ for path in [
303
+ "/.private",
304
+ "/%2eprivate",
305
+ "/%2E%2E/secret",
306
+ "/escape",
307
+ "/pipe",
308
+ "/missing",
309
+ ]:
310
+ assert (await http.get(path)).status_code == 404, path
311
+ assert (await http.post("/")).status_code == 404
312
+ async with httpx2.AsyncClient(
313
+ transport=httpx2.ASGITransport(app=_asgi(App(MCPServer("bare")))),
314
+ base_url="http://app",
315
+ ) as http:
316
+ assert (await http.get("/")).status_code == 404
317
+
318
+
319
+ def test_python_m_holon_serve_runs_an_entry_with_a_16_kib_context_and_stops_on_sigterm(
320
+ tmp_path,
321
+ ):
322
+ (tmp_path / "src").mkdir()
323
+ (tmp_path / "web").mkdir()
324
+ (tmp_path / "web/index.html").write_text("<p>Home</p>")
325
+ (tmp_path / "src/server.py").write_text(
326
+ """from mcp.server import MCPServer
327
+ from holon.context import get_context
328
+
329
+ server = MCPServer("large")
330
+ frontend = "web"
331
+
332
+
333
+ @server.tool()
334
+ def subject() -> str:
335
+ return get_context().principal.subject
336
+ """
337
+ )
338
+ subject = "a" * 12200
339
+ token = context(principal={**PERSON, "sub": subject})
340
+ assert len(token) >= 16 * 1024
341
+ with socket.socket() as reserved:
342
+ reserved.bind(("127.0.0.1", 0))
343
+ port = reserved.getsockname()[1]
344
+ environment = {**os.environ, "HOLON_PLATFORM": "1", "PORT": str(port)}
345
+ process = subprocess.Popen(
346
+ [sys.executable, "-m", "holon.serve", "src/server.py"],
347
+ cwd=tmp_path,
348
+ env=environment,
349
+ stderr=subprocess.PIPE,
350
+ text=True,
351
+ )
352
+
353
+ async def exercise():
354
+ origin = f"http://127.0.0.1:{port}"
355
+ async with httpx2.AsyncClient() as http:
356
+ while True:
357
+ try:
358
+ home = await http.get(origin)
359
+ break
360
+ except httpx2.ConnectError:
361
+ await asyncio.sleep(0.05)
362
+ assert home.text == "<p>Home</p>"
363
+ reader, writer = await asyncio.open_connection("127.0.0.1", port)
364
+ head = f"GET / HTTP/1.1\r\nhost: app\r\nx-holon-context: {token}\r\n\r\n"
365
+ for piece in [head[:-2], head[-2:]]:
366
+ writer.write(piece.encode())
367
+ await writer.drain()
368
+ await asyncio.sleep(0.1)
369
+ assert (await reader.readline()).startswith(b"HTTP/1.1 200")
370
+ writer.close()
371
+ result = await call(origin + "/mcp", "subject", {"x-holon-context": token})
372
+ assert result.structured_content == {"result": subject}
373
+
374
+ try:
375
+ asyncio.run(asyncio.wait_for(exercise(), timeout=20))
376
+ finally:
377
+ process.send_signal(signal.SIGTERM)
378
+ _, errors = process.communicate(timeout=10)
379
+ assert "Application shutdown complete" in errors
File without changes
File without changes