Using WebSockets in the Routzie

The Routzie platform provides a robust and flexible way to work with sockets, allowing you to expose server-side sockets to the web via WebSocket endpoints.

Basic Principles

• WebSocket endpoints are exposed by creating a SocketServer instance and calling its expose method.
• The API provides methods for sending and receiving data, broadcasting messages, managing connections, and handling events such as connection, disconnection, and server closure.
• The behavior is similar to classic WebSocket servers; all standard features are supported.

API Overview

Key features:

• Generic data type: You can work with raw strings, binary data (Uint8Array), or structured JSON.
• Event listeners: Handle connection events, data reception, and client disconnects.
• Data transmission: Send data to individual clients or broadcast to all.
• Connection management: List active connections, disconnect clients, and gracefully close the server.

Example: Machine Code (Server Side)

import { SocketServer } from 'sockets'

let socketServer: SocketServer

bootstrap(async () => {
  console.log("Started")

  socketServer = new SocketServer({
    onClose: () => console.log('onClose'),
    onConnection: (connectionId: string) => console.log('onConnection', connectionId),
    onConnectionClose: (connectionId: string) => console.log('onConnectionClose', connectionId),
    onData: (connectionId: string, data: any) => {
      console.log('onData', connectionId, data)
      socketServer.sendData(connectionId, 'Hello back!!')
    }
  })
  await socketServer.listen()
  await socketServer.expose('test')
})

onDispose(async () => {
  console.log("Disposed")
})

Example: Browser Client

<script>
  const socket = new WebSocket('wss://routzie.com/gateway/v1/public/{machineId}-{environment}/socket/test');

  socket.addEventListener('open', (event) => {
    console.log('Connected to server');
    socket.send('Hello from client!');
  });

  socket.addEventListener('message', (event) => {
    console.log('Message from server ', event.data);
  });

  socket.addEventListener('close', (event) => {
    console.log('Disconnected from server');
  });

  socket.addEventListener('error', (event) => {
    console.log('Error: ', event);
  });

  setTimeout(() => {
    socket.send('Hello again from client!');
  }, 5000);
</script>

How to Expose a Socket

To make your socket accessible via WebSocket, simply call the expose method with a chosen name:

await socketServer.expose('test')

This will register the socket with the gateway, making it available at the corresponding WebSocket URL.

Data Handling & JSON Mode

• Text and binary data: By default, both the server (SocketServer) and client (WebsocketClient) work with string or binary (Uint8Array) messages.

• JSON mode: If you want to send and receive structured JSON objects, instantiate either class with a generic type and set the last parameter (jsonMode) to true:

  • On the server:

    let socketServer: SocketServer<{ message: string }>
    socketServer = new SocketServer({
      // ...listeners
    }, true) // true enables JSON mode
    

  • On the client:

    let client: WebsocketClient<{ message: string }>
    client = new WebsocketClient({
      // ...listeners
    }, true) // true enables JSON mode
    

  With JSON mode enabled, all sent and received data will be automatically serialized/deserialized as JSON. This makes it easy to work with structured messages and ensures type safety throughout your code.

  If you omit the generic type and jsonMode, the API will work with plain text or binary data.

Machine WebSocket Client Usage

To connect to a WebSocket from machine code, use the WebsocketClient class. You can enable JSON mode and specify the expected message type using TypeScript generics:

import { WebsocketClient } from 'sockets'

let client: WebsocketClient<{ message: string }>

bootstrap(async () => {
  console.log("Started")

  client = new WebsocketClient({
    onData: (data) => console.log('onData', data),
    onConnected: () => console.log('onConnected'),
    onClose: () => console.log('onClose'),
  }, true) // true enables JSON mode

  await client.connect('wss://routzie.com/gateway/v1/public/20565c8f157f2508-sandbox/socket/test')

  setTimeout(async () => {
    await client.sendData({ message: "Hello from my local routzie!" })
  }, 1000)
})

onDispose(async () => {
  console.log("Disposed")
})

Implementation Note

Internally, sockets are implemented using Unix sockets for performance and isolation. This is handled automatically and does not require any special configuration from the user.

Summary

The Routzie socket API lets you easily expose server-side sockets to the web, handle real-time communication, and manage connections with a clean, type-safe interface. While the backend uses Unix sockets, the API is designed to feel familiar to anyone who has worked with WebSockets before.

How it works

• The last parameter (true) enables JSON mode, so all sent/received data is automatically handled as JSON.
• The generic type <{ message: string }> ensures type safety for your messages.
• If you omit the generic and jsonMode, the client will work with plain text or binary data.

This approach applies equally to the server (SocketServer) and client (WebsocketClient).