sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ GreengrassV2/ ComponentVersion.ts

import * as greengrassv2 from "@distilled.cloud/aws/greengrassv2";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
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 { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";

export interface ComponentVersionProps {
  /**
   * The inline component recipe, as a JSON or YAML string. The recipe defines
   * the component's name (`ComponentName`), version (`ComponentVersion`),
   * lifecycle, and platform capability.
   *
   * Component versions are immutable — changing the recipe replaces the
   * component version.
   */
  recipe: string;
  /**
   * Tags to apply to the component version. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface ComponentVersion extends Resource<
  "AWS.GreengrassV2.ComponentVersion",
  ComponentVersionProps,
  {
    /** The ARN of this component version. */
    arn: string;
    /** The name of the component. */
    componentName: string;
    /** The semantic version of the component. */
    componentVersion: string;
  },
  never,
  Providers
> {}

/**
 * An IoT Greengrass V2 component version created from an inline recipe.
 * Components are software modules that run on Greengrass core devices.
 *
 * Component versions are immutable in the cloud: any change to the recipe
 * replaces the component version (a new name/version pair is registered and
 * the previous one is deleted). Only tags are mutable in place.
 *
 * ### Creating Component Versions
 * **Example:** Component from an inline JSON recipe
 * ```typescript
 * import * as GreengrassV2 from "@alchemy.run/aws/GreengrassV2";
 *
 * const component = yield* GreengrassV2.ComponentVersion("Hello", {
 *   recipe: JSON.stringify({
 *     RecipeFormatVersion: "2020-01-25",
 *     ComponentName: "com.example.Hello",
 *     ComponentVersion: "1.0.0",
 *     ComponentDescription: "Prints a greeting",
 *     ComponentPublisher: "Example",
 *     Manifests: [
 *       {
 *         Platform: { os: "linux" },
 *         Lifecycle: { run: "echo hello" },
 *       },
 *     ],
 *   }),
 * });
 * ```
 *
 * **Example:** Tagged component version
 * ```typescript
 * const component = yield* GreengrassV2.ComponentVersion("Hello", {
 *   recipe,
 *   tags: { team: "edge" },
 * });
 * ```
 *
 * @resource
 */
export const ComponentVersion = Resource<ComponentVersion>("AWS.GreengrassV2.ComponentVersion");

/**
 * Raised when the inline recipe does not declare a `ComponentName` and
 * `ComponentVersion` that Alchemy can derive the component identity from.
 */
export class GreengrassInvalidRecipe extends Data.TaggedError("GreengrassInvalidRecipe")<{
  message: string;
}> {}

/**
 * Raised when the cloud reports the component version entered the `FAILED`
 * or `DEPRECATED` state instead of becoming `DEPLOYABLE`.
 */
export class GreengrassComponentFailed extends Data.TaggedError("GreengrassComponentFailed")<{
  message: string;
}> {}

/**
 * Internal signal used to poll a freshly created component version until the
 * cloud marks it `DEPLOYABLE`.
 */
export class GreengrassComponentNotReady extends Data.TaggedError("GreengrassComponentNotReady")<{
  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 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 === "GreengrassComponentNotReady",
    schedule: Schedule.max([Schedule.fixed(2000), Schedule.recurs(15)]),
  });

/**
 * Derives `{ componentName, componentVersion }` from an inline recipe string.
 * JSON recipes are parsed; YAML recipes are scanned for the top-level
 * `ComponentName:` / `ComponentVersion:` keys.
 */
const parseRecipeIdentity = Effect.fn(function* (recipe: string) {
  const fromJson = yield* Effect.sync(() => {
    try {
      const parsed = JSON.parse(recipe) as Record<string, unknown>;
      const name = parsed.ComponentName;
      const version = parsed.ComponentVersion;
      return typeof name === "string" && typeof version === "string"
        ? { componentName: name, componentVersion: version }
        : undefined;
    } catch {
      return undefined;
    }
  });
  if (fromJson !== undefined) return fromJson;
  const yamlValue = (key: string) => {
    const match = recipe.match(new RegExp(`^${key}:[ \\t]*['"]?([^'"#\\s]+)`, "m"));
    return match?.[1];
  };
  const componentName = yamlValue("ComponentName");
  const componentVersion = yamlValue("ComponentVersion");
  if (componentName === undefined || componentVersion === undefined) {
    return yield* new GreengrassInvalidRecipe({
      message:
        "the inline recipe must declare top-level ComponentName and ComponentVersion (JSON or YAML)",
    });
  }
  return { componentName, componentVersion };
});

const normalizeTags = (
  tags: { [key: string]: string | undefined } | undefined,
): Record<string, string> =>
  Object.fromEntries(
    Object.entries(tags ?? {}).filter((entry): entry is [string, string] => entry[1] !== undefined),
  );

