sailfork / t3code-github / .repos/ alchemy-effect/ packages/ neon/ src/ DataApi.ts

import * as Neon from "@distilled.cloud/neon";
import { OwnedBySomeoneElse, unownedUnlessPrevious } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { authPlanScope, authRequest, authSettingsMatch, removedAuthSettings } from "./Auth.ts";
import { resolveBranchScope, type ResolvedBranchScope } from "./BranchScope.ts";
import type { Providers } from "./Providers.ts";

export type DataApiProps = (
  | {
      /** Branch resource or explicit identity, optionally carrying its selected database. */
      branch: { projectId: string; branchId: string; databaseName?: string };
      project?: never;
    }
  | {
      /** Project resource or explicit identity; selects the observed default branch. */
      project: { projectId: string; databaseName?: string };
      branch?: never;
    }
) & {
  /** Database served by PostgREST. Infers the referenced resource's selected database, or the branch's only database; required when ambiguous. */
  database?: string;
  /** Authentication mechanism. Changes replace the Data API. */
  authProvider?: "neon_auth" | "external";
  /** HTTPS JWKS endpoint required for external authentication. */
  jwksUrl?: string;
  /** Display name for an external authentication provider. */
  providerName?: string;
  /** Expected JWT audience. Neon still accepts tokens without an audience. */
  jwtAudience?: string;
  /** Opt in to public-schema table grants. Defaults to false. */
  addDefaultGrants?: boolean;
  /** Skip creating the auth schema and RLS helpers. */
  skipAuthSchema?: boolean;
  /** Explicitly owned PostgREST settings. Removing previously managed fields requires an explicit reset value. */
  settings?: Neon.DataAPISettings;
};

export interface DataApiAttributes {
  /** Neon project identity. */
  projectId: string;
  /** Branch identity. */
  branchId: string;
  /** Database served by this endpoint. */
  database: string;
  /** Public PostgREST base URL. Requests must carry end-user authorization. */
  url: string;
  /** Observed deployment status. */
  status: string;
  /** Observed PostgREST settings, if exposed by the backend. */
  settings: Neon.DataAPISettings | undefined;
}

export interface DataApi extends Resource<
  "Neon.DataApi",
  DataApiProps,
  DataApiAttributes,
  never,
  Providers
> {}

/**
 * Own a branch/database Data API singleton. This resource never grants an
 * application the account deployment key. Configure RLS and forward the user's
 * token through QueryDataApi. Authentication inputs are creation-only because
 * the API only supports updating PostgREST settings.
 *
 * ### Expose a database through managed authentication
 * **Example:** Managed Auth and PostgREST
 * ```typescript
 * const dataApi = yield* Neon.DataApi("Data", {
 *   branch, authProvider: "neon_auth", settings: { db_max_rows: 100 },
 * });
 * ```
 *
 * @resource
 * @product Data API
 */
export const DataApi = Resource<DataApi>("Neon.DataApi");

export class InvalidDataApiConfiguration extends Data.TaggedError("InvalidDataApiConfiguration")<{
  message: string;
}> {}

const observe = (scope: { projectId: string; branchId: string; database: string }) =>
  Neon.getProjectBranchDataAPI({
    ...authRequest(scope),
    database_name: scope.database,
  }).pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const attributes = (
  scope: { projectId: string; branchId: string; database: string },
  observed: Neon.DataAPIReponse,
): DataApiAttributes => ({
  projectId: scope.projectId,
  branchId: scope.branchId,
  database: scope.database,
  url: observed.url,
  status: observed.status,
  settings: observed.settings ?? undefined,
});

const immutable = [
  "authProvider",
  "jwksUrl",
  "providerName",
  "jwtAudience",
  "addDefaultGrants",
  "skipAuthSchema",
] as const;

const validateDataApi = (news: DataApiProps) =>
  news.authProvider === "external" && !news.jwksUrl
    ? Effect.fail(
        new InvalidDataApiConfiguration({
          message: "External authentication requires jwksUrl",
        }),
      )
    : Effect.void;

const validateDataApiRemoval = (olds: DataApiProps | undefined, news: Input<DataApiProps>) => {
  const removed = removedAuthSettings(olds, news, [...immutable, "settings"]);
  return removed.length === 0
    ? Effect.void
    : Effect.fail(
        new InvalidDataApiConfiguration({
          message: `Cannot remove managed Data API settings: ${removed.join(", ")}; set explicit reset values instead`,
        }),
      );
};

