@tekki-forge/runtime-api 0.3.0 → 0.4.0

package/dist/service.js

@@ -5,14 +5,24 @@ import { BadRequestException, ConflictException, ForbiddenException, NotFoundExc
 import { queryableFields, unreadableFields, unwritableFields } from "./access.js";
 import { ComputedEngine } from "./computed.js";
 import { EventBus } from "./events.js";
+import { EventOutbox } from "./outbox.js";
+import { ExportService } from "./exports.js";
+import DecimalDefault from "decimal.js";
 import { NotificationService } from "./notifications.js";
 import { QueryError, parseListQuery, searchWhere } from "./query.js";
 import { diff, label, manyIds, relationInclude, serialize, toCsv, toPrismaData } from "./serialize.js";
 import { ApiKeyService } from "./api-keys.js";
 import { teamIdsOf } from "./teams.js";
 import { SettingsService, isGlobalAdminRole } from "./settings.js";
+const Decimal = (DecimalDefault.default ?? DecimalDefault);
 const EXPORT_LIMIT = 10_000;
-const TX = { timeout: 20_000, maxWait: 10_000 };
+const TX = { timeout: 20_000, maxWait: 10_000, isolationLevel: "Serializable" };
+/** Serializable transactions that lose a race are retried; the losing attempt changed nothing. */
+const TX_ATTEMPTS = 6;
+/** Custom actions may call other systems: no serializable retries (a handler never runs twice) and a longer budget. */
+const ACTION_TX = { timeout: 60_000, maxWait: 10_000, isolationLevel: "ReadCommitted" };
+/** What subscribers outside the framework receive: the internal delivery snapshot stays private. */
+const publicEvent = ({ delivery: _delivery, ...event }) => event;
 const invalid = (issues) => new BadRequestException({ statusCode: 400, error: "Bad Request", message: "Validation failed", issues });
 export class ForgeService {
     options;
@@ -21,6 +31,8 @@ export class ForgeService {
     auth;
     socialProviders;
     events;
+    outbox;
+    exports;
     computed;
     notifications;
     apiKeys;
@@ -39,6 +51,11 @@ export class ForgeService {
         this.auth = options.auth;
         this.socialProviders = options.socialProviders ?? [];
         this.events = options.events ?? new EventBus();
+        if (options.prisma.forgeOutbox)
+            this.outbox = new EventOutbox(options.prisma, this.events);
+        this.exports = new ExportService(this);
+        if (options.files)
+            this.useFileStore(options.files);
         this.computed = new ComputedEngine(options.app);
         this.apiKeys = new ApiKeyService(options.app, options.prisma);
         this.settings = new SettingsService(options.app, options.prisma);
@@ -63,7 +80,8 @@ export class ForgeService {
                     throw new Error(`[forge] ${entity.name}: extension configures unknown transition "${t}"`);
             }
             for (const [pattern, handler] of Object.entries(x.on ?? {}))
-                this.events.on(pattern, handler, `${entity.name} extension`);
+                this.events.on(pattern, (event) => handler(publicEvent(event)), `${entity.name} extension`);
+            this.registerAfterHooks(entity, x);
         }
         for (const e of options.app.entities) {
             const rules = [...Object.values(e.permissions), ...e.fields.flatMap((f) => [f.access?.read, f.access?.write]), ...(e.workflow?.transitions.map((t) => t.permission) ?? [])];
@@ -74,6 +92,37 @@ export class ForgeService {
             }
         }
     }
+    onModuleInit() { this.outbox?.start(); if (this.prisma.forgeExport)
+        this.exports.start(); }
+    async onModuleDestroy() { this.exports.stop(); await this.outbox?.stop(); }
+    registerAfterHooks(entity, extension) {
+        const hydrate = (row) => {
+            const result = { ...row };
+            for (const key of ["createdAt", "updatedAt", "deletedAt", ...entity.fields.filter((f) => ["date", "datetime"].includes(f.kind)).map((f) => f.name)])
+                if (typeof result[key] === "string")
+                    result[key] = new Date(result[key]);
+            for (const f of entity.fields)
+                if (["money", "decimal"].includes(f.kind) && ["string", "number"].includes(typeof result[f.name]))
+                    result[f.name] = new Decimal(result[f.name]);
+            return result;
+        };
+        this.events.on(`${entity.name}.*`, async (event) => {
+            const d = event.delivery;
+            if (!d)
+                return;
+            const ctx = this.hookContext(entity, d.context);
+            const record = hydrate(d.record);
+            const previous = hydrate(d.previous);
+            if (event.action === "created")
+                await extension.hooks?.afterCreate?.({ ...ctx, record });
+            if (event.action === "updated")
+                await extension.hooks?.afterUpdate?.({ ...ctx, record, previous });
+            if (event.action === "deleted")
+                await extension.hooks?.afterDelete?.({ ...ctx, record });
+            if (event.action === "transitioned")
+                await extension.transitions?.[event.name]?.after?.({ ...ctx, record, previous, input: d.input ?? {} });
+        }, `${entity.name} after-hooks`);
+    }
     /** Plugins attach behaviour (hooks, actions, event handlers) to the entities they contribute. */
     addExtension(ext) {
         const entity = this.byName.get(ext.entity);
@@ -88,11 +137,14 @@ export class ForgeService {
             transitions: { ...existing?.transitions, ...ext.transitions },
         });
         for (const [pattern, handler] of Object.entries(ext.on ?? {}))
-            this.events.on(pattern, handler, `${ext.entity} extension`);
+            this.events.on(pattern, (event) => handler(publicEvent(event)), `${ext.entity} extension`);
+        this.registerAfterHooks(entity, ext);
     }
     /** Used by the storage plugin during setup. */
     useFileStore(store) {
         this.options.files = store;
+        this.events.on("*", async (event) => { if (event.delivery?.releasedFiles?.length)
+            await store.release(event.delivery.releasedFiles); }, "released files");
     }
     /** Startup check once plugins have been set up. */
     assertReady() {
@@ -358,8 +410,10 @@ export class ForgeService {
         if (value === undefined || value === null || existing?.[rel.foreignKey] === value)
             return null;
         const principal = ctx.principal;
-        if (rel.owner && value !== actingUserId(ctx) && !principal.roles.includes("admin")) {
-            throw new ForbiddenException(`Only admins can assign the ${f.label.toLowerCase()} to another user`);
+        // Giving a record to someone else is an admin's call unless the relation names other roles (assignableBy);
+        // write access to the field alone never grants it.
+        if (rel.owner && value !== actingUserId(ctx) && !principal.roles.includes("admin") && !rel.assignableBy?.some((r) => principal.roles.includes(r))) {
+            throw new ForbiddenException(rel.assignableBy?.length ? `Only ${["admin", ...rel.assignableBy].join(", ")} can assign the ${f.label.toLowerCase()} to another user` : `Only admins can assign the ${f.label.toLowerCase()} to another user`);
         }
         if (rel.entity === "Team" && !principal.roles.includes("admin") && !(principal.teamIds ?? []).includes(value)) {
             throw new ForbiddenException("You can only assign records to teams you belong to");
@@ -400,7 +454,7 @@ export class ForgeService {
             },
         });
     }
-    async emit(entity, action, ctx, record, extra) {
+    async queueEvent(db, entity, action, ctx, record, extra, previous, input, releasedFiles) {
         const event = {
             id: randomUUID(),
             type: `${entity.name}.${action}`,
@@ -410,18 +464,81 @@ export class ForgeService {
             actor: ctx.user ? { id: ctx.user.id, name: ctx.user.name } : ctx.apiKey ? { id: `apikey:${ctx.apiKey.id}`, name: `API key "${ctx.apiKey.name}"` } : null,
             organizationId: ctx.principal?.organizationId ?? record?.organizationId ?? null,
             occurredAt: new Date().toISOString(),
+            // Stored until delivered: who acted, never where from (no IP address).
+            delivery: { context: { principal: ctx.principal, user: ctx.user, session: ctx.session, ...(ctx.apiKey ? { apiKey: ctx.apiKey } : {}) }, record, ...(previous ? { previous } : {}), ...(input ? { input } : {}), ...(releasedFiles?.length ? { releasedFiles } : {}) },
             ...extra,
         };
-        await this.events.emit(event);
-    }
-    tx(fn) {
-        return this.prisma.$transaction(fn, TX);
+        if (this.outbox)
+            await this.outbox.enqueue(db, event);
+        return event;
+    }
+    async dispatch(event) {
+        if (this.outbox) {
+            let timer;
+            try {
+                await Promise.race([this.outbox.deliver(event.id), new Promise((resolve) => { timer = setTimeout(resolve, 250); })]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        else
+            await this.events.emit(event);
+    }
+    versionInput(body, existing) {
+        if (!body || typeof body !== "object" || Array.isArray(body))
+            throw new BadRequestException("Expected a JSON object");
+        const input = { ...body };
+        if (input && "_version" in input) {
+            if (!Number.isSafeInteger(input._version) || input._version < 1)
+                throw new BadRequestException("_version must be a positive integer");
+            if (input._version !== existing.forgeVersion)
+                throw new ConflictException("This record changed while you were editing it. Reload and review the latest values before saving.");
+            delete input._version;
+        }
+        return input;
+    }
+    versionWhere(id, record) {
+        return { id, ...(typeof record.forgeVersion === "number" ? { forgeVersion: record.forgeVersion } : {}) };
+    }
+    versionIncrement(record) {
+        return typeof record.forgeVersion === "number" ? { forgeVersion: { increment: 1 } } : {};
+    }
+    /**
+     * Run `fn` in one transaction. Serializable by default: an attempt that loses a race with a concurrent
+     * write (P2034) is rolled back and run again, so `fn` must only change the database. A record that
+     * changed since it was read (P2025 on a versioned update) is a 409 at once.
+     */
+    async tx(fn, options = {}) {
+        const attempts = options.action ? 1 : TX_ATTEMPTS;
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await this.prisma.$transaction(fn, options.action ? ACTION_TX : TX);
+            }
+            catch (e) {
+                const code = e.code ?? "";
+                if (code === "P2034" && attempt < attempts) {
+                    await new Promise((r) => setTimeout(r, Math.random() * 10 * 2 ** attempt));
+                    continue;
+                }
+                if (["P2034", "P2025"].includes(code))
+                    throw new ConflictException("This record changed during the operation. Reload and try again.");
+                throw e;
+            }
+        }
     }
     // ─── CRUD ───────────────────────────────────────────────────────────────────
     async list(entity, query, ctx) {
         const decision = this.authorizeOp(entity, "read", ctx);
         const q = this.parse(entity, query, ctx);
         const where = { AND: [...this.baseWhere(entity, ctx, q.trashed), ...this.scopeWhere(entity, decision, ctx), ...q.where] };
+        if (q.pagination === "cursor" || q.count === false) {
+            if (q.after)
+                where.AND.push({ id: { [q.orderBy[0]?.id === "desc" ? "lt" : "gt"]: q.after } });
+            const rows = await this.delegate(entity).findMany({ where, orderBy: q.orderBy, ...(q.pagination ? {} : { skip: (q.page - 1) * q.pageSize }), take: q.pageSize + 1, include: relationInclude(entity) });
+            const data = rows.slice(0, q.pageSize);
+            return { data: await Promise.all(data.map((r) => this.present(entity, r, ctx))), meta: { page: q.page, pageSize: q.pageSize, total: null, pages: null, hasMore: rows.length > q.pageSize, nextCursor: rows.length > q.pageSize ? data.at(-1)?.id ?? null : null } };
+        }
         const [total, rows] = await this.prisma.$transaction([
             this.delegate(entity).count({ where }),
             this.delegate(entity).findMany({ where, orderBy: q.orderBy, skip: (q.page - 1) * q.pageSize, take: q.pageSize, include: relationInclude(entity) }),
@@ -467,25 +584,27 @@ export class ForgeService {
         }
         const hooks = this.extensions.get(entity.name)?.hooks;
         const include = relationInclude(entity);
+        let event;
         const record = await this.tx(async (db) => {
-            data = (await hooks?.beforeCreate?.({ ...this.hookContext(entity, ctx, db), data })) ?? data;
+            // Each attempt starts from the validated input: a retried attempt never sees a hook's earlier output.
+            let input = (await hooks?.beforeCreate?.({ ...this.hookContext(entity, ctx, db), data: { ...data } })) ?? { ...data };
             if (entity.features.tenant)
-                data.organizationId = ctx.principal.organizationId;
-            let row = await this.delegate(entity, db).create({ data: this.finalizeJson(data), include });
+                input = { ...input, organizationId: ctx.principal.organizationId };
+            let row = await this.delegate(entity, db).create({ data: this.finalizeJson(input), include });
             row = await this.computed.refresh(db, entity, row, include);
             await this.syncFiles(db, entity, row, null);
             await this.computed.refreshParents(db, entity, null, row);
             await this.audit(db, entity, ctx, options.auditAction ?? "create", row.id, { after: serialize(entity, row) });
+            event = await this.queueEvent(db, entity, "created", ctx, row, { recordId: row.id });
             return row;
         });
-        await this.emit(entity, "created", ctx, record, { recordId: record.id });
-        await hooks?.afterCreate?.({ ...this.hookContext(entity, ctx), record });
+        await this.dispatch(event);
         return this.present(entity, record, ctx);
     }
     async update(entity, id, body, ctx) {
         this.authorizeOp(entity, "update", ctx);
         const existing = await this.loadFor(entity, id, "update", ctx);
-        let data = this.validate(entity, "update", body);
+        let data = this.validate(entity, "update", this.versionInput(body, existing));
         const nulls = entity.fields.filter((f) => f.required && f.apiName in data && data[f.apiName] === null).map((f) => ({ path: f.apiName, message: "Required" }));
         if (nulls.length)
             throw invalid(nulls);
@@ -493,25 +612,20 @@ export class ForgeService {
         const hooks = this.extensions.get(entity.name)?.hooks;
         const include = relationInclude(entity);
         let released = [];
+        let event;
         const record = await this.tx(async (db) => {
-            data = (await hooks?.beforeUpdate?.({ ...this.hookContext(entity, ctx, db), data, existing })) ?? data;
-            let row = await this.delegate(entity, db).update({ where: { id }, data: this.finalizeJson(data), include });
+            const input = (await hooks?.beforeUpdate?.({ ...this.hookContext(entity, ctx, db), data: { ...data }, existing })) ?? { ...data };
+            let row = await this.delegate(entity, db).update({ where: this.versionWhere(id, existing), data: { ...this.finalizeJson(input), ...this.versionIncrement(existing) }, include });
             row = await this.computed.refresh(db, entity, row, include);
             released = await this.syncFiles(db, entity, row, existing);
             await this.computed.refreshParents(db, entity, existing, row);
             const changes = diff(serialize(entity, existing), serialize(entity, row));
             if (Object.keys(changes).length)
                 await this.audit(db, entity, ctx, "update", id, changes);
+            event = await this.queueEvent(db, entity, "updated", ctx, row, { recordId: id, previous: serialize(entity, existing, { apiPrefix: this.app.api.prefix }), changes }, existing, undefined, released);
             return row;
         });
-        if (released.length)
-            await this.options.files.release(released);
-        await this.emit(entity, "updated", ctx, record, {
-            recordId: id,
-            previous: serialize(entity, existing, { apiPrefix: this.app.api.prefix }),
-            changes: diff(serialize(entity, existing), serialize(entity, record)),
-        });
-        await hooks?.afterUpdate?.({ ...this.hookContext(entity, ctx), record, previous: existing });
+        await this.dispatch(event);
         return this.present(entity, record, ctx);
     }
     async remove(entity, id, ctx) {
@@ -519,49 +633,60 @@ export class ForgeService {
         const record = await this.loadFor(entity, id, "delete", ctx);
         const hooks = this.extensions.get(entity.name)?.hooks;
         let released = [];
+        let event;
         await this.tx(async (db) => {
             await hooks?.beforeDelete?.({ ...this.hookContext(entity, ctx, db), record });
             if (entity.features.softDelete)
-                await this.delegate(entity, db).update({ where: { id }, data: { deletedAt: new Date() } });
+                await this.delegate(entity, db).update({ where: this.versionWhere(id, record), data: { deletedAt: new Date(), ...this.versionIncrement(record) } });
             else {
-                await this.delegate(entity, db).delete({ where: { id } });
+                await this.delegate(entity, db).delete({ where: this.versionWhere(id, record) });
                 released = entity.fields.filter((f) => f.file && record[f.apiName]).map((f) => record[f.apiName]);
             }
             await this.computed.refreshParents(db, entity, record, null);
             await this.audit(db, entity, ctx, entity.features.softDelete ? "soft-delete" : "delete", id, { before: serialize(entity, record) });
+            event = await this.queueEvent(db, entity, "deleted", ctx, record, { recordId: id }, undefined, undefined, released);
         });
-        if (released.length)
-            await this.options.files.release(released);
-        await this.emit(entity, "deleted", ctx, record, { recordId: id });
-        await hooks?.afterDelete?.({ ...this.hookContext(entity, ctx), record });
+        await this.dispatch(event);
     }
     async bulkDelete(entity, body, ctx) {
         if (!entity.features.bulkDelete)
             throw new NotFoundException("Bulk delete is disabled for this resource");
+        this.authorizeOp(entity, "delete", ctx);
         const ids = body?.ids;
         if (!Array.isArray(ids) || ids.length === 0 || ids.length > 500 || !ids.every((i) => typeof i === "string")) {
             throw new BadRequestException("ids must be an array of 1–500 record ids");
         }
         let deleted = 0;
+        const failed = [];
         for (const id of new Set(ids)) {
-            await this.remove(entity, id, ctx);
-            deleted++;
+            try {
+                await this.remove(entity, id, ctx);
+                deleted++;
+            }
+            catch {
+                failed.push({ id, message: "Record could not be deleted; check access, references or concurrent changes" });
+            }
         }
-        return { deleted };
+        return { deleted, failed };
     }
     async restore(entity, id, ctx) {
         if (!entity.features.softDelete)
             throw new NotFoundException(`${entity.label} does not support restore`);
         this.authorizeOp(entity, "update", ctx);
-        await this.loadFor(entity, id, "update", ctx, { trashed: "only" });
+        const previous = await this.loadFor(entity, id, "update", ctx, { trashed: "only" });
+        let event;
         const include = relationInclude(entity);
+        const hooks = this.extensions.get(entity.name)?.hooks;
         const record = await this.tx(async (db) => {
-            const row = await this.delegate(entity, db).update({ where: { id }, data: { deletedAt: null }, include });
+            // Restoring is an update: the rules that guard edits (locks, overlaps, parents' states) apply to it too.
+            const input = (await hooks?.beforeUpdate?.({ ...this.hookContext(entity, ctx, db), data: {}, existing: previous })) ?? {};
+            const row = await this.delegate(entity, db).update({ where: this.versionWhere(id, previous), data: { ...this.finalizeJson(input), deletedAt: null, ...this.versionIncrement(previous) }, include });
             await this.computed.refreshParents(db, entity, null, row);
             await this.audit(db, entity, ctx, "restore", id, {});
+            event = await this.queueEvent(db, entity, "restored", ctx, row, { recordId: id });
             return row;
         });
-        await this.emit(entity, "restored", ctx, record, { recordId: id });
+        await this.dispatch(event);
         return this.present(entity, record, ctx);
     }
     async transition(entity, id, name, body, ctx) {
@@ -575,24 +700,21 @@ export class ForgeService {
             throw new ConflictException(`Cannot "${t.label}" a ${entity.label.toLowerCase()} that is ${from} (allowed from: ${t.from.join(", ")})`);
         }
         const ext = this.extensions.get(entity.name)?.transitions?.[name];
-        const verdict = await ext?.guard?.({ ...this.hookContext(entity, ctx), record, input: (body ?? {}) });
-        if (verdict === false || typeof verdict === "string")
-            throw new ConflictException(typeof verdict === "string" ? verdict : `"${t.label}" is not possible right now`);
+        const input = this.versionInput(body ?? {}, record);
         const include = relationInclude(entity);
+        let event;
         const updated = await this.tx(async (db) => {
-            let row = await this.delegate(entity, db).update({ where: { id }, data: { [wf.field]: t.to }, include });
+            const verdict = await ext?.guard?.({ ...this.hookContext(entity, ctx, db), record, input });
+            if (verdict === false || typeof verdict === "string")
+                throw new ConflictException(typeof verdict === "string" ? verdict : `"${t.label}" is not possible right now`);
+            let row = await this.delegate(entity, db).update({ where: { ...this.versionWhere(id, record), [wf.field]: from }, data: { [wf.field]: t.to, ...this.versionIncrement(record) }, include });
             row = await this.computed.refresh(db, entity, row, include);
             await this.computed.refreshParents(db, entity, record, row);
             await this.audit(db, entity, ctx, `transition:${name}`, id, { [wf.field]: { from, to: t.to } });
+            event = await this.queueEvent(db, entity, "transitioned", ctx, row, { recordId: id, name, previous: serialize(entity, record, { apiPrefix: this.app.api.prefix }), changes: { [wf.field]: { from, to: t.to } } }, record, input);
             return row;
         });
-        await this.emit(entity, "transitioned", ctx, updated, {
-            recordId: id,
-            name,
-            previous: serialize(entity, record, { apiPrefix: this.app.api.prefix }),
-            changes: { [wf.field]: { from, to: t.to } },
-        });
-        await ext?.after?.({ ...this.hookContext(entity, ctx), record: updated, previous: record, input: (body ?? {}) });
+        await this.dispatch(event);
         return this.present(entity, updated, ctx);
     }
     async runAction(entity, id, name, body, ctx) {
@@ -603,17 +725,22 @@ export class ForgeService {
         if (!handler)
             throw new NotImplementedException(`Action "${name}" has no handler — implement it in ${entity.name.toLowerCase()}.extension.ts`);
         const record = await this.loadFor(entity, id, "update", ctx, { rule: action.permission });
-        const result = await handler({ ...this.hookContext(entity, ctx), record, input: (body ?? {}) });
-        // Actions may change the record through prisma directly; keep computed values and parents current.
-        const fresh = await this.delegate(entity).findUnique({ where: { id }, include: relationInclude(entity) });
-        if (fresh) {
-            await this.tx(async (db) => {
-                const row = await this.computed.refresh(db, entity, fresh);
-                await this.computed.refreshParents(db, entity, record, row);
-                await this.audit(db, entity, ctx, `action:${name}`, id, {});
-            });
-        }
-        await this.emit(entity, "action", ctx, fresh, { recordId: id, name });
+        const input = this.versionInput(body ?? {}, record);
+        let event;
+        const result = await this.tx(async (db) => {
+            // Writes through ctx.prisma share this transaction and roll back if the handler throws. The record is
+            // not locked while the handler runs (a write through another client must not wait on us); the version
+            // check comes last, so a concurrent edit still turns the action into a 409.
+            const result = await handler({ ...this.hookContext(entity, ctx, db), record, input });
+            await this.delegate(entity, db).update({ where: this.versionWhere(id, record), data: this.versionIncrement(record) });
+            const fresh = await this.delegate(entity, db).findUnique({ where: { id }, include: relationInclude(entity) });
+            const row = fresh ? await this.computed.refresh(db, entity, fresh) : null;
+            await this.computed.refreshParents(db, entity, record, row);
+            await this.audit(db, entity, ctx, `action:${name}`, id, diff(serialize(entity, record), row ? serialize(entity, row) : {}));
+            event = await this.queueEvent(db, entity, "action", ctx, row, { recordId: id, name, result: result ?? null });
+            return result;
+        }, { action: true });
+        await this.dispatch(event);
         return { ok: true, result: result ?? null };
     }
     async lookup(entity, query, ctx) {