Skip to content
v9.1.1
Français

SpeculationOptions

import type { SpeculationOptions } from "@elie-laloum/outpost";

Parameters and properties

Section titled “Parameters and properties”
  • durabilityOptional
    SpeculationDurability | undefined
    Saves the race through a Transport so it can resume after a crash or a quota stop. Requires a provider with recover; omit it for an in-memory race.
  • cleanupMsOptional
    number | undefined
    Wait for each sandbox close or resource recovery, and for running candidates after cancellation, default 30000. Past it, cleanup stays pending.
  • observationOptional
    ObservationHub | undefined
    Parent hub for the events of every candidate, scoped by candidate key; it replaces each request’s own observation.
  • repositoryRequired
    string
    Host Git checkout. Its HEAD commit when the race first starts is the baseline of every candidate branch.
  • sandboxProviderRequired
    SandboxProvider
    Provider that allocates each candidate’s sandbox. Durable mode requires one with recover: Docker or Podman in mounted mode.
  • candidatesRequired
    readonly SpeculativeCandidate<T>[]
    1 to 8 candidates with unique keys, started in list order as concurrency allows.
  • concurrencyOptional
    number | undefined
    Maximum candidates running at once, 1 to 8, default 2.
  • budgetRequired
    WorkflowBudget
    Limits shared by all candidates. Each start consumes one of attempts and the limit stops new starts; reaching a usage token limit cancels running candidates. Tokens used inside validate are not counted.
  • signalOptional
    AbortSignal | undefined
    Aborting it cancels running candidates and ends the race with status aborted.
  • sandboxOptional
    Pick<SandboxOptions, "hooks" | "storageQuota" | "limits" | "logging" | "bootstrap" | "conversationHome"> | undefined
    Sandbox settings applied to every candidate: hooks, bootstrap, logging, limits, storageQuota and conversationHome.
  • validateRequired
    (candidate: SpeculativeValidation<T>) => boolean | Promise<boolean>
    Decides whether a finished candidate is acceptable, given its dispatch output and live sandbox; true accepts it. A throw marks the candidate failed.

Signature

Section titled “Signature”
export interface SpeculationOptions<T = undefined> {
  readonly durability?: SpeculationDurability;
  readonly cleanupMs?: number;
  readonly observation?: ObservationHub;
  readonly repository: string;
  readonly sandboxProvider: NonNullable<SandboxOptions["sandboxProvider"]>;
  readonly candidates: readonly SpeculativeCandidate<T>[];
  readonly concurrency?: number;
  readonly budget: WorkflowBudget;
  readonly signal?: AbortSignal;
  readonly sandbox?: Pick<
    SandboxOptions,
    | "hooks"
    | "bootstrap"
    | "logging"
    | "limits"
    | "storageQuota"
    | "conversationHome"
  >;
  readonly validate: (
    candidate: SpeculativeValidation<T>,
  ) => boolean | Promise<boolean>;
}
Section titled “Related contracts”