const resolveDatabase = Effect.fn(function* (news: DataApiProps, scope: ResolvedBranchScope) {
  const database = news.database ?? (news.branch ?? news.project)?.databaseName;
  if (database !== undefined) {
    if (!database)
      return yield* new InvalidDataApiConfiguration({
        message: "database must not be empty",
      });
    return database;
  }
  const { databases } = yield* Neon.listProjectBranchDatabases(authRequest(scope));
  if (databases.length !== 1) {
    return yield* new InvalidDataApiConfiguration({
      message: "Set database explicitly when the branch has no unambiguous selected database",
    });
  }
  return databases[0]!.name;
});

export const DataApiProvider = () =>
  Provider.succeed(DataApi, {
    stables: ["projectId", "branchId", "database"],
    diff: Effect.fn(function* ({ olds, news, output }) {
      yield* validateDataApiRemoval(olds, news);
      if (isResolved(news)) yield* validateDataApi(news);
      const scope = yield* authPlanScope(news);
      if (
        output &&
        (!scope || scope.projectId !== output.projectId || scope.branchId !== output.branchId)
      ) {
        return { action: "replace", deleteFirst: true } as const;
      }
      if (!isResolved(news)) return;
      const resolved = scope ?? (yield* resolveBranchScope(news));
      const database = yield* resolveDatabase(news, resolved);
      const previous = output ?? (yield* resolveBranchScope(olds));
      if (
        resolved.projectId !== previous.projectId ||
        resolved.branchId !== previous.branchId ||
        database !== (output?.database ?? (yield* resolveDatabase(olds, previous))) ||
        immutable.some((key) => news[key] !== olds[key])
      ) {
        return { action: "replace", deleteFirst: true } as const;
      }
      if (output) {
        const current = yield* observe({ ...resolved, database });
        if (
          !current ||
          (news.settings !== undefined && !authSettingsMatch(current.settings ?? {}, news.settings))
        )
          return { action: "update" } as const;
      }
    }),
    read: Effect.fn(function* ({ olds, output, previous }) {
      if (
        !output &&
        !(olds?.branch?.projectId && olds.branch.branchId) &&
        !olds?.project?.projectId
      )
        return undefined;
      const branch = output ?? (yield* resolveBranchScope(olds));
      const scope = output ?? {
        ...branch,
        database: yield* resolveDatabase(olds, branch),
      };
      const current = yield* observe(scope);
      if (!current) return undefined;
      const attrs = attributes(scope, current);
      return output ? attrs : unownedUnlessPrevious(attrs, previous, "database");
    }),
    reconcile: Effect.fn(function* ({ news, output, olds }) {
      yield* validateDataApiRemoval(olds, news);
      yield* validateDataApi(news);
      const branch = yield* resolveBranchScope(news);
      const scope = {
        ...branch,
        database: yield* resolveDatabase(news, branch),
      };
      if (
        output &&
        (scope.projectId !== output.projectId ||
          scope.branchId !== output.branchId ||
          scope.database !== output.database)
      ) {
        return yield* new InvalidDataApiConfiguration({
          message:
            "Data API identity changed without replacement; refusing to mutate either endpoint",
        });
      }
      const request = { ...authRequest(scope), database_name: scope.database };
      let current = yield* observe(scope);
      if (current && !output)
        return yield* new OwnedBySomeoneElse({
          message: "Existing Data API requires explicit adoption",
          resourceType: "Neon.DataApi",
        });
      if (current && olds === undefined && immutable.some((key) => news[key] !== undefined)) {
        return yield* new InvalidDataApiConfiguration({
          message:
            "Neon does not expose existing Data API authentication settings; adopt without creation-only settings, then replace to configure authentication",
        });
      }
      if (!current) {
        yield* Neon.createProjectBranchDataAPI({
          ...request,
          auth_provider: news.authProvider,
          jwks_url: news.jwksUrl,
          provider_name: news.providerName,
          jwt_audience: news.jwtAudience,
          add_default_grants: news.addDefaultGrants ?? false,
          skip_auth_schema: news.skipAuthSchema,
          settings: news.settings,
        }).pipe(
          Effect.catchTag("Conflict", () =>
            Effect.fail(
              new OwnedBySomeoneElse({
                message: "Data API appeared during creation; explicit adoption is required",
                resourceType: "Neon.DataApi",
              }),
            ),
          ),
        );
        current = yield* Neon.getProjectBranchDataAPI(request);
      }
      if (
        news.settings !== undefined &&
        !authSettingsMatch(current.settings ?? {}, news.settings)
      ) {
        yield* Neon.updateProjectBranchDataAPI({
          ...request,
          settings: news.settings,
        });
      }
      return attributes(scope, yield* Neon.getProjectBranchDataAPI(request));
    }),
    delete: Effect.fn(function* ({ output }) {
      if (yield* observe(output)) {
        yield* Neon.deleteProjectBranchDataAPI({
          ...authRequest(output),
          database_name: output.database,
        }).pipe(Effect.catchTag("NotFound", () => Effect.void));
      }
    }),
  });