@pikku/core 0.12.4 → 0.12.5

package/src/wirings/channel/serverless/serverless-channel-runner.ts

@@ -0,0 +1,289 @@
+import type { PikkuWire, WireServices } from '../../../types/core.types.js'
+import { closeWireServices } from '../../../utils.js'
+import { processMessageHandlers } from '../channel-handler.js'
+import { openChannel } from '../channel-runner.js'
+import type {
+  CoreChannel,
+  RunChannelOptions,
+  RunChannelParams,
+  PikkuChannelHandlerFactory,
+} from '../channel.types.js'
+import { createHTTPWire } from '../../http/http-runner.js'
+import type { ChannelStore } from '../channel-store.js'
+import { handleHTTPError } from '../../../handle-error.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../../services/user-session-service.js'
+import {
+  getSingletonServices,
+  getCreateWireServices,
+  pikkuState,
+} from '../../../pikku-state.js'
+import { PikkuFetchHTTPRequest } from '../../http/pikku-fetch-http-request.js'
+import type { PikkuHTTP } from '../../http/http.types.js'
+import { runChannelLifecycleWithMiddleware } from '../channel-common.js'
+
+export interface RunServerlessChannelParams<ChannelData>
+  extends RunChannelParams<ChannelData> {
+  channelStore: ChannelStore
+  channelHandlerFactory: PikkuChannelHandlerFactory
+  channelObject?: unknown
+}
+
+const getVariablesForChannel = ({
+  channelId,
+  channelName,
+  channelHandlerFactory,
+  openingData,
+}: {
+  channelId: string
+  channelName: string
+  channelHandlerFactory: PikkuChannelHandlerFactory
+  openingData?: unknown
+}) => {
+  const channels = pikkuState(null, 'channel', 'channels')
+  const channelConfig = channels.get(channelName)
+  const channelsMeta = pikkuState(null, 'channel', 'meta')
+  const meta = channelsMeta[channelName]
+  if (!channelConfig) {
+    throw new Error(`Channel not found: ${channelName}`)
+  }
+  if (!meta) {
+    throw new Error(`Channel meta not found: ${channelName}`)
+  }
+  const channelHandler = channelHandlerFactory(
+    channelId,
+    channelConfig.name,
+    openingData
+  )
+  return {
+    channelConfig,
+    channelHandler,
+    channel: channelHandler.getChannel(),
+    meta,
+  }
+}
+
+export const runChannelConnect = async ({
+  channelId,
+  channelObject,
+  request,
+  response,
+  route,
+  channelStore,
+  channelHandlerFactory,
+  coerceDataFromSchema = true,
+  logWarningsForStatusCodes = [],
+  respondWith404 = true,
+  bubbleErrors = false,
+}: Pick<CoreChannel<unknown, any>, 'route'> &
+  RunChannelOptions &
+  RunServerlessChannelParams<unknown>) => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
+  let wireServices: WireServices | undefined
+
+  let http: PikkuHTTP | undefined
+  if (request instanceof Request) {
+    http = createHTTPWire(new PikkuFetchHTTPRequest(request), response)
+  }
+
+  const userSession = new PikkuSessionService(channelStore, channelId)
+
+  const { channelConfig, openingData, meta } = await openChannel({
+    channelId,
+    request,
+    route,
+    coerceDataFromSchema,
+    userSession,
+  })
+
+  try {
+    await channelStore.addChannel({
+      channelId,
+      channelName: channelConfig.name,
+      openingData,
+      channelObject,
+    })
+    const { channel } = getVariablesForChannel({
+      channelId,
+      channelHandlerFactory,
+      channelName: channelConfig.name,
+    })
+
+    const wire: PikkuWire = {
+      channel,
+      ...createMiddlewareSessionWireProps(userSession),
+    }
+
+    if (createWireServices) {
+      wireServices = await createWireServices(singletonServices, wire)
+    }
+
+    const services = {
+      ...singletonServices,
+      ...wireServices,
+    }
+
+    if (channelConfig.onConnect && meta.connect) {
+      await runChannelLifecycleWithMiddleware({
+        channelConfig,
+        meta: meta.connect,
+        lifecycleConfig: channelConfig.onConnect,
+        lifecycleType: 'connect',
+        services,
+        channel,
+        data: openingData,
+        channelMiddlewareMeta: meta.channelMiddleware,
+      })
+    }
+    http?.response?.status(101)
+  } catch (e: any) {
+    handleHTTPError(
+      e,
+      http,
+      channelId,
+      singletonServices.logger,
+      logWarningsForStatusCodes,
+      respondWith404,
+      bubbleErrors
+    )
+  } finally {
+    if (wireServices) {
+      await closeWireServices(singletonServices.logger, wireServices)
+    }
+  }
+}
+
+export const runChannelDisconnect = async ({
+  channelId,
+  channelStore,
+  channelHandlerFactory,
+}: RunServerlessChannelParams<unknown>): Promise<void> => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
+  let wireServices: WireServices | undefined
+
+  // Try to get channel from store. In serverless environments (especially with
+  // serverless-offline or worker threads), disconnect can be called multiple times
+  // or after the channel has already been cleaned up. If channel doesn't exist,
+  // there's nothing to disconnect, so we can return early.
+  let channelData
+  try {
+    channelData = await channelStore.getChannelAndSession(channelId)
+  } catch {
+    singletonServices.logger.info(
+      `Channel ${channelId} not found during disconnect - already cleaned up`
+    )
+    return
+  }
+
+  const { openingData, channelName, session } = channelData
+  const { channel, channelConfig, meta } = getVariablesForChannel({
+    channelId,
+    channelHandlerFactory,
+    openingData,
+    channelName,
+  })
+
+  const userSession = new PikkuSessionService(channelStore, channelId)
+  userSession.setInitial(session)
+  const wire: PikkuWire = {
+    channel,
+    ...createMiddlewareSessionWireProps(userSession),
+  }
+
+  if (createWireServices) {
+    wireServices = await createWireServices(singletonServices, wire)
+  }
+
+  const services = {
+    ...singletonServices,
+    ...wireServices,
+  }
+
+  if (channelConfig.onDisconnect && meta.disconnect) {
+    try {
+      await runChannelLifecycleWithMiddleware({
+        channelConfig,
+        meta: meta.disconnect,
+        lifecycleConfig: channelConfig.onDisconnect,
+        lifecycleType: 'disconnect',
+        services,
+        channel,
+        channelMiddlewareMeta: meta.channelMiddleware,
+      })
+    } catch (e: any) {
+      singletonServices.logger.error(
+        `Error handling onDisconnect: ${e.message || e}`
+      )
+    }
+  }
+  await channelStore.removeChannels([channel.channelId])
+  if (wireServices) {
+    await closeWireServices(singletonServices.logger, wireServices)
+  }
+}
+
+export const runChannelMessage = async (
+  {
+    channelId,
+    channelStore,
+    channelHandlerFactory,
+  }: RunServerlessChannelParams<unknown>,
+  data: unknown
+): Promise<unknown> => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
+  let wireServices: WireServices | undefined
+  const { openingData, channelName, session } =
+    await channelStore.getChannelAndSession(channelId)
+
+  const { channel, channelHandler, channelConfig } = getVariablesForChannel({
+    channelId,
+    channelHandlerFactory,
+    openingData,
+    channelName,
+  })
+
+  const userSession = new PikkuSessionService(channelStore, channelId)
+  userSession.setInitial(session)
+  const wire: PikkuWire = {
+    channel,
+    ...createMiddlewareSessionWireProps(userSession),
+  }
+
+  if (createWireServices) {
+    wireServices = await createWireServices(singletonServices, wire)
+  }
+
+  const services = {
+    ...singletonServices,
+    ...wireServices,
+  }
+
+  let response: unknown
+  try {
+    const { onMessage } = processMessageHandlers(
+      services,
+      channelConfig,
+      channelHandler,
+      userSession
+    )
+    response = await onMessage(data)
+  } catch (e: any) {
+    singletonServices.logger.error(
+      `Error processing message: ${e.message || e}`
+    )
+    return {
+      error: e.message || 'Unknown error',
+      errorName: e.constructor?.name,
+    }
+  } finally {
+    if (wireServices) {
+      await closeWireServices(singletonServices.logger, wireServices)
+    }
+  }
+  return response
+}

