letopis 1.4.2 → 3.0.0

package/dist/sync.js

@@ -1,4 +1,7 @@
-import { LetopisError } from './errors.js';
+import { lerr, lmsg } from './errors.js';
+import { internalsOf } from './internal.js';
+import { NOLOG, traced } from './log.js';
+import { RESERVED_CLASS_NAMES } from './types.js';
 const ROLLBACK = Symbol('sync-dry-run');
 /** Канонический JSON: ключи по алфавиту — сравнение описаний без учёта порядка ключей. */
 function canon(v) {
@@ -9,11 +12,32 @@ function canon(v) {
     return JSON.stringify(v);
 }
 export async function syncModels(db, models, opts = {}) {
+    // событие sync (логирование 3.0): логгер — фасада, которым пишут классы
+    return traced(internalsOf(db)?.log ?? NOLOG, 'sync', { op: 'syncModels' }, () => syncCore(db, models, opts), (r) => ({
+        rows: r.created.length + r.updated.length,
+        detail: { applied: r.applied, models: models.length, created: r.created, updated: r.updated, unchanged: r.unchanged.length,
+            skipped: r.skipped, lost: r.lost.length },
+    }));
+}
+async function syncCore(db, models, opts) {
+    // хаб с именем метода цепочки или корня db (модель собрана мимо hub()) — отказ до записи (план 2.0, этап 4, п. 2;
+    // 7.10 №3); связь с таким именем отклоняет база
+    for (const m of models) {
+        if (m.kind === 'hub' && RESERVED_CLASS_NAMES.includes(m.name))
+            throw lerr('model.sync_hub_name_reserved', { name: m.name });
+    }
     const res = { applied: Boolean(opts.apply), created: [], updated: [], unchanged: [], skipped: [], lost: models.flatMap((m) => m.lostRules()) };
+    // преобразования Zod (.trim(), .toLowerCase(), .transform(), z.preprocess …) база и валидатор letopis не исполняют —
+    // данные записались бы как есть: отказ до записи (план 2.1, A11); refine остаётся в отчёте lost
+    const transforms = res.lost.filter((l) => l.kind !== 'refine');
+    if (transforms.length) {
+        throw lerr('model.transform_unsupported', { rules: transforms.map((l) => `${l.path} (${l.kind})`).join(', ') }, { detail: { rules: transforms } });
+    }
+    checkEndRoles(db.registry, models);
     const S = `"${db.schema.replace(/"/g, '""')}"`;
-    // предок раньше потомка; класс-источник агрегата раньше цели: агрегат над классом, которого ещё нет, база отклоняет.
-    // Круг (агрегат над собственным потомком, цикл агрегатов) так не упорядочить — отказ до записи с самим кругом (хвост
-    // ревью доработок после 1.2.0: раньше обход молча ставил потомка раньше предка)
+    // предок раньше потомка: потомка класса, которого ещё нет, база отклоняет. Круг родителей (модель, собранная мимо
+    // hub()) так не упорядочить — отказ до записи с самим кругом (хвост ревью доработок после 1.2.0: раньше обход молча
+    // ставил потомка раньше предка)
     const ordered = [];
     const path = [];
     const visit = (m) => {
@@ -21,23 +45,21 @@ export async function syncModels(db, models, opts = {}) {
             return;
         const at = path.indexOf(m);
         if (at >= 0) {
-            throw new LetopisError('invalid_class', `syncModels: модели зависят друг от друга по кругу: ${[...path.slice(at), m].map((x) => x.name).join(' → ')} — `
-                + 'родителя и источник агрегата база ждёт раньше класса');
+            throw lerr('model.models_cycle', { cycle: [...path.slice(at), m].map((x) => x.name).join(' → ') });
         }
         path.push(m);
         if (m.parent && models.includes(m.parent))
             visit(m.parent);
-        for (const a of Object.values(m.describe().aggregate ?? {})) {
-            const src = models.find((x) => x.name === a.of);
-            if (src)
-                visit(src);
-        }
         path.pop();
         ordered.push(m);
     };
     models.forEach(visit);
+    // у корня connect({ admin }) классы пишет администраторский пул с той же сессией (план 2.0, 7.9 №3): правка класса
+    // со строками требует прав, которых у роли приложения может не быть
+    const adminTx = internalsOf(db)?.adminTx;
+    const run = (fn) => (adminTx ? adminTx(fn) : db.transaction(fn));
     try {
-        await db.transaction(async (tx) => {
+        await run(async (tx) => {
             for (const m of ordered) {
                 const desc = m.describe();
                 const [cur] = await tx.unsafe(`select tenant = ${S}.ctx_tenant() as own, data - 'resolved' as data from ${S}.entity
@@ -69,6 +91,40 @@ export async function syncModels(db, models, opts = {}) {
         await db.refresh();
     return res;
 }
+const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
+/** Набор классов конца — как class_set() базы: список без повторов по порядку. */
+const classSet = (c) => [...new Set(typeof c === 'string' ? [c] : c)].sort().join(', ');
+/**
+ * Имя роли конца — одно на арендатора: в любом другом классе (своём или системном) роль с тем же именем обязана вести
+ * на тот же набор классов (база: sql-write.end_other_class в 60-write.sql, проверка ends при записи Class). Системные
+ * классы занимают роли User и Tenant (member → Account), Group и Object (rule → Resource). Проверка — до записи, по
+ * реестру и самим моделям, с понятным текстом; база проверяет всё равно.
+ */
+function checkEndRoles(reg, models) {
+    const names = new Set(models.map((m) => m.name));
+    const seen = new Map();
+    for (const c of reg.all()) {
+        if (names.has(c.name))
+            continue;
+        for (const [role, e] of Object.entries(c.ends)) {
+            if (!seen.has(role) || c.tenant === SYSTEM_ID)
+                seen.set(role, { cls: c.name, set: classSet(e.class), system: c.tenant === SYSTEM_ID });
+        }
+    }
+    for (const m of models) {
+        for (const [role, e] of Object.entries(m.describe().ends ?? {})) {
+            const mine = classSet(e.class);
+            const other = seen.get(role);
+            if (other && other.set !== mine) {
+                if (other.system)
+                    throw lerr('model.end_role_system', { end: role, model: m.name, cls: other.cls, target: other.set });
+                throw lerr('model.end_role_taken', { end: role, model: m.name, mine, cls: other.cls, target: other.set });
+            }
+            if (!other)
+                seen.set(role, { cls: m.name, set: mine, system: false });
+        }
+    }
+}
 /** Тип TypeScript по JSON Schema подмножества. */
 export function schemaToTs(s, indent = '') {
     if (!s || Object.keys(s).length === 0)
@@ -108,23 +164,40 @@ export function schemaToTs(s, indent = '') {
         }
     }).join(' | ');
 }
-/** Объявления `<Класс>Data` и `<Класс>Links` для классов реестра (кроме системных). */
+/**
+ * Объявления `<Класс>Data` и `<Класс>Links` для классов реестра и `<Класс>Model` — имя, алиас, концы с классами целей
+ * и предки (ModelLike, typed.ts), — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`
+ * (план 2.0, этап 4, п. 1). Классы арендатора System (системные и классы сидов пакета) — только с includeSystem
+ * (`letopis types --system`); без него системные классы даёт встроенный набор SystemModels. Пометка в первой строке —
+ * запись каталога model.types_header.
+ */
 export function generateTypes(registry, opts = {}) {
-    const out = ['// Сгенерировано letopis types — не править руками.', ''];
+    const out = [`// ${lmsg('model.types_header')}`, ''];
+    const models = [];
+    const lit = (v) => JSON.stringify(v);
     for (const c of registry.all().sort((a, b) => a.name.localeCompare(b.name))) {
         if (!opts.includeSystem && c.tenant === '2eba6d0a-1edd-4bb6-a85a-a703dab49035')
             continue;
         // идентификатор TypeScript — буквы Unicode, цифры, _ и $: кириллические имена классов допустимы (план 2.0, 7.5 №1)
         if (!/^[\p{L}_$][\p{L}\p{N}_$]*$/u.test(c.name))
-            throw new LetopisError('invalid_class', `types: имя класса ${c.name} не годится для идентификатора TypeScript`);
+            throw lerr('model.types_class_name', { name: c.name });
         // additionalProperties: false верхнего уровня в тип не переносится — лишние ключи и так ошибка типов
         const { additionalProperties: _closed, ...open } = c.schema;
         void _closed;
         // объектный литерал — интерфейс; класс без полей, union и открытая схема — псевдоним типа (иначе неверный TypeScript)
         const data = schemaToTs(open);
         out.push(/^\{[\s\S]*\}$/.test(data) && !/\}\s*&/.test(data) ? `export interface ${c.name}Data ${data}` : `export type ${c.name}Data = ${data};`);
-        const ends = Object.entries(c.ends).map(([role, e]) => `  ${JSON.stringify(role)}${e.required || (e.min ?? 0) > 0 ? '' : '?'}: ${e.many ? 'string[]' : 'string'};`);
-        out.push(`export interface ${c.name}Links {${ends.length ? `\n${ends.join('\n')}\n` : ''}}`, '');
+        const required = (e) => e.required === true || (e.min ?? 0) > 0;
+        const ends = Object.entries(c.ends).map(([role, e]) => `  ${lit(role)}${required(e) ? '' : '?'}: ${e.many ? 'string[]' : 'string'};`);
+        out.push(`export interface ${c.name}Links {${ends.length ? `\n${ends.join('\n')}\n` : ''}}`);
+        // концы с классами целей и предки — переходы, слоты и семейства строгих типов (typed.ts: ModelLike)
+        const specs = Object.entries(c.ends).map(([role, e]) => {
+            const targets = (Array.isArray(e.class) ? e.class : [e.class]).map(lit).join(' | ');
+            return `      ${lit(role)}: { targets: ${targets}; many: ${e.many === true}; required: ${required(e)} };`;
+        });
+        out.push(`export interface ${c.name}Model {`, `  readonly name: ${lit(c.name)};`, ...(c.alias ? [`  readonly alias: ${lit(c.alias)};`] : []), '  readonly __types?: {', `    data: ${c.name}Data;`, `    links: ${c.name}Links;`, `    ends: {${specs.length ? `\n${specs.join('\n')}\n    ` : ''}};`, `    ancestors: ${(c.ancestors.length ? c.ancestors : [c.name]).map(lit).join(' | ')};`, '  };', '}', '');
+        models.push(`${c.name}Model`);
     }
+    out.push(`export type Models = readonly [${models.join(', ')}];`, '');
     return out.join('\n');
 }

package/dist/tx.d.ts

@@ -23,6 +23,7 @@
  * записи. Неотправленное (ошибка отправки) остаётся в очереди до следующего интервала.
  */
 import type postgres from 'postgres';
+import { type Log } from './log.js';
 type Sql = postgres.Sql<Record<string, unknown>>;
 export type Tx = postgres.TransactionSql<Record<string, unknown>>;
 /** Транзиентные ошибки PG, которые снимает повтор: взаимная блокировка, сериализация. */
@@ -54,11 +55,12 @@ export declare class Notifier {
     private channel;
     private intervalMs;
     private onError;
+    private log;
     private queue;
     private timer;
     private stopped;
     private flushing;
-    constructor(sql: Sql, channel: string, intervalMs: number, onError?: (e: unknown) => void);
+    constructor(sql: Sql, channel: string, intervalMs: number, onError?: (e: unknown) => void, log?: Log);
     /** Добавить нагрузки из letopis.changed (строка через запятую). */
     add(changed: string | null | undefined): void;
     private schedule;
@@ -93,11 +95,23 @@ export interface TxContext {
     passes?: AclPasses;
     /** После успешной операции (продление сессии раз в минуту). */
     after?: () => void;
+    /**
+     * Сессия кончилась (no_session): выдать новую и вписать её токен в failed — у подключения по ключу APIKEY ключ
+     * обменивается заново. true — операцию можно повторить (один раз). Нет — no_session как есть.
+     */
+    renew?: (failed: TxContext) => Promise<boolean>;
+    /**
+     * Перед операцией (runTx, ExplicitTx.open): после простоя подключение проверяет, жива ли сессия, — иначе чтение под
+     * истёкшей сессией шло бы как анонимное и молча отдавало пустой ответ. Обновляет токен ctx, если сессию выдали заново.
+     */
+    before?: (ctx: TxContext) => Promise<void>;
     /**
      * После фиксации записи: нагрузки из letopis.changed (сигналы записи, session:<тег>) — кэш
      * результатов сбрасывает свои ответы сразу (§2.12); raw — запись через db.sql.
      */
     onChanged?: (names: string[], raw: boolean) => void;
+    /** Логгер (lib/src/log.ts): повторы (tx.retry), транзакции db.begin() (tx.begin, tx.commit, tx.rollback). */
+    log?: Log;
 }
 /**
  * Операция одной транзакцией с контекстом сессии и повтором при транзиентных ошибках и конфликте
@@ -135,8 +149,11 @@ export declare class ExplicitTx implements Executor {
     private failure;
     /** В транзакции был сырой SQL (db.sql): после фиксации — весь кэш. */
     private raw;
+    /** Время открытия — для ms у tx.commit и tx.rollback. */
+    private readonly t0;
     private constructor();
-    static open(ctx: TxContext): Promise<ExplicitTx>;
+    private get log();
+    static open(ctx: TxContext, renewed?: boolean): Promise<ExplicitTx>;
     /** Транзакция ещё открыта (не зафиксирована и не откачена). */
     get active(): boolean;
     run<T>(fn: (tx: Tx) => Promise<T>, opts?: {
@@ -146,6 +163,8 @@ export declare class ExplicitTx implements Executor {
     /** Advisory-блокировка до конца транзакции (отдельное от блокировок семейств пространство ключей). */
     lock(...keys: (string | number)[]): Promise<void>;
     commit(): Promise<void>;
+    /** Событие отката (tx.rollback) и ошибка, которой он вызван. */
+    private rolledBack;
     rollback(): Promise<void>;
 }
 export {};

package/dist/tx.js

@@ -1,4 +1,5 @@
-import { LetopisError, fromDbError } from './errors.js';
+import { LetopisError, fromDbError, lerr, lmsg } from './errors.js';
+import { NOLOG } from './log.js';
 /** Транзиентные ошибки PG, которые снимает повтор: взаимная блокировка, сериализация. */
 export function isTransient(e) {
     const code = e.code;
@@ -37,12 +38,14 @@ export function release(conn, err) {
         return;
     conn.release();
 }
-const commitUnknown = (cause) => Object.assign(new LetopisError('commit_unknown', 'связь оборвалась во время commit: транзакция могла зафиксироваться — '
-    + 'проверьте исход повтором той же операции с тем же ключом'), { cause });
-/** Взаимная блокировка в явной транзакции: повторить нужно весь блок (подсказка, как hintTxRetry 0.21). */
+const commitUnknown = (cause) => lerr('write.commit_unknown', undefined, { cause });
+/**
+ * Взаимная блокировка в явной транзакции: повторить нужно весь блок (подсказка, как hintTxRetry 0.21). Хвост —
+ * запись write.tx_retry_hint; он называет db.begin(), поэтому второй раз не дописывается.
+ */
 function hintTxRetry(e) {
     if (isTransient(e) && e instanceof Error && !e.message.includes('db.begin()')) {
-        e.message += ' — откатите транзакцию и повторите весь блок db.begin()';
+        e.message += lmsg('write.tx_retry_hint');
     }
     return e;
 }
@@ -54,15 +57,17 @@ export class Notifier {
     channel;
     intervalMs;
     onError;
+    log;
     queue = new Set();
     timer = null;
     stopped = false;
     flushing = Promise.resolve();
-    constructor(sql, channel, intervalMs, onError = () => { }) {
+    constructor(sql, channel, intervalMs, onError = () => { }, log = NOLOG) {
         this.sql = sql;
         this.channel = channel;
         this.intervalMs = intervalMs;
         this.onError = onError;
+        this.log = log;
     }
     /** Добавить нагрузки из letopis.changed (строка через запятую). */
     add(changed) {
@@ -87,7 +92,10 @@ export class Notifier {
             return this.flushing;
         const payloads = [...this.queue];
         this.queue.clear();
-        this.flushing = this.flushing.then(() => this.sql `select pg_notify(${this.channel}, c) from unnest(${payloads}::text[]) as c`.then(() => undefined, (e) => {
+        this.flushing = this.flushing.then(() => this.sql `select pg_notify(${this.channel}, c) from unnest(${payloads}::text[]) as c`.then(() => {
+            if (this.log.wants('signal.send'))
+                this.log.emit('signal.send', { rows: payloads.length });
+        }, (e) => {
             // не отправлено (обрыв связи, отказ базы) — обратно в очередь: уйдёт следующим интервалом
             // (в 1.0.1 такие сигналы терялись, и кэш других процессов устаревал до срока)
             for (const c of payloads)
@@ -156,6 +164,9 @@ const passSql = (q, ctx) => q.unsafe(`select set_config('letopis.acl', coalesce(
  */
 export async function runTx(ctx, fn, opts = {}) {
     const retries = opts.retries ?? RETRIES;
+    let renewed = false;
+    if (ctx.before)
+        await ctx.before(ctx);
     for (let attempt = 1;; attempt++) {
         let bodyDone = false;
         let dead = false;
@@ -199,16 +210,31 @@ export async function runTx(ctx, fn, opts = {}) {
             if (bodyDone && !opts.read && dead)
                 throw commitUnknown(e);
             if (attempt <= retries && (isTransient(e) || isLogConflict(e))) {
+                const log = ctx.log ?? NOLOG;
+                if (log.wants('tx.retry')) {
+                    log.emit('tx.retry', { detail: { attempt, of: retries, sqlstate: e.code,
+                            ...(isLogConflict(e) ? { conflict: 'log_id_rev' } : {}) } });
+                }
                 await retryDelay(attempt);
                 continue;
             }
-            throw fromDbError(e);
+            const le = fromDbError(e);
+            // сессия кончилась по простою: подключение по ключу выдаёт новую — повтор один раз, транзакция уже откачена
+            if (!renewed && !bodyDone && ctx.renew && isNoSession(le)) {
+                renewed = true;
+                if (await ctx.renew(ctx)) {
+                    attempt--;
+                    continue;
+                }
+            }
+            throw le;
         }
         finally {
             release(conn, failure);
         }
     }
 }
+const isNoSession = (e) => e instanceof LetopisError && e.code === 'no_session';
 /** Исполнитель пула: каждая операция — своя транзакция с повторами. */
 export function poolExecutor(ctx) {
     return { explicit: false, run: (fn, opts) => runTx(ctx, fn, opts) };
@@ -228,11 +254,18 @@ export class ExplicitTx {
     failure = null;
     /** В транзакции был сырой SQL (db.sql): после фиксации — весь кэш. */
     raw = false;
+    /** Время открытия — для ms у tx.commit и tx.rollback. */
+    t0 = performance.now();
     constructor(ctx, conn) {
         this.ctx = ctx;
         this.conn = conn;
     }
-    static async open(ctx) {
+    get log() {
+        return this.ctx.log ?? NOLOG;
+    }
+    static async open(ctx, renewed = false) {
+        if (!renewed && ctx.before)
+            await ctx.before(ctx);
         const conn = await ctx.sql.reserve();
         try {
             await conn.unsafe('begin isolation level read committed');
@@ -244,8 +277,15 @@ export class ExplicitTx {
         catch (e) {
             await rollbackAfter(conn, e);
             release(conn, e);
-            throw fromDbError(e);
+            const le = fromDbError(e);
+            // сессия кончилась по простою (как у runTx): подключение по ключу выдаёт новую — открыть ещё раз
+            if (!renewed && ctx.renew && isNoSession(le) && (await ctx.renew(ctx)))
+                return ExplicitTx.open(ctx, true);
+            throw le;
         }
+        const log = ctx.log ?? NOLOG;
+        if (log.wants('tx.begin'))
+            log.emit('tx.begin', { op: 'begin', detail: { isolation: 'read committed', ...(ctx.reason ? { reason: ctx.reason } : {}) } });
         return new ExplicitTx(ctx, conn);
     }
     /** Транзакция ещё открыта (не зафиксирована и не откачена). */
@@ -254,7 +294,7 @@ export class ExplicitTx {
     }
     async run(fn, opts) {
         if (this.done)
-            throw new LetopisError('tx_required', 'транзакция db.begin() уже завершена');
+            throw lerr('write.tx_done');
         if (this.broken)
             throw this.broken;
         if (opts?.raw)
@@ -271,7 +311,7 @@ export class ExplicitTx {
     /** Advisory-блокировка до конца транзакции (отдельное от блокировок семейств пространство ключей). */
     async lock(...keys) {
         if (this.done)
-            throw new LetopisError('tx_required', 'lock(): транзакция db.begin() уже завершена');
+            throw lerr('write.lock_tx_done');
         await this.run((q) => q.unsafe('select pg_advisory_xact_lock(hashtextextended($1, 0))', [keys.join('|')]));
     }
     async commit() {
@@ -286,6 +326,7 @@ export class ExplicitTx {
                 await this.conn.unsafe('rollback').catch(() => { });
             release(this.conn, this.broken);
             this.failure = this.broken;
+            this.rolledBack('error', this.broken);
             throw this.broken;
         }
         let changed = null;
@@ -303,25 +344,47 @@ export class ExplicitTx {
             }));
             changed = rows[0]?.changed ?? null;
             if (res.command === 'ROLLBACK') {
-                this.failure = new LetopisError('tx_rolled_back', 'commit: PostgreSQL откатил транзакцию (в ней была ошибка)');
+                this.failure = lerr('write.tx_rolled_back');
                 throw this.failure;
             }
         }
         catch (e) {
             this.failure ??= isConnectionError(e) ? commitUnknown(e) : fromDbError(e);
             release(this.conn, e);
+            this.rolledBack('error', this.failure);
             throw this.failure;
         }
         this.conn.release();
+        // транзакция с записью (write, delete, restore, db.sql, права, креды) — tx.commit уровня info: это и есть
+        // доказательство фиксации её событий записи (у них то же поле tx); без записи — debug, как прежде
+        const writes = this.log.writes ?? 0;
+        const level = writes > 0 ? 'info' : 'debug';
+        if (this.log.level(level)) {
+            this.log.emit('tx.commit', { op: 'commit', level, ms: performance.now() - this.t0,
+                detail: { writes, ...(changed ? { signals: changed.split(',').filter(Boolean).length } : {}) } });
+        }
         this.ctx.notifier?.add(changed);
         if (changed)
             this.ctx.onChanged?.(changedList(changed), this.raw);
         this.ctx.after?.();
     }
+    /** Событие отката (tx.rollback) и ошибка, которой он вызван. */
+    rolledBack(reason, err) {
+        const log = this.log;
+        if (!log.enabled)
+            return;
+        if (err !== undefined)
+            log.error(err, { op: 'commit', ms: performance.now() - this.t0 });
+        if (log.wants('tx.rollback')) {
+            log.emit('tx.rollback', { op: reason === 'error' ? 'commit' : 'rollback', ms: performance.now() - this.t0,
+                detail: { reason, writes: log.writes ?? 0, ...(this.broken ? { broken: true } : {}) } });
+        }
+    }
     async rollback() {
         if (this.done)
             return;
         this.done = true;
+        this.rolledBack('explicit');
         try {
             // соединение, оборванное ошибкой, не трогаем: postgres.js уронил бы процесс записью в закрытый сокет
             if (!isConnectionError(this.broken))