sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ IoTFleetWise/ StateTemplate.ts

import * as iotfleetwise from "@distilled.cloud/aws/iotfleetwise";
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, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  inFleetWiseRegion,
  readFleetWiseTags,
  retryObservation,
  stableEquals,
  syncFleetWiseTags,
  toFleetWiseTagList,
} from "./internal.ts";

export class StateTemplateUnexpectedResponse extends Data.TaggedError(
  "StateTemplateUnexpectedResponse",
)<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export interface StateTemplateProps {
  /**
   * Name of the state template. Must be 1-100 characters of
   * `[a-zA-Z0-9:_-]`. If omitted, a deterministic physical name is
   * generated. Changing the name replaces the state template.
   */
  stateTemplateName?: string;
  /**
   * Human-readable description of the state template. Updated in place.
   */
  description?: string;
  /**
   * ARN of the {@link SignalCatalog} the state template's signals come
   * from. Changing it replaces the state template.
   */
  signalCatalogArn: string;
  /**
   * Fully qualified names of the signals whose last-known state the
   * template tracks, e.g. `["Vehicle.Speed"]`. Synced in place via
   * add/remove deltas.
   */
  stateTemplateProperties: string[];
  /**
   * Vehicle attribute node paths added as extra dimensions on the state
   * data, e.g. `["Vehicle.VIN"]`. Updated in place.
   */
  dataExtraDimensions?: string[];
  /**
   * Vehicle attribute node paths added as extra dimensions on the MQTT
   * message metadata, e.g. `["Vehicle.VIN"]`. Updated in place.
   */
  metadataExtraDimensions?: string[];
  /**
   * User-defined tags for the state template.
   */
  tags?: Record<string, string>;
}

export interface StateTemplate extends Resource<
  "AWS.IoTFleetWise.StateTemplate",
  StateTemplateProps,
  {
    /** The name of the state template. */
    stateTemplateName: string;
    /** The ARN of the state template. */
    stateTemplateArn: string;
    /** The unique ID of the state template. */
    stateTemplateId: string | undefined;
    /** The signal catalog the state template's signals come from. */
    signalCatalogArn: string | undefined;
    /** The signals whose last-known state the template tracks. */
    stateTemplateProperties: string[];
  },
  never,
  Providers
> {}

