@pikku/core 0.11.1 → 0.12.0

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('function', 'meta', {
+  pikkuState(null, 'function', 'meta', {
     pikku_func_name: {
-      pikkuFuncName: 'pikku_func_name',
+      pikkuFuncId: 'pikku_func_name',
       services: ['userSession'],
     },
   } as any)
-  pikkuState('http', 'meta', {
+  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,6 +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 { 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.
@@ -68,9 +89,10 @@ import { httpRouter } from './routers/http-router.js'
  */
 export const addHTTPMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
   pattern: string,
-  middleware: CorePikkuMiddlewareGroup
+  middleware: CorePikkuMiddlewareGroup,
+  packageName: string | null = null
 ): CorePikkuMiddlewareGroup => {
-  const httpGroups = pikkuState('middleware', 'httpGroup')
+  const httpGroups = pikkuState(packageName, 'middleware', 'httpGroup')
   httpGroups[pattern] = middleware
   return middleware
 }
@@ -106,9 +128,10 @@ export const addHTTPMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
  */
 export const addHTTPPermission = <PikkuPermission extends CorePikkuPermission>(
   pattern: string,
-  permissions: CorePermissionGroup | CorePikkuPermission[]
+  permissions: CorePermissionGroup | CorePikkuPermission[],
+  packageName: string | null = null
 ): CorePermissionGroup | CorePikkuPermission[] => {
-  const httpGroups = pikkuState('permissions', 'httpGroup')
+  const httpGroups = pikkuState(packageName, 'permissions', 'httpGroup')
   httpGroups[pattern] = permissions
   return permissions
 }
@@ -151,17 +174,21 @@ export const wireHTTP = <
     PikkuMiddleware
   >
 ) => {
-  const httpMeta = pikkuState('http', 'meta')
+  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.pikkuFuncId, httpWiring.func)
   }
-  addFunction(routeMeta.pikkuFuncName, httpWiring.func)
-  const routes = pikkuState('http', 'routes')
+  const routes = pikkuState(null, 'http', 'routes')
   if (!routes.has(httpWiring.method)) {
     routes.set(httpWiring.method, new Map())
   }
-  pikkuState('http', 'routes')
+  pikkuState(null, 'http', 'routes')
     .get(httpWiring.method)
     ?.set(httpWiring.route, httpWiring as any)
 }
@@ -184,10 +211,10 @@ const getMatchingRoute = (requestType: string, requestPath: string) => {
   )
 
   if (matchedPath) {
-    const route = pikkuState('http', 'routes')
+    const route = pikkuState(null, 'http', 'routes')
       .get(requestType.toLowerCase() as HTTPMethod)!
       .get(matchedPath.route)!
-    const meta = pikkuState('http', 'meta')[
+    const meta = pikkuState(null, 'http', 'meta')[
       requestType.toLowerCase() as PikkuWiringTypes
     ][route.route]
 
@@ -273,13 +300,27 @@ const executeRoute = async (
   const { singletonServices, createWireServices, skipUserSession, requestId } =
     services
 
+  // 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
 
-  // Attach URL parameters to the request object
-  http?.request?.setParams(params)
-
   singletonServices.logger.info(
     `Matched route: ${route.route} | method: ${route.method.toUpperCase()} | auth: ${requiresSession.toString()}`
   )
@@ -289,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) {
@@ -319,12 +366,16 @@ const executeRoute = async (
     }
   }
 
-  const wire: PikkuWire = { http, channel, session: userSession }
+  const wire: PikkuWire = {
+    http,
+    channel,
+    ...createMiddlewareSessionWireProps(userSession),
+  }
 
   result = await runPikkuFunc(
     'http',
     `${meta.method}:${meta.route}`,
-    meta.pikkuFuncName,
+    meta.pikkuFuncId,
     {
       singletonServices,
       createWireServices,
@@ -337,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 }
 }
 

package/src/wirings/http/http.types.ts

@@ -1,5 +1,6 @@
 import type { SerializeOptions } from 'cookie'
-import type { PikkuError } from '../../errors/error-handler.js'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import { PikkuError } from '../../errors/error-handler.js'
 import type {
   CoreServices,
   CoreSingletonServices,
@@ -44,7 +45,7 @@ export type RunHTTPWiringOptions = Partial<{
 
 export type RunHTTPWiringParams = {
   singletonServices: CoreSingletonServices
-  createWireServices: CreateWireServices<
+  createWireServices?: CreateWireServices<
     CoreSingletonServices,
     CoreServices<CoreSingletonServices>,
     CoreUserSession
@@ -53,7 +54,7 @@ export type RunHTTPWiringParams = {
 
 /**
  * Represents the HTTP methods supported for API HTTP wirings.
-t */
+ */
 export type HTTPMethod =
   | 'post'
   | 'get'
@@ -64,21 +65,41 @@ export type HTTPMethod =
   | 'options'
 
 /**
- * Represents an API HTTP wiring without a function, including metadata such as content type, route, and timeout settings.
+ * Header schema type for request header validation.
+ * Uses Standard Schema interface - works with Zod, Valibot, ArkType, Effect Schema, etc.
  */
-export type CoreHTTPFunction = {
+export type HTTPHeadersSchema = StandardSchemaV1<
+  Record<string, string | string[] | undefined>
+>
+
+/**
+ * Documentation config for OpenAPI generation
+ */
+export type HTTPRouteDocsConfig = {
+  description?: string
+  response?: string
+  errors?: Array<typeof PikkuError>
+  tags?: string[]
+}
+
+/**
+ * Common HTTP route configuration shared between wireHTTP and wireHTTPRoutes
+ */
+export type HTTPRouteBaseConfig = {
   contentType?: 'xml' | 'json'
+  timeout?: number
+  tags?: string[]
+  headers?: HTTPHeadersSchema
+  docs?: HTTPRouteDocsConfig
+}
+
+/**
+ * Represents an API HTTP wiring without a function, including metadata such as content type, route, and timeout settings.
+ */
+export type CoreHTTPFunction = HTTPRouteBaseConfig & {
   route: string
   eventChannel?: false
   returnsJSON?: false
-  timeout?: number
-  tags?: string[]
-  docs?: Partial<{
-    description: string
-    response: string
-    errors: Array<typeof PikkuError>
-    tags: string[]
-  }>
 }
 /**
  * Represents a http wire within Pikku, including a request and response.
@@ -121,12 +142,14 @@ export type CoreHTTPFunctionWiring<
     In,
     Out,
     any,
+    any,
     any
   > = CorePikkuFunction<In, Out>,
   PikkuFunctionSessionless extends CorePikkuFunctionSessionless<
     In,
     Out,
     any,
+    any,
     any
   > = CorePikkuFunctionSessionless<In, Out>,
   PikkuPermission extends CorePikkuPermission<
@@ -149,7 +172,6 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
-      tags?: string[]
       middleware?: PikkuMiddleware[]
       sse?: undefined
     })
@@ -163,7 +185,6 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: undefined
       auth?: false
-      tags?: string[]
       middleware?: PikkuMiddleware[]
       sse?: undefined
     })
@@ -177,9 +198,8 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
-      sse?: boolean
-      tags?: string[]
       middleware?: PikkuMiddleware[]
+      sse?: boolean
     })
   | (CoreHTTPFunction & {
       route: R
@@ -191,9 +211,8 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: undefined
       auth?: false
-      sse?: boolean
-      tags?: string[]
       middleware?: PikkuMiddleware[]
+      sse?: boolean
     })
   | (CoreHTTPFunction & {
       route: R
@@ -205,9 +224,8 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
-      query?: Array<keyof In>
-      tags?: string[]
       middleware?: PikkuMiddleware[]
+      query?: Array<keyof In>
       sse?: undefined
     })
   | (CoreHTTPFunction & {
@@ -220,9 +238,8 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: undefined
       auth?: false
-      query?: Array<keyof In>
-      tags?: string[]
       middleware?: PikkuMiddleware[]
+      query?: Array<keyof In>
       sse?: undefined
     })
 
@@ -244,7 +261,9 @@ export type HTTPWiringMeta = CommonWireMeta & {
   params?: string[]
   query?: string[]
   inputTypes?: HTTPFunctionMetaInputTypes
+  headersSchemaName?: string
   sse?: true
+  groupBasePath?: string
 }
 export type HTTPWiringsMeta = Record<HTTPMethod, Record<string, HTTPWiringMeta>>
 
@@ -291,3 +310,82 @@ export interface PikkuHTTPResponse<Out = unknown> {
   close?: () => void
   setMode?: (mode: 'stream') => void
 }
+
+/**
+ * Single route configuration - supports all wireHTTP options
+ */
+export type HTTPRouteConfig<
+  PikkuFunction extends
+    | CorePikkuFunction<any, any, any, any, any>
+    | CorePikkuFunctionSessionless<any, any, any, any, any> =
+    | CorePikkuFunction<any, any, any, any, any>
+    | CorePikkuFunctionSessionless<any, any, any, any, any>,
+  PikkuPermission extends CorePikkuPermission<
+    any,
+    any,
+    any
+  > = CorePikkuPermission<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+> = HTTPRouteBaseConfig & {
+  // Required
+  method: HTTPMethod
+  route: string
+  func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>
+
+  // Auth & permissions
+  auth?: boolean
+  permissions?: CorePermissionGroup<PikkuPermission>
+
+  // Middleware
+  middleware?: PikkuMiddleware[]
+
+  // SSE support
+  sse?: boolean
+}
+
+/**
+ * Group-level configuration applied to all routes
+ */
+export type HTTPRoutesGroupConfig<
+  PikkuPermission extends CorePikkuPermission<
+    any,
+    any,
+    any
+  > = CorePikkuPermission<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+> = {
+  basePath?: string
+  tags?: string[]
+  auth?: boolean
+  middleware?: PikkuMiddleware[]
+  permissions?: CorePermissionGroup<PikkuPermission>
+}
+
+/**
+ * Nested route map - allows hierarchical organization
+ * Can contain individual routes, nested maps, or contracts with config
+ */
+export type HTTPRouteMap = {
+  [key: string]: HTTPRouteConfig | HTTPRouteMap | HTTPRouteContract
+}
+
+/**
+ * A route contract with optional group config (returned by defineRoutes)
+ */
+export type HTTPRouteContract<T extends HTTPRouteMap = HTTPRouteMap> =
+  HTTPRoutesGroupConfig & {
+    routes: T
+  }
+
+/**
+ * Full configuration for wireHTTPRoutes
+ */
+export type WireHTTPRoutesConfig = HTTPRoutesGroupConfig & {
+  routes: HTTPRouteMap | HTTPRouteConfig[]
+}

package/src/wirings/http/index.ts

@@ -1,6 +1,6 @@
-export * from './pikku-fetch-http-request.js'
-export * from './pikku-fetch-http-response.js'
-export * from './log-http-routes.js'
+export { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
+export { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
+export { logRoutes } from './log-http-routes.js'
 
 export {
   fetch,
@@ -10,4 +10,16 @@ export {
   addHTTPPermission,
 } from './http-runner.js'
 
-export type * from './http.types.js'
+export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js'
+
+export type {
+  AssertHTTPWiringParams,
+  CoreHTTPFunctionWiring,
+  HTTPMethod,
+  HTTPRouteBaseConfig,
+  HTTPWiringsMeta,
+  PikkuHTTPRequest,
+  PikkuHTTPResponse,
+  PikkuQuery,
+  RunHTTPWiringOptions,
+} from './http.types.js'