sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ IoTFleetWise/ Campaign.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 { toWireMillis, toWireSeconds } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  inFleetWiseRegion,
  readFleetWiseTags,
  retryObservation,
  stableEquals,
  syncFleetWiseTags,
  toFleetWiseTagList,
} from "./internal.ts";

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

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

/**
 * Time-based collection: collect the signals on a fixed cadence.
 */
export interface TimeBasedCollectionScheme {
  /**
   * How often to collect the signals, e.g. `"10 seconds"` or
   * `Duration.seconds(10)`. A bare number is milliseconds. Sent to
   * FleetWise as whole milliseconds (`periodMs`, 50 ms - 60 s).
   */
  period: Duration.Input;
}

/**
 * Condition-based collection: collect the signals whenever the expression
 * evaluates true.
 */
export interface ConditionBasedCollectionScheme {
  /**
   * The logical expression that triggers collection, e.g.
   * `$variable.\`Vehicle.OutsideAirTemperature\` >= 105.0`.
   */
  expression: string | Redacted.Redacted<string>;
  /**
   * Minimum time between two triggers, e.g. `"1 second"`. A bare number
   * is milliseconds. Sent to FleetWise as whole milliseconds
   * (`minimumTriggerIntervalMs`).
   * @default 0
   */
  minimumTriggerInterval?: Duration.Input;
  /**
   * Whether to trigger on every evaluation (`"ALWAYS"`) or only when the
   * expression flips to true (`"RISING_EDGE"`).
   * @default "ALWAYS"
   */
  triggerMode?: iotfleetwise.TriggerMode;
  /**
   * Version of the condition language.
   * @default 1
   */
  conditionLanguageVersion?: number;
}

/**
 * When to collect data — exactly one of a time-based or condition-based
 * scheme.
 */
export type CollectionScheme =
  | {
      timeBasedCollectionScheme: TimeBasedCollectionScheme;
      conditionBasedCollectionScheme?: never;
    }
  | {
      timeBasedCollectionScheme?: never;
      conditionBasedCollectionScheme: ConditionBasedCollectionScheme;
    };

/** A signal the campaign collects from vehicles. */
export interface SignalInformation {
  /** The name of the signal, e.g. `Vehicle.Speed`. */
  name: string;
  /** Maximum number of samples collected per trigger. */
  maxSampleCount?: number;
  /**
   * Minimum time between two samples of this signal, e.g. `"500 millis"`.
   * A bare number is milliseconds. Sent to FleetWise as whole milliseconds
   * (`minimumSamplingIntervalMs`).
   */
  minimumSamplingInterval?: Duration.Input;
  /** The ID of the data partition the signal is stored in. */
  dataPartitionId?: string;
}

/** Time-based on-demand fetch: run the fetch actions on a fixed cadence. */
export interface TimeBasedSignalFetchConfig {
  /**
   * How often to fetch the signal, e.g. `"1 minute"`. A bare number is
   * milliseconds. Sent to FleetWise as whole milliseconds
   * (`executionFrequencyMs`).
   */
  executionFrequency: Duration.Input;
}

/** How an on-demand signal fetch is triggered. */
export type SignalFetchConfig =
  | {
      timeBased: TimeBasedSignalFetchConfig;
      conditionBased?: never;
    }
  | {
      timeBased?: never;
      conditionBased: iotfleetwise.ConditionBasedSignalFetchConfig;
    };

/** A signal fetched on demand by actuator-triggered fetch configs. */
export interface SignalFetchInformation {
  /** The fully-qualified name of the signal to fetch. */
  fullyQualifiedName: string;
  /** When the fetch runs — time-based or condition-based. */
  signalFetchConfig: SignalFetchConfig;
  /**
   * Version of the condition language used by condition-based configs.
   * @default 1
   */
  conditionLanguageVersion?: number;
  /** The actions (expressions) evaluated when the fetch triggers. */
  actions: (string | Redacted.Redacted<string>)[];
}

const toWireCollectionScheme = (scheme: CollectionScheme): iotfleetwise.CollectionScheme =>
  scheme.timeBasedCollectionScheme !== undefined
    ? {
        timeBasedCollectionScheme: {
          periodMs: toWireMillis(scheme.timeBasedCollectionScheme.period)!,
        },
      }
    : {
        conditionBasedCollectionScheme: {
          expression: scheme.conditionBasedCollectionScheme.expression,
          minimumTriggerIntervalMs: toWireMillis(
            scheme.conditionBasedCollectionScheme.minimumTriggerInterval,
          ),
          triggerMode: scheme.conditionBasedCollectionScheme.triggerMode,
          conditionLanguageVersion: scheme.conditionBasedCollectionScheme.conditionLanguageVersion,
        },
      };

