Queue

The cloud.Queue resource represents a data structure for holding a list of messages. Queues are typically used to decouple producers of data and the consumers of said data in distributed systems. Queues by default are not FIFO (first in, first out) - so the order of messages is not guaranteed.

Usage

Setting a Queue Consumer

bring cloud;

let q = new cloud.Queue();

q.setConsumer(inflight (m: str) => {
  log("message ${m} consumed");
});

new cloud.Function(inflight () => {
  q.push("message a");
  q.push("message b");
});

Using Queue inflight api

Pushing messages, popping them, and purging.

bring cloud;

let q = new cloud.Queue();

new cloud.Function(inflight () => {
  q.push("message a");
  q.push("message b", "message c", "message d");
  log("approxSize is ${q.approxSize()}");
  log("popping message ${q.pop()!}");
  log("popping message ${q.pop()!}");
  log("approxSize is ${q.approxSize()}");
  q.purge();
  log("approxSize is ${q.approxSize()}");
});

Adding a dead-letter queue

Creating a queue and adding a dead-letter queue with the maximum number of attempts configured

bring cloud;

let dlq = new cloud.Queue() as "dead-letter queue";
let q = new cloud.Queue(
  dlq: { 
    queue: dlq,
    maxDeliveryAttempts: 2
  }
);

Referencing an external queue

If you would like to reference an existing queue from within your application you can use the QueueRef classes in the target-specific namespaces.

This is currently only supported for aws.

The following example defines a reference to an Amazon SQS queue with a specific ARN and sends a message to the queue from the function:

bring cloud;
bring aws;

let outbox = new aws.QueueRef("arn:aws:sqs:us-east-1:111111111111:Outbox");

new cloud.Function(inflight () => {
  outbox.push("send an email");
});

