Add documentation, add new internal LambdaRuntimeClientResponseStreamWriter, move Foundation import from AWSLambdaRuntimeCore

Author: aryan-25

Sources/AWSLambdaRuntime/Lambda+Codable.swift

@@ -16,9 +16,13 @@
 import NIOCore
 import NIOFoundationCompat
 
+#if canImport(FoundationEssentials)
+import FoundationEssentials
+#else
 import struct Foundation.Data
 import class Foundation.JSONDecoder
 import class Foundation.JSONEncoder
+#endif
 
 // MARK: - SimpleLambdaHandler Codable support
 
@@ -138,3 +142,6 @@ extension Lambda {
 extension JSONDecoder: LambdaCodableDecoder {}
 
 extension JSONEncoder: LambdaCodableEncoder {}
+
+extension JSONDecoder: AWSLambdaRuntimeCore.LambdaEventDecoder {}
+extension JSONEncoder: AWSLambdaRuntimeCore.LambdaOutputEncoder {}

Sources/AWSLambdaRuntimeCore/LambdaRuntimeClientProtocol.swift

@@ -14,8 +14,15 @@
 
 import NIOCore
 
+package protocol LambdaRuntimeClientResponseStreamWriter: LambdaResponseStreamWriter {
+    mutating func write(_ buffer: ByteBuffer) async throws
+    func finish() async throws
+    func writeAndFinish(_ buffer: ByteBuffer) async throws
+    func reportError(_ error: any Error) async throws
+}
+
 package protocol LambdaRuntimeClientProtocol {
-    associatedtype Writer: LambdaResponseStreamWriter
+    associatedtype Writer: LambdaRuntimeClientResponseStreamWriter
 
     func nextInvocation() async throws -> (Invocation, Writer)
 }

Sources/AWSLambdaRuntimeCore/NewLambda+JSON.swift

@@ -13,40 +13,55 @@
 //===----------------------------------------------------------------------===//
 
 import NIOCore
-import NIOFoundationCompat
-
-import class Foundation.JSONDecoder
-import class Foundation.JSONEncoder
 
+/// The protocol a decoder must conform to so that it can be used with ``LambdaCodableAdapter`` to decode incoming
+/// ``ByteBuffer`` events.
 package protocol LambdaEventDecoder {
+    /// Decode the ``ByteBuffer`` representing the received event into the generic ``Event`` type
+    /// the handler will receive.
+    /// - Parameters:
+    ///   - type: The type of the object to decode the buffer into.
+    ///   - buffer: The buffer to be decoded.
+    /// - Returns: An object containing the decoded data.
     func decode<Event: Decodable>(_ type: Event.Type, from buffer: ByteBuffer) throws -> Event
 }
 
+/// The protocol an encoder must conform to so that it can be used with ``LambdaCodableAdapter`` to encode the generic
+/// ``Output`` object into a ``ByteBuffer``.
 package protocol LambdaOutputEncoder {
+    /// Encode the generic type `Output` the handler has returned into a ``ByteBuffer``.
+    /// - Parameters:
+    ///   - value: The object to encode into a ``ByteBuffer``.
+    ///   - buffer: The ``ByteBuffer`` where the encoded value will be written to.
     func encode<Output: Encodable>(_ value: Output, into buffer: inout ByteBuffer) throws
 }
 
-extension JSONEncoder: LambdaOutputEncoder {}
-
-extension JSONDecoder: LambdaEventDecoder {}
-
 package struct VoidEncoder: LambdaOutputEncoder {
     package func encode<Output>(_ value: Output, into buffer: inout NIOCore.ByteBuffer) throws where Output: Encodable {
         fatalError("LambdaOutputEncoder must never be called on a void output")
     }
 }
 
+/// Adapts a ``NewLambdaHandler`` conforming handler to conform to ``LambdaWithBackgroundProcessingHandler``.
 package struct LambdaHandlerAdapter<
     Event: Decodable,
     Output,
     Handler: NewLambdaHandler
 >: LambdaWithBackgroundProcessingHandler where Handler.Event == Event, Handler.Output == Output {
     let handler: Handler
 
+    /// Initializes an instance given a concrete handler.
+    /// - Parameter handler: The ``NewLambdaHandler`` conforming handler that is to be adapted to ``LambdaWithBackgroundProcessingHandler``.
     package init(handler: Handler) {
         self.handler = handler
     }
 
+    /// Passes the generic ``Event`` object to the ``NewLambdaHandler/handle(_:context:)`` function, and
+    /// the resulting output is then written to ``LambdaWithBackgroundProcessingHandler``'s `outputWriter`.
+    /// - Parameters:
+    ///   - event: The received event.
+    ///   - outputWriter: The writer to write the computed response to.
+    ///   - context: The ``NewLambdaContext`` containing the invocation's metadata.
     package func handle(
         _ event: Event,
         outputWriter: consuming some LambdaResponseWriter<Output>,
@@ -57,6 +72,7 @@ package struct LambdaHandlerAdapter<
     }
 }
 
+/// Adapts a ``LambdaWithBackgroundProcessingHandler`` conforming handler to conform to ``StreamingLambdaHandler``.
 package struct LambdaCodableAdapter<
     Handler: LambdaWithBackgroundProcessingHandler,
     Event: Decodable,
@@ -69,18 +85,32 @@ package struct LambdaCodableAdapter<
     let decoder: Decoder
     private var byteBuffer: ByteBuffer = .init()
 
+    /// Initializes an instance given an encoder, decoder, and a handler with a non-`Void` output.
+    ///   - Parameters:
+    ///   - encoder: The encoder object that will be used to encode the generic ``Output`` obtained from the `handler`'s `outputWriter` into a ``ByteBuffer``.
+    ///   - decoder: The decoder object that will be used to decode the received ``ByteBuffer`` event into the generic ``Event`` type served to the `handler`.
+    ///   - handler: The handler object.
     package init(encoder: Encoder, decoder: Decoder, handler: Handler) where Output: Encodable {
         self.encoder = encoder
         self.decoder = decoder
         self.handler = handler
     }
 
+    /// Initializes an instance given a decoder, and a handler with a `Void` output.
+    ///   - Parameters:
+    ///   - decoder: The decoder object that will be used to decode the received ``ByteBuffer`` event into the generic ``Event`` type served to the `handler`.
+    ///   - handler: The handler object.
     package init(decoder: Decoder, handler: Handler) where Output == Void, Encoder == VoidEncoder {
         self.encoder = VoidEncoder()
         self.decoder = decoder
         self.handler = handler
     }
 
+    /// A ``StreamingLambdaHandler/handle(_:responseWriter:context:)`` wrapper.
+    ///   - Parameters:
+    ///   - event: The received event.
+    ///   - outputWriter: The writer to write the computed response to.
+    ///   - context: The ``NewLambdaContext`` containing the invocation's metadata.
     package mutating func handle(
         _ request: ByteBuffer,
         responseWriter: some LambdaResponseStreamWriter,
@@ -93,16 +123,23 @@ package struct LambdaCodableAdapter<
     }
 }
 
