session.ts

import { createForks, teardownForks } from "@tigrisdata/agent-kit";
import { executePromote } from "./promote.js";
import { recordQuarantine } from "./quarantine.js";
import type {
  ForkContext,
  ImmutableSessionOptions,
  PromoteStrategy,
  QuarantineRecord,
  SessionState,
  ValidationResult,
} from "./types.js";

type SessionStatus = "active" | "promoted" | "quarantined" | "torn-down";

export class TigrisSession {
  readonly bucket: string;
  readonly parentBucket: string;
  readonly parentCheckpointId?: string;

  private readonly state: SessionState;
  private status: SessionStatus = "active";

  private constructor(state: SessionState) {
    this.state = state;
    this.bucket = state.fork.bucket;
    this.parentBucket = state.parentBucket;
    this.parentCheckpointId = state.parentCheckpointId;
  }

  static async start(opts: ImmutableSessionOptions): Promise<TigrisSession> {
    const role = opts.credentials?.role ?? "Editor";

    const result = await createForks(opts.source, 1, {
      credentials: { role },
      config: opts.config,
    });
    if (result.error) {
      throw new Error(`createForks failed: ${result.error.message}`, {
        cause: result.error,
      });
    }

    const forks = result.data;
    const fork = forks.forks[0];
    if (!fork) {
      await safeTeardown(forks, opts.config);
      throw new Error("createForks returned no forks");
    }
    if (!fork.credentials?.accessKeyId || !fork.credentials.secretAccessKey) {
      await safeTeardown(forks, opts.config);
      throw new Error(
        "createForks did not return scoped credentials for the fork — did the role param get dropped?",
      );
    }

    return new TigrisSession({
      forks,
      fork,
      parentBucket: opts.source,
      parentCheckpointId: forks.snapshotId,
      validator: opts.validate,
      promoteStrategy: opts.promote ?? "pointer-swap",
      config: opts.config,
    });
  }

  /**
   * Build a ForkContext for the active session. Throws if the session has been
   * promoted, quarantined, or torn down — credentials and bucket access are no
   * longer guaranteed to be valid in those states.
   */
  forkContext(): ForkContext {
    if (this.status !== "active") {
      throw new Error(
        `Session is in status '${this.status}'; cannot derive a ForkContext after promote/quarantine/teardown`,
      );
    }
    const creds = this.state.fork.credentials!;
    return {
      bucket: this.state.fork.bucket,
      accessKeyId: creds.accessKeyId,
      secretAccessKey: creds.secretAccessKey,
      parentBucket: this.state.parentBucket,
      parentCheckpointId: this.state.parentCheckpointId,
    };
  }

  async run<T>(fn: (ctx: ForkContext) => Promise<T>): Promise<T> {
    return fn(this.forkContext());
  }

  async validate(): Promise<ValidationResult> {
    if (!this.state.validator) {
      return { passed: true };
    }
    return this.state.validator(this.forkContext());
  }

  async promote(strategy?: PromoteStrategy): Promise<void> {
    if (this.status !== "active") {
      throw new Error(`Cannot promote: session is '${this.status}'`);
    }
    const useStrategy = strategy ?? this.state.promoteStrategy;
    await executePromote(
      useStrategy,
      this.forkContext(),
      this.state.parentBucket,
      this.state.config,
    );
    this.status = "promoted";
  }

  async quarantine(opts: { reason: string }): Promise<QuarantineRecord> {
    if (this.status !== "active") {
      throw new Error(`Cannot quarantine: session is '${this.status}'`);
    }
    const record: QuarantineRecord = {
      bucket: this.state.fork.bucket,
      reason: opts.reason,
      quarantinedAt: new Date(),
      parentBucket: this.state.parentBucket,
      parentCheckpointId: this.state.parentCheckpointId,
    };
    await recordQuarantine(record, this.state.config);
    this.status = "quarantined";
    return record;
  }

  /**
   * Idempotent. Promoted or quarantined sessions are no-ops (the fork is intentionally
   * preserved). Active sessions tear down the fork bucket. Multiple calls are safe.
   */
  async teardown(): Promise<void> {
    if (this.status === "torn-down") return;

    if (this.status === "promoted" || this.status === "quarantined") {
      this.status = "torn-down";
      return;
    }

    const result = await teardownForks(this.state.forks, {
      config: this.state.config,
    });
    this.status = "torn-down";
    if (result.error) {
      throw new Error(`teardownForks failed: ${result.error.message}`, {
        cause: result.error,
      });
    }
  }
}

async function safeTeardown(
  forks: Parameters<typeof teardownForks>[0],
  config: ImmutableSessionOptions["config"],
): Promise<void> {
  try {
    await teardownForks(forks, { config });
  } catch {
    // best-effort: failure during partial-init cleanup is logged-and-ignored
  }
}