export const ComponentVersionProvider = () =>
  Provider.effect(
    ComponentVersion,
    Effect.gen(function* () {
      // The component version ARN is deterministic from the recipe identity,
      // so read/reconcile never depend on persisted output to find it.
      const componentArn = Effect.fn(function* (recipe: string) {
        const { accountId, region } = yield* AWSEnvironment.current;
        const { componentName, componentVersion } = yield* parseRecipeIdentity(recipe);
        return {
          componentName,
          componentVersion,
          arn: `arn:aws:greengrass:${region}:${accountId}:components:${componentName}:versions:${componentVersion}`,
        };
      });

      const observeComponent = (arn: string) =>
        greengrassv2
          .describeComponent({ arn })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));

      return ComponentVersion.Provider.of({
        stables: ["arn", "componentName", "componentVersion"],
        list: () =>
          Effect.gen(function* () {
            const components = yield* greengrassv2.listComponents
              .items({ scope: "PRIVATE" })
              .pipe(Stream.runCollect);
            const results: {
              arn: string;
              componentName: string;
              componentVersion: string;
            }[] = [];
            for (const component of components) {
              if (component.arn === undefined) continue;
              const versions = yield* greengrassv2.listComponentVersions
                .items({ arn: component.arn })
                .pipe(
                  Stream.runCollect,
                  Effect.catchTag("ResourceNotFoundException", () => Effect.succeed([] as const)),
                );
              for (const version of versions) {
                if (
                  version.arn !== undefined &&
                  version.componentName !== undefined &&
                  version.componentVersion !== undefined
                ) {
                  results.push({
                    arn: version.arn,
                    componentName: version.componentName,
                    componentVersion: version.componentVersion,
                  });
                }
              }
            }
            return results;
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const arn =
            output?.arn ??
            (olds !== undefined ? (yield* componentArn(olds.recipe)).arn : undefined);
          if (arn === undefined) return undefined;
          const found = yield* observeComponent(arn);
          if (
            found?.arn === undefined ||
            found.componentName === undefined ||
            found.componentVersion === undefined
          ) {
            return undefined;
          }
          const attrs = {
            arn: found.arn,
            componentName: found.componentName,
            componentVersion: found.componentVersion,
          };
          return (yield* hasAlchemyTags(id, normalizeTags(found.tags))) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          // Component versions are immutable — any recipe change replaces.
          if (olds !== undefined && news.recipe !== olds.recipe) {
            return { action: "replace" } as const;
          }
          // fall through: engine default update (tags sync in reconcile)
        }),
        reconcile: Effect.fn(function* ({ id, news, session }) {
          const identity = yield* componentArn(news.recipe);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — cloud state is authoritative.
          let live = yield* observeComponent(identity.arn);

          // 2. ENSURE — create when missing. A concurrent create surfaces as
          //    the typed ConflictException / RequestAlreadyInProgressException
          //    tags, which we treat as races and re-observe.
          if (live === undefined) {
            yield* greengrassv2
              .createComponentVersion({
                inlineRecipe: new TextEncoder().encode(news.recipe),
                tags: desiredTags,
              })
              .pipe(
                Effect.catchTag(
                  ["ConflictException", "RequestAlreadyInProgressException"],
                  () => Effect.undefined,
                ),
              );
            // Wait until the cloud marks the version DEPLOYABLE (bounded ~30s;
            // inline-recipe components typically settle within seconds).
            live = yield* Effect.gen(function* () {
              const observed = yield* observeComponent(identity.arn);
              const state = observed?.status?.componentState;
              if (state === "FAILED" || state === "DEPRECATED") {
                return yield* new GreengrassComponentFailed({
                  message: `component ${identity.componentName}@${identity.componentVersion} entered state ${state}: ${
                    observed?.status?.message ?? "no message"
                  }`,
                });
              }
              if (observed === undefined || state !== "DEPLOYABLE") {
                return yield* new GreengrassComponentNotReady({
                  message: `component ${identity.componentName}@${identity.componentVersion} is ${state ?? "missing"}`,
                });
              }
              return observed;
            }).pipe(retryWhileNotReady);
          }

          // 3. SYNC TAGS — diff against OBSERVED cloud tags so adoption
          //    converges (create-time tags only apply on first create).
          const observedTags = normalizeTags(live.tags);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* greengrassv2.tagResource({
              resourceArn: identity.arn,
              tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* greengrassv2.untagResource({
              resourceArn: identity.arn,
              tagKeys: removed,
            });
          }

          yield* session.note(`${identity.componentName}@${identity.componentVersion}`);
          return {
            arn: identity.arn,
            componentName: identity.componentName,
            componentVersion: identity.componentVersion,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* greengrassv2
            .deleteComponent({ arn: output.arn })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      });
    }),
  );