Skip to content
Source
Sign inSign up
TanStack/devtools
Open History to see the last commit

server.ts

392 lines12.1 KB

1import http from 'node:http'
2import { WebSocket, WebSocketServer } from 'ws'
3import { parseWithBigInt, stringifyWithBigInt } from '../utils/json'
4import type { Duplex } from 'node:stream'
5​
6// Shared types
7export interface TanStackDevtoolsEvent<
8 TEventName extends string,
9 TPayload = any,
10> {
11 type: TEventName
12 payload: TPayload
13 pluginId?: string // Optional pluginId to filter events by plugin
15// Used so no new server starts up when HMR happens
16declare global {
17 var __TANSTACK_DEVTOOLS_SERVER__: http.Server | null
18​
19 var __TANSTACK_DEVTOOLS_WSS_SERVER__: WebSocketServer | null
20​
21 var __TANSTACK_EVENT_TARGET__: EventTarget | null
23​
24/**
25 * A minimal server interface that both `http.Server` and `http2.Http2SecureServer` satisfy.
26 * Used so the event bus can piggyback on any compatible server without depending on http2 types directly.
27 */
28export interface HttpServerLike {
29 on: (event: string, listener: (...args: Array<any>) => void) => this
30 removeListener: (
31 event: string,
32 listener: (...args: Array<any>) => void,
33 ) => this
34 address: () => ReturnType<http.Server['address']>
36​
37export interface ServerEventBusConfig {
38 port?: number | undefined
39 host?: string | undefined
40 debug?: boolean | undefined
41 /**
42 * An external HTTP server to attach to instead of creating a standalone one.
43 * When provided, the event bus will add its SSE/POST/WS handlers to this server
44 * instead of creating and listening on its own server.
45 * Useful for piggybacking on Vite's HTTPS-enabled server.
46 */
47 httpServer?: HttpServerLike | undefined
49​
50export class ServerEventBus {
51 #eventTarget: EventTarget
52 #clients = new Set<WebSocket>()
53 #sseClients = new Set<http.ServerResponse>()
54 #server: http.Server | null = null
55 #wssServer: WebSocketServer | null = null
56 #port: number
57 #host: string
58 #debug: boolean
59 #externalServer: HttpServerLike | null = null
60 #externalRequestHandler:
61 | ((req: http.IncomingMessage, res: http.ServerResponse) => void)
62 | null = null
63 #externalUpgradeHandler:
64 | ((req: http.IncomingMessage, socket: Duplex, head: Buffer) => void)
65 | null = null
66 #dispatcher = (e: Event) => {
67 const event = (e as CustomEvent).detail
68 this.debugLog('Dispatching event from dispatcher, forwarding', event)
69 this.emit(event)
70 }
71 #connectFunction = () => {
72 this.debugLog(
73 'Connection request made to event-bus, replying back with success',
74 )
75 this.#eventTarget.dispatchEvent(new CustomEvent('tanstack-connect-success'))
76 }
77 constructor({
78 port = 4206,
79 host = 'localhost',
80 debug = false,
81 httpServer,
82 }: ServerEventBusConfig = {}) {
83 this.#port = port
84 this.#host = host
85 this.#eventTarget =
86 globalThis.__TANSTACK_EVENT_TARGET__ ?? new EventTarget()
87 // we want to set the global event target only once so that we can emit/listen to events on the server
88 if (!globalThis.__TANSTACK_EVENT_TARGET__) {
89 globalThis.__TANSTACK_EVENT_TARGET__ = this.#eventTarget
90 }
91 this.#server = globalThis.__TANSTACK_DEVTOOLS_SERVER__ ?? null
92 this.#wssServer = globalThis.__TANSTACK_DEVTOOLS_WSS_SERVER__ ?? null
93 this.#externalServer = httpServer ?? null
94 this.#debug = debug
95 this.debugLog('Initializing server event bus')
96 }
97​
98 private debugLog(...args: Array<any>) {
99 if (this.#debug) {
100 console.log('🌴 [tanstack-devtools:server-bus] ', ...args)
101 }
102 }
103​
104 private emitToServer(event: TanStackDevtoolsEvent<string>) {
105 this.debugLog('Emitting event to specific server listeners', event)
106 this.#eventTarget.dispatchEvent(
107 new CustomEvent(event.type, { detail: event }),
108 )
109 this.debugLog('Emitting event to global server listeners', event)
110 this.#eventTarget.dispatchEvent(
111 new CustomEvent('tanstack-devtools-global', { detail: event }),
112 )
113 }
114​
115 private emitEventToClients(event: TanStackDevtoolsEvent<string>) {
116 this.debugLog('Emitting event to clients', event)
117 const json = stringifyWithBigInt(event)
118​
119 for (const client of this.#clients) {
120 if (client.readyState === WebSocket.OPEN) {
121 client.send(json)
122 }
123 }
124 for (const res of this.#sseClients) {
125 res.write(`data: ${json}\n\n`)
126 }
127 }
128​
129 private emit(event: TanStackDevtoolsEvent<string>) {
130 this.emitEventToClients(event)
131 this.emitToServer(event)
132 }
133​
134 private createSSEServer() {
135 if (this.#server) {
136 return this.#server
137 }
138 const server = http.createServer((req, res) => {
139 if (req.url === '/__devtools/sse') {
140 res.writeHead(200, {
141 'Content-Type': 'text/event-stream',
142 'Cache-Control': 'no-cache',
143 Connection: 'keep-alive',
144 'Access-Control-Allow-Origin': '*',
145 })
146 res.write('\n')
147 this.debugLog('New SSE client connected')
148 this.#sseClients.add(res)
149 req.on('close', () => this.#sseClients.delete(res))
150 return
151 }
152​
153 if (req.url === '/__devtools/send' && req.method === 'POST') {
154 let body = ''
155 req.on('data', (chunk) => (body += chunk))
156 req.on('end', () => {
157 try {
158 const msg = parseWithBigInt(body)
159 this.debugLog('Received event from client', msg)
160 this.emitToServer(msg)
161 } catch {}
162 })
163 res.writeHead(200).end()
164 return
165 }
166​
167 res.statusCode = 404
168 res.end()
169 })
170 globalThis.__TANSTACK_DEVTOOLS_SERVER__ = server
171 this.#server = server
172 return server
173 }
174​
175 private createWebSocketServer() {
176 if (this.#wssServer) {
177 return this.#wssServer
178 }
179​
180 const wss = new WebSocketServer({ noServer: true })
181 this.#wssServer = wss
182 globalThis.__TANSTACK_DEVTOOLS_WSS_SERVER__ = wss
183 return wss
184 }
185​
186 private handleNewConnection(wss: WebSocketServer) {
187 wss.on('connection', (ws: WebSocket) => {
188 this.debugLog('New WebSocket client connected')
189 this.#clients.add(ws)
190 ws.on('close', () => {
191 this.debugLog('WebSocket client disconnected')
192 this.#clients.delete(ws)
193 })
194 ws.on('message', (msg) => {
195 this.debugLog('Received message from WebSocket client', msg.toString())
196 const data = parseWithBigInt(msg.toString())
197 this.emitToServer(data)
198 })
199 })
200 }
201​
202 start(): Promise<number> {
203 return new Promise((resolve) => {
204 if (process.env.NODE_ENV !== 'development') {
205 resolve(this.#port)
206 return
207 }
208 if (this.#server || this.#wssServer) {
209 // console.warn('Server is already running')
210 resolve(this.#port)
211 return
212 }
213​
214 this.#eventTarget.addEventListener(
215 'tanstack-dispatch-event',
216 this.#dispatcher,
217 )
218 this.#eventTarget.addEventListener(
219 'tanstack-connect',
220 this.#connectFunction,
221 )
222​
223 // When an external server is provided (e.g. Vite's HTTPS server),
224 // piggyback on it instead of creating a standalone server.
225 if (this.#externalServer) {
226 this.debugLog('Piggybacking on external HTTP server')
227 const wss = this.createWebSocketServer()
228 this.handleNewConnection(wss)
229​
230 // Add request handler for SSE and POST endpoints
231 this.#externalRequestHandler = (
232 req: http.IncomingMessage,
233 res: http.ServerResponse,
234 ) => {
235 if (req.url === '/__devtools/sse') {
236 res.writeHead(200, {
237 'Content-Type': 'text/event-stream',
238 'Cache-Control': 'no-cache',
239 Connection: 'keep-alive',
240 'Access-Control-Allow-Origin': '*',
241 })
242 res.write('\n')
243 this.debugLog('New SSE client connected (external server)')
244 this.#sseClients.add(res)
245 req.on('close', () => this.#sseClients.delete(res))
246 return
247 }
248​
249 if (req.url === '/__devtools/send' && req.method === 'POST') {
250 let body = ''
251 req.on('data', (chunk) => (body += chunk))
252 req.on('end', () => {
253 try {
254 const msg = parseWithBigInt(body)
255 this.debugLog(
256 'Received event from client (external server)',
257 msg,
258 )
259 this.emitToServer(msg)
260 } catch {}
261 })
262 res.writeHead(200).end()
263 return
264 }
265 }
266​
267 // Add upgrade handler for WebSocket
268 this.#externalUpgradeHandler = (
269 req: http.IncomingMessage,
270 socket: Duplex,
271 head: Buffer,
272 ) => {
273 if (req.url === '/__devtools/ws') {
274 wss.handleUpgrade(req, socket, head, (ws) => {
275 this.debugLog(
276 'WebSocket connection established (external server)',
277 )
278 wss.emit('connection', ws, req)
279 })
280 }
281 }
282​
283 this.#externalServer.on('request', this.#externalRequestHandler)
284 this.#externalServer.on('upgrade', this.#externalUpgradeHandler)
285​
286 // Resolve port from the external server's address
287 const address = this.#externalServer.address()
288 if (typeof address === 'object' && address) {
289 this.#port = address.port
290 }
291 this.debugLog(`Attached to external server on port ${this.#port}`)
292 resolve(this.#port)
293 return
294 }
295​
296 // Standalone mode: create our own HTTP + WebSocket server
297 this.debugLog('Starting server event bus')
298 const server = this.createSSEServer()
299 const wss = this.createWebSocketServer()
300​
301 this.handleNewConnection(wss)
302​
303 // Handle connection upgrade for WebSocket
304 server.on('upgrade', (req, socket, head) => {
305 if (req.url === '/__devtools/ws') {
306 wss.handleUpgrade(req, socket, head, (ws) => {
307 this.debugLog('WebSocket connection established')
308 wss.emit('connection', ws, req)
309 })
310 }
311 })
312​
313 const tryListen = (port: number) => {
314 server.listen(port, this.#host, () => {
315 const address = server.address()
316 if (typeof address === 'object' && address) {
317 this.#port = address.port
318 }
319 this.debugLog(`Listening on http://${this.#host}:${this.#port}`)
320 resolve(this.#port)
321 })
322 }
323​
324 // Handle EADDRINUSE by retrying with port 0 (OS-assigned)
325 server.on('error', (err: NodeJS.ErrnoException) => {
326 if (err.code === 'EADDRINUSE') {
327 this.debugLog(
328 `Port ${this.#port} is in use, trying OS-assigned port...`,
329 )
330 // Use port 0 to let OS assign an available port
331 tryListen(0)
332 }
333 })
334​
335 tryListen(this.#port)
336 })
337 }
338​
339 /**
340 * Get the port the server is listening on.
341 * This may differ from the configured port if the original port was in use.
342 */
343 get port(): number {
344 return this.#port
345 }
346​
347 stop() {
348 // Only close the server if we own it (standalone mode)
349 if (!this.#externalServer) {
350 this.#server?.close(() => {
351 this.debugLog('Server stopped')
352 })
353 } else {
354 // Remove our listeners from the external server without closing it
355 if (this.#externalRequestHandler) {
356 this.#externalServer.removeListener(
357 'request',
358 this.#externalRequestHandler,
359 )
360 this.#externalRequestHandler = null
361 }
362 if (this.#externalUpgradeHandler) {
363 this.#externalServer.removeListener(
364 'upgrade',
365 this.#externalUpgradeHandler,
366 )
367 this.#externalUpgradeHandler = null
368 }
369 this.debugLog('Detached from external server')
370 }
371 this.#wssServer?.close(() => {
372 this.debugLog('WebSocket server stopped')
373 })
374 this.debugLog('Clearing all connections')
375 this.#clients.clear()
376 this.#sseClients.forEach((res) => res.end())
377 this.#sseClients.clear()
378 this.debugLog('Cleared all WS/SSE connections')
379 this.#server = null
380 this.#wssServer = null
381 this.#externalServer = null
382 this.#eventTarget.removeEventListener(
383 'tanstack-dispatch-event',
384 this.#dispatcher,
385 )
386 this.#eventTarget.removeEventListener(
387 'tanstack-connect',
388 this.#connectFunction,
389 )
390 this.debugLog('[tanstack-devtools] All connections cleared')
391 }