sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ApplicationSignals/ ServiceLevelObjective.ts

import * as appsignals from "@distilled.cloud/aws/application-signals";
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, createTagsList, diffTags, 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";

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

export interface ServiceLevelObjectiveProps {
  /**
   * Name of the SLO (up to 127 characters, pattern
   * `[0-9A-Za-z][-._A-Za-z0-9 ]*`). Changing the name replaces the SLO —
   * the API has no rename operation.
   * @default ${app}-${stage}-${id}
   */
  sloName?: string;
  /**
   * A human-readable description of the SLO. Shown in the CloudWatch
   * console next to the SLO.
   */
  description?: string;
  /**
   * Period-based service level indicator: a CloudWatch metric (via
   * `SliMetricConfig.MetricDataQueries` for any metric or math expression,
   * or the `KeyAttributes`/`OperationName` shorthand for services discovered
   * by Application Signals), a `MetricThreshold`, and a `ComparisonOperator`.
   *
   * Exactly one of `sliConfig` or `requestBasedSliConfig` must be provided.
   * Switching between them replaces the SLO — the evaluation type of an
   * existing SLO cannot be changed.
   */
  sliConfig?: appsignals.ServiceLevelIndicatorConfig;
  /**
   * Request-based service level indicator: `TotalRequestCountMetric` plus a
   * `GoodCountMetric` or `BadCountMetric` under
   * `RequestBasedSliMetricConfig.MonitoredRequestCountMetric`.
   *
   * Exactly one of `sliConfig` or `requestBasedSliConfig` must be provided.
   * Switching between them replaces the SLO.
   */
  requestBasedSliConfig?: appsignals.RequestBasedServiceLevelIndicatorConfig;
  /**
   * The attainment goal for the SLO: the `Interval` (rolling or calendar),
   * the `AttainmentGoal` percentage, and the `WarningThreshold`.
   * @default rolling 7-day interval, 99% attainment, 30% warning threshold
   */
  goal?: appsignals.Goal;
  /**
   * Burn-rate windows to compute for the SLO. Each entry creates a burn-rate
   * metric over the given look-back window.
   */
  burnRateConfigurations?: appsignals.BurnRateConfiguration[];
  /**
   * Tags to apply to the SLO. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface ServiceLevelObjective extends Resource<
  "AWS.ApplicationSignals.ServiceLevelObjective",
  ServiceLevelObjectiveProps,
  {
    /**
     * Name of the service level objective.
     */
    sloName: string;
    /**
     * ARN of the service level objective.
     */
    sloArn: string;
    /**
     * How the SLO is evaluated (`PeriodBased` or `RequestBased`).
     */
    evaluationType: appsignals.EvaluationType | undefined;
  },
  never,
  Providers
> {}

/**
 * A CloudWatch Application Signals service level objective (SLO) that tracks
 * an attainment goal against a service level indicator — any CloudWatch
 * metric or metric-math expression, or a service operation discovered by
 * Application Signals.
 * ### Creating Service Level Objectives
 * **Example:** Period-based SLO on a CloudWatch metric
 * ```typescript
 * import * as ApplicationSignals from "@alchemy.run/aws/ApplicationSignals";
 *
 * const slo = yield* ApplicationSignals.ServiceLevelObjective("ApiLatency", {
 *   description: "p99 latency under 2 seconds",
 *   sliConfig: {
 *     SliMetricConfig: {
 *       MetricDataQueries: [
 *         {
 *           Id: "m1",
 *           MetricStat: {
 *             Metric: {
 *               Namespace: "AWS/Lambda",
 *               MetricName: "Duration",
 *               Dimensions: [{ Name: "FunctionName", Value: "my-api" }],
 *             },
 *             Period: 60,
 *             Stat: "p99",
 *           },
 *           ReturnData: true,
 *         },
 *       ],
 *     },
 *     MetricThreshold: 2000,
 *     ComparisonOperator: "LessThanOrEqualTo",
 *   },
 *   goal: {
 *     Interval: { RollingInterval: { DurationUnit: "DAY", Duration: 7 } },
 *     AttainmentGoal: 99,
 *     WarningThreshold: 50,
 *   },
 * });
 * ```
 *
 * **Example:** Request-based SLO
 * ```typescript
 * const slo = yield* ApplicationSignals.ServiceLevelObjective("Availability", {
 *   requestBasedSliConfig: {
 *     RequestBasedSliMetricConfig: {
 *       TotalRequestCountMetric: [
 *         {
 *           Id: "total",
 *           MetricStat: {
 *             Metric: { Namespace: "AWS/ApplicationELB", MetricName: "RequestCount" },
 *             Period: 60,
 *             Stat: "Sum",
 *           },
 *           ReturnData: true,
 *         },
 *       ],
 *       MonitoredRequestCountMetric: {
 *         BadCountMetric: [
 *           {
 *             Id: "bad",
 *             MetricStat: {
 *               Metric: { Namespace: "AWS/ApplicationELB", MetricName: "HTTPCode_Target_5XX_Count" },
 *               Period: 60,
 *               Stat: "Sum",
 *             },
 *             ReturnData: true,
 *           },
 *         ],
 *       },
 *     },
 *   },
 *   goal: { AttainmentGoal: 99.9 },
 * });
 * ```
 *
 * @resource
 */
