sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Deadline/ Fleet.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 { toWireHours, toWireSeconds } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as EffectStream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  asPlain,
  deadlineArnOf,
  fetchDeadlineTags,
  retryThroughIamPropagation,
  retryWhileConflict,
  retryWhileFarmSettling,
  syncDeadlineTags,
} from "./internal.ts";

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

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

export type FleetStatus = deadline.FleetStatus;

/**
 * Worker auto-scaling settings for a fleet, with idle time expressed as a
 * `Duration.Input` (converted to whole seconds on the wire).
 */
export interface FleetAutoScalingConfiguration {
  /**
   * Number of idle workers kept on standby to absorb bursts.
   * @default 0
   */
  standbyWorkerCount?: number;
  /**
   * How long a worker may sit idle before it is scaled in
   * (wire: `workerIdleDurationSeconds`).
   * @default "5 minutes"
   */
  workerIdleDuration?: Duration.Input;
  /**
   * Maximum number of workers added per minute when scaling out.
   */
  scaleOutWorkersPerMinute?: number;
}

/**
 * Customer-managed fleet configuration (you run the worker hosts).
 */
export interface CustomerManagedFleetConfiguration extends Omit<
  deadline.CustomerManagedFleetConfiguration,
  "autoScalingConfiguration"
> {
  /**
   * Auto-scaling behavior for `EVENT_BASED_AUTO_SCALING` mode.
   */
  autoScalingConfiguration?: FleetAutoScalingConfiguration;
}

/**
 * Persistent EBS volume settings for service-managed EC2 workers, with the
 * reuse TTL expressed as a `Duration.Input` (converted to whole hours on the
 * wire).
 */
export interface FleetPersistentVolumeConfiguration extends Omit<
  deadline.PersistentVolumeConfiguration,
  "lastUsedTtlHours"
> {
  /**
   * How long an unused persistent volume is retained for reuse before it is
   * deleted (wire: `lastUsedTtlHours`).
   */
  lastUsedTtl?: Duration.Input;
}

/**
 * Service-managed EC2 fleet configuration (Deadline provisions instances).
 */
export interface ServiceManagedEc2FleetConfiguration extends Omit<
  deadline.ServiceManagedEc2FleetConfiguration,
  "autoScalingConfiguration" | "persistentVolumeConfiguration"
> {
  /**
   * Auto-scaling behavior for the EC2 workers.
   */
  autoScalingConfiguration?: FleetAutoScalingConfiguration;
  /**
   * Persistent EBS volume reused across workers.
   */
  persistentVolumeConfiguration?: FleetPersistentVolumeConfiguration;
}

/**
 * Fleet configuration — either `customerManaged` (you run the workers) or
 * `serviceManagedEc2` (Deadline provisions EC2 instances).
 */
export type FleetConfiguration =
  | {
      customerManaged: CustomerManagedFleetConfiguration;
      serviceManagedEc2?: never;
    }
  | {
      customerManaged?: never;
      serviceManagedEc2: ServiceManagedEc2FleetConfiguration;
    };

/**
 * Startup script run on each worker host, with the timeout expressed as a
 * `Duration.Input` (converted to whole seconds on the wire).
 */
export interface FleetHostConfiguration {
  /**
   * The script body executed when a worker host starts.
   */
  scriptBody: string | Redacted.Redacted<string>;
  /**
   * Maximum time the startup script may run before the worker is marked
   * unhealthy (wire: `scriptTimeoutSeconds`).
   * @default "5 minutes"
   */
  scriptTimeout?: Duration.Input;
}

const toWireAutoScaling = (
  config: FleetAutoScalingConfiguration | undefined,
): deadline.CustomerManagedAutoScalingConfiguration | undefined => {
  if (config === undefined) return undefined;
  const { workerIdleDuration, ...rest } = config;
  return {
    ...rest,
    workerIdleDurationSeconds: toWireSeconds(workerIdleDuration),
  };
};

