Topic

The cloud.Topic class represents a subject of data that is open for subscription.

Topics are a staple of event-driven architectures, especially those that rely on pub-sub messaging to decouple producers of data and the consumers of said data.

Usage

Creating a topic

bring cloud;

let topic = new cloud.Topic();

Subscribing to a topic

bring cloud;

let topic = new cloud.Topic();

topic.onMessage(inflight (message: str) => {
  log("Topic published message: {message}");
});

Subscribing a Queue to a Topic

bring cloud;

let queue = new cloud.Queue();
queue.setConsumer(inflight (message: str) => {
  log("Topic published message: {message}");
});

let topic = new cloud.Topic();
topic.subscribeQueue(queue);

Publishing to a topic

The inflight method publish sends messages to all of the topic's subscribers.

bring cloud;

let topic = new cloud.Topic();

inflight () => {
  topic.publish(
    "Topics can now publish",
    "multiple messages at once"
  );
};

Simple pub-sub example

Here is an example of combining the preflight and inflight apis for a topic and creating an adorable simple pub-sub application.

bring cloud;

// First we create a topic
let topic = new cloud.Topic();

// Then we define a consumer inflight handler
let consumerHandler = inflight(message: str) => {
  log("Doing some work with message: {message}");
};

// Now we can use a preflight method of topic to register the consumer handler
// to be invoked when a message is published to the topic.
topic.onMessage(consumerHandler);

// Then we define the producer inflight handler
let publisherHandler = inflight () => {
  // Here we use the inflight api to publish a message to the topic.
  topic.publish("Here are those launch codes you asked for.");
};

// Finally we can use multiple resources to invoke our publisher handler
// for simplicity sake we will just use a function.
new cloud.Function(publisherHandler);

Target-specific details

Simulator (sim)

Within the context of the simulator, topics are implemented by keeping an in-memory list of subscribers and publishing messages to them when publish is called.

AWS (tf-aws and awscdk)

AWS implementations of cloud.Topic use AWS SNS.

Azure (tf-azure)

🚧 Not supported yet (tracking issue: #621)

GCP (tf-gcp)

🚧 Not supported yet (tracking issue: #620)

API Reference

Topic

A topic for pub/sub notifications.

Initializers

bring cloud;

new cloud.Topic(props?: TopicProps);

Name	Type	Description
props	TopicProps	No description.

---

props^Optional

• Type: TopicProps

---

Methods

Preflight Methods

Name	Description
onMessage	Run an inflight whenever an message is published to the topic.
subscribeQueue	Subscribing queue to the topic.

Inflight Methods

Name	Description
publish	Publish messages to topic, if multiple messages are passed then they will be published as a batch if supported by the target platform.

---

onMessage

onMessage(inflight: ITopicOnMessageHandler, props?: TopicOnMessageOptions): Function

Run an inflight whenever an message is published to the topic.

inflight^Required

• Type: ITopicOnMessageHandler

---

props^Optional

• Type: TopicOnMessageOptions

---

subscribeQueue

subscribeQueue(queue: Queue, props?: TopicSubscribeQueueOptions): void

Subscribing queue to the topic.

queue^Required

• Type: Queue

---

props^Optional

• Type: TopicSubscribeQueueOptions

---

publish

inflight publish(...messages: Array<str>): void

Publish messages to topic, if multiple messages are passed then they will be published as a batch if supported by the target platform.

messages^Required

• Type: str

Payload to publish to Topic.

---

Static Functions

Name	Description
onLiftType	A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.
toInflight	Generates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.

---

onLiftType

bring cloud;

cloud.Topic.onLiftType(host: IInflightHost, ops: MutArray<str>);

A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.

The list of requested inflight methods needed by the inflight host are given by ops.

This method is commonly used for adding permissions, environment variables, or other capabilities to the inflight host.

host^Required

• Type: IInflightHost

---

ops^Required

• Type: MutArray<str>

---

toInflight

bring cloud;

cloud.Topic.toInflight(obj: IResource);

Generates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.

NOTE: This statement must be executed within an async context.

obj^Required

• Type: IResource

---

Properties

Name	Type	Description
node	constructs.Node	The tree node.

---

node^Required

node: Node;

• Type: constructs.Node

The tree node.

---

Structs

TopicOnMessageOptions

Options for Topic.onMessage.

Initializer

bring cloud;

let TopicOnMessageOptions = cloud.TopicOnMessageOptions{ ... };

Properties

Name	Type	Description
concurrency	num	The maximum concurrent invocations that can run at one time.
env	MutMap<str>	Environment variables to pass to the function.
logRetentionDays	num	Specifies the number of days that function logs will be kept.
memory	num	The amount of memory to allocate to the function, in MB.
timeout	duration	The maximum amount of time the function can run.

---

concurrency^Optional

concurrency: num;

• Type: num
• Default: platform specific limits (100 on the simulator)

The maximum concurrent invocations that can run at one time.

---

env^Optional

env: MutMap<str>;

• Type: MutMap<str>
• Default: No environment variables.

Environment variables to pass to the function.

---

logRetentionDays^Optional

logRetentionDays: num;

• Type: num
• Default: 30

Specifies the number of days that function logs will be kept.

Setting negative value means logs will not expire.

---

memory^Optional

memory: num;

• Type: num
• Default: 1024

The amount of memory to allocate to the function, in MB.

---

timeout^Optional

timeout: duration;

• Type: duration
• Default: 1m

The maximum amount of time the function can run.

---

TopicProps

Options for Topic.

Initializer

bring cloud;

let TopicProps = cloud.TopicProps{ ... };

TopicSubscribeQueueOptions

Options for Topic.subscribeQueue.

Initializer

bring cloud;

let TopicSubscribeQueueOptions = cloud.TopicSubscribeQueueOptions{ ... };

Properties

Name	Type	Description
dlq	DeadLetterQueueProps	A dead-letter queue.
retentionPeriod	duration	How long a queue retains a message.
timeout	duration	How long a queue's consumers have to process a message.

---

dlq^Optional

dlq: DeadLetterQueueProps;

• Type: DeadLetterQueueProps
• Default: no dead letter queue

A dead-letter queue.

---

retentionPeriod^Optional

retentionPeriod: duration;

• Type: duration
• Default: 1h

How long a queue retains a message.

---

timeout^Optional

timeout: duration;

• Type: duration
• Default: 30s

How long a queue's consumers have to process a message.

---

Protocols

ITopicOnMessageHandler

• Extends: IInflight

• Implemented By: ITopicOnMessageHandler

Inflight client: @winglang/sdk.cloud.ITopicOnMessageHandlerClient

A resource with an inflight "handle" method that can be passed to Topic.on_message.

ITopicOnMessageHandlerClient

• Implemented By: ITopicOnMessageHandlerClient

Inflight client for ITopicOnMessageHandler.

Methods

Name	Description
handle	Function that will be called when a message is received from the topic.

---

handle

inflight handle(message: str): void

Function that will be called when a message is received from the topic.

message^Required

• Type: str

---