/**
 * An AWS IoT FleetWise state template — a definition of which signals'
 * last-known state the Edge Agent reports for a {@link Vehicle}
 * (associated via the vehicle's `stateTemplates` prop).
 *
 * Only the description, tracked properties, and extra dimensions are
 * mutable — changing the name or signal catalog replaces the template.
 * AWS IoT FleetWise is allowlist-gated and offered in
 * `us-east-1`/`eu-central-1` only.
 * ### Creating a State Template
 * **Example:** Track Last-Known Speed
 * ```typescript
 * const template = yield* StateTemplate("SpeedState", {
 *   signalCatalogArn: catalog.signalCatalogArn,
 *   stateTemplateProperties: ["Vehicle.Speed"],
 * });
 * ```
 *
 * **Example:** Associate with a Vehicle
 * ```typescript
 * const vehicle = yield* Vehicle("TestVehicle", {
 *   modelManifestArn: model.modelManifestArn,
 *   decoderManifestArn: decoder.decoderManifestArn,
 *   stateTemplates: [
 *     {
 *       identifier: template.stateTemplateName,
 *       stateTemplateUpdateStrategy: { onChange: {} },
 *     },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const StateTemplate = Resource<StateTemplate>("AWS.IoTFleetWise.StateTemplate");

export const StateTemplateProvider = () =>
  Provider.effect(
    StateTemplate,
    Effect.gen(function* () {
      const toName = (id: string, props: { stateTemplateName?: string }) =>
        props.stateTemplateName
          ? Effect.succeed(props.stateTemplateName)
          : createPhysicalName({ id, maxLength: 100 });

      const readTemplate = Effect.fn(function* (identifier: string) {
        return yield* iotfleetwise.getStateTemplate({ identifier }).pipe(
          inFleetWiseRegion,
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );
      });

      const toAttrs = Effect.fn(function* (template: iotfleetwise.GetStateTemplateResponse) {
        if (template.name === undefined || template.arn === undefined) {
          return yield* new StateTemplateUnexpectedResponse({
            message: `StateTemplate '${template.name}' is missing its ARN`,
          });
        }
        return {
          stateTemplateName: template.name,
          stateTemplateArn: template.arn,
          stateTemplateId: template.id,
          signalCatalogArn: template.signalCatalogArn,
          stateTemplateProperties: [...(template.stateTemplateProperties ?? [])],
        };
      });

      return {
        stables: ["stateTemplateName", "stateTemplateArn", "stateTemplateId"],

        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          if ((yield* toName(id, olds)) !== (yield* toName(id, news))) {
            return { action: "replace" } as const;
          }
          // The backing signal catalog is fixed at creation.
          if (olds.signalCatalogArn !== news.signalCatalogArn) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.stateTemplateName ?? (yield* toName(id, olds ?? {}));
          const found = yield* readTemplate(name);
          if (found?.arn === undefined) return undefined;
          const attrs = yield* toAttrs(found);
          const tags = yield* readFleetWiseTags(found.arn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.stateTemplateName ?? (yield* toName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // 1. Observe — cloud state is authoritative.
          let observed = yield* readTemplate(name);

          // 2. Ensure — create if missing; tolerate the AlreadyExists race.
          if (observed === undefined) {
            yield* iotfleetwise
              .createStateTemplate({
                name,
                description: news.description,
                signalCatalogArn: news.signalCatalogArn,
                stateTemplateProperties: news.stateTemplateProperties,
                dataExtraDimensions: news.dataExtraDimensions,
                metadataExtraDimensions: news.metadataExtraDimensions,
                tags: toFleetWiseTagList(desiredTags),
              })
              .pipe(
                inFleetWiseRegion,
                Effect.catchTag("ConflictException", () => Effect.void),
              );
            observed = yield* readTemplate(name).pipe(
              Effect.flatMap((template) =>
                template === undefined
                  ? Effect.fail(
                      new StateTemplateUnexpectedResponse({
                        message: `StateTemplate '${name}' not found`,
                      }),
                    )
                  : Effect.succeed(template),
              ),
              retryObservation,
            );
          }

          // 3. Sync mutable aspects against OBSERVED cloud state.
          const observedProperties = observed.stateTemplateProperties ?? [];
          const toAdd = news.stateTemplateProperties.filter(
            (fqn) => !observedProperties.includes(fqn),
          );
          const toRemove = observedProperties.filter(
            (fqn) => !news.stateTemplateProperties.includes(fqn),
          );
          const descriptionChanged =
            news.description !== undefined && news.description !== observed.description;
          const dataDimensionsChanged =
            news.dataExtraDimensions !== undefined &&
            !stableEquals(observed.dataExtraDimensions ?? [], news.dataExtraDimensions);
          const metadataDimensionsChanged =
            news.metadataExtraDimensions !== undefined &&
            !stableEquals(observed.metadataExtraDimensions ?? [], news.metadataExtraDimensions);
          if (
            toAdd.length > 0 ||
            toRemove.length > 0 ||
            descriptionChanged ||
            dataDimensionsChanged ||
            metadataDimensionsChanged
          ) {
            yield* iotfleetwise
              .updateStateTemplate({
                identifier: name,
                description: descriptionChanged ? news.description : undefined,
                stateTemplatePropertiesToAdd: toAdd.length > 0 ? toAdd : undefined,
                stateTemplatePropertiesToRemove: toRemove.length > 0 ? toRemove : undefined,
                dataExtraDimensions: dataDimensionsChanged ? news.dataExtraDimensions : undefined,
                metadataExtraDimensions: metadataDimensionsChanged
                  ? news.metadataExtraDimensions
                  : undefined,
              })
              .pipe(inFleetWiseRegion);
            observed = yield* readTemplate(name).pipe(
              Effect.flatMap((template) =>
                template === undefined
                  ? Effect.fail(
                      new StateTemplateUnexpectedResponse({
                        message: `StateTemplate '${name}' not found`,
                      }),
                    )
                  : Effect.succeed(template),
              ),
              retryObservation,
            );
          }

          // 3b. Sync tags against OBSERVED cloud tags.
          const arn = observed.arn;
          if (arn !== undefined) {
            yield* syncFleetWiseTags(arn, desiredTags);
          }

          yield* session.note(name);
          return yield* toAttrs(observed);
        }),

        delete: Effect.fn(function* ({ output }) {
          // DeleteStateTemplate is idempotent — deleting a missing template
          // succeeds (its error union carries no not-found tag).
          yield* iotfleetwise
            .deleteStateTemplate({ identifier: output.stateTemplateName })
            .pipe(inFleetWiseRegion);
        }),

        list: () =>
          iotfleetwise.listStateTemplates.items({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((summary) =>
                summary.name !== undefined && summary.arn !== undefined
                  ? [
                      {
                        stateTemplateName: summary.name,
                        stateTemplateArn: summary.arn,
                        stateTemplateId: summary.id,
                        signalCatalogArn: summary.signalCatalogArn,
                        stateTemplateProperties: [] as string[],
                      },
                    ]
                  : [],
              ),
            ),
            inFleetWiseRegion,
          ),
      };
    }),
  );