{"id":23107081,"url":"https://github.com/four43/aws-simple-websocket","last_synced_at":"2025-08-16T17:31:19.813Z","repository":{"id":65945915,"uuid":"398576492","full_name":"four43/aws-simple-websocket","owner":"four43","description":"Using AWS's API Gateway + Lambda to run a simple websocket application. For learning/testing.","archived":false,"fork":false,"pushed_at":"2021-08-24T15:06:16.000Z","size":112,"stargazers_count":15,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2023-03-18T04:25:17.573Z","etag":null,"topics":["aws","aws-lambda","getting-started","python","terraform","websocket"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/four43.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-08-21T14:19:40.000Z","updated_at":"2023-02-08T23:59:51.000Z","dependencies_parsed_at":"2023-02-17T18:25:14.734Z","dependency_job_id":null,"html_url":"https://github.com/four43/aws-simple-websocket","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/four43%2Faws-simple-websocket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/four43%2Faws-simple-websocket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/four43%2Faws-simple-websocket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/four43%2Faws-simple-websocket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/four43","download_url":"https://codeload.github.com/four43/aws-simple-websocket/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230047252,"owners_count":18164573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","getting-started","python","terraform","websocket"],"created_at":"2024-12-17T01:12:12.894Z","updated_at":"2024-12-17T01:12:13.537Z","avatar_url":"https://github.com/four43.png","language":"Python","readme":"# aws-simple-websocket\n\nUsing AWS's API Gateway + Lambda + Python to run a simple websocket application. For learning/testing. The AWS Resources\nseemed overly complex and were missing some critical gotchas in setting up a system like this.\n\n![Example terminal showing usage](./docs/example.gif)\n\nUsing the following for guidance:\n\n* [AWS Blog: Announcing WebSocket APIs in Amazon API Gateway](https://aws.amazon.com/blogs/compute/announcing-websocket-apis-in-amazon-api-gateway/)\n* [GitHub: aws-samples/simple-websockets-chat-app (Node.JS + SAM)](https://github.com/aws-samples/simple-websockets-chat-app)\n\n## Architecture\n\nTo keep things as basic as possible we're using a bare minimum of resources and CLI helpers where possible.\n\nA **client** makes a connection via Websocket to an **API Gateway V2**. That gateway maintains a socket connection for\nus, and sends events to some sort of \"integration\" or handler. In our case, this will be a **Lambda** function that will\nhandle the incoming socket events (**$connect**/**$disconnect**). It will handle messages sent from websocket clients,\nand to further expand this example, an outside data source via **SNS** topic. The API Gateway requires us to keep track\nof Connection IDs, so we can programmatically and precisely send messages to specific clients.\n\nUsing Terraform (in `./deployment`) the following are created:\n\n![Architecture Diagram](./docs/architecture.svg)\n\n1. **API Gateway V2 (Websocket)** - The primary Websocket management service which holds sockets for connections and can\n   hit a variety of AWS integrations\n\n1. **Lambda** - The main executor of business logic - where all our code will live\n\n1. **S3** - A basic Key/Value store for our connections\n\n1. **SNS** - To demonstrate an external publisher, our Lambda function is also listening to an SNS Topic\n\nSome additional resources are needed:\n\n1. **CloudWatch** - Logging for API Gateway and Lambda function with retention periods set by default\n\n1. **IAM** - Permissions to glue everything together\n\n## Deployment\n\nThis demo repo uses Terraform to manage cloud resources. These are all stored in the `./deployment` repository.\n**NOTE:** Creating resources in AWS may incur charges to your account. Ensure you have billing alarms setup and\nunderstand AWS costs. This demo repo should cost almost nothing, however.\n\n1. [Install Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli)\n1. Change to `./deployment` directory\n1. Init Terraform (`terraform init`)\n1. It's best practice to use \"Workspaces\" to namespace resources in terraform for different environments, so create\n   a `dev` workspace (`terraform workspace new dev`)\n1. Check if you need to\n   enable [API Gateway Logging](https://aws.amazon.com/premiumsupport/knowledge-center/api-gateway-cloudwatch-logs/) in\n   your current region. Feel free to set `./deployment/enf.tf:init_api_gw_logging_role` to false if your account already\n   has this setup\n1. Create the resources `terraform apply`\n1. Run `/util/lambda-deploy dev` to build and deploy the lambda code. There are no external dependencies, just `boto3`\n\n## Usage\n\nContained in `./util` are a lot of small CLI scripts to allow us to interact with the system without bloating the core\ntoo much with things like static web pages for the app side.\n\n* **lambda-build** - builds a zip archive for deployment to Lambda\n\n* **lambda-deploy** - runs `lambda-build` and deploys the archive to the provided Lambda environment. Uses `terraform` \n  to get the name of our Lambda function to deploy to\n\n* **send-data [json]** - Sends a JSON payload to connected clients via SNS Topic. Uses `terraform` to get the name of\n  our SNS Topic\n  \n* **tail-logs** - Watches logs for the API Gateway and Lambda function. Uses `terraform` to get the name of\n  our the log groups\n  \n* **connect** - Connect to the websocket using a small utility, [websocat](https://github.com/vi/websocat) \n\n### Quick Example\n\n 1. Deploy the stack using the above instructions.\n 1. `./util/connect` to connect and listen to the websocket\n 1. Using a new terminal session, `./util/send-data '{\"hello\": \"world\"}'`\n 1. View that in your first terminal with connect running, you'll see `{\"hello\": \"world\"}`\n\nUsers can broadcast messages to other users as well, not just through SNS. With a connected client, send: \n```json\n{\"action\": \"broadcast\", \"message\": \"Good news, everyone!\"}\n```\nYou will then see: `{\"message\": \"Good news, everyone!\"}` in all the connected clients.\n\n## Improvements\n\n1. Move from `print()` to `logging` module, for the sake of keeping this really simple, I left print in there\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffour43%2Faws-simple-websocket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffour43%2Faws-simple-websocket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffour43%2Faws-simple-websocket/lists"}