sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Batch/ JobQueue.ts

import * as batch from "@distilled.cloud/aws/batch";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { AWSEnvironment, type AccountID } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
import { pollBatch, retryBatch } from "./internal.ts";

export type JobQueueName = string;
export type JobQueueArn = `arn:aws:batch:${RegionID}:${AccountID}:job-queue/${JobQueueName}`;

/**
 * Raised when a job queue's asynchronous deletion does not complete within
 * the provider's poll budget. Reporting success here would let the engine
 * delete the queue's compute environments while the association still exists,
 * wedging the whole chain.
 */
export class JobQueueDeleteTimeoutError extends Data.TaggedError("JobQueueDeleteTimeoutError")<{
  readonly jobQueueName: string;
  readonly status: string | undefined;
  readonly statusReason: string | undefined;
  readonly message: string;
}> {}

export interface JobQueueProps {
  /**
   * Name of the job queue. If omitted, a unique name is generated.
   * Up to 128 characters (letters, numbers, hyphens, underscores).
   */
  jobQueueName?: string;
  /**
   * Compute environment ARNs the queue schedules onto, in preference order
   * (index 0 is tried first).
   */
  computeEnvironments: string[];
  /**
   * Queue priority — queues with a higher value are evaluated first when
   * they share compute environments.
   * @default 1
   */
  priority?: number;
  /**
   * Whether the queue accepts new job submissions.
   * @default "ENABLED"
   */
  state?: "ENABLED" | "DISABLED";
  /**
   * User-defined tags to apply to the job queue.
   */
  tags?: Record<string, string>;
}

