pynect-worker 0.8.5__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,108 @@
1
+ """Canonical Pynect protocol and configuration models."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import enum
6
+ from typing import Annotated
7
+
8
+ from pydantic import BaseModel, ConfigDict, Field, field_validator
9
+ from pydantic.alias_generators import to_camel
10
+
11
+ PROTOCOL_VERSION = 2
12
+ WEBSOCKET_SUBPROTOCOL = f"pynect.v{PROTOCOL_VERSION}"
13
+ MAX_LOCAL_FRAME_BYTES = 256 * 1024 * 1024
14
+ DEFAULT_WEBSOCKET_FRAME_BYTES = 8 * 1024 * 1024
15
+
16
+
17
+ class MessageKind(enum.StrEnum):
18
+ """RPC envelope kinds shared with JavaScript."""
19
+
20
+ CALLBACK = "callback"
21
+ CALLBACK_RELEASE = "callback_release"
22
+ CALLBACK_RESULT = "callback_result"
23
+ HELLO = "hello"
24
+ NOTIFY = "notify"
25
+ REQUEST = "request"
26
+ RESPONSE = "response"
27
+
28
+
29
+ class Operation(enum.StrEnum):
30
+ """Operations supported by the Python object bridge."""
31
+
32
+ CALL = "call"
33
+ DIR = "dir"
34
+ GET = "get"
35
+ IMPORT = "import"
36
+ ITER = "iter"
37
+ NEXT = "next"
38
+ RELEASE = "release"
39
+ REPR = "repr"
40
+ SET = "set"
41
+ SHUTDOWN = "shutdown"
42
+ VALUE = "value"
43
+
44
+
45
+ class WireValueType(enum.StrEnum):
46
+ """Tagged non-MessagePack values supported by the wire codec."""
47
+
48
+ CALLBACK = "callback"
49
+ DATE = "date"
50
+ DATETIME = "datetime"
51
+ MAP = "map"
52
+ REFERENCE = "reference"
53
+ SET = "set"
54
+ TIME = "time"
55
+ UNDEFINED = "undefined"
56
+
57
+
58
+ class WorkerOptions(BaseModel):
59
+ """Behavior shared by local IPC workers and remote sessions."""
60
+
61
+ model_config = ConfigDict(
62
+ alias_generator=to_camel,
63
+ populate_by_name=True,
64
+ extra="forbid",
65
+ )
66
+
67
+ validate_pydantic: bool = Field(
68
+ default=True,
69
+ title="Validate Pydantic",
70
+ description="Validate annotated Python arguments with Pydantic.",
71
+ )
72
+
73
+
74
+ class ServerOptions(WorkerOptions):
75
+ """Loopback-first WebSocket server configuration."""
76
+
77
+ host: str = Field(
78
+ default="127.0.0.1",
79
+ min_length=1,
80
+ description="Interface on which the proxy-facing server listens.",
81
+ )
82
+ port: Annotated[int, Field(ge=0, le=65_535)] = Field(
83
+ default=0,
84
+ description="Listening port; zero asks the operating system to choose one.",
85
+ )
86
+ path: str = Field(
87
+ default="/pynect",
88
+ description="Absolute WebSocket URL path accepted by the server.",
89
+ )
90
+ modules: dict[str, str] = Field(
91
+ default_factory=dict,
92
+ description="Public module names mapped to importable Python module names.",
93
+ json_schema_extra={"default": {}},
94
+ )
95
+ max_frame_bytes: Annotated[int, Field(gt=0, le=0xFFFF_FFFB)] = Field(
96
+ default=DEFAULT_WEBSOCKET_FRAME_BYTES,
97
+ title="Max Frame Bytes",
98
+ description="Maximum MessagePack payload size for one RPC frame.",
99
+ )
100
+
101
+ @field_validator("path")
102
+ @classmethod
103
+ def validate_path(cls, value: str) -> str:
104
+ """Require a path-only absolute URL component."""
105
+
106
+ if not value.startswith("/") or "?" in value or "#" in value:
107
+ raise ValueError("must be an absolute URL path without query or fragment")
108
+ return value
pynect_worker/py.typed ADDED
@@ -0,0 +1 @@
1
+
@@ -0,0 +1,47 @@
1
+ """Emit the canonical Pynect JSON Schema for JavaScript code generation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from typing import Any
7
+
8
+ from .models import (
9
+ PROTOCOL_VERSION,
10
+ WEBSOCKET_SUBPROTOCOL,
11
+ MessageKind,
12
+ Operation,
13
+ ServerOptions,
14
+ WireValueType,
15
+ WorkerOptions,
16
+ )
17
+
18
+
19
+ def schema_document() -> dict[str, Any]:
20
+ """Build the stable cross-language schema document."""
21
+
22
+ return {
23
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
24
+ "$id": "https://nodepyx.dev/schemas/pynect.json",
25
+ "title": "Pynect shared schema",
26
+ "$defs": {
27
+ "WorkerOptions": WorkerOptions.model_json_schema(by_alias=True),
28
+ "ServerOptions": ServerOptions.model_json_schema(by_alias=True),
29
+ },
30
+ "x-pynect-protocol": {
31
+ "version": PROTOCOL_VERSION,
32
+ "websocketSubprotocol": WEBSOCKET_SUBPROTOCOL,
33
+ "messageKinds": [item.value for item in MessageKind],
34
+ "operations": [item.value for item in Operation],
35
+ "wireValueTypes": [item.value for item in WireValueType],
36
+ },
37
+ }
38
+
39
+
40
+ def main() -> None:
41
+ """Write canonical JSON to stdout for a language-neutral generator."""
42
+
43
+ print(json.dumps(schema_document(), indent=2, sort_keys=True))
44
+
45
+
46
+ if __name__ == "__main__":
47
+ main()
@@ -0,0 +1,221 @@
1
+ """Direct multi-client WebSocket transport for Pynect."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import concurrent.futures
6
+ import contextlib
7
+ import json
8
+ import os
9
+ import signal
10
+ import threading
11
+ from http import HTTPStatus
12
+ from types import FrameType
13
+ from typing import Any
14
+ from urllib.parse import urlsplit
15
+
16
+ from websockets.exceptions import ConnectionClosed
17
+ from websockets.http11 import Request, Response
18
+ from websockets.sync.server import Server, ServerConnection, serve
19
+
20
+ from .bridge import Bridge
21
+ from .connection import RpcConnection
22
+ from .framing import decode_frame, encode_frame
23
+ from .models import WEBSOCKET_SUBPROTOCOL, ServerOptions
24
+
25
+
26
+ class WebSocketConnection(RpcConnection):
27
+ """Adapt one binary WebSocket session to the bridge connection contract."""
28
+
29
+ def __init__(self, websocket: ServerConnection, max_frame_bytes: int) -> None:
30
+ self._websocket = websocket
31
+ self._max_frame_bytes = max_frame_bytes
32
+ self._write_lock = threading.Lock()
33
+ self._closed = False
34
+
35
+ def read(self) -> dict[str, Any] | None:
36
+ try:
37
+ frame = self._websocket.recv()
38
+ except ConnectionClosed:
39
+ return None
40
+ if isinstance(frame, str):
41
+ self._websocket.close(1003, "Binary Pynect frames required")
42
+ raise TypeError("Pynect WebSocket messages must be binary")
43
+ return decode_frame(bytes(frame), self._max_frame_bytes)
44
+
45
+ def write(self, message: dict[str, Any]) -> None:
46
+ frame = encode_frame(message, self._max_frame_bytes)
47
+ with self._write_lock:
48
+ if self._closed:
49
+ raise EOFError("WebSocket connection is closed")
50
+ self._websocket.send(frame)
51
+
52
+ def close(self) -> None:
53
+ with self._write_lock:
54
+ if self._closed:
55
+ return
56
+ self._closed = True
57
+ with contextlib.suppress(ConnectionClosed):
58
+ self._websocket.close()
59
+
60
+
61
+ class PynectServer:
62
+ """A shared Python process with an isolated bridge per WebSocket client."""
63
+
64
+ def __init__(self, options: ServerOptions) -> None:
65
+ self.options = options
66
+ self._sessions: set[WebSocketConnection] = set()
67
+ self._sessions_lock = threading.Lock()
68
+ worker_count = min(32, (os.cpu_count() or 1) + 4)
69
+ self._executor = concurrent.futures.ThreadPoolExecutor(
70
+ max_workers=worker_count,
71
+ thread_name_prefix="pynect-server-call",
72
+ )
73
+ self._server: Server = serve(
74
+ self._handle,
75
+ options.host,
76
+ options.port,
77
+ compression=None,
78
+ max_size=options.max_frame_bytes + 4,
79
+ process_request=self._process_request,
80
+ subprotocols=[WEBSOCKET_SUBPROTOCOL],
81
+ )
82
+ self._shutdown_started = threading.Event()
83
+
84
+ @property
85
+ def url(self) -> str:
86
+ """Return the actual bound URL, including an operating-system-selected port."""
87
+
88
+ address = self._server.socket.getsockname()
89
+ host = self.options.host
90
+ if host in {"0.0.0.0", "::"}:
91
+ host = str(address[0])
92
+ if ":" in host and not host.startswith("["):
93
+ host = f"[{host}]"
94
+ return f"ws://{host}:{address[1]}{self.options.path}"
95
+
96
+ @property
97
+ def active_connections(self) -> int:
98
+ """Return the number of bridge sessions currently connected."""
99
+
100
+ with self._sessions_lock:
101
+ return len(self._sessions)
102
+
103
+ def serve_forever(self) -> None:
104
+ """Accept clients until shutdown is requested."""
105
+
106
+ self._server.serve_forever()
107
+
108
+ def shutdown(self) -> None:
109
+ """Stop accepting clients and close active sessions without signaling them."""
110
+
111
+ if self._shutdown_started.is_set():
112
+ return
113
+ self._shutdown_started.set()
114
+ with self._sessions_lock:
115
+ sessions = tuple(self._sessions)
116
+ for session in sessions:
117
+ session.close()
118
+ self._server.shutdown()
119
+
120
+ def close(self) -> None:
121
+ """Release server and shared executor resources."""
122
+
123
+ self.shutdown()
124
+ self._executor.shutdown(wait=False, cancel_futures=True)
125
+
126
+ def _handle(self, websocket: ServerConnection) -> None:
127
+ connection = WebSocketConnection(websocket, self.options.max_frame_bytes)
128
+ with self._sessions_lock:
129
+ self._sessions.add(connection)
130
+ try:
131
+ Bridge(
132
+ connection,
133
+ token=None,
134
+ validate_pydantic=self.options.validate_pydantic,
135
+ modules=self.options.modules,
136
+ executor=self._executor,
137
+ ).run()
138
+ finally:
139
+ with self._sessions_lock:
140
+ self._sessions.discard(connection)
141
+
142
+ def _process_request(
143
+ self,
144
+ connection: ServerConnection,
145
+ request: Request,
146
+ ) -> Response | None:
147
+ if urlsplit(request.path).path != self.options.path:
148
+ return connection.respond(HTTPStatus.NOT_FOUND, "Not found\n")
149
+ offered = {
150
+ item.strip() for item in request.headers.get("Sec-WebSocket-Protocol", "").split(",") if item.strip()
151
+ }
152
+ if WEBSOCKET_SUBPROTOCOL not in offered:
153
+ return connection.respond(
154
+ HTTPStatus.UPGRADE_REQUIRED,
155
+ f"WebSocket subprotocol {WEBSOCKET_SUBPROTOCOL} is required\n",
156
+ )
157
+ return None
158
+
159
+
160
+ class ShutdownLatch:
161
+ """Latch the first process termination request and replay it after server startup."""
162
+
163
+ def __init__(self) -> None:
164
+ self.requested = threading.Event()
165
+ self._server: PynectServer | None = None
166
+ self._lock = threading.Lock()
167
+
168
+ def attach(self, server: PynectServer) -> None:
169
+ """Attach a constructed server and replay any earlier request."""
170
+
171
+ with self._lock:
172
+ self._server = server
173
+ requested = self.requested.is_set()
174
+ if requested:
175
+ self._shutdown(server)
176
+
177
+ def handle(self, _signal: int, _frame: FrameType | None) -> None:
178
+ """Record one signal and ask the server to stop from a safe helper thread."""
179
+
180
+ self.requested.set()
181
+ with self._lock:
182
+ server = self._server
183
+ if server is not None:
184
+ self._shutdown(server)
185
+
186
+ @staticmethod
187
+ def _shutdown(server: PynectServer) -> None:
188
+ threading.Thread(
189
+ target=server.shutdown,
190
+ name="pynect-server-shutdown",
191
+ daemon=True,
192
+ ).start()
193
+
194
+
195
+ def run_server(options: ServerOptions) -> None:
196
+ """Run a server with single-delivery SIGINT and SIGTERM handling."""
197
+
198
+ latch = ShutdownLatch()
199
+ handled_signals = tuple(
200
+ candidate
201
+ for candidate in (getattr(signal, "SIGINT", None), getattr(signal, "SIGTERM", None))
202
+ if candidate is not None
203
+ )
204
+ previous = {candidate: signal.getsignal(candidate) for candidate in handled_signals}
205
+ for candidate in handled_signals:
206
+ signal.signal(candidate, latch.handle)
207
+
208
+ server: PynectServer | None = None
209
+ try:
210
+ server = PynectServer(options)
211
+ latch.attach(server)
212
+ print(
213
+ json.dumps({"event": "listening", "pid": os.getpid(), "url": server.url}),
214
+ flush=True,
215
+ )
216
+ server.serve_forever()
217
+ finally:
218
+ if server is not None:
219
+ server.close()
220
+ for candidate, handler in previous.items():
221
+ signal.signal(candidate, handler)