Add (API Gateway) WebSockets Support to Swift for AWS Lambda Events (#38)

Add APIGateway WebSockets Event Type

### Motivation:

What I propose is adding WebSockets support to AWS Lambda Events.

Let me begin by stating outright that I am not sure this is the correct
approach to take to bring WebSockets to AWS Lambda Events. Therefore, if
this pull request is outright rejected, it won't hurt my feelings in the
slightest.

API Gateway supports not only RESTful APIs, but also WebSockets. The way
that it works is that API Gateway manages WebSockets sessions with
clients. Whenever a client sends API Gateway some WebSockets data, API
Gateway bundles it up in as an APIGatewayV2 request (at least, according
to Amazon) and passes it along to a designated target…usually a Lambda
function. This is what a bundled request looks like:

```javascript
{  
 headers: {
    Host: 'lqrlmblaa2.execute-api.us-east-1.amazonaws.com',
    Origin: 'wss://lqrlmblaa2.execute-api.us-east-1.amazonaws.com',
    'Sec-WebSocket-Extensions': 'permessage-deflate; client_max_window_bits; server_max_window_bits=15',
    'Sec-WebSocket-Key': 'am5ubWVpbHd3bmNyYXF0ag==',
    'Sec-WebSocket-Version': '13',
    'X-Amzn-Trace-Id': 'Root=1-64b83950-42de8e247b4c2b43091ef67c',
    'X-Forwarded-For': '24.148.42.16',
    'X-Forwarded-Port': '443',
    'X-Forwarded-Proto': 'https'
  },
  multiValueHeaders: {
    Host: [ 'lqrlmblaa2.execute-api.us-east-1.amazonaws.com' ],
    Origin: [ 'wss://lqrlmblaa2.execute-api.us-east-1.amazonaws.com' ],
    'Sec-WebSocket-Extensions': [
      'permessage-deflate; client_max_window_bits; server_max_window_bits=15'
    ],
    'Sec-WebSocket-Key': [ 'am5ubWVpbHd3bmNyYXF0ag==' ],
    'Sec-WebSocket-Version': [ '13' ],
    'X-Amzn-Trace-Id': [ 'Root=1-64b83950-42de8e247b4c2b43091ef67c' ],
    'X-Forwarded-For': [ '24.148.42.16' ],
    'X-Forwarded-Port': [ '443' ],
    'X-Forwarded-Proto': [ 'https' ]
  },
  requestContext: {
    routeKey: '$connect',
    eventType: 'CONNECT',
    extendedRequestId: 'IU3kkGyEoAMFwZQ=',
    requestTime: '19/Jul/2023:19:28:16 +0000',
    messageDirection: 'IN',
    stage: 'dev',
    connectedAt: 1689794896145,
    requestTimeEpoch: 1689794896162,
    identity: { sourceIp: '24.148.42.16' },
    requestId: 'IU3kkGyEoAMFwZQ=',
    domainName: 'lqrlmblaa2.execute-api.us-east-1.amazonaws.com',
    connectionId: 'IU3kkeN4IAMCJwA=',
    apiId: 'lqrlmblaa2'
  },
  isBase64Encoded: false
}
```

The problem, of course, is that the current `APIGatewayV2Request` type
cannot decode that JSON because it is is missing a number of
non-optional data values that `APIGatewayV2Request` expects to exist
(e.g., `version`, `rawPath`, etc.).

There are (at least as far as I can tell) two solutions to make this
work. The first is simply to alter the current `APIGatewayV2Request` so
that a number of its data values become optionals. I resisted suggesting
this because I suspected it could easily break production code (forcing
developers to `if-let` things). I thought a better solution might simply
be to create a new request/response type pair that could accommodate
WebSockets APIs.

### Modifications:
I suggest adding a new event source file to AWS Lambda Events:
`APIGateway+WebSockets.swift` containing two new types:
`APIGatewayWebSocketRequest` and `APIGatewayWebSocketResponse`.
`APIGatewayWebSocketResponse` would simply be a type alias (since
responses require that no changes be made to that type);
`APIGatewayWebSocketRequest` would be capable of decoding the JSON
listed above.
A typical Lambda handler supporting WebSockets would look like this:

```swift
func handle(
  _ request: APIGatewayWebSocketRequest,
  context: LambdaContext
) async throws -> APIGatewayWebSocketResponse {

  let connectionID = request.context.connectionId
  let routeKey = request.context.routeKey
	
  // Route based on the type of WebSockets request
  // The following are "default" request types
  switch routeKey {
  case "$connect": break
  case "$disconnect": break
  case "$default":
    if let body = request.body {
    // Responses are sent to clients via the
    // ApiGatewayManagementApi. "post" is a method
    // (not shown) which does that
      try await post(
        message: "{\"echo\": \"\(body)\"}",
        toConnectionWithID: connectionID
      )
    }
    default:
      logger.log(level: .info, "Something weird happened");
    }

  // API Gateway requires that "some" status be returned
  // "no matter what"  
  return APIGatewayWebSocketResponse(statusCode: .ok)

}
```

Note that responses to WebSockets clients (including, potentially,
errors) are made through Amazon's `ApiGatewayManagementApi`. However,
API Gateway itself always expects some kind of response…this can be a
simple as always sending a 200 "OK" back to API Gateway.

### Result:
The Swift for AWS Lambda Runtime would be able to support API Gateway
WebSockets applications.

---------

Co-authored-by: Sébastien Stormacq <[email protected]>

Author: richwolf

Sources/AWSLambdaEvents/APIGateway+WebSockets.swift

@@ -0,0 +1,68 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright (c) YEARS Apple Inc. and the SwiftAWSLambdaRuntime project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+/// `APIGatewayWebSocketRequest` is a variation of the`APIGatewayV2Request`
+/// and contains data coming from the WebSockets API Gateway.
+public struct APIGatewayWebSocketRequest: Codable {
+    /// `Context` contains information to identify the AWS account and resources invoking the Lambda function.
+    public struct Context: Codable {
+        public struct Identity: Codable {
+            public let sourceIp: String
+        }
+
+        public let routeKey: String
+        public let eventType: String
+        public let extendedRequestId: String
+        /// The request time in format: 23/Apr/2020:11:08:18 +0000
+        public let requestTime: String
+        public let messageDirection: String
+        public let stage: String
+        public let connectedAt: UInt64
+        public let requestTimeEpoch: UInt64
+        public let identity: Identity
+        public let requestId: String
+        public let domainName: String
+        public let connectionId: String
+        public let apiId: String
+    }
+
+    public let headers: HTTPHeaders?
+    public let multiValueHeaders: HTTPMultiValueHeaders?
+    public let context: Context
+    public let body: String?
+    public let isBase64Encoded: Bool?
+
+    enum CodingKeys: String, CodingKey {
+        case headers
+        case multiValueHeaders
+        case context = "requestContext"
+        case body
+        case isBase64Encoded
+    }
+}
+
+/// `APIGatewayWebSocketResponse` is a type alias for `APIGatewayV2Request`.
+/// Typically, lambda WebSockets servers send clients data via
+/// the ApiGatewayManagementApi mechanism. However, APIGateway does require
+/// lambda servers to return some kind of status when APIGateway invokes them.
+/// This can be as simple as always returning a 200 "OK" response for all
+/// WebSockets requests (the ApiGatewayManagementApi can return any errors to
+/// WebSockets clients).
+public typealias APIGatewayWebSocketResponse = APIGatewayV2Response
+
+#if swift(>=5.6)
+extension APIGatewayWebSocketRequest: Sendable {}
+extension APIGatewayWebSocketRequest.Context: Sendable {}
+extension APIGatewayWebSocketRequest.Context.Identity: Sendable {}
+#endif

Tests/AWSLambdaEventsTests/APIGateway+WebsocketsTests.swift

@@ -0,0 +1,78 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright (c) YEARS Apple Inc. and the SwiftAWSLambdaRuntime project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+import Testing
+
+@testable import AWSLambdaEvents
+
+@Suite
+class APIGatewayWebSocketsTests {
+    static let exampleConnectEventBody = """
+        {
+          "headers": {
+            "Host": "lqrlmblaa2.execute-api.us-east-1.amazonaws.com",
+            "Origin": "wss://lqrlmblaa2.execute-api.us-east-1.amazonaws.com",
+            "Sec-WebSocket-Extensions": "",
+            "Sec-WebSocket-Key": "am5ubWVpbHd3bmNyYXF0ag==",
+            "Sec-WebSocket-Version": "13",
+            "X-Amzn-Trace-Id": "Root=1-64b83950-42de8e247b4c2b43091ef67c",
+            "X-Forwarded-For": "24.148.42.16",
+            "X-Forwarded-Port": "443",
+            "X-Forwarded-Proto": "https"
+          },
+          "multiValueHeaders": {
+            "Host": [ "lqrlmblaa2.execute-api.us-east-1.amazonaws.com" ],
+            "Origin": [ "wss://lqrlmblaa2.execute-api.us-east-1.amazonaws.com" ],
+            "Sec-WebSocket-Extensions": [
+              "permessage-deflate; client_max_window_bits; server_max_window_bits=15"
+            ],
+            "Sec-WebSocket-Key": [ "am5ubWVpbHd3bmNyYXF0ag==" ],
+            "Sec-WebSocket-Version": [ "13" ],
+            "X-Amzn-Trace-Id": [ "Root=1-64b83950-42de8e247b4c2b43091ef67c" ],
+            "X-Forwarded-For": [ "24.148.42.16" ],
+            "X-Forwarded-Port": [ "443" ],
+            "X-Forwarded-Proto": [ "https" ]
+          },
+          "requestContext": {
+            "routeKey": "$connect",
+            "eventType": "CONNECT",
+            "extendedRequestId": "IU3kkGyEoAMFwZQ=",
+            "requestTime": "19/Jul/2023:19:28:16 +0000",
+            "messageDirection": "IN",
+            "stage": "dev",
+            "connectedAt": 1689794896145,
+            "requestTimeEpoch": 1689794896162,
+            "identity": { "sourceIp": "24.148.42.16" },
+            "requestId": "IU3kkGyEoAMFwZQ=",
+            "domainName": "lqrlmblaa2.execute-api.us-east-1.amazonaws.com",
+            "connectionId": "IU3kkeN4IAMCJwA=",
+            "apiId": "lqrlmblaa2"
+          },
+          "isBase64Encoded": false
+        }
+        """
+
+    // MARK: - Request -
+
+    // MARK: Decoding
+    @Test func testRequestDecodingExampleConnectRequest() async throws {
+        let data = APIGatewayWebSocketsTests.exampleConnectEventBody.data(using: .utf8)!
+        let req = try JSONDecoder().decode(APIGatewayWebSocketRequest.self, from: data)
+
+        #expect(req.context.routeKey == "$connect")
+        #expect(req.context.connectionId == "IU3kkeN4IAMCJwA=")
+        #expect(req.body == nil)
+    }
+}