sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ SasPortal/ NodesDevice.ts

import * as sasportal from "@distilled.cloud/gcp/sasportal_v1alpha1";
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 { GcpEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import {
  deviceBody,
  deviceConfigOf,
  deviceGrantsOf,
  deviceMetadataOf,
  encodeOwnershipLine,
  expandNode,
  findOwnedNodeDevice,
  frequencyRangesOf,
  getNodeDevice,
  hasOwnershipMarker,
  lastSegment,
  listNodeDevices,
  MAX_DISPLAY_NAME_LENGTH,
  ownedByAlchemy,
  ownershipLabels,
  parentOf,
  parseOwnership,
  replaceOnIdentity,
  retryDelete,
  sameJson,
  sameText,
  scanOwnedNodeDevice,
  toDisplayName,
  toSerialNumber,
  updateMaskOf,
  waitUntilGone,
  walkNodes,
  type DeviceConfig,
  type DeviceGrant,
  type DeviceMetadata,
  type FrequencyRange,
} from "./internal.ts";

export type NodesDeviceProps = {
  /**
   * Parent SAS node, as `nodes/{node}` or
   * `customers/{customer}/nodes/{node}`. Immutable — changing it
   * replaces the device.
   */
  parent: string;
  /**
   * Server-assigned device resource name. Immutable — changing it
   * replaces the device.
   */
  name?: string;
  /**
   * Display name. SAS Portal devices have no labels field, so Alchemy
   * stamps ownership into a `[alchemy …]` prefix and strips it from
   * attributes.
   */
  displayName?: string;
  /**
   * Manufacturer serial number. Immutable — changing it replaces the
   * device.
   */
  serialNumber?: string;
  /**
   * FCC identifier of the CBSD. Immutable — changing it replaces the
   * device.
   */
  fccId?: string;
  /**
   * Frequency ranges available for new grants.
   */
  grantRangeAllowlists?: FrequencyRange[];
  /**
   * Device configuration supplied through the SAS Portal API.
   */
  preloadedConfig?: DeviceConfig;
  /**
   * Overridable device metadata (ICG, CCG, antenna model).
   */
  deviceMetadata?: DeviceMetadata;
};

export type NodesDevice = Resource<
  "GCP.SasPortal.NodesDevice",
  NodesDeviceProps,
  {
    /** Resource name of the device. */
    name: string;
    /** Device id (last path segment). */
    deviceId: string;
    /** Parent node resource name. */
    parent: string;
    /** Project id used when the device was reconciled. */
    project: string;
    /** User-facing display name with the Alchemy prefix stripped. */
    displayName: string | undefined;
    /** Manufacturer serial number. */
    serialNumber: string | undefined;
    /** FCC identifier. */
    fccId: string | undefined;
    /** Grant-range allowlists. */
    grantRangeAllowlists: FrequencyRange[] | undefined;
    /** Portal-supplied configuration. */
    preloadedConfig: DeviceConfig | undefined;
    /** Current SAS-registered configuration. */
    activeConfig: DeviceConfig | undefined;
    /** Overridable device metadata. */
    deviceMetadata: DeviceMetadata | undefined;
    /** Device state. */
    state: string | undefined;
    /** Grants held by the device. */
    grants: DeviceGrant[] | undefined;
  },
  never,
  Providers
>;

/**
 * A Spectrum Access System (SAS) Portal CBSD under a node.
 *
 * SAS Portal devices have no labels field, so Alchemy stamps ownership
 * into `displayName` for `list` / nuke. Parent node, FCC id, and serial
 * number are identity. Display name, grant allowlists, preloaded
 * config, and metadata update in place.
 *
 * ### Creating a Device
 * **Example:** Under a customer node
 * ```typescript
 * const device = yield* GCP.SasPortal.NodesDevice("Cbsd", {
 *   parent: node.name,
 *   displayName: "sector-a",
 *   fccId: "TESTFCC",
 *   serialNumber: "SN2001",
 * });
 * ```
 *
 * ### Updating a Device
 * Change props on the same logical id; the engine keeps the physical id.
 *
 * **Example:** Rename
 * ```typescript
 * const device = yield* GCP.SasPortal.NodesDevice("Cbsd", {
 *   parent: node.name,
 *   displayName: "sector-b",
 *   fccId: "TESTFCC",
 *   serialNumber: "SN2001",
 * });
 * ```
 *
 * @resource
 * @category SasPortal
 */
export const NodesDevice = Resource<NodesDevice>("GCP.SasPortal.NodesDevice");

export class NodesDeviceNotResolved extends Data.TaggedError(
  "GCP.SasPortal.NodesDeviceNotResolved",
)<{
  parent: string;
  resourceName: string;
}> {}

const toAttrs = (device: sasportal.SasPortalDevice, parent: string, project: string) => {
  const name = device.name ?? "";
  return {
    name,
    deviceId: lastSegment(name),
    parent: parentOf(name) || parent,
    project,
    displayName: parseOwnership(device.displayName).text,
    serialNumber: device.serialNumber,
    fccId: device.fccId,
    grantRangeAllowlists: frequencyRangesOf(device.grantRangeAllowlists),
    preloadedConfig: deviceConfigOf(device.preloadedConfig),
    activeConfig: deviceConfigOf(device.activeConfig),
    deviceMetadata: deviceMetadataOf(device.deviceMetadata),
    state: device.state,
    grants: deviceGrantsOf(device.grants),
  };
};

export const NodesDeviceProvider = () =>
  Provider.succeed(NodesDevice, {
    stables: ["name", "deviceId", "parent", "project", "serialNumber", "fccId"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      return replaceOnIdentity({
        previousParent: olds?.parent ?? output?.parent,
        nextParent: expandNode(news.parent),
        previousId: olds?.name ?? output?.name,
        nextId: news.name,
        extra:
          (news.serialNumber !== undefined &&
            output?.serialNumber !== undefined &&
            news.serialNumber !== output.serialNumber) ||
          (news.fccId !== undefined && output?.fccId !== undefined && news.fccId !== output.fccId),
      });
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const parent = expandNode(olds?.parent ?? output?.parent ?? "");
      const name = olds?.name ?? output?.name ?? "";
      let existing = yield* getNodeDevice(name);
      let locatedParent = existing ? parentOf(existing.name ?? "") || parent : parent;
      if (existing === undefined) {
        const found = yield* scanOwnedNodeDevice(id, parent);
        existing = found?.row;
        locatedParent = found?.parent ?? locatedParent;
      }
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, locatedParent, env.project);
      return (yield* ownedByAlchemy(id, existing.displayName)) ? attrs : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const nodes = yield* walkNodes();
        const pages = yield* Effect.forEach(
          nodes,
          (entry) => {
            const parent = entry.node.name ?? "";
            return parent.length === 0
              ? Effect.succeed([])
              : listNodeDevices(parent).pipe(
                  Effect.map((rows) =>
                    rows
                      .filter((row) => hasOwnershipMarker(row.displayName))
                      .map((row) => toAttrs(row, parent, env.project)),
                  ),
                );
          },
          { concurrency: 4 },
        );
        return pages.flat();
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const parent = expandNode(news.parent);
      const ownership = yield* ownershipLabels(id);
      const displayName = encodeOwnershipLine(
        ownership,
        yield* toDisplayName(id, news.displayName, output?.displayName),
        MAX_DISPLAY_NAME_LENGTH,
      );
      const serialNumber = yield* toSerialNumber(id, news.serialNumber, output?.serialNumber);
      const desired = deviceBody({
        displayName,
        serialNumber,
        fccId: news.fccId ?? output?.fccId,
        grantRangeAllowlists: news.grantRangeAllowlists,
        preloadedConfig: news.preloadedConfig,
        deviceMetadata: news.deviceMetadata,
      });

      let current = yield* getNodeDevice(news.name ?? output?.name ?? "");
      if (current === undefined) {
        const found =
          (yield* findOwnedNodeDevice(id, parent)) ?? (yield* scanOwnedNodeDevice(id, parent));
        current = found?.row;
      }

      if (current === undefined) {
        const created = yield* sasportal
          .createNodesDevices({
            parent,
            body: desired,
          })
          .pipe(
            Effect.catchTag("Conflict", () =>
              findOwnedNodeDevice(id, parent).pipe(Effect.map((found) => found?.row)),
            ),
          );
        current = created ?? undefined;
      }

      if (current === undefined) {
        return yield* new NodesDeviceNotResolved({
          parent,
          resourceName: news.name ?? output?.name ?? displayName,
        });
      }

      const name = current.name ?? news.name ?? output?.name ?? "";
      const nameChanged = !sameText(current.displayName, displayName);
      const allowlistsChanged =
        news.grantRangeAllowlists !== undefined &&
        !sameJson(frequencyRangesOf(current.grantRangeAllowlists), news.grantRangeAllowlists);
      const configChanged =
        news.preloadedConfig !== undefined &&
        !sameJson(deviceConfigOf(current.preloadedConfig), news.preloadedConfig);
      const metadataChanged =
        news.deviceMetadata !== undefined &&
        !sameJson(deviceMetadataOf(current.deviceMetadata), news.deviceMetadata);
      if (nameChanged || allowlistsChanged || configChanged || metadataChanged) {
        current = yield* sasportal.patchNodesDevices({
          name,
          updateMask: updateMaskOf(
            "displayName",
            news.grantRangeAllowlists !== undefined ? "grantRangeAllowlists" : undefined,
            news.preloadedConfig !== undefined ? "preloadedConfig" : undefined,
            news.deviceMetadata !== undefined ? "deviceMetadata" : undefined,
          ),
          body: desired,
        });
      }

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

    delete: Effect.fn(function* ({ output }) {
      if (!output.name) return;
      yield* retryDelete(sasportal.deleteNodesDevices({ name: output.name })).pipe(
        Effect.catchTag("NotFound", () => Effect.void),
      );
      yield* waitUntilGone(getNodeDevice(output.name));
    }),
  });