Add article and fix default config

Author: Andrea Scuderi

Sources/BreezeDemoHTTPApplication/BreezeDemoHTTPApplication.swift

@@ -18,7 +18,6 @@ import AWSLambdaRuntime
 import AsyncHTTPClient
 import Logging
 import NIOCore
-import ServiceLifecycle
 
 /// This is a simple example of a Breeze Lambda WebHook handler.
 /// It uses the BreezeHTTPClientService to make an HTTP request to example.com
@@ -57,18 +56,8 @@ struct DemoLambdaHandler: BreezeLambdaWebHookHandler, Sendable {
 @main
 struct BreezeDemoHTTPApplication {
 
-    static let applicationName = "BreezeDemoHTTPApplication"
-    static let logger = Logger(label: "BreezeDemoHTTPApplication")
-    
     static func main() async throws {
-        let config = BreezeHTTPClientConfig(
-            timeout: .seconds(30),
-            logger: logger
-        )
-        let app = BreezeLambdaWebHook<DemoLambdaHandler>(
-            name: applicationName,
-            config: config,
-        )
-        try await app.run()
+        let lambda = BreezeLambdaWebHook<DemoLambdaHandler>(name: "DemoLambdaHandler")
+        try await lambda.run()
     }
 }

Sources/BreezeLambdaWebHook/BreezeHTTPClientConfig.swift

@@ -23,7 +23,10 @@ public enum BreezeClientServiceError: Error {
 
 /// Configuration for the Breeze HTTP Client
 public struct BreezeHTTPClientConfig: Sendable {
-    public init(timeout: TimeAmount, logger: Logger) {
+    public init(
+        timeout: TimeAmount = .seconds(30),
+        logger: Logger = Logger(label: "BreezeLambdaWebHookLogger")
+    ) {
         self.timeout = timeout
         self.logger = logger
     }

Sources/BreezeLambdaWebHook/BreezeLambdaWebHook.swift

@@ -30,9 +30,20 @@ public struct BreezeLambdaWebHook<LambdaHandler: BreezeLambdaWebHookHandler>: Se
     /// - Parameters:
     ///  - name: The name of the service.
     ///  - config: Configuration for the Breeze HTTP Client.
-    public init(name: String, config: BreezeHTTPClientConfig) {
+    ///
+    ///  This initializer sets up the Breeze Lambda WebHook service with a specified name and configuration.
+    ///
+    /// - Note: If no configuration is provided, a default configuration with a 30-second timeout and a logger will be used.
+    public init(
+        name: String,
+        config: BreezeHTTPClientConfig? = nil
+    ) {
         self.name = name
-        self.config = config
+        let defaultConfig = BreezeHTTPClientConfig(
+            timeout: .seconds(30),
+            logger: Logger(label: "\(name)")
+        )
+        self.config = config ?? defaultConfig
     }
 
     /// Runs the Breeze Lambda WebHook service.

Sources/BreezeLambdaWebHook/Docs.docc/Docs.md

@@ -0,0 +1,155 @@
+# ``BreezeLambdaWebHook``
+
+@Metadata { 
+   @PageImage(purpose: icon, source: "wind")
+}
+
+## Overview
+
+BreezeLambdaWebHook is a Swift framework that simplifies the development of serverless webhook handlers for AWS Lambda.
+
+It provides a clean, type-safe interface for processing HTTP requests from API Gateway and returning appropriate responses.
+
+It allows you to define a handler that processes incoming webhook requests and returns appropriate responses using `AsyncHTTPClient` framework.
+
+![BreezeLambdaWebHook Diagram](webhook)
+
+## Key Features
+
+- Serverless Architecture - Built specifically for AWS Lambda with API Gateway integration
+- Webhook Handling: Processes incoming requests and returns responses
+- Swift Concurrency: Fully compatible with Swift's async/await model
+- Type Safety: Leverages Swift's type system with Codable support
+- It supports both GET and POST requests
+- Minimal Configuration - Focus on business logic rather than infrastructure plumbing
+
+## How it works
+
+The framework handles the underlying AWS Lambda event processing, allowing you to focus on implementing your webhook logic. When a request arrives through API Gateway:
+
+1. The Lambda function receives the API Gateway event
+2. BreezeLambdaWebHook deserializes the event into a Swift type
+3. The handler processes the request, performing any necessary business logic
+4. The handler returns a response, which is serialized back to the API Gateway format
+
+## Getting Started
+ 
+To create a webhook handler, implement the BreezeLambdaWebHookHandler protocol:
+
+```swift
+class MyWebhook: BreezeLambdaWebHookHandler {
+    let handlerContext: HandlerContext
+    
+    required init(handlerContext: HandlerContext) {
+        self.handlerContext = handlerContext
+    }
+    
+    func handle(context: LambdaContext, event: APIGatewayV2Request) async -> APIGatewayV2Response {
+        // Your webhook logic here
+        return APIGatewayV2Response(with: "Success", statusCode: .ok)
+    }
+}
+```
+
+Then, implement the `main.swift` file to run the Lambda function:
+```swift
+import BreezeLambdaWebHook
+import AWSLambdaEvents
+import AWSLambdaRuntime
+import AsyncHTTPClient
+import Logging
+import NIOCore
+
+@main
+struct BreezeDemoHTTPApplication {
+    static func main() async throws {
+        let app = BreezeLambdaWebHook<DemoLambdaHandler>(name: "BreezeDemoHTTPApplication")
+        try await app.run()
+    }
+}
+```
+
+## Example WebHook Handlers
+
+### GET WebHook example:
+
+If the parameter `github-user` is present in the query string, the value is extracted and used to get the content from GitHub, the content is returned to the response payload.
+
+```swift
+class GetWebHook: BreezeLambdaWebHookHandler {
+    
+    let handlerContext: HandlerContext
+    
+    required init(handlerContext: HandlerContext) {
+        self.handlerContext = handlerContext
+    }
+    
+    func handle(context: AWSLambdaRuntimeCore.LambdaContext, event: AWSLambdaEvents.APIGatewayV2Request) async -> AWSLambdaEvents.APIGatewayV2Response {
+        do {
+            context.logger.info("event: \(event)")
+            guard let params = event.queryStringParameters else {
+                throw BreezeLambdaWebHookError.invalidRequest
+            }
+            if let user = params["github-user"] {
+                let url = "https://github.com/\(user)"
+                let request = HTTPClientRequest(url: url)
+                let response = try await httpClient.execute(request, timeout: .seconds(3))
+                let bytes = try await response.body.collect(upTo: 1024 * 1024) // 1 MB Buffer
+                let body = String(buffer: bytes)
+                return APIGatewayV2Response(with: body, statusCode: .ok)
+            } else {
+                return APIGatewayV2Response(with: params, statusCode: .ok)
+            }
+        } catch {
+            return APIGatewayV2Response(with: error, statusCode: .badRequest)
+        }
+    }
+}
+```
+
+### PostWebHook example:
+
+If the parameter `github-user` is present in the JSON payload, the value is extracted and used to get the content from GitHub, the content is returned to the response payload.
+
+```swift
+struct PostWebHookRequest: Codable {
+    let githubUser: String
+    
+    enum CodingKeys: String, CodingKey {
+        case githubUser = "github-user"
+    }
+}
+
+class PostWebHook: BreezeLambdaWebHookHandler {
+    
+    let handlerContext: HandlerContext
+    
+    required init(handlerContext: HandlerContext) {
+        self.handlerContext = handlerContext
+    }
+    
+    func handle(context: AWSLambdaRuntimeCore.LambdaContext, event: AWSLambdaEvents.APIGatewayV2Request) async -> AWSLambdaEvents.APIGatewayV2Response {
+        do {
+            context.logger.info("event: \(event)")
+            let incomingRequest: PostWebHookRequest = try event.bodyObject()
+            let url = "https://github.com/\(incomingRequest.githubUser)"
+            let request = HTTPClientRequest(url: url)
+            let response = try await httpClient.execute(request, timeout: .seconds(3))
+            let bytes = try await response.body.collect(upTo: 1024 * 1024) // 1 MB Buffer
+            let body = String(buffer: bytes)
+            return APIGatewayV2Response(with: body, statusCode: .ok)
+        } catch {
+            return APIGatewayV2Response(with: error, statusCode: .badRequest)
+        }
+    }
+}
+```
+
+## Deployment
+
+Deploy your Lambda function using AWS CDK, SAM, Serverless or Terraform. The Lambda requires:
+
+- API Gateway integration for HTTP requests
+
+For step-by-step deployment instructions and templates, see the [Breeze project repository](https://github.com/swift-serverless/Breeze) for more info on how to deploy it on AWS.
+