The best way to control Claude Code, Codex and more from any computer or phone

main
ts 123 lines 4 KB
Raw
1 import type * as lambda from "aws-lambda";
2 import * as Context from "effect/Context";
3 import type * as Effect from "effect/Effect";
4 import type { Api } from "./Api.ts";
5
6 /**
7 * The event shape a WebSocket route handler receives — the API Gateway v2
8 * WebSocket proxy event (`requestContext.connectionId`, `routeKey`,
9 * `eventType`, plus `body` for `MESSAGE` events).
10 */
11 export type WebSocketEvent = lambda.APIGatewayProxyWebsocketEventV2;
12
13 /**
14 * The result a WebSocket route handler may return. For `$connect` routes a
15 * non-2xx `statusCode` rejects the connection; for other routes the result
16 * is only surfaced to the client when the route has a route response
17 * configured. Returning `void` means `{ statusCode: 200 }`.
18 */
19 export type WebSocketResult = { statusCode: number; body?: string } | undefined | void;
20
21 export interface WebSocketRouteProps {
22 /**
23 * The WebSocket route key this handler serves: `$connect`,
24 * `$disconnect`, `$default`, or a custom action name matched by the
25 * API's route selection expression.
26 */
27 routeKey: string;
28 }
29
30 export type WebSocketEventSourceService = <Req = never>(
31 api: Api,
32 props: WebSocketRouteProps,
33 handler: (event: WebSocketEvent) => Effect.Effect<WebSocketResult, never, Req>,
34 ) => Effect.Effect<void, never, never>;
35
36 /**
37 * Event source connecting a WebSocket {@link Api} route to the hosting
38 * Lambda function.
39 *
40 * At deploy time the Lambda implementation (`Lambda.WebSocketEventSource`)
41 * materializes the `Integration`, `Route`, and invoke `Permission` for the
42 * route; at runtime it dispatches matching WebSocket proxy events to the
43 * handler. Subscribe routes with {@link onWebSocketRoute} and provide
44 * `Lambda.WebSocketEventSource` on the hosting function.
45 *
46 * ### Handling WebSocket Routes
47 * **Example:** Echo server on a WEBSOCKET Api
48 * ```typescript
49 * export default MyFunction.make(
50 * { main: import.meta.url },
51 * Effect.gen(function* () {
52 * const api = yield* ApiGatewayV2.Api("WsApi", {
53 * protocolType: "WEBSOCKET",
54 * routeSelectionExpression: "$request.body.action",
55 * });
56 * const stage = yield* ApiGatewayV2.Stage("WsStage", {
57 * api,
58 * stageName: "prod",
59 * autoDeploy: true,
60 * });
61 * const connections = yield* ApiGatewayV2.ManageConnections(stage);
62 *
63 * yield* ApiGatewayV2.onWebSocketRoute(api, { routeKey: "$connect" }, () =>
64 * Effect.succeed({ statusCode: 200 }),
65 * );
66 *
67 * yield* ApiGatewayV2.onWebSocketRoute(api, { routeKey: "$default" }, (event) =>
68 * connections
69 * .postToConnection({
70 * ConnectionId: event.requestContext.connectionId,
71 * Data: `echo:${event.body ?? ""}`,
72 * })
73 * .pipe(
74 * Effect.asVoid,
75 * Effect.catchTag("GoneException", () => Effect.void),
76 * Effect.orDie,
77 * ),
78 * );
79 *
80 * return {};
81 * }).pipe(
82 * Effect.provide(
83 * Layer.mergeAll(
84 * Lambda.WebSocketEventSource,
85 * ApiGatewayV2.ManageConnectionsHttp,
86 * ),
87 * ),
88 * ),
89 * );
90 * ```
91 *
92 * @binding
93 */
94 export class WebSocketEventSource extends Context.Service<
95 WebSocketEventSource,
96 WebSocketEventSourceService
97 >()("AWS.ApiGatewayV2.WebSocketEventSource") {}
98
99 /**
100 * Subscribe an Effect handler to a WebSocket route of an API Gateway v2
101 * WEBSOCKET {@link Api}.
102 *
103 * Provide `Lambda.WebSocketEventSource` on the hosting function to
104 * satisfy the requirement.
105 *
106 * @param api The WebSocket API.
107 * @param props The route key to serve.
108 * @param handler Invoked once per WebSocket event for the route.
109 *
110 * @example
111 * ```typescript
112 * yield* ApiGatewayV2.onWebSocketRoute(api, { routeKey: "$connect" }, () =>
113 * Effect.succeed({ statusCode: 200 }),
114 * );
115 * ```
116 */
117 export function onWebSocketRoute<Req = never>(
118 api: Api,
119 props: WebSocketRouteProps,
120 handler: (event: WebSocketEvent) => Effect.Effect<WebSocketResult, never, Req>,
121 ): Effect.Effect<void, never, WebSocketEventSource> {
122 return WebSocketEventSource.use((source) => source(api, props, handler));
123 }