@pikku/lambda 0.12.2 → 0.12.4

package/src/handler-factories.ts

@@ -0,0 +1,165 @@
+/**
+ * Lambda handler factories — mirrors Cloudflare's handler-factories.ts.
+ *
+ * Creates combined Lambda handlers based on which handler types a unit needs
+ * (fetch, queue, scheduled). Services are cached across warm invocations.
+ */
+
+import { LocalVariablesService, LocalSecretService } from '@pikku/core/services'
+import type { CoreSingletonServices } from '@pikku/core'
+import type { ChannelStore } from '@pikku/core/channel'
+import { runFetchV2 } from './http/run-fetch-v2.js'
+import { runSQSQueueWorker } from './queue/sqs-worker.js'
+import { runLambdaScheduled } from './scheduled/run-scheduled.js'
+import type {
+  APIGatewayEvent,
+  APIGatewayProxyEventV2,
+  SQSEvent,
+  ScheduledEvent,
+} from 'aws-lambda'
+
+export interface LambdaServiceFactories {
+  createConfig: (
+    variables: LocalVariablesService,
+    ...args: unknown[]
+  ) => Promise<unknown>
+  createSingletonServices: (
+    config: unknown,
+    existingServices?: Partial<Record<string, unknown>>
+  ) => Promise<CoreSingletonServices>
+  /**
+   * Optional callback to create platform services from environment.
+   * Returns services to merge into existingServices.
+   * Generated by the deploy codegen based on unit capabilities.
+   */
+  createPlatformServices?: () =>
+    | Record<string, unknown>
+    | Promise<Record<string, unknown>>
+}
+
+let cachedServices: CoreSingletonServices | null = null
+
+async function setupServices(
+  factories: LambdaServiceFactories
+): Promise<CoreSingletonServices> {
+  if (cachedServices) return cachedServices
+  const variables = new LocalVariablesService(
+    process.env as Record<string, string | undefined>
+  )
+  const config = await factories.createConfig(variables)
+  const secrets = new LocalSecretService(variables)
+
+  const platformServices = factories.createPlatformServices
+    ? await factories.createPlatformServices()
+    : {}
+
+  cachedServices = await factories.createSingletonServices(config, {
+    variables,
+    secrets,
+    ...platformServices,
+  })
+  return cachedServices
+}
+
+/**
+ * Creates a combined Lambda handler based on which handler types the unit needs.
+ *
+ * Returns an object with named exports that serverless.yml references:
+ * - `handler` for HTTP (API Gateway)
+ * - `queue` for SQS
+ * - `scheduled` for EventBridge
+ */
+export function createLambdaHandler(
+  factories: LambdaServiceFactories,
+  handlerTypes: string[]
+) {
+  const result: Record<string, unknown> = {}
+
+  if (handlerTypes.includes('fetch')) {
+    result.handler = async (event: APIGatewayProxyEventV2) => {
+      await setupServices(factories)
+      return runFetchV2(event)
+    }
+  }
+
+  if (handlerTypes.includes('queue')) {
+    result.queue = async (event: SQSEvent) => {
+      const services = await setupServices(factories)
+      return runSQSQueueWorker(services.logger, event)
+    }
+  }
+
+  if (handlerTypes.includes('scheduled')) {
+    result.scheduled = async (event: ScheduledEvent) => {
+      await setupServices(factories)
+      return runLambdaScheduled(event)
+    }
+  }
+
+  // If no fetch handler was requested, add a health check
+  if (!handlerTypes.includes('fetch')) {
+    const activeHandlers = handlerTypes.join(', ')
+    result.handler = async () => ({
+      statusCode: 200,
+      body: `Lambda active (handlers: ${activeHandlers})`,
+    })
+  }
+
+  return result
+}
+
+/**
+ * Creates a Lambda handler with a fetch() entrypoint for HTTP, agent, RPC,
+ * and workflow-orchestrator units.
+ */
+export function createLambdaWorkerHandler(factories: LambdaServiceFactories) {
+  return {
+    async handler(event: APIGatewayProxyEventV2) {
+      await setupServices(factories)
+      return runFetchV2(event)
+    },
+  }
+}
+
+/**
+ * Creates a Lambda handler for WebSocket channel units.
+ * Exports separate handlers for $connect, $disconnect, and $default routes.
+ */
+export function createLambdaWebSocketHandler(
+  factories: LambdaServiceFactories
+) {
+  // Import dynamically to avoid pulling in websocket deps for non-channel units
+  const getChannelStore = () => {
+    if (!cachedServices) {
+      throw new Error('Services not initialized for WebSocket handler')
+    }
+    const channelStore = (cachedServices as unknown as Record<string, unknown>)
+      .channelStore as ChannelStore | undefined
+    if (!channelStore) {
+      throw new Error(
+        'channelStore not found in singleton services. Ensure it is configured for channel units.'
+      )
+    }
+    return channelStore
+  }
+
+  return {
+    async connect(event: APIGatewayEvent) {
+      await setupServices(factories)
+      const { connectWebsocket } = await import('./websocket/index.js')
+      return connectWebsocket(event, { channelStore: getChannelStore() })
+    },
+    async disconnect(event: APIGatewayEvent) {
+      await setupServices(factories)
+      const { disconnectWebsocket } = await import('./websocket/index.js')
+      return disconnectWebsocket(event, { channelStore: getChannelStore() })
+    },
+    async default(event: APIGatewayEvent) {
+      await setupServices(factories)
+      const { processWebsocketMessage } = await import('./websocket/index.js')
+      return processWebsocketMessage(event, {
+        channelStore: getChannelStore(),
+      })
+    },
+  }
+}