package/src/wirings/cli/channel/cli-channel-runner.ts

@@ -0,0 +1,136 @@
+import { pikkuState } from '../../../pikku-state.js'
+import type { CorePikkuCLIRender, CLIMeta } from '../cli.types.js'
+import { generateCommandHelp, parseCLIArguments } from '../command-parser.js'
+
+/**
+ * Default JSON renderer for CLI output
+ */
+const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
+  console.log(JSON.stringify(data, null, 2))
+}
+
+/**
+ * Execute a CLI program via WebSocket channel
+ * This is the main entry point for CLI-over-Channel clients
+ */
+export async function executeCLIViaChannel({
+  programName,
+  pikkuWS,
+  args = process.argv.slice(2),
+  renderers = {},
+  defaultRenderer,
+}: {
+  programName: string
+  pikkuWS: any // CorePikkuWebsocket instance
+  args?: string[]
+  renderers?: Record<string, CorePikkuCLIRender<any>>
+  defaultRenderer?: CorePikkuCLIRender<any>
+}): Promise<void> {
+  // Get CLI metadata from state
+  const cliMeta = pikkuState(null, 'cli', 'meta')
+  if (!cliMeta || !('programs' in cliMeta)) {
+    throw new Error(
+      '[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/docs/pikku-cli/errors/pku342 for more information.'
+    )
+  }
+  const allCLIMeta = cliMeta as CLIMeta
+  const programMeta = allCLIMeta.programs[programName]
+
+  if (!programMeta) {
+    console.error(`Error: CLI program "${programName}" not found`)
+    process.exit(1)
+  }
+
+  // Parse arguments for this specific program
+  const parsed = parseCLIArguments(args, programName, allCLIMeta)
+
+  // Handle help (check after parsing to support subcommand help)
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    const helpText = generateCommandHelp(
+      programName,
+      allCLIMeta,
+      parsed.commandPath
+    )
+    console.log(helpText)
+    return
+  }
+
+  if (parsed.errors.length > 0) {
+    // Check if any error is about an unknown command
+    const hasUnknownCommand = parsed.errors.some(
+      (error) =>
+        error.startsWith('Unknown command:') ||
+        error.startsWith('Command not found:')
+    )
+
+    if (hasUnknownCommand) {
+      // Show help instead of error for unknown commands
+      const helpText = generateCommandHelp(
+        programName,
+        allCLIMeta,
+        parsed.commandPath
+      )
+      console.log(helpText)
+      process.exit(1)
+    } else {
+      // Show errors for other types of errors
+      console.error('Errors:')
+      parsed.errors.forEach((error) => console.error(`  ${error}`))
+      process.exit(1)
+    }
+  }
+
+  // Merge positionals and options into single data object
+  const data = { ...parsed.positionals, ...parsed.options }
+
+  // Get the renderer for this command
+  const commandId = parsed.commandPath.join('.')
+  const renderer =
+    renderers[commandId] || defaultRenderer || defaultJSONRenderer
+
+  return new Promise((resolve, reject) => {
+    // Subscribe to responses for this command
+    const commandRoute = pikkuWS.getRoute('command')
+
+    const responseHandler = (response: any) => {
+      // Check if this is a control message
+      if (
+        response?.action === 'cli-control' &&
+        response?.event === 'complete'
+      ) {
+        // Server signals command is complete, close the connection client-side
+        commandRoute.unsubscribe(commandId, responseHandler)
+        pikkuWS.ws.close()
+        resolve(undefined)
+        return
+      }
+
+      // Call renderer for any output
+      renderer(null as any, response, undefined)
+    }
+
+    commandRoute.subscribe(commandId, responseHandler)
+
+    // Handle connection close
+    pikkuWS.ws.addEventListener('close', () => {
+      commandRoute.unsubscribe(commandId, responseHandler)
+      resolve(undefined)
+    })
+
+    pikkuWS.ws.addEventListener('error', (error: any) => {
+      commandRoute.unsubscribe(commandId, responseHandler)
+      reject(error)
+    })
+
+    // Send the command once connected
+    if (pikkuWS.ws.readyState === 1) {
+      // Already open
+      commandRoute.send(commandId, data)
+    } else {
+      // Wait for open
+      pikkuWS.ws.addEventListener('open', () => {
+        commandRoute.send(commandId, data)
+      })
+    }
+  })
+}

package/src/wirings/cli/channel/index.ts

@@ -0,0 +1 @@
+export { executeCLIViaChannel } from './cli-channel-runner.js'