types.ts

export type Runtime = 'runc' | 'runsc' | 'kata';

export interface RunnerOptions {
  memory?: string;
  cpus?: string;
  runtime?: Runtime;
  gpus?: 'all' | number | string;
  noNewPrivileges?: boolean;
}

export interface ExtractSpec {
  /*
   * Path inside the container. Absolute, or relative to the workdir.
   * Paths containing `..` are rejected (no traversal).
   */
  from: string;
  /*
   * Host destination directory.
   * Auto-created (recursive mkdir).
   *   - If `from` is a directory: its contents land directly in `to`
   *     (rsync-like: `from/*` -> `to/*`, no basename wrap).
   *   - If `from` is a file: it lands as `to/basename(from)`.
   * CREATE AN EXEMPLE :TODO:
   */
  to: string;
}

export interface ExtractResult {
  from: string;
  to: string;
  status: 'ok' | 'missing' | 'error';
  error?: string;
  bytes?: number;
}

export interface RunRequest {
  image: string;

  entrypoint?: string;
  /*
   * Optional build-time setup steps.
   * Each entry becomes a `RUN <step>` in a generated Dockerfile (`FROM <image>` + N x `RUN`).
   * The resulting image is tagged `light-runner-cache:<sha256(image + run)>`, kept around for reuse,
   * and used as the actual base for the run.
   * 
   * Identical (image, run[]) pairs
   * hit the cache and skip the build.
   *
   * Threat model: `run[]` is executed by `docker build` (BuildKit by default)
   * which does NOT inherit the runtime sandbox flags.
   * Treat `run[]` as operator-trusted input. *Never pass user-supplied strings here.* 
   *
   * Validation rules per step (rejected with INVALID_RUN_STEP):
   *   - no newlines, carriage returns, or null bytes (would inject a new
   *     Dockerfile instruction)
   *   - no trailing backslash (Dockerfile line continuation)
   *   - no leading `--` (blocks BuildKit `RUN --mount`, `--network`,
   *     `--security`, `--device` host-access flags)
   */
  run?: string[];
  /*
   * Host path to a directory whose contents are copied into workdir ex: /app,
   * internal structure preserved. Entries named .git, node_modules, dist,
   * build, .next, .cache, .turbo, coverage are skipped. Symlinks are skipped.
   * Omit for an empty volume.
   */
  dir?: string;
  /*
  A RVOIR TODO TDEH COMMENT ET POURUOQI
   */
  input?: unknown;
  /* send SIGKILL at DEFAULT_TIMEOUT_MS milisecondes */
  timeout?: number;
  /*
   * Networks for the container. The first entry is the primary, set as Docker
   * NetworkMode; any further entries are connected after create, before start.
   *   - omitted          -> single isolated bridge (the secure default)
   *   - ['none']         -> no network
   *   - ['my-net']       -> one named network
   *   - ['a', 'b', ...]  -> 'a' is primary, 'b'... are additionally connected
   * Named networks must already exist. Listing several networks WIDENS the
   * container's reachability: an operator-trusted opt-in. Omitting the field
   * keeps the secure single-isolated-network default.
   */
  networks?: string[];
  /* filtred by ^[A-Za-z_][A-Za-z0-9_]*$ or siliencied ignored */
  env?: Record<string, string>;

  workdir?: string;
  signal?: AbortSignal;
  onLog?: (line: string) => void;
  /*
   * Files or folders to stream out of the container after a successful run,
   * disk-to-disk. Capped at 1 GiB per entry. Missing paths are reported in
   * `RunResult.extracted`, they do not fail the run.
   */
  extract?: ExtractSpec[];
  /*
   * When true, the container starts with `docker run -d` and the host process
   * returns immediately. The run state is persisted under the state dir so a
   * crashed host can resume it via `DockerRunner.attach(id)` later.
   *
   * Contract changes in detached mode:
   *   - `input` is rejected (no stdin can survive process death)
   *   - `onLog` streams to the launcher process; a host that re-attaches via
   *     DockerRunner.attach(id) does not receive live lines (use docker logs).
   *   - The returned Execution.result still resolves when the container exits
   *     for the host that launched it; a second host can re-attach by id.
   */
  detached?: boolean;
}

export interface RunResult {
  success: boolean;
  exitCode: number;
  duration: number;
  cancelled: boolean;
  /** Status of each requested extract. Present only if `extract` was set. */
  extracted?: ExtractResult[];
}