export const ServiceLevelObjective = Resource<ServiceLevelObjective>(
  "AWS.ApplicationSignals.ServiceLevelObjective",
);

/**
 * Rebuild `Date` instances that the engine's state serialization flattened
 * to ISO strings (calendar intervals carry a `StartTime` timestamp).
 */
const normalizeGoal = (goal: appsignals.Goal | undefined): appsignals.Goal | undefined => {
  const interval = goal?.Interval;
  if (interval && "CalendarInterval" in interval && interval.CalendarInterval) {
    return {
      ...goal,
      Interval: {
        CalendarInterval: {
          ...interval.CalendarInterval,
          StartTime: new Date(interval.CalendarInterval.StartTime),
        },
      },
    };
  }
  return goal;
};

const isPlainObject = (value: unknown): value is Record<string, unknown> =>
  typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);

const toTime = (value: unknown): number =>
  value instanceof Date ? value.getTime() : new Date(value as string | number).getTime();

/**
 * Structural subset comparison: every DEFINED field of `desired` must
 * deep-equal the corresponding field of `observed`. Extra observed fields
 * (server-side defaults the API echoes back, e.g. `ReturnData`, resolved
 * account ids) are ignored, so a reconcile whose desired state matches the
 * cloud skips the update call entirely.
 */
const subsetMatches = (desired: unknown, observed: unknown): boolean => {
  if (desired === undefined) return true;
  if (desired instanceof Date || observed instanceof Date) {
    return toTime(desired) === toTime(observed);
  }
  if (Array.isArray(desired)) {
    return (
      Array.isArray(observed) &&
      observed.length === desired.length &&
      desired.every((item, index) => subsetMatches(item, observed[index]))
    );
  }
  if (isPlainObject(desired)) {
    return (
      isPlainObject(observed) &&
      Object.entries(desired).every(([key, value]) => subsetMatches(value, observed[key]))
    );
  }
  return desired === observed;
};

/** The mutable aspects of the SLO, in `UpdateServiceLevelObjective` shape. */
const desiredState = (news: ServiceLevelObjectiveProps) => ({
  Description: news.description,
  SliConfig: news.sliConfig,
  RequestBasedSliConfig: news.requestBasedSliConfig,
  Goal: normalizeGoal(news.goal),
  BurnRateConfigurations: news.burnRateConfigurations,
});

/** Project the observed SLO into the same shape as {@link desiredState}. */
const observedState = (slo: appsignals.ServiceLevelObjective) => ({
  Description: slo.Description,
  SliConfig: slo.Sli && {
    SliMetricConfig: slo.Sli.SliMetric,
    MetricThreshold: slo.Sli.MetricThreshold,
    ComparisonOperator: slo.Sli.ComparisonOperator,
  },
  RequestBasedSliConfig: slo.RequestBasedSli && {
    RequestBasedSliMetricConfig: slo.RequestBasedSli.RequestBasedSliMetric,
    MetricThreshold: slo.RequestBasedSli.MetricThreshold,
    ComparisonOperator: slo.RequestBasedSli.ComparisonOperator,
  },
  Goal: slo.Goal,
  BurnRateConfigurations: slo.BurnRateConfigurations,
});