const toWirePersistentVolume = (
  config: FleetPersistentVolumeConfiguration | undefined,
): deadline.PersistentVolumeConfiguration | undefined => {
  if (config === undefined) return undefined;
  const { lastUsedTtl, ...rest } = config;
  return { ...rest, lastUsedTtlHours: toWireHours(lastUsedTtl) };
};

const toWireConfiguration = (config: FleetConfiguration): deadline.FleetConfiguration =>
  config.customerManaged !== undefined
    ? {
        customerManaged: {
          ...config.customerManaged,
          autoScalingConfiguration: toWireAutoScaling(
            config.customerManaged.autoScalingConfiguration,
          ),
        },
      }
    : {
        serviceManagedEc2: {
          ...config.serviceManagedEc2,
          autoScalingConfiguration: toWireAutoScaling(
            config.serviceManagedEc2.autoScalingConfiguration,
          ),
          persistentVolumeConfiguration: toWirePersistentVolume(
            config.serviceManagedEc2.persistentVolumeConfiguration,
          ),
        },
      };

const toWireHostConfiguration = (
  config: FleetHostConfiguration | undefined,
): deadline.HostConfiguration | undefined => {
  if (config === undefined) return undefined;
  const { scriptTimeout, ...rest } = config;
  return { ...rest, scriptTimeoutSeconds: toWireSeconds(scriptTimeout) };
};

export interface FleetProps {
  /**
   * The identifier of the farm the fleet belongs to. Changing it replaces
   * the fleet.
   */
  farmId: string;
  /**
   * Display name of the fleet.
   * @default ${app}-${stage}-${id}
   */
  displayName?: string;
  /**
   * A description of the fleet.
   */
  description?: string;
  /**
   * ARN of the IAM role fleet workers assume (trusted by
   * `credentials.deadline.amazonaws.com`).
   */
  roleArn: string;
  /**
   * Minimum number of workers the fleet keeps running.
   * @default 0
   */
  minWorkerCount?: number;
  /**
   * Maximum number of workers the fleet scales to.
   */
  maxWorkerCount: number;
  /**
   * Fleet configuration — either `customerManaged` (you run the workers) or
   * `serviceManagedEc2` (Deadline provisions EC2 instances).
   */
  configuration: FleetConfiguration;
  /**
   * Script run on each worker host when it starts.
   */
  hostConfiguration?: FleetHostConfiguration;
  /**
   * Tags to associate with the fleet.
   */
  tags?: Record<string, string>;
}