This works both when running in the simulator (requires AWS credentials on the developer's machine) and when deployed to AWS. When this is deployed to AWS, the AWS Lambda IAM policy will include the needed permissions.

Target-specific details

Simulator (`sim`)

The sim implementation of cloud.Queue uses JavaScript's Array

AWS (`tf-aws` and `awscdk`)

The AWS implementation of cloud.Queue uses Amazon Simple Queue Service.

Azure (`tf-azure`)

🚧 Not supported yet (tracking issue: #617)

GCP (`tf-gcp`)

🚧 Not supported yet (tracking issue: #616)

API Reference

Queue

A queue.

Initializers

bring cloud;

new cloud.Queue(props?: QueueProps);

Name	Type	Description
`props`	`QueueProps`	No description.

`props`^Optional

Type: QueueProps

Methods

Preflight Methods

Name	Description
`setConsumer`	Create a function to consume messages from this queue.

Inflight Methods

Name	Description
`approxSize`	Retrieve the approximate number of messages in the queue.
`pop`	Pop a message from the queue.
`purge`	Purge all of the messages in the queue.
`push`	Push one or more messages to the queue.

`setConsumer`

setConsumer(handler: IQueueSetConsumerHandler, props?: QueueSetConsumerOptions): Function

Create a function to consume messages from this queue.

`handler`^Required

Type: IQueueSetConsumerHandler

`props`^Optional

Type: QueueSetConsumerOptions

`approxSize`

inflight approxSize(): num

Retrieve the approximate number of messages in the queue.

`pop`

inflight pop(): str?

Pop a message from the queue.

`purge`

inflight purge(): void

Purge all of the messages in the queue.

`push`

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

Push one or more messages to the queue.

`messages`^Required

Type: str

Payload to send to the queue.

Each message must be non-empty.

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

DeadLetterQueueProps

Dead letter queue options.

Initializer

bring cloud;

let DeadLetterQueueProps = cloud.DeadLetterQueueProps{ ... };

Properties

Name	Type	Description
`queue`	`Queue`	Queue to receive messages that failed processing.
`maxDeliveryAttempts`	`num`	Number of times a message will be processed before being sent to the dead-letter queue.

`queue`^Required

queue: Queue;

Type: Queue

Queue to receive messages that failed processing.

`maxDeliveryAttempts`^Optional

maxDeliveryAttempts: num;

Type: num
Default: 1

Number of times a message will be processed before being sent to the dead-letter queue.

QueueProps

Options for Queue.

Initializer

bring cloud;

let QueueProps = cloud.QueueProps{ ... };

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.

QueueSetConsumerOptions

Options for Queue.setConsumer.

Initializer

bring cloud;

let QueueSetConsumerOptions = cloud.QueueSetConsumerOptions{ ... };

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.
`batchSize`	`num`	The maximum number of messages to send to subscribers at once.

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

`batchSize`^Optional

batchSize: num;

Type: num
Default: 1

The maximum number of messages to send to subscribers at once.

Protocols

IQueueSetConsumerHandler

Extends: IInflight
Implemented By: IQueueSetConsumerHandler

Inflight client: @winglang/sdk.cloud.IQueueSetConsumerHandlerClient

A resource with an inflight "handle" method that can be passed to Queue.setConsumer.

IQueueSetConsumerHandlerClient

Implemented By: IQueueSetConsumerHandlerClient

Inflight client for IQueueSetConsumerHandler.

Methods

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

`handle`

inflight handle(message: str): void

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

`message`^Required

Type: str

Usage​

Setting a Queue Consumer​

Using Queue inflight api​

Adding a dead-letter queue​

Referencing an external queue​

Target-specific details​

Simulator (sim)​

AWS (tf-aws and awscdk)​

Azure (tf-azure)​

GCP (tf-gcp)​

API Reference ​

Queue ​

Initializers ​

propsOptional ​

Methods ​

Preflight Methods​

Inflight Methods​

setConsumer ​

handlerRequired ​

propsOptional ​

approxSize ​

pop ​

purge ​

push ​

messagesRequired ​

Static Functions ​

onLiftType ​

hostRequired ​

opsRequired ​

toInflight ​

objRequired ​

Properties ​

nodeRequired ​

Structs ​

DeadLetterQueueProps ​

Initializer ​

Properties ​

queueRequired ​

maxDeliveryAttemptsOptional ​

QueueProps ​

Initializer ​

Properties ​

dlqOptional ​

retentionPeriodOptional ​

timeoutOptional ​

QueueSetConsumerOptions ​

Initializer ​

Properties ​

concurrencyOptional ​

envOptional ​

logRetentionDaysOptional ​

memoryOptional ​

timeoutOptional ​

batchSizeOptional ​

Protocols ​

IQueueSetConsumerHandler ​

IQueueSetConsumerHandlerClient ​

Methods ​

handle ​

messageRequired ​

Usage

Setting a Queue Consumer

Using Queue inflight api

Adding a dead-letter queue

Referencing an external queue

Target-specific details

Simulator (`sim`)

AWS (`tf-aws` and `awscdk`)

Azure (`tf-azure`)

GCP (`tf-gcp`)

API Reference

Queue

Initializers

`props`^Optional

Methods

Preflight Methods

Inflight Methods

`setConsumer`

`handler`^Required

`props`^Optional

`approxSize`

`pop`

`purge`

`push`

`messages`^Required

Static Functions

`onLiftType`

`host`^Required

`ops`^Required

`toInflight`

`obj`^Required

Properties

`node`^Required

Structs

DeadLetterQueueProps

Initializer

Properties

`queue`^Required

`maxDeliveryAttempts`^Optional

QueueProps

Initializer

Properties

`dlq`^Optional

`retentionPeriod`^Optional

`timeout`^Optional

QueueSetConsumerOptions

Initializer

Properties

`concurrency`^Optional

`env`^Optional

`logRetentionDays`^Optional

`memory`^Optional

`timeout`^Optional

`batchSize`^Optional

Protocols

IQueueSetConsumerHandler

IQueueSetConsumerHandlerClient

Methods

`handle`

`message`^Required