sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Observability/ TraceScope.ts

import * as observability from "@distilled.cloud/gcp/observability_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
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, hasAlchemyLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import {
  DEFAULT_TRACE_LOCATION,
  encodeDescription,
  expandResourceNames,
  hasOwnershipMarker,
  parseDescription,
  parseScopeName,
  sameStringList,
  scopeResourceName,
  toScopeId,
} from "./internal.ts";

export type TraceScopeProps = {
  /**
   * Trace scope id (the `{traceScope}` segment of
   * `projects/{project}/locations/{location}/traceScopes/{traceScope}`).
   * If omitted, a unique name is generated from the stack, stage, and
   * logical id. Limited to 100 characters: letters, digits, underscores,
   * hyphens, periods; first character must be alphanumeric. Immutable —
   * changing it replaces the scope. The system-managed `_Default` scope
   * cannot be deleted.
   */
  traceScopeId?: string;
  /**
   * Location. Trace scopes are only available in `global`. Immutable —
   * changing it replaces the scope.
   * @default "global"
   */
  location?: string;
  /**
   * Projects whose traces this scope queries together. Each entry is
   * `projects/{project}`. At most 20 projects. Bare project ids are
   * expanded. If omitted, the current project is used.
   */
  resourceNames?: string[];
  /**
   * Human-readable description (max 8000 characters). Trace scopes have
   * no labels field, so Alchemy ownership is stored in a `[alchemy …]`
   * prefix and stripped from attributes.
   */
  description?: string;
};