package/src/http/index.ts

@@ -1 +1,4 @@
 export * from './run-fetch.js'
+export * from './run-fetch-v2.js'
+export { lambdaV2EventToRequest } from './request-converter-v2.js'
+export { responseToLambdaV2Result } from './response-converter-v2.js'

package/src/http/request-converter-v2.ts

@@ -0,0 +1,36 @@
+import type { APIGatewayProxyEventV2 } from 'aws-lambda'
+
+export const lambdaV2EventToRequest = (
+  event: APIGatewayProxyEventV2
+): Request => {
+  const host =
+    event.headers?.host ?? event.requestContext?.domainName ?? 'localhost'
+  const url = new URL(event.rawPath, `https://${host}`)
+
+  if (event.rawQueryString) {
+    // rawQueryString is already encoded, append directly
+    url.search = `?${event.rawQueryString}`
+  }
+
+  const body =
+    event.body && event.isBase64Encoded
+      ? Buffer.from(event.body, 'base64')
+      : event.body || undefined
+
+  const method = event.requestContext?.http?.method || 'GET'
+
+  const headers: Record<string, string> = {}
+  if (event.headers) {
+    for (const [key, value] of Object.entries(event.headers)) {
+      if (value != null) {
+        headers[key] = value
+      }
+    }
+  }
+
+  return new Request(url.toString(), {
+    method,
+    headers,
+    body: ['GET', 'HEAD'].includes(method.toUpperCase()) ? undefined : body,
+  })
+}

package/src/http/response-converter-v2.ts

@@ -0,0 +1,40 @@
+import type { APIGatewayProxyStructuredResultV2 } from 'aws-lambda'
+
+export const responseToLambdaV2Result = async (
+  response: Response
+): Promise<APIGatewayProxyStructuredResultV2> => {
+  // Extract Set-Cookie headers as cookies array (v2 format)
+  const cookies: string[] = response.headers.getSetCookie
+    ? response.headers.getSetCookie()
+    : []
+
+  const headers: Record<string, string> = {}
+  response.headers.forEach((value, key) => {
+    if (key.toLowerCase() === 'set-cookie' && cookies.length > 0) return
+    headers[key.toLowerCase()] = value
+  })
+
+  let body: string
+  let isBase64Encoded = false
+
+  const contentType = response.headers.get('content-type') || ''
+  const isBinary = !/^text\/|application\/(json|javascript|xml)/.test(
+    contentType
+  )
+
+  const buffer = Buffer.from(await response.arrayBuffer())
+  if (isBinary) {
+    body = buffer.toString('base64')
+    isBase64Encoded = true
+  } else {
+    body = buffer.toString('utf-8')
+  }
+
+  return {
+    statusCode: response.status,
+    headers,
+    body,
+    isBase64Encoded,
+    ...(cookies.length > 0 ? { cookies } : {}),
+  }
+}

package/src/http/run-fetch-v2.ts

