Skip to content

feat: WebSocket notifications template#7

Draft
gmoz22 wants to merge 10 commits into
jgilbert01:masterfrom
gmoz22:websocket
Draft

feat: WebSocket notifications template#7
gmoz22 wants to merge 10 commits into
jgilbert01:masterfrom
gmoz22:websocket

Conversation

@gmoz22
Copy link
Copy Markdown

@gmoz22 gmoz22 commented May 6, 2026 •
edited
Loading

Serverless backend + React MFE for pushing EventBridge events to browser clients in sub-second latency, with missed-event replay and live resubscription, without polling or per-user queues. Includes an end-to-end demo that deploys all infrastructure and hosts the MFE from a single terminal.

Requires aws-lambda-stream v1.2.0 or later. The WebSocket pipeline handlers (toConnections, toMessage, wsConnect, wsDisconnect, wsReplay, wsSubscribeWrite, wsSubscribeDelete) were introduced in that release.

Backend — template-websocket-service

  • EventBridge → broadcast Lambda (aws-lambda-stream pipeline) → API Gateway WebSocket push; events persisted to EventsTable with TTL
  • WebSocket lifecycle: connect, disconnect, replay, subscribe handlers
  • SubscriptionsTable supports per-type and catch-all (*) subscriptions
  • Missed-event replay on reconnect via client-triggered replay route
  • Live resubscription without reconnecting via subscribe route
  • Cross-region forwarding via EventBridge rule (opt-in, commented out)
  • toMessage, toConnections, and toUpdateRequest transformation logic in src/models/websocket.js
  • Full unit test coverage (c8 + Mocha + Chai) across broadcast, connections, and models

Frontend — template-websocket-mfe

  • useWebSocket hook: connects, auto-reconnects with exponential backoff, handles live resubscription and opt-in missed-event replay via sessionStorage
  • App, ConnectionStatus, EventLog, TagInput components
  • Single-SPA lifecycle integration, Vite build, dark console-style UI

Demo — template-websocket-demo

  • scripts/deploy.sh — deploys the EventBridge bus, WebSocket service, and MFE to S3 + CloudFront in sequence
  • scripts/demo.sh — interactive CLI runner for emitting test events and observing live pushes end-to-end
  • scripts/cleanup.sh — tears down all deployed stacks and S3 assets
  • src/emit.js — standalone EventBridge emitter for triggering test notifications
  • serverless.yml — minimal Serverless Framework config for the demo bus stack

See README.md for more info.

Previewing the WebSocket feature outside of the official aws-lambda-stream library

In the /additional/template-websocket-notifications/template-websocket-service/ folder, modify package.json to point to the folder of the local aws-lambda-stream websocket branch:
"aws-lambda-stream": "file:../aws-lambda-stream-websocket/",
or
"aws-lambda-stream": "file:/Users/gmoz22/WEBDEV/aws-lambda-stream-websocket/",
And run npm install to make sure it works.

DEMO (5m)

aws-lambda-stream_websocket_demo full

@gmoz22
feat: real-time WebSocket notifications template
7c0ed55 
Serverless backend + React MFE for pushing EventBridge events to browser clients in sub-second latency, with missed-event replay and live resubscription — without polling or per-user queues.

Backend (template-websocket-service):
- EventBridge → broadcast Lambda (aws-lambda-stream pipeline) → API Gateway WebSocket push; events persisted to EventsTable with TTL
- WebSocket lifecycle: connect, disconnect, replay, subscribe handlers
- SubscriptionsTable supports per-type and catch-all (*) subscriptions
- Missed-event replay on reconnect via client-triggered replay route
- Live resubscription without reconnecting via subscribe route
- Cross-region forwarding via EventBridge rule (opt-in, commented out)
- Transformation logic (toMessage, toConnections, toUpdateRequest) extracted to src/models/websocket.js following template-bff-service pattern
- Full unit test coverage (c8 + Mocha + Chai) across broadcast, connections, and models

Frontend (template-websocket-mfe):
- useWebSocket hook: connects, auto-reconnects with exponential backoff, handles live resubscription and opt-in missed-event replay via sessionStorage
- App, ConnectionStatus, EventLog, TagInput components
- Single-SPA lifecycle integration, Vite build, dark console UI

Co-authored-by: Copilot <copilot@github.com>
@gmoz22 gmoz22 marked this pull request as draft May 12, 2026 21:35
@gmoz22
feat: real-time WebSocket notifications template
f491ddb 
Serverless backend + React MFE for pushing EventBridge events to browser clients in sub-second latency, with missed-event replay and live resubscription — without polling or per-user queues.

Backend (template-websocket-service):
- EventBridge → broadcast Lambda (aws-lambda-stream pipeline) → API Gateway WebSocket push; events persisted to EventsTable with TTL
- WebSocket lifecycle: connect, disconnect, replay, subscribe handlers
- SubscriptionsTable supports per-type and catch-all (*) subscriptions
- Missed-event replay on reconnect via client-triggered replay route
- Live resubscription without reconnecting via subscribe route
- Cross-region forwarding via EventBridge rule (opt-in, commented out)
- Transformation logic (toMessage, toConnections, toUpdateRequest) extracted to src/models/websocket.js following template-bff-service pattern
- Full unit test coverage (c8 + Mocha + Chai) across broadcast, connections, and models

Frontend (template-websocket-mfe):
- useWebSocket hook: connects, auto-reconnects with exponential backoff, handles live resubscription and opt-in missed-event replay via sessionStorage
- App, ConnectionStatus, EventLog, TagInput components
- Single-SPA lifecycle integration, Vite build, dark console UI
@gmoz22
Copy link
Copy Markdown
Author

gmoz22 commented May 12, 2026

Dependency: MR #441 on aws-lambda-stream (target version is 1.2.0).

gmoz22 added 7 commits May 12, 2026 20:12
@gmoz22
feat(websocket-notifications): add end-to-end demo package
0753d57 
- Add template-websocket-demo with deploy, demo, and cleanup scripts, serverless config, and an EventBridge emitter
- Add build:standalone mode to template-websocket-mfe (Vite standalone output to dist/standalone)
- Fix config.yml: rename hubStack → busStack and update CloudFormation cross-references accordingly
- Update READMEs to reference template-websocket-demo and document aws-lambda-stream v1.2.0 requirement
@gmoz22
Merge branch 'websocket' of github.com:gmoz22/aws-lambda-stream-templ…
8461fd7 
…ates into websocket
@gmoz22
fix(websocket-demo): skip stacks that are already deployed or in prog…
1db953f 
…ress

- Check CloudFormation if stacks are deployed, else trigger a full deploy
- Add AWS CLI v1 detection and Node.js version check to preflight, remove redundant serverless --version check
- docs: clarify AWS_PROFILE step in prerequisites
@gmoz22
fix(websocket-demo): skip stacks that are already deployed or in prog…
aefaa25 
…ress

- Check CloudFormation if stacks are deployed, else trigger a full deploy
- Add AWS CLI v1 detection and Node.js version check to preflight, remove redundant serverless --version check
- docs: clarify AWS_PROFILE step in prerequisites
@gmoz22
Merge branch 'websocket' of github.com:gmoz22/aws-lambda-stream-templ…
9cfacfe 
…ates into websocket
@gmoz22
doc(websocket-demo): update prerequisites
89784bc
@gmoz22
fix(websocket-demo): Remove EventBridge rules before CloudFormation c…
0b032a7 
…an remove bus
@gmoz22 gmoz22 mentioned this pull request May 20, 2026
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@gmoz22