@protobase/cli 0.8.1 → 0.9.0

package/dist/dev/dev-jobs.js

@@ -0,0 +1,25 @@
+import { checkJobsSchema, startJobs } from "@protobase/server";
+//#region src/dev/dev-jobs.ts
+const store = globalThis;
+/**
+* Runs the project's jobs in the dev server: started on the first load, once the jobs schema checks out, and given the
+* reloaded definitions on every load after it, so an edited job runs its new code from the next job on.
+*/
+const devJobs = async (db, definitions) => {
+	if (store.__protobaseJobs) return store.__protobaseJobs.update(definitions);
+	if (definitions.length === 0) return;
+	await checkJobsSchema(db);
+	store.__protobaseJobs = await startJobs({
+		db,
+		jobs: definitions,
+		onError: (error) => console.error(error)
+	});
+};
+/** Lets running jobs finish and stops them, when the dev server closes. */
+const stopDevJobs = async () => {
+	const runtime = store.__protobaseJobs;
+	delete store.__protobaseJobs;
+	await runtime?.stop();
+};
+//#endregion
+export { devJobs, stopDevJobs };

package/dist/dev/entry.js

@@ -1,11 +1,13 @@
+import { devJobs } from "./dev-jobs.js";
+import { projectAdmin } from "../project/project-admin.js";
 import { loadProject, projectDb } from "./project.js";
-import { checkAuthSchema, checkChanges, configExports, createAdmin, hasUsers } from "@protobase/server";
+import { checkAuthSchema, checkChanges, checkWebhooksSchema, configExports, hasUsers } from "@protobase/server";
 import { Hono } from "hono";
 //#region src/dev/entry.ts
 const projectDir = process.env.PROTOBASE_PROJECT;
 const project = await loadProject(projectDir, JSON.parse(process.env.PROTOBASE_EXTENSIONS ?? "[]"));
 const db = projectDb(project, projectDir);
