Skip to content

Commit 82a9abd

Browse files
rewitt94claude
andauthored
Add a WebSocket pool to the napi JS client (#1104)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 5d87971 commit 82a9abd

20 files changed

Lines changed: 1331 additions & 135 deletions

‎crates/monty-js/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# @pydantic/monty
22

33
Run Python in Monty's sandbox from JavaScript or TypeScript.
4-
Node uses subprocess workers; `@pydantic/monty/wasm` uses Node worker threads or browser Web Workers.
4+
Node uses subprocess workers, or remote workers over a WebSocket with `MontyWebsocket`; `@pydantic/monty/wasm` uses
5+
Node worker threads or browser Web Workers.
56

67
```sh
78
npm install @pydantic/monty
Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
// `MontyWebsocket` end-to-end against in-process servers that bridge each
2+
// connection to a real `monty subprocess` child (see websocket_servers.ts),
3+
// mirroring crates/monty-python/tests/test_websocket.py.
4+
5+
import { AsyncLocalStorage } from 'node:async_hooks'
6+
7+
import { afterEach, test } from 'vitest'
8+
import { t } from './assertions.js'
9+
import {
10+
drainingServer,
11+
droppingRelay,
12+
refusingServer,
13+
relay,
14+
serve,
15+
StoringServer,
16+
type TestServer,
17+
} from './websocket_servers.js'
18+
19+
import { MontyDisconnectError, MontyRuntimeError, MontyShutdown, MontyWebsocket } from '@pydantic/monty'
20+
21+
const servers: TestServer[] = []
22+
23+
/** Serves `handle` until the end of the test. */
24+
async function server(handle: Parameters<typeof serve>[0]): Promise<TestServer> {
25+
const started = await serve(handle)
26+
servers.push(started)
27+
return started
28+
}
29+
30+
afterEach(async () => {
31+
await Promise.all(servers.splice(0).map((s) => s.close()))
32+
})
33+
34+
test('feedRun over a websocket keeps session state', async () => {
35+
const { url } = await server(relay)
36+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30 })
37+
await using session = await pool.checkout()
38+
t.is(await session.feedRun('1 + 1'), 2)
39+
await session.feedRun('x = 21')
40+
t.is(await session.feedRun('x * 2'), 42)
41+
})
42+
43+
test('inputs, prints and async external functions cross the websocket', async () => {
44+
const { url } = await server(relay)
45+
const printed: string[] = []
46+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30 })
47+
await using session = await pool.checkout()
48+
const result = await session.feedRun("print('hi')\nawait double(n) + 1", {
49+
inputs: { n: 20 },
50+
externalLookup: { double: async (x: number) => x * 2 },
51+
printCallback: (stream, text) => printed.push(`${stream}:${text}`),
52+
})
53+
t.is(result, 41)
54+
t.deepEqual(printed, ['stdout:hi\n'])
55+
})
56+
57+
test('separate checkouts are isolated', async () => {
58+
const { url } = await server(relay)
59+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30 })
60+
{
61+
await using session = await pool.checkout()
62+
await session.feedRun('leaked = 1')
63+
}
64+
await using session = await pool.checkout()
65+
const error = await t.throwsAsync(() => session.feedRun('leaked'), { instanceOf: MontyRuntimeError })
66+
t.is(error.display('msg'), "name 'leaked' is not defined")
67+
})
68+
69+
test('connectHeaders runs per checkout in the caller async context', async () => {
70+
const relayServer = await server(relay)
71+
const trace = new AsyncLocalStorage<string>()
72+
let calls = 0
73+
await using pool = await MontyWebsocket.create(relayServer.url, {
74+
requestTimeout: 30,
75+
connectHeaders: async () => {
76+
calls += 1
77+
return { traceparent: trace.getStore() ?? 'missing', 'x-token': 't' }
78+
},
79+
})
80+
const checkoutAs = (id: string) =>
81+
trace.run(id, async () => {
82+
await using session = await pool.checkout()
83+
return session.feedRun('1 + 1')
84+
})
85+
t.deepEqual(await Promise.all([checkoutAs('00-aaa-111-01'), checkoutAs('00-bbb-222-01')]), [2, 2])
86+
t.is(calls, 2)
87+
t.deepEqual(relayServer.headers.map((headers) => headers.traceparent).sort(), ['00-aaa-111-01', '00-bbb-222-01'])
88+
t.deepEqual(
89+
relayServer.headers.map((headers) => headers['x-token']),
90+
['t', 't'],
91+
)
92+
})
93+
94+
test('connectHeaders must be a function', async () => {
95+
const notCallable = { 'x-token': 't' } as unknown as () => Record<string, string>
96+
await t.throwsAsync(() => MontyWebsocket.create('ws://127.0.0.1:9', { connectHeaders: notCallable }), {
97+
instanceOf: TypeError,
98+
message: 'connectHeaders must be a function returning a record of header names to values',
99+
})
100+
})
101+
102+
test('a bad connectHeaders result rejects the checkout and leaves the pool usable', async () => {
103+
const relayServer = await server(relay)
104+
let result: unknown = 5
105+
await using pool = await MontyWebsocket.create(relayServer.url, {
106+
requestTimeout: 30,
107+
connectHeaders: () => result as Record<string, string>,
108+
})
109+
await t.throwsAsync(() => pool.checkout(), {
110+
instanceOf: TypeError,
111+
message: 'connectHeaders must return a record of header names to values, got number',
112+
})
113+
result = { 'x-token': 1 }
114+
await t.throwsAsync(() => pool.checkout(), {
115+
instanceOf: TypeError,
116+
message: "connectHeaders must return string header values, got number for 'x-token'",
117+
})
118+
result = { 'x-token': 't' }
119+
await using session = await pool.checkout()
120+
t.is(await session.feedRun('1 + 1'), 2)
121+
t.is(relayServer.headers.length, 1)
122+
})
123+
124+
test('a refused connection rejects the checkout', async () => {
125+
await using pool = await MontyWebsocket.create('ws://127.0.0.1:9', { requestTimeout: 30 })
126+
const error = await t.throwsAsync(() => pool.checkout())
127+
t.regex(error.message, /^failed to spawn monty worker: ws:\/\/127\.0\.0\.1:9/)
128+
})
129+
130+
test('a session the server refuses rejects the checkout with MontyRuntimeError', async () => {
131+
const { url } = await server(refusingServer("unknown profile 'gpu'"))
132+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30 })
133+
const error = await t.throwsAsync(() => pool.checkout({ profile: 'gpu' }), { instanceOf: MontyRuntimeError })
134+
t.is(error.message, "RuntimeError: unknown profile 'gpu'")
135+
})
136+
137+
test('a connection dropped during checkout rejects it with MontyDisconnectError', async () => {
138+
const { url } = await server(droppingRelay(1))
139+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30 })
140+
const error = await t.throwsAsync(() => pool.checkout(), { instanceOf: MontyDisconnectError })
141+
t.regex(error.message, /^RuntimeError: monty worker connection closed while /)
142+
})
143+
144+
test('a draining server rejects the checkout with MontyShutdown', async () => {
145+
const { url } = await server(drainingServer)
146+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30 })
147+
const error = await t.throwsAsync(() => pool.checkout(), { instanceOf: MontyShutdown })
148+
t.is(error.message, 'RuntimeError: monty server is shutting down; the request did not run')
149+
t.is(error.dump, null)
150+
})
151+
152+
test('a checkout that waits past checkoutTimeout rejects with a TimeoutError', async () => {
153+
const { url } = await server(relay)
154+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30, maxProcesses: 1, checkoutTimeout: 0.1 })
155+
await using _held = await pool.checkout()
156+
const error = await t.throwsAsync(() => pool.checkout(), { instanceOf: DOMException })
157+
t.is(error.name, 'TimeoutError')
158+
t.is(error.message, 'no monty worker became available within the checkout timeout')
159+
})
160+
161+
test('a plain relay names no session, whatever ephemeral and profile say', async () => {
162+
const { url } = await server(relay)
163+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30 })
164+
for (const options of [{}, { ephemeral: true }, { ephemeral: false }, { profile: 'gpu' }, { profile: '' }]) {
165+
await using session = await pool.checkout(options)
166+
t.is(session.sessionId, undefined)
167+
t.is(await session.feedRun('1 + 1'), 2)
168+
}
169+
})
170+
171+
test('dump bytes from a plain relay load into a new session', async () => {
172+
const { url } = await server(relay)
173+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30 })
174+
let dump: Buffer
175+
{
176+
await using session = await pool.checkout()
177+
await session.feedRun('x = 20')
178+
dump = await session.dump()
179+
}
180+
await using session = await pool.checkout()
181+
await session.loadSession(dump)
182+
t.is(session.sessionId, undefined)
183+
t.is(await session.feedRun('x + 1'), 21)
184+
})
185+
186+
test('a dropped connection raises MontyDisconnectError and loses the session', async () => {
187+
// request 1 is Configure, 2 the first feed
188+
const { url } = await server(droppingRelay(3))
189+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30 })
190+
await using session = await pool.checkout()
191+
t.is(await session.feedRun('1 + 1'), 2)
192+
const error = await t.throwsAsync(() => session.feedRun('2 + 2'), { instanceOf: MontyDisconnectError })
193+
t.regex(error.message, /^RuntimeError: monty worker connection closed while /)
194+
t.is(await t.throwsAsync(() => session.feedRun('3 + 3')), error)
195+
})
196+
197+
test('a dropped connection during dump raises MontyDisconnectError', async () => {
198+
const { url } = await server(droppingRelay(2))
199+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30 })
200+
await using session = await pool.checkout()
201+
await t.throwsAsync(() => session.dump(), { instanceOf: MontyDisconnectError })
202+
})
203+
204+
test('a storing server names the session and a shutdown is resumed', async () => {
205+
const { url } = await server(new StoringServer().handle)
206+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30 })
207+
const session = await pool.checkout()
208+
t.deepEqual(session.sessionId, Buffer.from('sess-1'))
209+
await session.feedRun('x = 20')
210+
// the fake parks the session instead of running this feed; the pool
211+
// reloads the ID on a new connection and re-sends it
212+
t.is(await session.feedRun('x + 1'), 21)
213+
await session.close()
214+
// the ID the resume adopted outlives the checkout
215+
t.deepEqual(session.sessionId, Buffer.from('sess-3'))
216+
})
217+
218+
test('with autoResume off a shutdown raises MontyShutdown naming the session', async () => {
219+
const { url } = await server(new StoringServer().handle)
220+
await using pool = await MontyWebsocket.create(url, { requestTimeout: 30, autoResume: false })
221+
{
222+
await using session = await pool.checkout()
223+
await session.feedRun('x = 20')
224+
const error = await t.throwsAsync(() => session.feedRun('x + 1'), { instanceOf: MontyShutdown })
225+
t.is(
226+
error.message,
227+
'RuntimeError: monty server is shutting down; the request did not run (restorable state attached)',
228+
)
229+
t.deepEqual(error.dump, Buffer.from('sess-1'))
230+
}
231+
await using session = await pool.checkout()
232+
await session.loadSession(Buffer.from('sess-1'))
233+
t.deepEqual(session.sessionId, Buffer.from('sess-3'))
234+
t.is(await session.feedRun('x + 1'), 21)
235+
})
236+
237+
test('a closed pool rejects checkouts', async () => {
238+
const pool = await MontyWebsocket.create('ws://127.0.0.1:9')
239+
await pool.close()
240+
await t.throwsAsync(() => pool.checkout(), {
241+
message: 'the pool is closed — create a new MontyWebsocket pool',
242+
})
243+
})

‎crates/monty-js/__test__/pool.spec.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -305,7 +305,8 @@ test('exhausted pool times out the checkout', async () => {
305305
await using pool = await Monty.create({ maxProcesses: 1, checkoutTimeout: 0.2 })
306306
const held = await pool.checkout()
307307
try {
308-
const error = await t.throwsAsync(() => pool.checkout())
308+
const error = await t.throwsAsync(() => pool.checkout(), { instanceOf: DOMException })
309+
t.is(error.name, 'TimeoutError')
309310
t.is(error.message, 'no monty worker became available within the checkout timeout')
310311
} finally {
311312
await held.close()

0 commit comments

Comments
 (0)