wirejs-deploy-amplify-basic 0.0.91 → 0.0.93-realtime

package/amplify-backend-assets/backend.ts

@@ -5,11 +5,12 @@ import { RemovalPolicy } from "aws-cdk-lib";
 import { FunctionUrlAuthType } from 'aws-cdk-lib/aws-lambda';
 import { Bucket, BlockPublicAccess } from 'aws-cdk-lib/aws-s3';
 import { Table, AttributeType, BillingMode } from 'aws-cdk-lib/aws-dynamodb';
+import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
+import { TableDefinition, Resource, indexName } from 'wirejs-resources';
+import { TableIndexes } from './constructs/table-indexes';
+import { RealtimeService } from './constructs/realtime-service';
 import { api } from './functions/api/resource';
 import { auth } from './auth/resource';
-import { TableDefinition, indexName } from 'wirejs-resources';
-import { TableIndexes } from './constructs/table-indexes';
-import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
 
 // @ts-ignore
 import generatedResources from './generated-resources';
@@ -128,6 +129,29 @@ for (const resource of generated) {
   }
 }
 
+function isRealtimeService(resource: any): resource is {
+  type: 'RealtimeService';
+  options: Resource;
+} {
+  return resource.type === 'RealtimeService';
+}
+
+if (generated.some(isRealtimeService)) {
+  const realtime = new RealtimeService(backend.stack, 'realtime', {
+    appId: APP_ID!,
+    branchId: BRANCH_ID,
+    publisher: backend.api,
+    namespaces: generated
+      .filter(isRealtimeService)
+      .map(r => r.options.absoluteId),
+  });
+  // TODO: is there a better way to ensure we grant access specifically
+  // to what `Secret` uses to store its creds without creating N places to
+  // map this?
+  // Longer term: Secrets will be stored either in DDB, parameter store, something
+  // else that is more appropriate than S3.
+  bucket.grantRead(realtime.authHandler);
+}
 
 /**
  * Lambda environment vars

package/amplify-backend-assets/constructs/realtime-service/authorizer-lambda.ts

@@ -0,0 +1,76 @@
+import * as jose from 'jose';
+import { Secret } from 'wirejs-resources';
+
+type Operation = "EVENT_CONNECT" | "EVENT_SUBSCRIBE" | "EVENT_PUBLISH";
+
+type AuthorizationRequest = {
+	authorizationToken: string,
+	requestContext: {
+		apiId: string,
+		accountId: string,
+		requestId: string,
+		operation: Operation,
+		channelNamespaceName: string,
+		channel: string
+	},
+	requestHeaders: Record<string, string>
+};
+
+type AuthorizationResult = {
+	isAuthorized: boolean;
+	handlerContext?: Record<string, string>; // unused by wirejs
+	ttlOverride?: number;
+};
+
+let secrets: Record<string, Promise<string> | undefined> = {};
+async function getSecret(ns: string): Promise<any> {
+	if (!secrets[ns]) {
+		secrets[ns] = new Promise(async (resolve, reject) => {
+			try {
+				const secret = new Secret(ns, process.env.SECRET_ID!)
+				resolve(await secret.read());
+			} catch (error) {
+				console.error('Error reading secret:', error);
+				reject(error);
+			}
+		});
+	}
+	return secrets[ns];
+}
+
+export const handler = async (event: AuthorizationRequest): Promise<AuthorizationResult> => {
+	/**
+	 * Intended authorization rules:
+	 * 
+	 * 1. Must be connect or subscribe operation
+	 * 2. Must be a valid JWT token
+	 * 3. Must be signed with the correct secret
+	 * 4. Must be for the correct channel
+	 */
+	try {
+		const token = event.authorizationToken;
+		if (!token) {
+			throw new Error('Authorization token is missing');
+		}
+		const decoded = await jose.jwtVerify(
+			token,
+			await getSecret(event.requestContext.channelNamespaceName)
+		);
+		if (decoded.payload.channel !== event.requestContext.channel) {
+			throw new Error('Channel mismatch');
+		}
+		if (!['EVENT_CONNECT', 'EVENT_SUBSCRIBE'].includes(event.requestContext.operation)) {
+			throw new Error('Operation mismatch');
+		}
+
+		// Default TTL from AppSync is 5 minutes according to construct docstring.
+		return {
+			isAuthorized: true,
+		}
+	} catch (error) {
+		console.error('Authorization error:', error);
+		return {
+			isAuthorized: false,
+		}
+	}
+};

