nanonext (version 1.9.0)

handler_ws: Create WebSocket Handler

Description

Creates a WebSocket handler for use with http_server().

Usage

handler_ws(
  path,
  on_message,
  on_open = NULL,
  on_close = NULL,
  textframes = FALSE
)

Value

A handler object for use with http_server().

Arguments

path

URI path for WebSocket connections (e.g., "/ws").

on_message

Function called when a message is received. Signature: function(ws, data) where ws is the connection object and data is the message. Use ws$send() to send responses; the return value is ignored.

on_open

[default NULL] Function called when a connection opens. Signature: function(ws, req) where req is a list with uri (character) and headers (named character vector) from the HTTP upgrade request.

on_close

[default NULL] Function called when a connection closes. Signature: function(ws)

textframes

[default FALSE] Logical, use text frames instead of binary. When TRUE: incoming data is character, outgoing data should be character. When FALSE: incoming data is raw vector, outgoing data should be raw vector.

Connection Object

The ws object passed to callbacks has the following fields and methods:

• ws$send(data): Send a message to the client. data can be a raw vector or character string. Returns 0 on success, or an error code on failure (e.g., if the connection is closed).

• ws$close(): Close the connection.

• ws$id: Unique integer identifier for this connection. No two connections on the same server will share an ID, even across different handlers, making IDs safe to use as keys in a shared data structure.

Examples

# Simple echo server
h <- handler_ws("/ws", function(ws, data) ws$send(data))

# With connection tracking
clients <- list()
h <- handler_ws(
  "/chat",
  on_message = function(ws, data) {
    # Broadcast to all
    for (client in clients) client$send(data)
  },
  on_open = function(ws, req) {
    clients[[as.character(ws$id)]] <<- ws
  },
  on_close = function(ws) {
    clients[[as.character(ws$id)]] <<- NULL
  },
  textframes = TRUE
)