import * as glacier from "@distilled.cloud/aws/glacier";
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, diffTags, hasAlchemyTags } 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 { Providers } from "../Providers.ts";
// Glacier's REST API takes the AWS account ID as a path segment; `-` means
// "the account that signed the request".
const ACCOUNT = "-";
export interface VaultNotificationConfigProps {
/**
* ARN of the SNS topic that Amazon S3 Glacier publishes job-completion
* notifications to.
*/
snsTopic: string;
/**
* Job-completion events to publish. Valid values are
* `ArchiveRetrievalCompleted` and `InventoryRetrievalCompleted`.
*/
events: string[];
}
export interface VaultProps {
/**
* Name of the vault. 1-255 characters; allowed characters are a-z, A-Z,
* 0-9, `_` (underscore), `-` (hyphen), and `.` (period). Changing the
* name replaces the vault.
* @default ${app}-${stage}-${id}
*/
vaultName?: string;
/**
* Notification configuration publishing job-completion events to an SNS
* topic. Removing the prop deletes the vault's notification
* configuration.
*/
notificationConfig?: VaultNotificationConfigProps;
/**
* Vault access policy (a resource-based IAM policy document), provided
* as a JSON string or a plain object. Removing the prop deletes the
* vault's access policy.
*/
accessPolicy?: string | Record<string, any>;
/**
* Vault lock policy (an IAM policy document enforcing compliance
* controls), provided as a JSON string or a plain object. Setting it
* initiates the vault lock, leaving it in the `InProgress` state — the
* policy is in effect but can still be changed or removed for 24 hours.
* Alchemy never calls `CompleteVaultLock`, so the lock is never made
* immutable by this resource. Removing the prop aborts an in-progress
* lock.
*/
lockPolicy?: string | Record<string, any>;
/**
* Tags to apply to the vault (up to 10). Merged with internal Alchemy
* tags.
*/
tags?: Record<string, string>;
}
export interface Vault extends Resource<
"AWS.Glacier.Vault",
VaultProps,
{
/** The name of the vault. */
vaultName: string;
/** The ARN of the vault. */
vaultArn: string;
/** ISO-8601 timestamp of when the vault was created. */
creationDate: string;
},
never,
Providers
> {}
/**
* An Amazon S3 Glacier vault — a container for archives in the original
* (vault-based) S3 Glacier service.
*
* Vault creation is idempotent and free; storage is billed per archive.
* A vault must be empty to be deleted, which is always the case for vaults
* that only ever held configuration.
* ### Creating Vaults
* **Example:** Basic Vault
* ```typescript
* import * as Glacier from "@alchemy.run/aws/Glacier";
*
* const vault = yield* Glacier.Vault("Backups");
* ```
*
* **Example:** Vault with Tags
* ```typescript
* const vault = yield* Glacier.Vault("Backups", {
* tags: { team: "storage" },
* });
* ```
*
* ### Notifications
* **Example:** Publish job-completion events to SNS
* ```typescript
* const topic = yield* SNS.Topic("VaultEvents");
* const vault = yield* Glacier.Vault("Backups", {
* notificationConfig: {
* snsTopic: topic.topicArn,
* events: ["ArchiveRetrievalCompleted", "InventoryRetrievalCompleted"],
* },
* });
* ```
*
* ### Access Control
* **Example:** Vault access policy
* ```typescript
* const vault = yield* Glacier.Vault("Backups", {
* accessPolicy: {
* Version: "2012-10-17",
* Statement: [{
* Sid: "deny-archive-deletes",
* Effect: "Deny",
* Principal: "*",
* Action: ["glacier:DeleteArchive"],
* Resource: ["arn:aws:glacier:us-east-1:123456789012:vaults/backups"],
* }],
* },
* });
* ```
*
* **Example:** Vault lock policy (left in-progress, never completed)
* ```typescript
* const vault = yield* Glacier.Vault("Compliance", {
* lockPolicy: {
* Version: "2012-10-17",
* Statement: [{
* Sid: "deny-archive-deletes",
* Effect: "Deny",
* Principal: "*",
* Action: ["glacier:DeleteArchive"],
* Resource: ["arn:aws:glacier:us-east-1:123456789012:vaults/compliance"],
* }],
* },
* });
* ```
*
* @resource
*/
export const Vault = Resource<Vault>("AWS.Glacier.Vault");
/**
* Raised when the desired `lockPolicy` differs from (or removes) a vault
* lock that is already in the `Locked` state. A locked vault lock policy is
* immutable — it can never be changed or removed.
*/
export class GlacierVaultLockImmutable extends Data.TaggedError("GlacierVaultLockImmutable")<{
message: string;
}> {}
/**
* Raised when DescribeVault returns a vault record missing its ARN or
* creation date — never expected from the live API.
*/
export class GlacierVaultIncomplete extends Data.TaggedError("GlacierVaultIncomplete")<{
message: string;
}> {}
// Explicitly-typed pipeable retry helper. Inlining `Effect.retry` in a
// provider lifecycle op leaks `Retry.Return`'s conditional into declaration
// emit and widens the provider layer to `unknown` R for every consumer of
// `AWS.providers()`.
const retryWhileVaultNotFound = <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 === "ResourceNotFoundException",
schedule: Schedule.max([Schedule.fixed(1000), Schedule.recurs(10)]),
});
const toPolicyString = (policy: string | Record<string, any> | undefined): string | undefined =>
policy === undefined ? undefined : typeof policy === "string" ? policy : JSON.stringify(policy);
// Structural comparison for policy documents: AWS may re-serialize the
// stored policy, so compare parsed shapes rather than raw strings. Falls
// back to raw string equality if either side is not valid JSON.
const samePolicy = (left: string, right: string): boolean => {
if (left === right) return true;
try {
return JSON.stringify(JSON.parse(left)) === JSON.stringify(JSON.parse(right));
} catch {
return false;
}
};
const sameStringSet = (left: readonly string[], right: readonly string[]): boolean => {
if (left.length !== right.length) return false;
const sortedLeft = [...left].sort();
const sortedRight = [...right].sort();
return sortedLeft.every((value, i) => value === sortedRight[i]);
};
export const VaultProvider = () =>
Provider.effect(
Vault,
Effect.gen(function* () {
const createVaultName = Effect.fn(function* (id: string, props: VaultProps) {
return props.vaultName ?? (yield* createPhysicalName({ id, maxLength: 255 }));
});
const describeVault = (vaultName: string) =>
glacier
.describeVault({ accountId: ACCOUNT, vaultName })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
const readVaultTags = (vaultName: string) =>
glacier.listTagsForVault({ accountId: ACCOUNT, vaultName }).pipe(
Effect.map((r) => (r.Tags ?? {}) as Record<string, string>),
Effect.orElseSucceed(() => ({}) as Record<string, string>),
);
return Vault.Provider.of({
stables: ["vaultName", "vaultArn", "creationDate"],
// Enumerate every vault in the ambient account/region. Vaults whose
// list entry is missing identifying fields (never expected from the
// live API) are dropped.
list: () =>
Effect.gen(function* () {
const pages = yield* glacier.listVaults
.pages({ accountId: ACCOUNT })
.pipe(Stream.runCollect);
return Array.from(pages)
.flatMap((page) => page.VaultList ?? [])
.flatMap((vault) =>
vault.VaultName !== undefined &&
vault.VaultARN !== undefined &&
vault.CreationDate !== undefined
? [
{
vaultName: vault.VaultName,
vaultArn: vault.VaultARN,
creationDate: vault.CreationDate,
},
]
: [],
);
}),
read: Effect.fn(function* ({ id, olds, output }) {
const vaultName = output?.vaultName ?? (yield* createVaultName(id, olds ?? {}));
const found = yield* describeVault(vaultName);
if (found?.VaultARN === undefined) return undefined;
const attrs = {
vaultName,
vaultArn: found.VaultARN,
creationDate: found.CreationDate ?? "",
};
const tags = yield* readVaultTags(vaultName);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
const oldName = yield* createVaultName(id, olds ?? {});
const newName = yield* createVaultName(id, news);
if (oldName !== newName) {
return { action: "replace" } as const;
}
// undefined → default update path (reconcile syncs the rest)
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const props = news ?? {};
const vaultName = output?.vaultName ?? (yield* createVaultName(id, props));
const internalTags = yield* createInternalTags(id);
// 1. OBSERVE — cloud state is authoritative; output is only a
// name cache.
let live = yield* describeVault(vaultName);
// 2. ENSURE — CreateVault is an idempotent PUT; re-observe for the
// full record (create only returns a Location header). A brief
// bounded retry covers read-after-create consistency.
if (live === undefined) {
yield* glacier.createVault({ accountId: ACCOUNT, vaultName });
live = yield* glacier
.describeVault({ accountId: ACCOUNT, vaultName })
.pipe(retryWhileVaultNotFound);
}
if (live.VaultARN === undefined || live.CreationDate === undefined) {
return yield* new GlacierVaultIncomplete({
message: `DescribeVault for '${vaultName}' returned no VaultARN/CreationDate`,
});
}
// 3a. SYNC notification configuration — observed vs desired.
const observedNotifications = yield* glacier
.getVaultNotifications({ accountId: ACCOUNT, vaultName })
.pipe(
Effect.map((r) => r.vaultNotificationConfig),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
const desiredNotifications = props.notificationConfig;
if (desiredNotifications !== undefined) {
const inSync =
observedNotifications !== undefined &&
observedNotifications.SNSTopic === desiredNotifications.snsTopic &&
sameStringSet(observedNotifications.Events ?? [], desiredNotifications.events);
if (!inSync) {
yield* glacier.setVaultNotifications({
accountId: ACCOUNT,
vaultName,
vaultNotificationConfig: {
SNSTopic: desiredNotifications.snsTopic,
Events: desiredNotifications.events,
},
});
}
} else if (observedNotifications !== undefined) {
yield* glacier
.deleteVaultNotifications({ accountId: ACCOUNT, vaultName })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}
// 3b. SYNC access policy — observed vs desired.
const observedPolicy = yield* glacier
.getVaultAccessPolicy({ accountId: ACCOUNT, vaultName })
.pipe(
Effect.map((r) => r.policy?.Policy),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
const desiredPolicy = toPolicyString(props.accessPolicy);
if (desiredPolicy !== undefined) {
if (observedPolicy === undefined || !samePolicy(observedPolicy, desiredPolicy)) {
yield* glacier.setVaultAccessPolicy({
accountId: ACCOUNT,
vaultName,
policy: { Policy: desiredPolicy },
});
}
} else if (observedPolicy !== undefined) {
yield* glacier
.deleteVaultAccessPolicy({ accountId: ACCOUNT, vaultName })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}
// 3c. SYNC vault lock — observed vs desired. An `InProgress` lock
// can be aborted and re-initiated; a `Locked` lock is immutable
// forever, so any drift from the desired state is surfaced as a
// typed failure rather than silently ignored.
const observedLock = yield* glacier
.getVaultLock({ accountId: ACCOUNT, vaultName })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
const desiredLock = toPolicyString(props.lockPolicy);
if (desiredLock !== undefined) {
if (observedLock === undefined) {
yield* glacier.initiateVaultLock({
accountId: ACCOUNT,
vaultName,
policy: { Policy: desiredLock },
});
} else if (
observedLock.Policy === undefined ||
!samePolicy(observedLock.Policy, desiredLock)
) {
if (observedLock.State === "Locked") {
return yield* new GlacierVaultLockImmutable({
message: `Vault '${vaultName}' lock is in the Locked state; its lock policy can never be changed.`,
});
}
// InProgress with a different policy: abort and re-initiate.
yield* glacier
.abortVaultLock({ accountId: ACCOUNT, vaultName })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
yield* glacier.initiateVaultLock({
accountId: ACCOUNT,
vaultName,
policy: { Policy: desiredLock },
});
}
} else if (observedLock !== undefined) {
if (observedLock.State === "Locked") {
return yield* new GlacierVaultLockImmutable({
message: `Vault '${vaultName}' lock is in the Locked state; it can never be removed.`,
});
}
yield* glacier
.abortVaultLock({ accountId: ACCOUNT, vaultName })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}
// 3d. SYNC tags — diff against OBSERVED cloud tags so adoption
// converges.
const observedTags = yield* readVaultTags(vaultName);
const desiredTags: Record<string, string> = {
...props.tags,
...internalTags,
};
const { upsert, removed } = diffTags(observedTags, desiredTags);
if (upsert.length > 0) {
yield* glacier.addTagsToVault({
accountId: ACCOUNT,
vaultName,
Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
});
}
if (removed.length > 0) {
yield* glacier.removeTagsFromVault({
accountId: ACCOUNT,
vaultName,
TagKeys: removed,
});
}
// 4. RETURN fresh Attributes.
yield* session.note(vaultName);
return {
vaultName,
vaultArn: live.VaultARN,
creationDate: live.CreationDate,
};
}),
// Idempotent delete. An in-progress vault lock is aborted first so a
// lock policy that denies deletes cannot strand the vault; deleting
// an already-deleted vault is not an error.
delete: Effect.fn(function* ({ output }) {
const lock = yield* glacier
.getVaultLock({
accountId: ACCOUNT,
vaultName: output.vaultName,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
if (lock !== undefined && lock.State !== "Locked") {
yield* glacier
.abortVaultLock({
accountId: ACCOUNT,
vaultName: output.vaultName,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}
yield* glacier
.deleteVault({ accountId: ACCOUNT, vaultName: output.vaultName })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}),
});
}),
);