sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Monitoring/ ServicesServiceLevelObjective.ts

import * as monitoring from "@distilled.cloud/gcp/monitoring_v3";
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 { tagRecord } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { GcpEnvironment } from "../Environment.ts";
import {
  createInternalLabels,
  diffLabels,
  hasAlchemyLabels,
  stripInternalLabels,
  toLabels,
} from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import { jsonEqual, lastSegment, parentOf, toEmptyObject } from "./ownership.ts";

const MAX_SLO_ID_LENGTH = 63;
const DEFAULT_ROLLING_PERIOD = "86400s";

export type LatencyCriteria = {
  /** Requests at or below this latency count as good. */
  threshold?: string;
};

export type BasicSli = {
  /** Locations this SLI applies to. Omitted means all. */
  location?: string[];
  /** Availability SLI (successful request count). */
  availability?: Record<string, never>;
  /** Latency SLI against `threshold`. */
  latency?: LatencyCriteria;
  /** RPC methods this SLI applies to. Omitted means all. */
  method?: string[];
  /** API versions this SLI applies to. Omitted means all. */
  version?: string[];
};

export type ValueRange = {
  /** Inclusive maximum. Omit (or use Infinity) for an open upper bound. */
  max?: number;
  /** Inclusive minimum. Omit (or use -Infinity) for an open lower bound. */
  min?: number;
};

export type MetricRange = {
  /** Range of values considered good. */
  range?: ValueRange;
  /** Monitoring filter selecting a GAUGE INT64 or DOUBLE time series. */
  timeSeries?: string;
};

export type DistributionCut = {
  /** Range of distribution bucket values considered good. */
  range?: ValueRange;
  /**
   * Monitoring filter selecting a DISTRIBUTION DELTA or CUMULATIVE
   * time series.
   */
  distributionFilter?: string;
};

export type TimeSeriesRatio = {
  /** Filter quantifying good service. */
  goodServiceFilter?: string;
  /** Filter quantifying bad service. */
  badServiceFilter?: string;
  /** Filter quantifying total demanded service. */
  totalServiceFilter?: string;
};

export type RequestBasedSli = {
  /** Good service is the count of distribution values in `range`. */
  distributionCut?: DistributionCut;
  /** Good / total ratio from a pair of time series. */
  goodTotalRatio?: TimeSeriesRatio;
};

export type PerformanceThreshold = {
  /** Window is good when performance is at least this fraction. */
  threshold?: number;
  /** Request-based SLI used to judge the window. */
  performance?: RequestBasedSli;
  /** Basic SLI used to judge the window. */
  basicSliPerformance?: BasicSli;
};

export type WindowsBasedSli = {
  /**
   * Window duration. Must be an integer fraction of a day and at least
   * 60s.
   */
  windowPeriod?: string;
  /** Window is good when the summed metric is in `range`. */
  metricSumInRange?: MetricRange;
  /** BOOL time series; the window is good if any true value appears. */
  goodBadMetricFilter?: string;
  /** Window is good when performance is above `threshold`. */
  goodTotalRatioThreshold?: PerformanceThreshold;
  /** Window is good when the mean metric is in `range`. */
  metricMeanInRange?: MetricRange;
};

export type ServiceLevelIndicator = {
  /** Basic SLI on a well-known service type. */
  basicSli?: BasicSli;
  /** Windows-based SLI. */
  windowsBased?: WindowsBasedSli;
  /** Request-based SLI. */
  requestBased?: RequestBasedSli;
};

export type CalendarPeriod = "DAY" | "WEEK" | "FORTNIGHT" | "MONTH" | (string & {});