@@ -0,0 +1,42 @@
+import { PikkuFetchHTTPResponse, fetchData } from '@pikku/core/http'
+import type {
+  APIGatewayProxyEventV2,
+  APIGatewayProxyStructuredResultV2,
+} from 'aws-lambda'
+import { responseToLambdaV2Result } from './response-converter-v2.js'
+import { lambdaV2EventToRequest } from './request-converter-v2.js'
+
+export const runFetchV2 = async (
+  event: APIGatewayProxyEventV2
+): Promise<APIGatewayProxyStructuredResultV2> => {
+  const request = lambdaV2EventToRequest(event)
+  const response = new PikkuFetchHTTPResponse()
+
+  if (request.method === 'OPTIONS') {
+    response.header(
+      'Access-Control-Allow-Origin',
+      request.headers.get('origin') || '*'
+    )
+    response.header(
+      'Access-Control-Allow-Headers',
+      'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token,X-Amz-User-Agent'
+    )
+    response.header(
+      'Access-Control-Allow-Methods',
+      'OPTIONS,DELETE,GET,HEAD,PATCH,POST,PUT'
+    )
+    response.status(200)
+    return responseToLambdaV2Result(response.toResponse())
+  }
+
+  try {
+    await fetchData(request, response)
+  } catch (err) {
+    console.error('fetchData error:', err)
+    response.status(500)
+    response.header('content-type', 'application/json')
+    response.json({ error: 'Internal Server Error' })
+  }
+
+  return responseToLambdaV2Result(response.toResponse())
+}

package/src/http/run-fetch.ts

