Server SDKs

Official backend SDKs for publishing events, querying channels, and authenticating subscriptions.

SDK	Package	Framework	Runtime deps
relay-php	`relayhq/relay-php`	Laravel	Guzzle
relay-node	`@relayhq/relay-node`	Express / Node.js	Zero
relay-ruby	`relay-ruby`	Rails	Zero
relay-python	`relay-python`	Django	Zero

Laravel (relay-php) composer require relayhq/relay-php

Install

bash

composer require relayhq/relay-php

Configuration

php

// config/broadcasting.php
'default' => 'relay',
'connections' => [
    'relay' => [
        'driver'  => 'relay',
        'host'    => env('RELAY_HOST', '127.0.0.1'),
        'port'    => env('RELAY_PORT', 6001),
        'key'     => env('RELAY_APP_KEY'),
        'secret'  => env('RELAY_APP_SECRET'),
        'app_id'  => env('RELAY_APP_ID'),
    ],
],

Publishing

php

// Using Laravel's broadcasting
broadcast(new MessageSent($message));

// Or directly via the client
$relay = new \RelayHQ\Relay\RelayClient($config);
$relay->publish('chat', 'new-message', ['text' => 'Hello!']);

Authentication

php

// Private channel
$auth = $relay->authenticate($socketId, 'private-orders');

// Presence channel
$auth = $relay->authenticate($socketId, 'presence-room', [
    'user_id' => 42,
    'user_info' => ['name' => 'Alice'],
]);

Node.js (relay-node) npm install @relayhq/relay-node

Install

bash

npm install @relayhq/relay-node

Setup

import { RelayClient } from '@relayhq/relay-node'

const relay = new RelayClient({
  host: '127.0.0.1',
  port: 6001,
  appId: 'my-app',
  key: 'my-key',
  secret: 'my-secret',
})

Publishing

// Single event
await relay.publish('chat', 'new-message', { text: 'Hello!' })

// Batch
await relay.publishBatch([
  { channel: 'chat', event: 'msg', data: { text: 'Hello' } },
  { channel: 'alerts', event: 'notify', data: { level: 'info' } },
])

// Query channels
const channels = await relay.getChannels()
const users = await relay.getChannelUsers('presence-room')

Express Auth Middleware

import express from 'express'
import { RelayClient, relayAuthMiddleware } from '@relayhq/relay-node'

const app = express()
app.use(express.json())

const relay = new RelayClient({ /* config */ })

app.post('/broadcasting/auth', relayAuthMiddleware(relay, (req) => {
  return req.user  // return user object or null to deny
}))

Authentication

// Private channel
const auth = relay.authenticate(socketId, 'private-orders')

// Presence channel
const auth = relay.authenticate(socketId, 'presence-room', {
  user_id: 42,
  user_info: { name: 'Alice' },
})

Rails (relay-ruby) gem 'relay-ruby'

Install

ruby

# Gemfile
gem 'relay-ruby'

ActionCable Configuration

yaml

# config/cable.yml
production:
  adapter: relay
  host: 127.0.0.1
  port: 6001
  app_id: my-app
  key: my-key
  secret: my-secret

That's it. All ActionCable.server.broadcast calls now go through Relay.

Direct Client Usage

ruby

client = Relay::Client.new(
  host: '127.0.0.1',
  port: 6001,
  app_id: 'my-app',
  key: 'my-key',
  secret: 'my-secret'
)

# Publish
client.publish('chat', 'new-message', { text: 'Hello!' })

# Batch
client.publish_batch([
  { channel: 'chat', event: 'msg', data: { text: 'Hello' } }
])

# Query
channels = client.get_channels
users = client.get_channel_users('presence-room')

Authentication

ruby

# Private channel
auth = client.authenticate(socket_id, 'private-orders')

# Presence channel
auth = client.authenticate(socket_id, 'presence-room',
  channel_data: { user_id: 42, user_info: { name: 'Alice' } }
)

Django / Python (relay-python) pip install relay-python

Install

bash

pip install relay-python

Setup

python

from relay import RelayClient

relay = RelayClient(
    host='127.0.0.1',
    port=6001,
    app_id='my-app',
    key='my-key',
    secret='my-secret',
)

Publishing

python

# Synchronous
relay.publish('chat', 'new-message', {'text': 'Hello!'})

# Async
await relay.async_publish('chat', 'new-message', {'text': 'Hello!'})

# Batch
relay.publish_batch([
    {'channel': 'chat', 'event': 'msg', 'data': {'text': 'Hello'}},
])

# Query channels
channels = relay.get_channels()
users = relay.get_channel_users('presence-room')

Django Auth Middleware

python

# settings.py
from relay import RelayClient

RELAY_CLIENT = RelayClient(
    host='127.0.0.1', port=6001,
    app_id='my-app', key='my-key', secret='my-secret',
)

MIDDLEWARE = [
    ...
    'relay.django.middleware.RelayAuthMiddleware',
]

The middleware intercepts POST /broadcasting/auth, checks request.user.is_authenticated, and returns a signed token.

Decorator

python

from relay.django import relay_auth_required

@relay_auth_required
def auth_view(request):
    return {
        'user_id': request.user.id,
        'user_info': {'name': request.user.username},
    }

Django Channels Layer

python

# settings.py
CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "relay.django.channels.RelayChannelLayer",
        "CONFIG": {
            "host": "127.0.0.1",
            "port": 6001,
            "app_id": "my-app",
            "key": "my-key",
            "secret": "my-secret",
        },
    },
}

Authentication

python

# Private channel
auth = relay.authenticate(socket_id, 'private-orders')

# Presence channel
auth = relay.authenticate(socket_id, 'presence-room',
    channel_data={'user_id': 42, 'user_info': {'name': 'Alice'}}
)