@pikku/core 0.11.2 → 0.12.1

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

@@ -1,20 +1,19 @@
-import {
+import type {
   CoreHTTPFunctionWiring,
   RunHTTPWiringOptions,
-  RunHTTPWiringParams,
   PikkuHTTP,
   PikkuHTTPRequest,
   PikkuHTTPResponse,
   HTTPWiringMeta,
   HTTPMethod,
 } from './http.types.js'
-import {
+import type {
   CorePikkuFunction,
   CorePikkuFunctionSessionless,
   CorePikkuPermission,
   CorePermissionGroup,
 } from '../../function/functions.types.js'
-import {
+import type {
   CoreUserSession,
   CorePikkuMiddleware,
   CorePikkuMiddlewareGroup,
@@ -22,21 +21,43 @@ 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 {
+  getSingletonServices,
+  getCreateWireServices,
+} from '../../pikku-state.js'
 import { PikkuSessionService } 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'
 import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
-import { PikkuChannel } from '../channel/channel.types.js'
+import type { 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'
+import { runMiddleware } from '../../middleware-runner.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 +178,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 +304,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 +331,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 +367,19 @@ 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,
+    session: userSession.get() as CoreUserSession | undefined,
+    setSession: (s: any) => userSession.setInitial(s),
+    getSession: () => userSession.get(),
+    hasSessionChanged: () => userSession.sessionChanged,
   }
 
   result = await runPikkuFunc(
     'http',
     `${meta.method}:${meta.route}`,
-    meta.pikkuFuncName,
+    meta.pikkuFuncId,
     {
       singletonServices,
       createWireServices,
@@ -354,20 +392,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 }
 }
 
@@ -383,12 +421,12 @@ const executeRoute = async (
  * @template In Expected input data type.
  * @template Out Expected output data type.
  * @param {Request} request - The native Fetch API Request object.
- * @param {RunHTTPWiringOptions & RunHTTPWiringParams} params - Additional options including services and session management.
+ * @param {RunHTTPWiringOptions} params - Additional options including services and session management.
  * @returns {Promise<Response>} A promise that resolves to a Fetch API Response object.
  */
 export const fetch = async <In, Out>(
   request: Request,
-  params: RunHTTPWiringOptions & RunHTTPWiringParams
+  params: RunHTTPWiringOptions = {}
 ): Promise<Response> => {
   const pikkuResponse = new PikkuFetchHTTPResponse()
   await fetchData<In, Out>(request, pikkuResponse, params)
@@ -404,12 +442,12 @@ export const fetch = async <In, Out>(
  * @template In Expected input data type.
  * @template Out Expected output data type.
  * @param {Request | PikkuHTTPRequest} request - The request object.
- * @param {RunHTTPWiringOptions & RunHTTPWiringParams} params - Execution options including services and session configuration.
+ * @param {RunHTTPWiringOptions} params - Execution options including services and session configuration.
  * @returns {Promise<PikkuFetchHTTPResponse>} A promise that resolves to a PikkuFetchHTTPResponse object.
  */
 export const pikkuFetch = async <In, Out>(
   request: Request | PikkuHTTPRequest,
-  params: RunHTTPWiringOptions & RunHTTPWiringParams
+  params: RunHTTPWiringOptions = {}
 ): Promise<PikkuFetchHTTPResponse> => {
   const pikkuResponse = new PikkuFetchHTTPResponse()
   await fetchData<In, Out>(request, pikkuResponse, params)
@@ -431,43 +469,56 @@ export const pikkuFetch = async <In, Out>(
  * @template Out Expected output data type.
  * @param {Request | PikkuHTTPRequest} request - The incoming HTTP request.
  * @param {PikkuHTTPResponse} response - The response object to be populated.
- * @param {RunHTTPWiringOptions & RunHTTPWiringParams} options - Options such as singleton services, session handling, and error configuration.
+ * @param {RunHTTPWiringOptions} options - Options such as singleton services, session handling, and error configuration.
  * @returns {Promise<Out | void>} The output from the route handler or void if an error occurred.
  */
 export const fetchData = async <In, Out>(
   request: Request | PikkuHTTPRequest,
   response: PikkuHTTPResponse,
   {
-    singletonServices,
-    createWireServices,
     skipUserSession = false,
     respondWith404 = true,
     logWarningsForStatusCodes = [],
     coerceDataFromSchema = true,
     bubbleErrors = false,
     generateRequestId,
-  }: RunHTTPWiringOptions & RunHTTPWiringParams
+  }: RunHTTPWiringOptions = {}
 ): Promise<Out | void> => {
-  const requestId =
-    (request as any).getHeader?.('x-request-id') ||
-    generateRequestId?.() ||
-    createWeakUID()
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   let wireServices: WireServices<typeof singletonServices> | undefined
   let result: Out
 
   // Combine the request and response into one wire object
-  const http = createHTTPWire(
-    request instanceof Request ? new PikkuFetchHTTPRequest(request) : request,
-    response
-  )
+  const pikkuRequest =
+    request instanceof Request ? new PikkuFetchHTTPRequest(request) : request
+  let requestId: string | null = null
+  try {
+    requestId = pikkuRequest.header('x-request-id')
+  } catch {}
+  requestId = requestId || generateRequestId?.() || createWeakUID()
+  const http = createHTTPWire(pikkuRequest, response)
   const apiType = http!.request!.method()
   const apiRoute = http!.request!.path()
 
   // Locate the matching route based on the HTTP method and path
   const matchedRoute = getMatchingRoute(apiType, apiRoute)
   try {
-    // If no route matches, log the occurrence and throw a NotFoundError
     if (!matchedRoute) {
+      if (apiType.toLowerCase() === 'options') {
+        const httpGroups = pikkuState(null, 'middleware', 'httpGroup')
+        const globalMiddleware = httpGroups['*']
+        const wire: PikkuWire = { http: http! }
+        if (globalMiddleware) {
+          await runMiddleware(
+            singletonServices,
+            wire,
+            globalMiddleware as CorePikkuMiddleware[]
+          )
+        }
+        response.status(204).json(undefined as any)
+        return
+      }
       singletonServices.logger.info({
         message: 'Route not found',
         apiRoute,
@@ -491,7 +542,6 @@ export const fetchData = async <In, Out>(
 
     return result
   } catch (e: any) {
-    // Handle errors and, depending on configuration, bubble them up or respond with an error
     handleHTTPError(
       e,
       http,

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

@@ -1,10 +1,7 @@
 import type { SerializeOptions } from 'cookie'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { PikkuError } from '../../errors/error-handler.js'
 import type {
-  CoreServices,
-  CoreSingletonServices,
-  CoreUserSession,
-  CreateWireServices,
   CorePikkuMiddleware,
   CommonWireMeta,
 } from '../../types/core.types.js'
@@ -42,18 +39,9 @@ export type RunHTTPWiringOptions = Partial<{
   generateRequestId: () => string
 }>
 
-export type RunHTTPWiringParams = {
-  singletonServices: CoreSingletonServices
-  createWireServices: CreateWireServices<
-    CoreSingletonServices,
-    CoreServices<CoreSingletonServices>,
-    CoreUserSession
-  >
-}
-
 /**
  * Represents the HTTP methods supported for API HTTP wirings.
-t */
+ */
 export type HTTPMethod =
   | 'post'
   | 'get'
@@ -64,21 +52,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 HTTPHeadersSchema = StandardSchemaV1<
+  Record<string, string | string[] | undefined>
+>
+
+/**
+ * Documentation config for OpenAPI generation
  */
-export type CoreHTTPFunction = {
+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 +129,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 +159,6 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
-      tags?: string[]
       middleware?: PikkuMiddleware[]
       sse?: undefined
     })
@@ -163,7 +172,6 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: undefined
       auth?: false
-      tags?: string[]
       middleware?: PikkuMiddleware[]
       sse?: undefined
     })
@@ -177,9 +185,8 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
-      sse?: boolean
-      tags?: string[]
       middleware?: PikkuMiddleware[]
+      sse?: boolean
     })
   | (CoreHTTPFunction & {
       route: R
@@ -191,9 +198,8 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: undefined
       auth?: false
-      sse?: boolean
-      tags?: string[]
       middleware?: PikkuMiddleware[]
+      sse?: boolean
     })
   | (CoreHTTPFunction & {
       route: R
@@ -205,9 +211,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,24 +225,10 @@ export type CoreHTTPFunctionWiring<
       >
       permissions?: undefined
       auth?: false
-      query?: Array<keyof In>
-      tags?: string[]
       middleware?: PikkuMiddleware[]
+      query?: Array<keyof In>
       sse?: undefined
     })
-  | {
-      /** Route triggers a workflow matched by route/method from workflow wires.http */
-      route: R
-      method: HTTPMethod
-      workflow: true
-      func?: undefined
-      permissions?: undefined
-      auth?: undefined
-      tags?: undefined
-      middleware?: undefined
-      returnsJSON?: undefined
-      sse?: boolean
-    }
 
 /**
  * Represents the input types for HTTP wiring metadata, including parameters, query, and body types.
@@ -257,8 +248,9 @@ export type HTTPWiringMeta = CommonWireMeta & {
   params?: string[]
   query?: string[]
   inputTypes?: HTTPFunctionMetaInputTypes
+  headersSchemaName?: string
   sse?: true
-  workflow?: true
+  groupBasePath?: string
 }
 export type HTTPWiringsMeta = Record<HTTPMethod, Record<string, HTTPWiringMeta>>
 
@@ -305,3 +297,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'

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

@@ -1,5 +1,5 @@
 import { pikkuState } from '../../pikku-state.js'
-import { Logger } from '../../services/index.js'
+import type { Logger } from '../../services/index.js'
 
 /**
  * Logs all the loaded routes.

package/src/wirings/http/pikku-fetch-http-request.ts

@@ -1,6 +1,6 @@
 import { parse as parseQuery } from 'picoquery'
 import { parse as parseCookie } from 'cookie'
-import { HTTPMethod, PikkuHTTPRequest, PikkuQuery } from './http.types.js'
+import type { HTTPMethod, PikkuHTTPRequest, PikkuQuery } from './http.types.js'
 import { UnprocessableContentError } from '../../errors/errors.js'
 
 /**

package/src/wirings/http/pikku-fetch-http-response.ts

@@ -1,8 +1,6 @@
-import { PikkuHTTPResponse } from './http.types.js'
-import {
-  SerializeOptions as CookieSerializeOptions,
-  serialize as serializeCookie,
-} from 'cookie'
+import type { PikkuHTTPResponse } from './http.types.js'
+import type { SerializeOptions as CookieSerializeOptions } from 'cookie'
+import { serialize as serializeCookie } from 'cookie'
 
 export class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
   #statusCode: number = 200
@@ -91,6 +89,15 @@ export class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
   // }
 
   public redirect(location: string, status: number = 302): this {
+    if (
+      !location.startsWith('/') &&
+      !location.startsWith('https://') &&
+      !location.startsWith('http://')
+    ) {
+      throw new Error(
+        'Invalid redirect location: must be a relative path or absolute URL'
+      )
+    }
     this.#statusCode = status
     this.header('Location', location)
     return this

package/src/wirings/http/routers/http-router.ts

@@ -1,4 +1,4 @@
-import { HTTPMethod } from '../http.types.js'
+import type { HTTPMethod } from '../http.types.js'
 import { PathToRegexRouter } from './path-to-regex.js'
 
 export type MatchResult = {

package/src/wirings/http/routers/path-to-regex.test.ts

@@ -2,7 +2,7 @@ import { test, describe, beforeEach } from 'node:test'
 import * as assert from 'node:assert/strict'
 import { PathToRegexRouter } from './path-to-regex.js'
 import { resetPikkuState, pikkuState } from '../../../pikku-state.js'
-import { HTTPMethod } from '../http.types.js'
+import type { HTTPMethod } from '../http.types.js'
 
 describe('PathToRegexRouter', () => {
   let router: PathToRegexRouter

package/src/wirings/http/routers/path-to-regex.ts

@@ -1,6 +1,7 @@
-import { match, MatchFunction } from 'path-to-regexp'
-import { MatchResult, Router } from './http-router.js'
-import { HTTPMethod } from '../http.types.js'
+import type { MatchFunction } from 'path-to-regexp'
+import { match } from 'path-to-regexp'
+import type { MatchResult, Router } from './http-router.js'
+import type { HTTPMethod } from '../http.types.js'
 import { pikkuState } from '../../../pikku-state.js'
 
 interface CompiledRoute {

package/src/wirings/mcp/index.ts

@@ -1,3 +1,27 @@
-export * from './mcp.types.js'
-export * from './mcp-runner.js'
-export * from './mcp-endpoint-registry.js'
+export { MCPEndpointRegistry } from './mcp-endpoint-registry.js'
+export {
+  MCPError,
+  wireMCPResource,
+  wireMCPPrompt,
+  runMCPResource,
+  runMCPTool,
+  runMCPPrompt,
+} from './mcp-runner.js'
+export {
+  getMCPResourcesMeta,
+  getMCPToolsMeta,
+  getMCPPromptsMeta,
+} from './mcp-runner.js'
+export type {
+  AssertMCPResourceURIParams,
+  CoreMCPPrompt,
+  CoreMCPResource,
+  CoreMCPTool,
+  MCPPromptResponse,
+  MCPResourceMeta,
+  MCPResourceResponse,
+  MCPToolMeta,
+  MCPToolResponse,
+  MCPPromptMeta,
+  PikkuMCP,
+} from './mcp.types.js'