export type ServicesServiceLevelObjectiveProps = {
  /**
   * Parent service resource name
   * (`projects/{project}/services/{service}`) or service id. Immutable
   * — changing it replaces the SLO.
   */
  service: string;
  /**
   * SLO id (the last path segment). If omitted, a unique id is
   * generated from the stack, stage, and logical id. Must match
   * `[a-zA-Z0-9-_:.]`. Immutable — changing it replaces the SLO.
   */
  serviceLevelObjectiveId?: string;
  /**
   * Human-readable display name. If omitted, the SLO id is used.
   */
  displayName?: string;
  /**
   * Fraction of service that must be good (`0 < goal <= 0.9999`).
   */
  goal: number;
  /**
   * Rolling window (for example `"86400s"`). Mutually exclusive with
   * `calendarPeriod`. Defaults to `"86400s"` when neither is set.
   */
  rollingPeriod?: string;
  /**
   * Calendar period (`DAY`, `WEEK`, `FORTNIGHT`, `MONTH`). Mutually
   * exclusive with `rollingPeriod`.
   */
  calendarPeriod?: CalendarPeriod;
  /**
   * Service-level indicator defining good service.
   */
  serviceLevelIndicator: ServiceLevelIndicator;
  /**
   * User labels. Alchemy ownership labels are merged in automatically.
   */
  labels?: Record<string, string>;
};

export type ServicesServiceLevelObjective = Resource<
  "GCP.Monitoring.ServicesServiceLevelObjective",
  ServicesServiceLevelObjectiveProps,
  {
    /** Full resource name `projects/{project}/services/{service}/serviceLevelObjectives/{slo}`. */
    name: string;
    /** SLO id (last path segment). */
    serviceLevelObjectiveId: string;
    /** Parent service resource name. */
    service: string;
    /** Parent service id. */
    serviceId: string;
    /** Project id. */
    project: string;
    /** Human-readable display name. */
    displayName: string | undefined;
    /** Target good-service fraction. */
    goal: number;
    /** Rolling window, if this SLO is rolling. */
    rollingPeriod: string | undefined;
    /** Calendar period, if this SLO is calendar-based. */
    calendarPeriod: string | undefined;
    /** Service-level indicator. */
    serviceLevelIndicator: ServiceLevelIndicator | undefined;
    /** User labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
  },
  never,
  Providers
>;

/**
 * A Cloud Monitoring service-level objective under a Monitoring
 * Service.
 *
 * Alchemy stamps ownership into `userLabels` so `list` /
 * `pnpm nuke:gcp` can find them. Changing `service` or
 * `serviceLevelObjectiveId` replaces the SLO. Goal, period, SLI,
 * display name, and labels update in place.
 *
 * ### Creating an SLO
 * **Example:** Rolling request-latency SLO on a custom service
 * ```typescript
 * const checkout = yield* GCP.Monitoring.Service("Checkout", {});
 * const slo = yield* GCP.Monitoring.ServicesServiceLevelObjective(
 *   "Latency",
 *   {
 *     service: checkout.name,
 *     goal: 0.99,
 *     rollingPeriod: "86400s",
 *     serviceLevelIndicator: {
 *       requestBased: {
 *         distributionCut: {
 *           distributionFilter:
 *             'metric.type="serviceruntime.googleapis.com/api/request_latencies" AND resource.type="consumed_api"',
 *           range: { max: 500 },
 *         },
 *       },
 *     },
 *   },
 * );
 * ```
 *
 * ### Updating an SLO
 * **Example:** Lower the goal and switch to a calendar month
 * ```typescript
 * const slo = yield* GCP.Monitoring.ServicesServiceLevelObjective(
 *   "Latency",
 *   {
 *     service: checkout.name,
 *     goal: 0.95,
 *     calendarPeriod: "MONTH",
 *     serviceLevelIndicator: {
 *       requestBased: {
 *         distributionCut: {
 *           distributionFilter:
 *             'metric.type="serviceruntime.googleapis.com/api/request_latencies" AND resource.type="consumed_api"',
 *           range: { max: 500 },
 *         },
 *       },
 *     },
 *   },
 * );
 * ```
 *
 * @resource
 * @category Monitoring
 */
export const ServicesServiceLevelObjective = Resource<ServicesServiceLevelObjective>(
  "GCP.Monitoring.ServicesServiceLevelObjective",
);

export class ServicesServiceLevelObjectiveNotResolved extends Data.TaggedError(
  "GCP.Monitoring.ServicesServiceLevelObjectiveNotResolved",
)<{
  resourceName: string;
}> {}

const SERVICES = "/services/";

const parseSloName = (name: string) => {
  const parts = name.split("/").filter((part) => part.length > 0);
  const projectsAt = parts.lastIndexOf("projects");
  const servicesAt = parts.lastIndexOf("services");
  const slosAt = parts.lastIndexOf("serviceLevelObjectives");
  const project = projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : "";
  const serviceId = servicesAt >= 0 && parts[servicesAt + 1] ? parts[servicesAt + 1]! : "";
  const service = servicesAt >= 0 ? parts.slice(0, servicesAt + 2).join("/") : "";
  const serviceLevelObjectiveId =
    slosAt >= 0 && parts[slosAt + 1] ? parts[slosAt + 1]! : lastSegment(name);
  return { project, service, serviceId, serviceLevelObjectiveId };
};

const resolveService = (project: string, service: string) => {
  if (service.includes("/")) return service;
  return `${parentOf(project)}/services/${service}`;
};

const resourceName = (service: string, sloId: string) =>
  `${service}/serviceLevelObjectives/${sloId}`;

const userFacingLabels = (
  labels: Record<string, string | undefined> | null | undefined,
): Record<string, string> => stripInternalLabels(tagRecord(labels));

const toId = (id: string, sloId: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (sloId !== undefined) return sloId;
    if (existing !== undefined) return existing;
    const generated = yield* createPhysicalName({
      id,
      maxLength: MAX_SLO_ID_LENGTH,
      lowercase: true,
    });
    return generated.replace(/-+$/g, "").slice(0, MAX_SLO_ID_LENGTH);
  });

