Skip to content
Ion
Docs Console Examples

Realtime

Reference doc for the `sst.aws.Realtime` component.

The Realtime component lets you publish and subscribe to messages in realtime.

  • It offers a topic-based messaging network using AWS IoT.
  • Lets you publish and subscribe to messages using WebSocket in the browser and from your server.
  • Provides an SDK to authorize clients, and grants permissions to subscribe and publish to topics.

Use realtime endpoint in your app

const server = new sst.aws.Realtime("MyServer", {
  authorizer: "src/authorizer.handler"
});

Use the RealtimeAuthHandler function in the SDK to authorize the client, and grant permissions to subscribe and publish to topics.

Publish and receive messages in your frontend

const client = new mqtt.MqttClient();
const connection = client.new_connection(config);


// Subscribe messages
connection.on("message", (topic, payload) => {
  // handle the message
});


// Publish messages
connection.publish(topic, payload, mqtt.QoS.AtLeastOnce);

Subscribe messages in your backend

server.subscribe("src/subscriber.handler", {
  filter: `${$app.name}/${$app.stage}/chat/room1`
});

Publish message from your backend

import { IoTDataPlaneClient, PublishCommand } from "@aws-sdk/client-iot-data-plane";
const data = new IoTDataPlaneClient();
await data.send(
  new PublishCommand({
    payload: Buffer.from(
      JSON.stringify({ message: "Hello world" })
    ),
    topic: `${Resource.App.name}/${Resource.App.stage}/chat/room1`,
  })
);

Constructor

new Realtime(name, args, opts?)

Parameters

RealtimeArgs

authorizer

Type Input<string | FunctionArgs>

The Lambda function that’ll be used to authorize the client on connection.

{
  authorizer: "src/authorizer.handler"
}

transform?

Type Object

Transform how this subscription creates its underlying resources.

transform.authorizer?

Type AuthorizerArgs | (args: AuthorizerArgs => void)

Transform the IoT authorizer resource.

Properties

authorizer

Type Output<string>

The name of the IoT authorizer.

endpoint

Type Output<string>

The IoT endpoint.

nodes

Type Object

The underlying resources this component creates.

nodes.authHandler

Type Output<Function>

The IoT authorizer function resource.

nodes.authorizer

Type Authorizer

The IoT authorizer resource.

SDK

The following are accessible through the SDK at runtime.

  • authorizer string

    The name of the IoT authorizer.

  • endpoint string

    The IoT endpoint.

RealtimeAuthHandler

RealtimeAuthHandler(input)

Parameters

Returns IoTCustomAuthorizerHandler

Creates an authorization handler for the Realtime component, that validates the token and grants permissions for the topics the client can subscribe and publish to.

import { RealtimeAuthHandler, Resource } from "sst";


export const handler = RealtimeAuthHandler(async (token) => {
  // Validate the token
  console.log(token);


  // Return the topics to subscribe and publish
  return {
    subscribe: [`${Resource.App.name}/${Resource.App.stage}/chat/room1`],
    publish: [`${Resource.App.name}/${Resource.App.stage}/chat/room1`],
  };
});

RealtimeAuthResult

Type Object

RealtimeAuthResult.publish?

Type string[]

The topics the client can publish to.

For example, this publishes to specific topics.

{
  publish: ["chat/room1", "chat/room2"]
}

And to publish to all topics under a specific prefix.

{
  publish: ["chat/*"]
}

RealtimeAuthResult.subscribe?

Type string[]

The topics the client can subscribe to.

For example, this subscribes to specific topics.

{
  subscribe: ["chat/room1", "chat/room2"]
}

And to subscribe to all topics under a specific prefix.

{
  subscribe: ["chat/*"]
}

Methods

subscribe

subscribe(subscriber, args)

Parameters

Returns Output<RealtimeLambdaSubscriber>

Subscribe to this Realtime server.

server.subscribe("src/subscriber.handler", {
  filter: `${$app.name}/${$app.stage}/chat/room1`
});

Customize the subscriber function.

server.subscribe(
  {
    handler: "src/subscriber.handler",
    timeout: "60 seconds"
  },
  {
    filter: `${$app.name}/${$app.stage}/chat/room1`
  }
);

RealtimeSubscriberArgs

filter

Type Input<string>

Filter the topics that’ll be processed by the subscriber.

Subscribe to a specific topic.

{
  filter: `${$app.name}/${$app.stage}/chat/room1`
}

Subscribe to all topics under a prefix.

{
  filter: `${$app.name}/${$app.stage}/chat/#`
}

transform?

Type Object

Transform how this subscription creates its underlying resources.

transform.topicRule?

Type TopicRuleArgs | (args: TopicRuleArgs => void)

Transform the IoT topic rule resource.