export interface Fleet extends Resource<
  "AWS.Deadline.Fleet",
  FleetProps,
  {
    /**
     * The identifier of the farm the fleet belongs to.
     */
    farmId: string;
    /**
     * Service-assigned unique identifier of the fleet (`fleet-...`).
     */
    fleetId: string;
    /**
     * ARN of the fleet.
     */
    fleetArn: string;
    /**
     * The fleet's display name.
     */
    displayName: string;
    /**
     * Current lifecycle status of the fleet.
     */
    status: FleetStatus;
    /**
     * Number of workers currently in the fleet.
     */
    workerCount: number;
    /**
     * The configured minimum worker count.
     */
    minWorkerCount: number;
    /**
     * The configured maximum worker count.
     */
    maxWorkerCount: number;
    /**
     * ARN of the fleet's worker role.
     */
    roleArn: string;
    /**
     * Current tags reported for the fleet.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An AWS Deadline Cloud fleet — a group of workers (customer-managed hosts
 * or service-managed EC2 instances) that run render jobs from associated
 * queues.
 *
 * ### Creating Fleets
 * **Example:** Customer-Managed Fleet
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const fleet = yield* AWS.Deadline.Fleet("Workers", {
 *   farmId: farm.farmId,
 *   roleArn: fleetRole.roleArn,
 *   maxWorkerCount: 10,
 *   configuration: {
 *     customerManaged: {
 *       mode: "NO_SCALING",
 *       workerCapabilities: {
 *         vCpuCount: { min: 1 },
 *         memoryMiB: { min: 1024 },
 *         osFamily: "LINUX",
 *         cpuArchitectureType: "x86_64",
 *       },
 *     },
 *   },
 * });
 * ```
 *
 * **Example:** Service-Managed EC2 Fleet
 * ```typescript
 * const fleet = yield* AWS.Deadline.Fleet("Workers", {
 *   farmId: farm.farmId,
 *   roleArn: fleetRole.roleArn,
 *   minWorkerCount: 0,
 *   maxWorkerCount: 5,
 *   configuration: {
 *     serviceManagedEc2: {
 *       instanceCapabilities: {
 *         vCpuCount: { min: 2, max: 8 },
 *         memoryMiB: { min: 4096 },
 *         osFamily: "LINUX",
 *         cpuArchitectureType: "x86_64",
 *       },
 *       instanceMarketOptions: { type: "spot" },
 *     },
 *   },
 * });
 * ```
 *
 * @resource
 */
export const Fleet = Resource<Fleet>("AWS.Deadline.Fleet");

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

interface FleetState {
  attrs: Fleet["Attributes"];
  described: deadline.GetFleetResponse;
}

const readFleetById = Effect.fn(function* (
  farmId: string,
  fleetId: string,
  arnOf: (path: string) => string,
) {
  const described = yield* deadline
    .getFleet({ farmId, fleetId })
    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  if (!described) return undefined;
  const fleetArn = arnOf(`farm/${described.farmId}/fleet/${described.fleetId}`);
  const state: FleetState = {
    described,
    attrs: {
      farmId: described.farmId,
      fleetId: described.fleetId,
      fleetArn,
      displayName: described.displayName,
      status: described.status,
      workerCount: described.workerCount,
      minWorkerCount: described.minWorkerCount,
      maxWorkerCount: described.maxWorkerCount,
      roleArn: described.roleArn,
      tags: yield* fetchDeadlineTags(fleetArn),
    },
  };
  return state;
});

const findFleetByDisplayName = Effect.fn(function* (
  farmId: string,
  displayName: string,
  arnOf: (path: string) => string,
) {
  const summaries = yield* deadline.listFleets.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.FleetSummary[]),
    ),
  );
  const match = summaries.find((summary) => summary.displayName === displayName);
  if (!match) return undefined;
  return yield* readFleetById(farmId, match.fleetId, arnOf);
});

/**
 * A fleet still transitioning toward the awaited state — retried by the
 * bounded wait schedules below.
 */
class FleetNotReady extends Data.TaggedError("FleetNotReady")<{
  readonly fleetId: string;
  readonly status: string | undefined;
}> {}

/**
 * A fleet whose asynchronous provisioning converged to a terminal failed
 * status (`CREATE_FAILED` / `UPDATE_FAILED`).
 */
export class FleetProvisioningFailed extends Data.TaggedError("FleetProvisioningFailed")<{
  readonly fleetId: string;
  readonly status: string;
  readonly message: string | undefined;
}> {}

const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "FleetNotReady",
    // Fleet activation is usually well under a minute; stay within the
    // provider-wide bounded provisioning budget.
    schedule: Schedule.max([Schedule.spaced("6 seconds"), Schedule.recurs(9)]),
  });

const waitForFleetActive = (farmId: string, fleetId: string, arnOf: (path: string) => string) =>
  retryWhileNotReady(
    Effect.gen(function* () {
      const state = yield* readFleetById(farmId, fleetId, arnOf);
      if (state === undefined) {
        return yield* new FleetNotReady({ fleetId, status: undefined });
      }
      if (
        state.described.status === "CREATE_FAILED" ||
        state.described.status === "UPDATE_FAILED"
      ) {
        return yield* new FleetProvisioningFailed({
          fleetId,
          status: state.described.status,
          message: state.described.statusMessage,
        });
      }
      if (state.described.status !== "ACTIVE" && state.described.status !== "SUSPENDED") {
        return yield* new FleetNotReady({ fleetId, status: state.described.status });
      }
      return state;
    }),
  );

