feat(sdk): handler conversion utilities (#6335)

Resolves #6334

Introduce a bunch of static utility methods for converting handler types across the SDK.

This can be used to e.g. create custom implementations of the various APIs.

## Checklist

- [x] Title matches [Winglang's style guide](https://www.winglang.io/contributing/start-here/pull_requests#how-are-pull-request-titles-formatted)
- [x] Description explains motivation and solution
- [x] Tests added (always)
- [x] Docs updated (only required for features)
- [x] Added `pr/e2e-full` label if this feature requires end-to-end testing

*By submitting this pull request, I confirm that my contribution is made under the terms of the [Wing Cloud Contribution License](https://github.com/winglang/wing/blob/main/CONTRIBUTION_LICENSE.md)*.

docs/docs/04-standard-library/aws/api-reference.md

@@ -933,6 +933,60 @@ The cloud.Api.
 
 
 
+### ApiEndpointHandler <a name="ApiEndpointHandler" id="@winglang/sdk.aws.ApiEndpointHandler"></a>
+
+A helper class for working with AWS api endpoint handlers.
+
+#### Initializers <a name="Initializers" id="@winglang/sdk.aws.ApiEndpointHandler.Initializer"></a>
+
+```wing
+bring aws;
+
+new aws.ApiEndpointHandler();
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+
+---
+
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@winglang/sdk.aws.ApiEndpointHandler.toFunctionHandler">toFunctionHandler</a></code> | Returns a `cloud.Function` handler for handling requests from a `cloud.Api`. |
+
+---
+
+##### `toFunctionHandler` <a name="toFunctionHandler" id="@winglang/sdk.aws.ApiEndpointHandler.toFunctionHandler"></a>
+
+```wing
+bring aws;
+
+aws.ApiEndpointHandler.toFunctionHandler(handler: IApiEndpointHandler, corsOptions?: ApiCorsOptions);
+```
+
+Returns a `cloud.Function` handler for handling requests from a `cloud.Api`.
+
+###### `handler`<sup>Required</sup> <a name="handler" id="@winglang/sdk.aws.ApiEndpointHandler.toFunctionHandler.parameter.handler"></a>
+
+- *Type:* <a href="#@winglang/sdk.cloud.IApiEndpointHandler">IApiEndpointHandler</a>
+
+The `onRequest` handler.
+
+---
+
+###### `corsOptions`<sup>Optional</sup> <a name="corsOptions" id="@winglang/sdk.aws.ApiEndpointHandler.toFunctionHandler.parameter.corsOptions"></a>
+
+- *Type:* <a href="#@winglang/sdk.cloud.ApiCorsOptions">ApiCorsOptions</a>
+
+The CORS options.
+
+---
+
+
+
 ### Bucket <a name="Bucket" id="@winglang/sdk.aws.Bucket"></a>
 
 A helper class for working with AWS buckets.
@@ -979,6 +1033,60 @@ The cloud.Bucket.
 
 
 
+### BucketEventHandler <a name="BucketEventHandler" id="@winglang/sdk.aws.BucketEventHandler"></a>
+
+Utility class to work with bucket event handlers.
+
+#### Initializers <a name="Initializers" id="@winglang/sdk.aws.BucketEventHandler.Initializer"></a>
+
+```wing
+bring aws;
+
+new aws.BucketEventHandler();
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+
+---
+
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@winglang/sdk.aws.BucketEventHandler.toTopicOnMessageHandler">toTopicOnMessageHandler</a></code> | Converts a `cloud.IBucketEventHandler` to a `cloud.ITopicOnMessageHandler`. |
+
+---
+
+##### `toTopicOnMessageHandler` <a name="toTopicOnMessageHandler" id="@winglang/sdk.aws.BucketEventHandler.toTopicOnMessageHandler"></a>
+
+```wing
+bring aws;
+
+aws.BucketEventHandler.toTopicOnMessageHandler(handler: IBucketEventHandler, eventType: BucketEventType);
+```
+
+Converts a `cloud.IBucketEventHandler` to a `cloud.ITopicOnMessageHandler`.
+
+###### `handler`<sup>Required</sup> <a name="handler" id="@winglang/sdk.aws.BucketEventHandler.toTopicOnMessageHandler.parameter.handler"></a>
+
+- *Type:* <a href="#@winglang/sdk.cloud.IBucketEventHandler">IBucketEventHandler</a>
+
+the handler to convert.
+
+---
+
+###### `eventType`<sup>Required</sup> <a name="eventType" id="@winglang/sdk.aws.BucketEventHandler.toTopicOnMessageHandler.parameter.eventType"></a>
+
+- *Type:* <a href="#@winglang/sdk.cloud.BucketEventType">BucketEventType</a>
+
+the event type.
+
+---
+
+
+
 ### Counter <a name="Counter" id="@winglang/sdk.aws.Counter"></a>
 
 A helper class for working with AWS Counters.
@@ -1117,6 +1225,52 @@ The cloud.Queue.
 
 
 
+### QueueSetConsumerHandler <a name="QueueSetConsumerHandler" id="@winglang/sdk.aws.QueueSetConsumerHandler"></a>
+
+Utility class for working with the queue consumer handler.
+
+#### Initializers <a name="Initializers" id="@winglang/sdk.aws.QueueSetConsumerHandler.Initializer"></a>
+
+```wing
+bring aws;
+
+new aws.QueueSetConsumerHandler();
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+
+---
+
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@winglang/sdk.aws.QueueSetConsumerHandler.toFunctionHandler">toFunctionHandler</a></code> | Converts a queue consumer handler to a function handler. |
+
+---
+
+##### `toFunctionHandler` <a name="toFunctionHandler" id="@winglang/sdk.aws.QueueSetConsumerHandler.toFunctionHandler"></a>
+
+```wing
+bring aws;
+
+aws.QueueSetConsumerHandler.toFunctionHandler(handler: IQueueSetConsumerHandler);
+```
+
+Converts a queue consumer handler to a function handler.
+
+###### `handler`<sup>Required</sup> <a name="handler" id="@winglang/sdk.aws.QueueSetConsumerHandler.toFunctionHandler.parameter.handler"></a>
+
+- *Type:* <a href="#@winglang/sdk.cloud.IQueueSetConsumerHandler">IQueueSetConsumerHandler</a>
+
+The queue consumer handler.
+
+---
+
+
+
 ### Table <a name="Table" id="@winglang/sdk.aws.Table"></a>
 
 A helper class for working with AWS tables.
@@ -1209,6 +1363,52 @@ The cloud.Topic.
 
 
 
+### TopicOnMessageHandler <a name="TopicOnMessageHandler" id="@winglang/sdk.aws.TopicOnMessageHandler"></a>
+
+A helper class for working with AWS topic on message handlers.
+
+#### Initializers <a name="Initializers" id="@winglang/sdk.aws.TopicOnMessageHandler.Initializer"></a>
+
+```wing
+bring aws;
+
+new aws.TopicOnMessageHandler();
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+
+---
+
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@winglang/sdk.aws.TopicOnMessageHandler.toFunctionHandler">toFunctionHandler</a></code> | Returns a `cloud.Function` handler for handling messages from a `cloud.Topic`. |
+
+---
+
+##### `toFunctionHandler` <a name="toFunctionHandler" id="@winglang/sdk.aws.TopicOnMessageHandler.toFunctionHandler"></a>
+
+```wing
+bring aws;
+
+aws.TopicOnMessageHandler.toFunctionHandler(handler: ITopicOnMessageHandler);
+```
+
+Returns a `cloud.Function` handler for handling messages from a `cloud.Topic`.
+
+###### `handler`<sup>Required</sup> <a name="handler" id="@winglang/sdk.aws.TopicOnMessageHandler.toFunctionHandler.parameter.handler"></a>
+
+- *Type:* <a href="#@winglang/sdk.cloud.ITopicOnMessageHandler">ITopicOnMessageHandler</a>
+
+The `onMessage` handler.
+
+---
+
+
+
 ### Website <a name="Website" id="@winglang/sdk.aws.Website"></a>
 
 A helper class for working with AWS buckets.

docs/docs/04-standard-library/cloud/api.md

@@ -421,6 +421,8 @@ Options for the route.
 | **Name** | **Description** |
 | --- | --- |
 | <code><a href="#@winglang/sdk.cloud.Api.onLiftType">onLiftType</a></code> | A hook called by the Wing compiler once for each inflight host that needs to use this type inflight. |
+| <code><a href="#@winglang/sdk.cloud.Api.renderCorsHeaders">renderCorsHeaders</a></code> | Generates an object containing default CORS response headers and OPTIONS response headers. |
+| <code><a href="#@winglang/sdk.cloud.Api.renderOpenApiPath">renderOpenApiPath</a></code> | Converts input path to a valid OpenAPI path (replaces `:` based path params with `{}`). |
 
 ---
 
@@ -452,6 +454,42 @@ other capabilities to the inflight host.
 
 ---
 
+##### `renderCorsHeaders` <a name="renderCorsHeaders" id="@winglang/sdk.cloud.Api.renderCorsHeaders"></a>
+
+```wing
+bring cloud;
+
+cloud.Api.renderCorsHeaders(corsOptions?: ApiCorsOptions);
+```
+
+Generates an object containing default CORS response headers and OPTIONS response headers.
+
+###### `corsOptions`<sup>Optional</sup> <a name="corsOptions" id="@winglang/sdk.cloud.Api.renderCorsHeaders.parameter.corsOptions"></a>
+
+- *Type:* <a href="#@winglang/sdk.cloud.ApiCorsOptions">ApiCorsOptions</a>
+
+The CORS options to generate the headers from.
+
+---
+
+##### `renderOpenApiPath` <a name="renderOpenApiPath" id="@winglang/sdk.cloud.Api.renderOpenApiPath"></a>
+
+```wing
+bring cloud;
+
+cloud.Api.renderOpenApiPath(path: str);
+```
+
+Converts input path to a valid OpenAPI path (replaces `:` based path params with `{}`).
+
+###### `path`<sup>Required</sup> <a name="path" id="@winglang/sdk.cloud.Api.renderOpenApiPath.parameter.path"></a>
+
+- *Type:* str
+
+The path to convert (assumes path is valid).
+
+---
+
 #### Properties <a name="Properties" id="Properties"></a>
 
 | **Name** | **Type** | **Description** |

libs/awscdk/src/api.ts

@@ -1,5 +1,4 @@
 import { createHash } from "crypto";
-import { join } from "path";
 import { Lazy } from "aws-cdk-lib";
 import {
   ApiDefinition,
@@ -11,8 +10,7 @@ import { CfnPermission } from "aws-cdk-lib/aws-lambda";
 import { Construct } from "constructs";
 import { App } from "./app";
 import { cloud, core, std } from "@winglang/sdk";
-import { convertBetweenHandlers } from "@winglang/sdk/lib/shared/convert";
-import { IAwsApi, STAGE_NAME } from "@winglang/sdk/lib/shared-aws/api";
+import { ApiEndpointHandler, IAwsApi, STAGE_NAME } from "@winglang/sdk/lib/shared-aws/api";
 import { API_DEFAULT_RESPONSE } from "@winglang/sdk/lib/shared-aws/api.default";
 import { isAwsCdkFunction } from "./function";
 
@@ -204,15 +202,7 @@ export class Api extends cloud.Api implements IAwsApi {
   ): cloud.Function {
     let handler = this.handlers[inflight._id];
     if (!handler) {
-      const newInflight = convertBetweenHandlers(
-        inflight,
-        join(__dirname, "api.onrequest.inflight.js"),
-        "ApiOnRequestHandlerClient",
-        {
-          corsHeaders: this._generateCorsHeaders(this.corsOptions)
-            ?.defaultResponse,
-        }
-      );
+      const newInflight = ApiEndpointHandler.toFunctionHandler(inflight, Api.renderCorsHeaders(this.corsOptions));
       const prefix = `${method.toLowerCase()}${path.replace(/\//g, "_")}_}`;
       handler = new cloud.Function(
         this,
@@ -385,7 +375,7 @@ class WingRestApi extends Construct {
       action: "lambda:InvokeFunction",
       functionName: handler.awscdkFunction.functionName,
       principal: "apigateway.amazonaws.com",
-      sourceArn: this.api.arnForExecuteApi(method, Api._toOpenApiPath(path)),
+      sourceArn: this.api.arnForExecuteApi(method, Api.renderOpenApiPath(path)),
     });
   };
 }

libs/awscdk/src/queue.ts

@@ -1,13 +1,11 @@
-import { join } from "path";
 import { Duration } from "aws-cdk-lib";
 import { SqsEventSource } from "aws-cdk-lib/aws-lambda-event-sources";
 import { Queue as SQSQueue } from "aws-cdk-lib/aws-sqs";
 import { Construct } from "constructs";
 import { App } from "./app";
 import { std, core, cloud } from "@winglang/sdk";
-import { convertBetweenHandlers } from "@winglang/sdk/lib/shared/convert";
 import { calculateQueuePermissions } from "@winglang/sdk/lib/shared-aws/permissions";
-import { IAwsQueue, Queue as AwsQueue } from "@winglang/sdk/lib/shared-aws/queue";
+import { IAwsQueue, Queue as AwsQueue, QueueSetConsumerHandler } from "@winglang/sdk/lib/shared-aws/queue";
 import { addPolicyStatements, isAwsCdkFunction } from "./function";
 
 /**
@@ -50,14 +48,7 @@ export class Queue extends cloud.Queue implements IAwsQueue {
     inflight: cloud.IQueueSetConsumerHandler,
     props: cloud.QueueSetConsumerOptions = {}
   ): cloud.Function {
-    const functionHandler = convertBetweenHandlers(
-      inflight,
-      join(
-        __dirname,
-        "queue.setconsumer.inflight.js"
-      ),
-      "QueueSetConsumerHandlerClient"
-    );
+    const functionHandler = QueueSetConsumerHandler.toFunctionHandler(inflight);
 
     const fn = new cloud.Function(
       // ok since we're not a tree root

libs/awscdk/src/schedule.ts

@@ -1,4 +1,3 @@
-import { join } from "path";
 import { Duration } from "aws-cdk-lib";
 import { Rule, Schedule as EventSchedule } from "aws-cdk-lib/aws-events";
 import {
@@ -8,8 +7,7 @@ import {
 import { Construct } from "constructs";
 import { App } from "./app";
 import { cloud, core, std } from "@winglang/sdk";
-import { convertBetweenHandlers } from "@winglang/sdk/lib/shared/convert";
-import { convertUnixCronToAWSCron } from "@winglang/sdk/lib/shared-aws/schedule";
+import { ScheduleOnTickHandler, convertUnixCronToAWSCron } from "@winglang/sdk/lib/shared-aws/schedule";
 import { isAwsCdkFunction } from "./function";
 
 
@@ -54,14 +52,7 @@ export class Schedule extends cloud.Schedule {
     inflight: cloud.IScheduleOnTickHandler,
     props?: cloud.ScheduleOnTickOptions | undefined
   ): cloud.Function {
-    const functionHandler = convertBetweenHandlers(
-      inflight,
-      join(
-        __dirname,
-        "schedule.ontick.inflight.js"
-      ),
-      "ScheduleOnTickHandlerClient"
-    );
+    const functionHandler = ScheduleOnTickHandler.toFunctionHandler(inflight);
 
     const fn = new cloud.Function(
       // ok since we're not a tree root