sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ NetworkServices/ GrpcRoute.ts

import * as networkservices from "@distilled.cloud/gcp/networkservices_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { tagRecord } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { GcpEnvironment } from "../Environment.ts";
import { createInternalLabels, diffLabels, hasAlchemyLabels, toLabels } from "../Labels.ts";
import type { Providers } from "../Providers.ts";
import {
  DEFAULT_GLOBAL,
  changedFields,
  collectPages,
  hasAlchemyLabelKeys,
  normalizeLocation,
  parentOf,
  parseName,
  resourceName,
  rfc1035,
  sameJson,
  sameStringList,
  toPhysicalId,
  userLabels,
  waitForOperation,
  waitUntilGone,
  waitUntilPresent,
} from "./internal.ts";

const COLLECTION = "grpcRoutes";

export type GrpcRouteMethodMatch = {
  /** How to match the method name. Defaults to `EXACT`. */
  type?: string;
  /** gRPC service name. Omitted matches every service. */
  grpcService?: string;
  /** gRPC method name. Omitted matches every method. */
  grpcMethod?: string;
  /**
   * Case-sensitive matching. Defaults to true. Must not be set with
   * `REGULAR_EXPRESSION`.
   */
  caseSensitive?: boolean;
};

export type GrpcRouteHeaderMatch = {
  /** How to match the header value. Defaults to `EXACT`. */
  type?: string;
  /** Header key. */
  key?: string;
  /** Header value. */
  value?: string;
};

export type GrpcRouteRouteMatch = {
  /** gRPC method matcher. Omitted matches every method. */
  method?: GrpcRouteMethodMatch;
  /** Header matchers. */
  headers?: GrpcRouteHeaderMatch[];
};

export type GrpcRouteDestination = {
  /** BackendService or Service Directory service URL. */
  serviceName?: string;
  /** Traffic weight relative to other destinations. */
  weight?: number;
};

export type GrpcRouteFaultInjectionDelay = {
  /** Fixed delay before forwarding (duration string). */
  fixedDelay?: string;
  /** Percentage of traffic delayed, 0-100. */
  percentage?: number;
};

export type GrpcRouteFaultInjectionAbort = {
  /** HTTP status used to abort, 200-599. */
  httpStatus?: number;
  /** Percentage of traffic aborted, 0-100. */
  percentage?: number;
};

export type GrpcRouteFaultInjectionPolicy = {
  /** Delay injection. */
  delay?: GrpcRouteFaultInjectionDelay;
  /** Abort injection. */
  abort?: GrpcRouteFaultInjectionAbort;
};

export type GrpcRouteRetryPolicy = {
  /**
   * Conditions that trigger a retry (`connect-failure`, `unavailable`,
   * `cancelled`, …).
   */
  retryConditions?: string[];
  /** Allowed retry count. Defaults to 1. */
  numRetries?: number;
};

export type GrpcRouteStatefulSessionAffinityPolicy = {
  /** Cookie TTL for the `GSSA` session cookie (`0s` is a session cookie). */
  cookieTtl?: string;
};

export type GrpcRouteRouteAction = {
  /** Destinations that receive matched traffic. */
  destinations?: GrpcRouteDestination[];
  /** Fault injection. */
  faultInjectionPolicy?: GrpcRouteFaultInjectionPolicy;
  /** End-to-end timeout including retries. */
  timeout?: string;
  /** Retry policy. */
  retryPolicy?: GrpcRouteRetryPolicy;
  /** Cookie-based session affinity. */
  statefulSessionAffinity?: GrpcRouteStatefulSessionAffinityPolicy;
  /** Idle timeout. `0s` disables it. */
  idleTimeout?: string;
};

export type GrpcRouteRouteRule = {
  /**
   * Matchers. The rule matches if any matcher matches. Omitted matches
   * every request.
   */
  matches?: GrpcRouteRouteMatch[];
  /** How to route matched traffic. */
  action?: GrpcRouteRouteAction;
};