const waitUntilFleetGone = (farmId: string, fleetId: string) =>
  retryWhileNotReady(
    Effect.gen(function* () {
      const described = yield* deadline
        .getFleet({ farmId, fleetId })
        .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      if (described !== undefined) {
        return yield* new FleetNotReady({ fleetId, status: described.status });
      }
    }),
  ).pipe(
    // Exhausted retries: deletion is already converging server-side.
    Effect.catchTag("FleetNotReady", () => Effect.void),
  );

export const FleetProvider = () =>
  Provider.effect(
    Fleet,
    Effect.gen(function* () {
      return {
        stables: ["farmId", "fleetId", "fleetArn", "roleArn"],
        // 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?.fleetId
            ? yield* readFleetById(farmId, output.fleetId, arnOf)
            : yield* findFleetByDisplayName(farmId, yield* createFleetName(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 is fixed at creation.
          if (olds.farmId !== news.farmId) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          if (news === undefined) {
            return yield* new DeadlineFleetInvalidProps({
              message: "AWS.Deadline.Fleet requires props",
            });
          }
          const arnOf = yield* deadlineArnOf;
          const farmId = news.farmId;
          const displayName = yield* createFleetName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // Observe.
          let state = output?.fleetId
            ? yield* readFleetById(farmId, output.fleetId, arnOf)
            : yield* findFleetByDisplayName(farmId, displayName, arnOf);

          // Ensure — create if missing, then wait for ACTIVE.
          if (state === undefined) {
            const created = yield* deadline
              .createFleet({
                farmId,
                displayName,
                description: news.description,
                roleArn: news.roleArn,
                minWorkerCount: news.minWorkerCount,
                maxWorkerCount: news.maxWorkerCount,
                configuration: toWireConfiguration(news.configuration),
                hostConfiguration: toWireHostConfiguration(news.hostConfiguration),
                tags: desiredTags,
              })
              .pipe(retryThroughIamPropagation, retryWhileFarmSettling);
            yield* session.note(`Creating fleet ${displayName} (${created.fleetId})...`);
            state = yield* waitForFleetActive(farmId, created.fleetId, arnOf);
          }

          // Sync mutable settings — only when drifted from OBSERVED state.
          const described = state.described;
          const needsUpdate =
            displayName !== described.displayName ||
            (news.description !== undefined &&
              news.description !== (asPlain(described.description) ?? "")) ||
            news.roleArn !== described.roleArn ||
            (news.minWorkerCount !== undefined &&
              news.minWorkerCount !== described.minWorkerCount) ||
            news.maxWorkerCount !== described.maxWorkerCount ||
            news.configuration !== undefined;
          if (needsUpdate) {
            yield* retryWhileConflict(
              deadline
                .updateFleet({
                  farmId,
                  fleetId: state.attrs.fleetId,
                  displayName,
                  description: news.description,
                  roleArn: news.roleArn,
                  minWorkerCount: news.minWorkerCount,
                  maxWorkerCount: news.maxWorkerCount,
                  configuration: toWireConfiguration(news.configuration),
                  hostConfiguration: toWireHostConfiguration(news.hostConfiguration),
                })
                .pipe(retryThroughIamPropagation),
            );
            state = yield* waitForFleetActive(farmId, state.attrs.fleetId, arnOf);
            yield* session.note(`Updated fleet ${displayName}`);
          }

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

          yield* session.note(state.attrs.fleetArn);
          const final = yield* readFleetById(farmId, state.attrs.fleetId, arnOf);
          if (!final) {
            return yield* new DeadlineFleetUnexpectedResponse({
              message: `failed to read reconciled fleet ${displayName}`,
            });
          }
          return final.attrs;
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* retryWhileConflict(
            deadline.deleteFleet({
              farmId: output.farmId,
              fleetId: output.fleetId,
            }),
          ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
          // Fleet deletion drains workers asynchronously; wait until gone so
          // the parent farm's deletion does not hit a dependency conflict.
          yield* waitUntilFleetGone(output.farmId, output.fleetId);
        }),
      };
    }),
  );