Realtime

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

It offers a topic-based messaging network using AWS IoT. Letting you publish and subscribe to messages using a WebSocket in the browser and your server.

Also, provides an SDK to authorize clients, grant permissions to subscribe, and publish to topics.

Note

IoT is shared across all apps and stages in your AWS account. So you need to prefix the topics by the app and stage name.

There is only 1 IoT endpoint per region per AWS account. Messages from all apps and stages are published to the same IoT endpoint. Make sure to prefix the topics by the app and stage name.

Create a realtime endpoint

sst.config.ts

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

Authorize the client

src/authorizer.ts

import { Resource } from "sst/aws";
import { realtime } from "sst/aws/realtime";

export const handler = realtime.authorizer(async (token) => {
  // Validate the 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`],
  };
});

Publish and receive messages in your frontend

app/page.tsx

import { Resource } from "sst/aws";

const client = new mqtt.MqttClient();
// Configure with
// - Resource.Realtime.endpoint
// - Resource.Realtime.authorizer
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

sst.config.ts

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

Publish message from your backend

src/lambda.ts

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

• name string

• args RealtimeArgs

• opts? ComponentResourceOptions

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

• authorizer?

Transform how this subscription creates its underlying resources.

transform.authorizer?

Type AuthorizerArgs | (args: AuthorizerArgs, opts: ComponentResourceOptions, name: string) => 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

• authHandler

• authorizer

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

Use the SDK in your runtime to interact with your infrastructure.

---

Links

This is accessible through the Resource object in the SDK.

• authorizer string

  The name of the IoT authorizer.

• endpoint string

  The IoT endpoint.

The realtime client SDK is available through the following.

src/authorizer.ts

import { realtime } from "sst/aws/realtime";

---

authorizer

realtime.authorizer(input)

Parameters

• input (token: string) => Promise<AuthResult>

Returns (evt: IoTCustomAuthorizerEvent, context: Context) => Promise<Object>

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

src/authorizer.ts

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

  // Return the topics to subscribe and publish
  return {
    subscribe: ["*"],
    publish: ["*"],
  };
});

AuthResult

Type Object

• publish?

• subscribe?

AuthResult.publish?

Type string[]

The topics the client can publish to.

For example, this publishes to two specific topics.

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

And to publish to all topics under a given prefix.

{
  publish: ["chat/*"]
}

AuthResult.subscribe?

Type string[]

The topics the client can subscribe to.

For example, this subscribes to two specific topics.

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

And to subscribe to all topics under a given prefix.

{
  subscribe: ["chat/*"]
}

Methods

subscribe

subscribe(subscriber, args)

Parameters

• subscriber string | FunctionArgs

  The function that’ll be notified.

• args RealtimeSubscriberArgs

  Configure the subscription.

Returns Output<RealtimeLambdaSubscriber>

Subscribe to this Realtime server.

sst.config.ts

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

Customize the subscriber function.

sst.config.ts

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.

Tip

Learn more about topic filters.

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

• topicRule?

Transform how this subscription creates its underlying resources.

transform.topicRule?

Type TopicRuleArgs | (args: TopicRuleArgs, opts: ComponentResourceOptions, name: string) => void

Transform the IoT Topic rule resource.