import { Retry } from "@distilled.cloud/prisma";
import {
type GetEnvironmentVariablesResponse,
deleteEnvironmentVariable,
getEnvironmentVariables,
getEnvironmentVariable,
updateEnvironmentVariable,
createEnvironmentVariable,
} from "@distilled.cloud/prisma/management";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as ProviderLayer from "alchemy/Local/ProviderLayer";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import { DEV_TIMESTAMP, attrOrString, devId, devProvider } from "./internal/DevStub.ts";
import type { ObservedEnvironmentVariable } from "./internal/Observed.ts";
import { PrismaPaginationError } from "./internal/Pagination.ts";
import {
concreteIdsChanged,
isInputObject,
isPrismaDevId,
resolveProjectId,
unresolvedProjectIdOf,
} from "./internal/Refs.ts";
import type { Project } from "./Project.ts";
import type { Providers } from "./Providers.ts";
export class EnvironmentVariableConflict extends Data.TaggedError("EnvironmentVariableConflict")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class EnvironmentVariableInvalidProps extends Data.TaggedError(
"EnvironmentVariableInvalidProps",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
export interface EnvironmentVariableProps {
/**
* Project ID or `project.projectId` output that owns this variable.
*/
project: string | Project;
/**
* Preview branch ID for a branch override. Omit for project-level templates.
*/
branchId?: string;
/**
* Environment variable class.
*/
class: "production" | "preview";
/**
* Environment variable key.
*/
key: string;
/**
* Secret value. Must be wrapped with `Redacted.make(...)` so the engine
* redacts it before resource props are persisted to state.
*/
value: Redacted.Redacted<string>;
}
export interface EnvironmentVariable extends Resource<
"Prisma.EnvironmentVariable",
EnvironmentVariableProps,
{
/**
* Prisma environment variable ID.
*/
environmentVariableId: string;
/**
* Project ID that owns the variable.
*/
projectId: string;
/**
* Branch ID for branch overrides, or null for project templates.
*/
branchId: string | null;
/**
* Environment variable class.
*/
class: "production" | "preview";
/**
* Environment variable key.
*/
key: string;
/**
* Secret value, redacted in state.
*/
value: Redacted.Redacted<string>;
/**
* Key identifier for the encrypted stored value.
*/
valueKid: string;
/**
* Whether Prisma manages this variable internally.
*/
isManagedBySystem: boolean;
/**
* ISO timestamp when the variable was created.
*/
createdAt: string;
/**
* ISO timestamp when the variable was last updated.
*/
updatedAt: string;
},
never,
Providers
> {}
/**
* A Prisma compute environment variable.
*
* Values are write-only in Prisma. Alchemy stores them as `Redacted` values
* and reapplies the desired value to repair drift.
*
* ### Creating a Variable
* **Example:** Project-level production variable
* ```typescript
* yield* Prisma.EnvironmentVariable("api-url", {
* project: project.projectId,
* // No branchId: this is a project-level template.
* class: "production",
* key: "API_URL",
* value: Redacted.make("https://api.example.com"),
* });
* ```
*
* **Example:** Preview branch override
* ```typescript
* yield* Prisma.EnvironmentVariable("preview-api-url", {
* project,
* branchId: preview.branchId,
* // Branch overrides always use the preview class.
* class: "preview",
* key: "API_URL",
* value: Redacted.make("https://preview.example.com"),
* });
* ```
*
* @resource
* @product Compute
*/
export const EnvironmentVariable = Resource<EnvironmentVariable>("Prisma.EnvironmentVariable");
const ENV_KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
const ENV_VALUE_MAX_BYTES = 8 * 1024;
const validateEnvironmentVariableKey = (key: string) =>
Effect.gen(function* () {
if (key.length < 1 || key.length > 256 || !ENV_KEY_PATTERN.test(key)) {
return yield* new EnvironmentVariableInvalidProps({
message: `Prisma environment variable key '${key}' must match POSIX env-var key shape: [A-Z_][A-Z0-9_]* and be at most 256 characters.`,
});
}
});
const validateEnvironmentVariableWrite = (key: string, value: Redacted.Redacted<string>) =>
Effect.gen(function* () {
yield* validateEnvironmentVariableKey(key);
const raw = Redacted.value(value);
if (raw.length === 0) {
return yield* new EnvironmentVariableInvalidProps({
message: `Prisma environment variable '${key}' value must be non-empty.`,
});
}
const byteLength = yield* Effect.sync(() => new TextEncoder().encode(raw).byteLength);
if (byteLength > ENV_VALUE_MAX_BYTES) {
return yield* new EnvironmentVariableInvalidProps({
message: `Prisma environment variable '${key}' value exceeds ${ENV_VALUE_MAX_BYTES} bytes.`,
});
}
});
// Distilled emits the cursor-paginated list operations as plain ops, so
// callers walk `pagination` themselves (see `src/Neon/Project.ts`).
const listVariables = (
query: {
readonly projectId?: string;
readonly class?: "production" | "preview";
readonly key?: string;
readonly branchId?: string;
readonly limit?: number;
} = {},
) =>
Effect.gen(function* () {
const variables: GetEnvironmentVariablesResponse["data"][number][] = [];
let cursor: string | undefined;
while (true) {
const page = yield* getEnvironmentVariables(
cursor === undefined ? query : { ...query, cursor },
);
variables.push(...page.data);
const nextCursor = page.pagination.nextCursor;
if (!page.pagination.hasMore) break;
if (nextCursor === null) {
return yield* new PrismaPaginationError({
message:
"Invalid Prisma Management API pagination response from getEnvironmentVariables: hasMore was true without a non-empty nextCursor",
});
}
cursor = nextCursor;
}
return variables;
});
const findVariable = (
projectId: string,
cls: "production" | "preview",
key: string,
branchId?: string | null,
) =>
listVariables({
projectId,
class: cls,
key,
...(branchId ? { branchId } : {}),
limit: 100,
}).pipe(
Effect.flatMap((variables) => {
const matches = variables.filter((variable) => variable.branchId === (branchId ?? null));
return matches.length > 1
? Effect.fail(
new EnvironmentVariableConflict({
message: `Multiple Prisma environment variables match '${key}' in the requested scope; refusing to select one arbitrarily.`,
}),
)
: Effect.succeed(matches[0]);
}),
);
const attrsFrom = (
variable: ObservedEnvironmentVariable,
value: Redacted.Redacted<string>,
): EnvironmentVariable["Attributes"] => ({
environmentVariableId: variable.id,
projectId: variable.projectId,
branchId: variable.branchId,
class: variable.class,
key: variable.key,
value,
valueKid: variable.valueKid,
isManagedBySystem: variable.isManagedBySystem,
createdAt: variable.createdAt,
updatedAt: variable.updatedAt,
});
const systemManagedVariableError = (key: string) =>
new Error(
`Prisma environment variable '${key}' is managed by Prisma and cannot be managed by Alchemy.`,
);
const ensureUserManagedVariable = (variable: ObservedEnvironmentVariable) =>
Effect.gen(function* () {
if (variable.isManagedBySystem) {
return yield* Effect.fail(systemManagedVariableError(variable.key));
}
});
const ensureVariableIdentity = (
variable: ObservedEnvironmentVariable,
expected: {
projectId: string;
branchId: string | null;
class: "production" | "preview";
key: string;
},
) =>
variable.projectId === expected.projectId &&
variable.branchId === expected.branchId &&
variable.class === expected.class &&
variable.key === expected.key
? Effect.void
: Effect.fail(
new EnvironmentVariableConflict({
message: `Prisma environment variable '${variable.id}' has immutable identity project '${variable.projectId}', branch '${variable.branchId ?? "null"}', class '${variable.class}', key '${variable.key}', but this resource requires project '${expected.projectId}', branch '${expected.branchId ?? "null"}', class '${expected.class}', key '${expected.key}'. Refusing to update or delete a mismatched secret.`,
}),
);
const ProviderLive = () =>
Provider.effect(
EnvironmentVariable,
Effect.gen(function* () {
return {
stables: ["environmentVariableId"],
list: () =>
listVariables().pipe(
Effect.map((variables) =>
variables
// System-managed variables are project-owned and cannot be
// deleted through this API.
.filter((variable) => !variable.isManagedBySystem)
.map((variable) =>
// The API deliberately never returns plaintext. `delete`
// needs only identity/metadata, so nuke uses an impossible
// empty placeholder rather than pretending to know a secret.
attrsFrom(variable, Redacted.make("")),
),
),
),
diff: Effect.fn(function* ({ olds, news, output }) {
if (!isInputObject(news)) return undefined;
if (isPrismaDevId(output?.environmentVariableId)) {
return { action: "update" } as const;
}
const oldProjectId = output?.projectId ?? unresolvedProjectIdOf(olds.project);
const newProjectId = isResolved(news.project)
? unresolvedProjectIdOf(news.project)
: undefined;
if (
concreteIdsChanged(oldProjectId, newProjectId) ||
(isResolved(news.branchId) && news.branchId !== olds.branchId) ||
(isResolved(news.class) && news.class !== olds.class) ||
(isResolved(news.key) && news.key !== olds.key)
) {
return { action: "replace" } as const;
}
// Values are write-only: the Management API never returns
// plaintext, so equality with `olds` cannot prove the live secret
// is still correct. Re-apply every resolved desired value to heal
// out-of-band secret drift on ordinary deploys.
if (isResolved(news.value)) {
return { action: "update" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ output, olds }) {
const variableId = isPrismaDevId(output?.environmentVariableId)
? undefined
: output?.environmentVariableId;
const findVariableInProject = Effect.gen(function* () {
const projectId = unresolvedProjectIdOf(olds.project);
return projectId
? yield* findVariable(projectId, olds.class, olds.key, olds.branchId)
: undefined;
});
const variable = variableId
? yield* getEnvironmentVariable({
envVarId: variableId,
}).pipe(
Effect.map((response) => response.data),
Effect.catchTag("NotFound", () => Effect.undefined),
)
: yield* findVariableInProject;
if (!variable) return undefined;
const attrs = attrsFrom(
variable,
// A cold read cannot observe the secret. Never copy the desired
// value into output: doing so would make the forced adoption
// reconcile falsely conclude the cloud already contains it.
output?.value ?? Redacted.make(""),
);
return variableId === undefined ? Unowned(attrs) : attrs;
}),
reconcile: Effect.fn(function* ({ news, output }) {
if (news.branchId !== undefined && news.class !== "preview") {
return yield* new EnvironmentVariableInvalidProps({
message: 'Prisma branch-scoped environment variables must use class: "preview".',
});
}
yield* validateEnvironmentVariableWrite(news.key, news.value);
const projectId = yield* resolveProjectId(news.project);
const variableId = isPrismaDevId(output?.environmentVariableId)
? undefined
: output?.environmentVariableId;
let variable = variableId
? yield* getEnvironmentVariable({
envVarId: variableId,
}).pipe(
Effect.map((response) => response.data),
Effect.catchTag("NotFound", () => Effect.undefined),
)
: undefined;
const value = news.value;
let created = false;
if (!variable) {
const result = yield* createEnvironmentVariable({
projectId,
...(news.branchId ? { branchId: news.branchId } : {}),
class: news.class,
key: news.key,
value: Redacted.value(value),
}).pipe(
// A replayed create would mint a second variable; the retry
// policy cannot see the request, so opt out explicitly.
Retry.none,
Effect.map((response) => ({
variable: response.data,
created: true,
})),
Effect.catchTag("Conflict", () =>
Effect.fail(
new EnvironmentVariableConflict({
message: `Prisma environment variable '${news.key}' appeared after the adoption check. Refusing to overwrite its secret; rerun with adoption enabled if it is the intended variable.`,
}),
),
),
);
variable = result.variable;
created = result.created;
}
yield* ensureVariableIdentity(variable, {
projectId,
branchId: news.branchId ?? null,
class: news.class,
key: news.key,
});
yield* ensureUserManagedVariable(variable);
if (!created) {
variable = (yield* updateEnvironmentVariable({
envVarId: variable.id,
value: Redacted.value(value),
})).data;
}
return attrsFrom(variable, value);
}),
delete: Effect.fn(function* ({ output, session }) {
if (isPrismaDevId(output.environmentVariableId)) return;
const variable = yield* getEnvironmentVariable({
envVarId: output.environmentVariableId,
}).pipe(
Effect.map((response) => response.data),
Effect.catchTag("NotFound", () => Effect.undefined),
);
if (!variable) return;
yield* ensureVariableIdentity(variable, {
projectId: output.projectId,
branchId: output.branchId,
class: output.class,
key: output.key,
});
if (variable.isManagedBySystem) {
// Prisma-owned environment variables are provider-managed system
// state and are not deletable through this resource lifecycle.
if (session !== undefined) {
yield* session.note(
`Skipping direct delete for system-managed Prisma environment variable '${variable.key}'.`,
);
}
return;
}
yield* deleteEnvironmentVariable({
envVarId: variable.id,
}).pipe(Effect.catchTag("NotFound", () => Effect.void));
}),
};
}),
);
const ProviderLocal = () =>
devProvider(EnvironmentVariable, ["environmentVariableId"], ({ id, news }) => ({
environmentVariableId: devId("environment-variable", id),
projectId: attrOrString(news.project, "projectId"),
branchId: news.branchId ?? null,
class: news.class,
key: news.key,
value: news.value,
valueKid: devId("value-kid", id),
isManagedBySystem: false,
createdAt: DEV_TIMESTAMP,
updatedAt: DEV_TIMESTAMP,
}));
export const EnvironmentVariableProvider = () =>
ProviderLayer.dual(EnvironmentVariable, {
local: () => ProviderLocal(),
live: () => ProviderLive(),
});