@samebase/alchemy-convex 0.4.1 → 0.5.0

package/README.md

@@ -90,6 +90,27 @@ reads them through the stack's config provider (process env, `.env`, stack secre
 A key that does not fit the deployment is not used: the provider uses the access token. To pass
 values explicitly: `Convex.providers(Convex.fromValues({ accessToken, deployKey }))`.
 
+## State in Convex
+
+`state: Convex.state()` keeps the Alchemy state of every stage in the production deployment of the
+project, so the stack needs no Cloudflare token.
+[docs/design/convex-state.md](docs/design/convex-state.md) records the decisions.
+
+1. Mount the state component in `convex/convex.config.ts` with its default name:
+
+   ```ts
+   import alchemyState from "@samebase/alchemy-convex/convex.config";
+   app.use(alchemyState);
+   ```
+
+2. Set `CONVEX_STATE_DEPLOY_KEY` in every run, a preview run too, to a production deploy key. A key
+   with only the actions `deployment:data:view` and `deployment:data:write` is sufficient.
+
+The first run starts with empty state, keeps it in memory until `Convex.Deployment` has pushed the
+component, and then writes it. A run whose push does not mount the component fails at the end.
+Rows are in the `alchemyState` component tables `resources` and `outputs` in the dashboard. The
+store has no lock: run one deploy of a stage at a time, such as with a CI concurrency group.
+
 ## Resources
 
 - `Convex.Project`: `{ team, name, deploymentRegion?, deploymentType? }` creates a project with its

package/lib/index.d.ts

@@ -7,6 +7,7 @@ import { Resource } from "alchemy";
 import * as Provider from "alchemy/Provider";
 import "effect/process/ChildProcessSpawner";
 import { createDeploymentClient, createManagementClient } from "@convex-dev/platform";
