sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ObservabilityAdmin/ TelemetryConfig.ts

import type { Credentials } from "@distilled.cloud/aws/Credentials";
import * as obs from "@distilled.cloud/aws/observabilityadmin";
import type { Region } from "@distilled.cloud/aws/Region";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import type * as HttpClient from "effect/http/HttpClient";
import * as Schedule from "effect/Schedule";
import type { Providers } from "../Providers.ts";

export interface TelemetryConfigProps {
  /**
   * Whether the CloudWatch telemetry config feature (telemetry evaluation)
   * is onboarded for this account. Set `false` to keep the resource in the
   * stack while the feature is off.
   * @default true
   */
  enabled?: boolean;
}

export interface TelemetryConfig extends Resource<
  "AWS.ObservabilityAdmin.TelemetryConfig",
  TelemetryConfigProps,
  {
    /**
     * The onboarding status of the telemetry config feature after
     * reconciliation (`RUNNING` or `STOPPED`).
     */
    status: string;
    /**
     * The status observed before this stack first managed the feature
     * (`NOT_STARTED`, `RUNNING`, `STOPPED`, ...). Destroy restores this —
     * a feature that was already running when the stack adopted it is left
     * running.
     */
    priorStatus: string;
  },
  never,
  Providers
> {}

/**
 * Account-level CloudWatch **telemetry config** (Observability Admin
 * telemetry evaluation) — an account singleton that audits which AWS
 * resources (VPCs, Lambda functions, ...) have telemetry such as flow
 * logs enabled.
 *
 * This is an always-present account *setting*, not a discrete resource:
 * deploying it onboards the account, and destroying it restores whatever
 * onboarding state the account had before the stack first managed it.
 *
 * ### Managing telemetry config
 * **Example:** Onboard the account
 * ```typescript
 * import * as ObservabilityAdmin from "@alchemy.run/aws/ObservabilityAdmin";
 *
 * const telemetry = yield* ObservabilityAdmin.TelemetryConfig("Telemetry");
 * ```
 *
 * **Example:** Keep the resource but switch the feature off
 * ```typescript
 * const telemetry = yield* ObservabilityAdmin.TelemetryConfig("Telemetry", {
 *   enabled: false,
 * });
 * ```
 *
 * @resource
 */
export const TelemetryConfig = Resource<TelemetryConfig>("AWS.ObservabilityAdmin.TelemetryConfig");

/**
 * Raised when the telemetry config feature reports `FAILED_START` /
 * `FAILED_STOP`, or fails to converge within the bounded wait.
 */
export class TelemetryConfigTransitionFailed extends Data.TaggedError(
  "TelemetryConfigTransitionFailed",
)<{ message: string; status: string }> {}

type ObsRequirements = Credentials | Region | HttpClient.HttpClient;

const readStatus: Effect.Effect<string, obs.GetTelemetryEvaluationStatusError, ObsRequirements> =
  obs.getTelemetryEvaluationStatus({}).pipe(Effect.map((r) => r.Status ?? "NOT_STARTED"));

const ON_STATES = ["RUNNING", "STARTING"];

/**
 * Poll the evaluation status on a bounded schedule until it reaches a
 * settled state (start/stop completed in ~1s in probing; the bound is
 * defensive). Explicitly typed at module scope so the conditional types of
 * `Effect.repeat` never leak into the provider layer's declaration emit.
 */
const awaitSettledStatus: Effect.Effect<
  string,
  obs.GetTelemetryEvaluationStatusError,
  ObsRequirements
> = readStatus.pipe(
  Effect.repeat({
    schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
    until: (status) => status !== "STARTING" && status !== "STOPPING",
  }),
);

const failIfUnsettled = (status: string, transition: "start" | "stop") =>
  status === "STARTING" || status === "STOPPING" || status.startsWith("FAILED")
    ? Effect.fail(
        new TelemetryConfigTransitionFailed({
          message: `telemetry evaluation did not settle after ${transition} (status: ${status})`,
          status,
        }),
      )
    : Effect.succeed(status);

/**
 * One idempotent convergence step shared by reconcile and delete-restore:
 * observe the live status and start/stop only on an actual delta.
 */
const convergeTo = Effect.fn(function* (desiredOn: boolean) {
  const observed = yield* awaitSettledStatus;
  const isOn = ON_STATES.includes(observed);
  if (desiredOn && !isOn) {
    yield* obs.startTelemetryEvaluation({});
    return yield* failIfUnsettled(yield* awaitSettledStatus, "start");
  }
  if (!desiredOn && isOn) {
    yield* obs.stopTelemetryEvaluation({});
    return yield* failIfUnsettled(yield* awaitSettledStatus, "stop");
  }
  return observed;
});

export const TelemetryConfigProvider = () =>
  Provider.effect(
    TelemetryConfig,
    Effect.gen(function* () {
      return TelemetryConfig.Provider.of({
        // Account singleton setting — deleting only restores the prior
        // onboarding state; nuke must not toggle it.
        nuke: { singleton: true },
        stables: ["priorStatus"],
        // No enumeration API — the singleton is always present as account
        // configuration, never a discrete listable resource.
        list: () => Effect.succeed([]),
        read: Effect.fn(function* ({ output }) {
          const status = yield* readStatus;
          return {
            status,
            priorStatus: output?.priorStatus ?? status,
          };
        }),
        reconcile: Effect.fn(function* ({ news, output, session }) {
          // Capture the pre-management status exactly once so destroy can
          // restore it; on later updates the persisted capture wins.
          const priorStatus = output?.priorStatus ?? (yield* readStatus);
          const desiredOn = news.enabled !== false;
          const status = yield* convergeTo(desiredOn);
          yield* session.note(`telemetry evaluation ${status}`);
          return { status, priorStatus };
        }),
        delete: Effect.fn(function* ({ output, session }) {
          // Restore the captured pre-management state instead of blindly
          // stopping: an account that was already onboarded before this
          // stack managed it stays onboarded.
          const priorOn = ON_STATES.includes(output.priorStatus);
          const status = yield* convergeTo(priorOn);
          yield* session.note(`telemetry evaluation restored to ${status}`);
        }),
      });
    }),
  );