-const { resources, views, pages, userMenu } = configExports(project.exports);
+const { resources } = configExports(project.exports);
 if (!project.authenticate) throw new Error("No authenticator: export `authenticate` (and `auth`) from protobase.config.ts; see https://docs.protobase.net/reference/auth/");
 const store = globalThis;
 if (project.auth && !store.__protobaseAuthSchemaChecked) {
@@ -13,22 +15,12 @@ if (project.auth && !store.__protobaseAuthSchemaChecked) {
 	store.__protobaseAuthSchemaChecked = true;
 }
 await checkChanges(db, resources.map((resource) => resource.toModel()), project.events);
-const admin = createAdmin({
-	resources,
-	views,
-	pages,
-	...userMenu && { userMenu },
-	db,
-	authenticate: project.authenticate,
-	...project.auth && { auth: project.auth },
-	...project.functions && { functions: project.functions },
-	...project.files && { files: project.files },
-	...project.events && { events: project.events },
-	options: {
-		onUnhandledError: (error) => console.error(error),
-		...project.options
-	}
-});
+if (project.webhooks) await checkWebhooksSchema(db, project.webhooks);
+const { admin, jobs } = projectAdmin({
+	...project,
+	authenticate: project.authenticate
+}, project.exports, db);
+await devJobs(db, jobs);
 var entry_default = new Hono().route("/", admin);
 if (project.auth && !store.__protobaseNoUsersShown) {
 	store.__protobaseNoUsersShown = true;

package/dist/dev/run.js

@@ -5,6 +5,7 @@ import { moduleFile } from "../module-file.js";
 import { layoutCheck } from "../build/layout-check.js";
 import { projectUiPlugin } from "../project/project-ui.js";
 import { checkDatabase } from "./check-database.js";
+import { stopDevJobs } from "./dev-jobs.js";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { createServer, searchForWorkspaceRoot } from "vite";
@@ -23,6 +24,10 @@ const reloadOnProjectChange = (dirs) => ({
 		if (dirs.some((dir) => file.startsWith(`${dir}${path.sep}`)) && !file.includes(`${path.sep}node_modules${path.sep}`)) server.environments.ssr.moduleGraph.invalidateAll();
 	}
 });
+const stopJobsOnClose = {
+	name: "protobase-jobs",
+	closeBundle: () => stopDevJobs()
+};
 const appDependencies = [
 	"react",
 	"react/jsx-runtime",
@@ -65,6 +70,7 @@ const runDev = async (options, out) => {
 		},
 		plugins: [
 			reloadOnProjectChange([options.projectDir, ...extensions.map((extension) => extension.dir)]),
+			stopJobsOnClose,
 			projectUiPlugin(options.projectDir, extensions),
 			extensionImports(options.projectDir, extensions),
 			extensionStyles(extensions),

package/dist/main.js

@@ -9,8 +9,10 @@ import { parseHosts } from "./dev/hosts.js";
 import { runDev } from "./dev/run.js";
 import { runDoctor } from "./doctor/run.js";
 import { runScaffold } from "./scaffold/run.js";
+import { closeOnSignals } from "./serve/signals.js";
 import { serveBundle } from "./serve/serve-bundle.js";
 import { serveBundleDir } from "./serve/serve-dir.js";
+import { loadWorkerBundle, startWorker } from "./worker/start-worker.js";
 import { registerOrganizations } from "./organizations/register.js";
 import { registerFiles } from "./files/register.js";
 import { registerMigration } from "./migration/register.js";
@@ -86,6 +88,15 @@ program.command("serve").description("Serve a bundle written by `protobase build
 	if (statSync(bundle).isDirectory()) await serveBundleDir(bundle, process.env, out);
 	else await serveBundle(bundle, process.env, out);
 });
+program.command("worker").description("Run the jobs of a bundle from `protobase build` in a process of their own, until SIGTERM or SIGINT, as `serve` runs them beside the API").argument("<bundle>", "the bundle folder, e.g. dist, or its dist/protobase.config.js").action(async (bundle) => {
+	loadNearestEnvFile(process.cwd());
+	const worker = await startWorker({
+		project: await loadWorkerBundle(bundle),
+		databaseUrl: process.env.DATABASE_URL || void 0
+	});
+	closeOnSignals(worker.stop);
+	out(`protobase worker running ${worker.jobs} job${worker.jobs === 1 ? "" : "s"}\n`);
+});
 registerUsers(program);
 registerOrganizations(program);
 registerToken(program);

package/dist/migration/load-project.js

@@ -3,7 +3,7 @@ import { importProjectFile } from "../project/import-project-file.js";
 import { createPgDb } from "../project/pg-db.js";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { configExports, mergeConfig } from "@protobase/server";
+import { configExports, jobDefinitions, mergeConfig } from "@protobase/server";
 import pg from "pg";
 //#region src/migration/load-project.ts
 const configOf = async (file) => (await importProjectFile(file)).default ?? {};
@@ -32,6 +32,8 @@ const loadMigrationProject = async (dir, extensions = []) => {
 		db: project.db ?? ownDb,
 		...project.auth && { auth: project.auth },
 		...project.events && { events: project.events },
+		...project.webhooks && { webhooks: project.webhooks },
+		jobs: jobDefinitions(project.jobs ?? {}),
 		close: async () => {
 			await ownDb?.destroy();
 		}

package/dist/migration/parts.js

@@ -1,14 +1,27 @@
-import { authSchemaMigration, changesMigration } from "@protobase/server";
+import { authSchemaMigration, changesMigration, jobsSchemaMigration, webhooksMigration } from "@protobase/server";
 //#region src/migration/parts.ts
 /** Every feature the project's config enables, in the order their files are written. */
-const migrationParts = (project) => [...project.auth ? [{
-	name: "auth",
-	title: "The auth schema changes this version of Protobase needs",
-	sql: () => authSchemaMigration(project.auth)
-}] : [], {
-	name: "changes",
-	title: "The change capture the resources' events need",
-	sql: () => changesMigration(project.db, project.models, project.events)
-}];
+const migrationParts = (project) => [
+	...project.auth ? [{
+		name: "auth",
+		title: "The auth schema changes this version of Protobase needs",
+		sql: () => authSchemaMigration(project.auth)
+	}] : [],
+	...project.jobs.length > 0 || project.models.some((model) => model.events) || project.webhooks ? [{
+		name: "jobs",
+		title: "The jobs schema this version of Protobase needs",
+		sql: () => jobsSchemaMigration(project.db)
+	}] : [],
+	{
+		name: "changes",
+		title: "The change capture the resources' events need",
+		sql: () => changesMigration(project.db, project.models, project.events)
+	},
+	...project.webhooks ? [{
+		name: "webhooks",
+		title: "The webhook subscriptions of webhooks()",
+		sql: () => webhooksMigration(project.db, project.webhooks, project.events)
+	}] : []
+];
 //#endregion
 export { migrationParts };

package/dist/migration/register.js

@@ -7,7 +7,7 @@ import path from "node:path";
 const out = (text) => process.stdout.write(text);
 const collect = (value, previous) => [...previous, value];
 const registerMigration = (program) => {
-	program.command("migration").description("Write what the database still needs for every feature the config enables (auth, events) as the project's next SQL migrations").option("--dir <dir>", "migrations folder", "db/migrations").option("--extend <dir>", "merge the protobase.config.ts in this folder before the project's, as dev and build do, repeatable", collect, []).action(async (opts) => {
+	program.command("migration").description("Write what the database still needs for every feature the config enables (auth, events, jobs) as the project's next SQL migrations").option("--dir <dir>", "migrations folder", "db/migrations").option("--extend <dir>", "merge the protobase.config.ts in this folder before the project's, as dev and build do, repeatable", collect, []).action(async (opts) => {
 		const project = await loadMigrationProject(process.cwd(), resolveExtensions(opts.extend));
 		try {
 			const files = await writeMigrations(migrationParts(project), path.resolve(opts.dir));

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.8.1";
+var version = "0.9.0";
 //#endregion
 export { version };

package/dist/project/project-admin.js

@@ -0,0 +1,35 @@
+import { configExports, createAdmin, jobDefinitions } from "@protobase/server";
+//#region src/project/project-admin.ts
+/**
+* The admin API of a project over `db`, as `dev`, `serve` and `worker` build it: its config module's resources, views,
+* pages and subscriptions, and the rest of its config. `jobs` are the project's own and the delivery of its events.
+*/
+const projectAdmin = (project, config, db) => {
+	const { resources, views, pages, userMenu, subscriptions } = configExports(config);
+	const own = jobDefinitions(project.jobs ?? {});
+	const admin = createAdmin({
+		resources,
+		views,
+		pages,
+		...userMenu && { userMenu },
+		db,
+		authenticate: project.authenticate,
+		...project.auth && { auth: project.auth },
+		...project.functions && { functions: project.functions },
+		...project.files && { files: project.files },
+		...project.events && { events: project.events },
+		...project.webhooks && { webhooks: project.webhooks },
+		jobs: own,
+		subscriptions,
+		options: {
+			onUnhandledError: (error) => console.error(error),
+			...project.options
+		}
+	});
+	return {
+		admin,
+		jobs: [...own, ...admin.jobs]
+	};
+};
+//#endregion
+export { projectAdmin };

package/dist/serve/app.js

@@ -1,31 +1,18 @@
 import { isApiPath } from "../bundle/manifest.js";
 import { serveStaticSite } from "./static-site.js";
-import { configExports, createAdmin } from "@protobase/server";
+import { jobsDrainApp } from "@protobase/server";
 import { Hono } from "hono";
 import { logger } from "hono/logger";
 //#region src/serve/app.ts
-const createServeApp = ({ project, db, requestLog, site }) => {
-	const { resources, views, pages, userMenu } = configExports(project.config);
-	const admin = createAdmin({
-		resources,
-		views,
-		pages,
-		...userMenu && { userMenu },
-		db,
-		authenticate: project.authenticate,
-		...project.auth && { auth: project.auth },
-		...project.functions && { functions: project.functions },
-		...project.files && { files: project.files },
-		...project.events && { events: project.events },
-		options: {
-			onUnhandledError: (error) => console.error(error),
-			...project.options
-		}
-	});
+const createServeApp = ({ admin, requestLog, site, jobs, drainToken }) => {
 	const app = new Hono();
 	if (requestLog) app.use(logger());
 	app.get("/health", (c) => c.json({ status: "ok" }));
 	if (site) app.use("*", (c, next) => isApiPath(site.api, c.req.path) ? next() : serveStaticSite(site, c.req.raw));
+	if (jobs && drainToken) app.route("/", jobsDrainApp({
+		runtime: jobs,
+		token: drainToken
+	}));
 	app.route("/", admin);
 	return app;
 };

package/dist/serve/env.js

@@ -5,11 +5,15 @@ const readServeEnv = (env) => {
 	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`PORT must be a port number, not "${env.PORT}"`);
 	const minutes = env.PROTOBASE_FILES_CLEANUP_MINUTES ? Number(env.PROTOBASE_FILES_CLEANUP_MINUTES) : 60;
 	if (!Number.isInteger(minutes) || minutes < 0) throw new Error(`PROTOBASE_FILES_CLEANUP_MINUTES must be a whole number of minutes, not "${env.PROTOBASE_FILES_CLEANUP_MINUTES}"`);
+	const jobs = env.PROTOBASE_JOBS ?? "on";
+	if (jobs !== "on" && jobs !== "off") throw new Error(`PROTOBASE_JOBS must be on or off, not "${jobs}"`);
 	return {
 		port,
 		databaseUrl: env.DATABASE_URL || void 0,
 		requestLog: Boolean(env.REQUEST_LOG),
-		filesCleanupMinutes: minutes
+		filesCleanupMinutes: minutes,
+		runJobs: jobs === "on",
+		...env.PROTOBASE_JOBS_DRAIN_TOKEN && { drainToken: env.PROTOBASE_JOBS_DRAIN_TOKEN }
 	};
 };
 //#endregion

package/dist/serve/lifecycle.js

@@ -1,7 +1,8 @@
+import { projectAdmin } from "../project/project-admin.js";
 import { createPgDb } from "../project/pg-db.js";
 import { createServeApp } from "./app.js";
 import { startCleanupTimer } from "./cleanup-timer.js";
-import { checkAuthSchema, checkChanges, configExports, createFileCleanup } from "@protobase/server";
+import { checkAuthSchema, checkChanges, checkJobsSchema, checkWebhooksSchema, configExports, createFileCleanup, startJobs } from "@protobase/server";
 import { createAdaptorServer } from "@hono/node-server";
 import pg from "pg";
 //#region src/serve/lifecycle.ts
@@ -19,14 +20,35 @@ const startServe = async ({ project, env, createDb = (url) => createPgDb(pg, url
 	const ownDb = project.db ? void 0 : createDb(env.databaseUrl);
 	const db = project.db ?? ownDb;
 	const { resources } = configExports(project.config);
-	const app = createServeApp({
-		project,
-		db,
-		requestLog: env.requestLog,
-		site
-	});
-	const server = createAdaptorServer({ fetch: app.fetch });
-	await checkChanges(db, resources.map((resource) => resource.toModel()), project.events).then(() => listen(server, env.port)).catch(async (error) => {
+	const startJobsAndListen = async () => {
+		await checkChanges(db, resources.map((resource) => resource.toModel()), project.events);
+		if (project.webhooks) await checkWebhooksSchema(db, project.webhooks);
+		const { admin, jobs: definitions } = projectAdmin(project, project.config, db);
+		if (definitions.length > 0) await checkJobsSchema(db);
+		const jobs = definitions.length > 0 ? await startJobs({
+			db,
+			jobs: definitions,
+			work: env.runJobs,
+			onError: (error) => console.error(error)
+		}) : void 0;
+		const app = createServeApp({
+			admin,
+			requestLog: env.requestLog,
+			site,
+			...jobs && { jobs },
+			...env.drainToken && { drainToken: env.drainToken }
+		});
+		const server = createAdaptorServer({ fetch: app.fetch });
+		await listen(server, env.port).catch(async (error) => {
+			await jobs?.stop();
+			throw error;
+		});
+		return {
+			server,
+			jobs
+		};
+	};
+	const { server, jobs } = await startJobsAndListen().catch(async (error) => {
 		await ownDb?.destroy();
 		throw error;
 	});
@@ -39,6 +61,7 @@ const startServe = async ({ project, env, createDb = (url) => createPgDb(pg, url
 	const close = async () => {
 		await closeServer(server);
 		await timer?.stop();
+		await jobs?.stop();
 		await ownDb?.destroy();
 	};
 	return {

package/dist/worker/start-worker.js

@@ -0,0 +1,56 @@
+import { readManifest } from "../bundle/manifest.js";
+import { checkBundleVersion } from "../serve/bundle-version.js";
+import { projectAdmin } from "../project/project-admin.js";
+import { createPgDb } from "../project/pg-db.js";
+import { loadBundle } from "../serve/load-bundle.js";
+import { statSync } from "node:fs";
+import path from "node:path";
+import { checkJobsSchema, configExports, jobDefinitions, startJobs } from "@protobase/server";
+import pg from "pg";
+//#region src/worker/start-worker.ts
+const bundleConfigFile = async (bundle) => {
+	if (!statSync(bundle).isDirectory()) return bundle;
+	return path.join(bundle, (await readManifest(bundle)).server);
+};
+/**
+* Runs the project's jobs, and nothing else, until `stop`: the same handlers `protobase serve` runs, in a process of
+* their own. It reads the jobs schema at start and refuses one that is missing or behind, like `serve`.
+*/
+const startWorker = async ({ project, databaseUrl, createDb = (url) => createPgDb(pg, url) }) => {
+	const withEvents = configExports(project.config).resources.some((resource) => resource.toModel().events);
+	if (jobDefinitions(project.jobs ?? {}).length === 0 && !withEvents) throw new Error("The bundle has no jobs: export them from protobase.config.ts as `jobs`, or give a resource events");
+	if (!project.db && !databaseUrl) throw new Error("No database: set DATABASE_URL or export `db` from protobase.config.ts");
+	const ownDb = project.db ? void 0 : createDb(databaseUrl);
+	const db = project.db ?? ownDb;
+	const start = async () => {
+		const { jobs: definitions } = projectAdmin(project, project.config, db);
+		await checkJobsSchema(db);
+		return {
+			definitions,
+			runtime: await startJobs({
+				db,
+				jobs: definitions,
+				onError: (error) => console.error(error)
+			})
+		};
+	};
+	const { definitions, runtime: jobs } = await start().catch(async (error) => {
+		await ownDb?.destroy();
+		throw error;
+	});
+	return {
+		jobs: definitions.length,
+		stop: async () => {
+			await jobs.stop();
+			await ownDb?.destroy();
+		}
+	};
+};
+/** `protobase worker <bundle>`: the bundle's jobs until SIGTERM or SIGINT, once its manifest shows a version this CLI runs. */
+const loadWorkerBundle = async (bundle) => {
+	const file = await bundleConfigFile(bundle);
+	await checkBundleVersion(file);
+	return loadBundle(file);
+};
+//#endregion
+export { bundleConfigFile, loadWorkerBundle, startWorker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/cli",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "The protobase command: scaffold, doctor, dev, build and serve a Protobase project.",
   "license": "Apache-2.0",
   "repository": {
@@ -34,11 +34,11 @@
   "dependencies": {
     "@hono/node-server": "^2.1.3",
     "@hono/vite-dev-server": "^0.26.1",
-    "@protobase/layout": "0.8.1",
-    "@protobase/query": "0.8.1",
-    "@protobase/schema": "0.8.1",
-    "@protobase/server": "0.8.1",
-    "@protobase/ui": "0.8.1",
+    "@protobase/layout": "0.9.0",
+    "@protobase/query": "0.9.0",
+    "@protobase/schema": "0.9.0",
+    "@protobase/server": "0.9.0",
+    "@protobase/ui": "0.9.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@tailwindcss/vite": "^4.3.3",
     "@vitejs/plugin-react": "^6.1.2",