sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ CloudTasks/ Queue.ts

import * as cloudtasks from "@distilled.cloud/gcp/cloudtasks_v2";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { GcpEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";

const DEFAULT_STATE = "RUNNING" as const;
const MAX_QUEUE_ID_LENGTH = 100;

export type QueueRetryConfig = {
  /** Attempts per task, including the first. `-1` means unlimited. */
  maxAttempts?: number;
  /** Time limit for retrying a failed task, e.g. `"3600s"`. `"0s"` is unlimited. */
  maxRetryDuration?: string;
  /** Minimum backoff after a failed attempt, e.g. `"0.1s"`. */
  minBackoff?: string;
  /** Maximum backoff after a failed attempt, e.g. `"3600s"`. */
  maxBackoff?: string;
  /** Times the retry interval doubles before increasing linearly. */
  maxDoublings?: number;
};

export type QueueRateLimits = {
  /** Maximum dispatch rate (tasks per second). Max `500`. */
  maxDispatchesPerSecond?: number;
  /** Maximum concurrent dispatches. Max `5000`. */
  maxConcurrentDispatches?: number;
};

export type QueueStackdriverLoggingConfig = {
  /** Fraction of operations to log, in `[0.0, 1.0]`. `0` logs nothing. */
  samplingRatio?: number;
};

export type QueueHttpTarget = cloudtasks.HttpTarget;
export type QueueAppEngineRouting = cloudtasks.AppEngineRouting;

export type QueueState = "RUNNING" | "PAUSED";

export type QueueProps = {
  /**
   * Queue id (the `{queue}` segment of
   * `projects/{project}/locations/{location}/queues/{queue}`). If omitted,
   * a unique name is generated from the stack, stage, and logical id.
   * Immutable — changing it replaces the queue.
   */
  queueId?: string;
  /**
   * Location of the queue (e.g. `us-central1`). Immutable — changing it
   * replaces the queue. `US-CENTRAL1` is accepted and normalized to
   * `us-central1`.
   * @default the stack's GCP region (`GCP.Region`, else the profile region, else `us-central1`)
   */
  location?: string;
  /**
   * Queue-level retry settings applied to Cloud Tasks–created tasks.
   * Omitted fields keep the values Cloud Tasks currently has (including
   * API defaults).
   */
  retryConfig?: QueueRetryConfig;
  /**
   * Dispatch rate limits. `maxBurstSize` is output-only and not settable.
   * Omitted fields keep the current Cloud Tasks values.
   */
  rateLimits?: QueueRateLimits;
  /**
   * Cloud Logging sampling. If omitted, existing logging config is left
   * unchanged.
   */
  stackdriverLoggingConfig?: QueueStackdriverLoggingConfig;
  /**
   * Queue-level HTTP target overrides for HTTP tasks. If omitted, the
   * queue's current overrides are left unchanged.
   */
  httpTarget?: QueueHttpTarget;
  /**
   * App Engine routing override for App Engine tasks in this queue.
   */
  appEngineRoutingOverride?: QueueAppEngineRouting;
  /**
   * Desired queue state. `UpdateQueue` cannot change state — Alchemy
   * calls PauseQueue / ResumeQueue. `DISABLED` is queue.yaml-only and
   * is not settable here.
   * @default "RUNNING"
   */
  state?: QueueState;
};

export type Queue = Resource<
  "GCP.CloudTasks.Queue",
  QueueProps,
  {
    /** Full resource name `projects/{project}/locations/{location}/queues/{queue}`. */
    name: string;
    /** Queue id (last path segment). */
    queueId: string;
    /** Project id. */
    project: string;
    /** Location id (e.g. `us-central1`). */
    location: string;
    /** Server-reported state (`RUNNING`, `PAUSED`, `DISABLED`). */
    state: string | undefined;
    /** Retry settings currently on the queue. */
    retryConfig: QueueRetryConfig | undefined;
    /** Dispatch rate limits currently on the queue. */
    rateLimits: QueueRateLimits | undefined;
    /** Logging config currently on the queue. */
    stackdriverLoggingConfig: QueueStackdriverLoggingConfig | undefined;
    /** Queue-level HTTP target overrides. */
    httpTarget: QueueHttpTarget | undefined;
    /** App Engine routing override, if any. */
    appEngineRoutingOverride: QueueAppEngineRouting | undefined;
    /** Last purge time, if the queue has ever been purged. */
    purgeTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Google Cloud Tasks queue.
 *
 * Cloud Tasks queues have no labels, so Alchemy identifies its queues by
 * the generated `queueId`: `read` reports a queue with an explicit
 * `queueId` as unowned (adopt it with `--adopt`), and nuke cannot
 * discover queues.
 *
 * Changing `queueId` or `location` replaces the queue. Deleted queue
 * names are tombstoned for up to 3 days — CreateQueue may appear to
 * succeed; GetQueue is the source of truth.
 *
 * ### Creating a Queue
 * **Example:** Generated name
 * ```typescript
 * const queue = yield* GCP.CloudTasks.Queue("jobs", {});
 * ```
 *
 * **Example:** Rate limits, retries, and logging
 * ```typescript
 * const queue = yield* GCP.CloudTasks.Queue("jobs", {
 *   location: "us-central1",
 *   rateLimits: {
 *     maxDispatchesPerSecond: 10,
 *     maxConcurrentDispatches: 5,
 *   },
 *   retryConfig: {
 *     maxAttempts: 5,
 *     minBackoff: "1s",
 *     maxBackoff: "60s",
 *   },
 *   stackdriverLoggingConfig: { samplingRatio: 1 },
 * });
 * ```
 *
 * **Example:** Paused queue
 * ```typescript
 * const queue = yield* GCP.CloudTasks.Queue("jobs", {
 *   state: "PAUSED",
 * });
 * ```
 *
 * @resource
 * @category CloudTasks
 */
export const Queue = Resource<Queue>("GCP.CloudTasks.Queue");

export class QueueNotResolved extends Data.TaggedError("GCP.CloudTasks.QueueNotResolved")<{
  resourceName: string;
}> {}

const lastSegment = (value: string) => {
  const trimmed = value.replace(/\/+$/, "");
  const parts = trimmed.split("/");
  return parts[parts.length - 1] || trimmed;
};

const normalizeLocation = (location: string | undefined, fallback: string) =>
  lastSegment(location ?? fallback).toLowerCase();

const parseName = (name: string) => {
  const parts = name.split("/");
  return {
    project: parts[1] ?? "",
    location: parts[3] ?? "",
    queueId: parts[5] ?? lastSegment(name),
  };
};

const resourceName = (project: string, location: string, queueId: string) =>
  `projects/${project}/locations/${location}/queues/${queueId}`;

const locationParent = (project: string, location: string) =>
  `projects/${project}/locations/${location}`;

const toQueueId = (id: string, queueId: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (queueId !== undefined) return queueId;
    if (existing !== undefined) return existing;
    const generated = yield* createPhysicalName({
      id,
      maxLength: MAX_QUEUE_ID_LENGTH,
      lowercase: true,
    });
    const named = /^[a-z]/.test(generated) ? generated : `q${generated}`;
    return named.replace(/-+$/g, "").slice(0, MAX_QUEUE_ID_LENGTH);
  });

const sortHeaderOverrides = (
  headers: cloudtasks.HeaderOverrideList | undefined,
): cloudtasks.HeaderOverrideList =>
  [...(headers ?? [])]
    .map((item) => ({
      header: {
        key: item.header?.key?.toLowerCase(),
        value: item.header?.value,
      },
    }))
    .sort((left, right) => (left.header?.key ?? "").localeCompare(right.header?.key ?? ""));

const stable = (value: unknown): string =>
  JSON.stringify(value, (_key, current) => {
    if (current && typeof current === "object" && !Array.isArray(current)) {
      return Object.fromEntries(
        Object.entries(current as Record<string, unknown>)
          .filter(([, item]) => item !== undefined)
          .sort(([a], [b]) => a.localeCompare(b)),
      );
    }
    return current;
  });

const normalizeDuration = (value: string | undefined) => {
  if (value === undefined) return undefined;
  const match = /^([0-9]+(?:\.[0-9]+)?)s$/.exec(value.trim());
  if (!match) return value;
  return `${Number(match[1])}s`;
};

const normalizeRetry = (config: QueueRetryConfig) => ({
  maxAttempts: config.maxAttempts,
  maxRetryDuration: normalizeDuration(config.maxRetryDuration),
  minBackoff: normalizeDuration(config.minBackoff),
  maxBackoff: normalizeDuration(config.maxBackoff),
  maxDoublings: config.maxDoublings,
});

const overlayChanged = (
  desired: object | undefined,
  observed: object | undefined,
  normalize: (value: object) => unknown = (value) => value,
): boolean => {
  if (desired === undefined) return false;
  const picked: Record<string, unknown> = {};
  const source = (observed ?? {}) as Record<string, unknown>;
  for (const key of Object.keys(desired)) {
    picked[key] = source[key];
  }
  return stable(normalize(desired)) !== stable(normalize(picked));
};

const toRateLimits = (
  config: QueueRateLimits,
  observed?: cloudtasks.RateLimits,
): cloudtasks.RateLimits => {
  const merged: cloudtasks.RateLimits = { ...observed, ...config };
  delete merged.maxBurstSize;
  return merged;
};

const toUserRateLimits = (
  config: cloudtasks.RateLimits | undefined,
): QueueRateLimits | undefined => {
  if (config === undefined) return undefined;
  const next: QueueRateLimits = {};
  if (config.maxDispatchesPerSecond !== undefined) {
    next.maxDispatchesPerSecond = config.maxDispatchesPerSecond;
  }
  if (config.maxConcurrentDispatches !== undefined) {
    next.maxConcurrentDispatches = config.maxConcurrentDispatches;
  }
  return Object.keys(next).length > 0 ? next : undefined;
};

const toAttrs = (queue: cloudtasks.Queue, project: string): Queue["Attributes"] => {
  const name = queue.name ?? "";
  const parsed = parseName(name);
  return {
    name,
    queueId: parsed.queueId,
    project: parsed.project || project,
    location: parsed.location,
    state: queue.state,
    retryConfig: queue.retryConfig,
    rateLimits: toUserRateLimits(queue.rateLimits),
    stackdriverLoggingConfig: queue.stackdriverLoggingConfig,
    httpTarget: queue.httpTarget,
    appEngineRoutingOverride: queue.appEngineRoutingOverride,
    purgeTime: queue.purgeTime,
  };
};

const getByName = (name: string) =>
  cloudtasks
    .getProjectsLocationsQueues({ name })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const sameHttpTarget = (left: cloudtasks.HttpTarget, right: cloudtasks.HttpTarget | undefined) => {
  const normalize = (target: cloudtasks.HttpTarget | undefined) => {
    if (target === undefined) return undefined;
    return {
      ...target,
      headerOverrides: sortHeaderOverrides(target.headerOverrides),
    };
  };
  return stable(normalize(left)) === stable(normalize(right));
};

export const QueueProvider = () =>
  Provider.succeed(Queue, {
    stables: ["name", "queueId", "project", "location"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      const env = yield* GcpEnvironment.current;
      if (!isResolved(news)) return undefined;
      const previousId = olds?.queueId ?? output?.queueId;
      const nextId = news.queueId ?? previousId;
      const idChanged = previousId !== undefined && nextId !== undefined && nextId !== previousId;

      const previousLocation = normalizeLocation(olds?.location ?? output?.location, env.region);
      const nextLocation = normalizeLocation(news.location ?? output?.location, env.region);
      if (idChanged || previousLocation !== nextLocation) {
        return { action: "replace" as const };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const queueId = yield* toQueueId(id, olds?.queueId, output?.queueId);
      const location = normalizeLocation(olds?.location ?? output?.location, env.region);
      const name = output?.name ?? resourceName(env.project, location, queueId);
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      const generated = yield* toQueueId(id, undefined);
      return attrs.queueId === generated ? attrs : Unowned(attrs);
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const queueId = yield* toQueueId(id, news.queueId, output?.queueId);
      const location = normalizeLocation(news.location ?? output?.location, env.region);
      const name = resourceName(env.project, location, queueId);
      const parent = locationParent(env.project, location);
      const desiredHttpTarget = news.httpTarget;
      const desiredState = news.state ?? DEFAULT_STATE;

      let current = yield* getByName(name);

      if (current === undefined) {
        const body: cloudtasks.Queue = {
          name,
          httpTarget: desiredHttpTarget,
        };
        if (news.retryConfig !== undefined) {
          body.retryConfig = news.retryConfig;
        }
        if (news.rateLimits !== undefined) {
          body.rateLimits = toRateLimits(news.rateLimits);
        }
        if (news.stackdriverLoggingConfig !== undefined) {
          body.stackdriverLoggingConfig = news.stackdriverLoggingConfig;
        }
        if (news.appEngineRoutingOverride !== undefined) {
          body.appEngineRoutingOverride = news.appEngineRoutingOverride;
        }
        // CreateQueue can appear to succeed for a tombstoned name. GetQueue
        // is the source of truth (up to ~3 days after delete).
        yield* cloudtasks
          .createProjectsLocationsQueues({
            parent,
            body,
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.void));
        current = yield* getByName(name);
      }

      if (current === undefined) {
        return yield* new QueueNotResolved({ resourceName: name });
      }

      const mask: string[] = [];
      const patchBody: cloudtasks.Queue = { name };

      if (
        overlayChanged(news.retryConfig, current.retryConfig, (value) =>
          normalizeRetry(value as QueueRetryConfig),
        )
      ) {
        patchBody.retryConfig = {
          ...current.retryConfig,
          ...news.retryConfig,
        };
        mask.push("retryConfig");
      }

      const desiredRateLimits = news.rateLimits;
      if (
        desiredRateLimits !== undefined &&
        overlayChanged(desiredRateLimits, toUserRateLimits(current.rateLimits))
      ) {
        patchBody.rateLimits = toRateLimits(desiredRateLimits, current.rateLimits);
        mask.push("rateLimits");
      }

      if (overlayChanged(news.stackdriverLoggingConfig, current.stackdriverLoggingConfig)) {
        patchBody.stackdriverLoggingConfig = {
          ...current.stackdriverLoggingConfig,
          ...news.stackdriverLoggingConfig,
        };
        mask.push("stackdriverLoggingConfig");
      }

      if (
        desiredHttpTarget !== undefined &&
        !sameHttpTarget(desiredHttpTarget, current.httpTarget)
      ) {
        patchBody.httpTarget = desiredHttpTarget;
        mask.push("httpTarget");
      }

      if (overlayChanged(news.appEngineRoutingOverride, current.appEngineRoutingOverride)) {
        patchBody.appEngineRoutingOverride = {
          ...current.appEngineRoutingOverride,
          ...news.appEngineRoutingOverride,
        };
        mask.push("appEngineRoutingOverride");
      }

      if (mask.length > 0) {
        current = yield* cloudtasks.patchProjectsLocationsQueues({
          name,
          updateMask: mask.join(","),
          body: patchBody,
        });
      }

      if (desiredState === "PAUSED" && current.state === "RUNNING") {
        current = yield* cloudtasks.pauseProjectsLocationsQueues({
          name,
          body: {},
        });
      } else if (
        desiredState === "RUNNING" &&
        (current.state === "PAUSED" || current.state === "DISABLED")
      ) {
        current = yield* cloudtasks.resumeProjectsLocationsQueues({
          name,
          body: {},
        });
      }

      return toAttrs(current, env.project);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* cloudtasks
        .deleteProjectsLocationsQueues({ name: output.name })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),
  });