export type TraceScope = Resource<
  "GCP.Observability.TraceScope",
  TraceScopeProps,
  {
    /** Full resource name `projects/{project}/locations/{location}/traceScopes/{traceScopeId}`. */
    name: string;
    /** Trace scope id (last path segment). */
    traceScopeId: string;
    /** Project id. */
    project: string;
    /** Location (`global`). */
    location: string;
    /** Covered projects (`projects/{project}`). */
    resourceNames: string[];
    /** User description with the Alchemy ownership prefix stripped. */
    description: string | undefined;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Cloud Observability trace scope — a named collection of projects
 * whose traces are queried together in Trace Explorer.
 *
 * Trace scopes exist only in the `global` location. They have no labels
 * field, so Alchemy stamps ownership into the description for `list` /
 * nuke. `traceScopeId` and `location` are identity — changing either
 * replaces the scope. `resourceNames` and description update in place.
 * The system-managed `_Default` scope cannot be deleted.
 *
 * ### Creating a Trace Scope
 * **Example:** Generated name covering this project
 * ```typescript
 * const scope = yield* GCP.Observability.TraceScope("App", {
 *   resourceNames: ["projects/my-project"],
 *   description: "application traces",
 * });
 * ```
 *
 * **Example:** Named scope
 * ```typescript
 * const scope = yield* GCP.Observability.TraceScope("App", {
 *   traceScopeId: "app-traces",
 *   resourceNames: ["projects/my-project"],
 * });
 * ```
 *
 * ### Updating a Trace Scope
 * Change props on the same logical id; the engine keeps the physical id.
 *
 * **Example:** Change the description
 * ```typescript
 * const scope = yield* GCP.Observability.TraceScope("App", {
 *   resourceNames: ["projects/my-project"],
 *   description: "all application traces",
 * });
 * ```
 *
 * @resource
 * @category Observability
 */
export const TraceScope = Resource<TraceScope>("GCP.Observability.TraceScope");

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

const traceScopeIdOf = (scope: observability.TraceScope, fallback?: string) => {
  const parsed = parseScopeName(scope.name ?? "");
  return parsed?.traceScopeId ?? fallback ?? (scope.name ?? "").split("/").pop() ?? "";
};

const toAttrs = (scope: observability.TraceScope, project: string, location: string) => {
  const traceScopeId = traceScopeIdOf(scope);
  const parsed = parseDescription(scope.description);
  const parsedName = parseScopeName(scope.name ?? "");
  const resolvedLocation = parsedName?.location ?? location;
  const resolvedProject = parsedName?.project ?? project;
  return {
    name:
      scope.name ??
      (traceScopeId ? scopeResourceName(resolvedProject, resolvedLocation, traceScopeId) : ""),
    traceScopeId,
    project: resolvedProject,
    location: resolvedLocation,
    resourceNames: [...(scope.resourceNames ?? [])],
    description: parsed.description,
    createTime: scope.createTime,
    updateTime: scope.updateTime,
  };
};

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

export const TraceScopeProvider = () =>
  Provider.succeed(TraceScope, {
    stables: ["name", "traceScopeId", "project", "location", "createTime"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousId = olds?.traceScopeId ?? output?.traceScopeId;
      const idChanged =
        previousId !== undefined &&
        news.traceScopeId !== undefined &&
        news.traceScopeId !== previousId;
      const previousLocation = olds?.location ?? output?.location;
      const locationChanged =
        previousLocation !== undefined &&
        news.location !== undefined &&
        news.location !== previousLocation;
      if (!idChanged && !locationChanged) return undefined;
      return { action: "replace" as const, deleteFirst: false };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const location = olds?.location ?? output?.location ?? DEFAULT_TRACE_LOCATION;
      const traceScopeId = yield* toScopeId(id, olds?.traceScopeId, output?.traceScopeId);
      const name = output?.name ?? scopeResourceName(env.project, location, traceScopeId);
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project, location);
      const { labels } = parseDescription(existing.description);
      return (yield* hasAlchemyLabels(id, labels)) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        return yield* observability.listProjectsLocationsTraceScopes
          .pages({
            parent: `projects/${env.project}/locations/${DEFAULT_TRACE_LOCATION}`,
            pageSize: 1000,
          })
          .pipe(
            Stream.flatMap((page) => Stream.fromIterable(page.traceScopes ?? [])),
            Stream.filter((scope) => hasOwnershipMarker(scope.description)),
            Stream.map((scope) => toAttrs(scope, env.project, DEFAULT_TRACE_LOCATION)),
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk)),
            Effect.catchTag("NotFound", () => Effect.succeed([] as ReturnType<typeof toAttrs>[])),
          );
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const location = news.location ?? output?.location ?? DEFAULT_TRACE_LOCATION;
      const traceScopeId = yield* toScopeId(id, news.traceScopeId, output?.traceScopeId);
      const name = scopeResourceName(env.project, location, traceScopeId);
      const ownership = yield* createInternalLabels(id);
      const desiredDescription = encodeDescription(ownership, news.description);
      const desiredResources = expandResourceNames(news.resourceNames, env.project);

      let current = yield* getByName(output?.name ?? name);

      if (current === undefined) {
        const created = yield* observability
          .createProjectsLocationsTraceScopes({
            parent: `projects/${env.project}/locations/${location}`,
            traceScopeId,
            body: {
              resourceNames: desiredResources,
              description: desiredDescription,
            },
          })
          .pipe(Effect.catchTag("Conflict", () => getByName(name)));
        current = created ?? undefined;
      }

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

      const descriptionChanged = (current.description ?? "") !== desiredDescription;
      const resourcesChanged = !sameStringList(current.resourceNames, desiredResources);
      const updateMask = [
        descriptionChanged ? "description" : undefined,
        resourcesChanged ? "resourceNames" : undefined,
      ].filter((field): field is string => field !== undefined);

      if (updateMask.length > 0) {
        current = yield* observability.patchProjectsLocationsTraceScopes({
          name: current.name ?? name,
          updateMask: updateMask.join(","),
          body: {
            resourceNames: desiredResources,
            description: desiredDescription,
          },
        });
      }

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

    delete: Effect.fn(function* ({ output }) {
      if (output.traceScopeId === "_Default") return;
      yield* observability
        .deleteProjectsLocationsTraceScopes({ name: output.name })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
    }),
  });