const toBasicSli = (sli: monitoring.BasicSli | undefined): BasicSli | undefined => {
  if (sli === undefined) return undefined;
  return {
    location: sli.location,
    availability: toEmptyObject(sli.availability),
    latency: sli.latency,
    method: sli.method,
    version: sli.version,
  };
};

const toPerformanceThreshold = (
  value: monitoring.PerformanceThreshold | undefined,
): PerformanceThreshold | undefined => {
  if (value === undefined) return undefined;
  return {
    threshold: value.threshold,
    performance: value.performance,
    basicSliPerformance: toBasicSli(value.basicSliPerformance),
  };
};

const toWindowsBasedSli = (
  sli: monitoring.WindowsBasedSli | undefined,
): WindowsBasedSli | undefined => {
  if (sli === undefined) return undefined;
  return {
    windowPeriod: sli.windowPeriod,
    metricSumInRange: sli.metricSumInRange,
    goodBadMetricFilter: sli.goodBadMetricFilter,
    goodTotalRatioThreshold: toPerformanceThreshold(sli.goodTotalRatioThreshold),
    metricMeanInRange: sli.metricMeanInRange,
  };
};

const toSli = (
  sli: monitoring.ServiceLevelIndicator | undefined,
): ServiceLevelIndicator | undefined => {
  if (sli === undefined) return undefined;
  return {
    basicSli: toBasicSli(sli.basicSli),
    windowsBased: toWindowsBasedSli(sli.windowsBased),
    requestBased: sli.requestBased,
  };
};

const toAttrs = (slo: monitoring.ServiceLevelObjective, project: string) => {
  const name = slo.name ?? "";
  const parsed = parseSloName(name);
  return {
    name,
    serviceLevelObjectiveId: parsed.serviceLevelObjectiveId,
    service: parsed.service,
    serviceId: parsed.serviceId,
    project: parsed.project || project,
    displayName: slo.displayName,
    goal: slo.goal ?? 0,
    rollingPeriod: slo.rollingPeriod,
    calendarPeriod: slo.calendarPeriod,
    serviceLevelIndicator: toSli(slo.serviceLevelIndicator),
    labels: userFacingLabels(slo.userLabels),
  };
};

