Nuages.PubSub is a WebSocket services based on API Gateway WebSocket. It provides all the building block to easily deploy the backend to Lambda using Cloud Formation.
- Similar to Azure Web PubSub
- Include WebSocket Service + Client API
- Open API endpoint available (/swagger)
- Many database options are available: DynamoDB, MongoDB, MySQL abnd SQL Server. More can be added by providing additional provider trough DI.
- Use the following AWS services
- API Gateway
- Lambda
- CloudFormation (CDK)
- IAM
- CloudWatch
- Route 53 for custom domain (optional)
- Certificate Manager (optional)
- System Manager (Parameter Store, App Config, optional)
- DynamoDB (optional)
IMPORTANT! You need .NET 6. You need to have CDK configured on your machine
https://docs.aws.amazon.com/cdk/v2/guide/work-with.html#work-with-prerequisites
Everything is ready to be used as-is. All you need to do is deploy using the CDK from you machine.
- git clone https://github.com/nuages-io/nuages-pubsub
- cdk deploy
- Wait for the deployment to complete
WebSocket Endpoint Url and API Endpoint Url will be outputed in the console window upon deployment completion. The API Key required to call the API is available via the AWS console in the API Gateway section if you did not provide a value,
That's it. Your Web Socket services and API are ready to go.
You can customize most of the settings to fit you needs. Just follow the instructions below.
git clone https://github.com/nuages-io/nuages-pubsub
The following context variable can be set to customize the deployment using the CDK. (See https://docs.aws.amazon.com/cdk/v2/guide/context.html for detail about context).
By default, the stack will be deployed with the current configuration
- Not part of a Vpc
- Auto generated URL for WebSocket Endpoint and API Endpoint
- DynamoDB as internal storage
- Auto-generated API key
- Default values for Issuer, Audience and Secret.
You can customize this behavior by setting the following options.
| Name | Description | Instructions |
|---|---|---|
| ConfigOptions__WebSocketDomain | WebSocket Endpoint Domain Name | DO NOT CREATE YOURSELF. Route53 recordset will be created with the stack |
| ConfigOptions__WebSocketCertificateArn | Certificate for WebSocket Endpoint | Required if WebSocketDomain is assigned. |
| ConfigOptions__ApiDomain | API Endpoint Domain Name | DO NOT CREATE YOURSELF. Route53 recordset will be created with the stack |
| ConfigOptions__ApiCertificateArn | Certificate for API Endpoint | Required if APIDomain is assigned |
| ConfigOptions__ApiApiKey | API Gateway API Key | Will be autogenerated if not provided |
| ConfigOptions__VpcId | Id of the VPC. | Must be the VPC of the database you connect to. If you connect to an Internet data source like MongoDb Atlas you will have to make sure the Lambda has internet access. |
| ConfigOptions__SecurityGroupId | Security group Id | The Lambdas will be added to this security group. If a database proxy is used, this security group must have access to the database proxy and the database |
The following options applies if you choose to use a DatabaseProxy for your MySQL database. Both the VPC and DatabaseProxy must exists and will NOT be created during deployment. All options are required.
IMPORTANT! Adding the lambda to a VPC will prevent outbound access to the Internet if the VPC does not provided a public subnet and an Internet Gateway. Nuages PubSub does not require a Internet connection, so this might not be an issue unless you customize the code and add services that connect to the Internet.
| Name | Description | Instructions |
|---|---|---|
| ConfigOptions__DatabaseProxy__User | Database user name | Must be the same as in the connection string |
| ConfigOptions__DatabaseProxy__Arn | ARN of the Database Proxy | Required. See Proxy properties. |
| ConfigOptions__DatabaseProxy__Endpoint | Proxy Endpoint | Required. See Proxy properties. |
| ConfigOptions__DatabaseProxy__Name | Name of the proxy | Required. See Proxy properties. |
| Name | Description | Instructions |
|---|---|---|
| RuntimeOptions__Data__Storage | Database storage used. Default: DynamoDB | DynamoDB, MySQL, SQLServer or MongoDB |
| RuntimeOptions__Data__ConnectionString | Connection string to connect to the database | May be a connection string, an AWS Secrets Arn or null if provided from application settings. |
IMPORTANT!!!
- Only DynamoDB tables will be deployed as part of the stack. For other database engines, you need to do this deploy on your own and provide the connection string.
- It is recommended to setup a DatabaseProxy for MySQL and SQL Server (https://docs.aws.amazon.com/lambda/latest/dg/configuration-database.html)
The following settings can be set at deployment time. You may also want to set the values using standard application settings (see following section).
| Name | Description | Instructions |
|---|---|---|
| RuntimeOptions__Auth_Issuer | Token issuer | Ex: MyCompany or https://mycompany.com |
| RuntimeOptions__Auth_Audience | Token audience | Ex: MyAudience |
| RuntimeOptions__Auth_Secret | Token secret | Ex. Oiwebwbehj439857948fekhekrht435 (any value you want) |
The following settings applies when you want to use External Authentication
| Name | Description | Instructions |
|---|---|---|
| RuntimeOptions__ExternalAuth_Enabled | Enabled when True | |
| RuntimeOptions__ExternalAuth_ValidAudiences | List of valid audiences | Comma separated |
| RuntimeOptions__ExternalAuth_ValidIssuers | List of valid isseurs URL | Must be URLs. Comma separated |
| RuntimeOptions__ExternalAuth_DisableSslCheck | Disable SSL certificate validation when True | Might be useful if you are using ngrok |
| RuntimeOptions__ExternalAuth_JsonWebKeySetUrlPath | Json Web Token Key Set Path. | Open OpenId configuration page for your issuer. Ex: https://myissuer.com/.well-known/openid-configuration . Look for the wks_url value. Enter only the Path element. |
| RuntimeOptions__ExternalAuth_Roles | Roles asisgned to connections | Default to "SendMessageToGroup JoinOrLeaveGroup" |
Run this command at the solution root
cdk deploy
Very quick intructions here...I will be working on something more complete soon.
-
Services URL are available in the Output tab of the Cloud Formation Nuages PubSub stack page
- One endpoint for WebSocket
- One endpoint for the API
-
You can get the WebSocket URL using the API Endpoint getclienturi method
The API endpoint is secured usingh the API Key you provided on deploy (or it has been automatically assign). You can retrieve the value from the API Keys section in the AWS Application Gateway page.
The API key value should be added to the x-api-key request header
curl --location --request GET \
'[Your-API-Url]/api/auth/getclienturi?userId=martin&roles=SendMessageToGroup&roles=JoinOrLeaveGroup' \
--header 'x-api-key: [Your-Api-Key]'
This will get a WebSocket client Url
Once you have the WebSocket Url, you can use it to connect using any WebSocket client
wscat -c "[Your-WebSocket-Client-Url]"
{ "type":"echo" }{ "type":"join","dataType" : "json","group" : "group1"}{ "type":"leave", "dataType" : "json", "group" : "group1"}{"type":"send", "dataType" : "json", "group" : "group1", "data": { "my_message" : "message sent to group" }}Additional capabilities are offered using the API Endpoint.
API Documentaton is available here https://app.swaggerhub.com/apis/Nuages/nuages-pub_sub/v1
C# SDK is available here https://www.nuget.org/packages/Nuages.PubSub.API.Sdk/