alchemy 2.0.0-beta.30 → 2.0.0-beta.32

package/src/AWS/EventBridge/Rule.ts

@@ -1,6 +1,7 @@
 import { Region } from "@distilled.cloud/aws/Region";
 import * as eventbridge from "@distilled.cloud/aws/eventbridge";
 import * as Effect from "effect/Effect";
+import { Unowned } from "../../AdoptPolicy.ts";
 import { isResolved } from "../../Diff.ts";
 import type { Input } from "../../Input.ts";
 import { createPhysicalName } from "../../PhysicalName.ts";
@@ -322,135 +323,91 @@ export const RuleProvider = () =>
           }
 
           const resolvedEventBusName = described.EventBusName ?? eventBusName;
-          return {
+          const ruleArn = toRuleArn(
+            region,
+            accountId,
+            resolvedEventBusName,
+            described.Name,
+          );
+          const { Tags } = yield* eventbridge.listTagsForResource({
+            ResourceARN: described.Arn ?? ruleArn,
+          });
+          const attrs = {
             ruleName: described.Name,
-            ruleArn: toRuleArn(
-              region,
-              accountId,
-              resolvedEventBusName,
-              described.Name,
-            ),
+            ruleArn,
             eventBusName: resolvedEventBusName,
           };
+          return (yield* hasAlchemyTags(id, Tags ?? []))
+            ? attrs
+            : Unowned(attrs);
         }),