const toWireSignalsToCollect = (
  signals: SignalInformation[] | undefined,
): iotfleetwise.SignalInformation[] | undefined =>
  signals?.map((signal) => ({
    name: signal.name,
    maxSampleCount: signal.maxSampleCount,
    minimumSamplingIntervalMs: toWireMillis(signal.minimumSamplingInterval),
    dataPartitionId: signal.dataPartitionId,
  }));

const toWireSignalsToFetch = (
  signals: SignalFetchInformation[] | undefined,
): iotfleetwise.SignalFetchInformation[] | undefined =>
  signals?.map((signal) => ({
    fullyQualifiedName: signal.fullyQualifiedName,
    signalFetchConfig:
      signal.signalFetchConfig.timeBased !== undefined
        ? {
            timeBased: {
              executionFrequencyMs: toWireMillis(
                signal.signalFetchConfig.timeBased.executionFrequency,
              )!,
            },
          }
        : { conditionBased: signal.signalFetchConfig.conditionBased },
    conditionLanguageVersion: signal.conditionLanguageVersion,
    actions: signal.actions,
  }));

export interface CampaignProps {
  /**
   * Name of the campaign. Must be 1-100 characters of `[a-zA-Z0-9:_-]`.
   * If omitted, a deterministic physical name is generated. Changing the
   * name replaces the campaign.
   */
  campaignName?: string;
  /**
   * Human-readable description of the campaign. Updated in place.
   */
  description?: string;
  /**
   * ARN of the {@link SignalCatalog} the collected signals come from.
   * Changing it replaces the campaign.
   */
  signalCatalogArn: string;
  /**
   * ARN of the {@link Fleet} or {@link Vehicle} the campaign deploys to.
   * Changing it replaces the campaign.
   */
  targetArn: string;
  /**
   * When to collect data — a time-based or condition-based scheme.
   * Changing it replaces the campaign.
   */
  collectionScheme: CollectionScheme;
  /**
   * Signals to collect from vehicles. Changing them replaces the
   * campaign.
   */
  signalsToCollect?: SignalInformation[];
  /**
   * Destinations (S3, Timestream or MQTT topic) the collected data is
   * delivered to. Changing them replaces the campaign.
   */
  dataDestinationConfigs?: iotfleetwise.DataDestinationConfig[];
  /**
   * Time the campaign starts collecting data, as an ISO-8601 string.
   * Changing it replaces the campaign.
   * @default now
   */
  startTime?: string;
  /**
   * Time the campaign expires, as an ISO-8601 string. Changing it
   * replaces the campaign.
   * @default 253402214400 (9999-12-31)
   */
  expiryTime?: string;
  /**
   * How long to keep collecting data after a condition-based trigger
   * fires, e.g. `"30 seconds"` or `Duration.seconds(30)`. Sent to
   * FleetWise as whole seconds (a bare number is milliseconds).
   * Changing it replaces the campaign.
   * @default 0
   */
  postTriggerCollectionDuration?: Duration.Input;
  /**
   * Whether to send active diagnostic trouble codes — `"OFF"` or
   * `"SEND_ACTIVE_DTCS"`. Changing it replaces the campaign.
   * @default "OFF"
   */
  diagnosticsMode?: iotfleetwise.DiagnosticsMode;
  /**
   * Whether to store collected data offline when a vehicle lacks
   * connectivity — `"OFF"` or `"TO_DISK"`. Changing it replaces the
   * campaign.
   * @default "OFF"
   */
  spoolingMode?: iotfleetwise.SpoolingMode;
  /**
   * Whether to compress vehicle-to-cloud transmissions — `"OFF"` or
   * `"SNAPPY"`. Changing it replaces the campaign.
   * @default "OFF"
   */
  compression?: iotfleetwise.Compression;
  /**
   * Vehicle attribute node paths added as extra dimensions on the
   * collected data, e.g. `["Vehicle.VIN"]`. Updated in place.
   */
  dataExtraDimensions?: string[];
  /**
   * Data partitions for on-vehicle storage (requires spooling to disk).
   * Changing them replaces the campaign.
   */
  dataPartitions?: iotfleetwise.DataPartition[];
  /**
   * Signals fetched on demand by actuator-triggered fetch configs.
   * Changing them replaces the campaign.
   */
  signalsToFetch?: SignalFetchInformation[];
  /**
   * Whether the provider approves the campaign (transitioning it from
   * `WAITING_FOR_APPROVAL` to `RUNNING`) after creation.
   * @default false
   */
  autoApprove?: boolean;
  /**
   * User-defined tags for the campaign.
   */
  tags?: Record<string, string>;
}

