letopis 1.1.0 → 1.3.0

package/dist/model.d.ts

@@ -85,7 +85,33 @@ export interface ClassDef<S extends z.ZodRawShape = z.ZodRawShape, E extends End
         ttl?: number;
     };
     meta?: ClassMeta;
+    /** Производный класс (план 1.1, §2.4): строки пишет только проектор с этим именем; наследуется. */
+    derivedBy?: string;
+    /**
+     * Агрегаты в базе (план 1.1, §2.4): поле — сумма поля (`sum`) или число (`count: true`) живых строк класса `of` того
+     * же арендатора, чей одиночный конец `via` ведёт на строку; `where` — JSON Schema над данными строки-источника.
+     * Поле считает база, приложение его не пишет. Наследуется, потомок заменяет целиком.
+     */
+    aggregate?: Record<string, AggregateDef>;
 }
+/** Описание одного агрегатного поля: `sum` или `count: true`; `of` — класс-источник (имя или модель). */
+export type AggregateDef = {
+    sum: string;
+    count?: never;
+    of: string | {
+        readonly name: string;
+    };
+    via: string;
+    where?: JsonSchema;
+} | {
+    count: true;
+    sum?: never;
+    of: string | {
+        readonly name: string;
+    };
+    via: string;
+    where?: JsonSchema;
+};
 /** Описание класса в строке `Class` (метасхема `class_metaschema()` в lib/sql/40-class.sql). */
 export interface ClassDescription {
     name: string;
@@ -113,6 +139,14 @@ export interface ClassDescription {
         ttl?: number;
     };
     meta?: ClassMeta;
+    derivedBy?: string;
+    aggregate?: Record<string, {
+        sum?: string;
+        count?: true;
+        of: string;
+        via: string;
+        where?: JsonSchema;
+    }>;
 }
 /** Правило refine, которое не попадёт в базу: проверяется только в библиотеке. */
 export interface LostRule {

package/dist/model.js

@@ -145,6 +145,13 @@ function makeModel(kind, name, defArg, optsArg) {
             throw new LetopisError('invalid_class', `${name}: onDelete unset недопустим для обязательного конца ${role}`);
         }
     }