+/// A ``LambdaResponseStreamWriter`` wrapper that conforms to ``LambdaResponseWriter``.
 package struct ResponseWriter<Output>: LambdaResponseWriter {
     let underlyingStreamWriter: LambdaResponseStreamWriter
     let encoder: LambdaOutputEncoder
     var byteBuffer = ByteBuffer()
 
+    /// Initializes an instance given an encoder and an underlying ``LambdaResponseStreamWriter``.
+    /// - Parameters:
+    ///   - encoder: The encoder object that will be used to encode the generic ``Output`` into a ``ByteBuffer``, which will then be passed to `streamWriter`.
+    ///   - streamWriter: The underlying ``LambdaResponseStreamWriter`` that will be wrapped.
     package init(encoder: LambdaOutputEncoder, streamWriter: LambdaResponseStreamWriter) {
         self.encoder = encoder
         self.underlyingStreamWriter = streamWriter
     }
 
+    ///  Passes the `response` argument to ``LambdaResponseStreamWriter/writeAndFinish(_:)``.
+    /// - Parameter response: The generic ``Output`` object that will be passed to ``LambdaResponseStreamWriter/writeAndFinish(_:)``.
     package mutating func write(response: Output) async throws {
         if Output.self == Void.self {
             try await self.underlyingStreamWriter.finish()

Sources/AWSLambdaRuntimeCore/NewLambdaHandlers.swift

@@ -14,59 +14,129 @@
 
 import NIOCore
 
+/// The base handler protocol that receives a ``ByteBuffer`` representing the incoming event and returns the response as a ``ByteBuffer`` too.
+/// This handler protocol supports response streaming. Bytes can be streamed outwards through the ``LambdaResponseStreamWriter``
+/// passed as an argument in the ``handle(_:responseWriter:context:)`` function.
+/// Background work can also be executed after returning the response. After closing the response stream by calling
+/// ``LambdaResponseStreamWriter/finish()`` or ``LambdaResponseStreamWriter/writeAndFinish(_:)``,
+/// the ``handle(_:responseWriter:context:)`` function is free to execute any background work.
 package protocol StreamingLambdaHandler {
+    /// The handler function -- implement the business logic of the Lambda function here.
+    /// - Parameters:
+    ///   - event: The invocation's input data.
+    ///   - responseWriter: A ``LambdaResponseStreamWriter`` to write the invocation's response to.
+    ///   If no response or error is written to `responseWriter` an error will be reported to the invoker.
+    ///   - context: The ``NewLambdaContext`` containing the invocation's metadata.
+    /// - Throws:
+    /// How the thrown error will be handled by the runtime:
+    ///   - An invocation error will be reported if the error is thrown before the first call to
+    ///     ``LambdaResponseStreamWriter/write(_:)``.
+    ///   - If the error is thrown after call(s) to ``LambdaResponseStreamWriter/write(_:)`` but before
+    ///     a call to ``LambdaResponseStreamWriter/finish()``, the response stream will be closed and trailing
+    ///     headers will be sent.
+    ///   - If ``LambdaResponseStreamWriter/finish()`` has already been called before the error is thrown, the
+    ///     error will be logged.
     mutating func handle(
         _ event: ByteBuffer,
         responseWriter: some LambdaResponseStreamWriter,
         context: NewLambdaContext
     ) async throws
 }
 
+/// A writer object to write the Lambda response stream into. The HTTP response is started lazily.
+/// before the first call to ``write(_:)`` or ``writeAndFinish(_:)``.
 package protocol LambdaResponseStreamWriter {
+    /// Write a response part into the stream. Bytes written are streamed continually.
+    /// - Parameter buffer: The buffer to write.
     mutating func write(_ buffer: ByteBuffer) async throws
+
+    /// End the response stream and the underlying HTTP response.
     func finish() async throws
+
+    /// Write a response part into the stream and then end the stream as well as the underlying HTTP response.
+    /// - Parameter buffer: The buffer to write.
     func writeAndFinish(_ buffer: ByteBuffer) async throws
-    func reportError(_ error: any Error) async throws
 }
 
+/// This handler protocol is intended to serve the most common use-cases.
+/// This protocol is completely agnostic to any encoding/decoding -- decoding the received event invocation into an ``Event`` object and encoding the returned ``Output`` object is handled by the library.
+/// The``handle(_:context:)`` function simply receives the generic ``Event`` object as input and returns the generic ``Output`` object.
+///
+/// - note: This handler protocol does not support response streaming because the output has to be encoded prior to it being sent, e.g. it is not possible to encode a partial/incomplete JSON string.
+/// This protocol also does not support the execution of background work after the response has been returned -- the ``LambdaWithBackgroundProcessingHandler`` protocol caters for such use-cases.
 package protocol NewLambdaHandler {
+    /// Generic input type.
+    /// The body of the request sent to Lambda will be decoded into this type for the handler to consume.
     associatedtype Event: Decodable
+    /// Generic output type.
+    /// This is the return type of the ``handle(_:context:)`` function.
     associatedtype Output
 
+    /// Implement the business logic of the Lambda function here.
+    /// - Parameters:
+    ///   - event: The generic ``Event`` object representing the invocation's input data.
+    ///   - context: The ``NewLambdaContext`` containing the invocation's metadata.
+    /// - Returns: A generic ``Output`` object representing the computed result.
     func handle(_ event: Event, context: NewLambdaContext) async throws -> Output
 }
 
+/// This protocol is exactly like ``NewLambdaHandler``, with the only difference being the added support for executing background
+/// work after the result has been sent to the AWS Lambda control plane.
+/// This is achieved by not having a return type in the `handle` function. The output is instead written into a
+/// ``LambdaResponseWriter``that is passed in as an argument, meaning that the ``handle(_:)`` function is then free to implement
+/// any background work after the result has been sent to the AWS Lambda control plane.
 package protocol LambdaWithBackgroundProcessingHandler {
+    /// Generic input type.
+    /// The body of the request sent to Lambda will be decoded into this type for the handler to consume.
     associatedtype Event: Decodable
+    /// Generic output type.
+    /// This is the type that the `handle` function will send through the ``LambdaResponseWriter``.
     associatedtype Output
 
-    /// The business logic of the Lambda function. Receives a generic input type and returns a generic output type.
-    /// Agnostic to JSON encoding/decoding
+    /// Implement the business logic of the Lambda function here.
+    /// - Parameters:
+    ///   - event: The generic ``Event`` object representing the invocation's input data.
+    ///   - outputWriter: The writer to send the computed response to. A call to `outputWriter.write(_:)` will return the response to the AWS Lambda response endpoint.
+    ///   Any background work can then be executed before returning.
+    ///   - context: The ``NewLambdaContext`` containing the invocation's metadata.
     func handle(
         _ event: Event,
         outputWriter: some LambdaResponseWriter<Output>,
         context: NewLambdaContext
     ) async throws
 }
 
+/// Used with ``LambdaWithBackgroundProcessingHandler``.
+/// A mechanism to "return" an output from ``LambdaWithBackgroundProcessingHandler/handle(_:outputWriter:context:)`` without the function needing to
+/// have a return type and exit at that point. This allows for background work to be executed _after_ a response has been sent to the AWS Lambda response endpoint.
 package protocol LambdaResponseWriter<Output>: ~Copyable {
     associatedtype Output
-    /// Sends the generic Output object (representing the computed result of the handler)
+    /// Sends the generic ``Output`` object (representing the computed result of the handler)
     /// to the AWS Lambda response endpoint.
     /// This function simply serves as a mechanism to return the computed result from a handler function
     /// without an explicit `return`.
     mutating func write(response: Output) async throws
 }
 
+/// A ``StreamingLambdaHandler`` conforming handler object that can be constructed with a closure.
+/// Allows for a handler to be defined in a clean manner, leveraging Swift's trailing closure syntax.
 package struct StreamingClosureHandler: StreamingLambdaHandler {
     let body: @Sendable (ByteBuffer, LambdaResponseStreamWriter, NewLambdaContext) async throws -> Void
 
+    /// Initialize an instance from a handler function in the form of a closure.
+    /// - Parameter body: The handler function written as a closure.
     package init(
         body: @Sendable @escaping (ByteBuffer, LambdaResponseStreamWriter, NewLambdaContext) async throws -> Void
     ) {
         self.body = body
     }
 
+    /// Calls the provided `self.body` closure with the ``ByteBuffer`` invocation event, the ``LambdaResponseStreamWriter``, and the ``NewLambdaContext``
+    /// - Parameters:
+    ///   - event: The invocation's input data.
+    ///   - responseWriter: A ``LambdaResponseStreamWriter`` to write the invocation's response to.
+    ///   If no response or error is written to `responseWriter` an error will be reported to the invoker.
+    ///   - context: The ``NewLambdaContext`` containing the invocation's metadata.
     package func handle(
         _ request: ByteBuffer,
         responseWriter: some LambdaResponseStreamWriter,
@@ -76,17 +146,27 @@ package struct StreamingClosureHandler: StreamingLambdaHandler {
     }
 }
 
+/// A ``NewLambdaHandler`` conforming handler object that can be constructed with a closure.
+/// Allows for a handler to be defined in a clean manner, leveraging Swift's trailing closure syntax.
 package struct ClosureHandler<Event: Decodable, Output>: NewLambdaHandler {
     let body: (Event, NewLambdaContext) async throws -> Output
 
+    /// Initialize with a closure handler over generic `Input` and `Output` types.
+    /// - Parameter body: The handler function written as a closure.
     package init(body: @escaping (Event, NewLambdaContext) async throws -> Output) where Output: Encodable {
         self.body = body
     }
 
+    /// Initialize with a closure handler over a generic `Input` type, and a `Void` `Output`.
+    /// - Parameter body: The handler function written as a closure.
     package init(body: @escaping (Event, NewLambdaContext) async throws -> Void) where Output == Void {
         self.body = body
     }
 
+    /// Calls the provided `self.body` closure with the generic ``Event`` object representing the incoming event, and the ``NewLambdaContext``
+    /// - Parameters:
+    ///   - event: The generic ``Event`` object representing the invocation's input data.
+    ///   - context: The ``NewLambdaContext`` containing the invocation's metadata.
     package func handle(_ event: Event, context: NewLambdaContext) async throws -> Output {
         try await self.body(event, context)
     }

Tests/AWSLambdaRuntimeCoreTests/LambdaMockClient.swift

@@ -17,7 +17,7 @@ import Foundation
 import Logging
 import NIOCore
 
-struct LambdaMockWriter: LambdaResponseStreamWriter {
+struct LambdaMockWriter: LambdaRuntimeClientResponseStreamWriter {
     var underlying: LambdaMockClient
 
     init(underlying: LambdaMockClient) {