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

import * as Neon from "@distilled.cloud/neon";
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 * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import { resolveBranchScope, type BranchScope, type ResolvedBranchScope } from "./BranchScope.ts";
import { waitForOperations } from "./Project.ts";
import type { Providers } from "./Providers.ts";

export type RoleProps = BranchScope & {
  /**
   * Postgres role name, at most 63 bytes. Omit to generate a unique,
   * lowercase name. Changing an explicit name replaces the role.
   */
  name?: string;
  /**
   * Create a role that cannot log in, for example a group role that owns
   * objects and is granted to login roles with SQL. Changes replace the role.
   * @default false
   */
  noLogin?: boolean;
};

export interface RoleAttributes extends ResolvedBranchScope {
  /** Postgres role name. */
  roleName: string;
  /** Role password; `undefined` for a role created with `noLogin`. */
  password: Redacted.Redacted<string> | undefined;
  /** Whether the role cannot log in. */
  noLogin: boolean;
  /** Authentication method reported by Neon: `password`, `oauth`, or `no_login`. */
  authenticationMethod: string | undefined;
  /** Creation time. */
  createdAt: string;
}

export interface Role extends Resource<"Neon.Role", RoleProps, RoleAttributes, never, Providers> {}

/**
 * A Postgres role on a Neon branch. Neon makes every role it creates a
 * member of `neon_superuser`: it can read and write all data, create
 * databases and roles, and bypass row-level security. Use roles for
 * separate logins and passwords, not to restrict access.
 *
 * ### Creating a Role
 * **Example:** A login role on a branch
 * ```typescript
 * const app = yield* Neon.Role("App", { branch });
 * // app.roleName and app.password (Redacted) connect to branch.origin.host
 * ```
 *
 * **Example:** A role on the project's default branch
 * ```typescript
 * const migrator = yield* Neon.Role("Migrator", { project, name: "migrator" });
 * ```
 *
 * ### Group Roles
 * **Example:** A role that cannot log in
 * ```typescript
 * const owner = yield* Neon.Role("Owner", { branch, name: "app_owner", noLogin: true });
 * ```
 *
 * @resource
 * @product Role
 */
export const Role = Resource<Role>("Neon.Role");

const requestScope = (scope: ResolvedBranchScope) => ({
  project_id: scope.projectId,
  branch_id: scope.branchId,
});

const redact = (password: string | Redacted.Redacted<string>) =>
  Redacted.isRedacted(password) ? password : Redacted.make(password);

// Underscores keep generated names usable unquoted in SQL (`GRANT ... TO app_xyz`).
const createRoleName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    if (name !== undefined) return name;
    const generated = yield* createPhysicalName({ id, maxLength: 63, lowercase: true });
    return generated.replaceAll("-", "_");
  });

const observeRole = Effect.fn(function* (scope: ResolvedBranchScope, roleName: string) {
  return yield* Neon.getProjectBranchRole({ ...requestScope(scope), role_name: roleName }).pipe(
    Effect.map(({ role }) => role),
    Effect.catchTag("NotFound", () => Effect.undefined),
  );
});

const isNoLogin = (role: Neon.Role) => role.authentication_method === "no_login";

/** Read a login role's stored password, resetting it when Neon no longer has it. */
const revealPassword = Effect.fn(function* (scope: ResolvedBranchScope, role: Neon.Role) {
  if (isNoLogin(role)) return undefined;
  const request = { ...requestScope(scope), role_name: role.name };
  const stored = yield* Neon.getProjectBranchRolePassword(request).pipe(
    Effect.map(({ password }) => redact(password)),
    Effect.catchTag("NotFound", () => Effect.undefined),
  );
  if (stored) return stored;
  const reset = yield* Neon.resetProjectBranchRolePassword(request);
  yield* waitForOperations(reset.operations);
  return reset.role.password === undefined ? undefined : redact(reset.role.password);
});

const toAttributes = (
  scope: ResolvedBranchScope,
  role: Neon.Role,
  password: Redacted.Redacted<string> | undefined,
): RoleAttributes => ({
  ...scope,
  roleName: role.name,
  password,
  noLogin: isNoLogin(role),
  authenticationMethod: role.authentication_method,
  createdAt: role.created_at,
});

export const RoleProvider = () =>
  Provider.succeed(Role, {
    stables: ["projectId", "branchId", "roleName"],
    diff: Effect.fn(function* ({ news, output }) {
      if (!isResolved(news) || !output) return;
      const scope = yield* resolveBranchScope(news);
      const sameScope = scope.projectId === output.projectId && scope.branchId === output.branchId;
      if (
        !sameScope ||
        (news.name !== undefined && news.name !== output.roleName) ||
        (news.noLogin ?? false) !== output.noLogin
      ) {
        return {
          action: "replace",
          // A generated name changes with the new instance; only an explicit,
          // unchanged name must free itself before the replacement is created.
          deleteFirst: sameScope && news.name !== undefined && news.name === output.roleName,
        };
      }
    }),
    read: Effect.fn(function* ({ id, olds, output, previous }) {
      if (!output && !olds?.branch && !olds?.project) return undefined;
      const scope = output ?? (yield* resolveBranchScope(olds!));
      const roleName = output?.roleName ?? (yield* createRoleName(id, olds?.name));
      const role = yield* observeRole(scope, roleName);
      if (!role) return undefined;
      if (output) return toAttributes(scope, role, output.password);
      // The generation a delete-first replacement is about to free.
      if (
        previous?.projectId === scope.projectId &&
        previous.branchId === scope.branchId &&
        previous.roleName === role.name
      ) {
        return toAttributes(scope, role, previous.password);
      }
      // Only an explicit name can collide with a role this stack did not create.
      const attrs = toAttributes(scope, role, yield* revealPassword(scope, role));
      return olds?.name !== undefined ? Unowned(attrs) : attrs;
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const scope = yield* resolveBranchScope(news);
      const roleName = news.name ?? output?.roleName ?? (yield* createRoleName(id, undefined));
      const existing = yield* observeRole(scope, roleName);
      if (!existing) {
        const created = yield* Neon.createProjectBranchRole({
          ...requestScope(scope),
          role: { name: roleName, ...(news.noLogin ? { no_login: true } : {}) },
        }).pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        if (created) {
          yield* waitForOperations(created.operations);
          return toAttributes(
            scope,
            created.role,
            created.role.password === undefined ? undefined : redact(created.role.password),
          );
        }
      }
      // An existing role: keep the password we already hold, otherwise reveal it.
      const role =
        existing ??
        (yield* Neon.getProjectBranchRole({
          ...requestScope(scope),
          role_name: roleName,
        })).role;
      const password =
        output?.roleName === role.name && output.password !== undefined
          ? output.password
          : yield* revealPassword(scope, role);
      return toAttributes(scope, role, password);
    }),
    delete: Effect.fn(function* ({ output }) {
      const deleted = yield* Neon.deleteProjectBranchRole({
        ...requestScope(output),
        role_name: output.roleName,
      }).pipe(Effect.catchTag("NotFound", () => Effect.undefined));
      if (deleted) yield* waitForOperations(deleted.operations);
    }),
  });