@@ -9,7 +9,7 @@ export const runFetch = async (
   const request = lambdaEventToRequest(event)
   const response = new PikkuFetchHTTPResponse()
 
-  if (request.method === 'options') {
+  if (request.method === 'OPTIONS') {
     response.header(
       'Access-Control-Allow-Headers',
       'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token,X-Amz-User-Agent'

package/src/index.test.ts

@@ -0,0 +1,13 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+
+import * as lambdaRuntime from './index.js'
+
+describe('@pikku/lambda', () => {
+  test('exports the lambda runtime API', () => {
+    assert.equal(typeof lambdaRuntime.createLambdaHandler, 'function')
+    assert.equal(typeof lambdaRuntime.LambdaDeploymentService, 'function')
+    assert.equal(typeof lambdaRuntime.SQSQueueService, 'function')
+    assert.equal(typeof lambdaRuntime.runFetch, 'function')
+  })
+})

package/src/index.ts

@@ -1,3 +1,7 @@
 export * from './http/index.js'
 export * from './websocket/index.js'
 export * from './queue/index.js'
+export * from './scheduled/index.js'
+export * from './handler-factories.js'
+export { SQSQueueService } from './sqs-queue-service.js'
+export { LambdaDeploymentService } from './lambda-deployment-service.js'

package/src/lambda-deployment-service.ts

@@ -0,0 +1,134 @@
+/**
+ * Lambda deployment service — routes remote() calls via Lambda Invoke.
+ *
+ * When a gateway (agent, MCP, channel, workflow orchestrator) calls
+ * remote('funcName'), this service dispatches to the function's Lambda
+ * via the AWS SDK InvokeCommand. Equivalent to Cloudflare's service bindings.
+ *
+ * Session propagation uses the existing pikkuRemoteAuthMiddleware:
+ * JWT signed with PIKKU_REMOTE_SECRET, session encrypted in payload.
+ */
+
+import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda'
+import type { DeploymentService, DeploymentConfig } from '@pikku/core/services'
+import type { JWTService } from '@pikku/core/services'
+import type { SecretService } from '@pikku/core/services'
+import { encryptJSON } from '@pikku/core/crypto-utils'
+
+export class LambdaDeploymentService implements DeploymentService {
+  private client: LambdaClient
+  private bindings: Map<string, string>
+
+  constructor(
+    private jwt: JWTService | undefined,
+    private secrets: SecretService,
+    functionBindings: Record<string, string>
+  ) {
+    this.client = new LambdaClient({})
+    this.bindings = new Map(Object.entries(functionBindings))
+  }
+
+  async init(): Promise<void> {}
+  async start(_config: DeploymentConfig): Promise<void> {}
+  async stop(): Promise<void> {}
+
+  async invoke(
+    funcName: string,
+    data: unknown,
+    session?: unknown,
+    traceId?: string
+  ): Promise<unknown> {
+    const lambdaFunctionName = this.bindings.get(funcName)
+    if (!lambdaFunctionName) {
+      throw new Error(
+        `No Lambda binding for function '${funcName}'. ` +
+          `Available bindings: ${[...this.bindings.keys()].join(', ')}`
+      )
+    }
+
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+      ...(traceId && { 'x-request-id': traceId }),
+    }
+
+    // Sign session as JWT for pikkuRemoteAuthMiddleware
+    let secret: string | undefined
+    try {
+      secret = await this.secrets.getSecret('PIKKU_REMOTE_SECRET')
+    } catch {}
+
+    if (secret && this.jwt) {
+      const sessionEnc = session
+        ? await encryptJSON(secret, { session })
+        : undefined
+      const token = await this.jwt.encode(
+        { value: 5, unit: 'minute' },
+        {
+          aud: 'pikku-remote',
+          fn: funcName,
+          iat: Math.floor(Date.now() / 1000),
+          session: sessionEnc,
+        }
+      )
+      headers.authorization = `Bearer ${token}`
+    }
+
+    // Build an API Gateway v2 event for the target Lambda
+    const rpcPath = `/remote/rpc/${encodeURIComponent(funcName)}`
+    const apiGatewayEvent = {
+      httpMethod: 'POST',
+      path: rpcPath,
+      headers,
+      body: JSON.stringify({ data }),
+      isBase64Encoded: false,
+      queryStringParameters: null,
+      pathParameters: null,
+      stageVariables: null,
+      requestContext: {
+        httpMethod: 'POST',
+        path: rpcPath,
+        stage: 'prod',
+        requestId: crypto.randomUUID(),
+        identity: {},
+      },
+      resource: rpcPath,
+    }
+
+    const response = await this.client.send(
+      new InvokeCommand({
+        FunctionName: lambdaFunctionName,
+        Payload: JSON.stringify(apiGatewayEvent),
+      })
+    )
+
+    if (response.FunctionError) {
+      const errorPayload = response.Payload
+        ? new TextDecoder().decode(response.Payload)
+        : 'Unknown error'
+      throw new Error(
+        `Remote RPC call to '${funcName}' failed: Lambda error: ${errorPayload}`
+      )
+    }
+
+    if (!response.Payload) {
+      throw new Error(`Remote RPC call to '${funcName}' returned no payload`)
+    }
+
+    // The Lambda returns an API Gateway response shape
+    const lambdaResult = JSON.parse(new TextDecoder().decode(response.Payload))
+
+    if (lambdaResult.statusCode && lambdaResult.statusCode >= 400) {
+      throw new Error(
+        `Remote RPC call to '${funcName}' failed: ${lambdaResult.statusCode} ${lambdaResult.body}`
+      )
+    }
+
+    // Parse the body from the API Gateway response
+    const body = lambdaResult.body
+    try {
+      return JSON.parse(body)
+    } catch {
+      return body
+    }
+  }
+}

package/src/queue/sqs-worker.ts

@@ -60,7 +60,7 @@ export const runSQSQueueWorker = async (
   logger: Logger,
   event: SQSEvent
 ): Promise<SQSBatchResponse> => {
-  console.log(JSON.stringify(event, null, 2))
+  logger.info(`Processing ${event.Records.length} SQS messages`)
   const jobs = event.Records.map(mapSQSRecordToQueueJob)
 
   // Process all jobs in parallel

package/src/scheduled/index.ts

@@ -0,0 +1 @@
+export { runLambdaScheduled } from './run-scheduled.js'

package/src/scheduled/run-scheduled.ts

@@ -0,0 +1,30 @@
+/**
+ * Lambda handler for EventBridge scheduled events.
+ *
+ * Since each Lambda corresponds to a single unit, and each unit has
+ * specific scheduled tasks registered, we run all tasks in this unit
+ * when the schedule fires.
+ */
+
+import type { ScheduledEvent } from 'aws-lambda'
+import { runScheduledTask, getScheduledTasks } from '@pikku/core/scheduler'
+
+export const runLambdaScheduled = async (
+  _event: ScheduledEvent
+): Promise<void> => {
+  const scheduledTasks = getScheduledTasks()
+
+  // Run all scheduled tasks registered in this unit.
+  // Typically one task per unit, but iterate all to be safe.
+  for (const [name] of scheduledTasks) {
+    const traceId = `cron-${crypto.randomUUID()}`
+    try {
+      await runScheduledTask({ name, traceId })
+    } catch (err) {
+      console.error(
+        `Scheduled task '${name}' (traceId: ${traceId}) failed:`,
+        err
+      )
+    }
+  }
+}

package/src/sqs-queue-service.ts

@@ -0,0 +1,91 @@
+/**
+ * SQS implementation of QueueService (producer side).
+ *
+ * Sends messages to SQS queues. Queue URLs are resolved from environment
+ * variables following the convention: SQS_QUEUE_URL_<SCREAMING_SNAKE_NAME>.
+ *
+ * The consumer side is handled by sqs-worker.ts (runSQSQueueWorker).
+ */
+
+import { SQSClient, SendMessageCommand } from '@aws-sdk/client-sqs'
+import type { QueueService, QueueJob, JobOptions } from '@pikku/core/queue'
+
+export class SQSQueueService implements QueueService {
+  readonly supportsResults = false
+  private client: SQSClient
+
+  constructor(private queueUrlMap?: Record<string, string>) {
+    this.client = new SQSClient({})
+  }
+
+  async add<T>(
+    queueName: string,
+    data: T,
+    options?: JobOptions
+  ): Promise<string> {
+    const queueUrl = this.resolveQueueUrl(queueName)
+    const messageId = crypto.randomUUID()
+
+    const message = {
+      id: messageId,
+      queueName,
+      data,
+      pikkuUserId: options?.pikkuUserId,
+    }
+
+    const result = await this.client.send(
+      new SendMessageCommand({
+        QueueUrl: queueUrl,
+        MessageBody: JSON.stringify(message),
+        DelaySeconds: options?.delay
+          ? Math.min(Math.ceil(options.delay / 1000), 900)
+          : undefined,
+      })
+    )
+
+    return result.MessageId ?? messageId
+  }
+
+  async getJob<T, R>(
+    _queueName: string,
+    _jobId: string
+  ): Promise<QueueJob<T, R> | null> {
+    throw new Error(
+      'SQSQueueService does not support getJob(). ' +
+        'SQS is fire-and-forget. ' +
+        'Use BullMQ or PgBoss if you need job result tracking.'
+    )
+  }
+
+  /**
+   * Resolves the SQS queue URL for a given queue name.
+   *
+   * Checks in order:
+   * 1. Explicit queueUrlMap passed in constructor
+   * 2. Environment variable SQS_QUEUE_URL_<SCREAMING_SNAKE>
+   */
+  private resolveQueueUrl(queueName: string): string {
+    if (this.queueUrlMap?.[queueName]) {
+      return this.queueUrlMap[queueName]
+    }
+
+    const envKey = `SQS_QUEUE_URL_${toScreamingSnake(queueName)}`
+    const url = process.env[envKey]
+
+    if (!url) {
+      throw new Error(
+        `SQS queue URL not found for queue "${queueName}". ` +
+          `Set environment variable ${envKey} or pass queueUrlMap to constructor.`
+      )
+    }
+
+    return url
+  }
+}
+
+function toScreamingSnake(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/-/g, '_')
+    .toUpperCase()
+}

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

@@ -8,9 +8,9 @@ import { getApiGatewayManagementApiClient, sendMessages } from './utils.js'
 import type { Logger } from '@pikku/core/services'
 import type { APIGatewayEvent } from 'aws-lambda'
 
-export class LambdaEventHubService<EventTopics extends Record<string, any> = {}>
-  implements EventHubService<EventTopics>
-{
+export class LambdaEventHubService<
+  EventTopics extends Record<string, any> = {},
+> implements EventHubService<EventTopics> {
   private callbackAPI: ApiGatewayManagementApiClient
 
   constructor(

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/index.ts","./src/request-converter.ts","./src/response-converter.ts","./src/http/index.ts","./src/http/run-fetch.ts","./src/queue/index.ts","./src/queue/sqs-worker.ts","./src/websocket/index.ts","./src/websocket/lambda-channel-handler.ts","./src/websocket/lambda-eventhub-service.ts","./src/websocket/utils.ts","./src/websocket/websocket-connect.ts","./src/websocket/websocket-disconnect.ts","./src/websocket/websocket-message.ts","./src/websocket/websocket-types.ts"],"version":"5.9.3"}
+{"root":["./src/handler-factories.ts","./src/index.ts","./src/lambda-deployment-service.ts","./src/request-converter.ts","./src/response-converter.ts","./src/sqs-queue-service.ts","./src/http/index.ts","./src/http/request-converter-v2.ts","./src/http/response-converter-v2.ts","./src/http/run-fetch-v2.ts","./src/http/run-fetch.ts","./src/queue/index.ts","./src/queue/sqs-worker.ts","./src/scheduled/index.ts","./src/scheduled/run-scheduled.ts","./src/websocket/index.ts","./src/websocket/lambda-channel-handler.ts","./src/websocket/lambda-eventhub-service.ts","./src/websocket/utils.ts","./src/websocket/websocket-connect.ts","./src/websocket/websocket-disconnect.ts","./src/websocket/websocket-message.ts","./src/websocket/websocket-types.ts"],"version":"6.0.3"}