package/amplify-backend-assets/constructs/realtime-service/index.ts

@@ -0,0 +1,80 @@
+import { Duration } from 'aws-cdk-lib';
+import * as path from 'path';
+import { IFunction, Runtime } from 'aws-cdk-lib/aws-lambda';
+import { Construct } from 'constructs';
+import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
+import {
+	AppSyncAuthProvider,
+	AppSyncAuthorizationType,
+	EventApi
+} from 'aws-cdk-lib/aws-appsync';
+
+const __filename = import.meta.url.replace(/^file:/, '');
+const __dirname = path.dirname(__filename);
+
+export class RealtimeService extends Construct {
+	authHandler: IFunction;
+
+	constructor(scope: Construct, id: string, props: {
+		appId: string;
+		branchId: string;
+		publisher: {
+			addEnvironment: (key: string, value: string) => void;
+			resources: {
+				lambda: IFunction;
+			}
+		};
+		namespaces: string[];
+	}) {
+		super(scope, id);
+		let realtimeService: EventApi | undefined;
+
+		const LAMBDA = AppSyncAuthorizationType.LAMBDA;
+		const IAM = AppSyncAuthorizationType.IAM;
+
+		this.authHandler = new NodejsFunction(this, 'realtime-auth', {
+			runtime: Runtime.NODEJS_22_X,
+			handler: 'handler',
+			entry: path.join(__dirname, 'handler-lambda.ts'),
+			timeout: Duration.seconds(30),
+			environment: {
+				// must match wirejs-deploy-amplify-basic/wirejs-resources-overrides/services/realtime.ts:SECRET_ID
+				// TODO: find a common place to define this, or just pass it through
+				// in `addResource()`. (Redundant across `RealtimeService` instances.)
+				SECRET_ID: 'realtime-secret',
+			}
+		});
+
+		const lambdaProvider: AppSyncAuthProvider = {
+			authorizationType: LAMBDA,
+			lambdaAuthorizerConfig: { handler: this.authHandler }
+		};
+		const iamProvider: AppSyncAuthProvider = { authorizationType: IAM };
+
+		realtimeService = new EventApi(this, 'realtime', {
+			apiName: `${props.appId}-${props.branchId}-realtime-api`,
+			authorizationConfig: {
+				authProviders: [iamProvider, lambdaProvider],
+				connectionAuthModeTypes: [LAMBDA],
+				defaultSubscribeAuthModeTypes: [LAMBDA],
+				defaultPublishAuthModeTypes: [IAM],
+			},
+		});
+
+		// TODO: move this to backend.ts so all env vars are set in one place
+		props.publisher.addEnvironment(
+			'REALTIME_WS_DOMAIN', realtimeService.realtimeDns,
+		);
+		props.publisher.addEnvironment(
+			'REALTIME_HTTP_DOMAIN', realtimeService.httpDns,
+		);
+
+		for (const namespaceBaseName of props.namespaces) {
+			const resourceName = namespaceBaseName
+				.replace(/[^a-zA-Z0-9-_]/g, '_')
+				.slice(0, 50);
+			const ns = realtimeService.addChannelNamespace(resourceName);
+			ns.grantPublish(props.publisher.resources.lambda);
+		}
+	}
+}

package/amplify-hosting-assets/compute/default/package.json

@@ -3,6 +3,6 @@
 	"dependencies": {
 		"jsdom": "^25.0.1",
 		"wirejs-dom": "^1.0.41",
-		"wirejs-resources": "^0.1.59"
+		"wirejs-resources": "^0.1.61-realtime"
 	}
 }

package/dist/client/index.d.ts

@@ -1 +1 @@
-export * from 'wirejs-resources/client';
+export declare function apiTree(INTERNAL_API_URL: string, path?: string[]): () => void;

package/dist/client/index.js