-        create: Effect.fn(function* ({ id, news = {}, session }) {
+        reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
           yield* validateRuleProps(news);
-          const ruleName = yield* createRuleName(id, news);
+          const ruleName =
+            output?.ruleName ?? (yield* createRuleName(id, news));
+          const eventBusName =
+            output?.eventBusName ??
+            (news.eventBusName as string | undefined) ??
+            "default";
+          const eventBusParam =
+            eventBusName !== "default" ? eventBusName : undefined;
           const internalTags = yield* createInternalTags(id);
-          const allTags = {
+          const desiredTags = {
             ...internalTags,
             ...(news.tags as Record<string, string> | undefined),
           };
-          const eventBusName =
-            (news.eventBusName as string | undefined) ?? "default";
-          const ruleArn = toRuleArn(region, accountId, eventBusName, ruleName);
-
-          const existing = yield* eventbridge
-            .describeRule({
-              Name: ruleName,
-              EventBusName:
-                eventBusName !== "default" ? eventBusName : undefined,
-            })
-            .pipe(
-              Effect.catchTag("ResourceNotFoundException", () =>
-                Effect.succeed(undefined),
-              ),
-            );
-
-          if (existing) {
-            const { Tags } = yield* eventbridge.listTagsForResource({
-              ResourceARN: existing.Arn ?? ruleArn,
-            });
-
-            if (!(yield* hasAlchemyTags(id, Tags ?? []))) {
-              return yield* Effect.fail(
-                new Error(
-                  `Rule '${ruleName}' already exists on event bus '${eventBusName}' and is not managed by alchemy`,
-                ),
-              );
-            }
-          }
 
+          // Ensure + Sync rule definition — `putRule` is the single
+          // create-or-update API for the rule itself. It's idempotent on
+          // matching params and overwrites schedule/eventPattern/state/etc.
+          // on differences, so we call it unconditionally. `Tags` only
+          // applies when creating; tags are reconciled separately below
+          // against observed cloud tags.
           const { RuleArn } = yield* eventbridge.putRule({
             Name: ruleName,
             Description: news.description,
-            EventBusName: eventBusName !== "default" ? eventBusName : undefined,
+            EventBusName: eventBusParam,
             EventPattern: news.eventPattern
               ? JSON.stringify(news.eventPattern)
               : undefined,
             ScheduleExpression: news.scheduleExpression,
             State: news.state ?? "ENABLED",
             RoleArn: news.roleArn as string | undefined,
-            Tags: createTagsList(allTags),
+            Tags: createTagsList(desiredTags),
           });
+          const ruleArn =
+            (RuleArn as RuleArn | undefined) ??
+            toRuleArn(region, accountId, eventBusName, ruleName);
 
+          // Sync targets — observed cloud targets vs desired. `listTargetsByRule`
+          // gives us the live target ids; we remove anything no longer desired,
+          // and `putTargets` overwrites/upserts the rest.
           const resolvedTargets =
             (news.targets as Input.Resolve<RuleTarget>[] | undefined) ?? [];
-          if (resolvedTargets.length > 0) {
-            const response = yield* eventbridge.putTargets({
+          const desiredTargetIds = new Set(resolvedTargets.map((t) => t.Id));
+          const observedTargets = yield* eventbridge
+            .listTargetsByRule({
               Rule: ruleName,
-              EventBusName:
-                eventBusName !== "default" ? eventBusName : undefined,
-              Targets: resolvedTargets.map(toTarget),
-            });
-            yield* assertPutTargetsSucceeded(response);
-          }
-
-          yield* session.note(ruleArn);
-
-          return {
-            ruleName,
-            ruleArn:
-              (RuleArn as RuleArn | undefined) ??
-              toRuleArn(region, accountId, eventBusName, ruleName),
-            eventBusName,
-          };
-        }),
-        update: Effect.fn(function* ({
-          id,
-          news = {},
-          olds = {},
-          output,
-          session,
-        }) {
-          yield* validateRuleProps(news);
-          const ruleName = output.ruleName;
-          const eventBusName = output.eventBusName;
-          const eventBusParam =
-            eventBusName !== "default" ? eventBusName : undefined;
-
-          yield* eventbridge.putRule({
-            Name: ruleName,
-            Description: news.description,
-            EventBusName: eventBusParam,
-            EventPattern: news.eventPattern
-              ? JSON.stringify(news.eventPattern)
-              : undefined,
-            ScheduleExpression: news.scheduleExpression,
-            State: news.state ?? "ENABLED",
-            RoleArn: news.roleArn as string | undefined,
-          });
-
-          const oldTargetIds = new Set(
-            (
-              (olds.targets as Input.Resolve<RuleTarget>[] | undefined) ?? []
-            ).map((t) => t.Id),
-          );
-          const newTargetIds = new Set(
-            (
-              (news.targets as Input.Resolve<RuleTarget>[] | undefined) ?? []
-            ).map((t) => t.Id),
-          );
-          const removedIds = [...oldTargetIds].filter(
-            (id) => !newTargetIds.has(id),
-          );
+              EventBusName: eventBusParam,
+            })
+            .pipe(
+              Effect.map((r) => r.Targets ?? []),
+              Effect.catchTag("ResourceNotFoundException", () =>
+                Effect.succeed([] as eventbridge.Target[]),
+              ),
+            );
+          const removedTargetIds = observedTargets
+            .map((t) => t.Id)
+            .filter(
+              (tid): tid is string => !!tid && !desiredTargetIds.has(tid),
+            );
 
-          if (removedIds.length > 0) {
+          if (removedTargetIds.length > 0) {
             const response = yield* eventbridge
               .removeTargets({
                 Rule: ruleName,
                 EventBusName: eventBusParam,
-                Ids: removedIds,
+                Ids: removedTargetIds,
               })
               .pipe(
                 Effect.catchTag("ResourceNotFoundException", () =>
@@ -463,8 +420,6 @@ export const RuleProvider = () =>
             }
           }
 
-          const resolvedTargets =
-            (news.targets as Input.Resolve<RuleTarget>[] | undefined) ?? [];
           if (resolvedTargets.length > 0) {
             const response = yield* eventbridge.putTargets({
               Rule: ruleName,
@@ -474,33 +429,41 @@ export const RuleProvider = () =>
             yield* assertPutTargetsSucceeded(response);
           }
 
-          const internalTags = yield* createInternalTags(id);
-          const oldTags = {
-            ...internalTags,
-            ...(olds.tags as Record<string, string> | undefined),
-          };
-          const newTags = {
-            ...internalTags,
-            ...(news.tags as Record<string, string> | undefined),
-          };
-          const { removed, upsert } = diffTags(oldTags, newTags);
+          // Sync tags — diff observed cloud tags against desired. Adoption
+          // and partial prior runs both converge here.
+          const observedTagsList = yield* eventbridge
+            .listTagsForResource({
+              ResourceARN: ruleArn,
+            })
+            .pipe(Effect.map((r) => r.Tags ?? []));
+          const observedTags: Record<string, string> = {};
+          for (const tag of observedTagsList) {
+            if (tag.Key && tag.Value !== undefined) {
+              observedTags[tag.Key] = tag.Value;
+            }
+          }
+          const { removed, upsert } = diffTags(observedTags, desiredTags);
 
           if (removed.length > 0) {
             yield* eventbridge.untagResource({
-              ResourceARN: output.ruleArn,
+              ResourceARN: ruleArn,
               TagKeys: removed,
             });
           }
 
           if (upsert.length > 0) {
             yield* eventbridge.tagResource({
-              ResourceARN: output.ruleArn,
+              ResourceARN: ruleArn,
               Tags: upsert,
             });
           }
 
-          yield* session.note(output.ruleArn);
-          return output;
+          yield* session.note(ruleArn);
+          return {
+            ruleName,
+            ruleArn,
+            eventBusName,
+          };
         }),
         delete: Effect.fn(function* (input) {
           const ruleName = input.output.ruleName;

package/src/AWS/IAM/AccessKey.ts

@@ -94,45 +94,72 @@ export const AccessKeyProvider = () =>
         lastUsedRegion: lastUsed?.AccessKeyLastUsed?.Region,
       };
     }),
-    create: Effect.fn(function* ({ news, session }) {
-      const created = yield* iam.createAccessKey({
-        UserName: news.userName,
-      });
-      if (
-        news.status !== undefined &&
-        created.AccessKey.Status !== news.status
-      ) {
-        yield* iam.updateAccessKey({
+    reconcile: Effect.fn(function* ({ news, output, session }) {
+      // Observe — `accessKeyId` is generated by AWS, so we can only locate
+      // an existing key when we already have its id from a prior output.
+      // Without it (first reconciliation), we go straight to create.
+      const existing = output
+        ? yield* iam.listAccessKeys({ UserName: output.userName }).pipe(
+            Effect.map((listed) =>
+              listed.AccessKeyMetadata.find(
+                (entry) => entry.AccessKeyId === output.accessKeyId,
+              ),
+            ),
+            Effect.catchTag("NoSuchEntityException", () =>
+              Effect.succeed(undefined),
+            ),
+          )
+        : undefined;
+
+      // Ensure — create the access key if it does not exist on the cloud.
+      // The secret is only returned at creation time, so on adoption the
+      // best we can do is preserve any redacted value already stored.
+      let accessKeyId = existing?.AccessKeyId ?? output?.accessKeyId;
+      let secretAccessKey = output?.secretAccessKey;
+      let createDate: Date | undefined =
+        existing?.CreateDate ?? output?.createDate;
+
+      if (!existing) {
+        const created = yield* iam.createAccessKey({
           UserName: news.userName,
-          AccessKeyId: created.AccessKey.AccessKeyId,
-          Status: news.status,
         });
+        accessKeyId = created.AccessKey.AccessKeyId;
+        secretAccessKey = toRedactedString(created.AccessKey.SecretAccessKey);
+        createDate = created.AccessKey.CreateDate;
       }
-      yield* session.note(created.AccessKey.AccessKeyId);
-      return {
-        userName: created.AccessKey.UserName,
-        accessKeyId: created.AccessKey.AccessKeyId,
-        status: news.status ?? created.AccessKey.Status,
-        createDate: created.AccessKey.CreateDate,
-        secretAccessKey: toRedactedString(created.AccessKey.SecretAccessKey),
-        lastUsedDate: undefined,
-        lastUsedServiceName: undefined,
-        lastUsedRegion: undefined,
-      };
-    }),
-    update: Effect.fn(function* ({ news, output, session }) {
-      const status = news.status ?? output.status;
-      if (status !== output.status) {
+
+      if (!accessKeyId) {
+        return yield* Effect.fail(
+          new Error(`AccessKey for user '${news.userName}' has no id`),
+        );
+      }
+
+      // Sync — apply the desired status when it differs from the observed
+      // value. Default of `Active` matches AWS's behaviour.
+      const observedStatus = existing?.Status ?? output?.status ?? "Active";
+      const desiredStatus = news.status ?? observedStatus;
+      if (desiredStatus !== observedStatus) {
         yield* iam.updateAccessKey({
-          UserName: output.userName,
-          AccessKeyId: output.accessKeyId,
-          Status: status,
+          UserName: news.userName,
+          AccessKeyId: accessKeyId,
+          Status: desiredStatus,
         });
       }
-      yield* session.note(output.accessKeyId);
+
+      const lastUsed = yield* iam.getAccessKeyLastUsed({
+        AccessKeyId: accessKeyId,
+      });
+
+      yield* session.note(accessKeyId);
       return {
-        ...output,
-        status,
+        userName: existing?.UserName ?? news.userName,
+        accessKeyId,
+        status: desiredStatus,
+        createDate,
+        secretAccessKey,
+        lastUsedDate: lastUsed?.AccessKeyLastUsed?.LastUsedDate,
+        lastUsedServiceName: lastUsed?.AccessKeyLastUsed?.ServiceName,
+        lastUsedRegion: lastUsed?.AccessKeyLastUsed?.Region,
       };
     }),
     delete: Effect.fn(function* ({ output }) {

package/src/AWS/IAM/AccountAlias.ts

@@ -59,34 +59,29 @@ export const AccountAliasProvider = () =>
       }
       return { accountAlias };
     }),
-    create: Effect.fn(function* ({ news, session }) {
+    reconcile: Effect.fn(function* ({ news, session }) {
+      // Observe — the account alias is a singleton; the only way to know
+      // which alias is set is to list and take the first entry.
       const existing = yield* readAccountAlias;
-      if (existing && existing !== news.accountAlias) {
-        return yield* Effect.fail(
-          new Error(
-            `Account alias '${existing}' already exists and must be removed before '${news.accountAlias}' can be created`,
-          ),
-        );
-      }
-      if (!existing) {
-        yield* iam.createAccountAlias({
-          AccountAlias: news.accountAlias,
-        });
-      }
-      yield* session.note(news.accountAlias);
-      return { accountAlias: news.accountAlias };
-    }),
-    update: Effect.fn(function* ({ news, olds, session }) {
-      if (olds.accountAlias !== news.accountAlias) {
+
+      // Ensure / Sync — IAM only allows a single alias per account, so
+      // applying the desired alias is just `createAccountAlias`. If a
+      // different alias already exists, replace it by creating the new one
+      // and deleting the old (the API also supports overwriting in a
+      // single call but we keep delete idempotent).
+      if (existing !== news.accountAlias) {
         yield* iam.createAccountAlias({
           AccountAlias: news.accountAlias,
         });
-        yield* iam
-          .deleteAccountAlias({
-            AccountAlias: olds.accountAlias,
-          })
-          .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
+        if (existing && existing !== news.accountAlias) {
+          yield* iam
+            .deleteAccountAlias({
+              AccountAlias: existing,
+            })
+            .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
+        }
       }
+
       yield* session.note(news.accountAlias);
       return { accountAlias: news.accountAlias };
     }),

package/src/AWS/IAM/AccountPasswordPolicy.ts

@@ -50,12 +50,11 @@ export const AccountPasswordPolicyProvider = () =>
         );
       return response?.PasswordPolicy;
     }),
-    create: Effect.fn(function* ({ news, session }) {
-      yield* iam.updateAccountPasswordPolicy(news);
-      yield* session.note("account-password-policy");
-      return news;
-    }),
-    update: Effect.fn(function* ({ news, session }) {
+    reconcile: Effect.fn(function* ({ news, session }) {
+      // The account password policy is a singleton driven entirely by
+      // `updateAccountPasswordPolicy`, which is itself a full upsert.
+      // Observation is implicit in the API — there is nothing meaningful
+      // to diff because the request payload *is* the desired state.
       yield* iam.updateAccountPasswordPolicy(news);
       yield* session.note("account-password-policy");
       return news;

package/src/AWS/IAM/Group.ts

@@ -233,58 +233,69 @@ export const GroupProvider = () =>
             inlinePolicies,
           };
         }),
-        create: Effect.fn(function* ({ id, news, session }) {
-          const groupName = yield* toName(id, news);
-          const created = yield* iam
-            .createGroup({
-              GroupName: groupName,
-              Path: news.path,
-            })
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const groupName = output?.groupName ?? (yield* toName(id, news));
+
+          // Observe — fetch the live group. `getGroup` returns
+          // `NoSuchEntityException` when the group has not been created or
+          // was deleted out-of-band, in which case we fall through to the
+          // ensure step below.
+          let observed = yield* iam
+            .getGroup({ GroupName: groupName })
             .pipe(
-              Effect.catchTag("EntityAlreadyExistsException", () =>
-                iam
-                  .getGroup({
-                    GroupName: groupName,
-                  })
-                  .pipe(Effect.map((response) => ({ Group: response.Group }))),
+              Effect.catchTag("NoSuchEntityException", () =>
+                Effect.succeed(undefined),
               ),
             );
 
+          // Ensure — create the group when it is missing. A concurrent
+          // peer reconciler may win the race, so tolerate
+          // `EntityAlreadyExistsException` and reload.
+          if (!observed?.Group?.Arn) {
+            observed = yield* iam
+              .createGroup({
+                GroupName: groupName,
+                Path: news.path,
+              })
+              .pipe(
+                Effect.catchTag("EntityAlreadyExistsException", () =>
+                  iam.getGroup({ GroupName: groupName }),
+                ),
+                Effect.map((response) => ({
+                  Group: response.Group,
+                  Users: [],
+                  IsTruncated: false,
+                })),
+              );
+          }
+
+          // Sync — for each mutable aspect, diff observed against desired
+          // and apply only the delta. We trust the cloud as the source of
+          // truth instead of relying on `olds`.
+          const [observedManagedPolicies, observedInlinePolicies] =
+            yield* Effect.all([
+              readManagedPolicies(groupName),
+              readInlinePolicies(groupName),
+            ]);
+
           yield* syncManagedPolicies({
             groupName,
-            olds: [],
+            olds: observedManagedPolicies,
             news: news.managedPolicyArns ?? [],
           });
           yield* syncInlinePolicies({
             groupName,
-            olds: {},
+            olds: observedInlinePolicies,
             news: news.inlinePolicies ?? {},
           });
 
-          yield* session.note(created.Group?.Arn ?? groupName);
+          const groupArn = observed.Group?.Arn ?? groupName;
+          yield* session.note(groupArn);
           return {
-            groupArn: created.Group?.Arn ?? groupName,
+            groupArn,
             groupName,
-            groupId: created.Group?.GroupId,
-            path: created.Group?.Path ?? news.path ?? "/",
-            managedPolicyArns: news.managedPolicyArns ?? [],
-            inlinePolicies: news.inlinePolicies ?? {},
-          };
-        }),
-        update: Effect.fn(function* ({ news, olds, output, session }) {
-          yield* syncManagedPolicies({
-            groupName: output.groupName,
-            olds: olds.managedPolicyArns ?? [],
-            news: news.managedPolicyArns ?? [],
-          });
-          yield* syncInlinePolicies({
-            groupName: output.groupName,
-            olds: olds.inlinePolicies ?? {},
-            news: news.inlinePolicies ?? {},
-          });
-          yield* session.note(output.groupArn);
-          return {
-            ...output,
+            groupId: observed.Group?.GroupId,
+            path: observed.Group?.Path ?? news.path ?? "/",
             managedPolicyArns: news.managedPolicyArns ?? [],
             inlinePolicies: news.inlinePolicies ?? {},
           };

package/src/AWS/IAM/GroupMembership.ts

@@ -93,44 +93,50 @@ export const GroupMembershipProvider = () =>
           ),
       };
     }),
-    create: Effect.fn(function* ({ news, session }) {
-      for (const userName of news.userNames as string[]) {
-        yield* iam.addUserToGroup({
-          GroupName: news.groupName as string,
-          UserName: userName,
-        });
-      }
-      yield* session.note(news.groupName as string);
-      return {
-        groupName: news.groupName as string,
-        userNames: news.userNames as string[],
-      };
-    }),
-    update: Effect.fn(function* ({ olds, news, output, session }) {
-      const oldSet = new Set(olds.userNames as string[]);
-      const newSet = new Set(news.userNames as string[]);
-      for (const userName of news.userNames as string[]) {
-        if (!oldSet.has(userName)) {
+    reconcile: Effect.fn(function* ({ news, session }) {
+      const groupName = news.groupName as string;
+      const desiredUsers = news.userNames as string[];
+
+      // Observe — read the actual membership of the group. `getGroup`
+      // both confirms the group exists and returns the current user list
+      // in a single call.
+      const response = yield* iam
+        .getGroup({ GroupName: groupName })
+        .pipe(
+          Effect.catchTag("NoSuchEntityException", () =>
+            Effect.succeed(undefined),
+          ),
+        );
+      const observedUsers = (response?.Users ?? [])
+        .map((user) => user.UserName)
+        .filter((userName): userName is string => typeof userName === "string");
+
+      // Sync — diff observed against desired and apply only the delta.
+      const observedSet = new Set(observedUsers);
+      const desiredSet = new Set(desiredUsers);
+      for (const userName of desiredUsers) {
+        if (!observedSet.has(userName)) {
           yield* iam.addUserToGroup({
-            GroupName: output.groupName,
+            GroupName: groupName,
             UserName: userName,
           });
         }
       }
-      for (const userName of olds.userNames as string[]) {
-        if (!newSet.has(userName)) {
+      for (const userName of observedUsers) {
+        if (!desiredSet.has(userName)) {
           yield* iam
             .removeUserFromGroup({
-              GroupName: output.groupName,
+              GroupName: groupName,
               UserName: userName,
             })
             .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
         }
       }
-      yield* session.note(output.groupName);
+
+      yield* session.note(groupName);
       return {
-        groupName: output.groupName,
-        userNames: news.userNames as string[],
+        groupName,
+        userNames: desiredUsers,
       };
     }),
     delete: Effect.fn(function* ({ output }) {