export type GrpcRouteProps = {
  /**
   * GrpcRoute id (the `{grpcRoute}` segment of
   * `projects/{project}/locations/{location}/grpcRoutes/{grpcRoute}`).
   * If omitted, a unique name is generated from the stack, stage, and
   * logical id. Must be 1-63 characters and not start with a number.
   * Immutable — changing it replaces the route.
   */
  grpcRouteId?: string;
  /**
   * Location (`global`, `us-central1`, …). Immutable — changing it
   * replaces the route. `US-CENTRAL1` is accepted and normalized to
   * `us-central1`.
   * @default "global"
   */
  location?: string;
  /**
   * Service hostnames (with optional port) this route matches, e.g.
   * `foo.example.com` or `*.example.com`.
   */
  hostnames: string[];
  /**
   * Routing rules. The first matching rule is executed. At least one
   * rule is required.
   */
  rules: GrpcRouteRouteRule[];
  /**
   * Mesh resource names this route attaches to
   * (`projects/{project}/locations/{location}/meshes/{mesh}`).
   */
  meshes?: string[];
  /**
   * Gateway resource names this route attaches to
   * (`projects/{project}/locations/{location}/gateways/{gateway}`).
   */
  gateways?: string[];
  /**
   * Human-readable description. Max length 1024 characters.
   */
  description?: string;
  /**
   * User labels. Alchemy ownership labels are merged in automatically.
   */
  labels?: Record<string, string>;
};