export const ServiceLevelObjectiveProvider = () =>
  Provider.effect(
    ServiceLevelObjective,
    Effect.gen(function* () {
      const createSloName = Effect.fn(function* (
        id: string,
        props: Pick<ServiceLevelObjectiveProps, "sloName">,
      ) {
        // SLO names are limited to 127 characters.
        return props.sloName ?? (yield* createPhysicalName({ id, maxLength: 127 }));
      });

      // `Id` accepts the SLO name or ARN interchangeably.
      const observeSlo = (id: string) =>
        appsignals.getServiceLevelObjective({ Id: id }).pipe(
          Effect.map((r) => r.Slo),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );

      const observedTags = (sloArn: string) =>
        appsignals.listTagsForResource({ ResourceArn: sloArn }).pipe(
          Effect.map((r) => Object.fromEntries((r.Tags ?? []).map((t) => [t.Key, t.Value]))),
          Effect.catchTag("ResourceNotFoundException", () =>
            Effect.succeed({} as Record<string, string>),
          ),
        );

      return ServiceLevelObjective.Provider.of({
        stables: ["sloName", "sloArn"],
        list: () =>
          Effect.gen(function* () {
            const summaries = yield* appsignals.listServiceLevelObjectives
              .items({})
              .pipe(Stream.runCollect);
            return Array.from(summaries).map((slo) => ({
              sloName: slo.Name,
              sloArn: slo.Arn,
              evaluationType: slo.EvaluationType,
            }));
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const sloName = output?.sloName ?? (yield* createSloName(id, olds ?? {}));
          const found = yield* observeSlo(sloName);
          if (!found) return undefined;
          const attrs = {
            sloName: found.Name,
            sloArn: found.Arn,
            evaluationType: found.EvaluationType,
          };
          const tags = yield* observedTags(found.Arn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createSloName(id, olds ?? {});
          const newName = yield* createSloName(id, news ?? {});
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
          // An SLO cannot switch between period-based and request-based
          // evaluation — swapping the SLI config kind replaces the SLO.
          const oldKind = olds?.requestBasedSliConfig ? "RequestBased" : "PeriodBased";
          const newKind = news?.requestBasedSliConfig ? "RequestBased" : "PeriodBased";
          if (oldKind !== newKind) {
            return { action: "replace" } as const;
          }
          // fall through: engine default update logic for mutable fields
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const sloName = output?.sloName ?? (yield* createSloName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };
          const desired = desiredState(news);

          // 1. OBSERVE — cloud state is authoritative; `output` is only a
          //    cache for the physical name.
          let live = yield* observeSlo(sloName);

          if (live === undefined) {
            // 2. ENSURE — create when missing; a concurrent create surfaces
            //    as the typed ConflictException, which we treat as a race
            //    and re-observe.
            live = yield* appsignals
              .createServiceLevelObjective({
                Name: sloName,
                ...desired,
                Tags: createTagsList(desiredTags),
              })
              .pipe(
                Effect.map((r) => r.Slo),
                Effect.catchTag("ConflictException", () => observeSlo(sloName)),
              );
          } else if (!subsetMatches(desired, observedState(live))) {
            // 3. SYNC — converge every mutable aspect with a single PATCH;
            //    skipped entirely when the observed state already satisfies
            //    the desired state (update retains omitted parameters).
            live = yield* appsignals
              .updateServiceLevelObjective({ Id: sloName, ...desired })
              .pipe(Effect.map((r) => r.Slo));
          }

          if (live === undefined) {
            return yield* new ServiceLevelObjectiveOperationFailed({
              message: `failed to reconcile SLO '${sloName}'`,
            });
          }

          // 3b. SYNC TAGS — diff against OBSERVED cloud tags so adoption
          //     converges (create-time Tags only apply on first create).
          const currentTags = yield* observedTags(live.Arn);
          const { upsert, removed } = diffTags(currentTags, desiredTags);
          if (upsert.length > 0) {
            yield* appsignals.tagResource({
              ResourceArn: live.Arn,
              Tags: upsert,
            });
          }
          if (removed.length > 0) {
            yield* appsignals.untagResource({
              ResourceArn: live.Arn,
              TagKeys: removed,
            });
          }

          yield* session.note(sloName);
          return {
            sloName: live.Name,
            sloArn: live.Arn,
            evaluationType: live.EvaluationType,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* appsignals.deleteServiceLevelObjective({ Id: output.sloName }).pipe(
            // Idempotent delete — already-gone is success.
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );
        }),
      });
    }),
  );