ServerApiHost

tcmts.cli.web.ServerApiHost · #dtxntfsb · type

import type { Fn, ReceivedSpan, TraceSpan } from "#codebase/tcmts/cli/web";

export interface ServerApiHost {
  startWorker: (opts: {
    dataDir: string;
    load: (hash: string) => Promise<Fn>;
    log: (line: string) => void;
    describe?: (hash: string) => string;
  }) => () => void;
  setSchedules: (opts: {
    dataDir: string;
    jobs: { name: string; spec: string; fn: Fn; hash: string }[];
    log?: (line: string) => void;
  }) => void;
  withCall: <T>(
    call: {
      method: string;
      url: string;
      headers: Record<string, string | string[] | undefined>;
      ip: string | undefined;
      signal: AbortSignal;
    },
    opts: { secure: boolean; dataDir?: string; cookiePath?: string },
    fn: () => Promise<T>,
  ) => Promise<
    | { ok: true; value: T; setCookies: string[] }
    | { ok: false; error: unknown; setCookies: string[] }
  >;
  pendingCookies: () => string[];
  startSpan: (info: {
    kind: "call" | "render" | "page" | "http";
    name: string;
    hash?: string;
    attrs?: Record<string, string | number | boolean>;
    /** the caller's traceparent header */
    from?: string;
  }) => TraceSpan | undefined;
  endSpan: (
    span: TraceSpan | undefined,
    outcome?: { error?: unknown; attrs?: Record<string, string | number | boolean> },
  ) => void;
  withinSpan: <R>(span: TraceSpan | undefined, fn: () => R) => R;
  /** keep spans a page sent (of traces this server took part in, on its clock): how many it kept */
  receiveSpans: (spans: ReceivedSpan[]) => number;
  /** one of the codebase's functions, traced (`tcm dev --trace-calls`) */
  wrapCall: (hash: string, value: unknown) => unknown;
  startTracing: (opts: {
    dataDir: string;
    build?: string;
    service: string;
    otlp?: { url: string; headers: Record<string, string> };
    log?: (line: string) => void;
    /** what to say of a span's error besides itself (where it was thrown) */
    describe?: (error: unknown) => Record<string, string | number | boolean>;
    /** a definition's name, for the span of a call to it */
    nameOf?: (hash: string) => string | undefined;
  }) => void;
  stopTracing: () => Promise<void>;
}

uses

used by