const periodBody = (
  news: ServicesServiceLevelObjectiveProps,
): Pick<monitoring.ServiceLevelObjective, "rollingPeriod" | "calendarPeriod"> =>
  news.calendarPeriod !== undefined
    ? { calendarPeriod: news.calendarPeriod }
    : { rollingPeriod: news.rollingPeriod ?? DEFAULT_ROLLING_PERIOD };

const toBody = (
  news: ServicesServiceLevelObjectiveProps,
  displayName: string,
  desiredLabels: Record<string, string>,
): monitoring.ServiceLevelObjective => ({
  displayName,
  goal: news.goal,
  ...periodBody(news),
  serviceLevelIndicator: news.serviceLevelIndicator as monitoring.ServiceLevelIndicator | undefined,
  userLabels: desiredLabels,
});

const getByName = (name: string) =>
  monitoring
    .getServicesServiceLevelObjectives({ name })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const listSlos = (parent: string) =>
  monitoring.listServicesServiceLevelObjectives
    .pages({
      parent,
      pageSize: 1000,
    })
    .pipe(
      Stream.flatMap((page) => Stream.fromIterable(page.serviceLevelObjectives ?? [])),
      Stream.runCollect,
      Effect.map((chunk) => Array.from(chunk)),
      Effect.catchTag("NotFound", () => Effect.succeed([] as monitoring.ServiceLevelObjective[])),
    );

const listServices = (project: string) =>
  monitoring.listServices
    .pages({
      parent: parentOf(project),
      pageSize: 1000,
    })
    .pipe(
      Stream.flatMap((page) => Stream.fromIterable(page.services ?? [])),
      Stream.runCollect,
      Effect.map((chunk) => Array.from(chunk)),
      Effect.catchTag("NotFound", () => Effect.succeed([])),
    );

const listOwned = (project: string) =>
  Effect.gen(function* () {
    const services = yield* monitoring.listServices
      .pages({
        parent: parentOf(project),
        pageSize: 1000,
        filter: 'identifier_case = "CUSTOM"',
      })
      .pipe(
        Stream.flatMap((page) => Stream.fromIterable(page.services ?? [])),
        Stream.runCollect,
        Effect.map((chunk) => Array.from(chunk)),
        Effect.catchTag("NotFound", () => Effect.succeed([])),
      );
    const nested = yield* Effect.forEach(
      services,
      (service) =>
        service.name !== undefined
          ? listSlos(service.name)
          : Effect.succeed([] as monitoring.ServiceLevelObjective[]),
      { concurrency: 5 },
    );
    return nested
      .flat()
      .filter((slo) => Object.keys(slo.userLabels ?? {}).some((key) => key.startsWith("alchemy-")))
      .map((slo) => toAttrs(slo, project));
  });

const findOwned = (project: string, id: string, service: string | undefined) =>
  Effect.gen(function* () {
    const parents =
      service !== undefined
        ? [service]
        : (yield* listServices(project)).flatMap((item) =>
            item.name !== undefined ? [item.name] : [],
          );
    for (const parent of parents) {
      const slos = yield* listSlos(parent);
      for (const slo of slos) {
        if (yield* hasAlchemyLabels(id, tagRecord(slo.userLabels))) {
          return slo;
        }
      }
    }
    return undefined;
  });

const observe = (
  project: string,
  id: string,
  name: string | undefined,
  service: string | undefined,
) =>
  Effect.gen(function* () {
    if (name !== undefined) {
      const existing = yield* getByName(name);
      if (existing !== undefined) return existing;
    }
    return yield* findOwned(project, id, service);
  });

