import * as rbin from "@distilled.cloud/aws/rbin";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import {
createInternalTags,
createTagsList,
diffTags,
hasAlchemyTags,
tagRecord,
} from "alchemy/Tags";
import { toWireDays } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
/**
* A resource tag used to identify (or exclude) resources covered by a
* retention rule.
*/
export interface RuleResourceTag {
/**
* The tag key.
*/
key: string;
/**
* The tag value. Omit to match any resource that has the tag key,
* regardless of value.
*/
value?: string;
}
/**
* Lock configuration for a Region-level retention rule. A locked rule
* cannot be modified or deleted until it is unlocked and the unlock delay
* period expires.
*/
export interface RuleLockConfiguration {
/**
* The unlock delay that must expire after the rule is unlocked before it
* can be modified or deleted (e.g. `"7 days"`; valid range 7-30 days).
* Sent to the API in whole days.
*/
unlockDelay: Duration.Input;
}
export interface RuleProps {
/**
* The resource type to be retained by the retention rule:
* `EBS_SNAPSHOT` for Amazon EBS snapshots, `EC2_IMAGE` for EBS-backed
* AMIs, or `EBS_VOLUME` for Amazon EBS volumes.
* Changing the resource type replaces the rule.
*/
resourceType: "EBS_SNAPSHOT" | "EC2_IMAGE" | "EBS_VOLUME";
/**
* The period for which the retention rule retains resources after they
* are deleted (e.g. `"7 days"` or `Duration.days(7)`; valid range
* 1-365 days). Sent to the API in whole days.
*/
retentionPeriod: Duration.Input;
/**
* A brief description of the retention rule.
*/
description?: string;
/**
* Resource tags that identify the resources to retain (a **tag-level**
* retention rule). Resources of the specified type that have at least one
* of these tag key/value pairs are retained in the Recycle Bin upon
* deletion. Omit (along with `excludeResourceTags`) to create a
* **Region-level** rule that retains all resources of the type in the
* Region.
*/
resourceTags?: RuleResourceTag[];
/**
* Exclusion tags for a Region-level retention rule. Resources that have
* any of these tag key/value pairs are NOT retained by the rule. Cannot
* be combined with `resourceTags` or `lockConfiguration`.
*/
excludeResourceTags?: RuleResourceTag[];
/**
* Lock configuration for the rule. Only Region-level rules without
* exclusion tags can be locked. A locked rule cannot be modified or
* deleted; removing this prop unlocks the rule, which then remains in
* `pending_unlock` until the unlock delay (7-30 days) expires.
*/
lockConfiguration?: RuleLockConfiguration;
/**
* Tags to apply to the retention rule itself. Merged with internal
* Alchemy tags.
*/
tags?: Record<string, string>;
}
export interface Rule extends Resource<
"AWS.Rbin.Rule",
RuleProps,
{
/** The unique ID of the retention rule (e.g. `1a2b3c4d-5e6f-...`). */
identifier: string;
/** The Amazon Resource Name (ARN) of the retention rule. */
ruleArn: string;
/** The resource type retained by the retention rule. */
resourceType: rbin.ResourceType;
/** The state of the retention rule (`pending` or `available`). */
status: rbin.RuleStatus;
/** The lock state of the retention rule, if lockable. */
lockState?: rbin.LockState;
},
never,
Providers
> {}
/**
* A Recycle Bin retention rule. Recycle Bin retains deleted EBS snapshots,
* EBS-backed AMIs, and EBS volumes for a configurable period so they can be
* recovered after accidental deletion.
*
* Rules are either **tag-level** (retain only resources carrying specific
* resource tags) or **Region-level** (retain every resource of the type in
* the Region, optionally minus exclusion tags). Changing `resourceType`
* replaces the rule; every other property updates in place.
*
* ### Creating Retention Rules
* **Example:** Tag-level rule for EBS snapshots
* ```typescript
* import * as Rbin from "@alchemy.run/aws/Rbin";
*
* const rule = yield* Rbin.Rule("SnapshotRetention", {
* resourceType: "EBS_SNAPSHOT",
* retentionPeriod: "7 days",
* description: "Retain tagged snapshots for 7 days",
* resourceTags: [{ key: "team", value: "data" }],
* });
* ```
*
* **Example:** Region-level rule for AMIs
* ```typescript
* const rule = yield* Rbin.Rule("AmiRetention", {
* resourceType: "EC2_IMAGE",
* retentionPeriod: "14 days",
* description: "Retain all deregistered AMIs in this Region",
* });
* ```
*
* **Example:** Region-level rule with exclusion tags
* ```typescript
* const rule = yield* Rbin.Rule("SnapshotRetention", {
* resourceType: "EBS_SNAPSHOT",
* retentionPeriod: "30 days",
* excludeResourceTags: [{ key: "ephemeral", value: "true" }],
* });
* ```
*
* ### Locking
* A Region-level rule (without exclusion tags) can be locked so it cannot
* be modified or deleted. Removing `lockConfiguration` unlocks the rule,
* which stays protected in `pending_unlock` until the unlock delay expires.
*
* **Example:** Locked Region-level rule
* ```typescript
* const rule = yield* Rbin.Rule("LockedRetention", {
* resourceType: "EBS_SNAPSHOT",
* retentionPeriod: "30 days",
* lockConfiguration: { unlockDelay: "7 days" },
* });
* ```
*
* ### Tagging
* **Example:** Tag the rule itself
* ```typescript
* const rule = yield* Rbin.Rule("SnapshotRetention", {
* resourceType: "EBS_SNAPSHOT",
* retentionPeriod: "7 days",
* resourceTags: [{ key: "team", value: "data" }],
* tags: { CostCenter: "storage" },
* });
* ```
*
* @resource
*/
export const Rule = Resource<Rule>("AWS.Rbin.Rule");
/**
* Raised when a `Rule` combines `lockConfiguration` with `resourceTags` or
* `excludeResourceTags`. Recycle Bin only supports locking Region-level
* retention rules that have no exclusion tags.
*/
export class RbinLockUnsupported extends Data.TaggedError("RbinLockUnsupported")<{
message: string;
}> {}
const validateLock = (props: RuleProps) =>
props.lockConfiguration !== undefined &&
((props.resourceTags?.length ?? 0) > 0 || (props.excludeResourceTags?.length ?? 0) > 0)
? Effect.fail(
new RbinLockUnsupported({
message:
"lockConfiguration is only supported on Region-level retention rules without excludeResourceTags — remove resourceTags/excludeResourceTags or the lock.",
}),
)
: Effect.void;
/** All resource types a retention rule can cover — used to enumerate rules. */
const RULE_RESOURCE_TYPES = ["EBS_SNAPSHOT", "EC2_IMAGE", "EBS_VOLUME"] as const;
const toRetentionPeriod = (p: Duration.Input): rbin.RetentionPeriod => ({
// The wire unit is whole days (`DAYS` is the only supported unit).
RetentionPeriodValue: toWireDays(p)!,
RetentionPeriodUnit: "DAYS",
});
const toResourceTags = (tags: RuleResourceTag[] | undefined): rbin.ResourceTag[] =>
(tags ?? []).map((t) => ({
ResourceTagKey: t.key,
...(t.value !== undefined ? { ResourceTagValue: t.value } : {}),
}));
const toLockConfiguration = (lock: RuleLockConfiguration): rbin.LockConfiguration => ({
UnlockDelay: {
// The wire unit is whole days (`DAYS` is the only supported unit).
UnlockDelayValue: toWireDays(lock.unlockDelay)!,
UnlockDelayUnit: "DAYS",
},
});
/** Order-insensitive fingerprint of a resource-tag set for delta detection. */
const resourceTagsKey = (tags: readonly rbin.ResourceTag[] | undefined) =>
JSON.stringify(
(tags ?? [])
.map((t) => [t.ResourceTagKey, t.ResourceTagValue ?? ""])
.sort((a, b) => (a[0]! < b[0]! ? -1 : a[0]! > b[0]! ? 1 : 0)),
);
const toAttributes = (live: rbin.GetRuleResponse): Rule["Attributes"] => ({
identifier: live.Identifier!,
ruleArn: live.RuleArn!,
resourceType: live.ResourceType!,
status: live.Status ?? "available",
lockState: live.LockState,
});
/** Read a rule; a typed RULE_NOT_FOUND becomes `undefined`. */
const readRule = (identifier: string) =>
rbin
.getRule({ Identifier: identifier })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
/** Observed tags on the rule itself (empty on a NotFound race). */
const readRuleTags = (ruleArn: string) =>
rbin.listTagsForResource({ ResourceArn: ruleArn }).pipe(
Effect.map((r) => tagRecord(r.Tags ?? [])),
Effect.catchTag("ResourceNotFoundException", () =>
Effect.succeed({} as Record<string, string>),
),
);
/** Collect all rule summaries for one resource type (exhaustive pages). */
const listRuleSummaries = (resourceType: rbin.ResourceType) =>
rbin.listRules.items({ ResourceType: resourceType }).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk)),
// Tolerate a resource type the Region/partition doesn't support yet.
Effect.catchTag("ValidationException", () => Effect.succeed([] as rbin.RuleSummary[])),
);
class RuleStillPending extends Data.TaggedError("RuleStillPending")<{
identifier: string;
}> {}
class RuleStillExists extends Data.TaggedError("RuleStillExists")<{
identifier: string;
}> {}
/**
* Bounded retry while a freshly created/updated rule reports `pending`.
* Extracted to module scope with an explicit signature so the conditional
* `Retry.Return` type never leaks into the provider layer's declaration.
*/
const retryWhileRulePending = <A, E extends { _tag: string }, R>(
self: Effect.Effect<A, E | RuleStillPending, R>,
): Effect.Effect<A, E | RuleStillPending, R> =>
Effect.retry(self, {
while: (e) => e._tag === "RuleStillPending",
schedule: Schedule.max([Schedule.fixed("1 second"), Schedule.recurs(30)]),
});
/** Poll a rule until it leaves the transient `pending` status. */
const waitForRuleAvailable = (identifier: string) =>
retryWhileRulePending(
Effect.gen(function* () {
const live = yield* rbin.getRule({ Identifier: identifier });
if (live.Status === "pending") {
return yield* new RuleStillPending({ identifier });
}
return live;
}),
);
/** Bounded retry while the rule is still observable after deletion. */
const retryWhileRuleExists = <A, E extends { _tag: string }, R>(
self: Effect.Effect<A, E | RuleStillExists, R>,
): Effect.Effect<A, E | RuleStillExists, R> =>
Effect.retry(self, {
while: (e) => e._tag === "RuleStillExists",
schedule: Schedule.max([Schedule.fixed("1 second"), Schedule.recurs(15)]),
});
export const RuleProvider = () =>
Provider.effect(
Rule,
Effect.gen(function* () {
return Rule.Provider.of({
stables: ["identifier", "ruleArn", "resourceType"],
// Enumerate every retention rule in the ambient account/region across
// all supported resource types, hydrating each summary to the full
// Attributes shape. A rule can vanish between enumeration and
// hydration, so tolerate the typed NotFound per item and drop it.
list: () =>
Effect.gen(function* () {
const summaries = yield* Effect.forEach(
RULE_RESOURCE_TYPES,
(resourceType) => listRuleSummaries(resourceType),
{ concurrency: 3 },
).pipe(Effect.map((groups) => groups.flat()));
const items = yield* Effect.forEach(
summaries.filter((s) => s.Identifier !== undefined),
(summary) =>
readRule(summary.Identifier!).pipe(
Effect.map((live) => (live === undefined ? undefined : toAttributes(live))),
),
{ concurrency: 5 },
);
return items.filter((item): item is Rule["Attributes"] => item !== undefined);
}),
// Rule identifiers are server-generated, so without a cached output
// we search for a rule branded with our alchemy ownership tags.
read: Effect.fn(function* ({ id, olds, output }) {
if (output?.identifier) {
const live = yield* readRule(output.identifier);
if (!live) return undefined;
const attrs = toAttributes(live);
const tags = yield* readRuleTags(attrs.ruleArn);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}
const resourceTypes = olds?.resourceType ? [olds.resourceType] : RULE_RESOURCE_TYPES;
for (const resourceType of resourceTypes) {
const summaries = yield* listRuleSummaries(resourceType);
for (const summary of summaries) {
if (!summary.Identifier || !summary.RuleArn) continue;
const tags = yield* readRuleTags(summary.RuleArn);
if (yield* hasAlchemyTags(id, tags)) {
const live = yield* readRule(summary.Identifier);
if (live) return toAttributes(live);
}
}
}
return undefined;
}),
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return undefined;
yield* validateLock(news);
// The resource type of a retention rule cannot be changed after
// creation — a change requires replacement.
if (news.resourceType !== olds.resourceType) {
return { action: "replace" } as const;
}
// Everything else (retention period, description, resource tags,
// exclusion tags, lock, tags) updates in place.
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
yield* validateLock(news);
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
// OBSERVE — `output.identifier` is only a cache; a rule deleted
// out-of-band falls through to create.
let live = output?.identifier ? yield* readRule(output.identifier) : undefined;
// ENSURE — create if missing, then wait out the transient
// `pending` status so downstream sync reads settled state.
if (live === undefined) {
const created = yield* rbin.createRule({
ResourceType: news.resourceType,
RetentionPeriod: toRetentionPeriod(news.retentionPeriod),
Description: news.description,
...(news.resourceTags ? { ResourceTags: toResourceTags(news.resourceTags) } : {}),
...(news.excludeResourceTags
? {
ExcludeResourceTags: toResourceTags(news.excludeResourceTags),
}
: {}),
...(news.lockConfiguration
? {
LockConfiguration: toLockConfiguration(news.lockConfiguration),
}
: {}),
Tags: createTagsList(desiredTags),
});
yield* session.note(`Created retention rule ${created.Identifier}`);
live = yield* waitForRuleAvailable(created.Identifier!);
}
const identifier = live.Identifier!;
const ruleArn = live.RuleArn!;
// SYNC mutable settings — diff OBSERVED cloud state against the
// desired props and apply only the delta. A no-op skips the API
// call entirely (a fresh create always lands here as a no-op).
const desiredRetention = toRetentionPeriod(news.retentionPeriod);
const desiredResourceTags = toResourceTags(news.resourceTags);
const desiredExcludeTags = toResourceTags(news.excludeResourceTags);
const retentionChanged =
live.RetentionPeriod?.RetentionPeriodValue !== desiredRetention.RetentionPeriodValue ||
live.RetentionPeriod?.RetentionPeriodUnit !== desiredRetention.RetentionPeriodUnit;
const descriptionChanged = (live.Description ?? "") !== (news.description ?? "");
const resourceTagsChanged =
resourceTagsKey(live.ResourceTags) !== resourceTagsKey(desiredResourceTags);
const excludeTagsChanged =
resourceTagsKey(live.ExcludeResourceTags) !== resourceTagsKey(desiredExcludeTags);
if (retentionChanged || descriptionChanged || resourceTagsChanged || excludeTagsChanged) {
yield* rbin.updateRule({
Identifier: identifier,
...(retentionChanged ? { RetentionPeriod: desiredRetention } : {}),
...(descriptionChanged ? { Description: news.description ?? "" } : {}),
...(resourceTagsChanged ? { ResourceTags: desiredResourceTags } : {}),
...(excludeTagsChanged ? { ExcludeResourceTags: desiredExcludeTags } : {}),
});
live = yield* waitForRuleAvailable(identifier);
}
// SYNC lock state — observed lock state vs desired. Unlocking
// starts the unlock delay (`pending_unlock`); re-locking during
// that window is allowed and converges back to `locked`.
if (news.lockConfiguration !== undefined) {
const desiredLock = toLockConfiguration(news.lockConfiguration);
const lockDelta =
live.LockState !== "locked" ||
live.LockConfiguration?.UnlockDelay.UnlockDelayValue !==
desiredLock.UnlockDelay.UnlockDelayValue ||
live.LockConfiguration?.UnlockDelay.UnlockDelayUnit !==
desiredLock.UnlockDelay.UnlockDelayUnit;
if (lockDelta) {
yield* rbin.lockRule({
Identifier: identifier,
LockConfiguration: desiredLock,
});
yield* session.note(`Locked retention rule ${identifier}`);
}
} else if (live.LockState === "locked") {
yield* rbin.unlockRule({ Identifier: identifier });
yield* session.note(
`Unlock initiated for ${identifier}; rule stays protected (pending_unlock) until the unlock delay expires`,
);
}
// SYNC tags — diff against OBSERVED cloud tags (never olds/output)
// so adoption converges.
const currentTags = yield* readRuleTags(ruleArn);
const { upsert, removed } = diffTags(currentTags, desiredTags);
if (upsert.length > 0) {
yield* rbin.tagResource({ ResourceArn: ruleArn, Tags: upsert });
}
if (removed.length > 0) {
yield* rbin.untagResource({
ResourceArn: ruleArn,
TagKeys: removed,
});
}
// RETURN fresh attributes reflecting all sync steps.
const final = yield* rbin.getRule({ Identifier: identifier });
yield* session.note(identifier);
return toAttributes(final);
}),
// Idempotent: a rule already gone is success. A locked rule fails
// with the typed ConflictException (INVALID_RULE_STATE) — it must be
// unlocked and its unlock delay must expire before deletion.
delete: Effect.fn(function* ({ output }) {
yield* rbin
.deleteRule({ Identifier: output.identifier })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
// Deletion is near-immediate, but confirm the rule is gone so
// dependents (and re-creates of the same logical id) never observe
// a half-deleted rule.
yield* retryWhileRuleExists(
Effect.gen(function* () {
const live = yield* readRule(output.identifier);
if (live !== undefined) {
return yield* new RuleStillExists({
identifier: output.identifier,
});
}
}),
);
}),
});
}),
);