Realtime

Supabase allows the client to subscribe, listen, and broadcast messages to channels, send the user's presence, and listen changes in database. To learn more about it, read Supabase Realtime.

Raiden already provide the realtime endpoints by default. When you run the Raiden server, you can access the /realtime endpoints.

raiden.router: =========== Registered Route ===========
raiden.router:  GET
raiden.router: - /realtime/v1/websocket
raiden.router:  POST
raiden.router: - /realtime/v1/api/broadcast

You can use Supabase Client to interact with realtime endpoints.

WebSocket

The /realtime/v1/websocket endpoint proxies WebSocket connections to the upstream Supabase Realtime server. This enables clients to use Supabase's Phoenix-based realtime protocol (channels, presence, broadcast) through Raiden.

Features:

• Automatic reconnection (up to 5 attempts)
• Heartbeat/ping-pong keep-alive (every 30 seconds)
• Bidirectional message proxying between client and server

Broadcast

The /realtime/v1/api/broadcast endpoint proxies broadcast messages to the Supabase Realtime API. Clients can send broadcast messages via HTTP POST.

Subscribers (PubSub)

Raiden includes a built-in PubSub system for subscribing to external message queues. Subscribers are background workers that consume messages from topics and process them asynchronously.

Currently supported providers:

• Google Cloud Pub/Sub (PubSubProviderGoogle)

Defining a Subscriber

Create subscriber files in the internal/subscribers/ directory. Each subscriber embeds raiden.SubscriberBase and implements the SubscriberHandler interface.

internal/subscribers/order_created.go

package subscribers

import (
    "encoding/json"
    "fmt"

    "github.com/sev-2/raiden"
)

type OrderCreatedSubscriber struct {
    raiden.SubscriberBase
}

func (s *OrderCreatedSubscriber) Name() string {
    return "order-created"
}

func (s *OrderCreatedSubscriber) Provider() raiden.PubSubProviderType {
    return raiden.PubSubProviderGoogle
}

func (s *OrderCreatedSubscriber) Topic() string {
    return "order-events"
}

func (s *OrderCreatedSubscriber) Subscription() string {
    return "order-created-sub"
}

func (s *OrderCreatedSubscriber) Consume(ctx raiden.SubscriberContext, message any) error {
    fmt.Printf("Received message: %v\n", message)
    // Process the message
    return nil
}

Registering Subscribers

Register subscribers in the internal/bootstrap/subscribers.go file. This file is typically code-generated by raiden-cli:

package bootstrap

import (
    "app/internal/subscribers"
    "github.com/sev-2/raiden"
)

func RegisterSubscribers(server *raiden.Server) {
    server.RegisterSubscribers(
        &subscribers.OrderCreatedSubscriber{},
    )
}

SubscriberHandler Interface

Method	Default	Description
Name() string	"unknown"	Unique name for this subscriber.
Provider() PubSubProviderType	PubSubProviderUnknown	The PubSub provider to use.
Topic() string	""	The topic to subscribe to.
Subscription() string	""	The subscription ID.
SubscriptionType() SubscriptionType	SubscriptionTypePull	SubscriptionTypePull or SubscriptionTypePush.
PushEndpoint() string	""	Endpoint path for push subscriptions.
AutoAck() bool	true	Whether to automatically acknowledge messages after processing.
Consume(ctx SubscriberContext, message any) error	Error	The message handler. Must be implemented.

Subscription Types

Type	Constant	Description
Pull	SubscriptionTypePull	Raiden actively pulls messages from the provider (default).
Push	SubscriptionTypePush	The provider pushes messages to a Raiden HTTP endpoint.

For push subscriptions, Raiden automatically registers an HTTP endpoint at /pubsub-endpoint/{push-endpoint} and creates the subscription on the provider.

SubscriberContext

The Consume method receives a SubscriberContext with these methods:

Method	Description
Config() *Config	Access the application configuration.
Span() trace.Span	Get the current OpenTelemetry trace span.
SetSpan(span trace.Span)	Set a trace span.
HttpRequest(method, url string, body []byte, headers map[string]string, timeout time.Duration, response any) error	Make an HTTP request from within the subscriber. The response parameter must be a pointer.

Publishing Messages

You can publish messages to a topic using the PubSub manager:

err := server.PubSub.Publish(ctx, raiden.PubSubProviderGoogle, "topic-name", []byte(`{"key": "value"}`))

Google Cloud Pub/Sub Configuration

To use Google Cloud Pub/Sub, set the following environment variables:

Variable	Description
GOOGLE_PROJECT_ID	Your Google Cloud project ID.
GOOGLE_SA_PATH	Path to the Google Cloud service account JSON key file.
SERVER_DNS	(Required for push subscriptions) The public DNS/URL of your server.