/**
 * Module-scope (== per-isolate, same reasoning as
 * `packages/hosts/cloudflare/src/mcp/session-runtime-residency.ts`) semaphore
 * bounding concurrent COLD `buildMcpServer` builds.
 *
 * A burst of new sessions can land on one isolate at once. Each cold build
 * runs execution-stack setup and MCP server construction, which is real CPU
 * — concentrating several of those builds at the same instant is what drags
 * the isolate's request p95 during a wave. Capping how many builds run at
 * once smooths that burst into a short FIFO queue instead of letting every
 * arrival pay full concurrent cost.
 *
 * Deliberately dependency-free: a tiny promise-chain queue, not a library.
 */

const MAX_CONCURRENT_BUILDS = 4;

/**
 * Max time a build waits in the FIFO queue for a slot before proceeding
 * without one. Admission control exists only to smooth bursts into a short
 * queue — it must never turn a *slow* build into a *stuck* one. If the
 * isolate is wedged behind a hung dependency (e.g. a stalled DB during an
 * incident) and a slot never frees up, every waiter behind it would otherwise
 * block forever. Past this timeout a waiter gives up on the queue and builds
 * uncapped instead, same as if the semaphore did not exist, and reports
 * `timedOut: true` so it is visible in telemetry rather than silently
 * degrading.
 */
export const MAX_QUEUE_WAIT_MS = 10_000;

let activeBuilds = 0;

/** Lifecycle of one queued waiter. See `acquireBuildSlot` for the full state machine. */
type WaiterState = "queued" | "granted" | "timed-out" | "cancelled";

interface Waiter {
  state: WaiterState;
  readonly grant: () => void;
}

const waitQueue: Waiter[] = [];

export interface BuildSlotResult {
  /** False only when the wait timed out; the caller must NOT call `releaseBuildSlot` for it. */
  readonly acquired: boolean;
  /** Milliseconds spent waiting for a slot (0 when one was immediately free). */
  readonly waitMs: number;
  /** True when the wait hit `MAX_QUEUE_WAIT_MS` and proceeded without a slot. */
  readonly timedOut: boolean;
}

export interface BuildSlotHandle {
  /** Resolves exactly once, with the outcome of this acquisition. Never rejects. */
  readonly promise: Promise<BuildSlotResult>;
  /**
   * Cancel this acquisition. Safe to call at any point in its lifecycle,
   * including redundantly or after `promise` has already settled — it is
   * idempotent and only ever frees a slot once:
   *  - Still queued: dequeues the waiter. Nothing was ever granted, so there
   *    is nothing to release.
   *  - Already granted a slot — this races `releaseBuildSlot` handing the
   *    slot to this waiter (that happens synchronously inside
   *    `releaseBuildSlot`) against this `cancel` — releases that slot
   *    immediately so it is not held with no owner, and wakes the next FIFO
   *    waiter.
   *  - Already timed out or already cancelled: no-op.
   *
   * Callers should call this from a `finally`/`ensuring` unconditionally
   * (success, failure, or interruption alike) rather than trying to track
   * separately whether a slot was actually granted — idempotency here makes
   * that bookkeeping unnecessary and closes the acquire/release race that
   * bookkeeping was prone to.
   */
  readonly cancel: () => void;
}

/**
 * Reserve a build slot, queueing FIFO when the cap is already held, up to
 * `maxQueueWaitMs` (defaults to `MAX_QUEUE_WAIT_MS`; overridable for tests).
 *
 * Returns a handle rather than a bare promise so a caller that stops waiting
 * — most notably an `Effect` fiber interrupted mid-queue on a client
 * disconnect — can cancel cleanly instead of leaking the slot a later
 * `releaseBuildSlot` would otherwise hand to a waiter nobody is listening to
 * anymore.
 */
export const acquireBuildSlot = (maxQueueWaitMs: number = MAX_QUEUE_WAIT_MS): BuildSlotHandle => {
  const requestedAt = Date.now();

  if (activeBuilds < MAX_CONCURRENT_BUILDS) {
    activeBuilds += 1;
    let released = false;
    return {
      promise: Promise.resolve({ acquired: true, waitMs: 0, timedOut: false }),
      cancel: () => {
        if (released) return;
        released = true;
        releaseBuildSlot();
      },
    };
  }

  let resolvePromise!: (value: BuildSlotResult) => void;
  const promise = new Promise<BuildSlotResult>((resolve) => {
    resolvePromise = resolve;
  });

  const waiter: Waiter = {
    state: "queued",
    grant: () => {
      // Guaranteed "queued" here: `releaseBuildSlot` only reaches a waiter by
      // shifting it out of `waitQueue`, and both other transitions
      // (timeout, cancel) remove the waiter from the queue in the same tick
      // they change its state, so a granted waiter can't have been anything
      // else.
      waiter.state = "granted";
      activeBuilds += 1;
      resolvePromise({ acquired: true, waitMs: Date.now() - requestedAt, timedOut: false });
    },
  };
  waitQueue.push(waiter);

  const timer = setTimeout(() => {
    if (waiter.state !== "queued") return;
    waiter.state = "timed-out";
    const idx = waitQueue.indexOf(waiter);
    if (idx !== -1) waitQueue.splice(idx, 1);
    resolvePromise({ acquired: false, waitMs: Date.now() - requestedAt, timedOut: true });
  }, maxQueueWaitMs);

  return {
    promise,
    cancel: () => {
      clearTimeout(timer);
      if (waiter.state === "queued") {
        waiter.state = "cancelled";
        const idx = waitQueue.indexOf(waiter);
        if (idx !== -1) waitQueue.splice(idx, 1);
        return;
      }
      if (waiter.state === "granted") {
        // Grant already happened (raced with a concurrent `releaseBuildSlot`
        // shifting this waiter off the queue) before this cancel ran, and
        // the caller never got to consume the slot — hand it back now
        // instead of leaking it.
        waiter.state = "cancelled";
        releaseBuildSlot();
        return;
      }
      // "timed-out": never held a slot. "cancelled": a prior call already
      // handled this. Either way, nothing to do — idempotent no-op.
    },
  };
};

/**
 * Release a build slot. Must be called exactly once per slot a caller
 * actually acquired (i.e. `acquireBuildSlot`'s `promise` resolved with
 * `acquired: true`) — callers release from a `finally`/`ensuring` (typically
 * via the returned handle's `cancel`, which is idempotent) so a build that
 * throws, or is interrupted, still frees its slot and never deadlocks the
 * queue behind it.
 *
 * Wakes the next FIFO waiter, if any, handing it the freed slot directly
 * rather than making it race a fresh `acquireBuildSlot` caller.
 */
export const releaseBuildSlot = (): void => {
  activeBuilds = Math.max(0, activeBuilds - 1);
  const next = waitQueue.shift();
  if (next) next.grant();
};

/** Test-only: isolate-scoped module state outlives a single test case. */
export const resetBuildSlotsForTest = (): void => {
  activeBuilds = 0;
  waitQueue.length = 0;
};

export const currentActiveBuildsForTest = (): number => activeBuilds;

export const currentQueueLengthForTest = (): number => waitQueue.length;