Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

13.5 KB
Raw Blame
import type { IncomingMessage, ServerResponse } from 'node:http';
import {
  CLIENT_SURFACE_ATTRIBUTE,
  CLIENT_VERSION_HEADER,
  readClientSurface,
} from '@inkeep/open-knowledge-core';
import { context, propagation, SpanKind, SpanStatusCode } from '@opentelemetry/api';
import {
  ATTR_HTTP_REQUEST_METHOD,
  ATTR_HTTP_RESPONSE_STATUS_CODE,
  ATTR_HTTP_ROUTE,
  ATTR_URL_PATH,
  ATTR_URL_SCHEME,
  ATTR_USER_AGENT_ORIGINAL,
} from '@opentelemetry/semantic-conventions';
import { recordEmbedProbe } from '../embed-probe.ts';
import {
  admitRequestOrigin,
  buildIngressPolicy,
  HOST_NOT_ADMITTED_REMEDIATION,
  type IngressPolicy,
  isHostAdmitted,
  isPeerAdmitted,
  stampIngressContext,
} from '../ingress-policy.ts';
import type { PinoLogger } from '../logger.ts';
import { getMeter, getTracer, onTelemetryShutdown } from '../telemetry.ts';
import { errorResponse } from './error-response.ts';
import { REQUEST_ID_HEADER, rememberRequestId, resolveRequestId } from './request-id.ts';

interface ApiRouteResolution {
  template: string;
  dispatch?: ((req: IncomingMessage, res: ServerResponse) => Promise<void>) | undefined;
}

const PREVIEW_DOCUMENT_MUTATIONS = new Set([
  '/api/agent-write',
  '/api/agent-write-md',
  '/api/agent-patch',
  '/api/agent-undo',
  '/api/agent-write-batch',
  '/api/comments',
  '/api/comment',
  '/api/client-logs',
  '/api/frontmatter-patch',
  '/api/save-version',
  '/api/rollback',
  '/api/lint/fix',
  '/api/folder-config',
  '/api/template',
  '/api/agent-integrations/apply',
]);

export interface ApiRouteTable {
  resolve(pathname: string): ApiRouteResolution | null;
  isMutating(pathname: string): boolean;
}

export type ApiRouteRecord = Readonly<
  Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>>
>;

export interface ApiRouteGroupDynamicLeg {
  prefix: string;
  template: string;
  dispatch: (
    suffix: string,
  ) => ((req: IncomingMessage, res: ServerResponse) => Promise<void>) | undefined;
}

export interface ApiRouteGroup {
  paths: readonly string[];
  table: ApiRouteTable;
}

export function createApiRouteGroup<R extends ApiRouteRecord>(
  routes: R,
  opts: {
    mutating?: readonly (string extends keyof R ? never : keyof R & string)[];
    mutatingPrefixes?: readonly string[];
    dynamic?: ApiRouteGroupDynamicLeg;
  } = {},
): ApiRouteGroup {
  const { dynamic } = opts;
  const mutating: ReadonlySet<string> = new Set(opts.mutating ?? []);
  const mutatingPrefixes: readonly string[] = opts.mutatingPrefixes ?? [];
  const routeKeys = Object.keys(routes);
  if (dynamic !== undefined && !dynamic.prefix.endsWith('/')) {
    throw new Error(
      `dynamic.prefix '${dynamic.prefix}' must end in '/' — a bare prefix mounts a wildcard that also swallows unrelated siblings ('/api/local-op' matches '/api/local-op-status')`,
    );
  }
  for (const prefix of mutatingPrefixes) {
    if (!prefix.endsWith('/')) {
      throw new Error(
        `mutatingPrefixes entry '${prefix}' must end in '/' — a bare prefix also matches unrelated siblings ('/api/local-op' matches '/api/local-op-status')`,
      );
    }
    if (prefix !== dynamic?.prefix && !routeKeys.some((key) => key.startsWith(prefix))) {
      throw new Error(
        `mutatingPrefixes entry '${prefix}' covers no registered route and is not the dynamic leg's prefix — a typo here leaves its family on the read posture`,
      );
    }
  }
  const routeMap = new Map<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>>(
    Object.entries(routes),
  );
  const table: ApiRouteTable = {
    resolve(url) {
      const handler = routeMap.get(url);
      if (handler) {
        return { template: url, dispatch: (req, res) => handler(req, res) };
      }
      if (dynamic !== undefined && url.startsWith(dynamic.prefix)) {
        return {
          template: dynamic.template,
          dispatch: dynamic.dispatch(url.slice(dynamic.prefix.length)),
        };
      }
      return null;
    },
    isMutating: (url) => mutating.has(url) || mutatingPrefixes.some((p) => url.startsWith(p)),
  };
  return {
    paths:
      dynamic !== undefined
        ? [...routeKeys.filter((key) => !key.startsWith(dynamic.prefix)), `${dynamic.prefix}*`]
        : routeKeys,
    table,
  };
}