+    // агрегаты (план 1.1, §2.4): остальное — роль, поле суммы, цикл — сверяет база по описаниям источников
+    for (const [field, a] of Object.entries(def.aggregate ?? {})) {
+        if (!(field in shape))
+            throw new LetopisError('invalid_class', `${name}: агрегатного поля ${field} нет среди полей класса`);
+        if ((a.sum === undefined) === (a.count === undefined))
+            throw new LetopisError('invalid_class', `${name}: агрегат ${field} — ровно одно из sum и count: true`);
+    }
     // строгий верхний уровень — как в базе (resolved.schema: additionalProperties false)
     const schema = z.strictObject(shape);
     const model = {
@@ -204,6 +211,16 @@ function makeModel(kind, name, defArg, optsArg) {
                 desc.cache = def.cache;
             if (def.meta)
                 desc.meta = def.meta;
+            if (def.derivedBy)
+                desc.derivedBy = def.derivedBy;
+            if (def.aggregate) {
+                desc.aggregate = Object.fromEntries(Object.entries(def.aggregate).map(([field, a]) => [field, {
+                        ...(a.sum !== undefined ? { sum: a.sum } : { count: true }),
+                        of: typeof a.of === 'string' ? a.of : a.of.name,
+                        via: a.via,
+                        ...(a.where ? { where: a.where } : {}),
+                    }]));
+            }
             return desc;
         },
         lostRules() {

package/dist/project.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Проекторы из журнала (план 1.1, §2.4, этап 4а): db.projector(имя, { from, into, version, handle }).
+ *
+ * Проектор — процесс администратора, как загрузчик: подключение connect({ allowBypassRls: true }) роли,
+ * которая может стать владельцем схемы. Каждая пачка — одна транзакция под ролью владельца:
+ * строка-замок «схема:projector:имя» (lock_try, до конца транзакции) — писатель один; чекпоинт (строка secret вида
+ * PROJECTOR) — for update; события журнала ниже горизонта (watch_read: пачка и горизонт — одним
+ * оператором); handle; запись результатов (derived_apply); условный сдвиг чекпоинта (projector_advance).
+ * Обрыв посреди пачки откатывает всё, повтор начинает с того же курсора: каждое изменение применено
+ * ровно один раз.
+ *
+ * Арендаторы изолированы (ревью безопасности №2): handle и запись результатов идут группами по арендатору, каждая
+ * под своей точкой сохранения. Ошибку базы при записи результатов арендатора (его описания классов, его данные)
+ * откатывает только его группа: арендатор выбывает (meta.failed чекпоинта) до rebuild({ tenant }), а остальные
+ * идут дальше в той же транзакции. Исключение handle и нарушение границ out — ошибка проектора: пачка
+ * откатывается целиком.
+ *
+ * Перестройка идёт с текущего состояния: журнал прорежен политикой хранения и обрезан purge. Строки
+ * источников читаются одним снимком S (курсор SQL держит снимок своего объявления), чекпоинт встаёт на
+ * (xmin(S), 0, S), а хвост журнала исключает транзакции, видимые в S. Перестройка пачками: у каждой
+ * пачки свой снимок Sᵢ, и событие хвоста пропускается, если его транзакция видна в снимке пачки, в
+ * которую попал id. Перестройка одного арендатора — свой снимок в meta.resync: хвост пропускает изменения
+ * этого арендатора, чья транзакция в нём видна.
+ */
+import type postgres from 'postgres';
+import { type Row } from './types.js';
+import type { Signal } from './signals.js';
+type Sql = postgres.Sql<Record<string, unknown>>;
+/** Изменение для handle: версия журнала (как событие подписки) и, по withBefore, прошлая версия. */
+export interface ProjectorChange {
+    /** Курсор события в журнале (при перестройке — пустая строка). */
+    cursor: string;
+    id: string;
+    class: string;
+    tenant: string;
+    /** create, update, delete, restore, reclass, rekey, …; служебные — purge, trim, reset (их rev — 1). */
+    op: string;
+    rev: number;
+    at: string;
+    author: string;
+    agent?: string;
+    reason?: string;
+    moved?: string;
+    /** Версия из журнала (надгробие — $deleted); при перестройке — текущая строка. */
+    row: Row;
+    /**
+     * withBefore: прошлая версия того же id; null — её нет. У первой версии нового id после reclass и rekey — null:
+     * прежние данные вычитает надгробие прежнего id (его before — последняя версия прежнего id). Строка вошла в семейство
+     * from сменой класса без смены id — тоже null: прошлая версия была вне семейства.
+     */
+    before?: Row | null;
+    /** Строка текущего состояния при перестройке (op — create). */
+    rebuild?: true;
+}
+/** Строка результата в формате загрузчика: поля и роли концов на верхнем уровне, служебные $tags, $owner, $id. */
+export type ProjectorRow = Record<string, unknown>;
+/** Запись результатов: handle получает изменения одного арендатора, out пишет только классы into этого арендатора. */
+export interface ProjectorOut {
+    /** Создать или заменить целиком по ключу класса (у класса без ключа — по $id). */
+    upsert(cls: string, row: ProjectorRow, opts: {
+        tenant: string;
+    }): void;
+    /**
+     * Создать (поля без строки — от 0) или дополнить строку и прибавить числа: коммутативная свёртка без чтения.
+     * Приращения строки, заданной одними полями ключа (или одним $id), складываются до отправки в базу, пока между ними
+     * нет upsert, delete или get: одна правка строки на пачку.
+     */
+    inc(cls: string, row: ProjectorRow, deltas: Record<string, number>, opts: {
+        tenant: string;
+    }): void;
+    /** Удалить по ключу или id; строки нет — ничего. */
+    delete(cls: string, keyOrId: string | ProjectorRow, opts: {
+        tenant: string;
+    }): void;
+    /** Текущая строка внутри пачки (с записями пачки, сделанными до вызова); нет — null. */
+    get(cls: string, keyOrId: string | ProjectorRow, opts: {
+        tenant: string;
+    }): Promise<Row | null>;
+}
+export interface ProjectorOptions {
+    /** Классы-источники (с потомками); должны вести журнал. */
+    from: string[];
+    /** Производные классы (с потомками): описание каждого — derivedBy: имя проектора. */
+    into: string[];
+    /** Версия проектора: другая версия в чекпоинте — rebuild_required, нужна перестройка. */
+    version: number;
+    /** Изменения одного арендатора (пачка делится по арендаторам) и запись его результатов. */
+    handle(changes: ProjectorChange[], out: ProjectorOut): void | Promise<void>;
+    /** Подавать прошлую версию объекта (before). */
+    withBefore?: boolean;
+    /**
+     * Курсор старше яруса all политики хранения источников (cursor_expired): 'rebuild' — перестроить самому, пачками.
+     * Ярус — по арендатору: истёк у части участников — выбывают они (с 'rebuild' — перестраиваются сами, каждый своей
+     * транзакцией), у всех — вся проекция.
+     */
+    onExpired?: 'rebuild' | 'error';
+    /** Изменений в пачке (по умолчанию 500). */
+    batch?: number;
+    /** Запасной опрос журнала, мс (по умолчанию 1000; сигналы источников будят раньше). */
+    pollMs?: number;
+    /**
+     * Сколько транзакция проектора ждёт чужую блокировку строки, мс (по умолчанию 5000; 0 — без предела). Дольше —
+     * пачка откатывается, курсор остаётся, run() не отклоняется, а пропускает проход и повторяет его.
+     */
+    lockTimeout?: number;
+    /**
+     * Явный список арендаторов проектора: участники — только они (и только те, у кого каждый класс into помечен
+     * derivedBy). Без списка участник — любой арендатор с такими классами.
+     */
+    tenants?: string[];
+}
+export interface ProjectorReport {
+    /** Пачек журнала, записанных проектором. */
+    batches: number;
+    /** Изменений, переданных в handle (при перестройке — строк источников). */
+    changes: number;
+    created: number;
+    updated: number;
+    deleted: number;
+    unchanged: number;
+    /** Пачек, пропущенных из-за блокировки: проектор работает в другом процессе. */
+    skipped: number;
+    /** Перестроек. */
+    rebuilds: number;
+}
+/** Выбывший арендатор: база отклонила запись его результатов. */
+export interface ProjectorFailure {
+    /** Курсор первого неприменённого изменения арендатора (ошибка при перестройке — курсор её начала). */
+    cursor: string;
+    /**
+     * Код ошибки letopis (invalid_data, target_not_found, …) или SQLSTATE; cursor_expired — истёк ярус all источников
+     * арендатора, invalid_class — его источники не ведут журнал (history: false).
+     */
+    code: string;
+    /** Текст ошибки: проектор, арендатор и id строки. */
+    message: string;
+}
+export interface ProjectorStatus {
+    name: string;
+    /** new — проекции ещё нет; rebuilding — идёт (или прервана) перестройка пачками. */
+    state: 'new' | 'running' | 'rebuilding';
+    version: number | null;
+    cursor: string | null;
+    /** Время последнего прохода (события или пустой пачки). */
+    at: string | null;
+    /** Отставание, мс: возраст самого старого необработанного изменения источников; 0 — догнал. */
+    lag: number;
+    /** Выбывшие арендаторы (id → ошибка): их изменения пропускаются до rebuild({ tenant }) или полной перестройки. */
+    failed: Record<string, ProjectorFailure>;
+    /** Арендаторы, которых перестраивают пачками по одному (rebuild({ tenant, chunked: true }), onExpired: 'rebuild'). */
+    rebuildingTenants: string[];
+}
+export interface ProjectorEnv {
+    sql: Sql;
+    schema: string;
+    /** Схема в кавычках. */
+    S: string;
+    ownerRole: string;
+    /** Подписка на сигналы базы (нет LISTEN — только опрос). */
+    onSignal?: (fn: (s: Signal) => void) => () => void;
+}
+export declare class Projector {
+    readonly env: ProjectorEnv;
+    private def;
+    readonly name: string;
+    /** Области арендаторов проектора: свои семейства from и into. */
+    private scopes;
+    private from;
+    /** Арендаторы проектора: каждый класс into у них помечен его derivedBy (и, с опцией tenants, они в списке). */
+    private tenants;
+    /** Самый короткий ярус all политик хранения источников арендатора, мс (нет в карте — предела нет). */
+    private lim;
+    /** Источники арендатора без журнала (history: false): их изменений проектор не увидит — арендатор выбывает. */
+    private blind;
+    private stale;
+    /** В чекпоинте есть начатая перестройка арендатора пачками (по последней пачке; до первой — проверить). */
+    private tenantsPending;
+    private running;
+    private stopped;
+    private wake;
+    private off;
+    private readonly batch;
+    private readonly pollMs;
+    private readonly lockMs;
+    private readonly only;
+    constructor(env: ProjectorEnv, name: string, def: ProjectorOptions);
+    /**
+     * Догнать журнал и следовать за ним до stop(); { once: true } — только догнать. Первый запуск (проекции
+     * ещё нет) начинается с перестройки пачками, прерванная перестройка пачками продолжается; так же, пачками,
+     * перестраивает onExpired: 'rebuild' (решение точки Б: горизонт подписок кластера стоит не дольше пачки).
+     */
+    run(opts?: {
+        once?: boolean;
+    }): Promise<ProjectorReport>;
+    /**
+     * Перестроить проекцию с текущего состояния: атомарно (одна транзакция: до фиксации читатели видят
+     * прежние строки, но горизонт подписок стоит) или { chunked: true } — пачками: производные строки
+     * удаляются сразу, до конца перестройки данные неполные (status() — rebuilding); прерванную перестройку
+     * продолжает следующий запуск. Полная перестройка начинает всех участников заново: отметки выбывших снимаются,
+     * а чьи данные снова не проходят — выбывают снова. { tenant: id } — только этот арендатор, одной транзакцией:
+     * его производные строки удаляются и строятся из его текущих строк источников, отметка выбывшего снимается.
+     * { tenant, chunked: true } — этот арендатор пачками, пока хвост журнала идёт для всех (доработки после точки Б):
+     * его производные строки удаляются сразу и до конца перестройки неполны; блокировку, занятую run() другого процесса,
+     * перестройка пережидает.
+     */
+    rebuild(opts?: {
+        chunked?: boolean;
+        tenant?: string;
+    }): Promise<ProjectorReport>;
+    status(): Promise<ProjectorStatus>;
+    /** Остановить run() после текущей пачки. */
+    stop(): void;
+    /** stop() и отписка от сигналов. */
+    close(): void;
+    /** Транзакция под ролью владельца на отдельном соединении пула. */
+    private tx;
+    private lock;
+    private state;
+    private advance;
+    private now;
+    /** Отметка выбывшего: источники арендатора не ведут журнал. */
+    private blindFailure;
+    private blindError;
+    private versionError;
+    /**
+     * Арендаторы и классы по строкам Class всех арендаторов (реестр администраторского подключения без сессии
+     * видит только System). Проектор работает с арендаторами, у которых каждый класс into помечен его
+     * derivedBy (с опцией tenants — только из списка); изменения остальных арендаторов пропускаются — иначе
+     * любой арендатор, заведя одноимённый класс без пометки, остановил бы проектор для всех. Источники — семейства
+     * from у этих арендаторов, кроме собственных результатов.
+     */
+    private resolve;
+    /** Одна пачка журнала. */
+    private step;
+    /** Прошлые версии одним запросом: последняя версия того же id с меньшим номером, кроме служебных записей. */
+    private previous;
+    /**
+     * Прошлые версии (id, rev − 1 и раньше) — всегда того же id. У первой версии нового id после reclass и rekey прошлой
+     * версии нет (null): прежние данные вычитает надгробие прежнего id. Прежде её before была последняя версия прежнего
+     * id, и свёртка вычитала её дважды — через неё и через надгробие. Прошлая версия вне семейства from арендатора —
+     * тоже null: строка вошла в семейство сменой класса без смены id, и в проекции её не было (ревью безопасности №3, №4).
+     */
+    private fillBefore;
+    /**
+     * Смена класса без смены id (класс без ключа: сырой update set class, reclass()), уводящая строку из семейства from:
+     * журнал пишет версию уже другого класса, а для проекции это удаление (ревью безопасности №3, №4). Изменение — op
+     * delete с $deleted, строка — последняя версия в семействе, номер, время и автор — смены класса. Прошлая версия вне
+     * семейства арендатора — изменения нет.
+     */
+    private leaving;
+    /**
+     * handle и запись результатов в транзакции пачки — группами по арендатору (ревью безопасности №2). failed —
+     * отметки выбывших этой пачки: каждая группа идёт под точкой сохранения, и ошибка данных арендатора (tenantFault:
+     * отказ базы при записи или чтении его результатов, отказ out по строке или приращениям) откатывает только группу,
+     * а арендатор попадает в failed (курсор — первого изменения группы, у перестройки — start). Исключение handle,
+     * нарушение границ out и сбой окружения пачку не спасают: откатывается всё. failed null (rebuild({ tenant })) — без
+     * точек сохранения: любая ошибка откатывает перестройку.
+     */
+    private apply;
+    /**
+     * Перестройка. 'auto' — путь run() (проекции ещё нет, onExpired: 'rebuild'): пачками, а прерванная перестройка
+     * пачками продолжается с места обрыва; блокировку держит другой процесс — 'busy' (run() подождёт), а не
+     * projector_busy, как у rebuild(). Иначе — как просили в rebuild().
+     */
+    private rebuildNow;
+    /** Строка текущего состояния как изменение перестройки; прошлой версии у неё нет. */
+    private rebuildChange;
+    /** Изменение — из семейства from своего арендатора (сброс арендатора — тоже); выбывший арендатор пропускается. */
+    private ours;
+    /** Смена класса без смены id, после которой строка вне семейства from арендатора, — возможно, уход из него (leaving). */
+    private leaves;
+    /** Класс результата в арендаторе — из его семейства into. */
+    intoOf(tenant: string, cls: string): boolean;
+    /**
+     * Ключ свёртки inc: класс и строка из одних полей ключа класса или одного $id; иначе null. Строку с другими полями
+     * (данные, $tags, $owner) inc не складывает: её поля правят строку, и порядок таких правок важен.
+     */
+    foldKey(tenant: string, cls: string, row: ProjectorRow): string | null;
+    private busy;
+    /** Производные строки арендаторов tenants — только семейства into каждого из них (derived_clear по парам). */
+    private clear;
+    /** Атомарная перестройка: одна транзакция, источники — курсором одним снимком. */
+    private atomic;
+    /**
+     * Перестройка пачками: своя транзакция и свой снимок у каждой пачки источников. auto — путь run(): занятую другим
+     * процессом блокировку он пережидает ('busy'), а новую перестройку не начинает, если её уже начал или закончил
+     * другой процесс (курсор чекпоинта — не тот, что видел run()): тогда только продолжает начатую.
+     */
+    private chunked;
+    /**
+     * Перестройка одного арендатора (rebuild({ tenant })): одной транзакцией его производные строки удаляются и
+     * строятся заново из его текущих строк источников, отметка выбывшего снимается. Снимок перестройки встаёт в
+     * чекпоинт (meta.resync): изменения арендатора, чья транзакция в нём видна, хвост журнала пропускает — каждое
+     * изменение применено ровно один раз. Ошибка записи откатывает перестройку: арендатор остаётся выбывшим.
+     */
+    private rebuildTenant;
+    /** Предусловия перестройки одного арендатора (как у rebuild({ tenant })). */
+    private tenantAdmit;
+    /**
+     * Начало перестройки арендатора пачками: его производные строки удаляются, отметка выбывшего снимается, в чекпоинт
+     * встают пустая карта пачек и время начала. auto — путь run(): занятая блокировка — 'busy', а не projector_busy.
+     */
+    private startTenant;
+    /**
+     * Пачка перестройки арендатора: своя транзакция и свой снимок. Ошибка данных арендатора — он выбывает с её кодом,
+     * его частично построенные строки удаляются, перестройка снимается; источников больше нет — перестройка закончена.
+     */
+    private tenantChunk;
+    /**
+     * Перестройка арендаторов пачками — проход run(): с start (onExpired: 'rebuild') начинает её у каждого выбывшего по
+     * cursor_expired, затем продвигает на пачку каждую начатую — автоматическую и прерванную rebuild({ tenant, chunked:
+     * true }). true — работа ещё осталась.
+     */
+    private tenantWork;
+    /** Ждать сигнал источников, остановку или запасной опрос. */
+    private sleep;
+}
+export {};