@@ -1 +1,79 @@
-export * from 'wirejs-resources/client';
+import * as rt from './realtime.js';
+async function callApi(INTERNAL_API_URL, method, ...args) {
+    function isNode() {
+        return typeof args[0]?.cookies?.getAll === 'function';
+    }
+    function apiUrl() {
+        if (isNode()) {
+            return INTERNAL_API_URL;
+        }
+        else {
+            return "/api";
+        }
+    }
+    let cookieHeader = {};
+    if (isNode()) {
+        const context = args[0];
+        const cookies = context.cookies.getAll();
+        cookieHeader = typeof cookies === 'object'
+            ? {
+                Cookie: Object.entries(cookies).map(kv => kv.join('=')).join('; ')
+            }
+            : {};
+    }
+    const response = await fetch(apiUrl(), {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...cookieHeader
+        },
+        body: JSON.stringify([{ method, args: [...args] }]),
+    });
+    const body = await response.json();
+    if (isNode()) {
+        const context = args[0];
+        for (const c of response.headers.getSetCookie()) {
+            const parts = c.split(';').map(p => p.trim());
+            const flags = parts.slice(1);
+            const [name, value] = parts[0].split('=').map(decodeURIComponent);
+            const httpOnly = flags.includes('HttpOnly');
+            const secure = flags.includes('Secure');
+            const maxAgePart = flags.find(f => f.startsWith('Max-Age='))?.split('=')[1];
+            context.cookies.set({
+                name,
+                value,
+                httpOnly,
+                secure,
+                maxAge: maxAgePart ? parseInt(maxAgePart) : undefined
+            });
+        }
+    }
+    const error = body[0].error;
+    if (error) {
+        throw new Error(error);
+    }
+    const value = body[0].data;
+    if (typeof value === 'object' && value.__wjstype === 'realtime') {
+        return {
+            subscribe(subscriber) {
+                rt.subscribe(value.url, value.channel, value.token, subscriber);
+                return () => {
+                    rt.unsubscribe(value.url, value.channel, subscriber);
+                };
+            }
+        };
+    }
+    return value;
+}
+;
+export function apiTree(INTERNAL_API_URL, path = []) {
+    return new Proxy(function () { }, {
+        apply(_target, _thisArg, args) {
+            return callApi(INTERNAL_API_URL, path, ...args);
+        },
+        get(_target, prop) {
+            return apiTree(INTERNAL_API_URL, [...path, prop]);
+        }
+    });
+}
+;

package/dist/client/realtime.d.ts

@@ -0,0 +1,11 @@
+export type Subscriber = {
+    onmessage: (data: any) => void;
+    onclose?: () => void;
+};
+export type ChannelEvent<T = any> = {
+    type: "data" | "broadcast_error" | "ka";
+    id: string;
+    event: any;
+};
+export declare function subscribe(url: string, channel: string, token: string, subscriber: Subscriber): void;
+export declare function unsubscribe(url: string, channel: string, subscriber: Subscriber): void;

package/dist/client/realtime.js

