@pikku/inspector 0.12.74 → 0.12.81

package/src/add/add-http-route.ts

@@ -1,530 +0,0 @@
-import * as ts from 'typescript'
-import {
-  getPropertyValue,
-  getCommonWireMetaData,
-} from '../utils/get-property-value.js'
-import { pathToRegexp } from 'path-to-regexp'
-import type { HTTPMethod } from '@pikku/core/http'
-import {
-  extractFunctionName,
-  makeContextBasedId,
-} from '../utils/extract-function-name.js'
-import {
-  getPropertyAssignmentInitializer,
-  extractTypeKeys,
-} from '../utils/type-utils.js'
-import type {
-  AddWiring,
-  ExportedHTTPRouteConfigMeta,
-  InspectorState,
-} from '../types.js'
-import { resolveHTTPMiddlewareFromObject } from '../utils/middleware.js'
-import { resolvePermissions } from '../utils/permissions.js'
-import { extractWireNames } from '../utils/post-process.js'
-import { ensureFunctionMetadata } from '../utils/ensure-function-metadata.js'
-import { resolveFunctionMeta } from '../utils/resolve-function-meta.js'
-import { ErrorCode } from '../error-codes.js'
-import { validateAuthSessionless } from '../utils/validate-auth-sessionless.js'
-import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js'
-import { resolveAddonName } from '../utils/resolve-addon-package.js'
-
-import type { InspectorLogger } from '../types.js'
-
-/**
- * Parameters for registering an HTTP route
- */
-export interface RegisterHTTPRouteParams {
-  obj: ts.ObjectLiteralExpression
-  state: InspectorState
-  checker: ts.TypeChecker
-  logger: InspectorLogger
-  sourceFile: ts.SourceFile
-  basePath?: string
-  inheritedTags?: string[]
-  inheritedAuth?: boolean
-}
-
-export interface RegisterHTTPRouteMetaParams {
-  route: ExportedHTTPRouteConfigMeta
-  state: InspectorState
-  logger: InspectorLogger
-  sourceFile: ts.SourceFile
-  basePath?: string
-  inheritedTags?: string[]
-  inheritedAuth?: boolean
-}
-
-/**
- * Extract header schema reference from headers property
- */
-const extractHeadersSchema = (
-  obj: ts.ObjectLiteralExpression,
-  routeName: string,
-  method: string,
-  state: InspectorState,
-  checker: ts.TypeChecker,
-  logger: InspectorLogger
-): string | undefined => {
-  const headersNode = getPropertyAssignmentInitializer(
-    obj,
-    'headers',
-    true,
-    checker
-  )
-  if (!headersNode || !ts.isIdentifier(headersNode)) return undefined
-
-  // Resolve the schema reference
-  const symbol = checker.getSymbolAtLocation(headersNode)
-  if (!symbol) return undefined
-
-  const decl = symbol.valueDeclaration || symbol.declarations?.[0]
-  if (!decl) return undefined
-
-  let sourceFile: string
-  if (ts.isImportSpecifier(decl)) {
-    const aliasedSymbol = checker.getAliasedSymbol(symbol)
-    if (aliasedSymbol) {
-      const aliasedDecl =
-        aliasedSymbol.valueDeclaration || aliasedSymbol.declarations?.[0]
-      if (aliasedDecl) {
-        sourceFile = aliasedDecl.getSourceFile().fileName
-      } else {
-        return undefined
-      }
-    } else {
-      return undefined
-    }
-  } else {
-    sourceFile = decl.getSourceFile().fileName
-  }
-
-  const vendor = detectSchemaVendorOrError(
-    headersNode,
-    checker,
-    logger,
-    `Route '${routeName}' header`,
-    sourceFile
-  )
-  if (!vendor) return undefined
-
-  // Create a sanitized schema name from route and method to avoid collisions
-  const sanitizedRoute = routeName
-    .replace(/[^a-zA-Z0-9]/g, '_')
-    .replace(/^_+|_+$/g, '')
-  const schemaName = `${method.toUpperCase()}_${sanitizedRoute}_Headers`
-
-  state.schemaLookup.set(schemaName, {
-    variableName: headersNode.text,
-    sourceFile,
-    vendor,
-  })
-
-  return schemaName
-}
-
-/**
- * Populate metaInputTypes for a given route based on method, input type,
- * query and params.
- */
-const computeInputTypes = (
-  metaTypes: Map<
-    string,
-    { query?: string[]; params?: string[]; body?: string[] }
-  >,
-  methodType: string,
-  inputType: string | null,
-  queryValues: string[],
-  paramsValues: string[]
-): void => {
-  if (!inputType) return
-  metaTypes.set(inputType, {
-    query: queryValues,
-    params: paramsValues,
-    body: ['post', 'put', 'patch'].includes(methodType)
-      ? [...new Set([...queryValues, ...paramsValues])]
-      : [],
-  })
-}
-
-/**
- * Shared function to register an HTTP route in the inspector state.
- * Used by both wireHTTP and wireHTTPRoutes.
- */
-export function registerHTTPRoute({
-  obj,
-  state,
-  checker,
-  logger,
-  sourceFile,
-  basePath = '',
-  inheritedTags = [],
-  inheritedAuth,
-}: RegisterHTTPRouteParams): void {
-  // Extract route path
-  const routePath = getPropertyValue(obj, 'route') as string | null
-  if (!routePath) return
-
-  const method = (
-    (getPropertyValue(obj, 'method') as string) || 'get'
-  ).toLowerCase()
-  const fullRoute = basePath + routePath
-
-  // Extract params from route path
-  let params: string[] = []
-  try {
-    const keys = pathToRegexp(fullRoute).keys
-    params = keys.filter((k) => k.type === 'param').map((k) => k.name)
-  } catch (e) {
-    logger.error(
-      `Failed to parse route '${fullRoute}': ${e instanceof Error ? e.message : e}`
-    )
-    return
-  }
-
-  // Get common metadata
-  const {
-    disabled,
-    title,
-    tags: routeTags,
-    summary,
-    description,
-    errors,
-  } = getCommonWireMetaData(obj, 'HTTP route', fullRoute, logger, checker)
-
-  if (disabled) return
-
-  // Merge inherited tags with route tags
-  const tags = [...inheritedTags, ...(routeTags || [])]
-
-  const query = (getPropertyValue(obj, 'query') as string[]) || []
-
-  // Get function reference
-  const funcInitializer = getPropertyAssignmentInitializer(
-    obj,
-    'func',
-    true,
-    checker
-  )
-  if (!funcInitializer) {
-    logger.critical(
-      ErrorCode.MISSING_FUNC,
-      `No valid 'func' property for route '${fullRoute}'.`
-    )
-    return
-  }
-
-  const extracted = extractFunctionName(funcInitializer, checker, state.rootDir)
-  let funcName = extracted.pikkuFuncId
-  if (funcName.startsWith('__temp_')) {
-    funcName = makeContextBasedId('http', method, fullRoute)
-  }
-
-  let refAddonTarget: string | null = null
-  if (
-    ts.isCallExpression(funcInitializer) &&
-    ts.isIdentifier(funcInitializer.expression) &&
-    funcInitializer.expression.text === 'ref'
-  ) {
-    const [firstArg] = funcInitializer.arguments
-    if (
-      firstArg &&
-      ts.isStringLiteral(firstArg) &&
-      firstArg.text.includes(':')
-    ) {
-      refAddonTarget = firstArg.text
-    }
-  }
-
-  const packageName = ts.isIdentifier(funcInitializer)
-    ? resolveAddonName(
-        funcInitializer,
-        checker,
-        state.rpc.wireAddonDeclarations
-      )
-    : null
-
-  // A ref()-wired route points straight at the addon function, the same way the
-  // CLI and channel adders record one. The addon's own metadata is the contract
-  // — and it is authoritative where the checker is not: `ref('ns:fn')` only
-  // types precisely once the consumer's own rpc map already lists the addon's
-  // functions, so a cold run inferred the whole `FlattenedRPCMap` and a warm one
-  // inferred the real input. The addon's metadata says which it is either way.
-  //
-  // The route stays the consuming app's all the same, so it records no
-  // packageName: that names the package a wire *runs in*, and running this one
-  // inside the addon would hand it the addon's middleware and services instead
-  // of the app's. `ref` reaches the addon over RPC, which enters it properly.
-  if (refAddonTarget) {
-    const targetMeta = resolveFunctionMeta(state, refAddonTarget)
-    if (!targetMeta) {
-      logger.warn(
-        `Skipping route '${fullRoute}': addon function metadata for '${refAddonTarget}' is not available yet.`
-      )
-      return
-    }
-    funcName = refAddonTarget
-  } else {
-    ensureFunctionMetadata(
-      state,
-      funcName,
-      fullRoute,
-      funcInitializer,
-      checker,
-      extracted.isHelper
-    )
-  }
-
-  // The route's own `auth`, falling back to the group's. Recorded on the meta
-  // below so an audit can answer "is this route open?" without re-reading the
-  // source: the route can tighten a sessionless function, and until this was
-  // written down that tightening existed only in the wiring.
-  const routeAuthProp = getPropertyValue(obj, 'auth')
-  const resolvedAuth =
-    routeAuthProp === true || routeAuthProp === false
-      ? routeAuthProp
-      : inheritedAuth
-
-  // For inline functions (e.g. oauth2 handlers), propagate sessionless: true
-  // when auth is explicitly disabled at the route or group level — the
-  // developer opted out of auth so no session is required.
-  {
-    const inlineMeta = state.functions.meta[funcName]
-    if (
-      inlineMeta &&
-      inlineMeta.sessionless === undefined &&
-      resolvedAuth === false
-    ) {
-      inlineMeta.sessionless = true
-    }
-  }
-
-  // Lookup existing function metadata
-  const fnMeta = resolveFunctionMeta(state, funcName)
-  if (!fnMeta) {
-    logger.critical(
-      ErrorCode.FUNCTION_METADATA_NOT_FOUND,
-      `No function metadata found for '${funcName}'.`
-    )
-    return
-  }
-
-  if (
-    !validateAuthSessionless(
-      logger,
-      obj,
-      state,
-      funcName,
-      `Route '${fullRoute}'`,
-      inheritedAuth
-    )
-  ) {
-    return
-  }
-
-  const input = fnMeta.inputs?.[0] || null
-
-  const getRouteInputKeys = (): string[] | null => {
-    const inputTypes = state.typesLookup.get(funcName)
-    if (inputTypes && inputTypes.length > 0) {
-      return extractTypeKeys(inputTypes[0])
-    }
-
-    const targetMeta = resolveFunctionMeta(state, funcName)
-    if (targetMeta?.inputSchemaName) {
-      const schema = state.schemas[targetMeta.inputSchemaName] as any
-      const properties = schema?.properties
-      if (properties && typeof properties === 'object') {
-        return Object.keys(properties)
-      }
-    }
-
-    return null
-  }
-
-  // Validate that route params and query params exist in function input type
-  if (params.length > 0 || query.length > 0) {
-    const inputKeys = getRouteInputKeys()
-    if (!inputKeys) {
-      // Input shape isn't inspectable at this phase (e.g. addon ref or opaque handler).
-      // Skip param/query validation rather than emitting a false positive.
-    } else {
-      // Check path params
-      if (params.length > 0) {
-        const missingParams = params.filter((p) => !inputKeys.includes(p))
-        if (missingParams.length > 0) {
-          logger.critical(
-            ErrorCode.ROUTE_PARAM_MISMATCH,
-            `Route '${fullRoute}' has path parameter(s) [${missingParams.join(', ')}] ` +
-              `not found in function '${funcName}' input type. ` +
-              `Input type has: [${inputKeys.join(', ')}]`
-          )
-          return
-        }
-      }
-
-      // Check query params
-      if (query.length > 0) {
-        const missingQuery = query.filter((q) => !inputKeys.includes(q))
-        if (missingQuery.length > 0) {
-          logger.critical(
-            ErrorCode.ROUTE_QUERY_MISMATCH,
-            `Route '${fullRoute}' has query parameter(s) [${missingQuery.join(', ')}] ` +
-              `not found in function '${funcName}' input type. ` +
-              `Input type has: [${inputKeys.join(', ')}]`
-          )
-          return
-        }
-      }
-    }
-  }
-
-  // Compute inputTypes (body/query/params)
-  computeInputTypes(state.http.metaInputTypes, method, input, query, params)
-
-  // Resolve middleware
-  const middleware = resolveHTTPMiddlewareFromObject(
-    state,
-    fullRoute,
-    obj,
-    tags,
-    checker
-  )
-
-  // Resolve permissions
-  const permissions = resolvePermissions(state, obj, tags, checker)
-
-  state.serviceAggregation.usedFunctions.add(funcName)
-  extractWireNames(middleware).forEach((name) =>
-    state.serviceAggregation.usedMiddleware.add(name)
-  )
-  extractWireNames(permissions).forEach((name) =>
-    state.serviceAggregation.usedPermissions.add(name)
-  )
-
-  // Check for SSE
-  const sse = getPropertyValue(obj, 'sse') === true
-
-  // Extract header schema
-  const headersSchemaName = extractHeadersSchema(
-    obj,
-    fullRoute,
-    method,
-    state,
-    checker,
-    logger
-  )
-
-  // Record route
-  state.http.files.add(sourceFile.fileName)
-  state.http.meta[method][fullRoute] = {
-    pikkuFuncId: funcName,
-    ...(packageName && { packageName }),
-    route: fullRoute,
-    sourceFile: sourceFile.fileName,
-    method: method as HTTPMethod,
-    ...(resolvedAuth !== undefined && { auth: resolvedAuth }),
-    params: params.length > 0 ? params : undefined,
-    query: query.length > 0 ? query : undefined,
-    inputTypes: undefined,
-    title,
-    summary,
-    description,
-    errors,
-    tags: tags.length > 0 ? tags : undefined,
-    middleware,
-    permissions,
-    sse: sse ? true : undefined,
-    headersSchemaName,
-    groupBasePath: basePath || undefined,
-  }
-}
-
-export function registerHTTPRouteMeta({
-  route,
-  state,
-  logger,
-  sourceFile,
-  basePath = '',
-  inheritedTags = [],
-  inheritedAuth,
-}: RegisterHTTPRouteMetaParams): void {
-  const method = route.method.toLowerCase()
-  const fullRoute = basePath + route.route
-  const tags = [...inheritedTags, ...(route.tags || [])]
-  const funcName = route.func.pikkuFuncId
-  const fnMeta = resolveFunctionMeta(state, funcName)
-
-  if (!fnMeta) {
-    logger.critical(
-      ErrorCode.FUNCTION_METADATA_NOT_FOUND,
-      `No function metadata found for '${funcName}'.`
-    )
-    return
-  }
-
-  let params: string[] = []
-  try {
-    const keys = pathToRegexp(fullRoute).keys
-    params = keys.filter((k) => k.type === 'param').map((k) => k.name)
-  } catch (error) {
-    logger.error(
-      `Failed to parse route '${fullRoute}': ${error instanceof Error ? error.message : error}`
-    )
-    return
-  }
-
-  if (!route.func.packageName) {
-    computeInputTypes(
-      state.http.metaInputTypes,
-      method,
-      fnMeta.inputs?.[0] || null,
-      [],
-      params
-    )
-  }
-
-  state.serviceAggregation.usedFunctions.add(funcName)
-  state.http.files.add(sourceFile.fileName)
-  state.http.meta[method][fullRoute] = {
-    pikkuFuncId: funcName,
-    ...(route.func.packageName && { packageName: route.func.packageName }),
-    route: fullRoute,
-    sourceFile: sourceFile.fileName,
-    method: method as HTTPMethod,
-    ...((route.auth ?? inheritedAuth) !== undefined && {
-      auth: route.auth ?? inheritedAuth,
-    }),
-    params: params.length > 0 ? params : undefined,
-    inputTypes: undefined,
-    tags: tags.length > 0 ? tags : undefined,
-    sse: route.sse ? true : undefined,
-    groupBasePath: basePath || undefined,
-  }
-}
-
-/**
- * Process wireHTTP calls
- */
-export const addHTTPRoute: AddWiring = (
-  logger,
-  node,
-  checker,
-  state,
-  _options
-) => {
-  if (!ts.isCallExpression(node)) return
-
-  const { expression, arguments: args } = node
-  if (!ts.isIdentifier(expression) || expression.text !== 'wireHTTP') return
-
-  const firstArg = args[0]
-  if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return
-
-  registerHTTPRoute({
-    obj: firstArg,
-    state,
-    checker,
-    logger,
-    sourceFile: node.getSourceFile(),
-  })
-}