@trylight/app 0.3.6 → 0.3.8

package/README.md

@@ -91,10 +91,12 @@ drizzle-kit's own layout) and applied, whatever it does to the rows there (a
 removed column's values are archived first, below); one the rows refuse is taken back out,
 so the change stays pending rather than blocking every later migrate. Changed
 indexes and constraints are dropped before the columns they cover and enums
-only after, so the two halves apply in order. Syncs and migrates each hold a Postgres advisory lock (with a
-lock_timeout), so the dev server's watcher and an agent's own sync never
-overlap, and a process that dies releases it. `migrate` applies the journal; in an app's sandbox the agent's shell
-asks the platform's migrate socket to run it. `check` (in `pnpm build`)
+only after, so the two halves apply in order. Syncs and migrates each hold a
+Postgres advisory lock, so the dev server's watcher and an agent's own sync
+never overlap, and a process that dies releases it. A wait for the lock is
+bounded (`LOCK_WAIT_MS` in `src/db/locks.ts`), then fails naming its holder.
+`migrate` applies the journal; in an app's sandbox the agent's shell asks
+the platform's migrate socket to run it. `check` (in `pnpm build`)
 fails while `db/schema` has changes no migration holds.
 
 ## Recoverable deletes
@@ -103,13 +105,13 @@ fails while `db/schema` has changes no migration holds.
 that records each insert, update, delete and truncate in `light_changes` (the
 new row, `{ column: { from, to } }`, or the old row), whoever wrote it: the
 actor is `light.actor_kind/_id/_name`, which the entities route and the platform's
-`mii db write` set per transaction, or else the database role. A migration
+`light db write` set per transaction, or else the database role. A migration
 that drops a table or column or changes a column's type first copies what it
 destroys into `light_archive` (`light_archive_values`, called at the top of
 the migration, so in its transaction) and the migrate prints "Archived N
 values from table.column". Both tables refuse UPDATE, DELETE and TRUNCATE (a guard against mistakes:
 the owner role can still drop the trigger). DDL an agent runs itself (`drop
-table` through `mii db write`) is not archived.
+table` through `light db write`) is not archived.
 `migrate` installs the functions before applying migrations and the triggers
 after; the template's AGENTS.md has the restore SQL.
 

package/dist/db/cli.js

@@ -10,6 +10,7 @@ import { migrate } from "drizzle-orm/postgres-js/migrator";
 import postgres from "postgres";
 import { z } from "zod/v4";
 import { archiveNotices, entityTables, prepareAudit, trackTables } from "./audit.js";
+import { LockWaitError, takeLock } from "./locks.js";
 import { MIGRATIONS_DIR, SCHEMA_ENTRY, plan, unwriteMigration, writeMigration } from "./migrations.js";
 import { env } from "../server/env.js";
 /**
@@ -18,13 +19,9 @@ import { env } from "../server/env.js";
  * credential, behind this socket.
  */
 const PLATFORM_MIGRATE = "/run/mii/migrate.sock";
-/** Postgres advisory locks: one migrate, and one sync, of a database at a time. */
-const MIGRATE_LOCK_KEY = 4_815_162_342;
-const SYNC_LOCK_KEY = 4_815_162_343;
 /** Exit code of a migrate whose migrations committed but whose change tracking (triggers, index) didn't go on. */
 const APPLIED_UNTRACKED = 2;
-// pg_advisory_lock waits for the one before it; a process that dies releases it.
-// Only on a direct connection: behind a transaction pooler the lock stays on a
+// Session locks (./locks.ts) only on a direct connection: behind a transaction pooler the lock stays on a
 // pooled server connection after the process exits, and every later sync waits.
 const connect = (onnotice = () => undefined) => postgres(unpooledDatabaseUrl(), { max: 1, onnotice });
 const root = process.cwd();
@@ -50,7 +47,7 @@ function unpooledDatabaseUrl() {
 async function sync() {
     const client = connect();
     try {
-        await client `select pg_advisory_lock(${SYNC_LOCK_KEY})`;
+        await takeLock(client, "sync");
         const planned = await plan(root, await loadSchema());
         if (planned.statements.length === 0)
             return await applyMigrations();
@@ -64,7 +61,7 @@ async function sync() {
         });
         if (applied !== 0 && applied !== APPLIED_UNTRACKED) {
             unwriteMigration(root, tag);
-            console.error(`${MIGRATIONS_DIR}/${tag}.sql didn't apply, so it was taken back; change db/schema and save again.`);
+            console.error(`${MIGRATIONS_DIR}/${tag}.sql didn't apply, so it was taken back; sync again once the error above is dealt with.`);
         }
         return applied;
     }
