@pikku/core 0.11.2 → 0.12.0

package/src/wirings/http/http-routes.test.ts

@@ -0,0 +1,322 @@
+import { test, describe, beforeEach, afterEach } from 'node:test'
+import * as assert from 'assert'
+import { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { addFunction } from '../../function/function-runner.js'
+import { httpRouter } from './routers/http-router.js'
+import { CorePikkuMiddleware } from '../../types/core.types.js'
+
+// Mock function for testing
+const mockFunc = async () => ({ success: true })
+
+// Mock middleware
+const mockMiddleware: CorePikkuMiddleware = async (_services, _wire, next) => {
+  await next()
+}
+
+// Helper to set up function metadata for routes
+const setupFunctionMeta = (
+  routes: Array<{ method: string; route: string }>
+) => {
+  const meta: Record<string, Record<string, any>> = {
+    get: {},
+    post: {},
+    delete: {},
+    patch: {},
+    head: {},
+    put: {},
+    options: {},
+  }
+
+  for (const { method, route } of routes) {
+    meta[method][route] = {
+      pikkuFuncId: `func_${route.replace(/[^a-z0-9]/gi, '_')}`,
+      route,
+      method,
+    }
+  }
+
+  pikkuState(null, 'http', 'meta', meta)
+
+  for (const { method, route } of routes) {
+    const funcName = `func_${route.replace(/[^a-z0-9]/gi, '_')}`
+    pikkuState(null, 'function', 'meta', {
+      [funcName]: {
+        pikkuFuncId: funcName,
+        services: [],
+      },
+    } as any)
+    addFunction(funcName, { func: mockFunc })
+  }
+}
+
+describe('defineHTTPRoutes', () => {
+  test('should accept routes directly', () => {
+    const routes = defineHTTPRoutes({
+      list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      get: { method: 'get', route: '/todos/:id', func: { func: mockFunc } },
+    })
+
+    assert.ok(routes.routes.list)
+    assert.ok(routes.routes.get)
+    assert.strictEqual(routes.routes.list.method, 'get')
+    assert.strictEqual(routes.routes.list.route, '/todos')
+  })
+
+  test('should accept config with routes', () => {
+    const routes = defineHTTPRoutes({
+      auth: true,
+      tags: ['todos'],
+      routes: {
+        list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      },
+    })
+
+    assert.strictEqual(routes.auth, true)
+    assert.deepStrictEqual(routes.tags, ['todos'])
+    assert.ok(routes.routes.list)
+  })
+
+  test('should handle basePath in config', () => {
+    const routes = defineHTTPRoutes({
+      basePath: '/api',
+      routes: {
+        list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      },
+    })
+
+    assert.strictEqual(routes.basePath, '/api')
+  })
+})
+
+describe('wireHTTPRoutes', () => {
+  beforeEach(() => {
+    resetPikkuState()
+    httpRouter.reset()
+  })
+
+  afterEach(() => {
+    resetPikkuState()
+    httpRouter.reset()
+  })
+
+  test('should wire flat array of routes', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'post', route: '/todos' },
+    ])
+
+    wireHTTPRoutes({
+      routes: [
+        { method: 'get', route: '/todos', func: { func: mockFunc } },
+        { method: 'post', route: '/todos', func: { func: mockFunc } },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/todos'))
+    assert.ok(routes.get('post')?.has('/todos'))
+  })
+
+  test('should wire nested object routes', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'get', route: '/todos/:id' },
+      { method: 'post', route: '/auth/login' },
+    ])
+
+    wireHTTPRoutes({
+      routes: {
+        todos: {
+          list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+          get: {
+            method: 'get',
+            route: '/todos/:id',
+            func: { func: mockFunc },
+          },
+        },
+        auth: {
+          login: {
+            method: 'post',
+            route: '/auth/login',
+            func: { func: mockFunc },
+          },
+        },
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/todos'))
+    assert.ok(routes.get('get')?.has('/todos/:id'))
+    assert.ok(routes.get('post')?.has('/auth/login'))
+  })
+
+  test('should apply basePath to all routes', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/api/v1/todos' },
+      { method: 'post', route: '/api/v1/todos' },
+    ])
+
+    wireHTTPRoutes({
+      basePath: '/api/v1',
+      routes: [
+        { method: 'get', route: '/todos', func: { func: mockFunc } },
+        { method: 'post', route: '/todos', func: { func: mockFunc } },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/api/v1/todos'))
+    assert.ok(routes.get('post')?.has('/api/v1/todos'))
+  })
+
+  test('should merge tags from group config and route config', () => {
+    setupFunctionMeta([{ method: 'get', route: '/todos' }])
+
+    wireHTTPRoutes({
+      tags: ['api'],
+      routes: [
+        {
+          method: 'get',
+          route: '/todos',
+          func: { func: mockFunc },
+          tags: ['todos'],
+        },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const route = routes.get('get')?.get('/todos')
+    assert.deepStrictEqual(route?.tags, ['api', 'todos'])
+  })
+
+  test('should merge middleware from group config and route config', () => {
+    setupFunctionMeta([{ method: 'get', route: '/todos' }])
+
+    const groupMiddleware: CorePikkuMiddleware = async (_s, _w, next) => {
+      await next()
+    }
+    const routeMiddleware: CorePikkuMiddleware = async (_s, _w, next) => {
+      await next()
+    }
+
+    wireHTTPRoutes({
+      middleware: [groupMiddleware],
+      routes: [
+        {
+          method: 'get',
+          route: '/todos',
+          func: { func: mockFunc },
+          middleware: [routeMiddleware],
+        },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const route = routes.get('get')?.get('/todos')
+    assert.strictEqual(route?.middleware?.length, 2)
+  })
+
+  test('should allow route auth to override group auth', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'post', route: '/auth/login' },
+    ])
+
+    wireHTTPRoutes({
+      auth: true,
+      routes: [
+        { method: 'get', route: '/todos', func: { func: mockFunc } },
+        {
+          method: 'post',
+          route: '/auth/login',
+          func: { func: mockFunc },
+          auth: false,
+        },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const todosRoute = routes.get('get')?.get('/todos')
+    const loginRoute = routes.get('post')?.get('/auth/login')
+
+    assert.strictEqual(todosRoute?.auth, true)
+    assert.strictEqual(loginRoute?.auth, false)
+  })
+
+  test('should wire routes from defineHTTPRoutes contracts', () => {
+    const todosRoutes = defineHTTPRoutes({
+      tags: ['todos'],
+      routes: {
+        list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      },
+    })
+
+    setupFunctionMeta([{ method: 'get', route: '/api/todos' }])
+
+    wireHTTPRoutes({
+      basePath: '/api',
+      tags: ['api'],
+      routes: {
+        todos: todosRoutes,
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const route = routes.get('get')?.get('/api/todos')
+    assert.ok(route)
+    assert.deepStrictEqual(route?.tags, ['api', 'todos'])
+  })
+
+  test('should cascade basePath from multiple levels', () => {
+    const todosRoutes = defineHTTPRoutes({
+      basePath: '/todos',
+      routes: {
+        list: { method: 'get', route: '', func: { func: mockFunc } },
+        get: { method: 'get', route: '/:id', func: { func: mockFunc } },
+      },
+    })
+
+    setupFunctionMeta([
+      { method: 'get', route: '/api/v1/todos' },
+      { method: 'get', route: '/api/v1/todos/:id' },
+    ])
+
+    wireHTTPRoutes({
+      basePath: '/api/v1',
+      routes: {
+        todos: todosRoutes,
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/api/v1/todos'))
+    assert.ok(routes.get('get')?.has('/api/v1/todos/:id'))
+  })
+
+  test('should handle deeply nested route maps', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'get', route: '/todos/:id' },
+    ])
+
+    wireHTTPRoutes({
+      routes: {
+        level1: {
+          level2: {
+            list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+            get: {
+              method: 'get',
+              route: '/todos/:id',
+              func: { func: mockFunc },
+            },
+          },
+        },
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/todos'))
+    assert.ok(routes.get('get')?.has('/todos/:id'))
+  })
+})

package/src/wirings/http/http-routes.ts

@@ -0,0 +1,198 @@
+import type {
+  HTTPRouteConfig,
+  HTTPRouteMap,
+  HTTPRouteContract,
+  HTTPRoutesGroupConfig,
+  WireHTTPRoutesConfig,
+} from './http.types.js'
+import { wireHTTP } from './http-runner.js'
+
+/**
+ * Type-safe helper for defining route contracts that can be composed.
+ * Supports optional group-level config that cascades to all routes.
+ *
+ * @example
+ * ```typescript
+ * // Simple routes without group config
+ * export const todosRoutes = defineHTTPRoutes({
+ *   list: { method: 'get', route: '/todos', func: listTodos },
+ *   get: { method: 'get', route: '/todos/:id', func: getTodo },
+ * })
+ *
+ * // Routes with group-level config
+ * export const todosRoutes = defineHTTPRoutes({
+ *   auth: true,
+ *   tags: ['todos'],
+ *   routes: {
+ *     list: { method: 'get', route: '/todos', func: listTodos },
+ *     get: { method: 'get', route: '/todos/:id', func: getTodo },
+ *   }
+ * })
+ * ```
+ */
+export function defineHTTPRoutes<T extends HTTPRouteMap>(
+  routes: T
+): HTTPRouteContract<T>
+export function defineHTTPRoutes<T extends HTTPRouteMap>(
+  config: HTTPRoutesGroupConfig & { routes: T }
+): HTTPRouteContract<T>
+export function defineHTTPRoutes<T extends HTTPRouteMap>(
+  configOrRoutes: T | (HTTPRoutesGroupConfig & { routes: T })
+): HTTPRouteContract<T> {
+  // If it has a 'routes' property and contains a map (not a route config), it's config + routes
+  if (
+    'routes' in configOrRoutes &&
+    typeof configOrRoutes.routes === 'object' &&
+    !isRouteConfig(configOrRoutes.routes)
+  ) {
+    return configOrRoutes as HTTPRouteContract<T>
+  }
+  // Otherwise it's just routes
+  return { routes: configOrRoutes as T }
+}
+
+/**
+ * Wires multiple HTTP routes from a nested map or array configuration.
+ * Inspired by ts-rest's contract pattern, provides a single place to wire an entire API.
+ *
+ * @example
+ * ```typescript
+ * // Nested object format
+ * wireHTTPRoutes({
+ *   basePath: '/api/v1',
+ *   tags: ['api'],
+ *   routes: {
+ *     todos: {
+ *       list: { method: 'get', route: '/todos', func: listTodos },
+ *       get: { method: 'get', route: '/todos/:id', func: getTodo },
+ *     },
+ *     auth: {
+ *       login: { method: 'post', route: '/auth/login', func: login, auth: false },
+ *     },
+ *   },
+ * })
+ *
+ * // Flat array format
+ * wireHTTPRoutes({
+ *   basePath: '/api',
+ *   routes: [
+ *     { method: 'get', route: '/todos', func: listTodos },
+ *     { method: 'post', route: '/todos', func: createTodo },
+ *   ],
+ * })
+ *
+ * // Composing route contracts
+ * wireHTTPRoutes({
+ *   basePath: '/api/v1',
+ *   routes: {
+ *     todos: todosRoutes,  // from defineHTTPRoutes()
+ *     auth: authRoutes,    // from defineHTTPRoutes()
+ *   },
+ * })
+ * ```
+ */
+export const wireHTTPRoutes = (config: WireHTTPRoutesConfig): void => {
+  const { routes, ...groupConfig } = config
+
+  if (Array.isArray(routes)) {
+    routes.forEach((route) => registerRoute(route, groupConfig))
+  } else {
+    processRouteMap(routes, groupConfig)
+  }
+}
+
+/**
+ * Recursively processes a route map, handling nested maps and contracts
+ */
+function processRouteMap(
+  map: HTTPRouteMap,
+  parentConfig: HTTPRoutesGroupConfig
+): void {
+  for (const [_key, value] of Object.entries(map)) {
+    if (isRouteConfig(value)) {
+      registerRoute(value, parentConfig)
+    } else if (isRouteContract(value)) {
+      // Merge parent config with contract config, then process routes
+      const mergedConfig = mergeGroupConfig(parentConfig, value)
+      processRouteMap(value.routes, mergedConfig)
+    } else {
+      // Nested map without config
+      processRouteMap(value as HTTPRouteMap, parentConfig)
+    }
+  }
+}
+
+/**
+ * Merge group configs with proper cascading behavior:
+ * - basePath: Concatenates
+ * - tags: Merges (parent + child)
+ * - middleware: Merges (parent runs first)
+ * - auth: Inner overrides outer
+ * - permissions: Inner overrides outer
+ */
+function mergeGroupConfig(
+  parent: HTTPRoutesGroupConfig,
+  child: HTTPRoutesGroupConfig
+): HTTPRoutesGroupConfig {
+  return {
+    basePath: (parent.basePath || '') + (child.basePath || ''),
+    tags: [...(parent.tags || []), ...(child.tags || [])],
+    middleware: [...(parent.middleware || []), ...(child.middleware || [])],
+    auth: child.auth ?? parent.auth,
+    permissions: child.permissions ?? parent.permissions,
+  }
+}
+
+/**
+ * Registers a single route by calling wireHTTP with merged configuration
+ */
+function registerRoute(
+  route: HTTPRouteConfig,
+  groupConfig: HTTPRoutesGroupConfig
+): void {
+  const fullRoute = (groupConfig.basePath || '') + route.route
+
+  wireHTTP({
+    method: route.method,
+    route: fullRoute,
+    func: route.func,
+    auth: route.auth ?? groupConfig.auth,
+    tags: [...(groupConfig.tags || []), ...(route.tags || [])],
+    middleware: [
+      ...(groupConfig.middleware || []),
+      ...(route.middleware || []),
+    ],
+    permissions: route.permissions ?? groupConfig.permissions,
+    contentType: route.contentType,
+    timeout: route.timeout,
+    headers: route.headers,
+    docs: route.docs,
+    sse: route.sse,
+  } as any)
+}
+
+/**
+ * Type guard to check if a value is an individual route config
+ */
+function isRouteConfig(value: unknown): value is HTTPRouteConfig {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'method' in value &&
+    'func' in value &&
+    'route' in value
+  )
+}
+
+/**
+ * Type guard to check if a value is a route contract (has routes property but is not a route config)
+ */
+function isRouteContract(value: unknown): value is HTTPRouteContract {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'routes' in value &&
+    !('method' in value) &&
+    !('func' in value)
+  )
+}

package/src/wirings/http/http-runner.test.ts

@@ -12,21 +12,21 @@ import { addFunction } from '../../function/function-runner.js'
 import { httpRouter } from './routers/http-router.js'
 
 const sessionMiddleware: CorePikkuMiddleware = async (services, wire, next) => {
-  wire.session?.set({ userId: 'test' } as any)
+  wire.setSession?.({ userId: 'test' } as any)
   await next()
 }
 
 const setHTTPFunctionMap = (func: any) => {
   pikkuState(null, 'function', 'meta', {
     pikku_func_name: {
-      pikkuFuncName: 'pikku_func_name',
+      pikkuFuncId: 'pikku_func_name',
       services: ['userSession'],
     },
   } as any)
   pikkuState(null, 'http', 'meta', {
     get: {
       test: {
-        pikkuFuncName: 'pikku_func_name',
+        pikkuFuncId: 'pikku_func_name',
         route: 'test',
         method: 'get',
       },

package/src/wirings/http/http-runner.ts

@@ -22,13 +22,16 @@ import {
   PikkuWire,
   PikkuWiringTypes,
 } from '../../types/core.types.js'
-import { NotFoundError } from '../../errors/errors.js'
+import { NotFoundError, PikkuMissingMetaError } from '../../errors/errors.js'
 import {
   closeWireServices,
   createWeakUID,
   isSerializable,
 } from '../../utils.js'
-import { PikkuSessionService } from '../../services/user-session-service.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../services/user-session-service.js'
 import { handleHTTPError } from '../../handle-error.js'
 import { pikkuState } from '../../pikku-state.js'
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
@@ -36,7 +39,24 @@ import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
 import { PikkuChannel } from '../channel/channel.types.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { httpRouter } from './routers/http-router.js'
-import { startWorkflowByHttpWire } from '../workflow/workflow-utils.js'
+import { validateSchema } from '../../schema.js'
+
+/**
+ * Extract headers from a PikkuHTTPRequest based on the schema keys
+ */
+function extractHeadersFromRequest(
+  request: PikkuHTTPRequest,
+  headerKeys: string[]
+): Record<string, string | string[] | undefined> {
+  const headers: Record<string, string | string[] | undefined> = {}
+  for (const headerName of headerKeys) {
+    const value = request.header(headerName)
+    if (value !== null) {
+      headers[headerName] = value
+    }
+  }
+  return headers
+}
 
 /**
  * Registers HTTP middleware for a specific route pattern.
@@ -157,10 +177,12 @@ export const wireHTTP = <
   const httpMeta = pikkuState(null, 'http', 'meta')
   const routeMeta = httpMeta[httpWiring.method][httpWiring.route]
   if (!routeMeta) {
-    throw new Error('Route metadata not found')
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for HTTP route '${httpWiring.method.toUpperCase()} ${httpWiring.route}'`
+    )
   }
   if (httpWiring.func) {
-    addFunction(routeMeta.pikkuFuncName, httpWiring.func)
+    addFunction(routeMeta.pikkuFuncId, httpWiring.func)
   }
   const routes = pikkuState(null, 'http', 'routes')
   if (!routes.has(httpWiring.method)) {
@@ -281,6 +303,20 @@ const executeRoute = async (
   // Attach URL parameters to the request object
   http?.request?.setParams(params)
 
+  // Validate request headers if schema is defined
+  if (meta.headersSchemaName && http.request && singletonServices.schema) {
+    const headerKeys = singletonServices.schema.getSchemaKeys(
+      meta.headersSchemaName
+    )
+    const rawHeaders = extractHeadersFromRequest(http.request, headerKeys)
+    await validateSchema(
+      singletonServices.logger,
+      singletonServices.schema,
+      meta.headersSchemaName,
+      rawHeaders
+    )
+  }
+
   const requiresSession = route.auth !== false
   let wireServices: any
   let result: any
@@ -294,7 +330,13 @@ const executeRoute = async (
     throw new Error("Can't skip trying to get user session if auth is required")
   }
 
-  const data = () => http.request!.data()
+  let cachedData: unknown | undefined
+  const data = async () => {
+    if (cachedData === undefined) {
+      cachedData = await http.request!.data()
+    }
+    return cachedData
+  }
   let channel: PikkuChannel<unknown, unknown> | undefined
 
   if (matchedRoute.route.sse) {
@@ -324,24 +366,16 @@ const executeRoute = async (
     }
   }
 
-  const wire: PikkuWire = { http, channel, session: userSession }
-
-  if (matchedRoute.meta.workflow === true) {
-    await startWorkflowByHttpWire(
-      singletonServices,
-      createWireServices,
-      matchedRoute,
-      wire
-    )
-    return wireServices
-      ? { wireServices, result: http.response }
-      : { result: http.response }
+  const wire: PikkuWire = {
+    http,
+    channel,
+    ...createMiddlewareSessionWireProps(userSession),
   }
 
   result = await runPikkuFunc(
     'http',
     `${meta.method}:${meta.route}`,
-    meta.pikkuFuncName,
+    meta.pikkuFuncId,
     {
       singletonServices,
       createWireServices,
@@ -354,20 +388,20 @@ const executeRoute = async (
       coerceDataFromSchema: options.coerceDataFromSchema,
       tags: route.tags,
       wire,
+      sessionService: userSession,
     }
   )
-
-  // Respond with either a binary or JSON response based on configuration
-  if (route.returnsJSON === false) {
-    http?.response?.arrayBuffer(result)
-  } else {
-    http?.response?.json(result)
+  if (!matchedRoute.route.sse) {
+    if (result === undefined || result === null) {
+      http?.response?.status(204)
+    } else if (route.returnsJSON === false) {
+      http?.response?.arrayBuffer(result)
+    } else {
+      http?.response?.status(200)
+      http?.response?.json(result)
+    }
   }
 
-  http?.response?.status(200)
-  // TODO: Evaluate if the response stream should be explicitly ended.
-  // http?.response?.end()
-
   return wireServices ? { result, wireServices } : { result }
 }