export interface Campaign extends Resource<
  "AWS.IoTFleetWise.Campaign",
  CampaignProps,
  {
    /** The name of the campaign. */
    campaignName: string;
    /** The ARN of the campaign. */
    campaignArn: string;
    /** The current status of the campaign (`RUNNING`, `SUSPENDED`, ...). */
    status: string;
    /** The signal catalog the campaign collects from. */
    signalCatalogArn: string | undefined;
    /** The fleet or vehicle the campaign targets. */
    targetArn: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An AWS IoT FleetWise campaign — the orchestration of data-collection
 * rules that the Edge Agent uses to decide which signals to collect from
 * a {@link Fleet} or {@link Vehicle} and where to deliver them.
 *
 * Campaigns are created in `WAITING_FOR_APPROVAL` status; set
 * `autoApprove: true` to have the provider approve them into `RUNNING`.
 * Only the description and extra dimensions are mutable — every other
 * change replaces the campaign. AWS IoT FleetWise is allowlist-gated and
 * offered in `us-east-1`/`eu-central-1` only.
 * ### Creating a Campaign
 * **Example:** Time-Based Collection to S3
 * ```typescript
 * const campaign = yield* Campaign("SpeedTelemetry", {
 *   signalCatalogArn: catalog.signalCatalogArn,
 *   targetArn: fleet.fleetArn,
 *   collectionScheme: {
 *     timeBasedCollectionScheme: { period: "10 seconds" },
 *   },
 *   signalsToCollect: [{ name: "Vehicle.Speed" }],
 *   dataDestinationConfigs: [
 *     { s3Config: { bucketArn: bucket.bucketArn } },
 *   ],
 *   autoApprove: true,
 * });
 * ```
 *
 * **Example:** Condition-Based Collection
 * ```typescript
 * const campaign = yield* Campaign("HardBraking", {
 *   signalCatalogArn: catalog.signalCatalogArn,
 *   targetArn: fleet.fleetArn,
 *   collectionScheme: {
 *     conditionBasedCollectionScheme: {
 *       expression: "$variable.`Vehicle.Speed` > 120.0",
 *       minimumTriggerInterval: "5 seconds",
 *       triggerMode: "RISING_EDGE",
 *     },
 *   },
 *   signalsToCollect: [
 *     { name: "Vehicle.Speed", minimumSamplingInterval: "500 millis" },
 *   ],
 *   postTriggerCollectionDuration: "30 seconds",
 *   dataDestinationConfigs: [
 *     { s3Config: { bucketArn: bucket.bucketArn } },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const Campaign = Resource<Campaign>("AWS.IoTFleetWise.Campaign");

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

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

      // Campaign provisioning is asynchronous (status CREATING). Bounded
      // wait until the service settles it into an actionable status.
      const waitUntilSettled = Effect.fn(function* (name: string) {
        return yield* readCampaign(name).pipe(
          Effect.flatMap((campaign) => {
            if (campaign === undefined) {
              return Effect.fail(new CampaignNotReady({ message: `Campaign '${name}' not found` }));
            }
            if (campaign.status === "CREATING") {
              return Effect.fail(
                new CampaignNotReady({ message: `Campaign '${name}' still creating` }),
              );
            }
            return Effect.succeed(campaign);
          }),
          retryObservation,
        );
      });

      const toAttrs = Effect.fn(function* (campaign: iotfleetwise.GetCampaignResponse) {
        if (campaign.name === undefined || campaign.arn === undefined) {
          return yield* new CampaignUnexpectedResponse({
            message: `Campaign '${campaign.name}' is missing its ARN`,
          });
        }
        return {
          campaignName: campaign.name,
          campaignArn: campaign.arn,
          status: campaign.status ?? "CREATING",
          signalCatalogArn: campaign.signalCatalogArn,
          targetArn: campaign.targetArn,
        };
      });

      return {
        stables: ["campaignName", "campaignArn"],

        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;
          }
          // Only description and dataExtraDimensions are mutable; every
          // other property is fixed at creation.
          const createOnly = (props: CampaignProps) => ({
            signalCatalogArn: props.signalCatalogArn,
            targetArn: props.targetArn,
            // Durations are compared in wire units so that equivalent
            // inputs ("10 seconds" vs 10_000) never force a replacement.
            collectionScheme: toWireCollectionScheme(props.collectionScheme),
            signalsToCollect: toWireSignalsToCollect(props.signalsToCollect),
            dataDestinationConfigs: props.dataDestinationConfigs,
            startTime: props.startTime,
            expiryTime: props.expiryTime,
            postTriggerCollectionDuration: toWireSeconds(props.postTriggerCollectionDuration),
            diagnosticsMode: props.diagnosticsMode,
            spoolingMode: props.spoolingMode,
            compression: props.compression,
            dataPartitions: props.dataPartitions,
            signalsToFetch: toWireSignalsToFetch(props.signalsToFetch),
          });
          if (!stableEquals(createOnly(olds), createOnly(news))) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.campaignName ?? (yield* toName(id, olds ?? {}));
          const found = yield* readCampaign(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?.campaignName ?? (yield* toName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

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

          // 2. Ensure — create if missing; tolerate the AlreadyExists race.
          if (observed === undefined) {
            yield* iotfleetwise
              .createCampaign({
                name,
                description: news.description,
                signalCatalogArn: news.signalCatalogArn,
                targetArn: news.targetArn,
                collectionScheme: toWireCollectionScheme(news.collectionScheme),
                signalsToCollect: toWireSignalsToCollect(news.signalsToCollect),
                dataDestinationConfigs: news.dataDestinationConfigs,
                startTime: news.startTime !== undefined ? new Date(news.startTime) : undefined,
                expiryTime: news.expiryTime !== undefined ? new Date(news.expiryTime) : undefined,
                postTriggerCollectionDuration: toWireSeconds(news.postTriggerCollectionDuration),
                diagnosticsMode: news.diagnosticsMode,
                spoolingMode: news.spoolingMode,
                compression: news.compression,
                dataExtraDimensions: news.dataExtraDimensions,
                dataPartitions: news.dataPartitions,
                signalsToFetch: toWireSignalsToFetch(news.signalsToFetch),
                tags: toFleetWiseTagList(desiredTags),
              })
              .pipe(
                inFleetWiseRegion,
                Effect.catchTag("ConflictException", () => Effect.void),
              );
          }
          observed = yield* waitUntilSettled(name);

          // 3. Sync mutable aspects — description / dataExtraDimensions via
          //    the UPDATE action, applied only on an observed delta.
          const descriptionChanged =
            news.description !== undefined && news.description !== observed.description;
          const dimensionsChanged =
            news.dataExtraDimensions !== undefined &&
            !stableEquals(observed.dataExtraDimensions ?? [], news.dataExtraDimensions);
          if (descriptionChanged || dimensionsChanged) {
            yield* iotfleetwise
              .updateCampaign({
                name,
                action: "UPDATE",
                description: descriptionChanged ? news.description : undefined,
                dataExtraDimensions: dimensionsChanged ? news.dataExtraDimensions : undefined,
              })
              .pipe(inFleetWiseRegion);
          }

          // 3b. Approve a waiting campaign when requested.
          if (news.autoApprove === true && observed.status === "WAITING_FOR_APPROVAL") {
            yield* iotfleetwise.updateCampaign({ name, action: "APPROVE" }).pipe(inFleetWiseRegion);
          }

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

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

        delete: Effect.fn(function* ({ output }) {
          // Deleting a campaign suspends data collection and removes it
          // from vehicles; deleting a missing campaign is success.
          yield* iotfleetwise.deleteCampaign({ name: output.campaignName }).pipe(
            inFleetWiseRegion,
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );
        }),

        list: () =>
          iotfleetwise.listCampaigns.items({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((summary) =>
                summary.name !== undefined && summary.arn !== undefined
                  ? [
                      {
                        campaignName: summary.name,
                        campaignArn: summary.arn,
                        status: summary.status ?? "CREATING",
                        signalCatalogArn: summary.signalCatalogArn,
                        targetArn: summary.targetArn,
                      },
                    ]
                  : [],
              ),
            ),
            inFleetWiseRegion,
          ),
      };
    }),
  );