export type GrpcRoute = Resource<
  "GCP.NetworkServices.GrpcRoute",
  GrpcRouteProps,
  {
    /** Full resource name `projects/{project}/locations/{location}/grpcRoutes/{grpcRoute}`. */
    name: string;
    /** GrpcRoute id (last path segment). */
    grpcRouteId: string;
    /** Project id. */
    project: string;
    /** Location id (`global`, `us-central1`, …). */
    location: string;
    /** Server-defined resource URL. */
    selfLink: string | undefined;
    /** Hostnames this route matches. */
    hostnames: string[];
    /** Routing rules. */
    rules: GrpcRouteRouteRule[];
    /** Attached Mesh resource names. */
    meshes: string[];
    /** Attached Gateway resource names. */
    gateways: string[];
    /** User-provided description. */
    description: string | undefined;
    /** User labels (Alchemy ownership labels stripped). */
    labels: Record<string, string>;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Network Services GrpcRoute — how a Mesh or Gateway routes gRPC
 * traffic for a set of hostnames.
 *
 * Changing `grpcRouteId` or `location` replaces the route. Hostnames,
 * rules, mesh/gateway attachments, description, and labels update in
 * place.
 *
 * ### Creating a GrpcRoute
 * **Example:** Hostname with a retry policy
 * ```typescript
 * const route = yield* GCP.NetworkServices.GrpcRoute("Api", {
 *   hostnames: ["api.example.com"],
 *   rules: [
 *     {
 *       action: {
 *         retryPolicy: { retryConditions: ["unavailable"], numRetries: 2 },
 *       },
 *     },
 *   ],
 * });
 * ```
 *
 * **Example:** Attach to a gateway
 * ```typescript
 * const route = yield* GCP.NetworkServices.GrpcRoute("Api", {
 *   grpcRouteId: "app-grpc",
 *   hostnames: ["api.example.com"],
 *   gateways: [gateway.name],
 *   labels: { env: "prod" },
 *   rules: [
 *     {
 *       matches: [{ method: { grpcService: "api.v1.Orders", grpcMethod: "Get" } }],
 *       action: { destinations: [{ serviceName: backend.selfLink }] },
 *     },
 *   ],
 * });
 * ```
 *
 * @resource
 * @category NetworkServices
 */
export const GrpcRoute = Resource<GrpcRoute>("GCP.NetworkServices.GrpcRoute");

const toMethod = (
  value: GrpcRouteMethodMatch | networkservices.GrpcRouteMethodMatch | undefined,
): GrpcRouteMethodMatch | undefined => {
  if (value === undefined) return undefined;
  return {
    type: value.type,
    grpcService: value.grpcService,
    grpcMethod: value.grpcMethod,
    caseSensitive: value.caseSensitive,
  };
};

const toHeader = (
  value: GrpcRouteHeaderMatch | networkservices.GrpcRouteHeaderMatch,
): GrpcRouteHeaderMatch => ({
  type: value.type,
  key: value.key,
  value: value.value,
});

const toMatch = (
  value: GrpcRouteRouteMatch | networkservices.GrpcRouteRouteMatch,
): GrpcRouteRouteMatch => ({
  method: toMethod(value.method),
  headers: (value.headers ?? []).map(toHeader),
});

const toDestination = (
  value: GrpcRouteDestination | networkservices.GrpcRouteDestination,
): GrpcRouteDestination => ({
  serviceName: value.serviceName,
  weight: value.weight,
});

const toFault = (
  value: GrpcRouteFaultInjectionPolicy | networkservices.GrpcRouteFaultInjectionPolicy | undefined,
): GrpcRouteFaultInjectionPolicy | undefined => {
  if (value === undefined) return undefined;
  return {
    delay: value.delay
      ? {
          fixedDelay: value.delay.fixedDelay,
          percentage: value.delay.percentage,
        }
      : undefined,
    abort: value.abort
      ? {
          httpStatus: value.abort.httpStatus,
          percentage: value.abort.percentage,
        }
      : undefined,
  };
};

const toRetry = (
  value: GrpcRouteRetryPolicy | networkservices.GrpcRouteRetryPolicy | undefined,
): GrpcRouteRetryPolicy | undefined => {
  if (value === undefined) return undefined;
  return {
    retryConditions: value.retryConditions ?? [],
    numRetries: value.numRetries,
  };
};

const toAffinity = (
  value:
    | GrpcRouteStatefulSessionAffinityPolicy
    | networkservices.GrpcRouteStatefulSessionAffinityPolicy
    | undefined,
): GrpcRouteStatefulSessionAffinityPolicy | undefined => {
  if (value === undefined) return undefined;
  return { cookieTtl: value.cookieTtl };
};

const toAction = (
  value: GrpcRouteRouteAction | networkservices.GrpcRouteRouteAction | undefined,
): GrpcRouteRouteAction | undefined => {
  if (value === undefined) return undefined;
  return {
    destinations: (value.destinations ?? []).map(toDestination),
    faultInjectionPolicy: toFault(value.faultInjectionPolicy),
    timeout: value.timeout,
    retryPolicy: toRetry(value.retryPolicy),
    statefulSessionAffinity: toAffinity(value.statefulSessionAffinity),
    idleTimeout: value.idleTimeout,
  };
};

const toRule = (
  value: GrpcRouteRouteRule | networkservices.GrpcRouteRouteRule,
): GrpcRouteRouteRule => ({
  matches: (value.matches ?? []).map(toMatch),
  action: toAction(value.action),
});

const toAttrs = (route: networkservices.GrpcRoute, project: string) => {
  const name = route.name ?? "";
  const parsed = parseName(name, COLLECTION, DEFAULT_GLOBAL);
  return {
    name,
    grpcRouteId: parsed.id,
    project: parsed.project || project,
    location: parsed.location || DEFAULT_GLOBAL,
    selfLink: route.selfLink,
    hostnames: route.hostnames ?? [],
    rules: (route.rules ?? []).map(toRule),
    meshes: route.meshes ?? [],
    gateways: route.gateways ?? [],
    description: route.description,
    labels: userLabels(route.labels),
    createTime: route.createTime,
    updateTime: route.updateTime,
  };
};

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

export const GrpcRouteProvider = () =>
  Provider.succeed(GrpcRoute, {
    stables: ["name", "grpcRouteId", "project", "location", "selfLink", "createTime"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousId = olds?.grpcRouteId ?? output?.grpcRouteId;
      const nextId = news.grpcRouteId ? rfc1035(news.grpcRouteId, "grpc-route") : previousId;
      const previousLocation = normalizeLocation(
        olds?.location ?? output?.location,
        DEFAULT_GLOBAL,
      );
      const nextLocation = normalizeLocation(
        news.location ?? olds?.location ?? output?.location,
        DEFAULT_GLOBAL,
      );
      if (
        (previousId !== undefined && nextId !== undefined && nextId !== previousId) ||
        previousLocation !== nextLocation
      ) {
        return { action: "replace" as const };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const grpcRouteId = yield* toPhysicalId(
        id,
        olds?.grpcRouteId,
        output?.grpcRouteId,
        "grpc-route",
      );
      const location = normalizeLocation(olds?.location ?? output?.location, DEFAULT_GLOBAL);
      const name = output?.name ?? resourceName(env.project, location, COLLECTION, grpcRouteId);
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const items = yield* collectPages(
          networkservices.listProjectsLocationsGrpcRoutes.pages({
            parent: parentOf(env.project, "-"),
            pageSize: 1000,
            returnPartialSuccess: true,
          }),
          (page) => page.grpcRoutes,
        );
        return items
          .filter((item) => hasAlchemyLabelKeys(item.labels))
          .map((item) => toAttrs(item, env.project));
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const grpcRouteId = yield* toPhysicalId(
        id,
        news.grpcRouteId,
        output?.grpcRouteId,
        "grpc-route",
      );
      const location = normalizeLocation(news.location ?? output?.location, DEFAULT_GLOBAL);
      const name = resourceName(env.project, location, COLLECTION, grpcRouteId);
      const desiredLabels = {
        ...toLabels(news.labels),
        ...(yield* createInternalLabels(id)),
      };
      const desiredRules = news.rules.map(toRule);
      const desiredHostnames = news.hostnames;
      const desiredMeshes = news.meshes ?? [];
      const desiredGateways = news.gateways ?? [];

      let current = yield* getByName(name);

      if (current === undefined) {
        const created = yield* networkservices
          .createProjectsLocationsGrpcRoutes({
            parent: parentOf(env.project, location),
            grpcRouteId,
            body: {
              labels: desiredLabels,
              description: news.description,
              hostnames: desiredHostnames,
              rules: desiredRules,
              meshes: desiredMeshes,
              gateways: desiredGateways,
            },
          })
          .pipe(
            Effect.retry({
              while: (error) => error._tag === "Conflict",
              times: 5,
              schedule: Schedule.spaced("2 seconds"),
            }),
            Effect.catchTag("Conflict", () => Effect.undefined),
          );
        if (created !== undefined) {
          yield* waitForOperation(created);
        }
        current = yield* waitUntilPresent(getByName(name), name);
      }

      const observedLabels = tagRecord(current.labels);
      const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
      const labelsChanged = upsert.length > 0 || removed.length > 0;
      const descriptionChanged = (current.description ?? "") !== (news.description ?? "");
      const hostnamesChanged = !sameStringList(current.hostnames, desiredHostnames);
      const rulesChanged = !sameJson((current.rules ?? []).map(toRule), desiredRules);
      const meshesChanged = !sameStringList(current.meshes, desiredMeshes);
      const gatewaysChanged = !sameStringList(current.gateways, desiredGateways);

      const updateMask = changedFields([
        ["labels", labelsChanged],
        ["description", descriptionChanged],
        ["hostnames", hostnamesChanged],
        ["rules", rulesChanged],
        ["meshes", meshesChanged],
        ["gateways", gatewaysChanged],
      ]);

      if (updateMask.length > 0) {
        const operation = yield* networkservices.patchProjectsLocationsGrpcRoutes({
          name: current.name ?? name,
          updateMask: updateMask.join(","),
          body: {
            name: current.name ?? name,
            labels: desiredLabels,
            description: news.description,
            hostnames: desiredHostnames,
            rules: desiredRules,
            meshes: desiredMeshes,
            gateways: desiredGateways,
          },
        });
        yield* waitForOperation(operation);
        current = yield* waitUntilPresent(getByName(current.name ?? name), current.name ?? name);
      }

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

    delete: Effect.fn(function* ({ output }) {
      const operation = yield* networkservices
        .deleteProjectsLocationsGrpcRoutes({ name: output.name })
        .pipe(
          Effect.retry({
            while: (error) => error._tag === "Conflict",
            times: 8,
            schedule: Schedule.spaced("2 seconds"),
          }),
          Effect.catchTag("NotFound", () => Effect.undefined),
        );
      if (operation !== undefined) {
        yield* waitForOperation(operation, { notFoundOk: true });
      }
      yield* waitUntilGone(getByName(output.name), output.name);
    }),
  });