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.
- pynect_worker/__init__.py +11 -0
- pynect_worker/__main__.py +5 -0
- pynect_worker/_generated/__init__.py +1 -0
- pynect_worker/_generated/metadata.py +3 -0
- pynect_worker/bridge.py +594 -0
- pynect_worker/cli.py +64 -0
- pynect_worker/codegen.py +501 -0
- pynect_worker/connection.py +147 -0
- pynect_worker/framing.py +32 -0
- pynect_worker/models.py +108 -0
- pynect_worker/py.typed +1 -0
- pynect_worker/schema.py +47 -0
- pynect_worker/server.py +221 -0
- pynect_worker-0.8.5.dist-info/METADATA +386 -0
- pynect_worker-0.8.5.dist-info/RECORD +17 -0
- pynect_worker-0.8.5.dist-info/WHEEL +4 -0
- pynect_worker-0.8.5.dist-info/entry_points.txt +4 -0
pynect_worker/models.py
ADDED
|
@@ -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
|
+
|
pynect_worker/schema.py
ADDED
|
@@ -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()
|
pynect_worker/server.py
ADDED
|
@@ -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)
|