export interface ApiPipelineOptions {
  log: PinoLogger;
  policy?: IngressPolicy;
  ephemeral?: boolean;
  table: ApiRouteTable;
  dispatchMutation?: (operation: () => Promise<void>, pathname: string) => Promise<void>;
}

export type ApiRequestPipeline = (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;

let _httpDurationHist: ReturnType<ReturnType<typeof getMeter>['createHistogram']> | null = null;
onTelemetryShutdown(() => {
  _httpDurationHist = null;
});
function httpDurationHist(): ReturnType<ReturnType<typeof getMeter>['createHistogram']> {
  _httpDurationHist ||= getMeter().createHistogram('http.server.request.duration', {
    description: 'HTTP server request duration in seconds',
    unit: 's',
  });
  return _httpDurationHist;
}

export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPipeline {
  const { log, ephemeral, table } = opts;
  const policy = opts.policy ?? buildIngressPolicy({});
  const isAllowedWorkspaceHostHeader = (host: string | undefined): boolean =>
    isHostAdmitted(host, policy);

  return async (request, response) => {
    const url = request.url?.split('?')[0];
    if (!url) return false;

    const resolution = table.resolve(url);
    if (!resolution) return false;

    const headerString = (name: string): string | undefined => {
      const value = request.headers[name];
      if (value === undefined) return undefined;
      return Array.isArray(value) ? value.join(', ') : value;
    };
    recordEmbedProbe({
      ts: Date.now(),
      url,
      method: request.method ?? '',
      ua: headerString('user-agent'),
      origin: headerString('origin'),
      referer: headerString('referer'),
      host: headerString('host'),
      remote: request.socket?.remoteAddress,
      secChUa: headerString('sec-ch-ua'),
      secChUaMobile: headerString('sec-ch-ua-mobile'),
      secChUaPlatform: headerString('sec-ch-ua-platform'),
      secFetchSite: headerString('sec-fetch-site'),
      secFetchDest: headerString('sec-fetch-dest'),
      secFetchMode: headerString('sec-fetch-mode'),
      secFetchUser: headerString('sec-fetch-user'),
    });

    const method = request.method ?? 'GET';
    const routeTemplate = resolution.template;
    const clientSurface = readClientSurface(headerString(CLIENT_VERSION_HEADER.kind));

    const requestId = url.startsWith('/api/') ? resolveRequestId(request) : undefined;
    stampIngressContext(request, { requestId, clientSurface });
    if (requestId !== undefined) {
      rememberRequestId(request, requestId);
      if (typeof response.setHeader === 'function') {
        response.setHeader(REQUEST_ID_HEADER, requestId);
      }
      if (typeof response.once === 'function') {
        const accessStarted = Date.now();
        let accessLogged = false;
        const emitAccessLog = () => {
          if (accessLogged) return;
          accessLogged = true;
          log.info(
            {
              event: 'api.access',
              requestId,
              method,
              route: routeTemplate,
              status: response.statusCode,
              durationMs: Date.now() - accessStarted,
              ...(clientSurface === undefined ? {} : { clientSurface }),
              ...(response.writableFinished ? {} : { aborted: true }),
            },
            `${method} ${routeTemplate} ${response.statusCode}`,
          );
        };
        response.once('finish', emitAccessLog);
        response.once('close', emitAccessLog);
      }
    }

    if (url.startsWith('/api/')) {
      if (typeof response.setHeader === 'function') {
        response.setHeader('Cache-Control', 'no-store');
      }
      const origin = request.headers.origin;
      const admission = admitRequestOrigin(origin, method, policy);
      if (!admission.admitted) {
        errorResponse(response, 403, 'urn:ok:error:invalid-origin', 'Origin not allowed.', {
          handler: 'api-origin-gate',
          detail: admission.detail,
        });
        return true;
      }
      if (typeof response.setHeader === 'function') {
        if (origin !== undefined) {
          response.setHeader('Vary', 'Origin');
        }
        if (admission.corsGrant) {
          if (origin !== undefined) {
            response.setHeader('Access-Control-Allow-Origin', origin);
          }
          response.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
          response.setHeader(
            'Access-Control-Allow-Headers',
            `Content-Type, Authorization, traceparent, tracestate, baggage, ${REQUEST_ID_HEADER}, ${CLIENT_VERSION_HEADER.protocol}, ${CLIENT_VERSION_HEADER.runtime}, ${CLIENT_VERSION_HEADER.kind}`,
          );
          response.setHeader('Access-Control-Expose-Headers', REQUEST_ID_HEADER);
        }
      }
      if (request.method === 'OPTIONS') {
        response.writeHead(204);
        response.end();
        return true;
      }
    }

    if (table.isMutating(url)) {
      if (
        ephemeral &&
        resolution.dispatch !== undefined &&
        (method === 'POST' || method === 'PUT' || method === 'DELETE') &&
        !PREVIEW_DOCUMENT_MUTATIONS.has(url)
      ) {
        errorResponse(
          response,
          403,
          'urn:ok:error:single-file-mode',
          'Single-file previews cannot manage project files.',
          {
            handler: 'api-preview-content-scope',
          },
        );
        return true;
      }
      const peerAddress = request.socket?.remoteAddress;
      if (peerAddress !== undefined && !isPeerAdmitted(peerAddress, policy)) {
        errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
          handler: 'api-mutating-gate',
        });
        return true;
      }
      if (!isAllowedWorkspaceHostHeader(request.headers.host)) {
        errorResponse(response, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
          handler: 'api-mutating-gate',
          detail: HOST_NOT_ADMITTED_REMEDIATION,
        });
        return true;
      }
    }

    if (url.startsWith('/api/')) {
      const gateHandler = ephemeral ? 'api-ephemeral-gate' : 'api-read-gate';
      const peerAddress = request.socket?.remoteAddress;
      if (peerAddress !== undefined && !isPeerAdmitted(peerAddress, policy)) {
        errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
          handler: gateHandler,
        });
        return true;
      }
      if (!isAllowedWorkspaceHostHeader(request.headers.host)) {
        errorResponse(response, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
          handler: gateHandler,
          detail: HOST_NOT_ADMITTED_REMEDIATION,
        });
        return true;
      }
    }

    if (!url.startsWith('/api/')) return false;

    const extractedCtx = propagation.extract(context.active(), request.headers);

    const tracer = getTracer();
    const started = Date.now();
    await context.with(extractedCtx, () =>
      tracer.startActiveSpan(
        `HTTP ${method} ${routeTemplate}`,
        {
          kind: SpanKind.SERVER,
          attributes: {
            [ATTR_HTTP_REQUEST_METHOD]: method,
            [ATTR_HTTP_ROUTE]: routeTemplate,
            [ATTR_URL_PATH]: url,
            [ATTR_URL_SCHEME]: 'http',
            [ATTR_USER_AGENT_ORIGINAL]: request.headers['user-agent'] ?? '',
            'ok.request.id': requestId,
            [CLIENT_SURFACE_ATTRIBUTE]: clientSurface,
          },
        },
        async (span) => {
          try {
            const dispatch = resolution.dispatch;
            if (dispatch !== undefined) {
              if (table.isMutating(url) && opts.dispatchMutation !== undefined) {
                await opts.dispatchMutation(() => dispatch(request, response), url);
              } else {
                await dispatch(request, response);
              }
            } else {
              errorResponse(response, 404, 'urn:ok:error:not-found', 'API endpoint not found.', {
                handler: 'api-dispatch',
                detail: `No handler for ${method} ${url}`,
              });
            }

            const status = response.statusCode;
            span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, status);
            if (status >= 500) {
              span.setStatus({ code: SpanStatusCode.ERROR, message: `status ${status}` });
            }
          } catch (err) {
            span.recordException(err as Error);
            span.setStatus({
              code: SpanStatusCode.ERROR,
              message: err instanceof Error ? err.message : String(err),
            });
            if (!response.headersSent && !response.writableEnded && !response.destroyed) {
              errorResponse(
                response,
                500,
                'urn:ok:error:internal-server-error',
                'Internal server error.',
                {
                  handler: routeTemplate,
                  cause: err,
                },
              );
            }
            span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, response.statusCode);
            throw err;
          } finally {
            span.end();
            const durSec = (Date.now() - started) / 1000;
            httpDurationHist().record(durSec, {
              [ATTR_HTTP_REQUEST_METHOD]: method,
              [ATTR_HTTP_ROUTE]: routeTemplate,
              [ATTR_HTTP_RESPONSE_STATUS_CODE]: response.statusCode,
            });
          }
        },
      ),
    );
    return true;
  };
}