Design considerations

Deployment options

If this is the first time installing, or you are not sure what to install, deploy the virtual-waiting-room-on-aws-getting-started.template nested CloudFormation template, which installs the core, authorizers, and sample waiting room templates. This provides you a minimal waiting room with a simple flow.

Supported protocols

The Virtual Waiting Room on AWS solution can be integrated with the following:

• JSON Web Token verification libraries and tools

• Existing API Gateway deployments

• REST API clients

• OpenID clients and providers

Waiting room inlet strategies

Inlet strategies encapsulate the logic and data needed to move clients from the waiting room to the website. An inlet strategy can be implemented as a Lambda function, container, Amazon EC2 instance, or any other compute resource. It does not need to be a cloud resource as long as it can call the waiting room public and private APIs. The inlet strategy receives events about the waiting room, the website, or other outside indicators that help it decide when more clients can have tokens issued and enter the site. There are several approaches to inlet strategies. Which one you adopt depends on the resources available to you and constraints in the design of the website being protected.

The primary action taken by the inlet strategy is to call the increment_serving_num Amazon API Gateway private API with a relative value that indicates how many more clients can enter the site. This section describes two sample inlet strategies. These can be used as-is, customized, or you can employ a completely different approach.

MaxSize

Using the MaxSize strategy, the MaxSizeInlet Lambda function is configured with the maximum number of clients that can use the website concurrently. This is a fixed value. A client issues an Amazon SNS notification that invokes the MaxSizeInlet Lambda function to increase the serving counter based on the message payload. The source of the SNS message can come from anywhere, including code on the website or a monitoring tool that observes the site’s utilization level.

The MaxSizeInlet Lambda function expects to receive a message that can include:

• exited : number of transactions that have completed

• list of request IDs to be marked completed

• list of request IDs to be marked abandoned

This data is used to determine how much to increment the serving counter. There can be cases where there is no additional capacity to increment the counter, based on the current number of clients.

Periodic

When using the periodic strategy, a CloudWatch rule invokes the PeriodicInlet Lambda function every minute to increase the serving counter by a fixed quantity. The periodic inlet is parameterized with the event start time, end time, and increment amount. Optionally, this strategy also checks a CloudWatch alarm and, if the alarm is in OK state, it performs the increment, otherwise it skips it. The site integrators can connect a utilization metric to an alarm, and use that alarm to pause the periodic inlet. This strategy only changes the serving position while the current time is between the start and end times, and optionally, the specified alarm is in the OK state.

Customizing and extending the solution

Your organization’s site administrator must decide on the integration methods to use with the waiting room. There are two options:

1. Basic integration directly using APIs and API Gateway authorizers.

2. OpenID integration through an identity provider.

In addition to the integration above, you might be required to configure the domain name redirection. You are also responsible for deploying a customized waiting room site page.

The Virtual Waiting Room on AWS solution is designed for extension through two mechanisms: EventBridge for unidirectional event notification and REST APIs for bidirectional communication.

Quotas

The primary scale limitation for Virtual Waiting Room on AWS is the Lambda throttle limit for the installed AWS Region. When installed into an AWS account with the default Lambda concurrent run quota, the Virtual Waiting Room on AWS solution can handle up to 500 clients per second requesting a position in the queue. The 500 client per second rate is based on the solution having all Lambda function concurrent quota limits available exclusively. If the Region in the account is shared with other solutions that invoke Lambda functions, the Virtual Waiting Room on AWS solution should have at least 1,000 concurrent invocations available. You can use CloudWatch metrics to chart the Lambda concurrent invocations in your account over time to make a determination. You can use the Service Quotas console to request increases. Increasing the Lambda throttle limit only raises the monthly account charges if additional invocations actually occur.

For each additional 500 clients per second, increase your throttle limit by 1,000.

Incoming users per second expected	Recommended concurrent execution quota
0-500	1,000 (default)
501-1,000	2,000
1,001-1,500	3,000

Lambda has a fixed burst limit of 3,000 concurrent invocations. For more information, refer to Lambda function scaling. Client code should expect and retry some API calls if an error code is returned indicating a temporary throttle situation. The sample waiting room client includes this code as an example of how to design clients used in high capacity and high burst events.

This solution is also compatible with Lambda reserved and provisioned concurrency with custom configuration steps. For details, refer to Managing Lambda reserved concurrency.

The upper limit of users that can enter the waiting room, receive a token, and continue to a transaction is limited by the upper limit of Elasticache (Redis OSS) counters. The counters are used for the waiting room serving position and tracking summary state of the solution. The counters used in Elasticache (Redis OSS) have an upper limit of 9,223,372,036,854,775,807. A DynamoDB table is used to store a copy of each token issued to a waiting room user. DynamoDB has no practical limit on a table's size.

Regional deployments

Services used by this solution are supported in all AWS Regions. For the most current availability of AWS services by Region, refer to the AWS Regional Services List.