sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Deadline/ Budget.ts

import * as deadline from "@distilled.cloud/aws/deadline";
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 { createInternalTags, hasAlchemyTags, type Tags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as EffectStream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  asPlain,
  deadlineArnOf,
  fetchDeadlineTags,
  retryWhileFarmSettling,
  syncDeadlineTags,
} from "./internal.ts";

export class BudgetInvalidProps extends Data.TaggedError("BudgetInvalidProps")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export class BudgetUnexpectedResponse extends Data.TaggedError("BudgetUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type BudgetStatus = deadline.BudgetStatus;
export type BudgetActionType = deadline.BudgetActionType;

export interface BudgetActionProps {
  /**
   * Action taken when the threshold is crossed
   * (`STOP_SCHEDULING_AND_COMPLETE_TASKS` or
   * `STOP_SCHEDULING_AND_CANCEL_TASKS`).
   */
  type: BudgetActionType;
  /**
   * Percentage of the dollar limit at which the action fires (e.g. `100`).
   */
  thresholdPercentage: number;
  /**
   * A description of the action.
   */
  description?: string;
}

export interface BudgetScheduleProps {
  /**
   * Fixed budget window.
   */
  fixed: {
    /**
     * ISO-8601 start of the budget window (e.g. `2026-01-01T00:00:00Z`).
     */
    startTime: string;
    /**
     * ISO-8601 end of the budget window.
     */
    endTime: string;
  };
}

export interface BudgetProps {
  /**
   * The identifier of the farm the budget belongs to. Changing it replaces
   * the budget.
   */
  farmId: string;
  /**
   * The identifier of the queue whose usage the budget tracks. Changing it
   * replaces the budget.
   */
  queueId: string;
  /**
   * Display name of the budget.
   * @default ${app}-${stage}-${id}
   */
  displayName?: string;
  /**
   * A description of the budget.
   */
  description?: string;
  /**
   * Approximate dollar limit of the budget.
   */
  approximateDollarLimit: number;
  /**
   * Threshold actions taken as usage approaches the limit.
   */
  actions: BudgetActionProps[];
  /**
   * The period the budget is measured over.
   */
  schedule: BudgetScheduleProps;
  /**
   * Whether the budget is evaluated (`ACTIVE`) or ignored (`INACTIVE`).
   * @default "ACTIVE"
   */
  status?: BudgetStatus;
  /**
   * Tags to associate with the budget.
   */
  tags?: Record<string, string>;
}

export interface Budget extends Resource<
  "AWS.Deadline.Budget",
  BudgetProps,
  {
    /**
     * The identifier of the farm the budget belongs to.
     */
    farmId: string;
    /**
     * Service-assigned unique identifier of the budget (`budget-...`).
     */
    budgetId: string;
    /**
     * ARN of the budget.
     */
    budgetArn: string;
    /**
     * The identifier of the queue whose usage the budget tracks.
     */
    queueId: string;
    /**
     * The budget's display name.
     */
    displayName: string;
    /**
     * Whether the budget is currently evaluated.
     */
    status: BudgetStatus;
    /**
     * The configured approximate dollar limit.
     */
    approximateDollarLimit: number;
    /**
     * Current tags reported for the budget.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An AWS Deadline Cloud budget — tracks a queue's approximate render spend
 * over a fixed window and stops scheduling when thresholds are crossed.
 *
 * ### Creating Budgets
 * **Example:** Queue Budget with Hard Stop
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const budget = yield* AWS.Deadline.Budget("MonthlyBudget", {
 *   farmId: farm.farmId,
 *   queueId: queue.queueId,
 *   approximateDollarLimit: 100,
 *   actions: [
 *     { type: "STOP_SCHEDULING_AND_COMPLETE_TASKS", thresholdPercentage: 100 },
 *   ],
 *   schedule: {
 *     fixed: {
 *       startTime: "2026-01-01T00:00:00Z",
 *       endTime: "2027-01-01T00:00:00Z",
 *     },
 *   },
 * });
 * ```
 *
 * **Example:** Graduated Thresholds
 * ```typescript
 * // Let in-flight tasks finish at 90%, cancel everything at 100%.
 * const budget = yield* AWS.Deadline.Budget("QueueBudget", {
 *   farmId: farm.farmId,
 *   queueId: queue.queueId,
 *   approximateDollarLimit: 500,
 *   actions: [
 *     { type: "STOP_SCHEDULING_AND_COMPLETE_TASKS", thresholdPercentage: 90 },
 *     { type: "STOP_SCHEDULING_AND_CANCEL_TASKS", thresholdPercentage: 100 },
 *   ],
 *   schedule: {
 *     fixed: {
 *       startTime: "2026-01-01T00:00:00Z",
 *       endTime: "2026-02-01T00:00:00Z",
 *     },
 *   },
 * });
 * ```
 *
 * @resource
 */
export const Budget = Resource<Budget>("AWS.Deadline.Budget");

const createBudgetName = (id: string, props: { displayName?: string | undefined }) =>
  props.displayName
    ? Effect.succeed(props.displayName)
    : createPhysicalName({ id, maxLength: 100 });

interface BudgetState {
  attrs: Budget["Attributes"];
  described: deadline.GetBudgetResponse;
}

const readBudgetById = Effect.fn(function* (
  farmId: string,
  budgetId: string,
  arnOf: (path: string) => string,
) {
  const described = yield* deadline
    .getBudget({ farmId, budgetId })
    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  if (!described) return undefined;
  const budgetArn = arnOf(`farm/${farmId}/budget/${described.budgetId}`);
  const state: BudgetState = {
    described,
    attrs: {
      farmId,
      budgetId: described.budgetId,
      budgetArn,
      queueId: described.usageTrackingResource.queueId,
      displayName: described.displayName,
      status: described.status,
      approximateDollarLimit: described.approximateDollarLimit,
      tags: yield* fetchDeadlineTags(budgetArn),
    },
  };
  return state;
});

const findBudgetByDisplayName = Effect.fn(function* (
  farmId: string,
  displayName: string,
  arnOf: (path: string) => string,
) {
  const summaries = yield* deadline.listBudgets.items({ farmId }).pipe(
    EffectStream.runCollect,
    Effect.map((chunk) => Array.from(chunk)),
    // The parent farm may itself be gone.
    Effect.catchTag("ResourceNotFoundException", () =>
      Effect.succeed([] as deadline.BudgetSummary[]),
    ),
  );
  const match = summaries.find((summary) => summary.displayName === displayName);
  if (!match) return undefined;
  return yield* readBudgetById(farmId, match.budgetId, arnOf);
});

const actionKey = (action: { type: BudgetActionType; thresholdPercentage: number }) =>
  `${action.type}@${action.thresholdPercentage}`;

const toWireSchedule = (schedule: BudgetScheduleProps): deadline.BudgetSchedule => ({
  fixed: {
    startTime: new Date(schedule.fixed.startTime),
    endTime: new Date(schedule.fixed.endTime),
  },
});

export const BudgetProvider = () =>
  Provider.effect(
    Budget,
    Effect.gen(function* () {
      return {
        stables: ["farmId", "budgetId", "budgetArn", "queueId"],
        // Keyed by a parent farm — sub-resource list() convention.
        list: () => Effect.succeed([]),
        read: Effect.fn(function* ({ id, olds, output }) {
          const arnOf = yield* deadlineArnOf;
          const farmId = output?.farmId ?? olds?.farmId;
          if (farmId === undefined) return undefined;
          const state = output?.budgetId
            ? yield* readBudgetById(farmId, output.budgetId, arnOf)
            : yield* findBudgetByDisplayName(
                farmId,
                yield* createBudgetName(id, olds ?? {}),
                arnOf,
              );
          if (!state) return undefined;
          return (yield* hasAlchemyTags(id, state.attrs.tags as Tags))
            ? state.attrs
            : Unowned(state.attrs);
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return;
          if (olds === undefined) return;
          // The parent farm and tracked queue are fixed at creation.
          if (olds.farmId !== news.farmId || olds.queueId !== news.queueId) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          if (news === undefined) {
            return yield* new BudgetInvalidProps({ message: "AWS.Deadline.Budget requires props" });
          }
          const arnOf = yield* deadlineArnOf;
          const farmId = news.farmId;
          const displayName = yield* createBudgetName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };
          const desiredSchedule = toWireSchedule(news.schedule);

          // Observe.
          let state = output?.budgetId
            ? yield* readBudgetById(farmId, output.budgetId, arnOf)
            : yield* findBudgetByDisplayName(farmId, displayName, arnOf);

          // Ensure.
          if (state === undefined) {
            const created = yield* retryWhileFarmSettling(
              deadline.createBudget({
                farmId,
                displayName,
                description: news.description,
                usageTrackingResource: { queueId: news.queueId },
                approximateDollarLimit: news.approximateDollarLimit,
                actions: news.actions,
                schedule: desiredSchedule,
                tags: desiredTags,
              }),
            );
            yield* session.note(`Created budget ${displayName} (${created.budgetId})`);
            state = yield* readBudgetById(farmId, created.budgetId, arnOf);
            if (state === undefined) {
              return yield* new BudgetUnexpectedResponse({
                message: `failed to read created budget ${displayName}`,
              });
            }
          }

          // Sync mutable settings — compute action/schedule deltas from
          // OBSERVED state.
          const described = state.described;
          const observedActions = described.actions.map((action) => ({
            type: action.type,
            thresholdPercentage: action.thresholdPercentage,
          }));
          const observedKeys = new Set(observedActions.map(actionKey));
          const desiredKeys = new Set(news.actions.map(actionKey));
          const actionsToAdd = news.actions.filter(
            (action) => !observedKeys.has(actionKey(action)),
          );
          const actionsToRemove = observedActions.filter(
            (action) => !desiredKeys.has(actionKey(action)),
          );
          const observedSchedule = described.schedule.fixed;
          // Deadline clamps a startTime in the past to the creation instant,
          // so a past desired startTime can never converge — only compare it
          // while it is still in the future.
          const now = yield* Effect.sync(() => Date.now());
          const desiredStart = desiredSchedule.fixed.startTime.getTime();
          const scheduleDrifted =
            (desiredStart > now && observedSchedule.startTime.getTime() !== desiredStart) ||
            observedSchedule.endTime.getTime() !== desiredSchedule.fixed.endTime.getTime();
          const desiredStatus = news.status ?? described.status;
          const needsUpdate =
            displayName !== described.displayName ||
            (news.description !== undefined &&
              news.description !== (asPlain(described.description) ?? "")) ||
            desiredStatus !== described.status ||
            news.approximateDollarLimit !== described.approximateDollarLimit ||
            actionsToAdd.length > 0 ||
            actionsToRemove.length > 0 ||
            scheduleDrifted;
          if (needsUpdate) {
            yield* retryWhileFarmSettling(
              deadline.updateBudget({
                farmId,
                budgetId: state.attrs.budgetId,
                displayName,
                description: news.description,
                status: news.status,
                approximateDollarLimit: news.approximateDollarLimit,
                actionsToAdd: actionsToAdd.length > 0 ? actionsToAdd : undefined,
                actionsToRemove: actionsToRemove.length > 0 ? actionsToRemove : undefined,
                schedule: scheduleDrifted ? desiredSchedule : undefined,
              }),
            );
            yield* session.note(`Updated budget ${displayName}`);
          }

          // Sync tags — diff against observed cloud tags.
          yield* syncDeadlineTags(state.attrs.budgetArn, desiredTags);

          yield* session.note(state.attrs.budgetArn);
          const final = yield* readBudgetById(farmId, state.attrs.budgetId, arnOf);
          if (!final) {
            return yield* new BudgetUnexpectedResponse({
              message: `failed to read reconciled budget ${displayName}`,
            });
          }
          return final.attrs;
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* deadline
            .deleteBudget({
              farmId: output.farmId,
              budgetId: output.budgetId,
            })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      };
    }),
  );