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.
@@ -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
@@ -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)
@@ -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