Skip to main content

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);
NameTypeDescription
props
TopicProps
No description.

propsOptional

Methods

Preflight Methods
NameDescription
onMessage
Run an inflight whenever an message is published to the topic.
subscribeQueue
Subscribing queue to the topic.
Inflight Methods
NameDescription
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.

inflightRequired

propsOptional

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

Subscribing queue to the topic.

queueRequired

propsOptional

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.

messagesRequired
  • Type: str

Payload to publish to Topic.


Static Functions

NameDescription
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.

hostRequired

opsRequired
  • 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.

objRequired

Properties

NameTypeDescription
node
constructs.NodeThe tree node.

nodeRequired
node: Node;
  • Type: constructs.Node

The tree node.


Structs

TopicOnMessageOptions

Options for Topic.onMessage.

Initializer

bring cloud;

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

Properties

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

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

The maximum concurrent invocations that can run at one time.


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

Environment variables to pass to the function.


logRetentionDaysOptional
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.


memoryOptional
memory: num;
  • Type: num
  • Default: 1024

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


timeoutOptional
timeout: duration;

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

NameTypeDescription
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.

dlqOptional
dlq: DeadLetterQueueProps;

A dead-letter queue.


retentionPeriodOptional
retentionPeriod: duration;

How long a queue retains a message.


timeoutOptional
timeout: duration;

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


Protocols

ITopicOnMessageHandler

Inflight client: @winglang/sdk.cloud.ITopicOnMessageHandlerClient

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

ITopicOnMessageHandlerClient

Inflight client for ITopicOnMessageHandler.

Methods

NameDescription
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.

messageRequired
  • Type: str