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

import * as Binding from "alchemy/Binding";
import * as Output from "alchemy/Output";
import { defaultProviderMode } from "alchemy/ProviderMode";
import type { ResourceLike } from "alchemy/Resource";
import { CurrentRuntimeContext, type RuntimeContext } from "alchemy/RuntimeContext";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Redacted from "effect/Redacted";
import type { Branch } from "./Branch.ts";
import { resolveBranchScope } from "./BranchScope.ts";
import { branchScopeOf, type Function } from "./Function.ts";
import type { Project } from "./Project.ts";

/** Postgres connection accessors. Resolving these Effects does not acquire a socket or pool. */
export interface ConnectClient {
  /** Pooled URL for ordinary application queries. */
  connectionString: Effect.Effect<Redacted.Redacted<string>, never, RuntimeContext>;
  /** Pooled URL, including Neon's pooler hostname. */
  pooledConnectionString: Effect.Effect<Redacted.Redacted<string>, never, RuntimeContext>;
  /** Direct URL for migrations, notifications, and session-oriented clients. */
  directConnectionString: Effect.Effect<Redacted.Redacted<string>, never, RuntimeContext>;
}

/**
 * Connect to a Branch or a Project's default database from a Function, Worker,
 * Lambda, or another Platform host. Same-branch Neon Functions use the injected
 * `DATABASE_URL` and `DATABASE_URL_UNPOOLED`; local Functions and other hosts
 * receive namespaced database secrets, never the deployment account API key.
 *
 * Accessors are lazy and redacted. `SQL.Postgres` and `Drizzle.Postgres` create
 * their connections in request scope, not when this binding is initialized.
 *
 * ### Querying Postgres
 * **Example:** Bind a database to an Effect host
 * ```typescript
 * Effect.gen(function* () {
 *   const db = yield* Neon.Connect(branch);
 *   const sql = yield* SQL.Postgres({ url: db.connectionString });
 *   return { fetch: Effect.gen(function* () {
 *     return yield* HttpServerResponse.json(yield* sql`SELECT 1 AS value`);
 *   }) };
 * }).pipe(Effect.provide(Neon.ConnectHttp));
 * ```
 *
 * ### Native applications
 * **Example:** Explicit environment for a native cross-branch Function
 * ```typescript
 * const api = yield* Neon.Function("Api", {
 *   branch: applicationBranch,
 *   main: "./api.ts",
 *   env: Neon.connectEnv(databaseBranch),
 * });
 * ```
 *
 * Native same-branch Neon Functions already have `DATABASE_URL` and
 * `DATABASE_URL_UNPOOLED` and need no binding. `connectEnvKeys` gives native
 * applications the names used by `connectEnv` for cross-host connections.
 *
 * @binding
 * @product Branch
 */
export interface Connect extends Binding.Service<
  Connect,
  "Neon.Connect",
  (database: Branch | Project) => Effect.Effect<ConnectClient>
> {}

export const Connect = Binding.Service<Connect>("Neon.Connect");

/** Stable, collision-free environment names for native cross-host consumers. */
export const connectEnvKeys = (database: Pick<Branch | Project, "FQN">) => {
  const name = Array.from(database.FQN, (character) => character.codePointAt(0)!.toString(16)).join(
    "_",
  );
  const prefix = `NEON_${name}`;
  return {
    injected: `${prefix}_INJECTED`,
    pooledConnectionString: `${prefix}_DATABASE_URL`,
    directConnectionString: `${prefix}_DATABASE_URL_UNPOOLED`,
  };
};

/** Redacted environment outputs for native hosts. No deployment credentials are included. */
export const connectEnv = (database: Branch | Project) => {
  const keys = connectEnvKeys(database);
  return {
    [keys.pooledConnectionString]: database.pooledConnectionUri.pipe(Output.map(Redacted.make)),
    [keys.directConnectionString]: database.connectionUri.pipe(Output.map(Redacted.make)),
  };
};

const isFunction = (host: ResourceLike | undefined): host is Function =>
  host?.Type === "Neon.Function";
const stringOutput = (value: string | Output.Output<string>) =>
  typeof value === "string" ? Output.literal(value) : value;

const injectedScope = (host: ResourceLike | undefined, database: Branch | Project) => {
  if (!isFunction(host)) return Output.literal(false);
  const scope = branchScopeOf(host.Props);
  const targetBranch =
    database.Type === "Neon.Branch" ? database.branchId : database.defaultBranchId;
  if (scope.branch) {
    return Output.all(
      stringOutput(scope.branch.projectId),
      stringOutput(scope.branch.branchId),
      database.projectId,
      targetBranch,
    ).pipe(
      Output.map(
        ([project, branch, targetProject, target]) =>
          project === targetProject && branch === target,
      ),
    );
  }
  if (scope.project) {
    const resolved = stringOutput(scope.project.projectId).pipe(
      Output.mapEffect((projectId: string) =>
        resolveBranchScope({ project: { projectId } }).pipe(Effect.orDie),
      ),
    );
    return Output.all(resolved.projectId, resolved.branchId, database.projectId, targetBranch).pipe(
      Output.map(
        ([project, branch, targetProject, target]) =>
          project === targetProject && branch === target,
      ),
    );
  }
  return Output.literal(false);
};

/** Host-independent implementation using Platform's common environment channel. */
export const ConnectHttp = Layer.effect(
  Connect,
  Effect.gen(function* () {
    const context = yield* CurrentRuntimeContext;
    if (!context) return yield* Effect.die(new Error("Neon.Connect requires a Platform host"));
    return Effect.fn(function* (database: Branch | Project) {
      const keys = connectEnvKeys(database);
      if (!globalThis.__ALCHEMY_RUNTIME__) {
        const host = yield* Binding.Host;
        const mode = host?.Mode ?? (yield* defaultProviderMode);
        const injected = mode === "local" ? Output.literal(false) : injectedScope(host, database);
        yield* context.set(keys.injected, injected);
        yield* context.set(
          keys.pooledConnectionString,
          Output.all(injected, database.pooledConnectionUri).pipe(
            Output.map(([sameBranch, uri]) => (sameBranch ? "" : Redacted.make(uri))),
          ),
        );
        yield* context.set(
          keys.directConnectionString,
          Output.all(injected, database.connectionUri).pipe(
            Output.map(([sameBranch, uri]) => (sameBranch ? "" : Redacted.make(uri))),
          ),
        );
      }
      const connection = (key: string, injectedKey: string) =>
        Effect.gen(function* () {
          const injected = yield* context.get<boolean>(keys.injected);
          const value = yield* context.get<string | Redacted.Redacted<string>>(
            injected ? injectedKey : key,
          );
          if (value === undefined || value === "") {
            return yield* Effect.die(
              new Error(`Missing Neon database environment value: ${injected ? injectedKey : key}`),
            );
          }
          return Redacted.isRedacted(value) ? value : Redacted.make(value);
        });
      const pooledConnectionString = connection(keys.pooledConnectionString, "DATABASE_URL");
      return {
        connectionString: pooledConnectionString,
        pooledConnectionString,
        directConnectionString: connection(keys.directConnectionString, "DATABASE_URL_UNPOOLED"),
      } satisfies ConnectClient;
    });
  }),
);