nativecluster 0.1.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.
- nativecluster/__init__.py +139 -0
- nativecluster/_firings.py +185 -0
- nativecluster/_gate.py +312 -0
- nativecluster/_host.py +337 -0
- nativecluster/_hostsock.py +105 -0
- nativecluster/_launch.py +203 -0
- nativecluster/_models.py +639 -0
- nativecluster/_origin.py +217 -0
- nativecluster/_serve.py +227 -0
- nativecluster/_ticket.py +209 -0
- nativecluster/transport.py +576 -0
- nativecluster-0.1.0.dist-info/METADATA +107 -0
- nativecluster-0.1.0.dist-info/RECORD +16 -0
- nativecluster-0.1.0.dist-info/WHEEL +5 -0
- nativecluster-0.1.0.dist-info/licenses/LICENSE +202 -0
- nativecluster-0.1.0.dist-info/top_level.txt +1 -0
nativecluster/_origin.py
ADDED
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
"""What started a model call (spec/hostapi.v1.md, "The waiting line").
|
|
2
|
+
|
|
3
|
+
Nothing reaches a model without having been started by a person's request,
|
|
4
|
+
a firing of the app's schedules, or a job one of them started: every wait in
|
|
5
|
+
line carries that origin as its ticket, and the host checks it. The kit keeps
|
|
6
|
+
the origin in a context variable, the way the Go kit keeps it on a context:
|
|
7
|
+
the gate sets it for each request, and a firing's handler runs with the
|
|
8
|
+
firing's. Work moved to a thread of its own takes it along with bind().
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import contextlib
|
|
14
|
+
import contextvars
|
|
15
|
+
import threading
|
|
16
|
+
from dataclasses import dataclass
|
|
17
|
+
from typing import Any, Callable, Iterator, Optional, TypeVar
|
|
18
|
+
|
|
19
|
+
from ._ticket import Ticket
|
|
20
|
+
|
|
21
|
+
T = TypeVar("T")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
@dataclass(frozen=True)
|
|
25
|
+
class Origin:
|
|
26
|
+
"""What a model call is for, as its wait in line names it.
|
|
27
|
+
|
|
28
|
+
origin is "request" (a person's request: it waits in lane P, as a person
|
|
29
|
+
waiting), "firing" (a firing of the app's schedules) or "job" (long work
|
|
30
|
+
one of them started, which says what in source: "request", "firing", or
|
|
31
|
+
"resume" after the app started again); a firing's and a job's wait in
|
|
32
|
+
lane B, behind people. A job a person's request started that the person
|
|
33
|
+
waits for now (waits: an agent's turn at their screen) waits in lane P
|
|
34
|
+
while the host lets that request's turn last, and behind people after.
|
|
35
|
+
idle sends work to lane I: only on an idle Mac.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
origin: str
|
|
39
|
+
person: str = ""
|
|
40
|
+
request: str = ""
|
|
41
|
+
firing: str = ""
|
|
42
|
+
source: str = ""
|
|
43
|
+
idle: bool = False
|
|
44
|
+
waits: bool = False
|
|
45
|
+
|
|
46
|
+
def wire(self) -> dict:
|
|
47
|
+
"""The wait's ticket (sched.WireTicket)."""
|
|
48
|
+
out = {"origin": self.origin}
|
|
49
|
+
for key, value in (("from", self.source), ("person", self.person), ("firing", self.firing), ("request", self.request)):
|
|
50
|
+
if value:
|
|
51
|
+
out[key] = value
|
|
52
|
+
return out
|
|
53
|
+
|
|
54
|
+
@property
|
|
55
|
+
def lane(self) -> str:
|
|
56
|
+
if self.idle:
|
|
57
|
+
return "I"
|
|
58
|
+
if self.origin == "request" or (self.origin == "job" and self.source == "request" and self.waits):
|
|
59
|
+
return "P"
|
|
60
|
+
return "B"
|
|
61
|
+
|
|
62
|
+
@property
|
|
63
|
+
def job(self) -> bool:
|
|
64
|
+
return self.origin == "job"
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def for_request(ticket: Ticket) -> Origin:
|
|
68
|
+
"""The origin of a person's request, from its ticket (never the host's
|
|
69
|
+
own call)."""
|
|
70
|
+
if ticket.host:
|
|
71
|
+
raise ValueError("nativecluster: the host's own call is no person's request")
|
|
72
|
+
return Origin("request", person=ticket.person, request=ticket.id)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def for_firing(firing: Any) -> Origin:
|
|
76
|
+
"""The origin of a firing's work: it waits as the firing's person."""
|
|
77
|
+
return Origin("firing", person=firing.person, firing=firing.id)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def for_job(person: str = "", *, request: str = "", firing: str = "", resumed: bool = False, idle: bool = False,
|
|
81
|
+
waits: bool = False) -> Origin:
|
|
82
|
+
"""The origin of a long job (a whole book's translation) that outlives
|
|
83
|
+
what started it: a person's request (request, the ticket's id), a firing
|
|
84
|
+
(firing), or neither, resumed after the app started again. waits, for a
|
|
85
|
+
request's job, says its person waits for it now (an agent's turn): it
|
|
86
|
+
waits in their lane while the host lets that request's turn last."""
|
|
87
|
+
if resumed or not (request or firing):
|
|
88
|
+
return Origin("job", person=person, source="resume", idle=idle)
|
|
89
|
+
if firing:
|
|
90
|
+
return Origin("job", person=person, firing=firing, source="firing", idle=idle)
|
|
91
|
+
return Origin("job", person=person, request=request, source="request", idle=idle, waits=waits)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
_current: contextvars.ContextVar[Optional[Origin]] = contextvars.ContextVar("nativecluster_origin", default=None)
|
|
95
|
+
_conversation: contextvars.ContextVar[str] = contextvars.ContextVar("nativecluster_conversation", default="")
|
|
96
|
+
_away: contextvars.ContextVar[Optional[Callable[[str], None]]] = contextvars.ContextVar("nativecluster_away", default=None)
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
# _otherwise and _otherwise_conversation answer for model calls made where
|
|
100
|
+
# no origin or conversation was set: a thread the app did not start (an
|
|
101
|
+
# agent framework's own pool) carries none of the request's. None until the
|
|
102
|
+
# app names them (otherwise_acting_for).
|
|
103
|
+
_otherwise: Optional[Callable[[], Optional[Origin]]] = None
|
|
104
|
+
_otherwise_conversation: Optional[Callable[[], str]] = None
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def otherwise_acting_for(fn: Optional[Callable[[], Optional[Origin]]],
|
|
108
|
+
conversation: Optional[Callable[[], str]] = None) -> None:
|
|
109
|
+
"""Model calls made where no origin was set carry fn()'s, and where no
|
|
110
|
+
conversation was set conversation()'s, each asked at every call: for
|
|
111
|
+
work on threads the app does not start and cannot bind, such as an agent
|
|
112
|
+
framework's pool (the turn its person last asked for, say, as
|
|
113
|
+
for_job(person, request=..., waits=True), in the conversation it
|
|
114
|
+
continues, which keeps that conversation's reading warm). What is set
|
|
115
|
+
here still wins. None turns both off."""
|
|
116
|
+
global _otherwise, _otherwise_conversation
|
|
117
|
+
_otherwise, _otherwise_conversation = fn, conversation
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def current_origin() -> Optional[Origin]:
|
|
121
|
+
"""The origin model calls made here carry, None for none."""
|
|
122
|
+
o = _current.get()
|
|
123
|
+
if o is None and _otherwise is not None:
|
|
124
|
+
o = _otherwise()
|
|
125
|
+
return o
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
_carrying = False
|
|
129
|
+
_carrying_lock = threading.Lock()
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def carry_origin_into_threads() -> None:
|
|
133
|
+
"""From here on, a thread started and a task given to a thread pool
|
|
134
|
+
carry the origin and conversation of the code that started them, as
|
|
135
|
+
asyncio's tasks do (Python's own start with none): for an agent
|
|
136
|
+
framework that makes its model calls on threads and pools of its own.
|
|
137
|
+
Once per process; it stays on."""
|
|
138
|
+
global _carrying
|
|
139
|
+
with _carrying_lock:
|
|
140
|
+
if _carrying:
|
|
141
|
+
return
|
|
142
|
+
_carrying = True
|
|
143
|
+
import concurrent.futures.thread as pools
|
|
144
|
+
|
|
145
|
+
start = threading.Thread.start
|
|
146
|
+
submit = pools.ThreadPoolExecutor.submit
|
|
147
|
+
|
|
148
|
+
def carried_start(self: threading.Thread, *args: Any, **kwargs: Any) -> Any:
|
|
149
|
+
ctx, run = contextvars.copy_context(), self.run
|
|
150
|
+
self.run = lambda: ctx.run(run) # type: ignore[method-assign]
|
|
151
|
+
return start(self, *args, **kwargs)
|
|
152
|
+
|
|
153
|
+
def carried_submit(self: Any, fn: Callable[..., Any], /, *args: Any, **kwargs: Any) -> Any:
|
|
154
|
+
return submit(self, contextvars.copy_context().run, fn, *args, **kwargs)
|
|
155
|
+
|
|
156
|
+
threading.Thread.start = carried_start # type: ignore[method-assign]
|
|
157
|
+
pools.ThreadPoolExecutor.submit = carried_submit # type: ignore[method-assign]
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
@contextlib.contextmanager
|
|
161
|
+
def acting_for(origin: Optional[Origin]) -> Iterator[None]:
|
|
162
|
+
"""Model calls made inside carry origin."""
|
|
163
|
+
token = _current.set(origin)
|
|
164
|
+
try:
|
|
165
|
+
yield
|
|
166
|
+
finally:
|
|
167
|
+
_current.reset(token)
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
@contextlib.contextmanager
|
|
171
|
+
def when_away(fn: Optional[Callable[[str], None]]) -> Iterator[None]:
|
|
172
|
+
"""Model calls made inside tell fn the host's words, once, when their
|
|
173
|
+
wait in line is held because the cluster is out of reach (a computer
|
|
174
|
+
away from the office: the host's words explain that the answer can't
|
|
175
|
+
come yet): the wait goes on, and the call is answered when the cluster
|
|
176
|
+
is back. Threads carry it as they carry the origin
|
|
177
|
+
(carry_origin_into_threads)."""
|
|
178
|
+
token = _away.set(fn)
|
|
179
|
+
try:
|
|
180
|
+
yield
|
|
181
|
+
finally:
|
|
182
|
+
_away.reset(token)
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def current_away() -> Optional[Callable[[str], None]]:
|
|
186
|
+
return _away.get()
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
def current_conversation() -> str:
|
|
190
|
+
c = _conversation.get()
|
|
191
|
+
if not c and _otherwise_conversation is not None:
|
|
192
|
+
c = _otherwise_conversation() or ""
|
|
193
|
+
return c
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
@contextlib.contextmanager
|
|
197
|
+
def conversation(id: str) -> Iterator[None]:
|
|
198
|
+
"""Model calls made inside continue one conversation: an opaque id of
|
|
199
|
+
the app's (a chat's, a job's; never words), which with the person and
|
|
200
|
+
the task names the warm sequence the engine keeps for it."""
|
|
201
|
+
token = _conversation.set(id)
|
|
202
|
+
try:
|
|
203
|
+
yield
|
|
204
|
+
finally:
|
|
205
|
+
_conversation.reset(token)
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
def bind(fn: Callable[..., T]) -> Callable[..., T]:
|
|
209
|
+
"""fn, to run with the origin and conversation of here, on whatever
|
|
210
|
+
thread calls it: a thread does not take them along by itself."""
|
|
211
|
+
ctx = contextvars.copy_context()
|
|
212
|
+
|
|
213
|
+
def bound(*args: Any, **kwargs: Any) -> T:
|
|
214
|
+
# A copy per call: one context cannot be entered on two threads at once.
|
|
215
|
+
return ctx.copy().run(fn, *args, **kwargs)
|
|
216
|
+
|
|
217
|
+
return bound
|
nativecluster/_serve.py
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
"""Serving on the app's socket (spec/hostapi.v1.md, "Starting an app"; the
|
|
2
|
+
Go kit's Serve).
|
|
3
|
+
|
|
4
|
+
run_wsgi and run_asgi are an app's main: they answer `<program> manifest`
|
|
5
|
+
with the manifest the program carries, read what the host handed the app,
|
|
6
|
+
serve it on the socket the host names behind the gate, and leave when the
|
|
7
|
+
host stops the app (SIGTERM) or leaves. serve_wsgi needs nothing but Python
|
|
8
|
+
itself; serve_asgi runs uvicorn, which the app carries.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import io
|
|
14
|
+
import os
|
|
15
|
+
import signal
|
|
16
|
+
import socket
|
|
17
|
+
import socketserver
|
|
18
|
+
import sys
|
|
19
|
+
import threading
|
|
20
|
+
from typing import Any, Callable, Optional, Union
|
|
21
|
+
from wsgiref.simple_server import ServerHandler, WSGIRequestHandler
|
|
22
|
+
|
|
23
|
+
from ._gate import Gate, WSGIGate
|
|
24
|
+
from ._launch import EXIT_WITH_PARENT_ENV, Launch, NotBehindHost, answer_manifest, launch, watch_parent
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def listen(path: str) -> socket.socket:
|
|
28
|
+
"""The app's socket, bound and listening, readable and writable by this
|
|
29
|
+
user only; a stale file from an earlier run is removed first."""
|
|
30
|
+
try:
|
|
31
|
+
os.remove(path)
|
|
32
|
+
except FileNotFoundError:
|
|
33
|
+
pass
|
|
34
|
+
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
|
35
|
+
try:
|
|
36
|
+
sock.bind(path)
|
|
37
|
+
os.chmod(path, 0o600)
|
|
38
|
+
sock.listen(128)
|
|
39
|
+
except BaseException:
|
|
40
|
+
sock.close()
|
|
41
|
+
raise
|
|
42
|
+
return sock
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _exits_with_parent() -> bool:
|
|
46
|
+
return os.environ.get(EXIT_WITH_PARENT_ENV) == "1"
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
# --- WSGI, on Python alone ---
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class _Dechunked(io.RawIOBase):
|
|
53
|
+
"""A request body sent in chunks, read as the bytes it carries."""
|
|
54
|
+
|
|
55
|
+
def __init__(self, rfile: Any) -> None:
|
|
56
|
+
self._f = rfile
|
|
57
|
+
self._left = 0
|
|
58
|
+
self._done = False
|
|
59
|
+
|
|
60
|
+
def readable(self) -> bool:
|
|
61
|
+
return True
|
|
62
|
+
|
|
63
|
+
def readinto(self, b: Any) -> int:
|
|
64
|
+
if self._done:
|
|
65
|
+
return 0
|
|
66
|
+
if self._left == 0:
|
|
67
|
+
try:
|
|
68
|
+
size = int(self._f.readline(1026).split(b";", 1)[0].strip() or b"0", 16)
|
|
69
|
+
except ValueError:
|
|
70
|
+
size = 0
|
|
71
|
+
if size <= 0:
|
|
72
|
+
while self._f.readline(65537) not in (b"\r\n", b"\n", b""):
|
|
73
|
+
pass # trailers
|
|
74
|
+
self._done = True
|
|
75
|
+
return 0
|
|
76
|
+
self._left = size
|
|
77
|
+
data = self._f.read(min(len(b), self._left))
|
|
78
|
+
if not data:
|
|
79
|
+
self._done = True
|
|
80
|
+
return 0
|
|
81
|
+
b[: len(data)] = data
|
|
82
|
+
self._left -= len(data)
|
|
83
|
+
if self._left == 0:
|
|
84
|
+
self._f.readline(3)
|
|
85
|
+
return len(data)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
class _Limited(io.RawIOBase):
|
|
89
|
+
"""A request body of a known length: read() ends at its end, never at
|
|
90
|
+
the connection's, which the host keeps open."""
|
|
91
|
+
|
|
92
|
+
def __init__(self, rfile: Any, n: int) -> None:
|
|
93
|
+
self._f = rfile
|
|
94
|
+
self._left = n
|
|
95
|
+
|
|
96
|
+
def readable(self) -> bool:
|
|
97
|
+
return True
|
|
98
|
+
|
|
99
|
+
def readinto(self, b: Any) -> int:
|
|
100
|
+
if self._left <= 0:
|
|
101
|
+
return 0
|
|
102
|
+
data = self._f.read(min(len(b), self._left))
|
|
103
|
+
b[: len(data)] = data
|
|
104
|
+
self._left -= len(data)
|
|
105
|
+
return len(data)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
class _Handler(WSGIRequestHandler):
|
|
109
|
+
def log_message(self, format: str, *args: Any) -> None:
|
|
110
|
+
pass # the host keeps the request log; an app logs no paths it was not asked to
|
|
111
|
+
|
|
112
|
+
def handle(self) -> None:
|
|
113
|
+
self.raw_requestline = self.rfile.readline(65537)
|
|
114
|
+
if len(self.raw_requestline) > 65536:
|
|
115
|
+
self.requestline = self.request_version = self.command = ""
|
|
116
|
+
self.send_error(414)
|
|
117
|
+
return
|
|
118
|
+
if not self.parse_request():
|
|
119
|
+
return
|
|
120
|
+
if self.headers.get("Transfer-Encoding", "").lower() == "chunked":
|
|
121
|
+
stdin: Any = io.BufferedReader(_Dechunked(self.rfile))
|
|
122
|
+
else:
|
|
123
|
+
try:
|
|
124
|
+
n = int(self.headers.get("Content-Length") or 0)
|
|
125
|
+
except ValueError:
|
|
126
|
+
n = 0
|
|
127
|
+
stdin = io.BufferedReader(_Limited(self.rfile, max(n, 0)))
|
|
128
|
+
handler = ServerHandler(stdin, self.wfile, self.get_stderr(), self.get_environ(), multithread=True)
|
|
129
|
+
handler.request_handler = self
|
|
130
|
+
handler.run(self.server.get_app()) # type: ignore[attr-defined]
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
class _UnixWSGIServer(socketserver.ThreadingMixIn, socketserver.UnixStreamServer):
|
|
134
|
+
daemon_threads = True
|
|
135
|
+
|
|
136
|
+
def __init__(self, sock: socket.socket, app: Callable) -> None:
|
|
137
|
+
socketserver.BaseServer.__init__(self, sock.getsockname(), _Handler)
|
|
138
|
+
self.socket = sock
|
|
139
|
+
self._app = app
|
|
140
|
+
self.base_environ = {"SERVER_NAME": "host", "SERVER_PORT": "0", "GATEWAY_INTERFACE": "CGI/1.1",
|
|
141
|
+
"SCRIPT_NAME": "", "SERVER_SOFTWARE": "nativecluster"}
|
|
142
|
+
|
|
143
|
+
def get_request(self) -> Any:
|
|
144
|
+
conn, _ = self.socket.accept()
|
|
145
|
+
return conn, ("host", 0)
|
|
146
|
+
|
|
147
|
+
def get_app(self) -> Callable:
|
|
148
|
+
return self._app
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def serve_wsgi(app: Callable, *, on_wake: Optional[Callable] = None, on_tick: Optional[Callable] = None,
|
|
152
|
+
launched: Optional[Launch] = None, stop: Optional[threading.Event] = None) -> None:
|
|
153
|
+
"""Serves a WSGI app behind the gate on the launch's socket until the
|
|
154
|
+
host stops the app (SIGTERM), leaves, or stop is set."""
|
|
155
|
+
l = launched or launch()
|
|
156
|
+
sock = listen(l.app_socket)
|
|
157
|
+
server = _UnixWSGIServer(sock, WSGIGate(app, l.ticket_key, on_wake=on_wake, on_tick=on_tick))
|
|
158
|
+
ending = threading.Event()
|
|
159
|
+
|
|
160
|
+
def end(*_: Any) -> None:
|
|
161
|
+
if not ending.is_set():
|
|
162
|
+
ending.set()
|
|
163
|
+
threading.Thread(target=server.shutdown, daemon=True).start()
|
|
164
|
+
|
|
165
|
+
if threading.current_thread() is threading.main_thread():
|
|
166
|
+
signal.signal(signal.SIGTERM, end)
|
|
167
|
+
signal.signal(signal.SIGINT, end)
|
|
168
|
+
if _exits_with_parent():
|
|
169
|
+
watch_parent(end)
|
|
170
|
+
if stop is not None:
|
|
171
|
+
threading.Thread(target=lambda: (stop.wait(), end()), daemon=True).start()
|
|
172
|
+
try:
|
|
173
|
+
server.serve_forever(poll_interval=0.25)
|
|
174
|
+
finally:
|
|
175
|
+
server.server_close()
|
|
176
|
+
try:
|
|
177
|
+
os.remove(l.app_socket)
|
|
178
|
+
except OSError:
|
|
179
|
+
pass
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
# --- ASGI, with uvicorn ---
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def serve_asgi(app: Callable, *, on_wake: Optional[Callable] = None, on_tick: Optional[Callable] = None,
|
|
186
|
+
launched: Optional[Launch] = None, **uvicorn_options: Any) -> None:
|
|
187
|
+
"""Serves an ASGI app behind the gate on the launch's socket with
|
|
188
|
+
uvicorn, until the host stops the app (SIGTERM) or leaves. The socket
|
|
189
|
+
is opened here, readable and writable by this user only: uvicorn's own
|
|
190
|
+
opens it to everyone."""
|
|
191
|
+
import uvicorn
|
|
192
|
+
|
|
193
|
+
l = launched or launch()
|
|
194
|
+
sock = listen(l.app_socket)
|
|
195
|
+
uvicorn_options.setdefault("log_level", "warning")
|
|
196
|
+
server = uvicorn.Server(uvicorn.Config(Gate(app, l.ticket_key, on_wake=on_wake, on_tick=on_tick),
|
|
197
|
+
fd=sock.fileno(), **uvicorn_options))
|
|
198
|
+
if _exits_with_parent():
|
|
199
|
+
watch_parent(lambda: setattr(server, "should_exit", True))
|
|
200
|
+
try:
|
|
201
|
+
server.run()
|
|
202
|
+
finally:
|
|
203
|
+
sock.close()
|
|
204
|
+
try:
|
|
205
|
+
os.remove(l.app_socket)
|
|
206
|
+
except OSError:
|
|
207
|
+
pass
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
def _main(serve: Callable[..., None], manifest: Union[bytes, str], app: Callable, kw: dict) -> None:
|
|
211
|
+
answer_manifest(manifest)
|
|
212
|
+
try:
|
|
213
|
+
serve(app, **kw)
|
|
214
|
+
except NotBehindHost as e:
|
|
215
|
+
print(e, file=sys.stderr)
|
|
216
|
+
sys.exit(1)
|
|
217
|
+
sys.exit(0)
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def run_wsgi(manifest: Union[bytes, str], app: Callable, **kw: Any) -> None:
|
|
221
|
+
"""A WSGI app's main: run_wsgi(<nc-app.json's bytes or path>, app)."""
|
|
222
|
+
_main(serve_wsgi, manifest, app, kw)
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
def run_asgi(manifest: Union[bytes, str], app: Callable, **kw: Any) -> None:
|
|
226
|
+
"""An ASGI app's main: run_asgi(<nc-app.json's bytes or path>, app)."""
|
|
227
|
+
_main(serve_asgi, manifest, app, kw)
|
nativecluster/_ticket.py
ADDED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
"""The host's ticket (spec/hostapi.v1.md, "Requests to the app").
|
|
2
|
+
|
|
3
|
+
The host passes each request to the app's socket with a ticket it signed
|
|
4
|
+
with the key the app got on its stdin: what the host vouches for about the
|
|
5
|
+
request, never its words. The app trusts the ticket, and nothing else the
|
|
6
|
+
request says, for who is asking and from where. Every kit reads a ticket
|
|
7
|
+
exactly as spec/ticket-vectors.v1.json does (the Go kit's
|
|
8
|
+
sdk/go/app/ticket.go is the reference).
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import base64
|
|
14
|
+
import hashlib
|
|
15
|
+
import hmac
|
|
16
|
+
import json
|
|
17
|
+
import re
|
|
18
|
+
import time
|
|
19
|
+
from dataclasses import dataclass
|
|
20
|
+
from typing import Any, Optional, Union
|
|
21
|
+
|
|
22
|
+
# TICKET_HEADER carries the host's ticket on every request it passes to an
|
|
23
|
+
# app. The host drops any copy a client sent before it adds its own.
|
|
24
|
+
TICKET_HEADER = "X-NC-Ticket"
|
|
25
|
+
|
|
26
|
+
# TICKET_TTL_MS is how long a ticket is good for after the host issued it,
|
|
27
|
+
# either way: a request is passed on within milliseconds, so anything older
|
|
28
|
+
# was replayed.
|
|
29
|
+
TICKET_TTL_MS = 2 * 60 * 1000
|
|
30
|
+
|
|
31
|
+
_LABEL = b"nativecluster-ticket-v1\n"
|
|
32
|
+
|
|
33
|
+
# Base64url without padding: anything else (a "=", a "+", a space) is not
|
|
34
|
+
# a ticket the host wrote.
|
|
35
|
+
_B64URL = re.compile(r"\A[A-Za-z0-9_-]*\Z")
|
|
36
|
+
|
|
37
|
+
_STRINGS = ("id", "remote", "sni", "person", "email", "name", "session", "label")
|
|
38
|
+
_BOOLS = ("tls", "host", "mcp")
|
|
39
|
+
_INT64 = (-(1 << 63), (1 << 63) - 1)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class NoTicket(Exception):
|
|
43
|
+
"""A request the host did not vouch for."""
|
|
44
|
+
|
|
45
|
+
def __init__(self) -> None:
|
|
46
|
+
super().__init__("no valid ticket from NativeCluster")
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@dataclass(frozen=True)
|
|
50
|
+
class Ticket:
|
|
51
|
+
"""What the host vouches for about one request.
|
|
52
|
+
|
|
53
|
+
person is the app's own id for whoever the host signed in for the
|
|
54
|
+
request ("" for nobody): key everything the app keeps for them by it.
|
|
55
|
+
email and name come only to an app whose manifest asks people.read.
|
|
56
|
+
host marks the host's own call to its app (a firing, the clock's beat),
|
|
57
|
+
never a client's request. remote is the client's address as the host's
|
|
58
|
+
listener saw it, the only address an app may judge a request by.
|
|
59
|
+
"""
|
|
60
|
+
|
|
61
|
+
id: str = ""
|
|
62
|
+
remote: str = ""
|
|
63
|
+
tls: bool = False
|
|
64
|
+
sni: str = ""
|
|
65
|
+
issued: int = 0 # Unix milliseconds: the wire's "iat"
|
|
66
|
+
host: bool = False
|
|
67
|
+
person: str = ""
|
|
68
|
+
email: str = ""
|
|
69
|
+
name: str = ""
|
|
70
|
+
session: str = ""
|
|
71
|
+
label: str = ""
|
|
72
|
+
mcp: bool = False
|
|
73
|
+
|
|
74
|
+
def to_wire(self) -> dict:
|
|
75
|
+
"""The ticket as the host writes it, in the Go kit's field order."""
|
|
76
|
+
out: dict = {"id": self.id, "remote": self.remote}
|
|
77
|
+
if self.tls:
|
|
78
|
+
out["tls"] = True
|
|
79
|
+
if self.sni:
|
|
80
|
+
out["sni"] = self.sni
|
|
81
|
+
out["iat"] = self.issued
|
|
82
|
+
if self.host:
|
|
83
|
+
out["host"] = True
|
|
84
|
+
for name in ("person", "email", "name", "session", "label"):
|
|
85
|
+
if getattr(self, name):
|
|
86
|
+
out[name] = getattr(self, name)
|
|
87
|
+
if self.mcp:
|
|
88
|
+
out["mcp"] = True
|
|
89
|
+
return out
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _b64decode(s: str) -> bytes:
|
|
93
|
+
if not _B64URL.match(s) or len(s) % 4 == 1:
|
|
94
|
+
raise NoTicket()
|
|
95
|
+
return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _b64encode(b: bytes) -> str:
|
|
99
|
+
return base64.urlsafe_b64encode(b).rstrip(b"=").decode("ascii")
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def _field(name: str) -> Optional[str]:
|
|
103
|
+
"""The ticket's field a JSON key sets, as Go's decoder matches it: the
|
|
104
|
+
exact name, else the same name in another case."""
|
|
105
|
+
fields = _STRINGS + _BOOLS + ("iat",)
|
|
106
|
+
if name in fields:
|
|
107
|
+
return name
|
|
108
|
+
folded = name.lower()
|
|
109
|
+
for f in fields:
|
|
110
|
+
if f == folded:
|
|
111
|
+
return f
|
|
112
|
+
return None
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
class _Pairs(list):
|
|
116
|
+
"""A JSON object's keys and values, in order (a JSON array is a list,
|
|
117
|
+
never one of these)."""
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def _parse(raw: bytes) -> dict:
|
|
121
|
+
"""The payload's fields, each of its type, or NoTicket: a field of the
|
|
122
|
+
wrong type refuses the ticket, an unknown field is fine, null reads as
|
|
123
|
+
empty, and a key given twice keeps its last value."""
|
|
124
|
+
try:
|
|
125
|
+
pairs = json.loads(raw.decode("utf-8", errors="replace"), object_pairs_hook=_Pairs)
|
|
126
|
+
except ValueError:
|
|
127
|
+
raise NoTicket() from None
|
|
128
|
+
if not isinstance(pairs, _Pairs):
|
|
129
|
+
raise NoTicket()
|
|
130
|
+
out: dict = {}
|
|
131
|
+
for key, value in pairs:
|
|
132
|
+
f = _field(key)
|
|
133
|
+
if f is None or value is None:
|
|
134
|
+
continue
|
|
135
|
+
if f in _STRINGS:
|
|
136
|
+
if not isinstance(value, str):
|
|
137
|
+
raise NoTicket()
|
|
138
|
+
elif f in _BOOLS:
|
|
139
|
+
if not isinstance(value, bool):
|
|
140
|
+
raise NoTicket()
|
|
141
|
+
elif isinstance(value, bool) or not isinstance(value, int) or not _INT64[0] <= value <= _INT64[1]:
|
|
142
|
+
raise NoTicket()
|
|
143
|
+
out[f] = value
|
|
144
|
+
return out
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
class TicketKey:
|
|
148
|
+
"""The per-launch key the host signs tickets with: the app gets it on
|
|
149
|
+
its stdin when the host starts it, and nobody else ever holds it."""
|
|
150
|
+
|
|
151
|
+
__slots__ = ("_key",)
|
|
152
|
+
|
|
153
|
+
def __init__(self, key: bytes) -> None:
|
|
154
|
+
if len(key) != 32:
|
|
155
|
+
raise ValueError("the ticket key is not 32 bytes")
|
|
156
|
+
self._key = bytes(key)
|
|
157
|
+
|
|
158
|
+
@classmethod
|
|
159
|
+
def from_hex(cls, s: str) -> "TicketKey":
|
|
160
|
+
"""The key as the host hands it over (64 hex digits)."""
|
|
161
|
+
try:
|
|
162
|
+
key = bytes.fromhex(s.strip())
|
|
163
|
+
except ValueError:
|
|
164
|
+
key = b""
|
|
165
|
+
if len(key) != 32:
|
|
166
|
+
raise ValueError("the ticket key is not 32 bytes of hex")
|
|
167
|
+
return cls(key)
|
|
168
|
+
|
|
169
|
+
def __repr__(self) -> str:
|
|
170
|
+
return "TicketKey(...)"
|
|
171
|
+
|
|
172
|
+
def _mac(self, payload: str) -> bytes:
|
|
173
|
+
m = hmac.new(self._key, _LABEL, hashlib.sha256)
|
|
174
|
+
m.update(payload.encode("ascii"))
|
|
175
|
+
return m.digest()
|
|
176
|
+
|
|
177
|
+
def sign(self, t: Ticket) -> str:
|
|
178
|
+
"""The header value for t (the host's half; a test's and a fake
|
|
179
|
+
host's here)."""
|
|
180
|
+
b = json.dumps(t.to_wire(), separators=(",", ":"), ensure_ascii=False).encode("utf-8")
|
|
181
|
+
payload = _b64encode(b)
|
|
182
|
+
return payload + "." + _b64encode(self._mac(payload))
|
|
183
|
+
|
|
184
|
+
def verify(self, header: Union[str, bytes, None], now_ms: Optional[int] = None) -> Ticket:
|
|
185
|
+
"""The ticket a header value carries, or NoTicket."""
|
|
186
|
+
if isinstance(header, bytes):
|
|
187
|
+
header = header.decode("latin-1")
|
|
188
|
+
if not header:
|
|
189
|
+
raise NoTicket()
|
|
190
|
+
payload, dot, sig = header.partition(".")
|
|
191
|
+
if not dot:
|
|
192
|
+
raise NoTicket()
|
|
193
|
+
got = _b64decode(sig)
|
|
194
|
+
if not _B64URL.match(payload) or not hmac.compare_digest(got, self._mac(payload)):
|
|
195
|
+
raise NoTicket()
|
|
196
|
+
f: Any = _parse(_b64decode(payload))
|
|
197
|
+
t = Ticket(
|
|
198
|
+
id=f.get("id", ""), remote=f.get("remote", ""), tls=f.get("tls", False), sni=f.get("sni", ""),
|
|
199
|
+
issued=f.get("iat", 0), host=f.get("host", False), person=f.get("person", ""), email=f.get("email", ""),
|
|
200
|
+
name=f.get("name", ""), session=f.get("session", ""), label=f.get("label", ""), mcp=f.get("mcp", False),
|
|
201
|
+
)
|
|
202
|
+
if not t.remote:
|
|
203
|
+
raise NoTicket()
|
|
204
|
+
if now_ms is None:
|
|
205
|
+
now_ms = int(time.time() * 1000)
|
|
206
|
+
age = now_ms - t.issued
|
|
207
|
+
if age > TICKET_TTL_MS or age < -TICKET_TTL_MS:
|
|
208
|
+
raise NoTicket()
|
|
209
|
+
return t
|