feat(events): add WebSocketConnectionContext helper for APIGatewayV2WebSocketEvent (#273)

[ramanathan1504]

This change addresses #273 by adding a session-like, Lambda-safe connection context for API Gateway WebSocket events.

What changed

• Added WebSocketConnectionContext to APIGatewayV2WebSocketEvent in aws-lambda-java-events/src/main/java/com/amazonaws/services/lambda/runtime/events/APIGatewayV2WebSocketEvent.java
• Added convenience accessors:
  • APIGatewayV2WebSocketEvent#getConnectionContext()
  • APIGatewayV2WebSocketEvent.RequestContext#getConnectionContext()
• Added getManagementApiEndpoint() to build https://{domainName}/{stage} for API Gateway Management API usage
• Added null/empty fallback behavior for endpoint parts (domainName, stage)
• Added tests in aws-lambda-java-events/src/test/java/com/amazonaws/services/lambda/runtime/events/APIGatewayV2WebSocketEventTest.java
• Documented usage and null-safe handling in aws-lambda-java-events/README.md
• Added release note entry in aws-lambda-java-events/RELEASE.CHANGELOG.md

Why

AWS Lambda WebSocket events do not provide a native Java WebSocketSession. This helper provides a lightweight session-like object built from event metadata (connectionId, domainName, stage) so handlers can easily pass one context object through their business logic.

Backward compatibility

• Non-breaking: existing event fields and getters remain unchanged.
• Existing code using requestContext.getConnectionId() continues to work.
• New behavior is additive only.

Error handling / fallback

• getConnectionContext() returns null when requestContext or connectionId is missing.
• getManagementApiEndpoint() returns null when domainName or stage is missing/empty.
• No new exceptions introduced.

[darklight3it]

Hello @ramanathan1504, thanks for your contribution, any help is appreciated ❤️

Before diving into implementation details, I'd love to understand the use case better and make sure we're solving the right problem.

Every class in aws-lambda-java-events maps directly to a field or structure in an actual AWS service payload. WebSocketConnectionContext would be the first derived/computed object in the library, it doesn't correspond to anything in the API Gateway WebSocket schema.

Issue #273 asks for a WebSocketSession, which makes sense from a Spring/Jakarta EE perspective. But in Lambda, API Gateway owns the connection and Lambda is invoked once per message. Exposing this kind of object in an official AWS library could mislead users into thinking the runtime holds the connection the way Jakarta EE or Spring WebSocket do.

Were you thinking about Lambda Managed Instances and their multi-concurrency model as a use case here?

Besides that, the example provided in the README looks to me functionally identical to the one using requestContext directly.

using WebSocketConnectionContext

WebSocketConnectionContext connection = event.getConnectionContext();
if (connection != null) {
    String connectionId = connection.getConnectionId();
    String endpoint = connection.getManagementApiEndpoint();
}

using RequestContext

var rc = event.getRequestContext();
if (rc != null && rc.getConnectionId() != null) {
    String connectionId = rc.getConnectionId();
    String endpoint = "https://" + rc.getDomainName() + "/" + rc.getStage();
}

The only saving is the URL concatenation. Could you share a scenario where this meaningfully reduces the complexity for the end user?

Thanks again for your time!