export const ServicesServiceLevelObjectiveProvider = () =>
  Provider.succeed(ServicesServiceLevelObjective, {
    stables: ["name", "serviceLevelObjectiveId", "service", "serviceId", "project"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousId = olds?.serviceLevelObjectiveId ?? output?.serviceLevelObjectiveId;
      const idChanged =
        news.serviceLevelObjectiveId !== undefined &&
        previousId !== undefined &&
        news.serviceLevelObjectiveId !== previousId;
      const previousService = olds?.service ?? output?.service;
      const nextService = news.service;
      const serviceChanged =
        previousService !== undefined &&
        nextService !== previousService &&
        !previousService.endsWith(`/${nextService}`) &&
        !nextService.endsWith(`/${previousService.split(SERVICES).pop() ?? ""}`);
      if (!idChanged && !serviceChanged) return undefined;
      return {
        action: "replace" as const,
        deleteFirst: !idChanged,
      };
    }),

    read: Effect.fn(function* ({ id, output }) {
      const env = yield* GcpEnvironment.current;
      const existing = yield* observe(env.project, id, output?.name, output?.service);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      return (yield* hasAlchemyLabels(id, tagRecord(existing.userLabels))) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        return yield* listOwned(env.project);
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const service = resolveService(env.project, news.service);
      const sloId = yield* toId(id, news.serviceLevelObjectiveId, output?.serviceLevelObjectiveId);
      const name = resourceName(service, sloId);
      const displayName = news.displayName ?? sloId;
      const desiredLabels = {
        ...toLabels(news.labels),
        ...(yield* createInternalLabels(id)),
      };
      const desiredPeriod = periodBody(news);

      let current = yield* observe(env.project, id, output?.name ?? name, service);

      const body = toBody(news, displayName, desiredLabels);

      if (current === undefined) {
        const created = yield* monitoring
          .createServicesServiceLevelObjectives({
            parent: service,
            serviceLevelObjectiveId: sloId,
            body,
          })
          .pipe(
            Effect.catchTag("Conflict", () =>
              getByName(name).pipe(
                Effect.flatMap((existing) =>
                  existing !== undefined
                    ? Effect.succeed(existing)
                    : findOwned(env.project, id, service),
                ),
              ),
            ),
          );
        current = created ?? undefined;
      }

      if (current === undefined) {
        return yield* new ServicesServiceLevelObjectiveNotResolved({ resourceName: name });
      }

      const resource = current.name ?? name;
      const observedLabels = tagRecord(current.userLabels);
      const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
      const labelsChanged = upsert.length > 0 || removed.length > 0;
      const displayNameChanged = (current.displayName ?? "") !== displayName;
      const goalChanged = (current.goal ?? 0) !== news.goal;
      const rollingChanged = (current.rollingPeriod ?? "") !== (desiredPeriod.rollingPeriod ?? "");
      const calendarChanged =
        (current.calendarPeriod ?? "") !== (desiredPeriod.calendarPeriod ?? "");
      const sliChanged = !jsonEqual(
        toSli(current.serviceLevelIndicator) ?? null,
        news.serviceLevelIndicator,
      );

      const updateMask = [
        displayNameChanged ? "display_name" : undefined,
        labelsChanged ? "user_labels" : undefined,
        goalChanged ? "goal" : undefined,
        rollingChanged ? "rolling_period" : undefined,
        calendarChanged ? "calendar_period" : undefined,
        sliChanged ? "service_level_indicator" : undefined,
      ].filter((field): field is string => field !== undefined);

      if (updateMask.length > 0) {
        current = yield* monitoring.patchServicesServiceLevelObjectives({
          name: resource,
          updateMask: updateMask.join(","),
          body: {
            ...body,
            name: resource,
          },
        });
      }

      return toAttrs(current, env.project);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* monitoring
        .deleteServicesServiceLevelObjectives({ name: output.name })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),
  });