@@ -93,7 +90,7 @@ async function applyMigrations() {
     const archived = archiveNotices();
     const client = connect(archived.onnotice);
     try {
-        await client `select pg_advisory_lock(${MIGRATE_LOCK_KEY})`;
+        await takeLock(client, "migrate");
         const tables = entityTables(await loadSchema());
         await prepareAudit(client);
         await migrate(drizzle(client), { migrationsFolder: join(root, MIGRATIONS_DIR) });
@@ -128,4 +125,10 @@ async function migrateThroughPlatform() {
 // Last, so every const above is initialized before a command reads it.
 const commands = { sync, migrate: applyMigrations, check };
 const usage = z.enum(["sync", "migrate", "check"], { error: "Usage: light-db sync | migrate | check" });
-process.exit(await commands[usage.parse(command)]());
+const exitCode = await commands[usage.parse(command)]().catch((error) => {
+    if (!(error instanceof LockWaitError))
+        throw error;
+    console.error(error.message);
+    return 1;
+});
+process.exit(exitCode);

package/dist/db/locks.d.ts

@@ -0,0 +1,13 @@
+import postgres from "postgres";
+/** Postgres advisory locks: one migrate, and one sync, of a database at a time. */
+export declare const LOCKS: {
+    migrate: number;
+    sync: number;
+};
+/** How long a sync or migrate waits for the one before it, then fails naming who holds the lock. */
+export declare const LOCK_WAIT_MS = 30000;
+/** A sync or migrate gave up waiting for its lock; the message says who holds it. */
+export declare class LockWaitError extends Error {
+}
+/** Takes `command`'s session lock, or throws naming its holder after `LOCK_WAIT_MS`. */
+export declare function takeLock(client: postgres.Sql, command: keyof typeof LOCKS): Promise<void>;

package/dist/db/locks.js

@@ -0,0 +1,35 @@
+import postgres from "postgres";
+import { z } from "zod/v4";
+/** Postgres advisory locks: one migrate, and one sync, of a database at a time. */
+export const LOCKS = { migrate: 4_815_162_342, sync: 4_815_162_343 };
+/** How long a sync or migrate waits for the one before it, then fails naming who holds the lock. */
+export const LOCK_WAIT_MS = 30_000;
+const LOCK_NOT_AVAILABLE = "55P03";
+// Exclusive, so at most one backend holds it.
+const holderRows = z.array(z.object({ pid: z.number() })).max(1);
+/** A sync or migrate gave up waiting for its lock; the message says who holds it. */
+export class LockWaitError extends Error {
+}
+/** Takes `command`'s session lock, or throws naming its holder after `LOCK_WAIT_MS`. */
+export async function takeLock(client, command) {
+    const key = LOCKS[command];
+    try {
+        await client.begin(async (tx) => {
+            await tx `select set_config('lock_timeout', ${`${LOCK_WAIT_MS}ms`}, true)`;
+            await tx `select pg_advisory_lock(${key})`;
+        });
+    }
+    catch (error) {
+        if (!(error instanceof postgres.PostgresError) || error.code !== LOCK_NOT_AVAILABLE)
+            throw error;
+        const [holder] = holderRows.parse(await client `
+      select pid from pg_locks
+      where locktype = 'advisory' and granted and objsubid = 1
+        and database = (select oid from pg_database where datname = current_database())
+        and ((classid::bigint << 32) | objid::bigint) = ${key}`);
+        const waited = `light-db ${command}: waited ${LOCK_WAIT_MS / 1000}s for the ${command} lock`;
+        if (holder === undefined)
+            throw new LockWaitError(`${waited}; it came free just now, so run it again.`);
+        throw new LockWaitError(`${waited}, held by backend ${holder.pid}; if no other sync or migrate is running, the database's owner ends it with pg_terminate_backend(${holder.pid}).`);
+    }
+}

package/dist/invoke/contracts.d.ts

@@ -1,7 +1,7 @@
 import type { z } from "zod/v4";
 type ObjectSchema = z.ZodType<Record<string, unknown>, Record<string, unknown>>;
 export type Contract = {
-    /** The id `mii contract create` printed. */
+    /** The id `light contract create` printed. */
     readonly id: string;
     readonly input: ObjectSchema;
     readonly output: ObjectSchema;

package/dist/invoke/server.d.ts

@@ -20,7 +20,7 @@ export type MiiInvoke<C extends Contracts> = {
     readonly handler: (request: Request) => Promise<Response>;
     /**
      * Start a contract from a POST server function, as the person whose request
-     * it is answering, and return the run's id without waiting for it: for work
+     * it is answering (on a public app, a visitor with no session), and return the run's id without waiting for it: for work
      * that must be recorded with its run (a job row that names it). A page
      * follows it with `resume(id)`. Refusals reject with InvocationError, with
      * the codes a button's press gets.

package/dist/invoke/server.js

@@ -6,7 +6,8 @@ import { isSameOrigin, readCookie } from "../chat/server.js";
 import { errorBody } from "../request-error.js";
 import { isUuid } from "../uuid.js";
 import { failedRun, InvocationError } from "./error.js";
-import { INVOKE_BASE_PATH } from "../platform/contract.js";
+import { APP_CALLER_HEADERS, INVOKE_BASE_PATH } from "../platform/contract.js";
+import { env } from "../server/env.js";
 export { InvocationError };
 function routeOf(request) {
     const { pathname } = new URL(request.url);
@@ -21,6 +22,14 @@ function routeOf(request) {
     const [, id = ""] = read;
     return { kind: "read", id };
 }
+function platformPath(route) {
+    switch (route.kind) {
+        case "start":
+            return "/invocations";
+        case "read":
+            return `/invocations/${route.id}`;
+    }
+}
 const invokeBody = z.object({ key: z.string(), input: z.unknown() });
 const plazaInvocation = z.object({
     id: z.string(),
@@ -67,28 +76,40 @@ function startBody(contract, key, rawInput) {
     return JSON.stringify({ contractId: contract.id, input: input.data, outputSchema: contract.outputSchema });
 }
 /**
- * The person behind a request to this app: the session cookie, from one of
+ * The caller behind a request to this app: the session cookie, from one of
  * this app's own pages. Every org app shares one site with every other
  * (*.<domain>), so a page on another org's app can send this app's cookie along.
  */
-async function signedIn(auth, request) {
+async function callerOf(auth, request) {
     if (!isSameOrigin(request, new URL(request.url))) {
         throw new InvocationError(403, "cross_site", "Contracts can only be invoked from this app's own pages.");
     }
     const token = readCookie(request.headers.get("cookie"), auth.SESSION_COOKIE);
-    if (token === null)
-        throw new InvocationError(401, "not_signed_in", "Sign in to use this.");
+    if (token === null) {
+        const { appSecret } = env();
+        if (appSecret === null)
+            throw new InvocationError(401, "not_signed_in", "Sign in to use this.");
+        return { kind: "visitor", appId: miiAuthConfig().appId, secret: appSecret };
+    }
     const session = await auth.resolveSessionWithPlaza(token);
     if (session === null)
         throw new InvocationError(401, "sign_in_again", "Sign out and back in to use it here.");
-    return { token, plazaToken: session.plazaToken };
+    return { kind: "person", token, plazaToken: session.plazaToken };
+}
+function callerHeaders(caller) {
+    switch (caller.kind) {
+        case "person":
+            return { Authorization: `Bearer ${caller.plazaToken}` };
+        case "visitor":
+            return { [APP_CALLER_HEADERS.appId]: caller.appId, [APP_CALLER_HEADERS.secret]: caller.secret };
+    }
 }
-/** One call to the platform's contract API as the person; a refused token ends their session. Rejects only when the platform can't be reached. */
-async function callPlaza(auth, person, call) {
+/** One call to the platform's contract API as the caller; a refused token ends a person's session. Rejects only when the platform can't be reached. */
+async function callPlaza(auth, caller, call) {
     const answer = await fetch(call.target, {
         method: call.method,
         headers: {
-            Authorization: `Bearer ${person.plazaToken}`,
+            ...callerHeaders(caller),
             ...(call.body === null ? {} : { "Content-Type": "application/json" })
         },
         body: call.body,
@@ -96,17 +117,17 @@ async function callPlaza(auth, person, call) {
         redirect: "manual",
         signal: call.signal
     });
-    if (answer.status === 401 || answer.status === 403) {
-        await auth.revokeSession(person.token, answer.status === 403 ? "not_a_member" : "token_rejected");
+    if (caller.kind === "person" && (answer.status === 401 || answer.status === 403)) {
+        await auth.revokeSession(caller.token, answer.status === 403 ? "not_a_member" : "token_rejected");
     }
     return answer;
 }
 const plazaTarget = (path) => new URL(`${miiAuthConfig().plazaUrl}/api/app-contracts/v1${path}`);
-/** One call to the platform as the person, read as JSON. A refusal, or no answer, rejects with InvocationError. */
-async function askPlaza(auth, person, call) {
+/** One call to the platform as the caller, read as JSON. A refusal, or no answer, rejects with InvocationError. */
+async function askPlaza(auth, caller, call) {
     let answer;
     try {
-        answer = await callPlaza(auth, person, call);
+        answer = await callPlaza(auth, caller, call);
     }
     catch (error) {
         if (call.signal !== null && call.signal.aborted)
@@ -143,10 +164,10 @@ export function createMiiInvoke(auth, contracts, { reportError = (error, context
         if (route.kind === "read" && !isUuid(route.id)) {
             return refuse(404, "not_found", "Invocation not found.");
         }
-        let person;
+        let caller;
         let body = null;
         try {
-            person = await signedIn(auth, request);
+            caller = await callerOf(auth, request);
             if (route.kind === "start")
                 body = await readInvoke(request, declared);
         }
@@ -155,7 +176,7 @@ export function createMiiInvoke(auth, contracts, { reportError = (error, context
                 throw error;
             return refuse(error.status, error.code, error.message);
         }
-        const target = plazaTarget(route.kind === "start" ? "/invocations" : `/invocations/${route.id}`);
+        const target = plazaTarget(platformPath(route));
         // How long the platform may hold a read of a pending invocation. This app's own
         // function limit has to outlast it (see the README).
         const wait = new URL(request.url).searchParams.get("wait");
@@ -164,7 +185,7 @@ export function createMiiInvoke(auth, contracts, { reportError = (error, context
         let answer;
         try {
             // The browser giving up ends the platform's hold too.
-            answer = await callPlaza(auth, person, { method: request.method, target, body, signal: request.signal });
+            answer = await callPlaza(auth, caller, { method: request.method, target, body, signal: request.signal });
         }
         catch (error) {
             if (!request.signal.aborted)
@@ -190,17 +211,17 @@ export function createMiiInvoke(auth, contracts, { reportError = (error, context
         return respond(answer.status, plazaInvocation.parse(await answer.json()), declared, reportError);
     };
     const start = async ({ request, key, input, signal = null }) => {
-        const person = await signedIn(auth, request);
+        const caller = await callerOf(auth, request);
         const body = startBody(declared.get(key), key, input);
-        const answer = await askPlaza(auth, person, { method: "POST", target: plazaTarget("/invocations"), body, signal });
+        const answer = await askPlaza(auth, caller, { method: "POST", target: plazaTarget("/invocations"), body, signal });
         return { id: plazaInvocation.parse(answer).id };
     };
     const result = async (key, id, request) => {
-        const person = await signedIn(auth, request);
+        const caller = await callerOf(auth, request);
         const contract = contracts[key];
         if (!isUuid(id))
             throw new InvocationError(404, "not_found", "Invocation not found.");
-        const invocation = plazaInvocation.parse(await askPlaza(auth, person, { method: "GET", target: plazaTarget(`/invocations/${id}`), body: null, signal: null }));
+        const invocation = plazaInvocation.parse(await askPlaza(auth, caller, { method: "GET", target: plazaTarget(`/invocations/${id}`), body: null, signal: null }));
         if (invocation.contractId !== contract.id) {
             throw new InvocationError(404, "not_found", `Invocation ${id} is not a run of "${key}".`);
         }

package/dist/platform/contract.d.ts

@@ -16,6 +16,13 @@ export declare const PLATFORM_AUTH_PATHS: {
     /** "Continue with Google / Microsoft": the platform signs the person in and returns with a one-time code. */
     socialSignIn: string;
 };
+/** An app's server calling the platform as the app, for a visitor with no session: which app, and its secret. */
+export declare const APP_CALLER_HEADERS: {
+    appId: string;
+    secret: string;
+};
+/** The server env that secret is provisioned in. */
+export declare const APP_SECRET_ENV = "PLATFORM_APP_SECRET";
 /** The platform's chat API: an app's chat route forwards any path beneath it, so a new widget route needs no SDK release. */
 export declare const PLATFORM_CHAT_PATH = "/api/app-chat/v1/chat";
 /** What this app's chat server forwards beyond the first contract: the widget, served to every app version, offers only these. */

package/dist/platform/contract.js

@@ -22,6 +22,10 @@ export const PLATFORM_AUTH_PATHS = {
     /** "Continue with Google / Microsoft": the platform signs the person in and returns with a one-time code. */
     socialSignIn: "/api/app-auth/social"
 };
+/** An app's server calling the platform as the app, for a visitor with no session: which app, and its secret. */
+export const APP_CALLER_HEADERS = { appId: "x-app-id", secret: "x-app-secret" };
+/** The server env that secret is provisioned in. */
+export const APP_SECRET_ENV = "PLATFORM_APP_SECRET";
 /** The platform's chat API: an app's chat route forwards any path beneath it, so a new widget route needs no SDK release. */
 export const PLATFORM_CHAT_PATH = "/api/app-chat/v1/chat";
 /** What this app's chat server forwards beyond the first contract: the widget, served to every app version, offers only these. */

package/dist/schema.d.ts

@@ -17,7 +17,7 @@ export type FieldSources = Partial<Record<string, FieldSource>>;
  * Who may use a table through `app.table(...)`. Reads always go through the
  * app's door: members only, or anyone with the link on a public app. Writes
  * are either people signed in to the app ("door") or only the org's agents,
- * through `mii db write` ("agents").
+ * through `light db write` ("agents").
  */
 export type Access = {
     readonly read: "door";

package/dist/server/env.d.ts

@@ -2,6 +2,7 @@
 export declare function env(): {
     databaseUrl: string | undefined;
     unpooledDatabaseUrl: string | undefined;
+    appSecret: string | null;
     /** Sign-in needs the platform, this app's id in it, and a database for sessions. */
     configured: boolean;
     /**

package/dist/server/env.js

@@ -1,6 +1,7 @@
 // The server env the SDK reads, in one schema: what the platform injects
 // (Vercel env, the sandbox's .env.local).
 import { z } from "zod/v4";
+import { APP_SECRET_ENV } from "../platform/contract.js";
 const serverEnv = z
     .object({
     DATABASE_URL: z.string().min(1).optional(),
@@ -8,11 +9,14 @@ const serverEnv = z
     DATABASE_URL_UNPOOLED: z.string().min(1).optional(),
     MII_PLAZA_URL: z.url().optional(),
     MII_APP_ID: z.string().min(1).optional(),
+    /** What this app's server presents to call the platform as the app, for a visitor with no session. */
+    [APP_SECRET_ENV]: z.string().min(1).nullable().default(null),
     NODE_ENV: z.string().optional()
 })
     .transform((env) => ({
     databaseUrl: env.DATABASE_URL,
     unpooledDatabaseUrl: env.DATABASE_URL_UNPOOLED,
+    appSecret: env[APP_SECRET_ENV],
     /** Sign-in needs the platform, this app's id in it, and a database for sessions. */
     configured: Boolean(env.MII_PLAZA_URL && env.MII_APP_ID && env.DATABASE_URL),
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylight/app",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "The Light SDK every v2 org app depends on: entities (Drizzle tables with a typed client), sign-in, contracts and in-app chat.",
   "license": "UNLICENSED",
   "type": "module",