WorkerInterface
Defined in: index.cts:100
Interface that worker threads must implement to handle WebSocket events. All handler methods are optional - if not provided, the respective functionality will be unavailable.
Methods
Section titled “Methods”handleStart()?
Section titled “handleStart()?”
optionalhandleStart(workerArg?):void|Promise<void>
Defined in: index.cts:106
Called when the worker is starting up, before registering with the native addon. This allows for initialization logic that needs to run before handling WebSocket events.
Parameters
Section titled “Parameters”workerArg?
Section titled “workerArg?”any
Optional argument passed from the start() function’s workerArg option.
Returns
Section titled “Returns”void | Promise<void>
handleOpen()?
Section titled “handleOpen()?”
optionalhandleOpen(socketId,ip,headers):boolean|Promise<boolean>
Defined in: index.cts:115
Handles new WebSocket connections and can reject them. If not provided, all connections are accepted.
Parameters
Section titled “Parameters”socketId
Section titled “socketId”number
The unique identifier of the WebSocket connection.
string
The client’s IP address.
headers
Section titled “headers”Record<string, string>
HTTP headers from the WebSocket handshake request.
Returns
Section titled “Returns”boolean | Promise<boolean>
true to accept the connection, false to reject it.
handleTextMessage()?
Section titled “handleTextMessage()?”
optionalhandleTextMessage(data,socketId):void|Promise<void>
Defined in: index.cts:122
Handles incoming WebSocket text messages from clients.
Parameters
Section titled “Parameters”string
The message data as a string.
socketId
Section titled “socketId”number
The unique identifier of the WebSocket connection.
Returns
Section titled “Returns”void | Promise<void>
handleBinaryMessage()?
Section titled “handleBinaryMessage()?”
optionalhandleBinaryMessage(data,socketId):void|Promise<void>
Defined in: index.cts:129
Handles incoming WebSocket binary messages from clients.
Parameters
Section titled “Parameters”Uint8Array
The message data as a Uint8Array.
socketId
Section titled “socketId”number
The unique identifier of the WebSocket connection.
Returns
Section titled “Returns”void | Promise<void>
handleClose()?
Section titled “handleClose()?”
optionalhandleClose(socketId):void|Promise<void>
Defined in: index.cts:135
Handles WebSocket connection closures.
Parameters
Section titled “Parameters”socketId
Section titled “socketId”number
The unique identifier of the closed WebSocket connection.
Returns
Section titled “Returns”void | Promise<void>
handleHttpRequest()?
Section titled “handleHttpRequest()?”
optionalhandleHttpRequest(req,res):void|Promise<void>
Defined in: index.cts:163
Handles plain HTTP/1.1 requests arriving on the same port as the WebSocket server. Handy for health checks, landing pages, or webhook endpoints without a second server. HTTP requests are load-balanced across worker threads using round-robin (no per-connection pinning), since each HTTP request is independent.
req exposes method, url, headers, rawHeaders, httpVersion, remoteAddress,
and body (a pre-read Buffer). It also implements Node.js stream.Readable —
req.pipe(), req.on('data'), etc. work synchronously (body is pushed before your
handler is called, so no async I/O is needed before reading).
res implements Node.js stream.Writable. Written chunks are buffered; the complete
response is sent once the handler’s Promise resolves. statusCode, setHeader(),
getHeader(), removeHeader(), writeHead(), write(), and end() all work as
expected. Array values for setHeader() produce multiple header lines (e.g. Set-Cookie).
Real-time streaming is not supported — use WebSockets for that.
For small JSON/HTML responses or proxying webhook bodies to send(), these APIs are
drop-in compatible with code written against http.createServer.
There is no HTTP/2, no trailers, and no upgrade hook for non-WebSocket upgrades.
WebSocket upgrade requests are detected automatically and routed through handleOpen.
Parameters
Section titled “Parameters”The incoming request.
The response object.
Returns
Section titled “Returns”void | Promise<void>