From 2218473b2979d7f71077a69b5e5a8ad155845e7e Mon Sep 17 00:00:00 2001 From: willbot Date: Fri, 20 Nov 2026 22:23:48 +1100 Subject: [PATCH 1/6] fix(prisma-cloud): the deploy checks platform variables against the variable group the branch receives Preflight now makes one read, GET /v1/projects/{projectId}/resolved-variables, for the environment's branch (the default branch for production), in place of one list call per name filtered by class. A name is present when the read lists it, whatever group or override it comes from, so a value set in a custom variable group is seen. A failed read, or an answer that is paged, fails the deploy; there is no fallback to the old lookup, which gave wrong answers on a custom group. The commands for a missing variable follow the group's class, and the command that writes a branch override is no longer suggested. Co-Authored-By: Claude Fable 5.2 Signed-off-by: willbot Signed-off-by: Will Madden --- .../__tests__/map-with-concurrency.test.ts | 48 -- .../src/__tests__/preflight-payload.test.ts | 10 +- .../target/src/__tests__/preflight.test.ts | 688 ++++++++---------- .../target/src/map-with-concurrency.ts | 22 - .../1-extensions/target/src/preflight.ts | 163 +++-- 5 files changed, 407 insertions(+), 524 deletions(-) delete mode 100644 packages/1-prisma-cloud/1-extensions/target/src/__tests__/map-with-concurrency.test.ts delete mode 100644 packages/1-prisma-cloud/1-extensions/target/src/map-with-concurrency.ts diff --git a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/map-with-concurrency.test.ts b/packages/1-prisma-cloud/1-extensions/target/src/__tests__/map-with-concurrency.test.ts deleted file mode 100644 index 908f9bb66..000000000 --- a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/map-with-concurrency.test.ts +++ /dev/null @@ -1,48 +0,0 @@ -import { describe, expect, test } from 'bun:test'; -import { mapWithConcurrency } from '../map-with-concurrency.ts'; - -const tick = () => new Promise((resolve) => setTimeout(resolve, 1)); - -describe('mapWithConcurrency', () => { - test('keeps the results in the order of the items, whatever order the tasks finish in', async () => { - const results = await mapWithConcurrency([30, 10, 20], 3, async (ms) => { - await new Promise((resolve) => setTimeout(resolve, ms)); - return ms * 2; - }); - - expect(results).toEqual([60, 20, 40]); - }); - - test('never runs more than the limit at once', async () => { - let running = 0; - let most = 0; - await mapWithConcurrency( - Array.from({ length: 10 }, (_, index) => index), - 3, - async () => { - running += 1; - most = Math.max(most, running); - await tick(); - running -= 1; - }, - ); - - expect(most).toBe(3); - }); - - test('the first failure rejects the call, and no task starts after it', async () => { - const started: number[] = []; - const run = mapWithConcurrency([0, 1, 2, 3, 4], 1, async (item) => { - started.push(item); - await tick(); - if (item === 1) throw new Error('list failed'); - }); - - await expect(run).rejects.toThrow('list failed'); - expect(started).toEqual([0, 1]); - }); - - test('no items gives no results', async () => { - expect(await mapWithConcurrency([], 8, async () => 1)).toEqual([]); - }); -}); diff --git a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight-payload.test.ts b/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight-payload.test.ts index 053cbcbfd..3d47e2f66 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight-payload.test.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight-payload.test.ts @@ -34,13 +34,16 @@ const graph = () => }), ); -/** A platform holding STRIPE_SECRET_KEY, last written at `updatedAt`, or no row when `updatedAt` is undefined. Its VALUE is never returned — the API returns none. */ +/** A platform whose production group holds STRIPE_SECRET_KEY, last written at `updatedAt`, or does not hold it when `updatedAt` is undefined. The read returns no value. */ const fakePlatform = (updatedAt: string | undefined): ManagementApiClient => ({ GET: async () => ({ data: { - data: updatedAt === undefined ? [] : [{ branchId: null, updatedAt }], - pagination: { nextCursor: null, hasMore: false }, + group: { id: 'grp-production', name: 'production', class: 'production' }, + data: + updatedAt === undefined + ? [] + : [{ key: 'STRIPE_SECRET_KEY', updatedAt, isManagedBySystem: false }], }, error: undefined, response: new Response(null, { status: 200 }), @@ -63,6 +66,7 @@ const preflightAgainst = (updatedAt: string | undefined) => { appName: 'app', environment: 'production' }, 'proj', undefined, + 'br-default', ), environment: 'production', }, diff --git a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts b/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts index a57923b68..f4f559cee 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts @@ -27,9 +27,16 @@ const copyOf = (value: T): T => { return out.value as T; }; -/** A resolved container matching `input.container` after the boundary move — preflight narrows it with `prismaCloudContainerOf`. */ +/** A resolved container: a named environment carries its branch id, production its project's default branch id. */ const fakeContainer = (projectId: string, branchId: string | undefined) => - new PrismaCloudContainer({ appName: 'app', environment: 'production' }, projectId, branchId); + new PrismaCloudContainer( + { appName: 'app', environment: branchId === undefined ? 'production' : 'pr-1' }, + projectId, + branchId, + branchId === undefined ? DEFAULT_BRANCH_ID : undefined, + ); + +const DEFAULT_BRANCH_ID = 'br-default'; const build = { extension: '@prisma/composer/node', @@ -38,61 +45,110 @@ const build = { entry: 'server.js', }; +/** A row of the environment-variable list, which only the key-clash check still reads. */ interface Row { projectId: string; class: 'production' | 'preview'; key: string; branchId: string | null; - /** Defaulted by the fake client — only the rotation tests below care what it is. */ +} + +type Source = + | { type: 'group'; groupId: string; groupName: string; groupClass: string } + | { type: 'branchOverride' } + | { type: 'service'; serviceId: string }; + +/** One key the resolved-variables read lists for the branch. */ +interface Entry { + key: string; + /** Defaulted by the fake client. */ updatedAt?: string; isManagedBySystem?: boolean; + source?: Source; +} + +interface Group { + id: string; + name: string; + class: 'production' | 'preview' | 'custom'; } -/** What a row the test did not date reads as. */ +/** What a key the test did not date reads as. */ const DEFAULT_UPDATED_AT = '2026-01-01T00:00:00.000Z'; +const RESOLVED_VARIABLES_PATH = '/v1/projects/{projectId}/resolved-variables'; + interface FakeState { + /** Queries of the environment-variable list. */ gets: Record[]; + /** Each resolved-variables read, by the project and branch it asked about. */ + reads: { projectId: string; branchId: string }[]; posts: Record[]; rows: Row[]; - /** Page size for the env-var listing — unset serves everything in one page. */ - pageSize?: number; - /** When set, the listing reports hasMore with a nextCursor equal to the request's cursor — a broken, non-advancing pagination. */ - cursorStuck?: boolean; - /** When set, the listing always reports hasMore with an ever-advancing nextCursor — pagination that never ends. */ - cursorRunaway?: boolean; - /** When set, the listing reports hasMore but returns no nextCursor — more pages that cannot be fetched. */ - cursorMissing?: boolean; + entries: Entry[]; + /** The group the branch receives; unset gives `production` for the default branch and `preview` otherwise. */ + group?: Group; + /** Replaces the read's answer: an error status, or a body of the test's own. */ + answer?: { status: number; body?: unknown; error?: unknown }; } +const emptyState = (): FakeState => ({ gets: [], reads: [], posts: [], rows: [], entries: [] }); + +const builtInGroup = (branchId: string): Group => + branchId === DEFAULT_BRANCH_ID + ? { id: 'grp-production', name: 'production', class: 'production' } + : { id: 'grp-preview', name: 'preview', class: 'preview' }; + /** A stubbed Management API client — test file, exempt from the no-bare-cast rule. */ const fakeClient = (state: FakeState): ManagementApiClient => ({ - GET: async (_path: string, init: { params: { query: Record } }) => { + GET: async ( + path: string, + init: { + params: { path?: Record; query: Record }; + }, + ) => { + if (path === RESOLVED_VARIABLES_PATH) { + const projectId = init.params.path?.['projectId'] ?? ''; + const branchId = init.params.query['branchId'] ?? ''; + state.reads.push({ projectId, branchId }); + if (state.answer !== undefined) { + const ok = state.answer.status < 400; + return { + data: ok ? state.answer.body : undefined, + error: ok ? undefined : state.answer.error, + response: new Response(null, { status: state.answer.status }), + }; + } + const group = state.group ?? builtInGroup(branchId); + return { + data: { + group, + data: state.entries.map((entry) => ({ + key: entry.key, + updatedAt: entry.updatedAt ?? DEFAULT_UPDATED_AT, + isManagedBySystem: entry.isManagedBySystem ?? false, + source: entry.source ?? { + type: 'group', + groupId: group.id, + groupName: group.name, + groupClass: group.class, + }, + })), + }, + error: undefined, + response: new Response(null, { status: 200 }), + }; + } const q = init.params.query; state.gets.push(q); const rows = state.rows.filter( (r) => r.projectId === q['projectId'] && r.class === q['class'] && r.key === q['key'], ); - const offset = q['cursor'] === undefined ? 0 : Number(q['cursor']); - const pageSize = state.pageSize ?? rows.length; - const data = rows.slice(offset, offset + pageSize); - const pagination = - state.cursorStuck === true - ? { nextCursor: String(offset), hasMore: true } - : state.cursorRunaway === true - ? { nextCursor: String(offset + 1), hasMore: true } - : state.cursorMissing === true - ? { nextCursor: null, hasMore: true } - : { - nextCursor: - offset + data.length < rows.length ? String(offset + data.length) : null, - hasMore: offset + data.length < rows.length, - }; return { data: { - data: data.map((r) => ({ ...r, updatedAt: r.updatedAt ?? DEFAULT_UPDATED_AT })), - pagination, + data: rows.map((r) => ({ ...r, updatedAt: DEFAULT_UPDATED_AT })), + pagination: { nextCursor: null, hasMore: false }, }, error: undefined, response: new Response(null, { status: 200 }), @@ -267,74 +323,226 @@ const failureOf = async (run: Promise): Promise => { return error.message; }; -describe('the deploy check reads which variables exist and sets none', () => { +describe('the deploy check reads which variables the branch receives and sets none', () => { let state: FakeState; beforeEach(() => { - state = { gets: [], posts: [], rows: [] }; + state = emptyState(); }); - test('in production, a variable with a production row passes', async () => { - state.rows = [ - { projectId: 'proj', class: 'production', key: 'STRIPE_SECRET_KEY', branchId: null }, - ]; + const manyNamesGraph = (names: readonly string[]) => + Load( + appRoot('app', ({ provision }) => { + provision(compute({ name: 'ingest', deps: {}, input: anySchema, build }), { + id: 'ingest', + input: Object.fromEntries( + names.map((name) => [name.toLowerCase(), provision(variable.secret({ name }))]), + ), + }); + }), + ); - await preflightWith( - { graph: requiredSecretGraph(), ...production }, + test("a key from the branch's group is present, and its time is handed back", async () => { + state.entries = [{ key: 'STRIPE_SECRET_KEY', updatedAt: '2026-05-05T12:00:00.000Z' }]; + + const result = await preflightWith( + { graph: requiredSecretGraph(), ...preview }, { client: fakeClient(state) }, ); - expect(state.gets).toEqual([ - { projectId: 'proj', class: 'production', key: 'STRIPE_SECRET_KEY' }, - ]); + expect([...result.updatedAt]).toEqual([['STRIPE_SECRET_KEY', '2026-05-05T12:00:00.000Z']]); + expect(result.findings).toEqual({ unset: [] }); }); - test('in a named environment, a preview-wide row counts as a value', async () => { - state.rows = [ - { projectId: 'proj', class: 'preview', key: 'STRIPE_SECRET_KEY', branchId: null }, + test("a key from the branch's override is present, and its time is handed back", async () => { + state.entries = [ + { + key: 'STRIPE_SECRET_KEY', + updatedAt: '2026-07-07T12:00:00.000Z', + source: { type: 'branchOverride' }, + }, ]; - await preflightWith( + const result = await preflightWith( { graph: requiredSecretGraph(), ...preview }, { client: fakeClient(state) }, ); - expect(state.gets[0]?.['class']).toBe('preview'); + expect([...result.updatedAt]).toEqual([['STRIPE_SECRET_KEY', '2026-07-07T12:00:00.000Z']]); }); - test("in a named environment, this branch's own row counts as a value", async () => { - state.rows = [ - { projectId: 'proj', class: 'preview', key: 'STRIPE_SECRET_KEY', branchId: 'br-1' }, - ]; + test('a key the read does not list is unset and has no time', async () => { + state.entries = [{ key: 'SOMETHING_ELSE' }]; - await preflightWith( - { graph: requiredSecretGraph(), ...preview }, + const result = await preflightWith( + { graph: secretGraph(), ...preview }, { client: fakeClient(state) }, ); + + expect(result.findings.unset.map((variable) => variable.name)).toEqual(['STRIPE_SECRET_KEY']); + expect(result.updatedAt.has('STRIPE_SECRET_KEY')).toBe(false); }); - test("in a named environment, another branch's row does not count", async () => { - state.rows = [ - { projectId: 'proj', class: 'preview', key: 'STRIPE_SECRET_KEY', branchId: 'br-2' }, - ]; + test('a listed key the platform manages itself fails, naming the variable', async () => { + state.entries = [{ key: 'STRIPE_SECRET_KEY', isManagedBySystem: true }]; const message = await failureOf( - preflightWith({ graph: requiredSecretGraph(), ...preview }, { client: fakeClient(state) }), + preflightWith({ graph: secretGraph(), ...preview }, { client: fakeClient(state) }), ); - expect(message).toContain('STRIPE_SECRET_KEY'); + expect(message).toContain( + '"STRIPE_SECRET_KEY" is a platform variable that Prisma Cloud manages itself', + ); }); - test('in production, a production row with a branch does not count', async () => { - state.rows = [ - { projectId: 'proj', class: 'production', key: 'STRIPE_SECRET_KEY', branchId: 'br-2' }, - ]; + test('reads once per deploy, however many names the app has', async () => { + const names = Array.from({ length: 20 }, (_, index) => `KEY_${index}`); + + await preflightWith( + { graph: manyNamesGraph(names), ...production }, + { client: fakeClient(state) }, + ); + + expect(state.reads).toHaveLength(1); + expect(state.gets).toEqual([]); + }); + + test('production reads the project default branch', async () => { + await preflightWith({ graph: secretGraph(), ...production }, { client: fakeClient(state) }); + + expect(state.reads).toEqual([{ projectId: 'proj', branchId: DEFAULT_BRANCH_ID }]); + }); + + test('another environment reads its own branch', async () => { + await preflightWith({ graph: secretGraph(), ...preview }, { client: fakeClient(state) }); + + expect(state.reads).toEqual([{ projectId: 'proj', branchId: 'br-1' }]); + }); + + test('a graph with no platform variable makes no platform call and returns nothing', async () => { + const result = await preflightWith( + { graph: noSecretGraph(), ...production }, + { client: fakeClient(state) }, + ); + + expect(state.reads).toEqual([]); + expect(state.gets).toEqual([]); + expect(result).toEqual({ updatedAt: new Map(), findings: { unset: [] } }); + }); + + test('a value Composer generates needs no platform check', async () => { + await preflightWith({ graph: generatedGraph(), ...production }, { client: fakeClient(state) }); + + expect(state.reads).toEqual([]); + }); + + test('a literal-bound param never reaches the platform', async () => { + await preflightWith( + { graph: literalParamGraph(), ...production }, + { client: fakeClient(state) }, + ); + + expect(state.reads).toEqual([]); + expect(state.gets).toEqual([]); + }); + + describe('a failed read fails the deploy, naming the call, the status, the project and the branch', () => { + test.each([ + ['an unknown project', 404, { code: 'not-found', message: 'Project not found' }], + ['an unknown branch', 404, { code: 'not-found', message: 'Branch not found' }], + ['a server error', 500, { code: 'internal', message: 'boom' }], + ])('%s', async (_case, status, error) => { + state.answer = { status, error }; + + const message = await failureOf( + preflightWith({ graph: secretGraph(), ...preview }, { client: fakeClient(state) }), + ); + + expect(message).toBe( + `Deploy failed. GET /v1/projects/proj/resolved-variables?branchId=br-1 answered HTTP ${status}: ${JSON.stringify(error)}. ` + + 'The platform may not offer this read yet, and this Composer version needs it to check platform variables.', + ); + expect(state.reads).toHaveLength(1); + expect(state.gets).toEqual([]); + expect(state.posts).toEqual([]); + }); + }); + + test.each([ + ['a pagination object', { pagination: { nextCursor: 'c1', hasMore: true } }], + ['a next cursor', { nextCursor: 'c1' }], + ['a more-pages flag', { hasMore: false }], + ])( + 'an answer that carries %s fails the deploy as too old for the platform', + async (_case, extra) => { + state.answer = { + status: 200, + body: { group: builtInGroup('br-1'), data: [], ...extra }, + }; + + const message = await failureOf( + preflightWith({ graph: secretGraph(), ...preview }, { client: fakeClient(state) }), + ); + + expect(message).toStartWith( + 'Deploy failed. GET /v1/projects/proj/resolved-variables?branchId=br-1 answered with one page of a longer list.', + ); + expect(message).toContain('too old for the platform'); + }, + ); + + test('an answer without the group fails the deploy instead of guessing', async () => { + state.answer = { status: 200, body: { data: [] } }; const message = await failureOf( - preflightWith({ graph: requiredSecretGraph(), ...production }, { client: fakeClient(state) }), + preflightWith({ graph: secretGraph(), ...preview }, { client: fakeClient(state) }), ); - expect(message).toContain('STRIPE_SECRET_KEY'); + expect(message).toStartWith( + 'Deploy failed. GET /v1/projects/proj/resolved-variables?branchId=br-1 answered with a body this Composer version cannot read: ', + ); + }); + + describe('the commands that set a missing variable follow the group the branch receives', () => { + const commandsFor = async (group: Group | undefined, environment = preview) => { + if (group !== undefined) state.group = group; + const result = await preflightWith( + { graph: secretGraph(), ...environment }, + { client: fakeClient(state) }, + ); + return result.findings.unset[0]?.commands; + }; + + test('production', async () => { + expect(await commandsFor(undefined, production)).toEqual([ + "prisma project env add 'STRIPE_SECRET_KEY=' --project 'proj' --role production", + ]); + }); + + test('preview', async () => { + expect(await commandsFor(undefined)).toEqual([ + "prisma project env add 'STRIPE_SECRET_KEY=' --project 'proj' --role preview", + ]); + }); + + test('a custom group is named, quoted to paste', async () => { + expect(await commandsFor({ id: 'grp-1', name: `it's "staging" x`, class: 'custom' })).toEqual( + [ + `Set STRIPE_SECRET_KEY in the variable group 'it'\\''s "staging" x' in the Prisma Console.`, + ], + ); + }); + + test('no command sets a branch override', async () => { + const all = [ + ...((await commandsFor(undefined, production)) ?? []), + ...((await commandsFor(undefined)) ?? []), + ...((await commandsFor({ id: 'grp-1', name: 'staging', class: 'custom' })) ?? []), + ]; + + expect(all).toHaveLength(3); + expect(all.join('\n')).not.toContain('--branch'); + }); }); test('sets no platform variable, even when the app secrets hold a value for a missing name', async () => { @@ -346,11 +554,11 @@ describe('the deploy check reads which variables exist and sets none', () => { ).catch(() => undefined); }); - expect(state.gets.length).toBeGreaterThan(0); + expect(state.reads.length).toBeGreaterThan(0); expect(state.posts).toEqual([]); }); - test('a required variable with no row fails in production, naming the reader and the one command', async () => { + test('a required variable with no value fails in production, naming the reader and the one command', async () => { const message = await failureOf( preflightWith({ graph: requiredSecretGraph(), ...production }, { client: fakeClient(state) }), ); @@ -363,26 +571,20 @@ describe('the deploy check reads which variables exist and sets none', () => { ); }); - test('in any other environment the preview-wide command comes first and the branch command second, quoted to paste', async () => { + test('a required variable with no value on a custom group fails, naming the group', async () => { + state.group = { id: 'grp-1', name: 'staging', class: 'custom' }; + const message = await failureOf( - preflightWith( - { - graph: requiredSecretGraph(), - container: fakeContainer('proj', 'br_1'), - environment: `it's "$HOME" x`, - }, - { client: fakeClient(state) }, - ), + preflightWith({ graph: requiredSecretGraph(), ...preview }, { client: fakeClient(state) }), ); expect(message).toEndWith( 'Set it on the platform, then deploy again:\n' + - " - prisma project env add 'STRIPE_SECRET_KEY=' --project 'proj' --role preview\n" + - ` - prisma project env add 'STRIPE_SECRET_KEY=' --project 'proj' --branch 'it'\\''s "$HOME" x'`, + " - Set STRIPE_SECRET_KEY in the variable group 'staging' in the Prisma Console.", ); }); - test('a variable with no row that nothing requires passes and is reported with its reader and commands', async () => { + test('a variable with no value that nothing requires passes and is reported with its reader and commands', async () => { const result = await preflightWith( { graph: secretGraph(), ...preview }, { client: fakeClient(state) }, @@ -395,7 +597,6 @@ describe('the deploy check reads which variables exist and sets none', () => { readers: [{ kind: 'field', service: 'app.ingest', path: 'stripeKey' }], commands: [ "prisma project env add 'STRIPE_SECRET_KEY=' --project 'proj' --role preview", - "prisma project env add 'STRIPE_SECRET_KEY=' --project 'proj' --branch 'pr-1'", ], }, ], @@ -403,19 +604,6 @@ describe('the deploy check reads which variables exist and sets none', () => { expect(result.updatedAt.size).toBe(0); }); - test('a variable with a row is not a finding', async () => { - state.rows = [ - { projectId: 'proj', class: 'production', key: 'STRIPE_SECRET_KEY', branchId: null }, - ]; - - const result = await preflightWith( - { graph: secretGraph(), ...production }, - { client: fakeClient(state) }, - ); - - expect(result.findings).toEqual({ unset: [] }); - }); - test('reports how many names it checked with its findings, and nothing when it fails', async () => { const reports: PlatformVariableCheck[] = []; const run = (graph: ReturnType) => @@ -426,9 +614,7 @@ describe('the deploy check reads which variables exist and sets none', () => { const first = await run(secretGraph()); await run(requiredSecretGraph()).catch(() => undefined); - state.rows = [ - { projectId: 'proj', class: 'production', key: 'STRIPE_SECRET_KEY', branchId: null }, - ]; + state.entries = [{ key: 'STRIPE_SECRET_KEY' }]; await run(secretGraph()); expect(first.findings.unset.map((variable) => variable.name)).toEqual(['STRIPE_SECRET_KEY']); @@ -438,110 +624,14 @@ describe('the deploy check reads which variables exist and sets none', () => { ]); }); - test('a graph with no platform variable makes no platform call and returns nothing', async () => { - const result = await preflightWith( - { graph: noSecretGraph(), ...production }, - { client: fakeClient(state) }, - ); - - expect(state.gets).toEqual([]); - expect(result).toEqual({ updatedAt: new Map(), findings: { unset: [] } }); - }); - - test('a value Composer generates needs no platform check', async () => { - await preflightWith({ graph: generatedGraph(), ...production }, { client: fakeClient(state) }); - - expect(state.gets).toEqual([]); - }); - - test('follows pagination — a present name on a later page is not reported missing', async () => { - const pages = [ - { data: [], pagination: { nextCursor: 'c1', hasMore: true } }, - { - data: [{ branchId: null, updatedAt: DEFAULT_UPDATED_AT }], - pagination: { nextCursor: null, hasMore: false }, - }, - ]; - const queries: Record[] = []; - let call = 0; - const client = { - GET: async (_path: string, init: { params: { query: Record } }) => { - queries.push(init.params.query); - return { - data: pages[call++], - error: undefined, - response: new Response(null, { status: 200 }), - }; - }, - } as unknown as ManagementApiClient; - - await preflightWith({ graph: requiredSecretGraph(), ...production }, { client }); - - expect(call).toBe(2); - expect(queries[1]?.['cursor']).toBe('c1'); - }); - - test('a failed list call fails the deploy, naming the variable', async () => { - const client = { - GET: async () => ({ - data: undefined, - error: { code: 'internal', message: 'boom' }, - response: new Response(null, { status: 500 }), - }), - } as unknown as ManagementApiClient; - - const message = await failureOf( - preflightWith({ graph: secretGraph(), ...production }, { client }), - ); - - expect(message).toBe( - 'deploy preflight: Prisma Management API error listing "STRIPE_SECRET_KEY": {"code":"internal","message":"boom"}.', - ); - }); - - test('at most eight list calls run at once', async () => { - const names = Array.from({ length: 20 }, (_, index) => `KEY_${index}`); - const graph = Load( - appRoot('app', ({ provision }) => { - provision(compute({ name: 'ingest', deps: {}, input: anySchema, build }), { - id: 'ingest', - input: Object.fromEntries( - names.map((name) => [name.toLowerCase(), provision(variable.secret({ name }))]), - ), - }); - }), - ); - let running = 0; - let most = 0; - const listed: string[] = []; - const client = { - GET: async (_path: string, init: { params: { query: Record } }) => { - running += 1; - most = Math.max(most, running); - await new Promise((resolve) => setTimeout(resolve, 2)); - running -= 1; - listed.push(init.params.query['key'] ?? ''); - return { - data: { data: [], pagination: { nextCursor: null, hasMore: false } }, - error: undefined, - response: new Response(null, { status: 200 }), - }; - }, - } as unknown as ManagementApiClient; - - await preflightWith({ graph, ...production }, { client }); - - expect(most).toBe(8); - expect(listed.sort()).toEqual([...names].sort()); - }); - - test('the same platform name bound by two services is listed once, and the finding names both readers', async () => { + test('the same platform name bound by two services is checked once, and the finding names both readers', async () => { const result = await preflightWith( { graph: sharedNestedSecretGraph(), ...production }, { client: fakeClient(state) }, ); - expect(state.gets).toHaveLength(1); + expect(state.reads).toHaveLength(1); + expect(result.findings.unset).toHaveLength(1); expect(result.findings.unset[0]?.readers).toEqual([ { kind: 'field', service: 'app.web', path: 'stripe' }, { kind: 'field', service: 'app.ingest', path: 'stripe.key' }, @@ -609,7 +699,7 @@ describe('the deploy check reads which variables exist and sets none', () => { expect(message).not.toContain('STRIPE_WEBHOOK_SECRET'); }); - test('a variable in an array position with no row is required, whatever the schema says', async () => { + test('a variable in an array position with no value is required, whatever the schema says', async () => { const graph = Load( appRoot('app', ({ provision }) => { provision(compute({ name: 'ingest', deps: {}, input: anySchema, build }), { @@ -642,49 +732,6 @@ describe('the deploy check reads which variables exist and sets none', () => { expect(message).not.toContain('platform variable a service needs'); }); - test('a row the environment sees that the platform manages itself fails, naming the variable', async () => { - state.rows = [ - { - projectId: 'proj', - class: 'preview', - key: 'STRIPE_SECRET_KEY', - branchId: null, - isManagedBySystem: true, - }, - ]; - - const message = await failureOf( - preflightWith({ graph: secretGraph(), ...preview }, { client: fakeClient(state) }), - ); - - expect(message).toContain( - '"STRIPE_SECRET_KEY" is a platform variable that Prisma Cloud manages itself', - ); - }); - - test("another branch's row that the platform manages is not seen", async () => { - state.rows = [ - { - projectId: 'proj', - class: 'preview', - key: 'STRIPE_SECRET_KEY', - branchId: 'br-2', - isManagedBySystem: true, - }, - ]; - - await preflightWith({ graph: secretGraph(), ...preview }, { client: fakeClient(state) }); - }); - - test('a literal-bound param never reaches the platform — no calls at all', async () => { - await preflightWith( - { graph: literalParamGraph(), ...production }, - { client: fakeClient(state) }, - ); - - expect(state.gets).toEqual([]); - }); - test("a secret a service receives through a module's input is named as read by the service", async () => { const mail = module( 'mail', @@ -742,129 +789,6 @@ describe('the deploy check reads which variables exist and sets none', () => { expect(JSON.stringify({ ...result, updatedAt: [...result.updatedAt] })).not.toContain(sentinel); expect(message).not.toContain(sentinel); }); - - describe('env-var listing pagination (bounded — drivePagesAsync)', () => { - test('a visible row beyond the first page still counts as present', async () => { - state.pageSize = 1; - state.rows = [ - { projectId: 'proj', class: 'preview', key: 'STRIPE_SECRET_KEY', branchId: 'br-other' }, - { projectId: 'proj', class: 'preview', key: 'STRIPE_SECRET_KEY', branchId: null }, - ]; - - await preflightWith( - { graph: requiredSecretGraph(), ...preview }, - { client: fakeClient(state) }, - ); - - expect(state.gets).toHaveLength(2); - }); - - test('a non-advancing cursor fails as broken pagination instead of looping', async () => { - state.pageSize = 1; - state.cursorStuck = true; - - await expect( - preflightWith({ graph: secretGraph(), ...production }, { client: fakeClient(state) }), - ).rejects.toThrow(/pagination appears broken.*possibly incomplete listing/); - }); - - test('pagination that never ends fails at the page cap instead of hanging', async () => { - state.pageSize = 1; - state.cursorRunaway = true; - - await expect( - preflightWith({ graph: secretGraph(), ...production }, { client: fakeClient(state) }), - ).rejects.toThrow(/did not finish within 1000 pages/); - }); - - test('more pages reported without a cursor fails instead of accepting a partial listing', async () => { - state.pageSize = 1; - state.cursorMissing = true; - - await expect( - preflightWith({ graph: secretGraph(), ...production }, { client: fakeClient(state) }), - ).rejects.toThrow(/reported more pages but returned no cursor/); - }); - }); - - describe('the rotation timestamps it hands back', () => { - const row = (branchId: string | null, updatedAt: string): Row => ({ - projectId: 'proj', - class: 'preview', - key: 'STRIPE_SECRET_KEY', - branchId, - updatedAt, - }); - const timestampsFor = async () => - ( - await preflightWith( - { - graph: secretGraph(), - container: fakeContainer('proj', 'br-1'), - environment: 'feature', - }, - { client: fakeClient(state) }, - ) - ).updatedAt; - - test('a name present on the platform reports when it was last written', async () => { - state.rows = [ - { - projectId: 'proj', - class: 'production', - key: 'STRIPE_SECRET_KEY', - branchId: null, - updatedAt: '2026-05-05T12:00:00.000Z', - }, - ]; - - const { updatedAt } = await preflightWith( - { graph: secretGraph(), ...production }, - { client: fakeClient(state) }, - ); - - expect([...updatedAt]).toEqual([['STRIPE_SECRET_KEY', '2026-05-05T12:00:00.000Z']]); - }); - - test("with a class row and this branch's row, the branch row's time is handed back", async () => { - state.rows = [row(null, '2026-05-05T12:00:00.000Z'), row('br-1', '2026-07-07T12:00:00.000Z')]; - - expect((await timestampsFor()).get('STRIPE_SECRET_KEY')).toBe('2026-07-07T12:00:00.000Z'); - }); - - test('the branch row wins even when the class row is newer', async () => { - state.rows = [row(null, '2026-08-08T12:00:00.000Z'), row('br-1', '2026-07-07T12:00:00.000Z')]; - - expect((await timestampsFor()).get('STRIPE_SECRET_KEY')).toBe('2026-07-07T12:00:00.000Z'); - }); - - test('a newer class row under a branch row changes nothing', async () => { - state.rows = [row(null, '2026-05-05T12:00:00.000Z'), row('br-1', '2026-07-07T12:00:00.000Z')]; - const before = await timestampsFor(); - state.rows = [row(null, '2026-09-09T12:00:00.000Z'), row('br-1', '2026-07-07T12:00:00.000Z')]; - - expect(await timestampsFor()).toEqual(before); - }); - - test('with no branch row, the class row is handed back', async () => { - state.rows = [row(null, '2026-05-05T12:00:00.000Z')]; - - expect((await timestampsFor()).get('STRIPE_SECRET_KEY')).toBe('2026-05-05T12:00:00.000Z'); - }); - - test('a row belonging to ANOTHER branch is not in scope and does not date this one', async () => { - state.rows = [ - row(null, '2026-05-05T12:00:00.000Z'), - row('br-other', '2026-09-09T12:00:00.000Z'), - ]; - - expect((await timestampsFor()).get('STRIPE_SECRET_KEY')).toBe('2026-05-05T12:00:00.000Z'); - }); - - test('a name with no row has no time', async () => { - expect((await timestampsFor()).has('STRIPE_SECRET_KEY')).toBe(false); - }); - }); }); describe('runPreflight — a COMPOSER_ key that changes owner in the move to full addresses (ADR-0057)', () => { @@ -889,7 +813,7 @@ describe('runPreflight — a COMPOSER_ key that changes owner in the move to ful let state: FakeState; beforeEach(() => { - state = { gets: [], posts: [], rows: [] }; + state = emptyState(); }); const preflight = () => @@ -929,8 +853,11 @@ describe('runPreflight — a COMPOSER_ key that changes owner in the move to ful expect(String(error)).toContain(`--branch 'it'\\''s "$HOME" x'`); }); - test('passes once that variable is deleted', async () => { + test('passes once that variable is deleted, and an app with no platform variable reads none', async () => { await preflight(); + + expect(state.gets.length).toBeGreaterThan(0); + expect(state.reads).toEqual([]); }); test("passes after the move, when the old owner's row has its new key", async () => { @@ -984,8 +911,7 @@ describe('runPreflight — a chain of COMPOSER_ keys that change owner', () => { test('reports every link in one run', async () => { const state: FakeState = { - gets: [], - posts: [], + ...emptyState(), rows: [row('COMPOSER_SHOP_X_ORIGIN'), row('COMPOSER_SHOP_SHOP_X_ORIGIN')], }; @@ -997,8 +923,7 @@ describe('runPreflight — a chain of COMPOSER_ keys that change owner', () => { test('passes once every node has moved', async () => { const state: FakeState = { - gets: [], - posts: [], + ...emptyState(), rows: [ row('COMPOSER_SHOP_X_ORIGIN'), row('COMPOSER_SHOP_SHOP_X_ORIGIN'), @@ -1023,10 +948,7 @@ describe('preflight names', () => { expect( await failureOf( - preflightWith( - { graph, ...production }, - { client: fakeClient({ gets: [], posts: [], rows: [] }) }, - ), + preflightWith({ graph, ...production }, { client: fakeClient(emptyState()) }), ), ).toBe( 'input key "stripe.key" of service "app.web" is bound to a source that is not a platform variable. Provision variable() or variable.secret() from @prisma/composer-prisma-cloud in the app root and pass its value down.', @@ -1046,7 +968,7 @@ describe('the deploy check of platform variable nodes', () => { let state: FakeState; beforeEach(() => { - state = { gets: [], posts: [], rows: [] }; + state = emptyState(); }); const commands = (name: string) => [ @@ -1065,7 +987,7 @@ describe('the deploy check of platform variable nodes', () => { ); test('a required unset plain node fails the deploy, naming it and its reader', async () => { - state.rows = [{ projectId: 'proj', class: 'production', key: 'EMAIL_KEY', branchId: null }]; + state.entries = [{ key: 'EMAIL_KEY' }]; const message = await failureOf( preflightWith( @@ -1079,7 +1001,7 @@ describe('the deploy check of platform variable nodes', () => { }); test('a required unset secret node fails the deploy', async () => { - state.rows = [{ projectId: 'proj', class: 'production', key: 'EMAIL_FROM', branchId: null }]; + state.entries = [{ key: 'EMAIL_FROM' }]; const message = await failureOf( preflightWith( @@ -1111,11 +1033,8 @@ describe('the deploy check of platform variable nodes', () => { ]); }); - test('a node with a row passes and its row time is handed back', async () => { - state.rows = [ - { projectId: 'proj', class: 'production', key: 'EMAIL_FROM', branchId: null }, - { projectId: 'proj', class: 'production', key: 'EMAIL_KEY', branchId: null }, - ]; + test('a node the branch receives passes and its time is handed back', async () => { + state.entries = [{ key: 'EMAIL_FROM' }, { key: 'EMAIL_KEY' }]; const result = await preflightWith( { graph: mailGraph(requiresSecrets('key')), ...production }, @@ -1237,12 +1156,8 @@ describe('the deploy check of platform variable nodes', () => { }); describe("preflight identifies Composer on the caller's client", () => { - test("every environment-variable lookup through the caller's client carries Composer's headers", async () => { - const state: FakeState = { - gets: [], - posts: [], - rows: [{ projectId: 'proj', class: 'production', key: 'STRIPE_SECRET_KEY', branchId: null }], - }; + test("the read of the branch's variables through the caller's client carries Composer's headers", async () => { + const state: FakeState = { ...emptyState(), entries: [{ key: 'STRIPE_SECRET_KEY' }] }; const headersSeen: unknown[] = []; const fake = fakeClient(state); const caller = { @@ -1262,7 +1177,8 @@ describe("preflight identifies Composer on the caller's client", () => { credentials: { workspaceId: undefined, client: caller }, }); - expect(headersSeen.length).toBeGreaterThan(0); + expect(state.reads).toHaveLength(1); + expect(headersSeen).toHaveLength(1); for (const headers of headersSeen) { expect(headers).toMatchObject({ 'x-prisma-client-name': 'composer', diff --git a/packages/1-prisma-cloud/1-extensions/target/src/map-with-concurrency.ts b/packages/1-prisma-cloud/1-extensions/target/src/map-with-concurrency.ts deleted file mode 100644 index e39afa370..000000000 --- a/packages/1-prisma-cloud/1-extensions/target/src/map-with-concurrency.ts +++ /dev/null @@ -1,22 +0,0 @@ -export async function mapWithConcurrency( - items: readonly T[], - limit: number, - task: (item: T) => Promise, -): Promise { - const results: R[] = []; - const queue = items.entries(); - let failed = false; - const worker = async (): Promise => { - for (const [index, item] of queue) { - if (failed) return; - try { - results[index] = await task(item); - } catch (cause) { - failed = true; - throw cause; - } - } - }; - await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker)); - return results; -} diff --git a/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts b/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts index 50cce3c70..34a84669d 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts @@ -14,12 +14,12 @@ import { ManagementClient, managementClientLayer, } from '@internal/lowering'; +import { type } from 'arktype'; import * as Effect from 'effect/Effect'; import * as Layer from 'effect/Layer'; -import { prismaCloudContainerOf } from './container.ts'; +import { type PrismaCloudContainer, prismaCloudContainerOf } from './container.ts'; import type { DeployPreflightPayload } from './control/preflight-payload.ts'; import { type EnvKeyClash, findEnvKeyClashes } from './env-key-clash.ts'; -import { mapWithConcurrency } from './map-with-concurrency.ts'; import { addReader, missingVariableNames, missingVariablesText } from './missing-variables-text.ts'; import { resolveOrmConfig } from './orm-config.ts'; import { isPostgresResourceNode, requiredPackHeadOf } from './orm-postgres.ts'; @@ -35,11 +35,7 @@ const classFor = (branchId: string | undefined): EnvClass => /** The fields of one env-var list page that preflight consumes (metadata only; values are write-only). */ interface EnvVarListPage { - readonly data: readonly { - readonly branchId: string | null; - readonly updatedAt: string; - readonly isManagedBySystem?: boolean; - }[]; + readonly data: readonly { readonly branchId: string | null }[]; readonly pagination: { readonly nextCursor: string | null; readonly hasMore: boolean }; } interface EnvVarListResult { @@ -71,48 +67,61 @@ async function listEnvVars( >(res); } -interface ResolvedRow { - readonly updatedAt?: string; - readonly managedBySystem: boolean; +const RESOLVED_VARIABLES_PATH = '/v1/projects/{projectId}/resolved-variables'; + +/** The fields of the resolved-variables read that preflight uses: names and times, never values. */ +const resolvedVariablesBody = type({ + group: { name: 'string', class: 'string' }, + data: type({ key: 'string', updatedAt: 'string', isManagedBySystem: 'boolean' }).array(), +}); +type ResolvedVariables = typeof resolvedVariablesBody.infer; +type VariableGroup = ResolvedVariables['group']; + +interface ResolvedVariablesClient { + GET( + path: typeof RESOLVED_VARIABLES_PATH, + init: { params: { path: { projectId: string }; query: { branchId: string } } }, + ): Promise<{ readonly data?: unknown; readonly error?: unknown; readonly response: Response }>; } -const LIST_CONCURRENCY = 8; +const PAGINATION_FIELDS = ['pagination', 'nextCursor', 'hasMore', 'cursor']; + +const isRecord = (value: unknown): value is Record => + typeof value === 'object' && value !== null; -async function readPlatformVariable( +async function readResolvedVariables( client: ManagementApiClient, projectId: string, - branchId: string | undefined, - key: string, -): Promise { - const cls = classFor(branchId); - let classRow: string | undefined; - let branchRow: string | undefined; - let managedBySystem = false; - await drivePagesAsync( - `environment variables named "${key}"`, - async (cursor) => { - const res = await listEnvVars( - client, - cursor === undefined - ? { projectId, class: cls, key } - : { projectId, class: cls, key, cursor }, - ); - if (res.error !== undefined) throw listFailedError(key, res.error); - return res.data ?? { data: [], pagination: { nextCursor: null, hasMore: false } }; - }, - (data) => { - for (const row of data) { - if (row.branchId === null) classRow = row.updatedAt; - else if (branchId !== undefined && row.branchId === branchId) branchRow = row.updatedAt; - else continue; - managedBySystem ||= row.isManagedBySystem === true; - } - return false; - }, - ); - const updatedAt = branchRow ?? classRow; - if (updatedAt === undefined) return undefined; - return { updatedAt, managedBySystem }; + branchId: string, +): Promise { + const call = `GET /v1/projects/${projectId}/resolved-variables?branchId=${branchId}`; + const res = await blindCast< + ResolvedVariablesClient, + 'the published Management API SDK does not describe the resolved-variables read yet; its body is checked below' + >(client).GET(RESOLVED_VARIABLES_PATH, { + params: { path: { projectId }, query: { branchId } }, + }); + if (res.error !== undefined || !res.response.ok) { + throw resolvedReadFailedError(call, res.response.status, res.error); + } + const body = res.data; + if (isRecord(body) && PAGINATION_FIELDS.some((field) => field in body)) { + throw pagedReadError(call); + } + const parsed = resolvedVariablesBody(body); + if (parsed instanceof type.errors) throw unexpectedReadError(call, parsed.summary); + return parsed; +} + +/** The branch whose variables the environment receives: its own, or the project's default branch for production. */ +function deployBranchIdOf(container: PrismaCloudContainer): string { + const branchId = container.branchId ?? container.defaultBranchId; + if (branchId === undefined) { + throw new Error( + `deploy preflight: the container for the environment "${container.input.environment}" has no branch id. This is a bug in Composer.`, + ); + } + return branchId; } /** Whether `key` has a row in the scope Composer writes its own rows to: production, or the environment's branch. */ @@ -194,19 +203,38 @@ const listFailedError = (key: string, error: unknown): Error => `deploy preflight: Prisma Management API error listing "${key}": ${JSON.stringify(error)}.`, ); +const MAY_NOT_OFFER_READ = + 'The platform may not offer this read yet, and this Composer version needs it to check platform variables.'; + +const resolvedReadFailedError = (call: string, status: number, error: unknown): Error => + new Error( + `Deploy failed. ${call} answered HTTP ${String(status)}` + + `${error === undefined ? '' : `: ${JSON.stringify(error)}`}. ${MAY_NOT_OFFER_READ}`, + ); + +const unexpectedReadError = (call: string, problem: string): Error => + new Error( + `Deploy failed. ${call} answered with a body this Composer version cannot read: ${problem}. ${MAY_NOT_OFFER_READ}`, + ); + +const pagedReadError = (call: string): Error => + new Error( + `Deploy failed. ${call} answered with one page of a longer list. This Composer version reads only one page, so it would report set variables as missing. It is too old for the platform: upgrade Composer and deploy again.`, + ); + /** `value` as one POSIX shell word: single-quoted, each embedded `'` written as `'\''`. */ const shellQuote = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`; -function setCommands( - name: string, - projectId: string, - branchId: string | undefined, - environment: string, -): readonly string[] { +function setCommands(name: string, projectId: string, group: VariableGroup): readonly string[] { const add = `prisma project env add ${shellQuote(`${name}=`)} --project ${shellQuote(projectId)}`; - return branchId === undefined - ? [`${add} --role production`] - : [`${add} --role preview`, `${add} --branch ${shellQuote(environment)}`]; + switch (group.class) { + case 'production': + return [`${add} --role production`]; + case 'preview': + return [`${add} --role preview`]; + default: + return [`Set ${name} in the variable group ${shellQuote(group.name)} in the Prisma Console.`]; + } } function requiredError( @@ -283,7 +311,8 @@ export async function runPreflight( deps?: { readonly client?: ManagementApiClient }, ): Promise { checkPublicUrls(input.graph); - const { projectId, branchId } = prismaCloudContainerOf(input.container); + const container = prismaCloudContainerOf(input.container); + const { projectId, branchId } = container; const services = inputManifest(input.graph).map(({ serviceAddress, binding }) => ({ serviceAddress, @@ -307,21 +336,25 @@ export async function runPreflight( const pending = await pendingEnvKeyClashes(client, projectId, branchId, clashes); if (pending.length > 0) throw envKeyClashError(pending, projectId, branchId, input.environment); - const rows = await mapWithConcurrency(names, LIST_CONCURRENCY, (name) => - readPlatformVariable(client, projectId, branchId, name), - ); + if (names.length === 0) { + input.report?.({ checked: 0, unset: [] }); + return { updatedAt: new Map() }; + } + + const resolved = await readResolvedVariables(client, projectId, deployBranchIdOf(container)); + const entries = new Map(resolved.data.map((entry) => [entry.key, entry])); const updatedAt = new Map(); const unset = new Set(); const managedBySystem: string[] = []; - names.forEach((name, index) => { - const row = rows[index]; - if (row?.updatedAt === undefined) { + for (const name of names) { + const entry = entries.get(name); + if (entry === undefined) { unset.add(name); - return; + continue; } - updatedAt.set(name, row.updatedAt); - if (row.managedBySystem) managedBySystem.push(name); - }); + updatedAt.set(name, entry.updatedAt); + if (entry.isManagedBySystem) managedBySystem.push(name); + } if (managedBySystem.length > 0) throw managedBySystemError(managedBySystem); if (unset.size === 0) { input.report?.({ checked: names.length, unset: [] }); @@ -350,7 +383,7 @@ export async function runPreflight( if (unset.has(use.name)) addReader(readers, use.name, use.reader); } - const commandsFor = (name: string) => setCommands(name, projectId, branchId, input.environment); + const commandsFor = (name: string) => setCommands(name, projectId, resolved.group); if (required.length > 0) throw requiredError(required, readers, commandsFor); const findings: UnsetPlatformVariable[] = [...unset].sort().map((name) => ({ name, From a3d4e3ab30391b0d6617380fb9b4a9a6058e56e8 Mon Sep 17 00:00:00 2001 From: willbot Date: Fri, 20 Nov 2026 22:25:44 +1100 Subject: [PATCH 2/6] docs: a platform variable is set in the variable group the environment's branch receives The guides, the skill and the decision on platform variables now describe variable groups: each branch receives one group, the deploy reads once what the branch receives, and the hint for a missing variable follows the group's class. The command that writes a branch override is no longer suggested, and the guide says the deploy does not see a value set on one service in Console. The glossary gains variable group and service variable. Co-Authored-By: Claude Fable 5.2 Signed-off-by: willbot Signed-off-by: Will Madden --- docs/design/03-domain-model/glossary.md | 12 +++- docs/design/05-prisma-cloud/pdp-data-model.md | 14 ++++- docs/design/10-domains/config-params.md | 4 +- docs/design/10-domains/deploy-cli.md | 3 +- ...t-and-the-deploy-copies-no-local-values.md | 55 +++++++++++-------- docs/design/90-decisions/README.md | 2 +- docs/guides/building-an-app.md | 2 +- docs/guides/deploying.md | 17 +++--- skills/prisma-composer-core-concepts/SKILL.md | 2 +- 9 files changed, 70 insertions(+), 41 deletions(-) diff --git a/docs/design/03-domain-model/glossary.md b/docs/design/03-domain-model/glossary.md index 01ae2ce7b..2f64d33e5 100644 --- a/docs/design/03-domain-model/glossary.md +++ b/docs/design/03-domain-model/glossary.md @@ -170,7 +170,7 @@ A pointer is typed by its source. `serviceOrigin()` and a plain `generatedParam( ### Platform variable -A variable on the platform that a service reads by name at boot. The app declares each one with a [platform variable node](#platform-variable-node) in its root, so every message can name the node. The service reads it through a field of its `input`. "Plain platform variable" means the non-secret kind; the secret kind is a [platform secret](#platform-secret). A deploy does not copy its value from the developer's local environment and does not read it: the platform hands it to the running service. For now the operator sets it with `prisma project env add`. Under `prisma dev`, the local target plays the platform's part: it reads a plain platform variable's value from the app configuration and a platform secret's from the app secrets, and hands it to the local service. A variable has a class row (production or preview) and, on a preview environment, may have a branch row for one branch; the branch row wins ([ADR-0064](../90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). Composer's own `COMPOSER_` rows are [variables on the platform](#a-variable-on-the-platform) but not platform variables, because the app does not declare them. In code: `PlatformVariableReader`, `UnsetPlatformVariable`, `PlatformVariableCheck`. +A variable on the platform that a service reads by name at boot. The app declares each one with a [platform variable node](#platform-variable-node) in its root, so every message can name the node. The service reads it through a field of its `input`. "Plain platform variable" means the non-secret kind; the secret kind is a [platform secret](#platform-secret). A deploy does not copy its value from the developer's local environment and does not read it: the platform hands it to the running service. For now the operator sets it on Prisma Cloud, in the [variable group](#variable-group) the environment's branch receives. Under `prisma dev`, the local target plays the platform's part: it reads a plain platform variable's value from the app configuration and a platform secret's from the app secrets, and hands it to the local service. A service receives the value of its branch's group, under that branch's override row if it has one, under a [service variable](#service-variable) if its service has one; deploy preflight checks the group and the override, not the service variable ([ADR-0064](../90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). Composer's own `COMPOSER_` rows are [variables on the platform](#a-variable-on-the-platform) but not platform variables, because the app does not declare them. In code: `PlatformVariableReader`, `UnsetPlatformVariable`, `PlatformVariableCheck`. ### Platform variable node @@ -194,7 +194,15 @@ A [platform variable](#platform-variable) whose value is handled as a secret: bo ### A variable on the platform -Any entry, or **row**, in a Prisma Cloud project's environment variables: a name and a non-empty text, at a class and optionally a branch. That includes Composer's own `COMPOSER_` rows, which are not [platform variables](#platform-variable). The term names the platform's storage, as distinct from what the app reads. Prisma Cloud calls these rows environment variables. +Any entry, or **row**, in a Prisma Cloud project's environment variables: a name and a non-empty text. A **group row** belongs to a [variable group](#variable-group); what was called a class row is a row of the `production` or `preview` group. A **branch row** is one branch's override, which the platform is removing. That includes Composer's own `COMPOSER_` rows, which are not [platform variables](#platform-variable). The term names the platform's storage, as distinct from what the app reads. Prisma Cloud calls these rows environment variables. + +### Variable group + +Prisma Cloud's term for a named set of [variables on the platform](#a-variable-on-the-platform) in one project. Every project has a `production` group and a `preview` group; it can add custom groups, each with one rule on a branch's git name (`equals` or `startsWith`). Each branch receives exactly one group: the production branch receives `production`, any other branch the custom group with the most precise matching rule, or else `preview`. Groups do not combine. A group's class is `production`, `preview` or `custom`. This is the platform's planned model and not yet live. + +### Service variable + +Prisma Cloud's term for a value stored on one service, set through the create-deployment request or Console, and deleted with the service. It wins over the branch's group and override. Composer does not read or write one yet. This is the platform's planned model and not yet live. ### Value resource diff --git a/docs/design/05-prisma-cloud/pdp-data-model.md b/docs/design/05-prisma-cloud/pdp-data-model.md index b324f2487..422745566 100644 --- a/docs/design/05-prisma-cloud/pdp-data-model.md +++ b/docs/design/05-prisma-cloud/pdp-data-model.md @@ -106,7 +106,19 @@ Consequences Prisma Composer designs around: templates vs preview templates + per-branch overrides) — the substrate [an environment as a Branch](../10-domains/deploy-cli.md#environments-and-containers) is built on: an environment other than `production` is a Branch, and its config is written - preview-class with that Branch's overrides. + preview-class with that Branch's overrides. Under variable groups (below), a Branch + receives one group in place of a class. + +## Variable groups — the platform's planned model + +Prisma Cloud is moving variables into groups. This is designed in `projects/compute-env-var-groups/proposal.md` on the `pdp-control-plane` branch `chore/compute-env-var-groups-proposal`, and is not live yet. What Composer depends on: + +- **Variable groups.** Every project has a `production` group and a `preview` group, holding the rows the two classes hold today. A project can add custom groups, each with one rule on a branch's git name: `equals` or `startsWith`. +- **One group per branch.** The production branch receives `production`. Any other branch receives the custom group with the most precise matching rule, or else `preview`. Groups do not combine. +- **Service variables.** Values stored on one service, set only through the create-deployment request, deleted with the service. +- **The order a deployment receives values:** every value of its branch's group, then the branch's overrides, then the service's variables. Later wins. The map is still frozen into the version when it is created. +- **Branch overrides are being removed.** Three months after the platform work merges, a write that names a branch is rejected. Existing override rows keep applying until their branch is deleted. +- **The resolved-variables read.** `GET /v1/projects/{projectId}/resolved-variables?branchId=…` returns the group the branch receives (`id`, `name`, `class`) and every key the branch receives, each with `updatedAt`, `isManagedBySystem` and a `source` (`group`, `branchOverride` or `service`). It returns no values and does not paginate. Deploy preflight reads it once per deploy ([ADR-0064](../90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). ## Related diff --git a/docs/design/10-domains/config-params.md b/docs/design/10-domains/config-params.md index 1ffcfbc39..44d038cc3 100644 --- a/docs/design/10-domains/config-params.md +++ b/docs/design/10-domains/config-params.md @@ -123,8 +123,8 @@ signingKey.expose(); // the one door to the value The round trip carries only the name, never the value: 1. **Bind.** The app root provisions a platform secret node and binds its value, and each module on the way passes it on as a field of its input. Load records each service's input binding and each read in `valueReads`, and preflight collects every platform secret, also one no service reads. -2. **Set.** The operator sets the variable on the platform with `prisma project env add`, for production, for every preview environment, or for one. The deploy does not copy a value from the app secrets to the platform. -3. **Preflight.** Before Alchemy runs, the deploy checks whether each name has a row the environment sees, and writes none. A missing name that a service's schema requires fails the deploy, with its readers and the command that sets it; a missing name nothing requires is listed and the deploy goes on. +2. **Set.** The operator sets the variable on the platform in the variable group the environment's branch receives. The deploy does not copy a value from the app secrets to the platform. +3. **Preflight.** Before Alchemy runs, the deploy reads once which keys the environment's branch receives, checks each name against that list, and writes none. A missing name that a service's schema requires fails the deploy, with its readers and the command that sets it; a missing name nothing requires is listed and the deploy goes on. 4. **Marker.** The target writes the service's input document with a marker in place of each secret field, naming the variable, not its value: ```json { "signingKey": { "$platform": { "name": "AUTH_SIGNING_KEY", "secret": true } } } diff --git a/docs/design/10-domains/deploy-cli.md b/docs/design/10-domains/deploy-cli.md index fddc341dc..8e41bfd8d 100644 --- a/docs/design/10-domains/deploy-cli.md +++ b/docs/design/10-domains/deploy-cli.md @@ -277,7 +277,8 @@ them: | Missing extension env | the exact variable(s) the extension factory needed | | Built output missing | the expected path, and "run your build" | | An extension's graph check refuses the graph (`COMPOSE.GRAPH_INVALID`) | the extension's message: for Prisma Cloud, a platform variable declared by two nodes, a name used by both a plain platform variable node and a root input field, or a node bound as a service's whole input, naming the variable and every address involved | -| A platform variable a service needs has no value (`DEPLOY.PREFLIGHT_FAILED`) | each variable, the service and field that reads it, and the `prisma project env add` commands: `--role production` for production, otherwise `--role preview` then `--branch` | +| A platform variable a service needs has no value (`DEPLOY.PREFLIGHT_FAILED`) | each variable, the service and field that reads it, and what sets it, by the class of the group the branch receives: `prisma project env add … --role production` or `--role preview`, or for a custom group a sentence naming the group and the Prisma Console | +| The read of the branch's variables fails or is paged (`DEPLOY.PREFLIGHT_FAILED`) | the call, the HTTP status, the project and branch ids, and that the platform may not offer the read yet; for a paged answer, that this Composer version is too old for the platform | | A platform variable the app reads is managed by Prisma Cloud (`DEPLOY.PREFLIGHT_FAILED`) | the variable, and to rename it in the app | | Root's input refused by its schema | the schema's messages, and that a root's input is the app configuration for the environment | | A config adapter throws or returns something other than an object (`CONFIG.ADAPTER_FAILED`, `CONFIG.ADAPTER_INVALID`) | which list and position, and the fix | diff --git a/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md b/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md index ae92b8c41..0b3ad3596 100644 --- a/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md +++ b/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md @@ -22,14 +22,13 @@ $ prisma deploy --environment staging Platform variables with no value: - EMAIL_API_KEY (read by service "shop.email", field "apiKey") prisma project env add 'EMAIL_API_KEY=' --project 'proj_…' --role preview - prisma project env add 'EMAIL_API_KEY=' --project 'proj_…' --branch 'staging' ``` ## Decision A **platform variable** is a variable on the platform that a service reads by name at boot. The app declares each one with a **platform variable node** in its root: `variable({ name })` for a plain value, `variable.secret({ name })` for a **platform secret**, both from `@prisma/composer-prisma-cloud`. A plain variable may also declare what its text holds: `variable({ name, schema })` takes a schema from any library that implements [Standard JSON Schema](https://standardschema.dev/json-schema), such as ArkType or Zod. The value is then typed by the schema, and boot decodes the text and validates it against the schema's JSON Schema before the service's own schema sees it. `provision()` returns the value, and the root passes it down through module inputs to the services that read it. The loaded graph lists every node and, for each service, the variables it reads, without deploying. -The deploy does not copy a platform variable's value from the developer's local environment: the `secrets` and `config` adapters, by default `.env` files and the shell. An implicit copy can push a local value into a remote environment by accident. For now the operator sets each value on Prisma Cloud with `prisma project env add`, and the deploy creates, changes and deletes no platform variable. Preflight checks only that every variable a service needs has a value. This is not a rule that the deploy may never set a variable. An explicit way to set variables through `deploy`, where the operator says which values go to which environment, is expected later (see Future work). +The deploy does not copy a platform variable's value from the developer's local environment: the `secrets` and `config` adapters, by default `.env` files and the shell. An implicit copy can push a local value into a remote environment by accident. For now the operator sets each value on Prisma Cloud, in the variable group the environment's branch receives, and the deploy creates, changes and deletes no platform variable. Preflight checks only that every variable a service needs has a value. This is not a rule that the deploy may never set a variable. An explicit way to set variables through `deploy`, where the operator says which values go to which environment, is expected later (see Future work). Destroying the production environment removes the Project, and with it every variable on the platform set on it. Composer records which service reads which variable, checks at deploy that every variable a service needs has a value, lists the ones with none, and reads the value only inside the running service. The rows Composer does write are its own: the `COMPOSER_…` rows of each service. Those are variables on the platform, not platform variables: an app cannot declare a platform variable with a `COMPOSER_` name. @@ -44,16 +43,20 @@ The environment's facts, such as `environment.name`, and the values Composer cre ### What Prisma Cloud does -- **A variable is a row in a project.** A row has `projectId`, `class` (`production` or `preview`), an optional `branchId`, a `key` and a `value`. A row with no `branchId` is the class's shared value. A row with one is that preview branch's override. Prisma Cloud calls these rows environment variables. -- **A deployment receives the rows of its class, with its branch's overrides on top.** A **scope** is a level at which a row can be set and at which a reader looks it up. Today there are two: the class and the branch. When a name has a row at both, the more local one, the branch row, wins. The platform copies the rows into the deployment when it creates it and never reads them again, so a value set later reaches a service only at its next deployment. There is no service scope: every deployment receives every row of its class, its own and other services' alike. The list filter accepts only `projectId`, `class`, `key` and `branchId`. +- **A variable is a row in a project.** A row has a `key` and a `value`, and belongs either to a **variable group** or to one branch, as that branch's override. Prisma Cloud calls these rows environment variables. +- **Variable groups.** Every project has a `production` group and a `preview` group, which hold what the `production` and `preview` classes held before groups. A project can add custom groups, each with one rule on a branch's git name. A group's class is `production`, `preview` or `custom`. +- **A branch receives exactly one group.** The production branch receives `production`. Any other branch receives the custom group whose rule matches its name most precisely, or else `preview`. Groups do not combine: a branch on a group named `staging` receives nothing from `preview`. +- **The order of values.** A deployment receives every value of its branch's group, then that branch's overrides, then the **service variables** stored on its service, which Console sets. Later wins. The platform copies the values into the deployment when it creates it and never reads them again, so a value set later reaches a service only at its next deployment. A group or an override reaches every service on the branch, its own and other services' alike. +- **Branch overrides are being removed.** Three months after the platform work merges, it rejects a write that names a branch. Existing overrides keep applying until their branch is deleted. +- **One read answers what a branch receives.** `GET /v1/projects/{projectId}/resolved-variables?branchId=…` returns the group the branch receives and every key the branch receives, each with `updatedAt`, `isManagedBySystem` and a `source`. It returns no values and does not paginate. - **A key is upper case or it does not exist.** The platform refuses a key that does not match `[A-Z_][A-Z0-9_]*`, on write and in the list filter. - **A value is never empty.** The platform refuses an empty value, so a variable is either present with text or absent. -- **A read returns metadata, never a value.** It returns `updatedAt`, and `isManagedBySystem` for a row the platform owns. -- **The operator sets a row with the `prisma` CLI.** `prisma project env add 'NAME=' --project --role production` sets the production row. `--role preview` sets the preview-wide row that every preview branch shares. `--branch ` sets one branch's override. `update`, `list` and `delete` take the same scopes. +- **A read returns metadata, never a value.** It returns `updatedAt`, and `isManagedBySystem` for a key the platform owns. +- **The operator sets a value with the `prisma` CLI or in Console.** `prisma project env add 'NAME=' --project --role production` sets it in the `production` group, and `--role preview` in the `preview` group. A custom group is set in Console. `update`, `list` and `delete` take the same flags. - **A process that exits at boot is reported running.** The deployment is started and promoted as soon as it is created. The platform reports it `running`, `prisma deploy` succeeds, and the crashing deployment is promoted. The other services in the same deploy are promoted as usual. The platform does not restart the process on its own: each request to the service boots it once and gets a 502. The boot error is only in the logs: `prisma service logs --project `, or `GET /v1/deployments/{id}/logs?from_start=true` in the Management API. - **A deployment read lists the names it received.** `GET /v1/deployments/{id}` returns `envVars`, the names of the variables on that deployment with their values redacted. It shows what a deployment received without reading its logs. -- **Variables belong to a project.** There are no workspace-wide variables: every row belongs to one project. -- **The environment-variable endpoints are experimental.** The Management API SDK marks every one of them so. For platform variables, a change to these endpoints is a change to preflight, the only part of Composer that reads them. Composer's own `COMPOSER_…` rows are written through them too. +- **Variables belong to a project.** There are no workspace-wide variables: every row and every group belongs to one project. +- **The variable endpoints are experimental.** The Management API marks the environment-variable endpoints and the resolved-variables read so. For platform variables, a change to the read is a change to preflight, the only part of Composer that reads it. Composer's own `COMPOSER_…` rows are written through the environment-variable endpoints. ### The node @@ -214,10 +217,12 @@ The validator must be present wherever `@internal/input-document` runs at boot. Preflight runs after the deploy has resolved the app's Project and Branch, and before Alchemy runs. It writes no variable and reads no value. - **The names it checks.** Every platform variable, plain or secret, in a service's input binding, at any depth, found from the same walk of each binding, without serializing the service; and every platform variable node no service reads, which are the value resources not in `graph.valueReads`. An invalid input still fails after preflight reports the platform variables. The deploy preflight reads nothing from the app configuration. -- **One list call per name.** The call is filtered by `projectId`, `class` and `key`, and walks every page. The class is `production` for the environment `production` and `preview` for every other. The environment sees the class row, and for a preview environment its own branch's row. At most eight calls run at once. A failed call fails the deploy, because the deployment triggers need each row's `updatedAt`. -- **The row the platform resolves.** The branch row wins when there is one, otherwise the class row. Preflight keeps that row's `updatedAt`. A change to a class row under a branch override changes nothing the service receives, so it triggers nothing. -- **A system row is refused.** A row the environment sees with `isManagedBySystem: true` fails the deploy, naming the variable. -- **Required or reported, per service.** For each service that reads a variable with no row, preflight serialises the input with every variable present and runs the service's schema. A failure there is an invalid input, reported as such and never blamed on a variable. Then it runs the schema with every variable that has no row left out. If that passes, those variables are optional for that service. If it fails, it leaves out each one alone, and the ones whose absence alone fails are required. When no single one fails alone, the error says the service needs at least one of them. A variable an array position reads is required without a check. This is the method [ADR-0058](ADR-0058-prisma-dev-reads-secrets-from-the-app-secrets-and-never-invents-them.md) gives the dev preflight, and both preflights call the same code. +- **One read per deploy.** When the app names at least one platform variable, preflight makes one resolved-variables read for the environment's branch: the environment's own branch, or for `production` the project's default branch, whose id the deploy already holds. An app that names none makes no call. A name is present when the read lists its key. Its `updatedAt` is the trigger value. The entry's `source` is not consulted: a group value and a branch override both reach every service on the branch. +- **A failed read fails the deploy.** A 404 for the project or the branch, or any other error, stops the deploy with a message that names the call, the HTTP status, the project and the branch, and says the platform may not offer this read yet. There is no fallback to a per-name lookup, because that lookup gives wrong answers on a custom group. +- **A paged answer fails the deploy.** An answer that carries a pagination field or a cursor stops the deploy with a message that says this Composer version is too old for the platform. A version that read only the first page would report the rest missing, and older lines get no patch releases. +- **A system key is refused.** A listed key with `isManagedBySystem: true` fails the deploy, naming the variable. +- **A value set on one service is not seen.** Preflight asks about the branch, not about each service. A variable a service requires that is set only as that service's service variable fails the deploy as missing, and the hint says to set it in the group. A deployment that Console creates with "Save and Deploy" is replaced as live by the next `prisma deploy`. This gap is known and left open. +- **Required or reported, per service.** For each service that reads a variable with no value, preflight serialises the input with every variable present and runs the service's schema. A failure there is an invalid input, reported as such and never blamed on a variable. Then it runs the schema with every variable that has no value left out. If that passes, those variables are optional for that service. If it fails, it leaves out each one alone, and the ones whose absence alone fails are required. When no single one fails alone, the error says the service needs at least one of them. A variable an array position reads is required without a check. This is the method [ADR-0058](ADR-0058-prisma-dev-reads-secrets-from-the-app-secrets-and-never-invents-them.md) gives the dev preflight, and both preflights call the same code. - **A node no service reads** has no reader to need it. It is reported once, named by its node, `named by resource "shop.emailFrom", read by no service`, and never required. That includes a secret node that a module receives and no service reads. - **A required variable fails the deploy** with `DEPLOY.PREFLIGHT_FAILED`, before Alchemy runs: @@ -227,12 +232,11 @@ Preflight runs after the deploy has resolved the app's Project and Branch, and b Set it on the platform, then deploy again: - prisma project env add 'EMAIL_API_KEY=' --project 'proj_…' --role preview - - prisma project env add 'EMAIL_API_KEY=' --project 'proj_…' --branch 'staging' ``` - For production the one command is `--role production`. For every other environment the preview-wide command comes first, so the next preview branch is not missing it too, and the branch command second. A variable that an array position makes required has a second line with the reason, and a line for a service that needs some of several variables ends with the schema's message. -- **The findings.** Every variable with no row that nothing requires is listed, with its readers (a service and field, or the node that names it and that no service reads it) and the commands that set it. `PreflightInput.report` takes a `PlatformVariableCheck`: the count of platform variables checked and this list, names and readers only, never a value. It carries platform-variable findings and that count, nothing else. The deploy prints the list right after the preflight step, under `Platform variables with no value:`. With `--json` it is a message whose data holds the list, and `onEvent` receives it as a `preflight-findings` event. The step's data stays `{ checked, unset }`, two counts. The deploy hands the list to `lower()` as a value, `LowerOptions.findings`, and lowering puts it into `DeploymentResult.findings`; `prisma deploy` repeats it at the end of its report ([ADR-0066](ADR-0066-deploy-runs-alchemy-in-process.md)). An extension's own preflight payload never carries it. -- **Triggers.** Each service's deployment triggers carry `:updatedAt` for each platform variable its input document points at, with `?` when the variable has no row. Changing a value on the platform and deploying again replaces exactly the deployments that read it. + The hint follows the class of the group the branch receives: `--role production` for `production`, `--role preview` for `preview`. For a custom group it is a sentence that names the group, quoted for the shell, and says to set the value there in the Prisma Console, because no released CLI command writes to a custom group yet. No hint writes a branch override, which the platform is removing. A variable that an array position makes required has a second line with the reason, and a line for a service that needs some of several variables ends with the schema's message. +- **The findings.** Every variable with no value that nothing requires is listed, with its readers (a service and field, or the node that names it and that no service reads it) and the commands that set it. `PreflightInput.report` takes a `PlatformVariableCheck`: the count of platform variables checked and this list, names and readers only, never a value. It carries platform-variable findings and that count, nothing else. The deploy prints the list right after the preflight step, under `Platform variables with no value:`. With `--json` it is a message whose data holds the list, and `onEvent` receives it as a `preflight-findings` event. The step's data stays `{ checked, unset }`, two counts. The deploy hands the list to `lower()` as a value, `LowerOptions.findings`, and lowering puts it into `DeploymentResult.findings`; `prisma deploy` repeats it at the end of its report ([ADR-0066](ADR-0066-deploy-runs-alchemy-in-process.md)). An extension's own preflight payload never carries it. +- **Triggers.** Each service's deployment triggers carry `:updatedAt` for each platform variable its input document points at, with `?` when the variable has no value. Changing a value on the platform and deploying again replaces exactly the deployments that read it. ### `prisma dev` @@ -243,7 +247,7 @@ The local target plays the platform's part. - **A platform secret comes from the app secrets.** The first process hands the second process the named secrets, the app secrets under the secrets keys of the graph's platform secrets, in `PRISMA_COMPOSER_NAMED_SECRETS`, in memory. - **A missing value follows ADR-0058.** For a variable a service reads in its input, an unset or empty one is left out of the service's input document, and the schema decides: a required one, or one an array position reads, stops `prisma dev` before any service starts, naming it and the service. - **Every plain value in the file is checked.** A member of `plainVariableText` that holds a known secret fails with `CONFIG.SECRET_AS_PLAIN_VALUE`, naming the platform variable and the secret, never the value. -- **It isolates.** A local service receives only the variables its own `$platform` markers name. This is a requirement of the local target only: on Prisma Cloud every deployment receives every row of its class. +- **It isolates.** A local service receives only the variables its own `$platform` markers name. This is a requirement of the local target only: on Prisma Cloud every deployment receives every value of its branch's group. - **A changed value pauses rebuilds** until `prisma dev` is restarted. After the restart, the deployment's `:updatedAt` trigger replaces only the readers' deployments. - **A change to what the app reads pauses rebuilds.** A rebuild runs no preflight, so the values and the list of unset variables come from the preflight at start, and a read the change adds would have neither. After a rebuild's Load, `prisma dev` compares two sets with those at start: one key per `valueReads` entry (reader, node and path), and each read node's address with its `props`. Order does not matter. A change to a node's schema changes its `props`, so it is a change too. If either set differs, `prisma dev` does not converge, emits the `value-reads-changed` event, and pauses rebuilds until it is restarted. The CLI prints it as a warning: `The platform variables the app reads changed since dev started: reads of "shop.smtpPort" were added, reads of "shop.emailFrom" were removed, and "shop.sender" was changed. Restart dev to apply them; rebuilds are paused until then.` A node whose reads were only added goes in the first clause, one whose reads were only removed in the second, and one whose `props` changed, or whose reads were both added and removed, in the third. - **An edit to the app's own modules is seen.** Since [ADR-0067](ADR-0067-prisma-dev-converges-in-a-worker-thread.md), the comparison above runs in the worker thread of each converge, which loads the app as it is on disk, so it sees an edit to `module.ts`. Before that decision the first process compared the graph it loaded at start with itself, and saw no change. @@ -254,7 +258,7 @@ The local target plays the platform's part. **Only the root declares one.** A variable's name is one space per deployed app. A module below the root that named one would claim that name for every app and every instance that uses the module, and would hide from its input what it needs. The root is the app, so it is the one place whose scope matches that space. A module declares the value in its input and the root wires it down. -**The node says nothing about where its value is set.** Where a value lives is the operator's decision, made in the platform's own terms. Each reader receives the value the platform resolves for it under the variable's name, at whatever scopes the platform offers: today the class and the branch. Preflight is the only part of the deploy that looks up where a platform variable's value is set. If the platform adds a scope, such as a value set on one service, preflight's existence check gains a list call per reader, and nothing else in the deploy changes. `prisma dev` gives each name one value from local files, so two readers with two values under one name would also need a local source per reader. +**The node says nothing about where its value is set.** Where a value lives is the operator's decision, made in the platform's own terms. Each reader receives the value the platform resolves for it under the variable's name, from whatever the platform offers: the branch's group, the branch's override, and the service's own variables. Preflight is the only part of the deploy that looks up where a platform variable's value is set. To see a value set on one service, preflight would add one read per reading service, and nothing else in the deploy would change. `prisma dev` gives each name one value from local files, so two readers with two values under one name would also need a local source per reader. **A secret is a fact about Composer and the service, not about the platform.** The platform encrypts every row and returns no value, so it handles a secret and a plain value alike. The difference matters in four places inside Composer. In a binding, a platform secret fits only a secret field and arrives boxed, while a plain value fits only a `field()` field. In output, Composer redacts a secret's value wherever it prints; it must not redact a plain value such as `587`. In boot errors, a plain value's expected form may be described, while a secret is never decoded, so a secret's error says nothing about its content. Under `prisma dev`, a platform secret comes from the app secrets and a plain variable from the app configuration. So the node says which kind it is, and the platform needs nothing for it. @@ -264,7 +268,7 @@ The local target plays the platform's part. **The schema decides, as a black box.** [ADR-0042](ADR-0042-service-input-is-one-standard-schema.md) forbids reading a schema's internals. Leaving variables out and calling `validate` asks the schema exactly whether it can do without them, with no value and no introspection. -**One call per name, not per scope.** The list filter by class and key already returns the class row and every branch row. Listing the whole class would return every branch's `COMPOSER_` rows on a preview project. +**One read for the branch, not a lookup per name.** The platform decides which group a branch receives, by its git name. A lookup by class cannot see a custom group, so it reports a value in a custom group missing and counts a `preview` value the branch never receives as present. Asking the platform what the branch receives gives its own answer, in one call however many names the app has. **Upper-case names.** The platform accepts no other key, and Composer compares pointer names without case while a process environment on Linux compares them with case. With upper-case names a row and a name never differ by case, so boot finds the row preflight saw. @@ -289,10 +293,10 @@ The local target plays the platform's part. ## Consequences - A new environment needs its platform variables set first. For a new app, the first deploy creates the Project and Branch, then stops at preflight with the commands that set each required variable, including the project's id. -- Every new preview branch reads the preview-wide row. +- Every new branch reads the group whose rule matches its name, or `preview`. - A deploy succeeds with an optional variable unset and lists it. Because the platform has no way to store "deliberately empty", the list also holds a variable whose absence is intended. - A process that exits at boot for a reason preflight cannot see, such as a value that the schema refuses, is promoted. The guide names `prisma service logs ` as where the error is. -- Every service on Prisma Cloud sees every variable of its class. Composer records which service reads which variable in its graph and in each input document, so it can send that record if the platform ever takes one. +- Every service on Prisma Cloud sees every variable of its branch's group. Composer records which service reads which variable in its graph and in each input document, so it can send that record if the platform ever takes one. - Under `prisma dev` and on the platform, a service with an unset optional variable receives the same input: the field is absent. Dev's input document leaves the marker out; the deploy's document holds the marker, and boot leaves the key out. - The deploy reads the app secrets only to redact the values under the graph's secrets keys wherever it prints. - A schema's transform, default, refinement or removal of undeclared keys does not run on a platform variable's value. A transform or default the library can show in its JSON Schema is refused; one it cannot show, such as Zod's `.trim()` or `z.coerce`, is accepted and does not run. Such a check or change belongs in the service's own schema. @@ -304,8 +308,13 @@ The local target plays the platform's part. - **Copy local values on deploy.** Rejected: an implicit copy is how a local value reaches a remote environment by accident. - **Succeed with every variable unset, and report.** Rejected: the platform promotes a service that exits at boot and reports it running, so the deploy would leave it crashing. Preflight refuses the case the schema can show without a value. -- **Two list calls per name, one per scope.** Rejected: one call filtered by class and key returns both. -- **The newest row's `updatedAt` as the trigger.** Rejected: a change to a class row under a branch override would redeploy a service whose value did not change. +- **One list call per name, filtered by class and key**, with the branch row winning over the class row. This was the lookup before variable groups. Replaced: it cannot see a custom group, and on a branch that receives one it reports the wrong answer both ways. +- **Two list calls per name, one per scope.** Rejected for the same reason. +- **The newest row's `updatedAt` as the trigger.** Rejected: a change to a value under a branch override would redeploy a service whose value did not change. The read gives the `updatedAt` of the value the branch receives. +- **Fall back to the per-name lookup when the read fails.** Rejected: it brings back the wrong answers without a word. +- **Send no `branchId` for production and rely on the read's default.** Rejected: the deploy already holds the default branch's id, and sending it removes a platform behaviour Composer would otherwise depend on. +- **Suggest `--branch ` after `--role preview`**, so the next preview branch is not missing the value too. This was the hint before variable groups. Removed: it writes a branch override, which the platform is removing. +- **One read per reading service, so preflight sees a value set on one service.** Deferred: Composer has no way to declare such a value yet. - **A source with no node**, `envSecret('NAME')` and `envParam('NAME')`, written in any binding. Rejected: it leaves nothing for Load to list as a node and no address to name it by, and `envParam()` in an input binding gave a value the deploy reads a second spelling beside a root input field. Both are removed rather than kept as deprecated spellings, so there is one way to name a platform variable. - **A platform variable as a property of an input field,** such as `field(type('number'), { env: 'SMTP_PORT' })`. Rejected: a value the operator must set is part of the topology, so it is a node. - **A platform variable node anywhere in the tree.** Rejected: a nested module naming one claims the name for every app and instance, and hides from its input what it needs. diff --git a/docs/design/90-decisions/README.md b/docs/design/90-decisions/README.md index 68b7fbef4..ae7515f96 100644 --- a/docs/design/90-decisions/README.md +++ b/docs/design/90-decisions/README.md @@ -85,7 +85,7 @@ _Earlier drafts (ADR-0001, ADR-0002) were retired as the high-level design settl - [ADR-0061](ADR-0061-a-module-declares-its-input-as-a-compute-service-does.md) — A module declares its input as one Standard Schema, `input`, exactly as a compute service does, and whoever provisions it binds that input with a binding typed from the schema. The body receives `input` as a dictionary with one value per field; it passes fields on by name, or lists a plain field in `resolve()`, and never reads their data, so the graph cannot branch on its input. The dictionary itself is not a value: passing it on whole fails to compile and fails at Load, for every module. A field that may receive a value known only at boot, such as a platform variable's, is wrapped in `field()`; a secret is a `secretString()` field. The module `params`/`paramNeed()` and `secrets`/`secret()` slots are removed. The root may declare `input`, bound to the app configuration. - [ADR-0062](ADR-0062-environment-values-come-from-resolve-and-config-adapters.md) — The graph's structure is the same whatever inputs Composer is given; only values differ per environment. A module body holds values (`Value`), opaque stand-ins for data known later: deploy-time values, whose data the deploy has by the end of Load, and runtime values (`RuntimeValue`, which is `Value>`), whose data only the platform holds. A runtime value comes from a target's source, from a value resource (a resource node that is also a value, which only the app root can provision, enforced by the compiler), or from a module input bound to one; `provision()` returns the value with the node's address on it, and the graph's `valueReads` lists each service that reads each value resource. `resolve(dependencies, fn)` computes a value from deploy-time values only; `fn` never sees a pointer. Config adapters produce the app configuration, which fills the root's input; no source reads it, so a value the deploy reads is a root input field. Secrets adapters produce the app secrets, which `prisma dev` gives its services and which Composer redacts; the deploy does not copy either to platform variables, which the operator sets on the platform. Both lists default to `[environmentVariables()]`; `dotenv()` reads `.env` files through `dotenv-flow`. Only the first process runs adapters, once per deploy; the second reads the app configuration file and refuses a graph whose node addresses differ. Secrets stay out through pointers and redaction. Every environment has a name and none is special. *(Amended by ADR-0066: `deploy` runs Alchemy in its first process and writes no app configuration file; the second process applies to `prisma dev` and `destroy`.)* *(Amended by ADR-0067: `prisma dev` writes no app configuration file.)* *(Amended by ADR-0068: no command starts a second process or writes an app configuration file.)* - [ADR-0063](ADR-0063-a-node-depends-on-an-interface-or-exposes-one.md) — The two ends of a connection are named by what the node does with them: a node **depends on** an interface (`deps`) or **exposes** one (`expose`); an interface is a `Contract` in code; Input and Output are retired as port words, because the dataflow and ports-and-adapters traditions give the same two ends opposite names; the module body's `inputs` becomes `deps`; the topology's `in`/`out` stay, defined as the dependency end and the exposed end. A service also reads a platform variable, a third relationship recorded in `valueReads`, not as an edge. -- [ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md) — A platform variable is a variable on the platform that a service reads by name at boot, declared by a node the app root provisions: `variable({ name })` or `variable.secret({ name })`. A value the operator supplies reaches the app in two ways: a root input field for a value the deploy reads, a platform variable node for a value the service reads at boot. The node creates nothing and stays out of the application topology and the deploy report; the graph check refuses two nodes with one name, a plain node and a root input field with one name, and a node bound as a service's whole input. The deploy does not copy local values (by default `.env` and the shell) to platform variables, because an implicit copy can push a local value into a remote environment; for now the operator sets each with `prisma project env add`, and an explicit way through `deploy` is expected later. Before Alchemy runs, the deploy checks that every variable a service needs has a value, and fails with the commands that set the missing ones. Under `prisma dev` a plain variable comes from the app configuration. `variable({ name, schema })` types a plain variable's value by a Standard JSON Schema such as ArkType's or Zod's: the node keeps the reduced JSON Schema, and boot and `prisma dev` decode and validate the variable's text with it, with messages that never hold the text. Variable names match `^[A-Z][A-Z0-9_]*$`, and a few names are reserved for Composer and the platform. *(Amended by ADR-0067: plain platform variable text reaches the local target in memory.)* +- [ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md) — A platform variable is a variable on the platform that a service reads by name at boot, declared by a node the app root provisions: `variable({ name })` or `variable.secret({ name })`. A value the operator supplies reaches the app in two ways: a root input field for a value the deploy reads, a platform variable node for a value the service reads at boot. The node creates nothing and stays out of the application topology and the deploy report; the graph check refuses two nodes with one name, a plain node and a root input field with one name, and a node bound as a service's whole input. The deploy does not copy local values (by default `.env` and the shell) to platform variables, because an implicit copy can push a local value into a remote environment; for now the operator sets each on Prisma Cloud, in the variable group the environment's branch receives, and an explicit way through `deploy` is expected later. Before Alchemy runs, the deploy asks Prisma Cloud once which variables the environment's branch receives, checks that every variable a service needs has a value, and fails with what sets the missing ones; a failed or paged read fails the deploy. Under `prisma dev` a plain variable comes from the app configuration. `variable({ name, schema })` types a plain variable's value by a Standard JSON Schema such as ArkType's or Zod's: the node keeps the reduced JSON Schema, and boot and `prisma dev` decode and validate the variable's text with it, with messages that never hold the text. Variable names match `^[A-Z][A-Z0-9_]*$`, and a few names are reserved for Composer and the platform. *(Amended by ADR-0067: plain platform variable text reaches the local target in memory.)* - [ADR-0065](ADR-0065-a-compute-services-input-document-travels-in-its-artifact.md) — On Prisma Cloud the deploy writes a Compute service's input document into its artifact, in the `inputDocument` field of `compute.bootstrap.json`, and creates no variable for it; every other value the service reads at boot (`port`, connection params, provider params, generated values) stays a variable, because each is issued during the deploy or is a secret, except `port`, which the Compute emulator has to be able to set under `prisma dev`. The printed `bootstrap.js` passes the document to the Prisma Cloud service's `run(address, boot, inputDocument)`; core's `run` keeps two parameters. The artifact is the document's only source: `run()` ignores a `COMPOSER_
_INPUT` variable when the artifact holds the document, which the upgrade needs today, and the local target ignores one for every service that runs its artifact. A changed document changes the artifact's path and replaces the deployment; the document is not a trigger member, a platform variable it names still is. Under `prisma dev` the local `Deployment` provider reads the document with the packer's own reader to decide which platform variables a service receives, and `reserve` writes it as a variable for a dev server. `package` must not write a secret or an unresolved value into an artifact. A deployment made before the upgrade cannot be put back into service. Rejected: keeping every value a variable (8 KB limit), a general map of keys in the boot file, the document as parsed JSON, the environment winning, and writing both places for one release. - [ADR-0066](ADR-0066-deploy-runs-alchemy-in-process.md) — `prisma deploy` and the `deploy` operation run Alchemy's plan and apply in the `prisma` process through `alchemy/Alchemist`: no generated stack file, no Alchemy child. `lower()` takes containers, preflight payloads, the preflight findings and the report hook as values, the summary comes back as a value, Alchemy's events become engine step events, failures are `DEPLOY.ENGINE_FAILED` or `DEPLOY.INTERRUPTED`, and Ctrl-C releases the state lease. Every Management API request, Alchemy's and Composer's, goes through the engine's `ctx.api`, which `lower()` receives as `LowerOptions.credentials`, so a `prisma login` session deploys with no `PRISMA_SERVICE_TOKEN` and no credential enters `process.env`. Lowering and Alchemy load from the app's own install of `@prisma/composer`, which must speak the host's converge contract. Supersedes ADR-0007 for `deploy`; amends ADR-0038, ADR-0043, ADR-0044, ADR-0049, ADR-0062 and ADR-0064. *(Extended to `prisma dev` by ADR-0067.)* *(Extended to `destroy` by ADR-0068: `containers` and `preflightPayloads` are required, with no environment fallback.)* - [ADR-0067](ADR-0067-prisma-dev-converges-in-a-worker-thread.md) — Each converge of `prisma dev` runs in a new worker thread of the `prisma` process: no dev stack file, no app configuration file, no Alchemy child. The worker imports the config and the app as they are on disk, so an edit to an app definition file applies on the next rebuild; a loaded app is made of functions and cannot be handed between threads, so the import and the converge run in the same place. The main thread sends plain data in memory (values, named secrets, containers), holds the one-converge flag and the working directory for the worker, and reports its events and redacted output. Three kinds of edit still need a restart: adding or removing a node, passing on a root input field the root did not pass on at start, and changing which platform variables the app reads; under Bun, so does a directory import written before its `index.ts` exists. `destroy` keeps the stack file and the child. *(Amended by ADR-0068: `destroy` runs in process too.)* diff --git a/docs/guides/building-an-app.md b/docs/guides/building-an-app.md index f53aa440f..928bae77c 100644 --- a/docs/guides/building-an-app.md +++ b/docs/guides/building-an-app.md @@ -700,7 +700,7 @@ Here `mailer` is a service of the app whose input schema declares `from: field(t - **`provision()` returns the value**, with `id`, the node's address, on it. Pass it into a service's or a module's input like any other value. The node's default id is the name in camel case, so `EMAIL_FROM` is `shop.emailFrom`; give it another with `provision(variable({ name }), { id: 'sender' })`. - **Only the app root provisions one.** A platform variable names something outside the app, the names form one space per deployed app, and the root is the app. In a `module()` body, `provision(variable(…))` fails to compile, with an error that names `appRoot()`. A module that needs the value declares a field in its `input`, and the root passes the value down. So a root built with `module()` cannot declare a platform variable: build it with `appRoot()`. -- **The operator sets the value on the platform**, for production, for every preview environment, or for one: `prisma project env add 'STRIPE_SECRET_KEY=' --project '' --role preview`. The deploy does not copy it from `.env` or your shell. At deploy, preflight checks that the environment has the variable, and fails, with the command to run, when a service's schema requires a variable that has no value ([Deploying § Platform variables](deploying.md#platform-variables)). The framework carries only the variable's *name*; the platform injects the value straight into the running instance. Under `prisma dev` a plain variable's value comes from the `config` adapters and a secret's from the `secrets` adapters ([Running locally](running-locally.md)). +- **The operator sets the value on the platform**, in the variable group the environment's branch receives: for example `prisma project env add 'STRIPE_SECRET_KEY=' --project '' --role preview` for the `preview` group. The deploy does not copy it from `.env` or your shell. At deploy, preflight checks that the environment's branch receives the variable, and fails, with the command to run, when a service's schema requires a variable that has no value ([Deploying § Platform variables](deploying.md#platform-variables)). The framework carries only the variable's *name*; the platform injects the value straight into the running instance. Under `prisma dev` a plain variable's value comes from the `config` adapters and a secret's from the `secrets` adapters ([Running locally](running-locally.md)). - **The node creates nothing.** It is not sent to the platform's application topology, and the deploy report has no line for it. The loaded graph lists it, with each service that reads it in `graph.valueReads`. A node no service reads is listed under "Platform variables with no value" when it has none, as `named by resource "shop.emailFrom", read by no service`. A name is an upper-case letter followed by upper-case letters, digits and underscores, such as `STRIPE_SECRET_KEY`. Any name starting with `COMPOSER_`, and `DATABASE_URL`, `DATABASE_URL_POOLED`, `PORT`, `PATH` and `HOME`, are reserved. A name has one meaning in an app: two nodes with one name, or a platform variable and a root input field with one name, fail before anything is created, naming the variable and both places. Declare each platform variable once and pass its value to every module that needs it. A node's value bound as a service's whole input also fails: bind it to one field. diff --git a/docs/guides/deploying.md b/docs/guides/deploying.md index 974f7d37b..ea9b0b3aa 100644 --- a/docs/guides/deploying.md +++ b/docs/guides/deploying.md @@ -285,24 +285,24 @@ export default appRoot('shop', ({ provision }) => { You set its value on the platform as text. A variable declared with a `schema`, such as `variable({ name: 'SMTP_PORT', schema: type('number') })`, is decoded and validated when the service boots, not when you deploy: a text that does not fit fails the service at boot, the deploy still succeeds, and the error is in `prisma service logs ` ([Building an app § A typed platform variable](building-an-app.md#a-typed-platform-variable)). The node creates nothing: the deploy report has no line for it. The deploy does not copy a value from `.env` or your shell to the platform, because that could push a local value into a remote environment by accident, and today it creates, changes and deletes no platform variable. -Set a variable with the `prisma` CLI, at one of three scopes: +Prisma Cloud keeps variables in **variable groups**. Every project has a `production` group and a `preview` group, and can have custom groups, each matching branches by their git name. Each branch receives exactly one group: the production branch receives `production`, any other branch receives the custom group whose rule matches its name most precisely, or else `preview`. Groups do not combine: a branch that receives a custom group named `staging` receives nothing from `preview`. Set a value in the group the environment's branch receives: ```sh # production prisma project env add 'EMAIL_API_KEY=' --project '' --role production -# every preview environment +# every preview environment that receives the preview group prisma project env add 'EMAIL_API_KEY=' --project '' --role preview -# one preview environment only, overriding the preview-wide value -prisma project env add 'EMAIL_API_KEY=' --project '' --branch 'staging' ``` -`update`, `list` and `delete` take the same flags. A deployment receives every variable of its class with its own branch's overrides on top, so a preview-wide value reaches every new preview environment. +`update`, `list` and `delete` take the same flags. Set a value in a custom group in the Prisma Console. A value set in a group reaches every new environment whose branch receives that group. + +A deployment receives every value of its branch's group, then that branch's overrides, then the variables set on its service in the Console; a later one wins. Branch overrides are being removed from the platform, so set values in a group instead. The deploy checks the branch's group and its overrides. It does not see a value set on one service in the Console, so a variable a service needs that is set only there fails the deploy as missing. A change you make to a Composer service in the Console lasts until the next `prisma deploy`. The platform copies the variables into a deployment when it creates it. A value you change reaches a service at its next deploy, and that deploy replaces exactly the services that read the variable. ### What the deploy checks -The `check environment variables` step looks up every platform variable the app reads, before any service or database is created. It reads whether a value exists, never the value. +The `check environment variables` step asks Prisma Cloud once which variables the environment's branch receives, and looks up every platform variable the app reads in that answer, before any service or database is created. It reads whether a value exists, never the value. For `production` it asks about the project's default branch. If Prisma Cloud cannot answer, the deploy fails, naming the call and its HTTP status: the platform may not offer this read yet. - **A variable a service needs that has no value fails the deploy.** Whether a service needs it is decided by the service's input schema: the deploy leaves the variable out and validates the input. A required field fails; an optional one does not. @@ -312,10 +312,9 @@ The `check environment variables` step looks up every platform variable the app Set it on the platform, then deploy again: - prisma project env add 'EMAIL_API_KEY=' --project 'proj_…' --role preview - - prisma project env add 'EMAIL_API_KEY=' --project 'proj_…' --branch 'staging' ``` - For `production` the command uses `--role production`. For any other environment the preview-wide command comes first, so that the next preview environment has the value too. + The command follows the group the branch receives: `--role production` for the `production` group and `--role preview` for the `preview` group. For a custom group the deploy names the group and says to set the value there in the Prisma Console: `Set EMAIL_API_KEY in the variable group 'staging' in the Prisma Console.` - **A variable nothing needs that has no value is listed, and the deploy goes on.** The list prints right after the step, and again at the end of the deploy output: ```text @@ -444,7 +443,7 @@ pattern: on push, run `prisma deploy --environment "pr-$PR_NUMBER"`; on close, run a script like the one under [Removing an app or an environment](#removing-an-app-or-an-environment) that passes that name, `environment: 'pr-42'` for PR 42. -One extra: if your app declares platform variables (see [Building an app § Platform variables](building-an-app.md#platform-variables)), they live on the platform, and CI does not supply them. Set each one once with `--role preview`, and every new `pr-42` environment reads it ([Platform variables](#platform-variables)). A variable a service needs that has no value fails the deploy, naming it. A root input field is different: the deploy reads it from the app configuration on every deploy, so CI exports it, or commits it in `.env.` and lists `dotenv()`, every time. +One extra: if your app declares platform variables (see [Building an app § Platform variables](building-an-app.md#platform-variables)), they live on the platform, and CI does not supply them. Set each one once in the group the `pr-42` branches receive, `--role preview` for the `preview` group, and every new `pr-42` environment reads it ([Platform variables](#platform-variables)). A variable a service needs that has no value fails the deploy, naming it. A root input field is different: the deploy reads it from the app configuration on every deploy, so CI exports it, or commits it in `.env.` and lists `dotenv()`, every time. A root's input can come from a committed `.env.` file per environment ([Values from outside the code](building-an-app.md#values-from-outside-the-code)). Keep secrets out of committed files: put them in CI's secret store and keep `environmentVariables()` in `secrets`. diff --git a/skills/prisma-composer-core-concepts/SKILL.md b/skills/prisma-composer-core-concepts/SKILL.md index 33decb177..6f84b5ce0 100644 --- a/skills/prisma-composer-core-concepts/SKILL.md +++ b/skills/prisma-composer-core-concepts/SKILL.md @@ -132,7 +132,7 @@ export default appRoot('shop', { input: type({ EMAIL_FROM: 'string' }) }, ({ inp Rules that bite: 1. **Secretness is checked by the binding's type and by the deploy.** A `provision()` binding, a service's or a module's, is typed from the schema: a literal or a `SecretBox` where the schema expects `SecretString`, or a platform secret's value in a text field, fails to compile, and the deploy refuses it where the schema has no types. An ArkType schema with a `SecretString` field cannot also transform its input: a morph anywhere in it (`'string.trim'`, `.pipe()`, `field(type('string.integer.parse'))`) or `'+': 'delete'` copies the input, the copied secret loses its value, and the deploy refuses it. Transform in the service code instead; a Zod schema keeps the box. -2. **A plain platform variable's value is known only at boot: text, or the type its `schema` declares.** Bind it to a field wrapped with `field()`. A platform variable's value goes into a field of an `input` only. A compute service has one per-key param, the reserved `port`, which takes a literal or a root input field and no source, because the deploy needs the port before the service exists; every other value is a field of its `input`. A field of a narrower type, such as `email()`'s `deliveryMode`, takes a root input field declared with that type instead, for `email()` from the exported `emailDeliveryModes`; the deploy reads a root input field from the app configuration on every deploy and writes its value into the input document. A platform secret fits a `secretString()` field only. A platform variable's value always lives on the platform. The operator sets it there with `prisma project env add 'NAME=' --project --role production`. Use `--role preview` for every preview environment, or `--branch ` for one. The deploy does not copy local values (`.env`, the shell) to platform variables. The deploy fails only when a variable that a service's schema requires has no value. The error names the variable and the command that sets it. The other variables with no value print under `Platform variables with no value:`. Prisma Cloud reports a service that exits at boot as running and promotes it; read the error with `prisma service logs `. +2. **A plain platform variable's value is known only at boot: text, or the type its `schema` declares.** Bind it to a field wrapped with `field()`. A platform variable's value goes into a field of an `input` only. A compute service has one per-key param, the reserved `port`, which takes a literal or a root input field and no source, because the deploy needs the port before the service exists; every other value is a field of its `input`. A field of a narrower type, such as `email()`'s `deliveryMode`, takes a root input field declared with that type instead, for `email()` from the exported `emailDeliveryModes`; the deploy reads a root input field from the app configuration on every deploy and writes its value into the input document. A platform secret fits a `secretString()` field only. A platform variable's value always lives on the platform. The operator sets it there with `prisma project env add 'NAME=' --project --role production`. Each branch receives one variable group: production receives `production`, another branch a custom group whose rule matches its git name, or else `preview` (`--role preview`); a custom group is set in the Prisma Console. The deploy checks the branch's group and its overrides, not a value set on one service in the Console. The deploy does not copy local values (`.env`, the shell) to platform variables. The deploy fails only when a variable that a service's schema requires has no value. The error names the variable and the command that sets it. The other variables with no value print under `Platform variables with no value:`. Prisma Cloud reports a service that exits at boot as running and promotes it; read the error with `prisma service logs `. 3. **The schema decides whether a field may be absent.** A field bound to a platform variable that is unset or empty is left out at boot. That is allowed only if the schema allows it, for example with an optional field or a union member. An optional root input field that the adapters do not supply is left out at deploy. The deploy report prints the serialized input document (each secret shown as `$platform VAR`) and every key that resolved absent. On Prisma Cloud the deploy writes the input document into the service's artifact, not into a `COMPOSER_*` variable, so it is not limited to a variable's 8 KB, and a changed document redeploys exactly that service. 4. **The reserved `port` is outside the schema.** Read it through `service.port()`, never `process.env`. The framework also exports `PORT` From a95b4cda876168200f537ff714716639a1a7a7fd Mon Sep 17 00:00:00 2001 From: willbot Date: Fri, 20 Nov 2026 22:48:23 +1100 Subject: [PATCH 3/6] fix(prisma-cloud): a failed read of the branch's variables names the call, and a complete list answer is accepted Every failure of the resolved-variables read now names the call, the project and the branch: an error status with or without a body, a network failure, and a body that is not JSON or not the expected shape. Only a 404 says the platform may not offer the read yet. The deploy fails on a paged answer only when it says there is more, so a complete answer in the platform's list envelope passes. The custom-group hint names the group in double quotes, and core documents each hint line as a shell command where one exists, otherwise an instruction. The container carries the branch a deploy targets as deployBranchId. Co-Authored-By: Claude Fable 5.2 Signed-off-by: willbot Signed-off-by: Will Madden --- architecture.config.json | 6 - .../0-framework/1-core/core/src/preflight.ts | 2 +- .../target/src/__tests__/preflight.test.ts | 153 +++++++++++++----- .../1-extensions/target/src/container.ts | 10 +- .../1-extensions/target/src/preflight.ts | 78 +++++---- .../target/src/reporting/reporter.ts | 4 +- 6 files changed, 168 insertions(+), 85 deletions(-) diff --git a/architecture.config.json b/architecture.config.json index 4b272e84b..0de171330 100644 --- a/architecture.config.json +++ b/architecture.config.json @@ -408,12 +408,6 @@ "layer": "extensions", "plane": "shared" }, - { - "glob": "packages/1-prisma-cloud/1-extensions/target/src/map-with-concurrency.ts", - "domain": "prisma-cloud", - "layer": "extensions", - "plane": "control" - }, { "glob": "packages/1-prisma-cloud/1-extensions/target/src/required-variables.ts", "domain": "prisma-cloud", diff --git a/packages/0-framework/1-core/core/src/preflight.ts b/packages/0-framework/1-core/core/src/preflight.ts index 63dafe257..f4d051ca4 100644 --- a/packages/0-framework/1-core/core/src/preflight.ts +++ b/packages/0-framework/1-core/core/src/preflight.ts @@ -12,7 +12,7 @@ export type PlatformVariableReader = export interface UnsetPlatformVariable { readonly name: string; readonly readers: readonly PlatformVariableReader[]; - /** Shell commands that each set it, in the order to offer them. */ + /** How to set it, one line each, in the order to offer them: a shell command where one exists, otherwise an instruction. */ readonly commands: readonly string[]; } diff --git a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts b/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts index f4f559cee..c41d86780 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts @@ -45,7 +45,6 @@ const build = { entry: 'server.js', }; -/** A row of the environment-variable list, which only the key-clash check still reads. */ interface Row { projectId: string; class: 'production' | 'preview'; @@ -61,7 +60,6 @@ type Source = /** One key the resolved-variables read lists for the branch. */ interface Entry { key: string; - /** Defaulted by the fake client. */ updatedAt?: string; isManagedBySystem?: boolean; source?: Source; @@ -90,6 +88,8 @@ interface FakeState { group?: Group; /** Replaces the read's answer: an error status, or a body of the test's own. */ answer?: { status: number; body?: unknown; error?: unknown }; + /** Makes the read throw, as the client does on a network failure or a body that is not JSON. */ + throws?: Error; } const emptyState = (): FakeState => ({ gets: [], reads: [], posts: [], rows: [], entries: [] }); @@ -112,6 +112,7 @@ const fakeClient = (state: FakeState): ManagementApiClient => const projectId = init.params.path?.['projectId'] ?? ''; const branchId = init.params.query['branchId'] ?? ''; state.reads.push({ projectId, branchId }); + if (state.throws !== undefined) throw state.throws; if (state.answer !== undefined) { const ok = state.answer.status < 400; return { @@ -446,61 +447,121 @@ describe('the deploy check reads which variables the branch receives and sets no expect(state.gets).toEqual([]); }); - describe('a failed read fails the deploy, naming the call, the status, the project and the branch', () => { + const COULD_NOT_READ = + 'Deploy failed. Composer could not read which variables branch "br-1" of project "proj" receives: GET /v1/projects/proj/resolved-variables?branchId=br-1'; + + const failedReadMessage = async () => { + const message = await failureOf( + preflightWith({ graph: secretGraph(), ...preview }, { client: fakeClient(state) }), + ); + expect(state.reads).toHaveLength(1); + expect(state.gets).toEqual([]); + expect(state.posts).toEqual([]); + return message; + }; + + describe('a failed read fails the deploy, naming the call, the project and the branch', () => { test.each([ - ['an unknown project', 404, { code: 'not-found', message: 'Project not found' }], - ['an unknown branch', 404, { code: 'not-found', message: 'Branch not found' }], - ['a server error', 500, { code: 'internal', message: 'boom' }], - ])('%s', async (_case, status, error) => { - state.answer = { status, error }; - - const message = await failureOf( - preflightWith({ graph: secretGraph(), ...preview }, { client: fakeClient(state) }), - ); + ['an unknown project', { code: 'not-found', message: 'Project not found' }], + ['an unknown branch', { code: 'not-found', message: 'Branch not found' }], + ])('%s answers 404, which says the platform may not offer the read', async (_case, error) => { + state.answer = { status: 404, error: { error } }; - expect(message).toBe( - `Deploy failed. GET /v1/projects/proj/resolved-variables?branchId=br-1 answered HTTP ${status}: ${JSON.stringify(error)}. ` + + expect(await failedReadMessage()).toBe( + `${COULD_NOT_READ} answered HTTP 404: ${JSON.stringify({ error })}. ` + 'The platform may not offer this read yet, and this Composer version needs it to check platform variables.', ); - expect(state.reads).toHaveLength(1); - expect(state.gets).toEqual([]); - expect(state.posts).toEqual([]); + }); + + test('a server error names its status and body, and does not blame a missing read', async () => { + state.answer = { status: 500, error: { error: { code: 'internal', message: 'boom' } } }; + + expect(await failedReadMessage()).toBe( + `${COULD_NOT_READ} answered HTTP 500: {"error":{"code":"internal","message":"boom"}}.`, + ); + }); + + test('an error status with an empty body names the status', async () => { + state.answer = { status: 502 }; + + expect(await failedReadMessage()).toBe(`${COULD_NOT_READ} answered HTTP 502.`); + }); + + test('a network failure names the call and keeps the cause', async () => { + const cause = new TypeError('fetch failed'); + state.throws = cause; + + const error = await preflightWith( + { graph: secretGraph(), ...preview }, + { client: fakeClient(state) }, + ).catch((e: unknown) => e); + + expect(error).toBeInstanceOf(Error); + expect((error as Error).message).toBe(`${COULD_NOT_READ} failed: fetch failed.`); + expect((error as Error).cause).toBe(cause); + }); + + test('a body that is not JSON names the call', async () => { + state.throws = new SyntaxError('Unexpected token \'<\', "" is not valid JSON'); + + expect(await failedReadMessage()).toBe( + `${COULD_NOT_READ} failed: Unexpected token '<', "" is not valid JSON.`, + ); + }); + + test('a body without the group names the call and says the answer may have changed', async () => { + state.answer = { status: 200, body: { data: [] } }; + + const message = await failedReadMessage(); + + expect(message).toStartWith( + `${COULD_NOT_READ} answered with a body this Composer version cannot read: `, + ); + expect(message).toEndWith( + "The platform's answer may have changed, and a newer Composer version may read it.", + ); }); }); test.each([ - ['a pagination object', { pagination: { nextCursor: 'c1', hasMore: true } }], + ['a pagination object with more to fetch', { pagination: { nextCursor: 'c1', hasMore: true } }], + ['a pagination object with a cursor', { pagination: { nextCursor: 'c1', hasMore: false } }], ['a next cursor', { nextCursor: 'c1' }], - ['a more-pages flag', { hasMore: false }], + ['a cursor', { cursor: 'c1' }], + ['a more-pages flag', { hasMore: true }], ])( - 'an answer that carries %s fails the deploy as too old for the platform', + 'an answer that says it has more, with %s, fails the deploy as too old for the platform', async (_case, extra) => { - state.answer = { - status: 200, - body: { group: builtInGroup('br-1'), data: [], ...extra }, - }; + state.answer = { status: 200, body: { group: builtInGroup('br-1'), data: [], ...extra } }; - const message = await failureOf( - preflightWith({ graph: secretGraph(), ...preview }, { client: fakeClient(state) }), - ); + const message = await failedReadMessage(); - expect(message).toStartWith( - 'Deploy failed. GET /v1/projects/proj/resolved-variables?branchId=br-1 answered with one page of a longer list.', - ); + expect(message).toStartWith(`${COULD_NOT_READ} answered with one page of a longer list.`); expect(message).toContain('too old for the platform'); }, ); - test('an answer without the group fails the deploy instead of guessing', async () => { - state.answer = { status: 200, body: { data: [] } }; + test.each([ + ['a complete pagination object', { pagination: { nextCursor: null, hasMore: false } }], + ['top-level fields that say nothing is left', { nextCursor: null, hasMore: false, cursor: '' }], + ])('a complete answer in a list envelope, with %s, is accepted', async (_case, extra) => { + state.answer = { + status: 200, + body: { + group: builtInGroup('br-1'), + data: [ + { key: 'STRIPE_SECRET_KEY', updatedAt: DEFAULT_UPDATED_AT, isManagedBySystem: false }, + ], + ...extra, + }, + }; - const message = await failureOf( - preflightWith({ graph: secretGraph(), ...preview }, { client: fakeClient(state) }), + const result = await preflightWith( + { graph: requiredSecretGraph(), ...preview }, + { client: fakeClient(state) }, ); - expect(message).toStartWith( - 'Deploy failed. GET /v1/projects/proj/resolved-variables?branchId=br-1 answered with a body this Composer version cannot read: ', - ); + expect([...result.updatedAt]).toEqual([['STRIPE_SECRET_KEY', DEFAULT_UPDATED_AT]]); }); describe('the commands that set a missing variable follow the group the branch receives', () => { @@ -525,12 +586,16 @@ describe('the deploy check reads which variables the branch receives and sets no ]); }); - test('a custom group is named, quoted to paste', async () => { - expect(await commandsFor({ id: 'grp-1', name: `it's "staging" x`, class: 'custom' })).toEqual( - [ - `Set STRIPE_SECRET_KEY in the variable group 'it'\\''s "staging" x' in the Prisma Console.`, - ], - ); + test('a custom group is named in a sentence, since no command writes to it', async () => { + expect(await commandsFor({ id: 'grp-1', name: "team's staging", class: 'custom' })).toEqual([ + `Set STRIPE_SECRET_KEY in the variable group "team's staging" in the Prisma Console.`, + ]); + }); + + test('a group of a class Composer does not know gets the custom-group sentence', async () => { + expect( + await commandsFor({ id: 'grp-2', name: 'qa', class: 'experimental' as Group['class'] }), + ).toEqual([`Set STRIPE_SECRET_KEY in the variable group "qa" in the Prisma Console.`]); }); test('no command sets a branch override', async () => { @@ -580,7 +645,7 @@ describe('the deploy check reads which variables the branch receives and sets no expect(message).toEndWith( 'Set it on the platform, then deploy again:\n' + - " - Set STRIPE_SECRET_KEY in the variable group 'staging' in the Prisma Console.", + ' - Set STRIPE_SECRET_KEY in the variable group "staging" in the Prisma Console.', ); }); diff --git a/packages/1-prisma-cloud/1-extensions/target/src/container.ts b/packages/1-prisma-cloud/1-extensions/target/src/container.ts index 203ae8dd5..1097a59e7 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/container.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/container.ts @@ -46,6 +46,8 @@ function invalidAlchemyStageError(branchId: string): Error { export class PrismaCloudContainer implements ContainerInstance { /** The deterministic Alchemy stage (ContainerInstance SPI): the environment's Branch id, or the default Branch's id for `production`. Absent only for the dev container, which resolves no Branch. */ readonly alchemyStage: string | undefined; + /** The Branch this deploy targets: the environment's Branch, or the project's default Branch for `production`. Absent only for the dev container. */ + readonly deployBranchId: string | undefined; constructor( readonly input: LocateContainerInput, @@ -55,11 +57,11 @@ export class PrismaCloudContainer implements ContainerInstance { /** Set only by the dev container, which resolves no Branches. */ readonly branchless: boolean = false, ) { - const deployBranchId = branchId ?? defaultBranchId; - if (deployBranchId !== undefined && !ALCHEMY_STAGE_PATTERN.test(deployBranchId)) { - throw invalidAlchemyStageError(deployBranchId); + this.deployBranchId = branchId ?? defaultBranchId; + if (this.deployBranchId !== undefined && !ALCHEMY_STAGE_PATTERN.test(this.deployBranchId)) { + throw invalidAlchemyStageError(this.deployBranchId); } - this.alchemyStage = deployBranchId; + this.alchemyStage = this.deployBranchId; } serialize(): string { diff --git a/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts b/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts index 34a84669d..a5d5aeb7a 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts @@ -69,7 +69,6 @@ async function listEnvVars( const RESOLVED_VARIABLES_PATH = '/v1/projects/{projectId}/resolved-variables'; -/** The fields of the resolved-variables read that preflight uses: names and times, never values. */ const resolvedVariablesBody = type({ group: { name: 'string', class: 'string' }, data: type({ key: 'string', updatedAt: 'string', isManagedBySystem: 'boolean' }).array(), @@ -84,44 +83,58 @@ interface ResolvedVariablesClient { ): Promise<{ readonly data?: unknown; readonly error?: unknown; readonly response: Response }>; } -const PAGINATION_FIELDS = ['pagination', 'nextCursor', 'hasMore', 'cursor']; - const isRecord = (value: unknown): value is Record => typeof value === 'object' && value !== null; +const isCursor = (value: unknown): boolean => value !== undefined && value !== null && value !== ''; + +const saysThereIsMore = (fields: Record): boolean => + fields['hasMore'] === true || isCursor(fields['nextCursor']) || isCursor(fields['cursor']); + +const isPartial = (body: unknown): boolean => + isRecord(body) && + (saysThereIsMore(body) || (isRecord(body['pagination']) && saysThereIsMore(body['pagination']))); + +interface ResolvedRead { + readonly call: string; + readonly projectId: string; + readonly branchId: string; +} + async function readResolvedVariables( client: ManagementApiClient, projectId: string, branchId: string, ): Promise { - const call = `GET /v1/projects/${projectId}/resolved-variables?branchId=${branchId}`; + const read: ResolvedRead = { + call: `GET /v1/projects/${projectId}/resolved-variables?branchId=${branchId}`, + projectId, + branchId, + }; const res = await blindCast< ResolvedVariablesClient, 'the published Management API SDK does not describe the resolved-variables read yet; its body is checked below' - >(client).GET(RESOLVED_VARIABLES_PATH, { - params: { path: { projectId }, query: { branchId } }, - }); + >(client) + .GET(RESOLVED_VARIABLES_PATH, { params: { path: { projectId }, query: { branchId } } }) + .catch((cause: unknown) => { + throw readThrewError(read, cause); + }); if (res.error !== undefined || !res.response.ok) { - throw resolvedReadFailedError(call, res.response.status, res.error); - } - const body = res.data; - if (isRecord(body) && PAGINATION_FIELDS.some((field) => field in body)) { - throw pagedReadError(call); + throw readStatusError(read, res.response.status, res.error); } - const parsed = resolvedVariablesBody(body); - if (parsed instanceof type.errors) throw unexpectedReadError(call, parsed.summary); + if (isPartial(res.data)) throw pagedReadError(read); + const parsed = resolvedVariablesBody(res.data); + if (parsed instanceof type.errors) throw unexpectedReadError(read, parsed.summary); return parsed; } -/** The branch whose variables the environment receives: its own, or the project's default branch for production. */ function deployBranchIdOf(container: PrismaCloudContainer): string { - const branchId = container.branchId ?? container.defaultBranchId; - if (branchId === undefined) { + if (container.deployBranchId === undefined) { throw new Error( `deploy preflight: the container for the environment "${container.input.environment}" has no branch id. This is a bug in Composer.`, ); } - return branchId; + return container.deployBranchId; } /** Whether `key` has a row in the scope Composer writes its own rows to: production, or the environment's branch. */ @@ -203,23 +216,32 @@ const listFailedError = (key: string, error: unknown): Error => `deploy preflight: Prisma Management API error listing "${key}": ${JSON.stringify(error)}.`, ); -const MAY_NOT_OFFER_READ = - 'The platform may not offer this read yet, and this Composer version needs it to check platform variables.'; +const couldNotRead = (read: ResolvedRead): string => + `Deploy failed. Composer could not read which variables branch "${read.branchId}" of project "${read.projectId}" receives: ${read.call}`; + +const readStatusError = (read: ResolvedRead, status: number, error: unknown): Error => + new Error( + `${couldNotRead(read)} answered HTTP ${String(status)}` + + `${error === undefined || error === '' ? '' : `: ${JSON.stringify(error)}`}.` + + (status === 404 + ? ' The platform may not offer this read yet, and this Composer version needs it to check platform variables.' + : ''), + ); -const resolvedReadFailedError = (call: string, status: number, error: unknown): Error => +const readThrewError = (read: ResolvedRead, cause: unknown): Error => new Error( - `Deploy failed. ${call} answered HTTP ${String(status)}` + - `${error === undefined ? '' : `: ${JSON.stringify(error)}`}. ${MAY_NOT_OFFER_READ}`, + `${couldNotRead(read)} failed: ${cause instanceof Error ? cause.message : String(cause)}.`, + { cause }, ); -const unexpectedReadError = (call: string, problem: string): Error => +const unexpectedReadError = (read: ResolvedRead, problem: string): Error => new Error( - `Deploy failed. ${call} answered with a body this Composer version cannot read: ${problem}. ${MAY_NOT_OFFER_READ}`, + `${couldNotRead(read)} answered with a body this Composer version cannot read: ${problem}. The platform's answer may have changed, and a newer Composer version may read it.`, ); -const pagedReadError = (call: string): Error => +const pagedReadError = (read: ResolvedRead): Error => new Error( - `Deploy failed. ${call} answered with one page of a longer list. This Composer version reads only one page, so it would report set variables as missing. It is too old for the platform: upgrade Composer and deploy again.`, + `${couldNotRead(read)} answered with one page of a longer list. This Composer version reads only one page, so it would report set variables as missing. It is too old for the platform: upgrade Composer and deploy again.`, ); /** `value` as one POSIX shell word: single-quoted, each embedded `'` written as `'\''`. */ @@ -233,7 +255,7 @@ function setCommands(name: string, projectId: string, group: VariableGroup): rea case 'preview': return [`${add} --role preview`]; default: - return [`Set ${name} in the variable group ${shellQuote(group.name)} in the Prisma Console.`]; + return [`Set ${name} in the variable group "${group.name}" in the Prisma Console.`]; } } diff --git a/packages/1-prisma-cloud/1-extensions/target/src/reporting/reporter.ts b/packages/1-prisma-cloud/1-extensions/target/src/reporting/reporter.ts index 57cbe7111..f2c815e9d 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/reporting/reporter.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/reporting/reporter.ts @@ -12,10 +12,10 @@ import { prismaCloudContainerOf } from '../container.ts'; export function prismaCloudReporter(): ReporterDescriptor { return Builds.buildReporter({ refsOf: (container) => { - const { projectId, branchId, defaultBranchId } = prismaCloudContainerOf(container); + const { projectId, branchId, deployBranchId } = prismaCloudContainerOf(container); // The Build references only a non-production environment's Branch; the topology lives // on whichever Branch the deploy targets — the default one included. - return { projectId, branchId, deployBranchId: branchId ?? defaultBranchId }; + return { projectId, branchId, deployBranchId }; }, }); } From 4cb3ddee9e7418431317ce5a0d2979ab1d10ef4f Mon Sep 17 00:00:00 2001 From: willbot Date: Fri, 20 Nov 2026 22:48:27 +1100 Subject: [PATCH 4/6] docs: variable groups, branch overrides and service variables stated as the platform's model The glossary, the platform data model and the platform-variable decision now agree, in the present tense. A service variable belongs to one Composer service in one environment and is set only when a deployment is created. Lines that said a deployment receives every variable of its class now say its branch's group, and the failure and paging rules match the code. Co-Authored-By: Claude Fable 5.2 Signed-off-by: willbot Signed-off-by: Will Madden --- docs/design/03-domain-model/glossary.md | 8 ++++---- docs/design/05-prisma-cloud/pdp-data-model.md | 10 +++++----- docs/design/10-domains/deploy-cli.md | 2 +- docs/design/10-domains/local-dev.md | 2 +- ...sourced-value-the-framework-never-stores.md | 2 +- ...m-the-app-secrets-and-never-invents-them.md | 2 +- ...ot-and-the-deploy-copies-no-local-values.md | 18 +++++++++--------- docs/design/90-decisions/README.md | 2 +- docs/guides/deploying.md | 8 ++++---- docs/guides/running-locally.md | 2 +- skills/prisma-composer-core-concepts/SKILL.md | 2 +- 11 files changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/design/03-domain-model/glossary.md b/docs/design/03-domain-model/glossary.md index 2f64d33e5..ae9ddfab9 100644 --- a/docs/design/03-domain-model/glossary.md +++ b/docs/design/03-domain-model/glossary.md @@ -170,7 +170,7 @@ A pointer is typed by its source. `serviceOrigin()` and a plain `generatedParam( ### Platform variable -A variable on the platform that a service reads by name at boot. The app declares each one with a [platform variable node](#platform-variable-node) in its root, so every message can name the node. The service reads it through a field of its `input`. "Plain platform variable" means the non-secret kind; the secret kind is a [platform secret](#platform-secret). A deploy does not copy its value from the developer's local environment and does not read it: the platform hands it to the running service. For now the operator sets it on Prisma Cloud, in the [variable group](#variable-group) the environment's branch receives. Under `prisma dev`, the local target plays the platform's part: it reads a plain platform variable's value from the app configuration and a platform secret's from the app secrets, and hands it to the local service. A service receives the value of its branch's group, under that branch's override row if it has one, under a [service variable](#service-variable) if its service has one; deploy preflight checks the group and the override, not the service variable ([ADR-0064](../90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). Composer's own `COMPOSER_` rows are [variables on the platform](#a-variable-on-the-platform) but not platform variables, because the app does not declare them. In code: `PlatformVariableReader`, `UnsetPlatformVariable`, `PlatformVariableCheck`. +A variable on the platform that a service reads by name at boot. The app declares each one with a [platform variable node](#platform-variable-node) in its root, so every message can name the node. The service reads it through a field of its `input`. "Plain platform variable" means the non-secret kind; the secret kind is a [platform secret](#platform-secret). A deploy does not copy its value from the developer's local environment and does not read it: the platform hands it to the running service. For now the operator sets it on Prisma Cloud, in the [variable group](#variable-group) the environment's branch receives. Under `prisma dev`, the local target plays the platform's part: it reads a plain platform variable's value from the app configuration and a platform secret's from the app secrets, and hands it to the local service. A deployment receives the values of its branch's group, then the branch's overrides, then its service's [service variables](#service-variable); a later one wins. Deploy preflight checks the group and the overrides, not the service variables ([ADR-0064](../90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). Composer's own `COMPOSER_` rows are [variables on the platform](#a-variable-on-the-platform) but not platform variables, because the app does not declare them. In code: `PlatformVariableReader`, `UnsetPlatformVariable`, `PlatformVariableCheck`. ### Platform variable node @@ -194,15 +194,15 @@ A [platform variable](#platform-variable) whose value is handled as a secret: bo ### A variable on the platform -Any entry, or **row**, in a Prisma Cloud project's environment variables: a name and a non-empty text. A **group row** belongs to a [variable group](#variable-group); what was called a class row is a row of the `production` or `preview` group. A **branch row** is one branch's override, which the platform is removing. That includes Composer's own `COMPOSER_` rows, which are not [platform variables](#platform-variable). The term names the platform's storage, as distinct from what the app reads. Prisma Cloud calls these rows environment variables. +Any entry, or **row**, in a Prisma Cloud project's environment variables: a name and a non-empty text. A **group row** belongs to a [variable group](#variable-group); what was called a class row is a row of the `production` or `preview` group. A **branch override** (formerly "branch row") belongs to one branch and wins over its group's value. The platform is removing branch overrides: after a notice period, it rejects a write that names a branch. That includes Composer's own `COMPOSER_` rows, which are not [platform variables](#platform-variable). The term names the platform's storage, as distinct from what the app reads. Prisma Cloud calls these rows environment variables. ### Variable group -Prisma Cloud's term for a named set of [variables on the platform](#a-variable-on-the-platform) in one project. Every project has a `production` group and a `preview` group; it can add custom groups, each with one rule on a branch's git name (`equals` or `startsWith`). Each branch receives exactly one group: the production branch receives `production`, any other branch the custom group with the most precise matching rule, or else `preview`. Groups do not combine. A group's class is `production`, `preview` or `custom`. This is the platform's planned model and not yet live. +Prisma Cloud's term for a named set of [variables on the platform](#a-variable-on-the-platform) in one project. Every project has a `production` group and a `preview` group; it can add custom groups, each with one rule on a branch's git name (`equals` or `startsWith`). Each branch receives exactly one group: the production branch receives `production`, any other branch the custom group with the most precise matching rule, or else `preview`. Groups do not combine. A group's **class** is a field of the group that names its kind: `production`, `preview` or `custom`. It is not the old class of a row, which had only the values `production` and `preview`. ### Service variable -Prisma Cloud's term for a value stored on one service, set through the create-deployment request or Console, and deleted with the service. It wins over the branch's group and override. Composer does not read or write one yet. This is the platform's planned model and not yet live. +Prisma Cloud's term for a value stored on one platform service, which is one Composer [service](#service) in one environment (`Prisma.App` in code). It is set only when a deployment is created, through the create-deployment request, which Console's "Save and Deploy" sends, and is deleted with the platform service. It wins over the branch's group and overrides. Composer does not read or write one yet. ### Value resource diff --git a/docs/design/05-prisma-cloud/pdp-data-model.md b/docs/design/05-prisma-cloud/pdp-data-model.md index 422745566..2b3d13141 100644 --- a/docs/design/05-prisma-cloud/pdp-data-model.md +++ b/docs/design/05-prisma-cloud/pdp-data-model.md @@ -109,15 +109,15 @@ Consequences Prisma Composer designs around: preview-class with that Branch's overrides. Under variable groups (below), a Branch receives one group in place of a class. -## Variable groups — the platform's planned model +## Variable groups -Prisma Cloud is moving variables into groups. This is designed in `projects/compute-env-var-groups/proposal.md` on the `pdp-control-plane` branch `chore/compute-env-var-groups-proposal`, and is not live yet. What Composer depends on: +Prisma Cloud keeps variables in groups. What Composer depends on: -- **Variable groups.** Every project has a `production` group and a `preview` group, holding the rows the two classes hold today. A project can add custom groups, each with one rule on a branch's git name: `equals` or `startsWith`. +- **Variable groups.** Every project has a `production` group and a `preview` group, holding the rows the two old row classes held. A group's class (`production`, `preview` or `custom`) names its kind and is not a row's old class. A project can add custom groups, each with one rule on a branch's git name: `equals` or `startsWith`. - **One group per branch.** The production branch receives `production`. Any other branch receives the custom group with the most precise matching rule, or else `preview`. Groups do not combine. -- **Service variables.** Values stored on one service, set only through the create-deployment request, deleted with the service. +- **Service variables.** Values stored on one platform service, which is one Composer service in one environment. They are set only when a deployment is created, through the create-deployment request, which Console's "Save and Deploy" sends, and are deleted with the platform service. - **The order a deployment receives values:** every value of its branch's group, then the branch's overrides, then the service's variables. Later wins. The map is still frozen into the version when it is created. -- **Branch overrides are being removed.** Three months after the platform work merges, a write that names a branch is rejected. Existing override rows keep applying until their branch is deleted. +- **Branch overrides are being removed.** The platform is removing branch overrides: after a notice period, it rejects a write that names a branch. Existing overrides keep applying until their branch is deleted. - **The resolved-variables read.** `GET /v1/projects/{projectId}/resolved-variables?branchId=…` returns the group the branch receives (`id`, `name`, `class`) and every key the branch receives, each with `updatedAt`, `isManagedBySystem` and a `source` (`group`, `branchOverride` or `service`). It returns no values and does not paginate. Deploy preflight reads it once per deploy ([ADR-0064](../90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). ## Related diff --git a/docs/design/10-domains/deploy-cli.md b/docs/design/10-domains/deploy-cli.md index 8e41bfd8d..5e329e170 100644 --- a/docs/design/10-domains/deploy-cli.md +++ b/docs/design/10-domains/deploy-cli.md @@ -159,7 +159,7 @@ bun APIs can only deploy under bun, since loading the graph imports that module emulator instance is touched. On `deploy`, an older extension's `ensure` may already have created the app's Project by then; the check stops everything after that. -9. **Preflight (`deploy` only).** Each extension's `preflight` checks its platform prerequisites before Alchemy runs. The Prisma Cloud preflight checks that every platform variable a service needs has a value, and sets none. A variable a service requires that has no value fails the deploy with `DEPLOY.PREFLIGHT_FAILED`, naming the services that read it and the `prisma project env add` commands that set it. The CLI lists the other variables with no value after the step, under `Platform variables with no value:`, and again at the end of the deploy report. The platform reports a service that exits at boot as running and promotes it, so this step is the only check Composer makes for a missing value ([ADR-0064](../90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). +9. **Preflight (`deploy` only).** Each extension's `preflight` checks its platform prerequisites before Alchemy runs. The Prisma Cloud preflight checks that every platform variable a service needs has a value, and sets none. A variable a service requires that has no value fails the deploy with `DEPLOY.PREFLIGHT_FAILED`, naming the services that read it and how to set it: a `prisma project env add` command for the `production` or `preview` group, or for a custom group a sentence naming the group and the Prisma Console. The CLI lists the other variables with no value after the step, under `Platform variables with no value:`, and again at the end of the deploy report. The platform reports a service that exits at boot as running and promotes it, so this step is the only check Composer makes for a missing value ([ADR-0064](../90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). 10. **Lower and apply.** `deploy` calls core's `lower()` with the pipeline's results as values: the name, the environment, what Load read from the app configuration (`appConfigurationRead`), the graph's node addresses, the assembled bundles, every resolved container, every extension's preflight payload, the platform variables with no value that preflight found (`findings`), and the report hook. It passes the stack value `lower()` returns to `Alchemist.plan` and then `Alchemist.apply`, in the `prisma` process, with Alchemy's stage set as § CLI behavior notes describes ([ADR-0066](../90-decisions/ADR-0066-deploy-runs-alchemy-in-process.md)). No stack file is written and no child is started. - **Progress.** Alchemy's typed events become step events under the `deploy.apply` step: one step per resource, labelled with Alchemy's status word (`creating shop.api`, then `created shop.api`), and Alchemy's log lines become messages, with every known secret and credential-looking value removed (ADR-0062). Human and JSON output keep one format. Alchemy's console output is replaced, its terminal text becomes redacted message events, and the `prisma deploy` command sends every `console` method to stderr, redacted, while the operation runs. A provider that writes to `process.stdout` directly is out of reach. - **Result.** The report hook runs inside the apply, in the same process, so the deployment summary comes back as a value. diff --git a/docs/design/10-domains/local-dev.md b/docs/design/10-domains/local-dev.md index cf99a7170..6e5171100 100644 --- a/docs/design/10-domains/local-dev.md +++ b/docs/design/10-domains/local-dev.md @@ -552,7 +552,7 @@ The worker thread of a `prisma dev` converge runs no adapter. The main thread pa A rebuild runs no dev preflight, so a read of a platform variable that a code change adds would have no value. `prisma dev` therefore sends each converge's worker thread the reads of the graph it started with (`valueReads`: reader, node and path) and each read node's address and `props`. The worker, which has just loaded the app as it is on disk, compares them with its own graph's before it converges. If either differs, it does not converge; `prisma dev` emits the `value-reads-changed` event with the nodes whose reads were added, removed or changed, and pauses rebuilds until it is restarted. If the first converge sees a difference, which usually means an app file changed while `prisma dev` was starting, and otherwise that a module body builds a different graph each time it runs, `prisma dev` stops and names the reads that changed. For a rebuild the CLI prints a warning: `The platform variables the app reads changed since dev started: reads of "shop.smtpPort" were added, reads of "shop.emailFrom" were removed, and "shop.sender" was changed. Restart dev to apply them; rebuilds are paused until then.` An edit that adds or removes a node fails the rebuild with a message that says to restart `prisma dev`. -The local `Deployment` provider gives each service only the variables its own input reads: the `$platform` markers in its input document, at any depth. For a service that runs its artifact, it reads the input document for this from the unpacked artifact's `compute.bootstrap.json`, with the reader `@internal/lowering` exports next to the packer. It ignores a `COMPOSER_
_INPUT` entry in `env.json` for such a service, whether or not the artifact holds a document, and does not put that key into the process's environment, because the artifact's bootstrap passes the document to `run()`. For a service that runs a dev server, which has no artifact, the compute descriptor's `reserve` writes the input document as a `COMPOSER_
_INPUT` variable, which the local target keeps in `env.json` with the service's other rows. This isolation is a requirement of the local target only. On Prisma Cloud every deployment receives every variable of its class. +The local `Deployment` provider gives each service only the variables its own input reads: the `$platform` markers in its input document, at any depth. For a service that runs its artifact, it reads the input document for this from the unpacked artifact's `compute.bootstrap.json`, with the reader `@internal/lowering` exports next to the packer. It ignores a `COMPOSER_
_INPUT` entry in `env.json` for such a service, whether or not the artifact holds a document, and does not put that key into the process's environment, because the artifact's bootstrap passes the document to `run()`. For a service that runs a dev server, which has no artifact, the compute descriptor's `reserve` writes the input document as a `COMPOSER_
_INPUT` variable, which the local target keeps in `env.json` with the service's other rows. This isolation is a requirement of the local target only. On Prisma Cloud every deployment receives every variable of its branch's group. To load `.env` files, list `dotenv()` in `config` and `secrets`, with `environmentVariables()` after it to keep the shell. It reads `.env`, `.env.local`, `.env.` and `.env..local` beside `prisma.config.ts`, through `dotenv-flow`, and skips `.env.local` for the environment `test`. Values in `.env.dev` are read only by the environment `dev`; values in `.env` and `.env.local` are read by every environment, `prisma deploy` to `production` included. The deploy does not copy a secret to the platform, but a plain value there reaches the root's input in every environment. `import 'dotenv/config'` at the top of `prisma.config.ts` still works with the default lists; remove it when you list `dotenv()`. diff --git a/docs/design/90-decisions/ADR-0029-a-secret-is-an-environment-sourced-value-the-framework-never-stores.md b/docs/design/90-decisions/ADR-0029-a-secret-is-an-environment-sourced-value-the-framework-never-stores.md index 973f04abb..0c7932f7e 100644 --- a/docs/design/90-decisions/ADR-0029-a-secret-is-an-environment-sourced-value-the-framework-never-stores.md +++ b/docs/design/90-decisions/ADR-0029-a-secret-is-an-environment-sourced-value-the-framework-never-stores.md @@ -34,7 +34,7 @@ Three pieces carry the model: At boot the framework swaps each pointer for a redacting box over the named variable, which the platform injects into the running instance. A variable that is unset or empty leaves its field out, and the schema decides whether that is allowed ([ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). -**The operator sets the variable on the platform; preflight only checks it.** The deploy does not copy a value from the app secrets or the shell to the platform ([ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). Before Alchemy runs, deploy preflight checks whether each platform secret in the graph has a row the environment sees, also one no service reads. It reads no value and writes no variable. A missing variable that a service's schema requires fails the deploy, naming the variable, its readers and the `prisma project env add` commands that set it. A missing one nothing requires is listed and the deploy goes on ([ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). To change a value, change it on the platform and deploy again. +**The operator sets the variable on the platform; preflight only checks it.** The deploy does not copy a value from the app secrets or the shell to the platform ([ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). Before Alchemy runs, deploy preflight checks that each platform secret in the graph, also one no service reads, has a value the environment's branch receives. It reads no value and writes no variable. What it does with a missing one is in [ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md). To change a value, change it on the platform and deploy again. **Composer redacts every secret it knows.** Everywhere it prints, including errors, events, adapter failures, a thrown defect's cause chain and the deploy engine's failure cause, Composer replaces with `[redacted]` the value under each secrets key of the graph's secret sources (`variable.secret({ name: 'NAME' })` passes `NAME`), in the app configuration and in the app secrets. Every platform secret the root provisions is one of them, also when nothing binds it. Nothing else in the app secrets is a known secret. A known value is redacted at any length. When two known secrets overlap, it hides every character either one covers. Nothing is redacted by the known secrets before Load has named them: an adapter that throws, and a root schema failure that echoes a field's value, are redacted only by the credential-looking rule. Whether the deploy engine's own output is redacted depends on who runs it ([ADR-0062, "Alchemy's output"](ADR-0062-environment-values-come-from-resolve-and-config-adapters.md#keeping-secrets-out)). Composer also redacts values that look like credentials: a value of eight characters or more under a name that looks like a credential, in the app configuration or the process environment, bearer and basic tokens, JWTs, a password in a URL and `token=` pairs. diff --git a/docs/design/90-decisions/ADR-0058-prisma-dev-reads-secrets-from-the-app-secrets-and-never-invents-them.md b/docs/design/90-decisions/ADR-0058-prisma-dev-reads-secrets-from-the-app-secrets-and-never-invents-them.md index 0283efd54..beef41c63 100644 --- a/docs/design/90-decisions/ADR-0058-prisma-dev-reads-secrets-from-the-app-secrets-and-never-invents-them.md +++ b/docs/design/90-decisions/ADR-0058-prisma-dev-reads-secrets-from-the-app-secrets-and-never-invents-them.md @@ -31,7 +31,7 @@ Under `prisma dev`, a platform secret's value comes only from the app secrets, a - **Plain platform variables get the same sourcing.** For each plain platform variable node a service reads, the dev preflight reads the app configuration under the variable's name, once. A platform variable is read only through a field of a service's input. An unset or empty value is left out of the input document, like an unset secret, and the same validation decides whether the service needs it. A value that is not text stops `prisma dev` before any service starts, naming the variable, the node, the services that read it and the kind of value. The dev preflight then decodes and validates each text by the variable's schema, once per variable, with the code boot runs ([ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). A text that does not decode or fit stops `prisma dev` before any service starts, with the message boot would give followed by `prisma dev cannot start, because service "shop.mail" reads it.`, or `because services "shop.mail" and "shop.digest" read it.` with several readers. Like secrets, these values are read fresh each run and fingerprinted, so a changed value redeploys the services that read it. - **The second process receives the values; it reads none.** `prisma dev` runs Alchemy in a second process at start and at each rebuild. That process runs no adapter. It reads what Load read from the app configuration, the text of each plain platform variable a service reads (`plainVariableText`), and the first process's node addresses, from the app configuration file, `/app-configuration-.json`, readable only by its owner, which `prisma dev` writes before each converge and deletes as soon as that converge ends. `prisma dev` keeps the texts the dev preflight found at start and writes them on the first converge and on every rebuild. Before writing the file it checks every plain value in it, each `plainVariableText` member included, against the known secrets, and a plain value that holds a secret's value fails with `CONFIG.SECRET_AS_PLAIN_VALUE`. The second process passes `plainVariableText` to the local target, which fills each plain `$platform` marker from it. It receives the named secrets, the values under the secrets keys of the graph's secret sources, which are the platform secret nodes, in one environment variable, `PRISMA_COMPOSER_NAMED_SECRETS`, in memory; no secret is written to a file for it. - **The dev preflight hands the second process a payload.** It travels on the preflight transport that carries deploy's rotation timestamps (`PRISMA_COMPOSER_PREFLIGHT_`), with a `dev:` prefix that a deploy payload, always a JSON object, never starts with. It names the absent platform variables, plain and secret (`absentVariables`), and carries a fingerprint of the current value of each variable a service's input document names, never the value. The serializer leaves a platform variable out of the input document only when this payload names it absent. -- **Each local service gets only the variables its own markers name**: the `$platform` markers in its input document, at any depth. This is a requirement of the local target. On Prisma Cloud every deployment receives every platform variable of its class ([ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). A service that runs a dev server ([ADR-0056](ADR-0056-prisma-dev-runs-a-service-with-its-build-adapters-dev-server.md)) is given the same environment, and a changed value restarts it. +- **Each local service gets only the variables its own markers name**: the `$platform` markers in its input document, at any depth. This is a requirement of the local target. On Prisma Cloud every deployment receives every platform variable of its branch's group ([ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). A service that runs a dev server ([ADR-0056](ADR-0056-prisma-dev-runs-a-service-with-its-build-adapters-dev-server.md)) is given the same environment, and a changed value restarts it. - **A changed value redeploys the services that read it.** Each `Deployment`'s triggers carry a `:updatedAt` member per variable its input document's markers name. On a hosted deploy it holds the platform variable's `updatedAt`. Under `prisma dev` it holds the fingerprint from the payload: an HMAC-SHA256 of the value under a random 32-byte key that `prisma dev` creates once in `.prisma-composer/dev//fingerprint.key` (mode 0600). Alchemy writes trigger members to its state as given, which is why the fingerprint is keyed: a bare hash of a short secret could be reversed by guessing. A lost key causes one redeploy, and `--fresh` deletes it. - **A changed adapter value pauses rebuilds.** When what the adapters return at a rebuild differs from what they returned at start, `prisma dev` keeps the values it started with and stops rebuilding until it is restarted, as it does after an edit to `prisma.config.ts`. - **A change to what the app reads pauses rebuilds.** A rebuild runs no dev preflight, so a read the change adds would have no value. When the rebuilt graph's reads of platform variable nodes, or the read nodes' `props`, differ from those at start, `prisma dev` does not converge, emits `value-reads-changed`, warns that the platform variables the app reads changed, and pauses rebuilds until it is restarted ([ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). A rebuild reloads the app's modules as they were at start in the first process, so today this fires only when the graph the first process loads changes. diff --git a/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md b/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md index 0b3ad3596..2fba87d82 100644 --- a/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md +++ b/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md @@ -44,10 +44,10 @@ The environment's facts, such as `environment.name`, and the values Composer cre ### What Prisma Cloud does - **A variable is a row in a project.** A row has a `key` and a `value`, and belongs either to a **variable group** or to one branch, as that branch's override. Prisma Cloud calls these rows environment variables. -- **Variable groups.** Every project has a `production` group and a `preview` group, which hold what the `production` and `preview` classes held before groups. A project can add custom groups, each with one rule on a branch's git name. A group's class is `production`, `preview` or `custom`. +- **Variable groups.** Every project has a `production` group and a `preview` group, which hold what the `production` and `preview` classes held before groups. A project can add custom groups, each with one rule on a branch's git name. A group's class names its kind: `production`, `preview` or `custom`. It is not the old class of a row. - **A branch receives exactly one group.** The production branch receives `production`. Any other branch receives the custom group whose rule matches its name most precisely, or else `preview`. Groups do not combine: a branch on a group named `staging` receives nothing from `preview`. -- **The order of values.** A deployment receives every value of its branch's group, then that branch's overrides, then the **service variables** stored on its service, which Console sets. Later wins. The platform copies the values into the deployment when it creates it and never reads them again, so a value set later reaches a service only at its next deployment. A group or an override reaches every service on the branch, its own and other services' alike. -- **Branch overrides are being removed.** Three months after the platform work merges, it rejects a write that names a branch. Existing overrides keep applying until their branch is deleted. +- **The order of values.** A deployment receives every value of its branch's group, then that branch's overrides, then the **service variables** stored on its platform service, which is one Composer service in one environment. A service variable is set only when a deployment is created, through the create-deployment request, which Console's "Save and Deploy" sends. Later wins. The platform copies the values into the deployment when it creates it and never reads them again, so a value set later reaches a service only at its next deployment. A group or an override reaches every service on the branch, its own and other services' alike. +- **Branch overrides are being removed.** The platform is removing branch overrides: after a notice period, it rejects a write that names a branch. Existing overrides keep applying until their branch is deleted. - **One read answers what a branch receives.** `GET /v1/projects/{projectId}/resolved-variables?branchId=…` returns the group the branch receives and every key the branch receives, each with `updatedAt`, `isManagedBySystem` and a `source`. It returns no values and does not paginate. - **A key is upper case or it does not exist.** The platform refuses a key that does not match `[A-Z_][A-Z0-9_]*`, on write and in the list filter. - **A value is never empty.** The platform refuses an empty value, so a variable is either present with text or absent. @@ -218,8 +218,8 @@ Preflight runs after the deploy has resolved the app's Project and Branch, and b - **The names it checks.** Every platform variable, plain or secret, in a service's input binding, at any depth, found from the same walk of each binding, without serializing the service; and every platform variable node no service reads, which are the value resources not in `graph.valueReads`. An invalid input still fails after preflight reports the platform variables. The deploy preflight reads nothing from the app configuration. - **One read per deploy.** When the app names at least one platform variable, preflight makes one resolved-variables read for the environment's branch: the environment's own branch, or for `production` the project's default branch, whose id the deploy already holds. An app that names none makes no call. A name is present when the read lists its key. Its `updatedAt` is the trigger value. The entry's `source` is not consulted: a group value and a branch override both reach every service on the branch. -- **A failed read fails the deploy.** A 404 for the project or the branch, or any other error, stops the deploy with a message that names the call, the HTTP status, the project and the branch, and says the platform may not offer this read yet. There is no fallback to a per-name lookup, because that lookup gives wrong answers on a custom group. -- **A paged answer fails the deploy.** An answer that carries a pagination field or a cursor stops the deploy with a message that says this Composer version is too old for the platform. A version that read only the first page would report the rest missing, and older lines get no patch releases. +- **A failed read fails the deploy.** An error status, a network failure, or a body that is not JSON or not the expected shape stops the deploy with a message that names the call, the project and the branch, and the HTTP status when there is one. Only a 404 adds that the platform may not offer this read yet; a body of the wrong shape says the platform's answer may have changed. There is no fallback to a per-name lookup, because that lookup gives wrong answers on a custom group. +- **A paged answer fails the deploy.** An answer that says it has more, with `hasMore: true` or a non-empty `nextCursor` or `cursor`, at the top level or inside `pagination`, stops the deploy with a message that says this Composer version is too old for the platform. A version that read only the first page would report the rest missing, and older lines get no patch releases. A complete answer in the platform's list envelope, such as `pagination: { nextCursor: null, hasMore: false }`, is accepted. - **A system key is refused.** A listed key with `isManagedBySystem: true` fails the deploy, naming the variable. - **A value set on one service is not seen.** Preflight asks about the branch, not about each service. A variable a service requires that is set only as that service's service variable fails the deploy as missing, and the hint says to set it in the group. A deployment that Console creates with "Save and Deploy" is replaced as live by the next `prisma deploy`. This gap is known and left open. - **Required or reported, per service.** For each service that reads a variable with no value, preflight serialises the input with every variable present and runs the service's schema. A failure there is an invalid input, reported as such and never blamed on a variable. Then it runs the schema with every variable that has no value left out. If that passes, those variables are optional for that service. If it fails, it leaves out each one alone, and the ones whose absence alone fails are required. When no single one fails alone, the error says the service needs at least one of them. A variable an array position reads is required without a check. This is the method [ADR-0058](ADR-0058-prisma-dev-reads-secrets-from-the-app-secrets-and-never-invents-them.md) gives the dev preflight, and both preflights call the same code. @@ -234,7 +234,7 @@ Preflight runs after the deploy has resolved the app's Project and Branch, and b - prisma project env add 'EMAIL_API_KEY=' --project 'proj_…' --role preview ``` - The hint follows the class of the group the branch receives: `--role production` for `production`, `--role preview` for `preview`. For a custom group it is a sentence that names the group, quoted for the shell, and says to set the value there in the Prisma Console, because no released CLI command writes to a custom group yet. No hint writes a branch override, which the platform is removing. A variable that an array position makes required has a second line with the reason, and a line for a service that needs some of several variables ends with the schema's message. + The hint follows the class of the group the branch receives: `--role production` for `production`, `--role preview` for `preview`. For a custom group, or a group of any class Composer does not know, it is a sentence that names the group in double quotes and says to set the value there in the Prisma Console, because no released CLI command writes to a custom group yet. `UnsetPlatformVariable.commands` carries it; core documents each line as a shell command where one exists, otherwise an instruction. No hint writes a branch override, which the platform is removing. A variable that an array position makes required has a second line with the reason, and a line for a service that needs some of several variables ends with the schema's message. - **The findings.** Every variable with no value that nothing requires is listed, with its readers (a service and field, or the node that names it and that no service reads it) and the commands that set it. `PreflightInput.report` takes a `PlatformVariableCheck`: the count of platform variables checked and this list, names and readers only, never a value. It carries platform-variable findings and that count, nothing else. The deploy prints the list right after the preflight step, under `Platform variables with no value:`. With `--json` it is a message whose data holds the list, and `onEvent` receives it as a `preflight-findings` event. The step's data stays `{ checked, unset }`, two counts. The deploy hands the list to `lower()` as a value, `LowerOptions.findings`, and lowering puts it into `DeploymentResult.findings`; `prisma deploy` repeats it at the end of its report ([ADR-0066](ADR-0066-deploy-runs-alchemy-in-process.md)). An extension's own preflight payload never carries it. - **Triggers.** Each service's deployment triggers carry `:updatedAt` for each platform variable its input document points at, with `?` when the variable has no value. Changing a value on the platform and deploying again replaces exactly the deployments that read it. @@ -262,7 +262,7 @@ The local target plays the platform's part. **A secret is a fact about Composer and the service, not about the platform.** The platform encrypts every row and returns no value, so it handles a secret and a plain value alike. The difference matters in four places inside Composer. In a binding, a platform secret fits only a secret field and arrives boxed, while a plain value fits only a `field()` field. In output, Composer redacts a secret's value wherever it prints; it must not redact a plain value such as `587`. In boot errors, a plain value's expected form may be described, while a secret is never decoded, so a secret's error says nothing about its content. Under `prisma dev`, a platform secret comes from the app secrets and a plain variable from the app configuration. So the node says which kind it is, and the platform needs nothing for it. -**An implicit copy moves a local value to a remote environment.** A deploy that copies a missing variable from the app secrets or the app configuration to the platform can carry a developer's test key to production, because `.env` is read for every environment. Copying on each deploy also writes one override row per preview branch. Until the operator can say explicitly which value goes to which environment, the operator sets each value on the platform, in the scope the operator chooses. +**An implicit copy moves a local value to a remote environment.** A deploy that copies a missing variable from the app secrets or the app configuration to the platform can carry a developer's test key to production, because `.env` is read for every environment. Copying on each deploy also writes one override row per preview branch. Until the operator can say explicitly which value goes to which environment, the operator sets each value on the platform, in the group the operator chooses. **Preflight is the only protection against a missing value.** The platform promotes a deployment whose process exits at boot and reports it running. So a deploy that succeeded with a required variable unset would leave a crashing service in place. Preflight refuses the case it can see without a value: the service's own schema says the variable is needed. @@ -309,7 +309,7 @@ The local target plays the platform's part. - **Copy local values on deploy.** Rejected: an implicit copy is how a local value reaches a remote environment by accident. - **Succeed with every variable unset, and report.** Rejected: the platform promotes a service that exits at boot and reports it running, so the deploy would leave it crashing. Preflight refuses the case the schema can show without a value. - **One list call per name, filtered by class and key**, with the branch row winning over the class row. This was the lookup before variable groups. Replaced: it cannot see a custom group, and on a branch that receives one it reports the wrong answer both ways. -- **Two list calls per name, one per scope.** Rejected for the same reason. +- **Two list calls per name, one for the class row and one for the branch override.** Rejected for the same reason. - **The newest row's `updatedAt` as the trigger.** Rejected: a change to a value under a branch override would redeploy a service whose value did not change. The read gives the `updatedAt` of the value the branch receives. - **Fall back to the per-name lookup when the read fails.** Rejected: it brings back the wrong answers without a word. - **Send no `branchId` for production and rely on the read's default.** Rejected: the deploy already holds the default branch's id, and sending it removes a platform behaviour Composer would otherwise depend on. @@ -319,7 +319,7 @@ The local target plays the platform's part. - **A platform variable as a property of an input field,** such as `field(type('number'), { env: 'SMTP_PORT' })`. Rejected: a value the operator must set is part of the topology, so it is a node. - **A platform variable node anywhere in the tree.** Rejected: a nested module naming one claims the name for every app and instance, and hides from its input what it needs. - **Two nodes for one name reconciled when they agree.** Rejected: with root-only nodes, two declarations of one name are two lines in one body, and refusing them is simpler. -- **The node declares its scope,** such as `variable({ name, scope: 'service' })`. Rejected: where a value lives is the operator's decision in the platform's terms, not the author's. +- **The node declares its scope,** such as `variable({ name, scope: 'service' })`, where the scope is the level at which the value is set. Rejected: where a value lives is the operator's decision in the platform's terms, not the author's. - **`provision()` returning `{ id, value }`.** Rejected: the value itself with `id` on it matches `generatedParam()` and `serviceOrigin()`, so a binding reads `{ from, apiKey }`. - **Resource outputs as a new core concept, with Load asking the target for the pointer.** Rejected: core already has the source, which carries the secrets key that redaction and `prisma dev` need; "output" already means Alchemy's attributes and the retired name for the end of a connection; and Load calling a target would be core's first dependency on one. - **No descriptor for the node**, with core skipping it in lowering and registry coverage. Rejected: it would add a special case to the one lookup every node goes through ([ADR-0017](ADR-0017-control-plane-loads-through-the-app-config.md)). The descriptor creates nothing instead. diff --git a/docs/design/90-decisions/README.md b/docs/design/90-decisions/README.md index ae7515f96..053b67b4c 100644 --- a/docs/design/90-decisions/README.md +++ b/docs/design/90-decisions/README.md @@ -85,7 +85,7 @@ _Earlier drafts (ADR-0001, ADR-0002) were retired as the high-level design settl - [ADR-0061](ADR-0061-a-module-declares-its-input-as-a-compute-service-does.md) — A module declares its input as one Standard Schema, `input`, exactly as a compute service does, and whoever provisions it binds that input with a binding typed from the schema. The body receives `input` as a dictionary with one value per field; it passes fields on by name, or lists a plain field in `resolve()`, and never reads their data, so the graph cannot branch on its input. The dictionary itself is not a value: passing it on whole fails to compile and fails at Load, for every module. A field that may receive a value known only at boot, such as a platform variable's, is wrapped in `field()`; a secret is a `secretString()` field. The module `params`/`paramNeed()` and `secrets`/`secret()` slots are removed. The root may declare `input`, bound to the app configuration. - [ADR-0062](ADR-0062-environment-values-come-from-resolve-and-config-adapters.md) — The graph's structure is the same whatever inputs Composer is given; only values differ per environment. A module body holds values (`Value`), opaque stand-ins for data known later: deploy-time values, whose data the deploy has by the end of Load, and runtime values (`RuntimeValue`, which is `Value>`), whose data only the platform holds. A runtime value comes from a target's source, from a value resource (a resource node that is also a value, which only the app root can provision, enforced by the compiler), or from a module input bound to one; `provision()` returns the value with the node's address on it, and the graph's `valueReads` lists each service that reads each value resource. `resolve(dependencies, fn)` computes a value from deploy-time values only; `fn` never sees a pointer. Config adapters produce the app configuration, which fills the root's input; no source reads it, so a value the deploy reads is a root input field. Secrets adapters produce the app secrets, which `prisma dev` gives its services and which Composer redacts; the deploy does not copy either to platform variables, which the operator sets on the platform. Both lists default to `[environmentVariables()]`; `dotenv()` reads `.env` files through `dotenv-flow`. Only the first process runs adapters, once per deploy; the second reads the app configuration file and refuses a graph whose node addresses differ. Secrets stay out through pointers and redaction. Every environment has a name and none is special. *(Amended by ADR-0066: `deploy` runs Alchemy in its first process and writes no app configuration file; the second process applies to `prisma dev` and `destroy`.)* *(Amended by ADR-0067: `prisma dev` writes no app configuration file.)* *(Amended by ADR-0068: no command starts a second process or writes an app configuration file.)* - [ADR-0063](ADR-0063-a-node-depends-on-an-interface-or-exposes-one.md) — The two ends of a connection are named by what the node does with them: a node **depends on** an interface (`deps`) or **exposes** one (`expose`); an interface is a `Contract` in code; Input and Output are retired as port words, because the dataflow and ports-and-adapters traditions give the same two ends opposite names; the module body's `inputs` becomes `deps`; the topology's `in`/`out` stay, defined as the dependency end and the exposed end. A service also reads a platform variable, a third relationship recorded in `valueReads`, not as an edge. -- [ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md) — A platform variable is a variable on the platform that a service reads by name at boot, declared by a node the app root provisions: `variable({ name })` or `variable.secret({ name })`. A value the operator supplies reaches the app in two ways: a root input field for a value the deploy reads, a platform variable node for a value the service reads at boot. The node creates nothing and stays out of the application topology and the deploy report; the graph check refuses two nodes with one name, a plain node and a root input field with one name, and a node bound as a service's whole input. The deploy does not copy local values (by default `.env` and the shell) to platform variables, because an implicit copy can push a local value into a remote environment; for now the operator sets each on Prisma Cloud, in the variable group the environment's branch receives, and an explicit way through `deploy` is expected later. Before Alchemy runs, the deploy asks Prisma Cloud once which variables the environment's branch receives, checks that every variable a service needs has a value, and fails with what sets the missing ones; a failed or paged read fails the deploy. Under `prisma dev` a plain variable comes from the app configuration. `variable({ name, schema })` types a plain variable's value by a Standard JSON Schema such as ArkType's or Zod's: the node keeps the reduced JSON Schema, and boot and `prisma dev` decode and validate the variable's text with it, with messages that never hold the text. Variable names match `^[A-Z][A-Z0-9_]*$`, and a few names are reserved for Composer and the platform. *(Amended by ADR-0067: plain platform variable text reaches the local target in memory.)* +- [ADR-0064](ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md) — A platform variable is a variable on the platform that a service reads by name at boot, declared by a node the app root provisions: `variable({ name })` or `variable.secret({ name })`. A value the operator supplies reaches the app in two ways: a root input field for a value the deploy reads, a platform variable node for a value the service reads at boot. The node creates nothing and stays out of the application topology and the deploy report; the graph check refuses two nodes with one name, a plain node and a root input field with one name, and a node bound as a service's whole input. The deploy does not copy local values (by default `.env` and the shell) to platform variables, because an implicit copy can push a local value into a remote environment; for now the operator sets each on Prisma Cloud, in the variable group the environment's branch receives, and an explicit way through `deploy` is expected later. Before Alchemy runs, the deploy asks Prisma Cloud once which variables the environment's branch receives, checks that every variable a service needs has a value, and fails with what sets the missing ones; a failed read, or one that says it has more pages, fails the deploy. Under `prisma dev` a plain variable comes from the app configuration. `variable({ name, schema })` types a plain variable's value by a Standard JSON Schema such as ArkType's or Zod's: the node keeps the reduced JSON Schema, and boot and `prisma dev` decode and validate the variable's text with it, with messages that never hold the text. Variable names match `^[A-Z][A-Z0-9_]*$`, and a few names are reserved for Composer and the platform. *(Amended by ADR-0067: plain platform variable text reaches the local target in memory.)* - [ADR-0065](ADR-0065-a-compute-services-input-document-travels-in-its-artifact.md) — On Prisma Cloud the deploy writes a Compute service's input document into its artifact, in the `inputDocument` field of `compute.bootstrap.json`, and creates no variable for it; every other value the service reads at boot (`port`, connection params, provider params, generated values) stays a variable, because each is issued during the deploy or is a secret, except `port`, which the Compute emulator has to be able to set under `prisma dev`. The printed `bootstrap.js` passes the document to the Prisma Cloud service's `run(address, boot, inputDocument)`; core's `run` keeps two parameters. The artifact is the document's only source: `run()` ignores a `COMPOSER_
_INPUT` variable when the artifact holds the document, which the upgrade needs today, and the local target ignores one for every service that runs its artifact. A changed document changes the artifact's path and replaces the deployment; the document is not a trigger member, a platform variable it names still is. Under `prisma dev` the local `Deployment` provider reads the document with the packer's own reader to decide which platform variables a service receives, and `reserve` writes it as a variable for a dev server. `package` must not write a secret or an unresolved value into an artifact. A deployment made before the upgrade cannot be put back into service. Rejected: keeping every value a variable (8 KB limit), a general map of keys in the boot file, the document as parsed JSON, the environment winning, and writing both places for one release. - [ADR-0066](ADR-0066-deploy-runs-alchemy-in-process.md) — `prisma deploy` and the `deploy` operation run Alchemy's plan and apply in the `prisma` process through `alchemy/Alchemist`: no generated stack file, no Alchemy child. `lower()` takes containers, preflight payloads, the preflight findings and the report hook as values, the summary comes back as a value, Alchemy's events become engine step events, failures are `DEPLOY.ENGINE_FAILED` or `DEPLOY.INTERRUPTED`, and Ctrl-C releases the state lease. Every Management API request, Alchemy's and Composer's, goes through the engine's `ctx.api`, which `lower()` receives as `LowerOptions.credentials`, so a `prisma login` session deploys with no `PRISMA_SERVICE_TOKEN` and no credential enters `process.env`. Lowering and Alchemy load from the app's own install of `@prisma/composer`, which must speak the host's converge contract. Supersedes ADR-0007 for `deploy`; amends ADR-0038, ADR-0043, ADR-0044, ADR-0049, ADR-0062 and ADR-0064. *(Extended to `prisma dev` by ADR-0067.)* *(Extended to `destroy` by ADR-0068: `containers` and `preflightPayloads` are required, with no environment fallback.)* - [ADR-0067](ADR-0067-prisma-dev-converges-in-a-worker-thread.md) — Each converge of `prisma dev` runs in a new worker thread of the `prisma` process: no dev stack file, no app configuration file, no Alchemy child. The worker imports the config and the app as they are on disk, so an edit to an app definition file applies on the next rebuild; a loaded app is made of functions and cannot be handed between threads, so the import and the converge run in the same place. The main thread sends plain data in memory (values, named secrets, containers), holds the one-converge flag and the working directory for the worker, and reports its events and redacted output. Three kinds of edit still need a restart: adding or removing a node, passing on a root input field the root did not pass on at start, and changing which platform variables the app reads; under Bun, so does a directory import written before its `index.ts` exists. `destroy` keeps the stack file and the child. *(Amended by ADR-0068: `destroy` runs in process too.)* diff --git a/docs/guides/deploying.md b/docs/guides/deploying.md index ea9b0b3aa..cad54ac58 100644 --- a/docs/guides/deploying.md +++ b/docs/guides/deploying.md @@ -237,7 +237,7 @@ dependencies are traced and copied into the deploy artifact (see Inside `plan and apply`, each resource the deploy engine creates, updates or deletes is a step of its own, such as `▸ creating storefront-auth.web` and `✔ created storefront-auth.web (12.0s)`, and the engine's log lines print between them. The last line is the whole deploy, from start to finish. -With `--json`, each step is a `step-started` and a `step-finished` line on stdout, followed by an `endpoint` line per public URL and the `result` line. A `step-finished` line carries `data.durationMs`. An assemble step's `data` also holds whatever the service's build adapter reports, and the `check environment variables` step's `data` holds `checked` and `unset`, how many platform variables it checked and how many have no value. When some have no value and no service needs them, a `message` line follows the step, whose `data.unset` lists each one with its readers and commands ([Platform variables](#platform-variables)). The build adapter's fields vary by adapter, so read them as information, not as a stable format. The `result` line has the deploy's total `durationMs` beside `summary`, whose `findings.unset` lists the platform variables with no value again. +With `--json`, each step is a `step-started` and a `step-finished` line on stdout, followed by an `endpoint` line per public URL and the `result` line. A `step-finished` line carries `data.durationMs`. An assemble step's `data` also holds whatever the service's build adapter reports, and the `check environment variables` step's `data` holds `checked` and `unset`, how many platform variables it checked and how many have no value. When some have no value and no service needs them, a `message` line follows the step, whose `data.unset` lists each one with its readers and how to set it: a shell command, or for a custom group an instruction ([Platform variables](#platform-variables)). The build adapter's fields vary by adapter, so read them as information, not as a stable format. The `result` line has the deploy's total `durationMs` beside `summary`, whose `findings.unset` lists the platform variables with no value again. A deploy ends by printing your app's own topology — the names you authored, what each one became on the platform, and the public URLs: @@ -302,7 +302,7 @@ The platform copies the variables into a deployment when it creates it. A value ### What the deploy checks -The `check environment variables` step asks Prisma Cloud once which variables the environment's branch receives, and looks up every platform variable the app reads in that answer, before any service or database is created. It reads whether a value exists, never the value. For `production` it asks about the project's default branch. If Prisma Cloud cannot answer, the deploy fails, naming the call and its HTTP status: the platform may not offer this read yet. +The `check environment variables` step asks Prisma Cloud once which variables the environment's branch receives, and looks up every platform variable the app reads in that answer, before any service or database is created. It reads whether a value exists, never the value. For `production` it asks about the project's default branch. If Prisma Cloud cannot answer, the deploy fails, naming the call, the project and the branch, and the HTTP status when there is one. A 404 can mean the platform does not offer this read yet. - **A variable a service needs that has no value fails the deploy.** Whether a service needs it is decided by the service's input schema: the deploy leaves the variable out and validates the input. A required field fails; an optional one does not. @@ -314,7 +314,7 @@ The `check environment variables` step asks Prisma Cloud once which variables th - prisma project env add 'EMAIL_API_KEY=' --project 'proj_…' --role preview ``` - The command follows the group the branch receives: `--role production` for the `production` group and `--role preview` for the `preview` group. For a custom group the deploy names the group and says to set the value there in the Prisma Console: `Set EMAIL_API_KEY in the variable group 'staging' in the Prisma Console.` + The command follows the group the branch receives: `--role production` for the `production` group and `--role preview` for the `preview` group. For a custom group, or a group of a kind this Composer version does not know, the deploy names the group and says to set the value there in the Prisma Console: `Set EMAIL_API_KEY in the variable group "staging" in the Prisma Console.` - **A variable nothing needs that has no value is listed, and the deploy goes on.** The list prints right after the step, and again at the end of the deploy output: ```text @@ -331,7 +331,7 @@ A new app's first deploy creates its project, then stops at this step if a servi At boot, an unset or empty variable leaves its field out of the service's input, and the service's schema decides. A service whose schema refuses the input fails at boot, and the error ends with the names of the variables that had no value. **Prisma Cloud still reports a service that fails at boot as running, and the deploy promotes it**, so the deploy succeeds; the error is in `prisma service logs --project `. -Every deployment on Prisma Cloud receives every variable of its class, including the ones another service reads. Under `prisma dev` each service receives only its own. +Every deployment on Prisma Cloud receives every variable of its branch's group, including the ones another service reads. Under `prisma dev` each service receives only its own. ### Names diff --git a/docs/guides/running-locally.md b/docs/guides/running-locally.md index ed7907d5c..00d878047 100644 --- a/docs/guides/running-locally.md +++ b/docs/guides/running-locally.md @@ -444,7 +444,7 @@ token, workspace, or network is involved. Five consequences worth knowing: `prisma dev` treats as secrets only the values under the names of the graph's platform secrets, and redacts those values in what it prints. The other values in `.env` and the shell are not secrets to it, and print as they are, apart from values that look like credentials, such as a long value under a name containing `TOKEN` or `KEY`. - Each service gets only the platform variables its own input points at. Code that reads `process.env.X` directly, where `X` is bound by another service, gets nothing under `prisma dev`. On Prisma Cloud every service receives every platform variable of its class, so do not rely on this isolation there. + Each service gets only the platform variables its own input points at. Code that reads `process.env.X` directly, where `X` is bound by another service, gets nothing under `prisma dev`. On Prisma Cloud every service receives every platform variable of its branch's group, so do not rely on this isolation there. - **A plain platform variable comes from the `config` adapters.** For each `variable({ name })` node a service reads, `prisma dev` reads the value under the variable's name from what the `config` adapters return, at start. Set it in `.env.dev` or the shell, as you would a root input field. An unset or empty value is left out of the service's input, and the schema decides, as for a secret. A value that is not text, such as a number an adapter returns, stops `prisma dev` before any service starts, naming the variable, the node and the services that read it. A value that holds one of your secrets' values is refused too, because `prisma dev` gives plain values to your services as plain configuration. A variable declared with a `schema` is then decoded and validated, with the same code as at boot: a text that does not decode or fit stops `prisma dev` before any service starts, with the boot error followed by `prisma dev cannot start, because service "shop.mailer" reads it.` ([Building an app § A typed platform variable](building-an-app.md#a-typed-platform-variable)). - Changing a value an adapter reads while `prisma dev` runs pauses rebuilds at the next rebuild, with a message; restart `prisma dev` to use the new values. - **Changing which platform variables the app reads pauses rebuilds.** `prisma dev` works out each platform variable's value when it starts. If a rebuild's graph adds a read, removes one, moves one to another field, or changes a node (such as renaming its variable or making it a secret), `prisma dev` does not apply it and warns: `The platform variables the app reads changed since dev started: reads of "shop.smtpPort" were added. Restart dev to apply them; rebuilds are paused until then.` Restart `prisma dev`. The check runs against your app as it is on disk, so it sees an edit to `module.ts` and to the modules it imports. diff --git a/skills/prisma-composer-core-concepts/SKILL.md b/skills/prisma-composer-core-concepts/SKILL.md index 6f84b5ce0..641f3d18a 100644 --- a/skills/prisma-composer-core-concepts/SKILL.md +++ b/skills/prisma-composer-core-concepts/SKILL.md @@ -132,7 +132,7 @@ export default appRoot('shop', { input: type({ EMAIL_FROM: 'string' }) }, ({ inp Rules that bite: 1. **Secretness is checked by the binding's type and by the deploy.** A `provision()` binding, a service's or a module's, is typed from the schema: a literal or a `SecretBox` where the schema expects `SecretString`, or a platform secret's value in a text field, fails to compile, and the deploy refuses it where the schema has no types. An ArkType schema with a `SecretString` field cannot also transform its input: a morph anywhere in it (`'string.trim'`, `.pipe()`, `field(type('string.integer.parse'))`) or `'+': 'delete'` copies the input, the copied secret loses its value, and the deploy refuses it. Transform in the service code instead; a Zod schema keeps the box. -2. **A plain platform variable's value is known only at boot: text, or the type its `schema` declares.** Bind it to a field wrapped with `field()`. A platform variable's value goes into a field of an `input` only. A compute service has one per-key param, the reserved `port`, which takes a literal or a root input field and no source, because the deploy needs the port before the service exists; every other value is a field of its `input`. A field of a narrower type, such as `email()`'s `deliveryMode`, takes a root input field declared with that type instead, for `email()` from the exported `emailDeliveryModes`; the deploy reads a root input field from the app configuration on every deploy and writes its value into the input document. A platform secret fits a `secretString()` field only. A platform variable's value always lives on the platform. The operator sets it there with `prisma project env add 'NAME=' --project --role production`. Each branch receives one variable group: production receives `production`, another branch a custom group whose rule matches its git name, or else `preview` (`--role preview`); a custom group is set in the Prisma Console. The deploy checks the branch's group and its overrides, not a value set on one service in the Console. The deploy does not copy local values (`.env`, the shell) to platform variables. The deploy fails only when a variable that a service's schema requires has no value. The error names the variable and the command that sets it. The other variables with no value print under `Platform variables with no value:`. Prisma Cloud reports a service that exits at boot as running and promotes it; read the error with `prisma service logs `. +2. **A plain platform variable's value is known only at boot: text, or the type its `schema` declares.** Bind it to a field wrapped with `field()`. A platform variable's value goes into a field of an `input` only. A compute service has one per-key param, the reserved `port`, which takes a literal or a root input field and no source, because the deploy needs the port before the service exists; every other value is a field of its `input`. A field of a narrower type, such as `email()`'s `deliveryMode`, takes a root input field declared with that type instead, for `email()` from the exported `emailDeliveryModes`; the deploy reads a root input field from the app configuration on every deploy and writes its value into the input document. A platform secret fits a `secretString()` field only. A platform variable's value always lives on the platform. The operator sets it there with `prisma project env add 'NAME=' --project --role production`. Each branch receives one variable group: production receives `production`, another branch a custom group whose rule matches its git name, or else `preview` (`--role preview`); a custom group is set in the Prisma Console. The deploy checks the branch's group and its overrides, not a value set on one service in the Console. The deploy does not copy local values (`.env`, the shell) to platform variables. The deploy fails only when a variable that a service's schema requires has no value. The error names the variable and how to set it: a shell command, or for a custom group an instruction to use the Prisma Console. The other variables with no value print under `Platform variables with no value:`. Prisma Cloud reports a service that exits at boot as running and promotes it; read the error with `prisma service logs `. 3. **The schema decides whether a field may be absent.** A field bound to a platform variable that is unset or empty is left out at boot. That is allowed only if the schema allows it, for example with an optional field or a union member. An optional root input field that the adapters do not supply is left out at deploy. The deploy report prints the serialized input document (each secret shown as `$platform VAR`) and every key that resolved absent. On Prisma Cloud the deploy writes the input document into the service's artifact, not into a `COMPOSER_*` variable, so it is not limited to a variable's 8 KB, and a changed document redeploys exactly that service. 4. **The reserved `port` is outside the schema.** Read it through `service.port()`, never `process.env`. The framework also exports `PORT` From 836e7a38a50afcb819bdbfa5a1de656e1edb79b5 Mon Sep 17 00:00:00 2001 From: willbot Date: Fri, 20 Nov 2026 23:10:02 +1100 Subject: [PATCH 5/6] fix(prisma-cloud): a failed read of the branch's variables shows its status and one short line of the body The read now asks for its body as text and parses it itself, so a 200 whose body is not JSON names HTTP 200. An error body is shown as at most one short line, never a whole HTML page. A thrown error that carries a status names it, and the sentence ends with one full stop whatever the error's own punctuation. The container defines the branch a deploy targets once, as deployBranchId, and alchemyStage refers to it. Co-Authored-By: Claude Fable 5.2 Signed-off-by: willbot Signed-off-by: Will Madden --- .../src/__tests__/preflight-payload.test.ts | 4 +- .../target/src/__tests__/preflight.test.ts | 47 ++++++++++----- .../1-extensions/target/src/container.ts | 2 +- .../1-extensions/target/src/preflight.ts | 58 ++++++++++++++++--- .../target/src/reporting/reporter.ts | 3 +- 5 files changed, 88 insertions(+), 26 deletions(-) diff --git a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight-payload.test.ts b/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight-payload.test.ts index 3d47e2f66..41bf83dc0 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight-payload.test.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight-payload.test.ts @@ -38,13 +38,13 @@ const graph = () => const fakePlatform = (updatedAt: string | undefined): ManagementApiClient => ({ GET: async () => ({ - data: { + data: JSON.stringify({ group: { id: 'grp-production', name: 'production', class: 'production' }, data: updatedAt === undefined ? [] : [{ key: 'STRIPE_SECRET_KEY', updatedAt, isManagedBySystem: false }], - }, + }), error: undefined, response: new Response(null, { status: 200 }), }), diff --git a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts b/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts index c41d86780..ee9204045 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/__tests__/preflight.test.ts @@ -27,7 +27,6 @@ const copyOf = (value: T): T => { return out.value as T; }; -/** A resolved container: a named environment carries its branch id, production its project's default branch id. */ const fakeContainer = (projectId: string, branchId: string | undefined) => new PrismaCloudContainer( { appName: 'app', environment: branchId === undefined ? 'production' : 'pr-1' }, @@ -57,7 +56,6 @@ type Source = | { type: 'branchOverride' } | { type: 'service'; serviceId: string }; -/** One key the resolved-variables read lists for the branch. */ interface Entry { key: string; updatedAt?: string; @@ -77,18 +75,13 @@ const DEFAULT_UPDATED_AT = '2026-01-01T00:00:00.000Z'; const RESOLVED_VARIABLES_PATH = '/v1/projects/{projectId}/resolved-variables'; interface FakeState { - /** Queries of the environment-variable list. */ gets: Record[]; - /** Each resolved-variables read, by the project and branch it asked about. */ reads: { projectId: string; branchId: string }[]; posts: Record[]; rows: Row[]; entries: Entry[]; - /** The group the branch receives; unset gives `production` for the default branch and `preview` otherwise. */ group?: Group; - /** Replaces the read's answer: an error status, or a body of the test's own. */ answer?: { status: number; body?: unknown; error?: unknown }; - /** Makes the read throw, as the client does on a network failure or a body that is not JSON. */ throws?: Error; } @@ -99,6 +92,9 @@ const builtInGroup = (branchId: string): Group => ? { id: 'grp-production', name: 'production', class: 'production' } : { id: 'grp-preview', name: 'preview', class: 'preview' }; +const asText = (body: unknown): unknown => + typeof body === 'string' || body === undefined ? body : JSON.stringify(body); + /** A stubbed Management API client — test file, exempt from the no-bare-cast rule. */ const fakeClient = (state: FakeState): ManagementApiClient => ({ @@ -116,14 +112,14 @@ const fakeClient = (state: FakeState): ManagementApiClient => if (state.answer !== undefined) { const ok = state.answer.status < 400; return { - data: ok ? state.answer.body : undefined, + data: ok ? asText(state.answer.body) : undefined, error: ok ? undefined : state.answer.error, response: new Response(null, { status: state.answer.status }), }; } const group = state.group ?? builtInGroup(branchId); return { - data: { + data: asText({ group, data: state.entries.map((entry) => ({ key: entry.key, @@ -136,7 +132,7 @@ const fakeClient = (state: FakeState): ManagementApiClient => groupClass: group.class, }, })), - }, + }), error: undefined, response: new Response(null, { status: 200 }), }; @@ -501,11 +497,36 @@ describe('the deploy check reads which variables the branch receives and sets no expect((error as Error).cause).toBe(cause); }); - test('a body that is not JSON names the call', async () => { - state.throws = new SyntaxError('Unexpected token \'<\', "" is not valid JSON'); + test('a 200 whose body is not JSON names the status and a short excerpt', async () => { + state.answer = { status: 200, body: '\n Maintenance\n' }; + + expect(await failedReadMessage()).toBe( + `${COULD_NOT_READ} answered HTTP 200 with a body that is not JSON: Maintenance .`, + ); + }); + + test('an error status whose body is a whole HTML page shows one short line of it', async () => { + const page = `\n502 Bad Gateway\n${'x'.repeat(5000)}\n`; + state.answer = { status: 502, error: page }; + + const message = await failedReadMessage(); + + expect(message).toStartWith( + `${COULD_NOT_READ} answered HTTP 502: 502 Bad Gateway xxx`, + ); + expect(message).toEndWith('….'); + expect(message).not.toContain('\n'); + expect(message.length).toBeLessThan(COULD_NOT_READ.length + 160); + }); + + test('a thrown error that carries a status names it, and the sentence ends with one full stop', async () => { + state.throws = Object.assign( + new Error('The management API rejected the service token from PRISMA_SERVICE_TOKEN.'), + { status: 401 }, + ); expect(await failedReadMessage()).toBe( - `${COULD_NOT_READ} failed: Unexpected token '<', "" is not valid JSON.`, + `${COULD_NOT_READ} failed with HTTP 401: The management API rejected the service token from PRISMA_SERVICE_TOKEN.`, ); }); diff --git a/packages/1-prisma-cloud/1-extensions/target/src/container.ts b/packages/1-prisma-cloud/1-extensions/target/src/container.ts index 1097a59e7..2e8278811 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/container.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/container.ts @@ -44,7 +44,7 @@ function invalidAlchemyStageError(branchId: string): Error { } export class PrismaCloudContainer implements ContainerInstance { - /** The deterministic Alchemy stage (ContainerInstance SPI): the environment's Branch id, or the default Branch's id for `production`. Absent only for the dev container, which resolves no Branch. */ + /** The Alchemy stage (ContainerInstance SPI): {@link deployBranchId}. */ readonly alchemyStage: string | undefined; /** The Branch this deploy targets: the environment's Branch, or the project's default Branch for `production`. Absent only for the dev container. */ readonly deployBranchId: string | undefined; diff --git a/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts b/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts index a5d5aeb7a..a3837ff38 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/preflight.ts @@ -79,7 +79,10 @@ type VariableGroup = ResolvedVariables['group']; interface ResolvedVariablesClient { GET( path: typeof RESOLVED_VARIABLES_PATH, - init: { params: { path: { projectId: string }; query: { branchId: string } } }, + init: { + params: { path: { projectId: string }; query: { branchId: string } }; + parseAs: 'text'; + }, ): Promise<{ readonly data?: unknown; readonly error?: unknown; readonly response: Response }>; } @@ -95,6 +98,30 @@ const isPartial = (body: unknown): boolean => isRecord(body) && (saysThereIsMore(body) || (isRecord(body['pagination']) && saysThereIsMore(body['pagination']))); +const NOT_JSON = Symbol('not JSON'); + +function parseJson(text: unknown): unknown { + if (typeof text !== 'string') return NOT_JSON; + try { + return JSON.parse(text); + } catch { + return NOT_JSON; + } +} + +const EXCERPT_LENGTH = 120; + +const excerpt = (body: unknown): string => { + const text = typeof body === 'string' ? body : (JSON.stringify(body) ?? ''); + const line = text.replace(/\s+/g, ' ').trim(); + return line.length <= EXCERPT_LENGTH ? line : `${line.slice(0, EXCERPT_LENGTH)}…`; +}; + +const withoutClosingStops = (message: string): string => message.trim().replace(/\.+$/, ''); + +const statusOf = (error: unknown): number | undefined => + isRecord(error) && typeof error['status'] === 'number' ? error['status'] : undefined; + interface ResolvedRead { readonly call: string; readonly projectId: string; @@ -115,15 +142,20 @@ async function readResolvedVariables( ResolvedVariablesClient, 'the published Management API SDK does not describe the resolved-variables read yet; its body is checked below' >(client) - .GET(RESOLVED_VARIABLES_PATH, { params: { path: { projectId }, query: { branchId } } }) + .GET(RESOLVED_VARIABLES_PATH, { + params: { path: { projectId }, query: { branchId } }, + parseAs: 'text', + }) .catch((cause: unknown) => { throw readThrewError(read, cause); }); if (res.error !== undefined || !res.response.ok) { throw readStatusError(read, res.response.status, res.error); } - if (isPartial(res.data)) throw pagedReadError(read); - const parsed = resolvedVariablesBody(res.data); + const body = parseJson(res.data); + if (body === NOT_JSON) throw notJsonError(read, res.response.status, res.data); + if (isPartial(body)) throw pagedReadError(read); + const parsed = resolvedVariablesBody(body); if (parsed instanceof type.errors) throw unexpectedReadError(read, parsed.summary); return parsed; } @@ -222,17 +254,27 @@ const couldNotRead = (read: ResolvedRead): string => const readStatusError = (read: ResolvedRead, status: number, error: unknown): Error => new Error( `${couldNotRead(read)} answered HTTP ${String(status)}` + - `${error === undefined || error === '' ? '' : `: ${JSON.stringify(error)}`}.` + + `${error === undefined || error === '' ? '' : `: ${excerpt(error)}`}.` + (status === 404 ? ' The platform may not offer this read yet, and this Composer version needs it to check platform variables.' : ''), ); -const readThrewError = (read: ResolvedRead, cause: unknown): Error => - new Error( - `${couldNotRead(read)} failed: ${cause instanceof Error ? cause.message : String(cause)}.`, +const readThrewError = (read: ResolvedRead, cause: unknown): Error => { + const status = statusOf(cause); + const reason = withoutClosingStops(cause instanceof Error ? cause.message : String(cause)); + return new Error( + `${couldNotRead(read)} failed${status === undefined ? '' : ` with HTTP ${String(status)}`}: ${reason}.`, { cause }, ); +}; + +const notJsonError = (read: ResolvedRead, status: number, body: unknown): Error => { + const shown = excerpt(body); + return new Error( + `${couldNotRead(read)} answered HTTP ${String(status)} with ${shown === '' ? 'an empty body' : `a body that is not JSON: ${shown}`}.`, + ); +}; const unexpectedReadError = (read: ResolvedRead, problem: string): Error => new Error( diff --git a/packages/1-prisma-cloud/1-extensions/target/src/reporting/reporter.ts b/packages/1-prisma-cloud/1-extensions/target/src/reporting/reporter.ts index f2c815e9d..9b352e492 100644 --- a/packages/1-prisma-cloud/1-extensions/target/src/reporting/reporter.ts +++ b/packages/1-prisma-cloud/1-extensions/target/src/reporting/reporter.ts @@ -13,8 +13,7 @@ export function prismaCloudReporter(): ReporterDescriptor { return Builds.buildReporter({ refsOf: (container) => { const { projectId, branchId, deployBranchId } = prismaCloudContainerOf(container); - // The Build references only a non-production environment's Branch; the topology lives - // on whichever Branch the deploy targets — the default one included. + // The Build references only a non-production environment's Branch. return { projectId, branchId, deployBranchId }; }, }); From 131d933918d3d06da9f65e5fd602c0f217a8b803 Mon Sep 17 00:00:00 2001 From: willbot Date: Fri, 20 Nov 2026 23:10:05 +1100 Subject: [PATCH 6/6] docs: the platform data model describes variable groups throughout, and the design records the review corrections The data model's entity graph, edges and version-create row now describe groups, overrides and service variables as one model. The glossary entry for a variable on the platform says plainly which writes the platform will reject. The error table and ADR-0064 match the failure messages. The design records that only an answer saying it has more fails, that only a 404 says the read may be missing, and that the custom-group hint is a sentence; deferred.md and plan.md record what is left. Co-Authored-By: Claude Fable 5.2 Signed-off-by: willbot Signed-off-by: Will Madden --- .../variable-groups-compat/deferred.md | 4 ++ .../projects/variable-groups-compat/design.md | 10 ++--- .../projects/variable-groups-compat/plan.md | 4 ++ docs/design/03-domain-model/glossary.md | 2 +- docs/design/05-prisma-cloud/pdp-data-model.md | 37 ++++++++----------- docs/design/10-domains/deploy-cli.md | 2 +- ...t-and-the-deploy-copies-no-local-values.md | 4 +- docs/guides/deploying.md | 2 +- 8 files changed, 34 insertions(+), 31 deletions(-) diff --git a/.drive/projects/variable-groups-compat/deferred.md b/.drive/projects/variable-groups-compat/deferred.md index 776178063..3821484c4 100644 --- a/.drive/projects/variable-groups-compat/deferred.md +++ b/.drive/projects/variable-groups-compat/deferred.md @@ -3,4 +3,8 @@ - **Preflight does not see a value a user set on one service.** A platform variable set only as a service variable, through Console's "Save and Deploy", is reported unset, and a required one fails the deploy. The fix is one `resolved-variables?serviceId=` read per reading service that already exists, with each key's `updatedAt` added to that service's triggers. Not built because Composer has no way to declare such a value. From the design, section 4.1. - **Hints use `prisma project env` for the built-in groups.** Move them to `prisma variable` when it is the CLI most users have. - **An app upgrading directly from a version before the address change** can have one service receive another's old row once. The guide tells it to deploy with a release from 0.35.0 to 0.39.0 first. A check in preflight against the deploy state would refuse it instead. +- **A local client type and a cast stand in for the SDK's description of the resolved-variables read.** `ResolvedVariablesClient` and its `blindCast` in `packages/1-prisma-cloud/1-extensions/target/src/preflight.ts` exist because `@prisma/management-api-sdk` does not describe `GET /v1/projects/{projectId}/resolved-variables`. Remove both and use the SDK's types when it does. +- **The custom-group hint is a sentence because `prisma variable add … --group` does not exist.** When the CLI ships it, replace the sentence in `setCommands` with the command, and change ADR-0064's sentence that says no released CLI command writes to a custom group. +- **`scripts/e2e-first-deploy.ts` writes branch overrides and production rows with no group.** For a non-production environment it posts `class: preview` with a `branchId`, which the platform will reject; for production it posts a row with no `groupId`, which the resolved-variables read does not list. Slice 3 must change it to write to the branch's group. +- **`branchId ?? defaultBranchId` is still computed outside the container**, in `attachmentBranchIdOf` (`descriptors/shared.ts`, on `CloudApplication`) and in lowering's `deployed.ts`, on their own types. Minor; `PrismaCloudContainer.deployBranchId` is the one definition in the container. - **Ask the platform to put the limit and the count in its quota error for service variables.** Composer checks its own count, but cannot count variables a user set in Console. diff --git a/.drive/projects/variable-groups-compat/design.md b/.drive/projects/variable-groups-compat/design.md index 0f0c16e91..27a45afd7 100644 --- a/.drive/projects/variable-groups-compat/design.md +++ b/.drive/projects/variable-groups-compat/design.md @@ -102,9 +102,9 @@ From the response: Everything preflight returns keeps its type. `updatedAt` is printed the same way by the old list call and the new read, so on a branch that receives `production` or `preview` the trigger values do not change, and upgrading replaces no deployment for this reason. -**A failed call fails the deploy.** A 404 for the project or the branch, or any other error, stops the deploy with a message that names the call, the status, and the project and branch ids, and says that the platform may not offer this read yet. There is no fallback to the old per-key lookup: the old lookup is what gives wrong answers, and falling back would bring them back without a word. +**A failed call fails the deploy.** An error status, a network failure, or a body that is not JSON or not the expected shape stops the deploy with a message that names the call, the project and branch ids, and the HTTP status when the client reports one, with at most a one-line excerpt of the body. Only a 404 adds that the platform may not offer this read yet; for other failures that sentence would point at the wrong cause. There is no fallback to the old per-key lookup: the old lookup is what gives wrong answers, and falling back would bring them back without a word. -**A paginated answer fails the deploy.** The read returns everything in one response today. If the platform ever pages it, a release that read only the first page would report the rest missing, and there are no patch releases to fix that. So a response that carries a pagination field or a cursor stops the deploy with a message that says this Composer version is too old for the platform. +**A paginated answer fails the deploy.** The read returns everything in one response today. If the platform ever pages it, a release that read only the first page would report the rest missing, and there are no patch releases to fix that. So an answer that says there is more to fetch (`hasMore: true`, or a non-empty `nextCursor` or `cursor`, at the top level or inside `pagination`) stops the deploy with a message that says this Composer version is too old for the platform. A complete answer in the platform's list envelope, such as `pagination: { nextCursor: null, hasMore: false }`, is accepted. **Hint commands** are chosen by the class of the group the environment receives. @@ -112,12 +112,12 @@ Everything preflight returns keeps its type. `updatedAt` is printed the same way | --- | --- | | `production` | `prisma project env add 'NAME=' --project --role production` | | `preview` | `prisma project env add 'NAME=' --project --role preview` | -| `custom` | `prisma variable add 'NAME=' --project --group ` | +| `custom`, or a class Composer does not know | A sentence: `Set NAME in the variable group "" in the Prisma Console.` | -The group's name is quoted for the shell, as the project id is. Two changes from today: +Two changes from today: 1. **The `--branch ` command is no longer suggested.** It creates a branch override, which the platform is removing. -2. **A custom group gets the new CLI's command.** `prisma project env` cannot write to a custom group. `prisma variable` is not released yet. A custom group cannot exist in production before the platform turns the feature on, and the platform's rollout releases the CLI first. The slice that builds this checks the command's exact spelling against `prisma/prisma-cli` before it merges. If the command has not shipped by then, the hint for a custom group is a sentence naming the group and Console, with no command. +2. **A custom group gets a sentence, not a command.** `prisma project env` cannot write to a custom group, and the `prisma variable add … --group` command does not exist yet: on 2026-11-20 it is only in a draft demo pull request on `prisma/prisma-cli` (#395). So the hint names the group in double quotes and says to set the value in the Prisma Console. Core's comment on `UnsetPlatformVariable.commands` says each line is a shell command where one exists, otherwise an instruction. When `prisma variable` ships, the hint becomes its command (see `deferred.md`). The built-in groups keep `prisma project env` because it works with every CLI version. It is deprecated in the new CLI but keeps working. The hints move to `prisma variable` in a later change. diff --git a/.drive/projects/variable-groups-compat/plan.md b/.drive/projects/variable-groups-compat/plan.md index 81db6ad67..1fa3362a4 100644 --- a/.drive/projects/variable-groups-compat/plan.md +++ b/.drive/projects/variable-groups-compat/plan.md @@ -12,6 +12,10 @@ Design sections 4.3 and 4.4. Builds on: nothing. Hands to slice 2: the client vi Design section 4.1. Builds on: slice 1. Merges when the new read is live in production with the missing-group-id defect fixed. Until then the pull request is a draft. +Before merge: check again whether `prisma variable` has shipped (if it has, the custom-group hint becomes its command), and run manual QA once more against the platform's real read. + +Note for any later read by `serviceId`: for a key set both as a branch override and as a service variable, the platform's read reports the override (it layers overrides last), while its deployment gives the service the service variable (it layers service variables last). A trigger built from that read would miss a change to the service variable. Raise it with the platform team before relying on that read. + ## Slice 3: a service's `COMPOSER_` keys travel with its deployment Design section 4.2. Builds on: the open pull request "an unchanged deploy no longer replaces a service that depends on another service", merged. Independent of slice 2. Opened early as a draft, with `pnpm` patches standing in for the upstream packages, for Ty to align his interface against. Needs one pull request on Distilled and one on Alchemy once the platform's field is final. Merges when the platform accepts `variables` in production and both upstream packages have released. diff --git a/docs/design/03-domain-model/glossary.md b/docs/design/03-domain-model/glossary.md index ae9ddfab9..1ded4f58d 100644 --- a/docs/design/03-domain-model/glossary.md +++ b/docs/design/03-domain-model/glossary.md @@ -194,7 +194,7 @@ A [platform variable](#platform-variable) whose value is handled as a secret: bo ### A variable on the platform -Any entry, or **row**, in a Prisma Cloud project's environment variables: a name and a non-empty text. A **group row** belongs to a [variable group](#variable-group); what was called a class row is a row of the `production` or `preview` group. A **branch override** (formerly "branch row") belongs to one branch and wins over its group's value. The platform is removing branch overrides: after a notice period, it rejects a write that names a branch. That includes Composer's own `COMPOSER_` rows, which are not [platform variables](#platform-variable). The term names the platform's storage, as distinct from what the app reads. Prisma Cloud calls these rows environment variables. +Any entry, or **row**, in a Prisma Cloud project's environment variables: a name and a non-empty text. Composer's own `COMPOSER_` rows are rows too, but not [platform variables](#platform-variable). A **group row** belongs to a [variable group](#variable-group); what was called a class row is a row of the `production` or `preview` group. A **branch override** (formerly "branch row") belongs to one branch and wins over its group's value. The platform is removing branch overrides: after a notice period, it rejects a write that names a branch. Composer writes a service's `COMPOSER_` rows on a preview environment as branch overrides, so those writes fail once the platform rejects them. The term names the platform's storage, as distinct from what the app reads. Prisma Cloud calls these rows environment variables. ### Variable group diff --git a/docs/design/05-prisma-cloud/pdp-data-model.md b/docs/design/05-prisma-cloud/pdp-data-model.md index 2b3d13141..b44bc88cc 100644 --- a/docs/design/05-prisma-cloud/pdp-data-model.md +++ b/docs/design/05-prisma-cloud/pdp-data-model.md @@ -14,8 +14,10 @@ flowchart TB WS[Workspace
auth boundary · service tokens] P[Project
encryption keyset - DEK] B[Branch
one has the production role] - CVT[ConfigVariable — template
branchId NULL] - CVO[ConfigVariable — override
branchId set · preview class only] + VG[VariableGroup
production · preview · custom] + CVG[ConfigVariable — group row
groupId set] + CVO[ConfigVariable — branch override
branchId set] + SV[Service variable] A[App
API name: compute service
serviceEndpointDomain] DB[Database] D[Deployment
DB table: ComputeVersion
foundryVersionId] @@ -24,10 +26,12 @@ flowchart TB WS --> P P --> B - P --> CVT + P --> VG + VG --> CVG B --> CVO B --> A B --> DB + A --> SV A --> D A --> PR PR --> D @@ -48,12 +52,8 @@ Edge semantics, with the properties that matter to us: `[branchId, projectId]`). An App **must be attached to a Branch to deploy** — version creation 422s otherwise (`resolveDeployEnvVars.ts`: "Attach the app to a Branch before creating a deployment"). -- **Project → ConfigVariable (template), Branch → ConfigVariable (override).** - `ConfigVariable` = `{ projectId, branchId?, class: production|preview, key, - encryptedValue (AES-GCM under the project DEK), isManagedByModule }`, unique on - `(project, branch, class, key)`. `branchId NULL` is a project-level template; - a set `branchId` is a branch-scoped override, **allowed only for the preview - class** (CHECK constraint). +- **Project → VariableGroup → ConfigVariable, Branch → ConfigVariable (override).** A `ConfigVariable` holds a `key` and an `encryptedValue` (AES-GCM under the project DEK), and belongs either to a variable group, as a **group row**, or to one Branch, as that Branch's **override**. Every project has a `production` and a `preview` group and can add custom groups; each Branch receives exactly one group (see [Variable groups](#variable-groups)). +- **App → Service variable.** Values stored on one App, which is one Composer service in one environment (see [Variable groups](#variable-groups)). - **App → Deployment.** A Deployment is one immutable version of the app (`ComputeVersion` table); `foundryVersionId` links it to the runner's record. - **App → Promotion → Deployment.** Promotion points the app's stable endpoint @@ -81,9 +81,9 @@ This is the timing model Prisma Composer's graph must respect: | Moment | What happens | Source | | --- | --- | --- | -| default DB provisioned | the platform **writes** `DATABASE_URL` and `DATABASE_URL_POOLED` as ordinary project-level production-class ConfigVariable **templates** (user-set values win) | `compute-config/wireDefaultDatabaseUrl.ts` | +| default DB provisioned | the platform **writes** `DATABASE_URL` and `DATABASE_URL_POOLED` as ordinary rows of the project's `production` group (user-set values win) | `compute-config/wireDefaultDatabaseUrl.ts` | | any time | ConfigVariable rows are created/updated/deleted via the environment-variables API — **rows only; no effect on any existing version** | `routes/v1/environment-variables.ts` | -| **version create** | `materializeBranchEnvVars(app.branchId)` resolves the complete map — production branch → production templates; preview branch → preview templates merged with that branch's overrides (override wins) — decrypts it, and hands the **plain map to Foundry with the version**. The env is **frozen into the version** | `routes/v1/versions.ts` → `resolveDeployEnvVars.ts` → `compute-config/materializeBranchEnvVars.ts` | +| **version create** | `materializeBranchEnvVars(app.branchId)` resolves the complete map — the Branch's group, then that Branch's overrides (override wins); a deployment created with service variables gets them on top — decrypts it, and hands the **plain map to Foundry with the version**. The env is **frozen into the version** | `routes/v1/versions.ts` → `resolveDeployEnvVars.ts` → `compute-config/materializeBranchEnvVars.ts` | | version start | boots the version; **no env re-resolution** | `routes/v1/version-handlers.ts` | | promote | endpoint routed to the version; `serviceEndpointDomain` persisted. The domain returned at *create* time is a placeholder region — only the post-promote read is trustworthy (PRO-200) | `interactors/compute/service.ts` | @@ -101,23 +101,18 @@ Consequences Prisma Composer designs around: the deployment, so the change reaches the running service (see the change-propagation note in [alchemy-lowering.md](alchemy-lowering.md#the-lowering-graphs)). -3. **`DATABASE_URL` is not a separate mechanism.** It is a platform-written template flowing through the same materialization as user variables — a convenience for hand-provisioned single services. The platform owns it (system-managed) and writes it only for a project's default database. Prisma Composer refuses to bind or manage the name and creates no default database (see [alchemy-lowering.md](alchemy-lowering.md#database_url-is-forbidden--and-left-to-the-platform)); every database URL a service consumes is an explicit, service-named variable. -4. **Branch + class is the platform's environments model** (production - templates vs preview templates + per-branch overrides) — the substrate - [an environment as a Branch](../10-domains/deploy-cli.md#environments-and-containers) is - built on: an environment other than `production` is a Branch, and its config is written - preview-class with that Branch's overrides. Under variable groups (below), a Branch - receives one group in place of a class. +3. **`DATABASE_URL` is not a separate mechanism.** It is a platform-written group row flowing through the same materialization as user variables — a convenience for hand-provisioned single services. The platform owns it (system-managed) and writes it only for a project's default database. Prisma Composer refuses to bind or manage the name and creates no default database (see [alchemy-lowering.md](alchemy-lowering.md#database_url-is-forbidden--and-left-to-the-platform)); every database URL a service consumes is an explicit, service-named variable. +4. **The Branch is the platform's environments model**: each Branch receives one variable group and its own overrides. It is the substrate [an environment as a Branch](../10-domains/deploy-cli.md#environments-and-containers) is built on: an environment other than `production` is a Branch, and production is the project's default Branch. ## Variable groups Prisma Cloud keeps variables in groups. What Composer depends on: -- **Variable groups.** Every project has a `production` group and a `preview` group, holding the rows the two old row classes held. A group's class (`production`, `preview` or `custom`) names its kind and is not a row's old class. A project can add custom groups, each with one rule on a branch's git name: `equals` or `startsWith`. +- **Variable groups.** Every project has a `production` group and a `preview` group. A group's class (`production`, `preview` or `custom`) names its kind. A project can add custom groups, each with one rule on a branch's git name: `equals` or `startsWith`. - **One group per branch.** The production branch receives `production`. Any other branch receives the custom group with the most precise matching rule, or else `preview`. Groups do not combine. - **Service variables.** Values stored on one platform service, which is one Composer service in one environment. They are set only when a deployment is created, through the create-deployment request, which Console's "Save and Deploy" sends, and are deleted with the platform service. -- **The order a deployment receives values:** every value of its branch's group, then the branch's overrides, then the service's variables. Later wins. The map is still frozen into the version when it is created. -- **Branch overrides are being removed.** The platform is removing branch overrides: after a notice period, it rejects a write that names a branch. Existing overrides keep applying until their branch is deleted. +- **The order a deployment receives values:** every value of its branch's group, then the branch's overrides, then the service's variables. Later wins. The map is frozen into the version when it is created. +- **Branch overrides are being removed.** After a notice period, the platform rejects a write that names a branch. Existing overrides keep applying until their branch is deleted. - **The resolved-variables read.** `GET /v1/projects/{projectId}/resolved-variables?branchId=…` returns the group the branch receives (`id`, `name`, `class`) and every key the branch receives, each with `updatedAt`, `isManagedBySystem` and a `source` (`group`, `branchOverride` or `service`). It returns no values and does not paginate. Deploy preflight reads it once per deploy ([ADR-0064](../90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md)). ## Related diff --git a/docs/design/10-domains/deploy-cli.md b/docs/design/10-domains/deploy-cli.md index 5e329e170..466e6a200 100644 --- a/docs/design/10-domains/deploy-cli.md +++ b/docs/design/10-domains/deploy-cli.md @@ -278,7 +278,7 @@ them: | Built output missing | the expected path, and "run your build" | | An extension's graph check refuses the graph (`COMPOSE.GRAPH_INVALID`) | the extension's message: for Prisma Cloud, a platform variable declared by two nodes, a name used by both a plain platform variable node and a root input field, or a node bound as a service's whole input, naming the variable and every address involved | | A platform variable a service needs has no value (`DEPLOY.PREFLIGHT_FAILED`) | each variable, the service and field that reads it, and what sets it, by the class of the group the branch receives: `prisma project env add … --role production` or `--role preview`, or for a custom group a sentence naming the group and the Prisma Console | -| The read of the branch's variables fails or is paged (`DEPLOY.PREFLIGHT_FAILED`) | the call, the HTTP status, the project and branch ids, and that the platform may not offer the read yet; for a paged answer, that this Composer version is too old for the platform | +| The read of the branch's variables fails or is paged (`DEPLOY.PREFLIGHT_FAILED`) | the call, the project and branch ids, and the HTTP status when the client reports one, with at most a one-line excerpt of the body; for a 404, that the platform may not offer the read yet; for a paged answer, that this Composer version is too old for the platform | | A platform variable the app reads is managed by Prisma Cloud (`DEPLOY.PREFLIGHT_FAILED`) | the variable, and to rename it in the app | | Root's input refused by its schema | the schema's messages, and that a root's input is the app configuration for the environment | | A config adapter throws or returns something other than an object (`CONFIG.ADAPTER_FAILED`, `CONFIG.ADAPTER_INVALID`) | which list and position, and the fix | diff --git a/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md b/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md index 2fba87d82..106f31c27 100644 --- a/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md +++ b/docs/design/90-decisions/ADR-0064-an-app-declares-its-platform-variables-in-its-root-and-the-deploy-copies-no-local-values.md @@ -218,7 +218,7 @@ Preflight runs after the deploy has resolved the app's Project and Branch, and b - **The names it checks.** Every platform variable, plain or secret, in a service's input binding, at any depth, found from the same walk of each binding, without serializing the service; and every platform variable node no service reads, which are the value resources not in `graph.valueReads`. An invalid input still fails after preflight reports the platform variables. The deploy preflight reads nothing from the app configuration. - **One read per deploy.** When the app names at least one platform variable, preflight makes one resolved-variables read for the environment's branch: the environment's own branch, or for `production` the project's default branch, whose id the deploy already holds. An app that names none makes no call. A name is present when the read lists its key. Its `updatedAt` is the trigger value. The entry's `source` is not consulted: a group value and a branch override both reach every service on the branch. -- **A failed read fails the deploy.** An error status, a network failure, or a body that is not JSON or not the expected shape stops the deploy with a message that names the call, the project and the branch, and the HTTP status when there is one. Only a 404 adds that the platform may not offer this read yet; a body of the wrong shape says the platform's answer may have changed. There is no fallback to a per-name lookup, because that lookup gives wrong answers on a custom group. +- **A failed read fails the deploy.** An error status, a network failure, or a body that is not JSON or not the expected shape stops the deploy with a message that names the call, the project and the branch, and the HTTP status when the client reports one. Of a body it shows at most a one-line excerpt. Only a 404 adds that the platform may not offer this read yet; a body of the wrong shape says the platform's answer may have changed. There is no fallback to a per-name lookup, because that lookup gives wrong answers on a custom group. - **A paged answer fails the deploy.** An answer that says it has more, with `hasMore: true` or a non-empty `nextCursor` or `cursor`, at the top level or inside `pagination`, stops the deploy with a message that says this Composer version is too old for the platform. A version that read only the first page would report the rest missing, and older lines get no patch releases. A complete answer in the platform's list envelope, such as `pagination: { nextCursor: null, hasMore: false }`, is accepted. - **A system key is refused.** A listed key with `isManagedBySystem: true` fails the deploy, naming the variable. - **A value set on one service is not seen.** Preflight asks about the branch, not about each service. A variable a service requires that is set only as that service's service variable fails the deploy as missing, and the hint says to set it in the group. A deployment that Console creates with "Save and Deploy" is replaced as live by the next `prisma deploy`. This gap is known and left open. @@ -235,7 +235,7 @@ Preflight runs after the deploy has resolved the app's Project and Branch, and b ``` The hint follows the class of the group the branch receives: `--role production` for `production`, `--role preview` for `preview`. For a custom group, or a group of any class Composer does not know, it is a sentence that names the group in double quotes and says to set the value there in the Prisma Console, because no released CLI command writes to a custom group yet. `UnsetPlatformVariable.commands` carries it; core documents each line as a shell command where one exists, otherwise an instruction. No hint writes a branch override, which the platform is removing. A variable that an array position makes required has a second line with the reason, and a line for a service that needs some of several variables ends with the schema's message. -- **The findings.** Every variable with no value that nothing requires is listed, with its readers (a service and field, or the node that names it and that no service reads it) and the commands that set it. `PreflightInput.report` takes a `PlatformVariableCheck`: the count of platform variables checked and this list, names and readers only, never a value. It carries platform-variable findings and that count, nothing else. The deploy prints the list right after the preflight step, under `Platform variables with no value:`. With `--json` it is a message whose data holds the list, and `onEvent` receives it as a `preflight-findings` event. The step's data stays `{ checked, unset }`, two counts. The deploy hands the list to `lower()` as a value, `LowerOptions.findings`, and lowering puts it into `DeploymentResult.findings`; `prisma deploy` repeats it at the end of its report ([ADR-0066](ADR-0066-deploy-runs-alchemy-in-process.md)). An extension's own preflight payload never carries it. +- **The findings.** Every variable with no value that nothing requires is listed, with its readers (a service and field, or the node that names it and that no service reads it) and how to set it: a shell command, or for a custom group an instruction. `PreflightInput.report` takes a `PlatformVariableCheck`: the count of platform variables checked and this list, names and readers only, never a value. It carries platform-variable findings and that count, nothing else. The deploy prints the list right after the preflight step, under `Platform variables with no value:`. With `--json` it is a message whose data holds the list, and `onEvent` receives it as a `preflight-findings` event. The step's data stays `{ checked, unset }`, two counts. The deploy hands the list to `lower()` as a value, `LowerOptions.findings`, and lowering puts it into `DeploymentResult.findings`; `prisma deploy` repeats it at the end of its report ([ADR-0066](ADR-0066-deploy-runs-alchemy-in-process.md)). An extension's own preflight payload never carries it. - **Triggers.** Each service's deployment triggers carry `:updatedAt` for each platform variable its input document points at, with `?` when the variable has no value. Changing a value on the platform and deploying again replaces exactly the deployments that read it. ### `prisma dev` diff --git a/docs/guides/deploying.md b/docs/guides/deploying.md index cad54ac58..ec936256c 100644 --- a/docs/guides/deploying.md +++ b/docs/guides/deploying.md @@ -302,7 +302,7 @@ The platform copies the variables into a deployment when it creates it. A value ### What the deploy checks -The `check environment variables` step asks Prisma Cloud once which variables the environment's branch receives, and looks up every platform variable the app reads in that answer, before any service or database is created. It reads whether a value exists, never the value. For `production` it asks about the project's default branch. If Prisma Cloud cannot answer, the deploy fails, naming the call, the project and the branch, and the HTTP status when there is one. A 404 can mean the platform does not offer this read yet. +The `check environment variables` step asks Prisma Cloud once which variables the environment's branch receives, and looks up every platform variable the app reads in that answer, before any service or database is created. It reads whether a value exists, never the value. For `production` it asks about the project's default branch. If Prisma Cloud cannot answer, the deploy fails, naming the call, the project and the branch, and the HTTP status when the client reports one. A 404 can mean the platform does not offer this read yet. - **A variable a service needs that has no value fails the deploy.** Whether a service needs it is decided by the service's input schema: the deploy leaves the variable out and validates the input. A required field fails; an optional one does not.