@@ -0,0 +1,127 @@
+// AppSync RTS has a few complexities we don't handle in local mode.
+// 1. We connect *one time* per URL.
+// 2. We subscribe to a channel within the WebSocket connection *one time*.
+// 3. Each new subscriber need to listen to the "connection"
+/**
+ * URL -> WebSocket connection
+ */
+const connections = new Map();
+/**
+ * `${URL}#${channel}` -> subscription ID
+ */
+const channelSubs = new Map();
+/**
+ * subscription ID -> subscriber
+ */
+const subscribers = new Map();
+/**
+ * Encodes an object into Base64 URL format.
+ * From https://docs.aws.amazon.com/appsync/latest/eventapi/event-api-websocket-protocol.html#websocket-connection-handshake
+ * @param {*} authorization - an object with the required authorization properties
+ **/
+function getBase64URLEncoded(authorization) {
+    return btoa(JSON.stringify(authorization))
+        .replace(/\+/g, '-') // Convert '+' to '-'
+        .replace(/\//g, '_') // Convert '/' to '_'
+        .replace(/=+$/, ''); // Remove padding `=`
+}
+/**
+ * @param authorization
+ * @returns
+ */
+function getAuthProtocol(authorization) {
+    const header = getBase64URLEncoded(authorization);
+    return `header-${header}`;
+}
+export function subscribe(url, channel, token, subscriber) {
+    const fullChannelName = `${url}#${channel}`;
+    const authorization = {
+        Authorization: token,
+        host: new URL(url).host,
+    };
+    if (!connections.has(url)) {
+        const ws = new WebSocket(url, [
+            'aws-appsync-event-ws',
+            getAuthProtocol(authorization)
+        ]);
+        connections.set(url, ws);
+        ws.onmessage = event => {
+            const data = JSON.parse(event.data);
+            if (data.type === 'data') {
+                for (const subscriber of subscribers.get(data.id) || []) {
+                    try {
+                        subscriber.onmessage(data.event);
+                    }
+                    catch (error) {
+                        console.error('Error in subscriber onmessage:', error);
+                    }
+                }
+            }
+        };
+        ws.onclose = event => {
+            const subscriptionIds = Array.from(channelSubs.keys())
+                .filter(id => id.startsWith(`${url}#`));
+            for (const subscriptionId of subscriptionIds) {
+                const subs = subscribers.get(subscriptionId);
+                if (subs) {
+                    for (const subscriber of subs) {
+                        if (subscriber.onclose) {
+                            try {
+                                subscriber.onclose();
+                            }
+                            catch (error) {
+                                console.error('Error in subscriber onclose:', error);
+                            }
+                        }
+                    }
+                    subscribers.delete(subscriptionId);
+                }
+            }
+            console.log('closed', event);
+        };
+    }
+    if (!channelSubs.has(channel)) {
+        const subscriptionId = crypto.randomUUID();
+        const ws = connections.get(url);
+        const subscribe = () => {
+            ws.send(JSON.stringify({
+                id: subscriptionId,
+                type: 'subscribe',
+                channel,
+                authorization
+            }));
+            channelSubs.set(fullChannelName, subscriptionId);
+            subscribers.set(subscriptionId, []);
+        };
+        if (ws.readyState === WebSocket.OPEN) {
+            subscribe();
+        }
+        else {
+            ws.addEventListener('open', subscribe);
+        }
+    }
+    subscribers.get(fullChannelName).push(subscriber);
+}
+export function unsubscribe(url, channel, subscriber) {
+    const fullChannelName = `${url}#${channel}`;
+    if (subscribers.has(fullChannelName)) {
+        const subs = subscribers.get(fullChannelName);
+        const index = subs.indexOf(subscriber);
+        if (index !== -1) {
+            subs.splice(index, 1);
+            if (subs.length === 0) {
+                channelSubs.delete(fullChannelName);
+                const urlSubs = Array.from(channelSubs.keys())
+                    .filter(id => id.startsWith(`${url}#`));
+                if (urlSubs.length === 0) {
+                    const ws = connections.get(url);
+                    if (ws) {
+                        ws.close();
+                        connections.delete(url);
+                    }
+                }
+                subscribers.delete(url);
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from 'wirejs-resources';
 export { FileService } from './services/file.js';
 export { AuthenticationService } from './services/authentication.js';
 export { DistributedTable } from './resources/distributed-table.js';
+export { RealtimeService } from './services/realtime.js';

package/dist/index.js

@@ -8,7 +8,10 @@ import { AuthenticationService } from './services/authentication.js';
 export { AuthenticationService } from './services/authentication.js';
 import { DistributedTable } from './resources/distributed-table.js';
 export { DistributedTable } from './resources/distributed-table.js';
+import { RealtimeService } from './services/realtime.js';
+export { RealtimeService } from './services/realtime.js';
 // expose resources to other resources that might depend on it.
 overrides.AuthenticationService = AuthenticationService;
 overrides.DistributedTable = DistributedTable;
 overrides.FileService = FileService;
+overrides.RealtimeService = RealtimeService;

package/dist/services/realtime.d.ts

@@ -0,0 +1,12 @@
+import { Resource } from 'wirejs-resources';
+export declare const SECRET_ID = "realtime-secret";
+export declare class RealtimeService<T = any> extends Resource {
+    #private;
+    constructor(scope: Resource | string, id: string);
+    /**
+     * The address the client will need to connect to.
+     */
+    get address(): string;
+    publish(channel: string, events: T[]): Promise<void>;
+    getStream(channel: string): Promise<any>;
+}

package/dist/services/realtime.js

@@ -0,0 +1,106 @@
+import * as jose from 'jose';
+import { Resource, Secret } from 'wirejs-resources';
+import { SignatureV4 } from '@aws-sdk/signature-v4';
+import { HttpRequest } from '@aws-sdk/protocol-http';
+import { defaultProvider } from '@aws-sdk/credential-provider-node';
+import { Sha256 } from '@aws-crypto/sha256-js';
+import { addResource } from '../resource-collector.js';
+export const SECRET_ID = 'realtime-secret';
+export class RealtimeService extends Resource {
+    #secret;
+    constructor(scope, id) {
+        super(scope, id);
+        this.#secret = new Secret(this, SECRET_ID);
+        addResource('RealtimeService', { absoluteId: this.absoluteId });
+    }
+    /**
+     * Ensures channel name will be supported by known, major cloud provers using
+     * "serverless" solutions.
+     *
+     * Least common denominator on channel naming appears to be AWS AppSync:
+     * Ref: https://docs.aws.amazon.com/appsync/latest/eventapi/event-api-websocket-protocol.html#realtime-websocket-operations
+     *
+     * AFAIK, other providers allow 255 and beyond with a similar limitations. GCP PubSub
+     * doesn't support slashes in the topic name. But, on GCP, we can probably replaces
+     * slashes with underscores, and actual underscores with double-underscores...
+     *
+     * @param name
+     */
+    #validateChannelName(name) {
+        if (!name.match(/^\/?[A-Za-z0-9](?:[A-Za-z0-9-]{0,48}[A-Za-z0-9])?(?:\/[A-Za-z0-9](?:[A-Za-z0-9-]{0,48}[A-Za-z0-9])?){0,4}\/?$/)) {
+            throw new Error("Channel name must be no more than 4 segments of 1-50 alphanumeric characters and dashes each.");
+        }
+    }
+    /**
+     * The address the client will need to connect to.
+     */
+    get address() {
+        return `ws://${process.env.REALTIME_WS_DOMAIN}/event`;
+    }
+    async publish(channel, events) {
+        this.#validateChannelName(channel);
+        console.log('Publishing to channels:', channel);
+        // AppSync allows batches of no more than 5. Hence, if we have more than 5,
+        // we need to perform batching on our end.
+        if (events.length > 5) {
+            let i = 0;
+            while (i < events.length) {
+                const batch = events.slice(i, i + 5);
+                await this.publish(channel, batch);
+                i += 5;
+            }
+            return;
+        }
+        // TODO: Utility for making SigV4 requests a little more concise.
+        const credentials = await defaultProvider()();
+        const signer = new SignatureV4({
+            service: 'appsync',
+            region: process.env.AWS_REGION || 'us-east-1',
+            credentials,
+            sha256: Sha256,
+        });
+        const request = new HttpRequest({
+            method: 'POST',
+            protocol: 'https:',
+            // hostname: `${process.env.REALTIME_DOMAIN}.appsync-api.${process.env.AWS_REGION}.amazonaws.com`,
+            hostname: process.env.REALTIME_HTTP_DOMAIN,
+            path: '/event',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-amz-date': new Date().toISOString(),
+            },
+            body: JSON.stringify({
+                channel,
+                events: {
+                    channel: `default/${channel}`,
+                    events: events.map(event => JSON.stringify(event))
+                },
+            }),
+        });
+        const signedRequest = await signer.sign(request);
+        const response = await fetch(`https://${signedRequest.hostname}${signedRequest.path}`, {
+            method: signedRequest.method,
+            headers: signedRequest.headers,
+            body: signedRequest.body,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to publish to channel: ${response.statusText}`);
+        }
+    }
+    async getStream(channel) {
+        this.#validateChannelName(channel);
+        const channelString = Buffer.from(channel).toString('base64');
+        const payload = { channel };
+        const jwt = await new jose.SignJWT(payload)
+            .setProtectedHeader({ alg: 'HS256' })
+            .setIssuedAt()
+            .setExpirationTime(`10s`)
+            .sign(new TextEncoder().encode(await this.#secret.read()));
+        return {
+            __wjstype: 'realtime',
+            url: `${this.address}/${channelString}`,
+            channel,
+            token: jwt
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wirejs-deploy-amplify-basic",
-	"version": "0.0.91",
+	"version": "0.0.93-realtime",
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -27,17 +27,21 @@
 		"wirejs-deploy-amplify-basic": "build.js"
 	},
 	"dependencies": {
+		"@aws-crypto/sha256-js": "^5.2.0",
 		"@aws-sdk/client-cognito-identity-provider": "^3.741.0",
 		"@aws-sdk/client-dynamodb": "^3.774.0",
 		"@aws-sdk/client-s3": "^3.738.0",
+		"@aws-sdk/credential-provider-node": "^3.806.0",
 		"@aws-sdk/lib-dynamodb": "^3.778.0",
+		"@aws-sdk/protocol-http": "^3.370.0",
+		"@aws-sdk/signature-v4": "^3.370.0",
 		"copy": "^0.3.2",
 		"esbuild": "^0.24.2",
 		"jsdom": "^25.0.0",
 		"recursive-copy": "^2.0.14",
 		"rimraf": "^6.0.1",
 		"wirejs-dom": "^1.0.41",
-		"wirejs-resources": "^0.1.59"
+		"wirejs-resources": "^0.1.61-realtime"
 	},
 	"devDependencies": {
 		"@aws-amplify/backend": "^1.14.0",