feat: add API Gateway route testing and discovery

packages/api/src/adapter-aws/AwsApiGatewayAdapter.ts

@@ -5,7 +5,9 @@ import {
     DeleteRestApiCommand,
     GetRestApiCommand,
     GetRestApisCommand,
+    GetMethodCommand,
     GetResourcesCommand,
+    GetStagesCommand,
     PutIntegrationCommand,
     PutMethodCommand,
     type APIGatewayClient,
@@ -16,7 +18,7 @@ import {apiGateway as defaultApiGateway, defaultAccountId, lambda as defaultLamb
 import {awsApiGatewaySchema} from '../cloud-spi/apigatewaySchema'
 import {ValidationError} from '../cloud-spi/errors'
 import {awsEndpoint} from '../service/runtimeProbe'
-import type {ApiGatewayLambdaRouteInput, ApiGatewayLambdaRouteResult, CloudResource, CloudServiceAdapter, CreateResourceInput, ResourceQuery, ServiceSchema} from '../cloud-spi/types'
+import type {ApiGatewayLambdaRouteInput, ApiGatewayLambdaRouteResult, ApiGatewayRouteOverview, ApiGatewayRoutesResult, ApiGatewayTestRouteInput, ApiGatewayTestRouteResult, CloudResource, CloudServiceAdapter, CreateResourceInput, ResourceQuery, ServiceSchema} from '../cloud-spi/types'
 
 export class AwsApiGatewayAdapter implements CloudServiceAdapter {
     readonly cloud = 'aws' as const
@@ -132,6 +134,77 @@ export class AwsApiGatewayAdapter implements CloudServiceAdapter {
         }
     }
 
+    async testApiGatewayRoute(apiId: string, input: ApiGatewayTestRouteInput): Promise<ApiGatewayTestRouteResult> {
+        const path = testRoutePath(input.path)
+        const method = input.method.toUpperCase()
+        const stage = stageName(input.stage)
+        if (!['GET', 'POST', 'PUT', 'DELETE'].includes(method)) {
+            throw new ValidationError('method must be GET, POST, PUT, or DELETE')
+        }
+
+        const encodedPath = path.split('/').map(encodeURIComponent).join('/')
+        const url = new URL(`${awsEndpoint().replace(/\/$/, '')}/execute-api/${encodeURIComponent(apiId)}/${encodeURIComponent(stage)}${encodedPath}`)
+        url.search = queryString(input.query)
+        const headers = new Headers(input.headers)
+        if (input.body && !headers.has('content-type')) headers.set('content-type', 'application/json')
+
+        const startedAt = performance.now()
+        const response = await globalThis.fetch(url, {
+            method,
+            headers,
+            body: ['GET', 'HEAD', 'OPTIONS'].includes(method) ? undefined : input.body || undefined,
+        })
+        return {
+            statusCode: response.status,
+            headers: Object.fromEntries(response.headers.entries()),
+            body: await response.text(),
+            durationMs: Math.round(performance.now() - startedAt),
+        }
+    }
+
+    async listApiGatewayRoutes(apiId: string): Promise<ApiGatewayRoutesResult> {
+        const resources = []
+        let position: string | undefined
+        do {
+            const result = await this.apiGateway.send(new GetResourcesCommand({restApiId: apiId, position, embed: ['methods']}))
+            resources.push(...(result.items ?? []))
+            position = result.position
+        } while (position)
+
+        const routes: ApiGatewayRouteOverview[] = []
+        for (const resource of resources) {
+            const methods = resource.resourceMethods
+                ? Object.keys(resource.resourceMethods).sort()
+                : ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT']
+            for (const method of methods) {
+                if (!resource.id || !resource.path) continue
+                let result
+                try {
+                    result = await this.apiGateway.send(new GetMethodCommand({
+                        restApiId: apiId,
+                        resourceId: resource.id,
+                        httpMethod: method,
+                    }))
+                } catch (error) {
+                    if (hasHttpStatus(error, 404)) continue
+                    throw error
+                }
+                routes.push({
+                    resourceId: resource.id,
+                    path: resource.path,
+                    method,
+                    functionName: lambdaFunctionName(result.methodIntegration?.uri),
+                })
+            }
+        }
+
+        const stages = await this.apiGateway.send(new GetStagesCommand({restApiId: apiId}))
+        return {
+            routes: routes.sort((left, right) => left.path.localeCompare(right.path) || left.method.localeCompare(right.method)),
+            stages: (stages.item ?? []).map((stage) => stage.stageName).filter((stage): stage is string => Boolean(stage)).sort(),
+        }
+    }
+
     private async rootResource(apiId: string) {
         let position: string | undefined
         do {
@@ -160,6 +233,25 @@ function stageName(stage: string): string {
     return value
 }
 
+function queryString(query: string): string {
+    const value = stringValue(query)
+    if (value.length > 8_192) throw new ValidationError('query must be at most 8192 characters')
+    return value.replace(/^\?/, '')
+}
+
+function testRoutePath(path: string): string {
+    const value = stringValue(path)
+    if (!/^\/(?:[A-Za-z0-9._~{}-]+\/)*[A-Za-z0-9._~{}-]+$/.test(value)) {
+        throw new ValidationError('path must be an API Gateway route path, for example /orders or /users/{id}')
+    }
+    return value
+}
+
+function lambdaFunctionName(uri?: string): string | null {
+    const match = uri?.match(/\/functions\/arn:aws:lambda:[^:]+:\d+:function:([^/:]+)/)
+    return match?.[1] ?? null
+}
+
 function toResource(api: RestApi): CloudResource {
     const id = api.id ?? ''
     return {