import * as ec2 from "@distilled.cloud/aws/ec2";
import { isResolved, somePropsAreDifferent } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import type { ScopedPlanStatusSession } from "alchemy/Report";
import { Resource } from "alchemy/Resource";
import {
createAlchemyTagFilters,
createInternalTags,
createTagsList,
diffTags,
} from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { AccountID } from "../Environment.ts";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
export type VolumeId<ID extends string = string> = `vol-${ID}`;
export const VolumeId = <ID extends string>(id: ID): ID & VolumeId<ID> =>
`vol-${id}` as ID & VolumeId<ID>;
export type VolumeArn = `arn:aws:ec2:${RegionID}:${AccountID}:volume/${VolumeId}`;
export interface VolumeProps {
/**
* The Availability Zone in which to create the volume, e.g. `us-east-1a`.
* Required. An EBS volume is bound to a single AZ; changing it replaces the
* volume.
*/
availabilityZone: string;
/**
* The size of the volume, in GiB. Required unless you create the volume from
* a `snapshotId` (in which case it defaults to the snapshot size). The size
* can be increased in place via `modifyVolume`; decreasing it replaces the
* volume.
*/
size?: number;
/**
* The volume type.
* @default "gp3"
*/
volumeType?: ec2.VolumeType;
/**
* The number of I/O operations per second (IOPS). Only valid for `io1`,
* `io2`, and `gp3` volumes. Mutable in place via `modifyVolume`.
*/
iops?: number;
/**
* The throughput to provision, in MiB/s. Only valid for `gp3` volumes.
* Mutable in place via `modifyVolume`.
*/
throughput?: number;
/**
* Whether the volume is encrypted. Changing this replaces the volume.
* @default false
*/
encrypted?: boolean;
/**
* The identifier of the KMS key to use for encryption. Can be a key ID, key
* ARN, alias name (`alias/my-key`), or alias ARN. Implies `encrypted: true`.
* Changing this replaces the volume.
*/
kmsKeyId?: string;
/**
* The snapshot from which to create the volume. Changing this replaces the
* volume.
*/
snapshotId?: string;
/**
* Whether the volume can be attached to multiple instances (Multi-Attach).
* Only valid for `io1`/`io2` volumes.
* @default false
*/
multiAttachEnabled?: boolean;
/**
* Tags to assign to the volume. Merged with alchemy auto-tags
* (alchemy::stack, alchemy::stage, alchemy::id).
*/
tags?: Record<string, string>;
}
export interface Volume extends Resource<
"AWS.EC2.Volume",
VolumeProps,
{
/**
* The ID of the volume.
*/
volumeId: VolumeId;
/**
* The Amazon Resource Name (ARN) of the volume.
*/
volumeArn: VolumeArn;
/**
* The Availability Zone of the volume.
*/
availabilityZone: string;
/**
* The size of the volume, in GiB.
*/
size: number;
/**
* The volume type.
*/
volumeType: ec2.VolumeType;
/**
* The number of IOPS provisioned for the volume.
*/
iops?: number;
/**
* The throughput provisioned for the volume, in MiB/s.
*/
throughput?: number;
/**
* Whether the volume is encrypted.
*/
encrypted: boolean;
/**
* The KMS key used for encryption, if any.
*/
kmsKeyId?: string;
/**
* The snapshot the volume was created from, if any.
*/
snapshotId?: string;
/**
* Whether Multi-Attach is enabled.
*/
multiAttachEnabled: boolean;
/**
* The current state of the volume.
*/
state: ec2.VolumeState;
},
never,
Providers
> {}
/**
* An Elastic Block Store (EBS) volume — durable block storage you attach to an
* EC2 instance via a {@link VolumeAttachment}. Volumes live in a single
* Availability Zone and persist independently of any instance.
*
* Changing `availabilityZone`, `encrypted`, `kmsKeyId`, `snapshotId`, or
* shrinking `size` replaces the volume. Growing `size` and changing `iops`,
* `throughput`, or `volumeType` are applied in place via `modifyVolume` (note
* AWS enforces a 6-hour cooldown between volume modifications).
*
* ### Creating a Volume
* **Example:** Basic gp3 Volume
* ```typescript
* const volume = yield* AWS.EC2.Volume("DataVolume", {
* availabilityZone: "us-east-1a",
* size: 20,
* volumeType: "gp3",
* });
* ```
*
* The minimal volume: a 20 GiB general-purpose `gp3` volume in one AZ. It must
* be in the same AZ as the instance you attach it to.
*
* ### Provisioned Performance
* **Example:** gp3 with Provisioned IOPS and Throughput
* ```typescript
* const fast = yield* AWS.EC2.Volume("FastVolume", {
* availabilityZone: "us-east-1a",
* size: 100,
* volumeType: "gp3",
* iops: 6000,
* throughput: 250,
* });
* ```
*
* `gp3` decouples IOPS and throughput from size, so you can provision up to
* 16,000 IOPS and 1,000 MiB/s independently. Use `io2` for the highest
* durability and IOPS ceilings.
*
* ### Encryption
* **Example:** Encrypted Volume with a KMS Key
* ```typescript
* const secure = yield* AWS.EC2.Volume("SecureVolume", {
* availabilityZone: "us-east-1a",
* size: 20,
* encrypted: true,
* kmsKeyId: "alias/my-app-key",
* });
* ```
*
* Setting `kmsKeyId` implies encryption. Omit it while setting `encrypted:
* true` to use the account's default EBS KMS key.
*
* ### Creating from a Snapshot
* **Example:** Restore a Volume from a Snapshot
* ```typescript
* const restored = yield* AWS.EC2.Volume("RestoredVolume", {
* availabilityZone: "us-east-1a",
* snapshotId: snapshot.snapshotId,
* });
* ```
*
* When you create a volume from a snapshot, `size` defaults to the snapshot's
* size and can only be grown, never shrunk.
*
* @resource
*/
export const Volume = Resource<Volume>("AWS.EC2.Volume");
export const VolumeProvider = () =>
Provider.effect(
Volume,
Effect.gen(function* () {
// EBS volume IDs are server-assigned. Recover a successfully created
// volume after state persistence failure via the resource instance tag;
// logical-id-only tags are insufficient during replacement because the
// old and new volume instances can coexist.
const findVolumeByInstanceTags = Effect.fn(function* (id: string, instanceId: string) {
const filters = yield* createAlchemyTagFilters(id);
const pages = yield* ec2.describeVolumes
.pages({
Filters: [...filters, { Name: "tag:alchemy::instance", Values: [instanceId] }],
})
.pipe(Stream.runCollect);
return Array.from(pages)
.flatMap((page) => page.Volumes ?? [])
.find((volume) => volume.State !== "deleting" && volume.State !== "deleted");
});
// Try the cached volume id first, then the ownership-tag lookup. A
// volume that is deleting or deleted counts as missing.
const observeVolume = Effect.fn(function* (
id: string,
instanceId: string,
volumeId: string | undefined,
) {
if (volumeId) {
const lookup = yield* ec2
.describeVolumes({ VolumeIds: [volumeId] })
.pipe(Effect.catchTag("InvalidVolume.NotFound", () => Effect.succeed({ Volumes: [] })));
const found = lookup.Volumes?.[0];
if (found && found.State !== "deleting" && found.State !== "deleted") {
return found;
}
}
return yield* findVolumeByInstanceTags(id, instanceId);
});
return {
stables: [
"volumeId",
"volumeArn",
"availabilityZone",
"encrypted",
"kmsKeyId",
"snapshotId",
],
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return;
if (
somePropsAreDifferent(olds, news, [
"availabilityZone",
"encrypted",
"kmsKeyId",
"snapshotId",
])
) {
return { action: "replace" };
}
// Shrinking a volume is not supported in place — replace.
if (olds.size !== undefined && news.size !== undefined && news.size < olds.size) {
return { action: "replace" };
}
}),
read: Effect.fn(function* ({ id, instanceId, output }) {
const { accountId, region } = yield* AWSEnvironment.current;
const volume = yield* observeVolume(id, instanceId, output?.volumeId);
return volume ? toVolumeAttributes(volume, region, accountId) : undefined;
}),
reconcile: Effect.fn(function* ({ id, instanceId, news, output, session }) {
const { accountId, region } = yield* AWSEnvironment.current;
const alchemyTags = yield* createInternalTags(id);
const desiredTags = {
...news.tags,
...alchemyTags,
"alchemy::instance": instanceId,
};
// 1. OBSERVE — cloud state is authoritative; output is only an id
// cache. A volume in a terminal state is treated as missing.
let volume = yield* observeVolume(id, instanceId, output?.volumeId);
// 2. ENSURE — create the volume when missing, then wait until it is
// available. The ClientToken is this generation plus the last
// volume it created, so a create retried after a lost reply
// returns the first volume, and a recreate after the volume was
// deleted sends a new token.
if (volume === undefined) {
const create = (clientToken: string | undefined) =>
ec2.createVolume({
AvailabilityZone: news.availabilityZone,
Size: news.size,
VolumeType: news.volumeType ?? "gp3",
Iops: news.iops,
Throughput: news.throughput,
Encrypted: news.encrypted ?? (news.kmsKeyId !== undefined ? true : undefined),
KmsKeyId: news.kmsKeyId,
SnapshotId: news.snapshotId,
MultiAttachEnabled: news.multiAttachEnabled,
ClientToken: clientToken,
TagSpecifications: [
{
ResourceType: "volume",
Tags: createTagsList(desiredTags),
},
],
DryRun: false,
});
// EC2 refuses a token whose volume was deleted, which a recreate
// with no saved volume id (Drift.repair) runs into. Step to the
// next token in a fixed sequence, so a retry after a lost reply
// walks the same sequence and returns the same volume.
const token = `${instanceId}-${output?.volumeId ?? "initial"}`;
const createFrom = (
attempt: number,
): Effect.Effect<
ec2.Volume,
Effect.Error<ReturnType<typeof create>>,
Effect.Services<ReturnType<typeof create>>
> =>
create(attempt === 0 ? token : `${token}-${attempt}`).pipe(
Effect.catchTag("IdempotentVolumeDeleted", (e) =>
attempt < 8 ? createFrom(attempt + 1) : Effect.fail(e),
),
);
const created = yield* createFrom(0);
const volumeId = created.VolumeId! as VolumeId;
yield* session.note(`Volume created: ${volumeId}`);
volume = yield* waitForVolumeAvailable(volumeId, session);
}
const volumeId = volume.VolumeId! as VolumeId;
// 3. SYNC — grow size / adjust performance in place. Only include a
// field when the user specified it AND it drifts from observed
// cloud state, so a no-op reconcile never triggers the 6h
// modification cooldown.
const modify: ec2.ModifyVolumeRequest = { VolumeId: volumeId };
let needsModify = false;
if (news.size !== undefined && news.size > (volume.Size ?? 0)) {
modify.Size = news.size;
needsModify = true;
}
if (news.volumeType !== undefined && news.volumeType !== volume.VolumeType) {
modify.VolumeType = news.volumeType;
needsModify = true;
}
if (news.iops !== undefined && news.iops !== volume.Iops) {
modify.Iops = news.iops;
needsModify = true;
}
if (news.throughput !== undefined && news.throughput !== volume.Throughput) {
modify.Throughput = news.throughput;
needsModify = true;
}
if (needsModify) {
yield* ec2.modifyVolume(modify);
yield* session.note(`Volume modified: ${volumeId}`);
}
// 3b. SYNC TAGS — diff against observed cloud tags.
const currentTags = Object.fromEntries(
(volume.Tags ?? []).map((t) => [t.Key!, t.Value!]),
) as Record<string, string>;
const { removed, upsert } = diffTags(currentTags, desiredTags);
if (removed.length > 0) {
yield* ec2.deleteTags({
Resources: [volumeId],
Tags: removed.map((key) => ({ Key: key })),
DryRun: false,
});
}
if (upsert.length > 0) {
yield* ec2.createTags({
Resources: [volumeId],
Tags: upsert,
DryRun: false,
});
}
// 4. RETURN fresh attributes.
const finalLookup = yield* ec2.describeVolumes({
VolumeIds: [volumeId],
});
const final = finalLookup.Volumes?.[0] ?? volume;
return toVolumeAttributes(final, region, accountId);
}),
// Enumerate every volume in the ambient account/region.
list: () =>
Effect.gen(function* () {
const { accountId, region } = yield* AWSEnvironment.current;
const chunk = yield* ec2.describeVolumes.pages({}).pipe(Stream.runCollect);
return Array.from(chunk).flatMap((page) =>
(page.Volumes ?? []).map((v) => toVolumeAttributes(v, region, accountId)),
);
}),
delete: Effect.fn(function* ({ output, session }) {
const volumeId = output.volumeId;
yield* session.note(`Deleting volume: ${volumeId}`);
yield* ec2.deleteVolume({ VolumeId: volumeId, DryRun: false }).pipe(
Effect.tapError(Effect.logDebug),
Effect.catchTag("InvalidVolume.NotFound", () => Effect.void),
// A volume that is still detaching reports VolumeInUse — retry
// until the detach completes.
Effect.retry({
while: (e) => e._tag === "VolumeInUse",
schedule: Schedule.max([Schedule.fixed(3000), Schedule.recurs(20)]).pipe(
Schedule.tap(({ attempt }) =>
session.note(`Waiting for volume to detach... (attempt ${attempt + 1})`),
),
),
}),
);
yield* waitForVolumeDeleted(volumeId, session);
yield* session.note(`Volume ${volumeId} deleted successfully`);
}),
};
}),
);
const toVolumeAttributes = (
volume: ec2.Volume,
region: RegionID,
accountId: AccountID,
): Volume["Attributes"] => {
const volumeId = volume.VolumeId! as VolumeId;
return {
volumeId,
volumeArn: `arn:aws:ec2:${region}:${accountId}:volume/${volumeId}` as VolumeArn,
availabilityZone: volume.AvailabilityZone!,
size: volume.Size ?? 0,
volumeType: volume.VolumeType ?? "gp3",
iops: volume.Iops,
throughput: volume.Throughput,
encrypted: volume.Encrypted ?? false,
kmsKeyId: volume.KmsKeyId,
snapshotId: volume.SnapshotId && volume.SnapshotId.length > 0 ? volume.SnapshotId : undefined,
multiAttachEnabled: volume.MultiAttachEnabled ?? false,
state: volume.State ?? "creating",
};
};
class VolumeNotFound extends Data.TaggedError("VolumeNotFound")<{
volumeId: string;
}> {}
class VolumeFailed extends Data.TaggedError("VolumeFailed")<{
volumeId: string;
}> {}
class VolumeNotReady extends Data.TaggedError("VolumeNotReady")<{
volumeId: string;
state: string;
}> {}
class VolumeStillExists extends Data.TaggedError("VolumeStillExists")<{
volumeId: string;
state: string;
message: string;
}> {}
/**
* Wait for the volume to reach the `available` state.
*/
const waitForVolumeAvailable = (volumeId: string, session?: ScopedPlanStatusSession) =>
Effect.gen(function* () {
const result = yield* ec2.describeVolumes({ VolumeIds: [volumeId] });
const volume = result.Volumes?.[0];
if (!volume) {
return yield* new VolumeNotFound({ volumeId });
}
if (volume.State === "available" || volume.State === "in-use") {
return volume;
}
if (volume.State === "error") {
return yield* new VolumeFailed({ volumeId });
}
return yield* new VolumeNotReady({ volumeId, state: volume.State! });
}).pipe(
Effect.retry({
while: (e) => e._tag === "VolumeNotReady",
schedule: Schedule.max([
Schedule.fixed(2000),
Schedule.recurs(30), // max ~60s
]).pipe(
Schedule.tap(({ attempt }) =>
session
? session.note(`Waiting for volume to be available... (${(attempt + 1) * 2}s)`)
: Effect.void,
),
),
}),
);
/**
* Wait for the volume to be fully deleted.
*/
const waitForVolumeDeleted = (volumeId: string, session: ScopedPlanStatusSession) =>
Effect.gen(function* () {
const result = yield* ec2
.describeVolumes({ VolumeIds: [volumeId] })
.pipe(Effect.catchTag("InvalidVolume.NotFound", () => Effect.succeed({ Volumes: [] })));
const volume = result.Volumes?.[0];
// Do not treat `deleting` as deleted. The provider's delete contract is
// complete only after EC2 stops returning the volume; otherwise nuke can
// report success while the resource remains in its inventory.
if (!volume || volume.State === "deleted") {
return;
}
return yield* new VolumeStillExists({
volumeId,
state: volume.State ?? "unknown",
message:
`Volume ${volumeId} remains ${volume.State ?? "visible"} after the bounded delete wait; ` +
"AWS accepted DeleteVolume but has not removed it",
});
}).pipe(
Effect.retry({
while: (e) => e._tag === "VolumeStillExists",
schedule: Schedule.max([
Schedule.fixed(2000),
// DeleteVolume is accepted immediately but describe can keep
// returning `deleting` well past a minute after a snapshot (the
// suite log hit the old 60s cap with the volume still present).
Schedule.recurs(45),
]).pipe(
Schedule.tap(({ attempt }) =>
session.note(`Waiting for volume deletion... (${(attempt + 1) * 2}s)`),
),
),
}),
);