+import { State, StateStoreError } from "alchemy/State";
 import { components } from "@convex-dev/platform/managementApi";
 //#region src/Credentials.d.ts
 interface ResolvedCredentials {
@@ -339,5 +340,16 @@ export declare class ProjectNotFound extends ProjectNotFound_base {
   get message(): string;
 }
 //#endregion
+//#region src/State.d.ts
+/** Environment variable with the deploy key of the deployment that holds the state. */
+export declare const STATE_DEPLOY_KEY_ENV = "CONVEX_STATE_DEPLOY_KEY";
+/**
+ * Alchemy state in the alchemyState component of the deployment that the
+ * deploy key in CONVEX_STATE_DEPLOY_KEY names: the production deployment of
+ * the project. The key needs the actions `deployment:data:view` and
+ * `deployment:data:write`.
+ */
+export declare const state: () => Layer.Layer<State>;
+//#endregion
 export type { DeploymentAttributes, DeploymentProps, DeploymentRegion, EnvValue, ProjectAttributes, ProjectProps, Source };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/Credentials.ts","../src/ManagementApi.ts","../src/Providers.ts","../src/Push.ts","../src/Deployment.ts","../src/Project.ts"],"mappings":";;;;;;;;;;;UA6BiB;;WAEN,aAAa,SAAS;;WAEtB;;UAGM;;WAEN,aAAa,OAAO,OAAO;;WAE3B,gBAAgB,OAAO;;WAEvB,WAAW,OAAO,OAAO,SAAS;;;qBAGhC,oBAAoB;;qBAKpB;;qBAGA;;;;qBAOA,yBAAyB;;;;;;;;;qBAiCzB,kBAAiB,MAAM,MAAM;;qBA0B7B,aAAc;WAChB,cAAc,SAAS;WACvB,YAAY,SAAS;MAC5B,MAAM,MAAM;;;KC3GJ,mBAAmB,kBAAkB;KACrC,mBAAmB,kBAAkB;;UAGhC,YAAY;WAClB,OAAO;WACP;WACA,UAAU;;;;;;;;;;;;;qBAQR,uBAAuB;UAuBnB;;WAEN,UAAU,GACjB,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,cACP,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,0BACxC,OAAO,aAAa;;WAEhB,oBAAoB,GAC3B,mBACA,6BACA,WAAW,SAAS,kBACpB,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,gBAAgB,0BAA0B,OAAO,eAAe;;;;;;;;WAQhE,oBAAoB,mBAAmB,OAAO;;;;;WAK9C,YAAY,OAAO,SAAS,qBAAqB;;;qBAM/C,sBAAsB;;;;qBClFtB,kBAAkB;;;;;;qBAOlB,YAAa,cAAa,MAAM,MAAM,iBAA2B,MAAA,MAAA,8CAAA,mCAAA,oDAAA;;;;KC8BlE,oBAAoB,SAAS;;;;;KAM7B;;WAIG;;;;;;;;WAQA;;;;;;;WAOA;;;;;;qBA2BF,0BAA0B;MAIxB;;;;;;qBAMF,0BAA0B;MAIxB;;;;;;;;;qBAMF,uBAAuB;MAMrB;;;;;;;qBAQF,2BAA2B;MAIzB;;;;;;;qBAMF,oCAAoC;MAIlC;;;;;;qBAMF,kCAAkC;MAIhC;;;qBAuCF,oBACX;EACG;EAAa;;;;UCzHR;;WAEC;aAAoB;;;;;;;;WAOpB,SAAS;;WAET,MAAM,SAAS,eAAe;;KAG7B,mBACP;;WAEU;MAEV;;WAEU;;;;;WAKA;;;UAIL;WACC;WACA,MAAM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;UAGM,6BAA6B;;WAEnC;;WAEA;;YAGC,aAAa,8BAEvB,iBACA,6BAEA;qBAEW,8BAAU,cAAA;;;;;;;;;qBAKV,iCAAiC;MAU/B;;;;;;qBAMF,qCAAqC;MAInC;;;;;;;;;qBAMF,4BAA4B;MAS1B;;;;;KChJH,mBAAmB;KAEnB;;WAGG;;WAEA;;WAEA,mBAAmB;;WAEnB;;;WAIA;;WAEA;;UAGE;WACN;WACA;WACA;WACA;WACA;WACA;;YAGC,UAAU,2BAA2B,cAAc,0BAA0B;qBAC5E,2BAAO,cAAA;;;;;;;qBAGP,0BAA0B;MAIxB;;;;;;;;;;;;qBASF,gCAAgC;MAS9B;;;;;;;;qBAOF,yBAAyB;MAKvB;;;;;;qBAMF,+BAA+B;MAI7B;;;;;;;qBAMF,wBAAwB;MAItB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/Credentials.ts","../src/ManagementApi.ts","../src/Providers.ts","../src/Push.ts","../src/Deployment.ts","../src/Project.ts","../src/State.ts"],"mappings":";;;;;;;;;;;;UA6BiB;;WAEN,aAAa,SAAS;;WAEtB;;UAGM;;WAEN,aAAa,OAAO,OAAO;;WAE3B,gBAAgB,OAAO;;WAEvB,WAAW,OAAO,OAAO,SAAS;;;qBAGhC,oBAAoB;;qBAKpB;;qBAGA;;;;qBAOA,yBAAyB;;;;;;;;;qBAiCzB,kBAAiB,MAAM,MAAM;;qBA0B7B,aAAc;WAChB,cAAc,SAAS;WACvB,YAAY,SAAS;MAC5B,MAAM,MAAM;;;KC3GJ,mBAAmB,kBAAkB;KACrC,mBAAmB,kBAAkB;;UAGhC,YAAY;WAClB,OAAO;WACP;WACA,UAAU;;;;;;;;;;;;;qBAQR,uBAAuB;UAuBnB;;WAEN,UAAU,GACjB,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,cACP,mBACA,MAAM,QAAQ,qBAAqB,QAAQ,0BACxC,OAAO,aAAa;;WAEhB,oBAAoB,GAC3B,mBACA,6BACA,WAAW,SAAS,kBACpB,MAAM,QAAQ,qBAAqB,QAAQ,YAAY,QACpD,OAAO,OAAO,GAAG;;WAEb,gBAAgB,0BAA0B,OAAO,eAAe;;;;;;;;WAQhE,oBAAoB,mBAAmB,OAAO;;;;;WAK9C,YAAY,OAAO,SAAS,qBAAqB;;;qBAM/C,sBAAsB;;;;qBClFtB,kBAAkB;;;;;;qBAOlB,YAAa,cAAa,MAAM,MAAM,iBAA2B,MAAA,MAAA,8CAAA,mCAAA,oDAAA;;;;KC8BlE,oBAAoB,SAAS;;;;;KAM7B;;WAIG;;;;;;;;WAQA;;;;;;;WAOA;;;;;;qBA2BF,0BAA0B;MAIxB;;;;;;qBAMF,0BAA0B;MAIxB;;;;;;;;;qBAMF,uBAAuB;MAMrB;;;;;;;qBAQF,2BAA2B;MAIzB;;;;;;;qBAMF,oCAAoC;MAIlC;;;;;;qBAMF,kCAAkC;MAIhC;;;qBAuCF,oBACX;EACG;EAAa;;;;UCzHR;;WAEC;aAAoB;;;;;;;;WAOpB,SAAS;;WAET,MAAM,SAAS,eAAe;;KAG7B,mBACP;;WAEU;MAEV;;WAEU;;;;;WAKA;;;UAIL;WACC;WACA,MAAM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;UAGM,6BAA6B;;WAEnC;;WAEA;;YAGC,aAAa,8BAEvB,iBACA,6BAEA;qBAEW,8BAAU,cAAA;;;;;;;;;qBAKV,iCAAiC;MAU/B;;;;;;qBAMF,qCAAqC;MAInC;;;;;;;;;qBAMF,4BAA4B;MAS1B;;;;;KChJH,mBAAmB;KAEnB;;WAGG;;WAEA;;WAEA,mBAAmB;;WAEnB;;;WAIA;;WAEA;;UAGE;WACN;WACA;WACA;WACA;WACA;WACA;;YAGC,UAAU,2BAA2B,cAAc,0BAA0B;qBAC5E,2BAAO,cAAA;;;;;;;qBAGP,0BAA0B;MAIxB;;;;;;;;;;;;qBASF,gCAAgC;MAS9B;;;;;;;;qBAOF,yBAAyB;MAKvB;;;;;;qBAMF,+BAA+B;MAI7B;;;;;;;qBAMF,wBAAwB;MAItB;;;;;qBC7EF;;;;;;;qBAgQA,aAAY,MAAM,MAAM"}

package/lib/index.js

@@ -25,6 +25,7 @@ import { hashDirectory } from "alchemy/Command/Memo";
 import * as Clock from "effect/Clock";
 import * as ChildProcess from "effect/process/ChildProcess";
 import * as Stream from "effect/Stream";
+import { InMemoryService, STATE_STORE_VERSION, State, StateStoreError, encodeState, reviveState } from "alchemy/State";
 //#region src/Credentials.ts
 var Credentials = class extends Context.Service()("@samebase/alchemy-convex/Credentials") {};
 /** Environment variable for the access token, read by {@link fromConfig}. */
@@ -1256,6 +1257,191 @@ var Providers = class extends Provider.ProviderCollection()("Convex") {};
 */
 const providers = (credentials = fromConfig()) => Layer.effect(Providers, Provider.collection([Project, Deployment])).pipe(Layer.provide(Layer.mergeAll(ProjectProvider(), DeploymentProvider())), Layer.provide(ManagementApiLive()), Layer.provide(credentials), Layer.orDie);
 //#endregion
-export { ACCESS_TOKEN_ENV, AmbiguousDeployment, AmbiguousProject, CodePushFailed, ConvexApiError, ConvexAppNotFound, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DEPLOY_KEY_ENV, Deployment, DeploymentIdentityChange, EnvironmentNeedsDeployKey, ManagementApi, ProductionDeploymentNotFound, Project, ProjectDeploymentChange, ProjectNotFound, ProjectTeamChange, Providers, PushTargetMismatch, VariablesOwnedBySomeoneElse, fromConfig, fromValues, parseDeployOutput, providers };
+//#region src/State.ts
+/** Environment variable with the deploy key of the deployment that holds the state. */
+const STATE_DEPLOY_KEY_ENV = "CONVEX_STATE_DEPLOY_KEY";
+/** The component path of alchemyState in the app: its default name. */
+const COMPONENT_PATH = "alchemyState";
+/** The body of POST /api/function and /api/query, with HTTP 200 or 560 for a function error. */
+const Reply = Schema.Union([Schema.Struct({
+	status: Schema.Literal("success"),
+	value: Schema.Unknown
+}), Schema.Struct({
+	status: Schema.Literal("error"),
+	errorMessage: Schema.String
+})]);
+/** The value of `_system/frontend/components:list`: the root has path "", a removed mount is "unmounted". */
+const Components = Schema.Array(Schema.Struct({
+	path: Schema.String,
+	state: Schema.String
+}));
+const failure = (message) => new StateStoreError({ message: `Convex state: ${message}` });
+/** No reply, HTTP 429, or HTTP 5xx: a new attempt can succeed. Every call of the store is idempotent. */
+const isTransient = (error) => error.http !== void 0 && (error.http.status === void 0 || error.http.status === 429 || error.http.status >= 500);
+const post = (url, headers, body) => Effect.tryPromise({
+	try: () => fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			...headers
+		},
+		body: JSON.stringify(body)
+	}),
+	catch: () => new StateStoreError({
+		message: `Convex state: POST ${url} failed`,
+		http: {}
+	})
+}).pipe(Effect.flatMap((response) => response.ok || response.status === 560 ? Effect.tryPromise({
+	try: () => response.json(),
+	catch: () => failure(`${url} gave no JSON`)
+}) : Effect.fail(new StateStoreError({
+	message: `Convex state: POST ${url} failed with HTTP ${response.status}`,
+	http: { status: response.status }
+}))), Effect.retry({
+	while: isTransient,
+	schedule: Schedule.exponential("100 millis").pipe(Schedule.jittered),
+	times: 5
+}));
+const decode = (schema, what) => (value) => Schema.decodeUnknownEffect(schema)(value).pipe(Effect.mapError(() => failure(`bad ${what}`)));
+/**
+* The deployment URL of a deploy key. The Convex CLI makes the same unofficial
+* call for every deploy key (convex 1.46 `cli/lib/deploymentSelection.js`).
+*/
+const urlForKey = (key) => post("https://api.convex.dev/api/deployment/url_for_key", {}, { deployKey: Redacted.value(key) }).pipe(Effect.flatMap(decode(Schema.String, "deployment URL")));
+const makeFunctionApi = (url, key) => ({ call: (path, args, componentPath) => post(`${url}/api/${componentPath === void 0 ? "query" : "function"}`, { Authorization: `Convex ${Redacted.value(key)}` }, {
+	...componentPath === void 0 ? {} : { componentPath },
+	path,
+	args,
+	format: "json"
+}).pipe(Effect.flatMap(decode(Reply, `reply of ${path}`)), Effect.flatMap((reply) => reply.status === "success" ? Effect.succeed(reply.value) : Effect.fail(failure(reply.errorMessage.trim())))) });
+/** The state of the alchemyState mount: "active", "unmounted" (its rows are kept), or undefined. */
+const mountOf = (api) => api.call("_system/frontend/components:list", {}).pipe(Effect.flatMap(decode(Components, "component list")), Effect.map((components) => components.find((c) => c.path === COMPONENT_PATH)?.state));
+/** The component functions with Alchemy's encoding: the JSON text of encodeState. */
+const remoteOf = (api) => {
+	const run = (name, args) => api.call(`state:${name}`, args, COMPONENT_PATH);
+	const strings = (name, args) => run(name, args).pipe(Effect.flatMap(decode(Schema.Array(Schema.String), name)));
+	const optional = (name, args) => run(name, args).pipe(Effect.flatMap(decode(Schema.NullOr(Schema.String), name)));
+	const encode = (value) => JSON.stringify(encodeState(value));
+	return {
+		listStacks: () => strings("stacks", {}),
+		listStages: (stack) => strings("stages", { stack }),
+		list: (r) => strings("list", {
+			stack: r.stack,
+			stage: r.stage
+		}),
+		get: (r) => optional("get", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn
+		}).pipe(Effect.map((text) => text === null ? void 0 : JSON.parse(text, reviveState))),
+		getReplacedResources: (r) => strings("replaced", {
+			stack: r.stack,
+			stage: r.stage
+		}).pipe(Effect.map((texts) => texts.map((text) => JSON.parse(text, reviveState)))),
+		getOutput: (r) => optional("getOutput", {
+			stack: r.stack,
+			stage: r.stage
+		}).pipe(Effect.map((text) => text === null ? void 0 : JSON.parse(text, reviveState))),
+		set: (r) => run("set", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn,
+			value: encode(r.value)
+		}),
+		delete: (r) => run("remove", {
+			stack: r.stack,
+			stage: r.stage,
+			fqn: r.fqn
+		}),
+		deleteStack: (r) => run("removeStack", {
+			stack: r.stack,
+			stage: r.stage
+		}),
+		setOutput: (r) => run("setOutput", {
+			stack: r.stack,
+			stage: r.stage,
+			value: encode(r.value)
+		})
+	};
+};
+const unmounted = failure(`the ${COMPONENT_PATH} component of the deployment is unmounted. Its rows are kept: mount @samebase/alchemy-convex/convex.config in convex/convex.config.ts again.`);
+/**
+* The StateService over `api`. Without an alchemyState component at
+* the start, the state of the run stays in memory until a write finds the
+* component active.
+*/
+const makeConvexState = (api) => Effect.gen(function* () {
+	const remote = remoteOf(api);
+	const mount = yield* mountOf(api);
+	if (mount === "unmounted") return yield* unmounted;
+	let pending = mount === void 0;
+	const rows = {};
+	const outputs = {};
+	const memory = yield* InMemoryService(rows, outputs);
+	/** Moves the memory to the component once it is active. Rows that the run did not read stop it. */
+	const flush = Effect.gen(function* () {
+		const now = yield* mountOf(api);
+		if (now === void 0) return;
+		if (now !== "active") return yield* unmounted;
+		const stages = [.../* @__PURE__ */ new Set([...Object.keys(rows), ...Object.keys(outputs)])].flatMap((stack) => [.../* @__PURE__ */ new Set([...Object.keys(rows[stack] ?? {}), ...Object.keys(outputs[stack] ?? {})])].map((stage) => ({
+			stack,
+			stage
+		})));
+		for (const { stack, stage } of stages) {
+			const found = yield* remote.list({
+				stack,
+				stage
+			});
+			if (found.length > 0) return yield* failure(`${stack}/${stage} has ${found.length} rows in the deployment that this run did not read, so the run wrote none. Run it again.`);
+		}
+		for (const { stack, stage } of stages) {
+			for (const [fqn, value] of Object.entries(rows[stack]?.[stage] ?? {})) yield* remote.set({
+				stack,
+				stage,
+				fqn,
+				value
+			});
+			const byStage = outputs[stack];
+			if (byStage !== void 0 && stage in byStage) yield* remote.setOutput({
+				stack,
+				stage,
+				value: byStage[stage]
+			});
+		}
+		pending = false;
+	});
+	const read = (inMemory, inConvex) => Effect.suspend(() => pending ? inMemory : inConvex);
+	const write = (inMemory, inConvex, result) => Effect.suspend(() => pending ? Effect.tap(inMemory, () => flush) : Effect.as(inConvex, result));
+	return {
+		id: "convex",
+		getVersion: () => Effect.succeed(STATE_STORE_VERSION),
+		listStacks: () => read(memory.listStacks(), remote.listStacks()),
+		listStages: (stack) => read(memory.listStages(stack), remote.listStages(stack)),
+		list: (request) => read(memory.list(request), remote.list(request)),
+		get: (request) => read(memory.get(request), remote.get(request)),
+		getReplacedResources: (request) => read(memory.getReplacedResources(request), remote.getReplacedResources(request)),
+		getOutput: (request) => read(memory.getOutput(request), remote.getOutput(request)),
+		set: (request) => write(memory.set(request), remote.set(request), request.value),
+		delete: (request) => write(memory.delete(request), remote.delete(request), void 0),
+		deleteStack: (request) => write(memory.deleteStack(request), remote.deleteStack(request), void 0),
+		setOutput: (request) => write(memory.setOutput(request), remote.setOutput(request), request.value).pipe(Effect.tap(() => pending ? Effect.fail(failure(`the deployment of ${STATE_DEPLOY_KEY_ENV} has no ${COMPONENT_PATH} component at the end of the run, so this run saved no state. Mount @samebase/alchemy-convex/convex.config in convex/convex.config.ts.`)) : Effect.void))
+	};
+});
+/**
+* Alchemy state in the alchemyState component of the deployment that the
+* deploy key in CONVEX_STATE_DEPLOY_KEY names: the production deployment of
+* the project. The key needs the actions `deployment:data:view` and
+* `deployment:data:write`.
+*/
+const state = () => Layer.effect(State, Effect.gen(function* () {
+	const context = yield* Effect.context();
+	return yield* Effect.cached(Effect.gen(function* () {
+		const key = yield* Config.Redacted(STATE_DEPLOY_KEY_ENV);
+		if (keyTargetOf(Redacted.value(key)).kind !== "deployment") return yield* failure(`${STATE_DEPLOY_KEY_ENV} must be the deploy key of one deployment, such as prod:<name>|..., not a preview deploy key.`);
+		return yield* makeConvexState(makeFunctionApi(yield* urlForKey(key), key));
+	}).pipe(Effect.provideContext(context), Effect.orDie));
+}));
+//#endregion
+export { ACCESS_TOKEN_ENV, AmbiguousDeployment, AmbiguousProject, CodePushFailed, ConvexApiError, ConvexAppNotFound, ConvexCliNotFound, CreatedProjectNotFound, Credentials, CredentialsError, DEPLOY_KEY_ENV, Deployment, DeploymentIdentityChange, EnvironmentNeedsDeployKey, ManagementApi, ProductionDeploymentNotFound, Project, ProjectDeploymentChange, ProjectNotFound, ProjectTeamChange, Providers, PushTargetMismatch, STATE_DEPLOY_KEY_ENV, VariablesOwnedBySomeoneElse, fromConfig, fromValues, parseDeployOutput, providers, state };
 
 //# sourceMappingURL=index.js.map