@cloudfort/tez-sdk

Blazing-fast realtime client SDK for the Tez UDP engine — for any game (2D, 3D, VR) and any application or service, in Node.js and the browser.

Features

• 🚀 Ultra-low latency — UDP-based protocol with custom reliability layer
• 🎮 Game-agnostic — Works for any realtime application (games, VR, collaborative apps)
• 🔄 Automatic reconnection — Built-in reconnect with state recovery
• 📦 Tiny footprint — Zero dependencies (optional ws for Node.js)
• 🌐 Universal — Works in browsers, Node.js, and game engines
• 🔒 Type-safe — Full TypeScript support with comprehensive type definitions
• 📡 Channel pub/sub — Pusher-compatible WebSocket channels (public, private, presence)

Installation

npm install @cloudfort/tez-sdk

Quick Start

Browser (UDP Engine)

import { TezClient } from '@cloudfort/tez-sdk';

const client = new TezClient({
  serverUrl: 'ws://your-server:9000',
  room: 'my-room',
});

client.on('connected', () => {
  console.log('Connected to Tez server!');
  client.sendInput({ x: 10, y: 20, action: 'jump' });
});

client.on('snapshot', (state) => {
  renderGame(state);
});

client.connect();

Node.js

import { TezClient } from '@cloudfort/tez-sdk/node';

const client = new TezClient({
  serverUrl: 'ws://your-server:9000',
  room: 'my-room',
});

await client.connect();

Channels (WebSocket Pub/Sub)

import { TezChannelsClient } from '@cloudfort/tez-sdk/channels';

const client = new TezChannelsClient({
  url: 'https://tez.example',
  apiKey: 'app-key',
});

// Public channel
const chat = client.subscribe('chat.lobby');
chat.listen('App\\Events\\MessageSent', e => console.log(e));

// Presence channel
const room = client.subscribe('presence-room.1');
room.here(members => console.log('online:', members));
room.joining(m => console.log('joined:', m));
room.leaving(m => console.log('left:', m));

// Send client events
chat.sendEvent('chat-message', { text: 'Hello!' });

API Reference

TezClient (UDP Engine)

Constructor

new TezClient(options: TezClientOptions)

Options:

• serverUrl (string) — WebSocket URL of the Tez server
• room (string) — Room name to join
• authKey? (string) — Optional HMAC authentication key
• reconnect? (boolean) — Auto-reconnect on disconnect (default: true)

Methods

• connect() — Connect to the server
• disconnect() — Disconnect from the server
• sendInput(input: object) — Send input to the server
• sendCustom(data: Uint8Array) — Send custom binary data
• on(event: string, callback: Function) — Subscribe to events

Events

• connected — Fired when connected to server
• disconnected — Fired when disconnected
• snapshot — Fired when world state update received
• event — Fired when custom event received
• error — Fired on error

TezChannelsClient (WebSocket Channels)

Constructor

new TezChannelsClient(options: TezChannelsOptions)

Options:

| Option | Description | |---|---| | url | Server origin or full /v1/channels/ws URL (HTTP(S) auto-converts to WS(S)) | | apiKey | Public Tez API key | | authEndpoint | Laravel auth URL (default: /broadcasting/auth) | | authorizer | Custom promise-style authorizer (replaces authEndpoint) | | auth.headers | Extra headers for auth requests | | auth.credentials | Fetch credentials mode (default: same-origin) | | reconnect | false to disable, or { initialDelayMs, maxDelayMs } (cap 30 s) |

Methods

• connect() — Start connection
• disconnect() — Disconnect and stop reconnecting
• subscribe(channel: string) — Subscribe to a channel, returns TezChannel
• channel(name) / privateChannel(name) / presenceChannel(name) — Shorthand subscribe
• leaveChannel(name) / leave(name) / leaveAllChannels() — Unsubscribe

TezChannel

• listen(event, callback) — Listen for channel events
• listenToAll(callback) — Listen for all events
• subscribed(callback) — Called when subscription succeeds
• here(callback) — Presence member snapshot
• joining(callback) / leaving(callback) — Presence member changes
• sendEvent(event, data) — Send client event to other subscribers
• subscribe() / unsubscribe() / leave() — Lifecycle

