@pikku/lambda 0.6.3

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@pikku/lambda",
+  "version": "0.6.3",
+  "license": "MIT",
+  "author": "yasser.fadl@gmail.com",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "tsc": "tsc",
+    "build:esm": "tsc -b",
+    "build": "yarn build:esm",
+    "release": "npm run build && npm test",
+    "ncu": "ncu",
+    "test": "bash run-tests.sh",
+    "test:watch": "bash run-tests.sh --watch",
+    "test:coverage": "bash run-tests.sh --coverage"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./http": "./dist/http/index.js",
+    "./websocket": "./dist/websocket/index.js"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-apigatewaymanagementapi": "^3.713.0",
+    "@pikku/core": "^0.6.7",
+    "@types/aws-lambda": "^8.10.146"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-apigatewaymanagementapi": "^3.713.0",
+    "@types/aws-lambda": "^8.10.146",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/run-tests.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+
+# Enable nullglob to handle cases where no files match the pattern
+shopt -s nullglob
+
+# Initialize variables for options
+watch_mode=false
+coverage_mode=false
+
+# Parse command-line options
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --watch)
+      watch_mode=true
+      shift
+      ;;
+    --coverage)
+      coverage_mode=true
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1"
+      exit 1
+      ;;
+  esac
+done
+
+# Define the pattern to match your test files
+pattern="src/*.test.ts"
+
+# Expand the pattern into an array of files
+files=($(find src -type f -name "*.test.ts"))
+
+# Check if any files matched the pattern
+if [ ${#files[@]} -eq 0 ]; then
+  echo "No test files found matching pattern: $pattern"
+  exit 0
+fi
+
+# Construct the node command
+node_cmd="node --import tsx --test"
+
+# Append options based on flags
+if [ "$watch_mode" = true ]; then
+  node_cmd="$node_cmd --watch"
+fi
+
+if [ "$coverage_mode" = true ]; then
+  node_cmd="$node_cmd --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info"
+fi
+
+# Execute the node command with the expanded list of files
+$node_cmd "${files[@]}"

package/src/http/anywhere-http.ts

@@ -0,0 +1,39 @@
+import {
+  CoreSingletonServices,
+  CoreServices,
+  CreateSessionServices,
+  CoreUserSession,
+} from '@pikku/core'
+import { APIGatewayProxyEvent } from 'aws-lambda'
+import { generalHTTPHandler } from './general-http-handler.js'
+import { PikkuAPIGatewayLambdaRequest } from '../pikku-api-gateway-lambda-request.js'
+import { PikkuAPIGatewayLambdaResponse } from '../pikku-api-gateway-lambda-response.js'
+
+export const anywhereHTTP = async <
+  SingletonServices extends CoreSingletonServices,
+  Services extends CoreServices<SingletonServices>,
+>(
+  event: APIGatewayProxyEvent,
+  singletonServices: SingletonServices,
+  createSessionServices: CreateSessionServices<
+    SingletonServices,
+    Services,
+    CoreUserSession
+  >
+) => {
+  const request = new PikkuAPIGatewayLambdaRequest(event)
+  const response = new PikkuAPIGatewayLambdaResponse()
+  if (event.headers.origin) {
+    response.setHeader(
+      'Access-Control-Allow-Origin',
+      event.headers.origin.toString()
+    )
+  }
+  response.setHeader('Access-Control-Allow-Credentials', true)
+  return await generalHTTPHandler(
+    singletonServices,
+    createSessionServices,
+    request,
+    response
+  )
+}

package/src/http/cors-http.ts

@@ -0,0 +1,70 @@
+import type {
+  CoreSingletonServices,
+  CoreServices,
+  CreateSessionServices,
+  CoreUserSession,
+} from '@pikku/core'
+import type { APIGatewayProxyEvent } from 'aws-lambda'
+import type { Logger } from '@pikku/core/services'
+
+import { generalHTTPHandler } from './general-http-handler.js'
+import { InvalidOriginError } from '@pikku/core/errors'
+import { PikkuAPIGatewayLambdaResponse } from '../pikku-api-gateway-lambda-response.js'
+import { PikkuAPIGatewayLambdaRequest } from '../pikku-api-gateway-lambda-request.js'
+
+const validateOrigin = (
+  allowsOrigins: string[],
+  logger: Logger,
+  event: APIGatewayProxyEvent
+): string => {
+  const origin = event.headers.origin
+  if (!origin || allowsOrigins.every((domain) => !origin.includes(domain))) {
+    logger.error(`
+  CORS Error
+    - Recieved from origin: ${origin}
+    - Expected domain(s): ${allowsOrigins.join(', ')}
+    - Host: ${event.headers.host}
+    - Path: ${event.path}
+    - Headers: ${JSON.stringify(event.headers, null, '\t')}
+  `)
+    throw new InvalidOriginError()
+  }
+
+  return origin
+}
+
+export const corsHTTP = async <
+  SingletonServices extends CoreSingletonServices,
+  Services extends CoreServices<SingletonServices>,
+  UserSession extends CoreUserSession,
+>(
+  event: APIGatewayProxyEvent,
+  allowedOrigins: string[],
+  singletonServices: SingletonServices,
+  createSessionServices: CreateSessionServices<
+    SingletonServices,
+    Services,
+    UserSession
+  >
+) => {
+  const request = new PikkuAPIGatewayLambdaRequest(event)
+  const response = new PikkuAPIGatewayLambdaResponse()
+
+  let origin: string | false = false
+  try {
+    origin = validateOrigin(allowedOrigins, singletonServices.logger, event)
+  } catch {
+    response.setStatus(400)
+    response.setJson({ error: 'error.invalid_origin' })
+  }
+
+  response.setHeader('Access-Control-Allow-Origin', origin)
+  response.setHeader('Access-Control-Allow-Credentials', true)
+
+  return await generalHTTPHandler(
+    singletonServices,
+    createSessionServices,
+    request,
+    response
+  )
+}

package/src/http/corsless-http.ts

@@ -0,0 +1,33 @@
+import { APIGatewayProxyEvent } from 'aws-lambda'
+import {
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+  CreateSessionServices,
+} from '@pikku/core'
+import { generalHTTPHandler } from './general-http-handler.js'
+import { PikkuAPIGatewayLambdaRequest } from '../pikku-api-gateway-lambda-request.js'
+import { PikkuAPIGatewayLambdaResponse } from '../pikku-api-gateway-lambda-response.js'
+
+export const corslessHTTP = async <
+  SingletonServices extends CoreSingletonServices,
+  Services extends CoreServices<SingletonServices>,
+  UserSession extends CoreUserSession,
+>(
+  event: APIGatewayProxyEvent,
+  singletonServices: SingletonServices,
+  createSessionServices: CreateSessionServices<
+    SingletonServices,
+    Services,
+    UserSession
+  >
+) => {
+  const request = new PikkuAPIGatewayLambdaRequest(event)
+  const response = new PikkuAPIGatewayLambdaResponse()
+  return await generalHTTPHandler(
+    singletonServices,
+    createSessionServices,
+    request,
+    response
+  )
+}

package/src/http/general-http-handler.ts

@@ -0,0 +1,59 @@
+import {
+  CoreSingletonServices,
+  CoreServices,
+  CreateSessionServices,
+  CoreUserSession,
+} from '@pikku/core'
+import { runHTTPRoute } from '@pikku/core/http'
+import { APIGatewayProxyResult } from 'aws-lambda'
+import { PikkuAPIGatewayLambdaRequest } from '../pikku-api-gateway-lambda-request.js'
+import { PikkuAPIGatewayLambdaResponse } from '../pikku-api-gateway-lambda-response.js'
+
+export const generalHTTPHandler = async <
+  SingletonServices extends CoreSingletonServices,
+  Services extends CoreServices<SingletonServices>,
+  UserSession extends CoreUserSession,
+>(
+  singletonServices: SingletonServices,
+  createSessionServices: CreateSessionServices<
+    SingletonServices,
+    Services,
+    UserSession
+  >,
+  request: PikkuAPIGatewayLambdaRequest,
+  response: PikkuAPIGatewayLambdaResponse
+): Promise<APIGatewayProxyResult> => {
+  if (request.getMethod() === 'options') {
+    response.setHeader(
+      'Access-Control-Allow-Headers',
+      'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token,X-Amz-User-Agent'
+    )
+    response.setHeader(
+      'Access-Control-Allow-Methods',
+      'OPTIONS,DELETE,GET,HEAD,PATCH,POST,PUT'
+    )
+    response.setStatus(200)
+    response.setJson({})
+    return response.getLambdaResponse()
+  }
+
+  if (request.getPath().includes('health-check')) {
+    response.setStatus(200)
+    return response.getLambdaResponse()
+  }
+
+  try {
+    await runHTTPRoute({
+      request,
+      response,
+      singletonServices,
+      createSessionServices: createSessionServices as any,
+      route: request.getPath(),
+      method: request.getMethod() as any,
+    })
+  } catch {
+    // Error should have already been handled by runHTTPRoute
+  }
+
+  return response.getLambdaResponse()
+}

package/src/http/index.ts

@@ -0,0 +1,3 @@
+export * from './anywhere-http.js'
+export * from './corsless-http.js'
+export * from './cors-http.js'

package/src/index.ts

@@ -0,0 +1 @@
+export default null

package/src/pikku-api-gateway-lambda-request.ts

@@ -0,0 +1,31 @@
+import type { APIGatewayProxyEvent } from 'aws-lambda'
+import type { HTTPMethod, PikkuQuery } from '@pikku/core/http'
+import { PikkuHTTPAbstractRequest } from '@pikku/core/http/pikku-http-abstract-request'
+
+export class PikkuAPIGatewayLambdaRequest extends PikkuHTTPAbstractRequest {
+  constructor(protected event: APIGatewayProxyEvent) {
+    super()
+  }
+
+  public getPath() {
+    // TODO: The path can be undefined, types are invalid
+    return this.event.path || '/'
+  }
+
+  public getMethod() {
+    return this.event.httpMethod.toLowerCase() as HTTPMethod
+  }
+
+  public async getBody() {
+    return this.event.body
+  }
+
+  public getHeader(headerName: string): string | undefined {
+    return this.event.headers[headerName]
+  }
+
+  public getQuery() {
+    // TODO: If query isn't defined, it should be an empty object
+    return (this.event.queryStringParameters as PikkuQuery) || {}
+  }
+}

package/src/pikku-api-gateway-lambda-response.ts

@@ -0,0 +1,41 @@
+import { JSONValue } from '@pikku/core'
+import { PikkuHTTPAbstractResponse } from '@pikku/core/http/pikku-http-abstract-response'
+import { APIGatewayProxyResult } from 'aws-lambda'
+
+export class PikkuAPIGatewayLambdaResponse extends PikkuHTTPAbstractResponse {
+  public headers: Record<string, string> = {}
+  private status: number = 200
+  private body: any | undefined
+
+  constructor() {
+    super()
+  }
+
+  public getLambdaResponse(): APIGatewayProxyResult {
+    return {
+      headers: this.headers,
+      statusCode: this.status,
+      body: this.body,
+    }
+  }
+
+  public setStatus(status: number): void {
+    this.status = status
+  }
+
+  public setHeader(name: string, value: string | boolean | string[]): void {
+    this.headers[name] = value.toString()
+  }
+
+  public setJson(value: JSONValue): void {
+    this.body = JSON.stringify(value)
+  }
+
+  public setResponse(response: string | Buffer): void {
+    this.body = response
+  }
+
+  public setRedirect(path: string, status: number) {
+    throw new Error('Method not implemented.')
+  }
+}

package/src/websocket/index.ts

@@ -0,0 +1,4 @@
+export * from './websocket-message.js'
+export * from './websocket-connect.js'
+export * from './websocket-disconnect.js'
+export * from './lambda-eventhub-service.js'

package/src/websocket/lambda-channel-handler.ts

@@ -0,0 +1,63 @@
+import { CoreUserSession } from '@pikku/core'
+import {
+  ChannelStore,
+  PikkuAbstractChannelHandler,
+  PikkuChannelHandlerFactory,
+} from '@pikku/core/channel'
+import { sendMessage } from './utils.js'
+import { ApiGatewayManagementApiClient } from '@aws-sdk/client-apigatewaymanagementapi'
+import { Logger } from '@pikku/core/services'
+
+class LambdaChannelHandler<
+  UserSession extends CoreUserSession = CoreUserSession,
+  OpeningData = unknown,
+  Out = unknown,
+> extends PikkuAbstractChannelHandler<UserSession, OpeningData, Out> {
+  constructor(
+    private logger: Logger,
+    userSession: UserSession | undefined,
+    private channelStore: ChannelStore,
+    private callbackAPI: ApiGatewayManagementApiClient,
+    channelId: string,
+    channelName: string,
+    openingData: OpeningData
+  ) {
+    super(channelId, channelName, userSession, openingData)
+  }
+
+  public async setUserSession(userSession: UserSession): Promise<void> {
+    this.userSession = userSession
+    await this.channelStore.setUserSession(this.channelId, userSession)
+  }
+
+  public async send(message: Out, isBinary?: boolean) {
+    if (isBinary) {
+      throw new Error('Binary data is not supported on serverless lambdas')
+    }
+    const data = JSON.stringify(message)
+    await sendMessage(this.logger, this.callbackAPI, this.channelId, data)
+  }
+}
+
+export const createLambdaChannelHandlerFactory = (
+  logger: Logger,
+  channelStore: ChannelStore,
+  callbackAPI: ApiGatewayManagementApiClient
+) => {
+  const factory: PikkuChannelHandlerFactory = (
+    channelId,
+    channelName,
+    openingData,
+    userSession
+  ) =>
+    new LambdaChannelHandler(
+      logger,
+      userSession,
+      channelStore,
+      callbackAPI,
+      channelId,
+      channelName,
+      openingData
+    )
+  return factory
+}

package/src/websocket/lambda-eventhub-service.ts

@@ -0,0 +1,59 @@
+import { ApiGatewayManagementApiClient } from '@aws-sdk/client-apigatewaymanagementapi'
+import {
+  ChannelStore,
+  EventHubService,
+  EventHubStore,
+} from '@pikku/core/channel'
+import { getApiGatewayManagementApiClient, sendMessages } from './utils.js'
+import { Logger } from '@pikku/core/services'
+import { APIGatewayEvent } from 'aws-lambda'
+
+export class LambdaEventHubService<Out = unknown>
+  implements EventHubService<Out>
+{
+  private callbackAPI: ApiGatewayManagementApiClient
+
+  constructor(
+    private logger: Logger,
+    event: APIGatewayEvent,
+    private channelStore: ChannelStore,
+    private eventHubStore: EventHubStore
+  ) {
+    this.callbackAPI = getApiGatewayManagementApiClient(logger, event)
+  }
+
+  async subscribe(topic: string, channelId: string): Promise<void> {
+    await this.eventHubStore.subscribe(topic, channelId)
+  }
+
+  async unsubscribe(topic: string, channelId: string): Promise<void> {
+    await this.eventHubStore.unsubscribe(topic, channelId)
+  }
+
+  async publish(
+    topic: string,
+    fromChannelId: string,
+    data: Out,
+    isBinary?: boolean
+  ): Promise<void> {
+    const channelIds = await this.eventHubStore.getChannelIdsForTopic(topic)
+    await this.sendMessages(channelIds, fromChannelId, data)
+  }
+
+  private async sendMessages(
+    channelIds: string[],
+    fromChannelId: string,
+    data: Out,
+    isBinary?: boolean
+  ): Promise<void> {
+    await sendMessages(
+      this.logger,
+      this.channelStore,
+      this.callbackAPI,
+      fromChannelId,
+      channelIds,
+      data,
+      isBinary
+    )
+  }
+}

package/src/websocket/utils.ts

@@ -0,0 +1,95 @@
+import {
+  ApiGatewayManagementApiClient,
+  PostToConnectionCommand,
+} from '@aws-sdk/client-apigatewaymanagementapi'
+import { Logger } from '@pikku/core/services'
+import { APIGatewayEvent } from 'aws-lambda'
+import { createLambdaChannelHandlerFactory } from './lambda-channel-handler.js'
+import { ChannelStore } from '@pikku/core/channel'
+
+export const sendMessage = async (
+  logger: Logger,
+  callbackAPI: ApiGatewayManagementApiClient,
+  ConnectionId: string,
+  Data: string
+): Promise<boolean> => {
+  try {
+    await callbackAPI.send(new PostToConnectionCommand({ ConnectionId, Data }))
+    return true
+  } catch (e: any) {
+    // TODO: We need to check if it's a 410 and remove the connection if it is
+    // Otherwise we need to log the error
+    logger.error(e.message)
+    return false
+  }
+}
+
+export const sendMessages = async (
+  logger: Logger,
+  channelStore: ChannelStore,
+  callbackAPI: ApiGatewayManagementApiClient,
+  fromChannelId: string,
+  channelIds: string[],
+  data: unknown,
+  isBinary?: boolean
+): Promise<void> => {
+  if (isBinary) {
+    throw new Error('Binary data is not supported on serverless lambdas')
+  }
+  const staleWebsockets: string[] = []
+  const Data = JSON.stringify(data)
+  await Promise.all(
+    channelIds.map(async (channelId) => {
+      if (channelId !== fromChannelId) {
+        const success = await sendMessage(logger, callbackAPI, channelId, Data)
+        if (!success) {
+          staleWebsockets.push(channelId)
+        }
+      }
+    })
+  )
+  if (staleWebsockets.length > 0) {
+    await channelStore.removeChannels(staleWebsockets)
+  }
+}
+
+export const getApiGatewayManagementApiClient = (
+  logger: Logger,
+  event: APIGatewayEvent
+) => {
+  let endpoint: string
+  if (process.env.IS_OFFLINE) {
+    logger.info('Assuming serverless offline mode due to IS_OFFLINE')
+    endpoint = `http://localhost:3001`
+  } else if (event.requestContext.domainName?.includes('amazonaws.com')) {
+    logger.info(
+      'Assuming we are using the default endpoint mode due to amazonaws.com domain'
+    )
+    endpoint = `https://${event.requestContext.domainName}/${event.requestContext.stage}`
+  } else {
+    logger.info('Assuming we are using a custom domain mode')
+    endpoint = `https://${event.requestContext.domainName}`
+  }
+  return new ApiGatewayManagementApiClient({
+    apiVersion: '2018-11-29',
+    endpoint,
+  })
+}
+
+export const getServerlessDependencies = (
+  logger: Logger,
+  channelStore: ChannelStore,
+  event: APIGatewayEvent
+) => {
+  const channelId = event.requestContext.connectionId
+  if (!channelId) {
+    throw new Error('No connectionId found in requestContext')
+  }
+  const callbackAPI = getApiGatewayManagementApiClient(logger, event)
+  const channelHandlerFactory = createLambdaChannelHandlerFactory(
+    logger,
+    channelStore,
+    callbackAPI
+  )
+  return { channelId, callbackAPI, channelHandlerFactory, channelStore }
+}

package/src/websocket/websocket-connect.ts

@@ -0,0 +1,41 @@
+import {
+  CoreSingletonServices,
+  CoreServices,
+  CoreUserSession,
+} from '@pikku/core'
+import { APIGatewayEvent, APIGatewayProxyResult } from 'aws-lambda'
+import { PikkuAPIGatewayLambdaResponse } from '../pikku-api-gateway-lambda-response.js'
+import { runChannelConnect } from '@pikku/core/channel/serverless'
+import { getServerlessDependencies } from './utils.js'
+import { WebsocketParams } from './websocket-types.js'
+import { PikkuAPIGatewayLambdaRequest } from '../pikku-api-gateway-lambda-request.js'
+
+export const connectWebsocket = async <
+  SingletonServices extends CoreSingletonServices,
+  Services extends CoreServices<SingletonServices>,
+  UserSession extends CoreUserSession,
+>(
+  event: APIGatewayEvent,
+  {
+    singletonServices,
+    createSessionServices,
+    channelStore,
+  }: WebsocketParams<SingletonServices, Services, UserSession>
+): Promise<APIGatewayProxyResult> => {
+  const runnerParams = getServerlessDependencies(
+    singletonServices.logger,
+    channelStore,
+    event
+  )
+  const request = new PikkuAPIGatewayLambdaRequest(event)
+  const response = new PikkuAPIGatewayLambdaResponse()
+  await runChannelConnect({
+    ...runnerParams,
+    request,
+    response,
+    singletonServices: singletonServices as any,
+    createSessionServices: createSessionServices as any,
+    route: event.path || '/',
+  })
+  return response.getLambdaResponse()
+}

package/src/websocket/websocket-disconnect.ts

@@ -0,0 +1,35 @@
+import {
+  CoreSingletonServices,
+  CoreServices,
+  CoreUserSession,
+} from '@pikku/core'
+import { runChannelDisconnect } from '@pikku/core/channel/serverless'
+import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda'
+
+import { getServerlessDependencies } from './utils.js'
+import { WebsocketParams } from './websocket-types.js'
+
+export const disconnectWebsocket = async <
+  SingletonServices extends CoreSingletonServices,
+  Services extends CoreServices<SingletonServices>,
+  UserSession extends CoreUserSession,
+>(
+  event: APIGatewayProxyEvent,
+  {
+    singletonServices,
+    createSessionServices,
+    channelStore,
+  }: WebsocketParams<SingletonServices, Services, UserSession>
+): Promise<APIGatewayProxyResult> => {
+  const runnerParams = getServerlessDependencies(
+    singletonServices.logger,
+    channelStore,
+    event
+  )
+  await runChannelDisconnect({
+    ...runnerParams,
+    singletonServices: singletonServices as any,
+    createSessionServices: createSessionServices as any,
+  })
+  return { statusCode: 200, body: '' }
+}