export interface JobQueue extends Resource<
  "AWS.Batch.JobQueue",
  JobQueueProps,
  {
    jobQueueName: JobQueueName;
    jobQueueArn: JobQueueArn;
    state: "ENABLED" | "DISABLED";
    status: string;
    priority: number;
    computeEnvironments: string[];
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An AWS Batch job queue. Jobs submitted to the queue are scheduled onto its
 * associated compute environments in preference order.
 *
 * ### Creating Job Queues
 * **Example:** Queue on a Fargate Compute Environment
 * ```typescript
 * const ce = yield* Batch.ComputeEnvironment("JobsCE", {});
 * const queue = yield* Batch.JobQueue("JobsQueue", {
 *   computeEnvironments: [ce.computeEnvironmentArn],
 * });
 * ```
 *
 * **Example:** Prioritized queue
 * ```typescript
 * const critical = yield* Batch.JobQueue("CriticalQueue", {
 *   priority: 10,
 *   computeEnvironments: [ce.computeEnvironmentArn],
 * });
 * ```
 *
 * @resource
 */
export const JobQueue = Resource<JobQueue>("AWS.Batch.JobQueue");

const toAttributes = (q: batch.JobQueueDetail, tags: Record<string, string>) => ({
  jobQueueName: q.jobQueueName!,
  jobQueueArn: q.jobQueueArn as JobQueueArn,
  state: (q.state ?? "ENABLED") as "ENABLED" | "DISABLED",
  status: q.status ?? "VALID",
  priority: q.priority ?? 1,
  computeEnvironments: [...(q.computeEnvironmentOrder ?? [])]
    .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
    .flatMap((o) => (o.computeEnvironment ? [o.computeEnvironment] : [])),
  tags,
});

const observedTagsOf = (q: { tags?: { [key: string]: string | undefined } }) =>
  Object.fromEntries(
    Object.entries(q.tags ?? {}).filter((e): e is [string, string] => typeof e[1] === "string"),
  );

const toOrder = (computeEnvironments: string[]): batch.ComputeEnvironmentOrder[] =>
  computeEnvironments.map((computeEnvironment, index) => ({
    order: index + 1,
    computeEnvironment,
  }));

export const JobQueueProvider = () =>
  Provider.effect(
    JobQueue,
    Effect.gen(function* () {
      const toName = (id: string, props: { jobQueueName?: string } = {}) =>
        props.jobQueueName
          ? Effect.succeed(props.jobQueueName)
          : createPhysicalName({ id, maxLength: 128 });

      // A deleted queue lingers as a DELETED record for a while and the name
      // is immediately reusable, so a describe-by-name can briefly return
      // both the tombstone and the live queue — prefer the live one.
      const describeOne = (name: string) =>
        batch
          .describeJobQueues({ jobQueues: [name] })
          .pipe(
            Effect.map(
              (res) => res.jobQueues?.find((q) => q.status !== "DELETED") ?? res.jobQueues?.[0],
            ),
          );

      /** Wait until any CREATING/UPDATING/DELETING transition settles. */
      const awaitSettled = (name: string) =>
        pollBatch(
          describeOne(name),
          (q) =>
            q === undefined ||
            (q.status !== "CREATING" && q.status !== "UPDATING" && q.status !== "DELETING"),
        );

      const awaitDisabled = (name: string) =>
        pollBatch(
          describeOne(name),
          (queue) =>
            queue === undefined ||
            queue.status === "DELETED" ||
            queue.status === "DELETING" ||
            (queue.state === "DISABLED" &&
              queue.status !== "CREATING" &&
              queue.status !== "UPDATING"),
        );

      return {
        stables: ["jobQueueName", "jobQueueArn"],
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return;
          if ((yield* toName(id, olds ?? {})) !== (yield* toName(id, news ?? {}))) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.jobQueueName ?? (yield* toName(id, olds ?? {}));
          const q = yield* describeOne(name);
          if (!q?.jobQueueArn || q.status === "DELETED") {
            return undefined;
          }
          return toAttributes(q, observedTagsOf(q));
        }),
        list: () =>
          Effect.gen(function* () {
            const pages = yield* batch.describeJobQueues.pages({}).pipe(Stream.runCollect);
            return Array.from(pages)
              .flatMap((page) => page.jobQueues ?? [])
              .flatMap((q) =>
                q.jobQueueArn && q.status !== "DELETED" ? [toAttributes(q, observedTagsOf(q))] : [],
              );
          }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const name = output?.jobQueueName ?? (yield* toName(id, news));
          const arn = `arn:aws:batch:${region}:${accountId}:job-queue/${name}` as JobQueueArn;
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };
          const desiredState = news.state ?? "ENABLED";
          const desiredPriority = news.priority ?? 1;
          const desiredOrder = toOrder(news.computeEnvironments);

          // Observe — cloud state is authoritative.
          let queue = yield* describeOne(name);
          if (queue?.status === "DELETED") queue = undefined;

          // Ensure — create if missing. The referenced compute environment may
          // still be settling to VALID (its own reconcile waits, but adoption
          // or manual drift can race) — retry through that window, and treat
          // a concurrent create as a race to observe.
          const create = retryBatch(
            batch.createJobQueue({
              jobQueueName: name,
              state: desiredState,
              priority: desiredPriority,
              computeEnvironmentOrder: desiredOrder,
              tags: desiredTags,
            }),
            (e) => e._tag === "ComputeEnvironmentNotValid",
          ).pipe(Effect.catchTag("JobQueueAlreadyExists", () => Effect.void));

          if (queue?.jobQueueArn && queue.status === "DELETING") {
            // An interrupted destroy left the queue mid-deletion — let it
            // finish, then fall through to a fresh create below.
            queue = yield* awaitSettled(name);
            if (queue?.status === "DELETED") queue = undefined;
          }
          if (!queue?.jobQueueArn) {
            yield* create;
            queue = yield* awaitSettled(name);
          } else if (queue.status !== "VALID" && queue.status !== "INVALID") {
            queue = yield* awaitSettled(name);
          }
          if (queue?.status === "DELETED") {
            // The settle above can still land on a tombstone (deletion that
            // completed between observe and settle) — one more create pass.
            yield* create;
            queue = yield* awaitSettled(name);
          }

          if (!queue?.jobQueueArn) {
            return yield* Effect.die(new Error(`JobQueue ${name} did not settle`));
          }

          // Sync — diff observed against desired, apply only the delta.
          const observedOrder = [...(queue.computeEnvironmentOrder ?? [])]
            .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
            .map((o) => o.computeEnvironment)
            .join(",");
          const update: batch.UpdateJobQueueRequest = { jobQueue: name };
          let dirty = false;
          if ((queue.state ?? "ENABLED") !== desiredState) {
            update.state = desiredState;
            dirty = true;
          }
          if ((queue.priority ?? 1) !== desiredPriority) {
            update.priority = desiredPriority;
            dirty = true;
          }
          if (observedOrder !== news.computeEnvironments.join(",")) {
            update.computeEnvironmentOrder = desiredOrder;
            dirty = true;
          }
          if (dirty) {
            yield* retryBatch(
              batch.updateJobQueue(update),
              (e) => e._tag === "JobQueueBeingModified",
            );
            queue = (yield* awaitSettled(name)) ?? queue;
          }

          // Sync tags — diff against OBSERVED cloud tags.
          const { upsert, removed } = diffTags(observedTagsOf(queue), desiredTags);
          if (upsert.length > 0) {
            yield* batch.tagResource({
              resourceArn: arn,
              tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* batch.untagResource({ resourceArn: arn, tagKeys: removed });
          }

          yield* session.note(arn);
          return toAttributes({ ...queue, jobQueueName: name, jobQueueArn: arn }, desiredTags);
        }),
        delete: Effect.fn(function* ({ output }) {
          const name = output.jobQueueName;
          const existing = yield* describeOne(name);
          if (!existing || existing.status === "DELETED") return;

          // Must be DISABLED before deletion.
          if ((existing.state ?? "ENABLED") !== "DISABLED" && existing.status !== "DELETING") {
            yield* retryBatch(
              batch.updateJobQueue({ jobQueue: name, state: "DISABLED" }),
              (e) => e._tag === "JobQueueBeingModified",
            ).pipe(Effect.catchTag("JobQueueNotFound", () => Effect.void));
          }
          const disabled = yield* awaitDisabled(name);
          if (!disabled || disabled.status === "DELETED") return;

          // A resumed destroy can observe DELETING. Do not issue a redundant
          // delete; just wait for the relationship to disappear. This keeps
          // the downstream compute-environment delete strictly ordered.
          if (disabled.status !== "DELETING") {
            yield* retryBatch(
              batch.deleteJobQueue({ jobQueue: name }),
              (e) => e._tag === "JobQueueBeingModified",
            ).pipe(Effect.catchTag("JobQueueNotFound", () => Effect.void));
          }

          // Wait until fully gone so downstream compute-environment deletion
          // doesn't trip over the lingering association (queue deletion is
          // asynchronous and takes up to ~1-2 minutes). An expired poll MUST
          // NOT report success — the engine would then delete the queue's
          // compute environments mid-teardown and wedge the chain.
          const final = yield* pollBatch(
            describeOne(name),
            (q) => q === undefined || q.status === "DELETED",
          );
          if (final && final.status !== "DELETED") {
            return yield* new JobQueueDeleteTimeoutError({
              jobQueueName: name,
              status: final.status,
              statusReason: final.statusReason,
              message: `Job queue ${name} was still ${final.status ?? "present"} after the delete poll budget${final.statusReason ? `: ${final.statusReason}` : ""}`,
            });
          }
        }),
      };
    }),
  );