Laravel Echo Connector

import Echo from 'laravel-echo';
import { TezEchoConnector } from '@cloudfort/tez-sdk/echo';

window.Echo = new Echo({
  broadcaster: TezEchoConnector,
  url: 'https://tez.example',
  key: 'app-key',
  authEndpoint: '/broadcasting/auth',
});

window.Echo.private('orders.8')
  .listen('OrderUpdated', e => console.log(e));

window.Echo.join('room.1')
  .here(members => console.log('online:', members))
  .joining(m => console.log('joined:', m))
  .leaving(m => console.log('left:', m));

The connector auto-detects the Laravel CSRF token from window.Laravel or a <meta name="csrf-token"> tag. Pass bearerToken for Sanctum/API auth.

Socket ID and toOthers()

axios.interceptors.request.use(config => {
  const id = window.Echo.socketId();
  if (id) config.headers['X-Socket-ID'] = id;
  return config;
});

Protocol

UDP Engine

Tez uses a custom binary protocol over UDP (or WebSocket fallback):

• Handshake — HMAC-SHA256 authenticated connection
• Input — Client → Server (20-30 Hz)
• Snapshot — Server → Client (10-30 Hz, adaptive)
• Custom — Bidirectional binary messages

WebSocket Channels

JSON text frames over WebSocket at /v1/channels/ws?key=<api_key>:

• welcome — Server assigns socket_id on connect
• subscribe/unsubscribe — Client manages channel subscriptions
• event — Server delivers published or client events
• member_added/member_removed — Presence channel membership changes
• ping/pong — Bidirectional keepalive

Proxy Configuration

Place nginx in front of the channels HTTP/WS endpoint:

location /v1/channels/ {
    proxy_pass http://127.0.0.1:9102;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 86400s;
}

Always terminate TLS at the proxy; the backend listens on plain HTTP/WS.

Security and Delivery Limitations

• Live delivery only. HTTP 202 means accepted by the broadcasting backend, not acknowledged by recipients. There is no event history, offline replay, or exactly-once guarantee.
• No signing secrets on the frontend. Private/presence authorization goes through your Laravel channels.php callbacks; the browser never sees the HMAC secret.
• Origin validation. The server validates browser Origin headers and rejects Origin: null.
• Rate limits. Default publish rate: 100 req/s per key (burst 200); subscription rate: 20/s per socket (burst 40).

Performance

• Latency: < 5ms (local network), < 50ms (internet)
• Throughput: 10,000+ messages/second per client
• Memory: < 1 MB per client instance
• CPU: < 1% per client (idle)

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 15+
• Opera 76+

Node.js Support

• Node.js 18.17+
• TypeScript 5.0+

Ecosystem

All SDKs and tools by Cloudfort Tech:

Tez — Realtime UDP Engine

| SDK | Language | Repository | |-----|----------|------------| | Tez Engine | Rust | Cloudfort-Tech/tez (private) | | JS/TS SDK | TypeScript | Cloudfort-Tech/js-udp-tez | | PHP SDK | PHP | Cloudfort-Tech/php-udp-tez |

Callum — Voice & Communication

| SDK | Language | Repository | |-----|----------|------------| | React Native | TypeScript | Cloudfort-Tech/react-native-callum-voice | | Unity | C# | Cloudfort-Tech/unity-callum-voice | | .NET | C# | Cloudfort-Tech/dotnet-callum-voice | | Swift | Swift | Cloudfort-Tech/swift-callum-voice | | Unreal | C++ | Cloudfort-Tech/unreal-callum-voice | | Dart/Flutter | Dart | Cloudfort-Tech/dart-callum-voice | | Java/Android | Java | Cloudfort-Tech/java-callum-voice | | JavaScript | JavaScript | Cloudfort-Tech/js-callum-voice |

License

MIT © Cloudfort Tech

Contributing

Contributions welcome! Please read our Contributing Guide first.