@toa.io/extensions.chronicles 0.0.0-stage → 1.0.0-alpha.333

package/store/clickhouse.scope.sql

@@ -0,0 +1,29 @@
+-- A context's user of the store: it reads the rows of its scope and nothing else, and keeps its
+-- views in a database of its own. {scope} is the context's scope, {password} the `store_password`
+-- of its `chronicles` secret.
+
+CREATE DATABASE IF NOT EXISTS `{scope}`;
+
+-- limits a query cannot lift, because they are its profile's, not settings a request passes
+CREATE SETTINGS PROFILE IF NOT EXISTS `{scope}` SETTINGS
+  max_execution_time = 30 CONST,
+  max_result_rows = 10001 CONST,
+  max_result_bytes = 67108864 CONST,
+  max_memory_usage = 4000000000 CONST,
+  max_concurrent_queries_for_user = 4 CONST;
+
+CREATE USER IF NOT EXISTS `{scope}` IDENTIFIED WITH sha256_password BY '{password}'
+  DEFAULT DATABASE chronicles SETTINGS PROFILE '{scope}';
+
+GRANT SELECT ON chronicles.events TO `{scope}`;
+GRANT SELECT ON chronicles.states TO `{scope}`;
+GRANT SELECT ON chronicles.encounters TO `{scope}`;
+GRANT SELECT, CREATE VIEW, CREATE TABLE, INSERT, DROP VIEW, DROP TABLE ON `{scope}`.* TO `{scope}`;
+
+-- when its materialized views were last refreshed
+GRANT SELECT ON system.view_refreshes TO `{scope}`;
+
+-- replaced rather than kept: a policy outlives its user, and one left to a user made again would
+-- apply to no one, which reads as no restriction at all
+CREATE ROW POLICY OR REPLACE `{scope}` ON chronicles.events, chronicles.states, chronicles.encounters
+  USING scope = '{scope}' TO `{scope}`;

package/store/clickhouse.sql

@@ -0,0 +1,99 @@
+-- The store of every context that publishes to one analytics broker: what Toa publishes, and what
+-- it reads. Toa runs none of this; whoever sets the store up does, once, and again where a release
+-- of Toa says so. {broker}, {broker_username} and {broker_password} are the broker ClickHouse
+-- consumes, as ClickHouse reaches it.
+
+CREATE DATABASE IF NOT EXISTS chronicles;
+
+-- a row for everything a component did, by `id`, kept until `expires`
+CREATE TABLE IF NOT EXISTS chronicles.events (
+  scope LowCardinality(String),
+  id String,
+  label LowCardinality(String),
+  component LowCardinality(String),
+  time DateTime64(3, 'UTC'),
+  entity Nullable(String),
+  version Nullable(UInt64),
+  identity Nullable(String),
+  trace Nullable(String),
+  payload JSON,
+  expires DateTime DEFAULT '2106-01-01 00:00:00'
+) ENGINE = ReplacingMergeTree
+PARTITION BY toYYYYMM(time)
+ORDER BY (scope, label, toDate(time), id)
+TTL expires;
+
+-- each entity as it stands, by the latest `version`
+CREATE TABLE IF NOT EXISTS chronicles.states (
+  scope LowCardinality(String),
+  component LowCardinality(String),
+  entity String,
+  version UInt64,
+  identity Nullable(String),
+  time DateTime64(3, 'UTC'),
+  payload JSON
+) ENGINE = ReplacingMergeTree(version)
+ORDER BY (scope, component, entity);
+
+-- what clients sent, by `id`, kept and expired by when the gateway received it
+CREATE TABLE IF NOT EXISTS chronicles.encounters (
+  scope LowCardinality(String),
+  id String,
+  name LowCardinality(String),
+  time DateTime64(3, 'UTC'),
+  received DateTime64(3, 'UTC'),
+  visitor Nullable(String),
+  session Nullable(String),
+  identity Nullable(String),
+  ip Nullable(String),
+  country LowCardinality(Nullable(String)),
+  origin LowCardinality(Nullable(String)),
+  agent Nullable(String),
+  browser LowCardinality(Nullable(String)),
+  os LowCardinality(Nullable(String)),
+  device LowCardinality(Nullable(String)),
+  payload JSON,
+  expires DateTime DEFAULT '2106-01-01 00:00:00'
+) ENGINE = ReplacingMergeTree
+PARTITION BY toYYYYMM(received)
+ORDER BY (scope, name, toDate(time), id)
+TTL expires;
+
+-- what the broker delivers: one JSON row a message, from the exchange `chronicles` under the key
+-- of its table, moved into the table by the view beside it
+CREATE TABLE IF NOT EXISTS chronicles.events_queue AS chronicles.events
+ENGINE = RabbitMQ SETTINGS
+  rabbitmq_host_port = '{broker}', rabbitmq_username = '{broker_username}',
+  rabbitmq_password = '{broker_password}', rabbitmq_exchange_name = 'chronicles',
+  rabbitmq_exchange_type = 'direct', rabbitmq_routing_key_list = 'events',
+  rabbitmq_queue_base = 'chronicles.events', rabbitmq_format = 'JSONEachRow',
+  rabbitmq_flush_interval_ms = 1000;
+
+-- a message without `expires` reads it as zero rather than as the default, which would expire it
+CREATE MATERIALIZED VIEW IF NOT EXISTS chronicles.events_consumer TO chronicles.events
+AS SELECT * REPLACE (if(toUnixTimestamp(expires) = 0, toDateTime('2106-01-01 00:00:00'), expires) AS expires)
+FROM chronicles.events_queue;
+
+CREATE TABLE IF NOT EXISTS chronicles.states_queue AS chronicles.states
+ENGINE = RabbitMQ SETTINGS
+  rabbitmq_host_port = '{broker}', rabbitmq_username = '{broker_username}',
+  rabbitmq_password = '{broker_password}', rabbitmq_exchange_name = 'chronicles',
+  rabbitmq_exchange_type = 'direct', rabbitmq_routing_key_list = 'states',
+  rabbitmq_queue_base = 'chronicles.states', rabbitmq_format = 'JSONEachRow',
+  rabbitmq_flush_interval_ms = 1000;
+
+CREATE MATERIALIZED VIEW IF NOT EXISTS chronicles.states_consumer TO chronicles.states
+AS SELECT * FROM chronicles.states_queue;
+
+CREATE TABLE IF NOT EXISTS chronicles.encounters_queue AS chronicles.encounters
+ENGINE = RabbitMQ SETTINGS
+  rabbitmq_host_port = '{broker}', rabbitmq_username = '{broker_username}',
+  rabbitmq_password = '{broker_password}', rabbitmq_exchange_name = 'chronicles',
+  rabbitmq_exchange_type = 'direct', rabbitmq_routing_key_list = 'encounters',
+  rabbitmq_queue_base = 'chronicles.encounters', rabbitmq_format = 'JSONEachRow',
+  rabbitmq_flush_interval_ms = 1000;
+
+-- a message without `expires` reads it as zero rather than as the default, which would expire it
+CREATE MATERIALIZED VIEW IF NOT EXISTS chronicles.encounters_consumer TO chronicles.encounters
+AS SELECT * REPLACE (if(toUnixTimestamp(expires) = 0, toDateTime('2106-01-01 00:00:00'), expires) AS expires)
+FROM chronicles.encounters_queue;

package/transpiled/Client.d.ts

@@ -0,0 +1,32 @@
+import { Connector } from '@toa.io/core';
+import type { extensions } from '@toa.io/core/types';
+import type { Address } from '@toa.io/definitions/extensions.chronicles';
+/**
+ * What `chronicles.encounters` takes what clients send through: each event a row of `encounters`,
+ * with the client's own id and the visitor and the session the batch names, all of a batch one
+ * task to the relay, and answered once the context's broker has it — the relay publishes it, then
+ * or once the broker of the log is back.
+ *
+ * A client's clock is its own, and may be off by anything; what it measures between two of its
+ * moments is not. So an event is when the gateway received the batch, less how long before
+ * sending it the client says it happened: the time of the gateway, at the distance the client
+ * measured.
+ */
+export declare class Client extends Connector {
+    readonly name = "chronicles";
+    private readonly host;
+    private readonly address;
+    private relay?;
+    constructor(host: extensions.Host, address: () => Address);
+    invoke(method: string, ...args: any[]): Promise<unknown>;
+    /**
+     * `identity` is the one the gateway verified the caller to be, from the path; `null` for the
+     * route anyone may call, whose body is then refused where it says whose it is.
+     */
+    private write;
+    /**
+     * Found on the first batch and not before: an aspect is made ahead of the components of its
+     * composition, and one that could not be found is looked for again by the next batch.
+     */
+    private relayed;
+}

package/transpiled/Client.js

@@ -0,0 +1,173 @@
+import { Connector, Locator, exceptions } from '@toa.io/core';
+import { NAMESPACE, RELAY } from '@toa.io/definitions/extensions.chronicles';
+import { keep } from './address.js';
+import { classify } from './agent.js';
+/**
+ * What `chronicles.encounters` takes what clients send through: each event a row of `encounters`,
+ * with the client's own id and the visitor and the session the batch names, all of a batch one
+ * task to the relay, and answered once the context's broker has it — the relay publishes it, then
+ * or once the broker of the log is back.
+ *
+ * A client's clock is its own, and may be off by anything; what it measures between two of its
+ * moments is not. So an event is when the gateway received the batch, less how long before
+ * sending it the client says it happened: the time of the gateway, at the distance the client
+ * measured.
+ */
+export class Client extends Connector {
+    name = 'chronicles';
+    host;
+    address;
+    relay;
+    constructor(host, address) {
+        super();
+        this.host = host;
+        this.address = address;
+    }
+    async invoke(method, ...args) {
+        if (method !== 'write')
+            throw new exceptions.MisuseException(`Chronicles have no '${method}'`);
+        return await this.write(args[0], args[1] ?? null);
+    }
+    /**
+     * `identity` is the one the gateway verified the caller to be, from the path; `null` for the
+     * route anyone may call, whose body is then refused where it says whose it is.
+     */
+    async write(input, identity) {
+        const received = Date.now();
+        const batch = parse(input, identity !== null);
+        if (batch instanceof Error)
+            return batch;
+        // put in by the gateway, which overwrites whatever the body says of them
+        const { ip, country, origin, agent } = input;
+        const address = keep(ip, this.address());
+        const from = typeof country === 'string' ? country : null;
+        const page = typeof origin === 'string' ? origin : null;
+        const client = typeof agent === 'string' ? agent : null;
+        const { browser, os, device } = classify(client);
+        const encounters = batch.events.map((event) => ({
+            id: event.id,
+            name: event.name,
+            time: received - (batch.sent - event.time),
+            received,
+            visitor: batch.visitor,
+            session: batch.session,
+            identity,
+            ip: address,
+            country: from,
+            origin: page,
+            agent: client,
+            browser,
+            os,
+            device,
+            payload: event.payload ?? {}
+        }));
+        const relay = await this.relayed();
+        await relay.invoke('encounter', { input: { encounters }, task: true });
+        return { status: 202, accepted: encounters.length };
+    }
+    /**
+     * Found on the first batch and not before: an aspect is made ahead of the components of its
+     * composition, and one that could not be found is looked for again by the next batch.
+     */
+    async relayed() {
+        this.relay ??= (async () => {
+            const remote = await this.host.remote(LOCATOR, SOURCE);
+            this.depends(remote);
+            await remote.connect();
+            return remote;
+        })().catch((error) => {
+            this.relay = undefined;
+            throw error;
+        });
+        return await this.relay;
+    }
+}
+/**
+ * A batch, `{ sent, visitor?, session?, events }`: as JSON, or as the form `navigator.sendBeacon`
+ * sends, whose `events` is the JSON of them, and `sent` the digits of a number. Checked here rather than by the operation's schema, which
+ * cannot read the form's. `identified` is whether the gateway put the identity in, which is then a
+ * key the body may have beside `events`.
+ */
+function parse(input, identified) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input))
+        return invalid('The body is `{ sent, visitor?, session?, events }`');
+    // `ip`, `country`, `origin` and `agent` are the gateway's, which sets them on every request it
+    // makes
+    const { events: given, sent: stated, visitor, session, identity, ip: _ip, country: _country, origin: _origin, agent: _agent, ...rest } = input;
+    const extra = Object.keys(rest);
+    if (extra.length > 0)
+        return invalid(`The body has no '${extra[0]}'`);
+    // the identity is the path's, never the body's
+    if (!identified && identity !== undefined)
+        return invalid('The body names no identity: a client that has one sends it in the path');
+    // `null` is a client that has none, as absent is
+    for (const [key, value] of [
+        ['visitor', visitor],
+        ['session', session]
+    ])
+        if (value !== undefined &&
+            value !== null &&
+            (typeof value !== 'string' || value === '' || value.length > 64))
+            return invalid(`\`${key}\` is a string of 1 to 64 characters`);
+    // a form's every value is a string
+    const sent = typeof stated === 'string' && /^\d{1,15}$/.test(stated) ? Number(stated) : stated;
+    if (!Number.isInteger(sent) || sent < 0)
+        return invalid('`sent` is when the client sent the batch, in milliseconds by its clock');
+    let events = given;
+    if (typeof events === 'string')
+        try {
+            events = JSON.parse(events);
+        }
+        catch {
+            return invalid('`events` is not JSON');
+        }
+    if (!Array.isArray(events))
+        return invalid('`events` is an array of events');
+    if (events.length > MAX_EVENTS)
+        return invalid(`A request carries at most ${MAX_EVENTS} events`);
+    for (const [index, event] of events.entries()) {
+        const problem = check(event);
+        if (problem !== null)
+            return invalid(problem, index);
+        if (event.time > sent)
+            return invalid('An event happens before the batch that carries it is sent', index);
+        if (JSON.stringify(event.payload ?? {}).length > MAX_PAYLOAD)
+            return new Error('OVERSIZED', {
+                cause: { index, message: `A payload is at most ${MAX_PAYLOAD} bytes of JSON` }
+            });
+    }
+    return {
+        sent: sent,
+        visitor: visitor ?? null,
+        session: session ?? null,
+        events: events
+    };
+}
+function check(event) {
+    if (typeof event !== 'object' || event === null || Array.isArray(event))
+        return 'An event is an object';
+    const { id, name, time, payload, ...rest } = event;
+    if (Object.keys(rest).length > 0)
+        return `An event has no '${Object.keys(rest)[0]}'`;
+    if (typeof id !== 'string' || id.length === 0 || id.length > 64)
+        return '`id` is a string of 1 to 64 characters';
+    if (typeof name !== 'string' || name.length > 64 || !NAME.test(name))
+        return '`name` is lowercase letters, digits and underscores from a letter, at most 64 characters';
+    if (!Number.isInteger(time) || time < 0)
+        return "`time` is when it happened, in milliseconds by the client's clock";
+    if (payload !== undefined &&
+        (typeof payload !== 'object' || payload === null || Array.isArray(payload)))
+        return '`payload` is an object';
+    return null;
+}
+function invalid(message, index) {
+    return new Error('INVALID', {
+        cause: index === undefined ? { message } : { index, message }
+    });
+}
+const MAX_EVENTS = 100;
+const MAX_PAYLOAD = 16 * 1024;
+const NAME = /^[a-z][a-z0-9_]*$/;
+const LOCATOR = new Locator(RELAY, NAMESPACE);
+const SOURCE = { service: 'chronicles' };
+//# sourceMappingURL=Client.js.map

package/transpiled/Client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Client.js","sourceRoot":"","sources":["../source/Client.ts"],"names":[],"mappings":"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"}

package/transpiled/Factory.d.ts

@@ -0,0 +1,24 @@
+import type { Connector, Locator } from '@toa.io/core';
+import type { extensions } from '@toa.io/core/types';
+import type { Declaration } from '@toa.io/definitions/extensions.chronicles';
+/**
+ * A component sends facts through its context; the events it declares reach the log as events of
+ * the context, which the service consumes. The components this extension ships are given what
+ * they serve instead: the queries, the store; the relay, the publisher; the encounters, the relay.
+ */
+export declare class Factory implements extensions.Factory {
+    private readonly host;
+    /** the publisher of the service running, which the relay it runs publishes through */
+    private publisher;
+    /** one store for the process, made where the process is one that reads it */
+    private store;
+    constructor(host: extensions.Host);
+    aspect(locator: Locator, declaration?: Declaration): extensions.Aspect;
+    service(): Connector;
+    /**
+     * The publisher of the settings there are, made anew where they have changed or the one there was
+     * has stopped with its service.
+     */
+    private publish;
+    private read;
+}

package/transpiled/Factory.js

@@ -0,0 +1,62 @@
+import { environment } from '@toa.io/generic';
+import { ENCOUNTERS, NAMESPACE, QUERIES, RELAY } from '@toa.io/definitions/extensions.chronicles';
+import { Client } from './Client.js';
+import { Publisher } from './Publisher.js';
+import { Reader } from './Reader.js';
+import { Relay } from './Relay.js';
+import { Sender } from './Sender.js';
+import { Service } from './Service.js';
+import { credentials, settings } from './settings.js';
+import { provider } from './store.js';
+/**
+ * A component sends facts through its context; the events it declares reach the log as events of
+ * the context, which the service consumes. The components this extension ships are given what
+ * they serve instead: the queries, the store; the relay, the publisher; the encounters, the relay.
+ */
+export class Factory {
+    host;
+    /** the publisher of the service running, which the relay it runs publishes through */
+    publisher;
+    /** one store for the process, made where the process is one that reads it */
+    store;
+    constructor(host) {
+        this.host = host;
+    }
+    aspect(locator, declaration) {
+        if (mine(locator))
+            switch (locator.name) {
+                case QUERIES:
+                    return new Reader(this.host, () => this.read(), settings);
+                case RELAY:
+                    return new Relay(this.publish());
+                case ENCOUNTERS:
+                    return new Client(this.host, () => settings().ip);
+            }
+        return new Sender(this.host, locator, declaration?.facts ?? {});
+    }
+    // nothing connects to this, so a halt takes the whole of it
+    service() {
+        return this.host.gate(async () => new Service(this.host, settings(), this.publish()));
+    }
+    /**
+     * The publisher of the settings there are, made anew where they have changed or the one there was
+     * has stopped with its service.
+     */
+    publish() {
+        const { broker, retention } = settings();
+        if (this.publisher === undefined ||
+            this.publisher.done ||
+            this.publisher.address !== broker)
+            this.publisher = new Publisher(broker, credentials().broker, environment.scope(), retention);
+        return this.publisher;
+    }
+    read() {
+        this.store ??= provider(settings(), credentials().store, environment.scope());
+        return this.store;
+    }
+}
+/** Whether this is a component the extension ships rather than one of the application's. */
+function mine(locator) {
+    return locator.namespace === NAMESPACE;
+}
+//# sourceMappingURL=Factory.js.map

package/transpiled/Factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EACL,UAAU,EACV,SAAS,EACT,OAAO,EACP,KAAK,EACN,MAAM,2CAA2C,CAAA;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAMrC;;;;GAIG;AACH,MAAM,OAAO,OAAO;IACD,IAAI,CAAiB;IAEtC,sFAAsF;IAC9E,SAAS,CAAuB;IAExC,6EAA6E;IACrE,KAAK,CAAsB;IAEnC,YAAmB,IAAqB;QACtC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEM,MAAM,CAAC,OAAgB,EAAE,WAAyB;QACvD,IAAI,IAAI,CAAC,OAAO,CAAC;YACf,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;gBACrB,KAAK,OAAO;oBACV,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAA;gBAC3D,KAAK,KAAK;oBACR,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;gBAClC,KAAK,UAAU;oBACb,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;YACrD,CAAC;QAEH,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,CAAA;IACjE,CAAC;IAED,4DAA4D;IACrD,OAAO;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IACvF,CAAC;IAED;;;OAGG;IACK,OAAO;QACb,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,QAAQ,EAAE,CAAA;QAExC,IACE,IAAI,CAAC,SAAS,KAAK,SAAS;YAC5B,IAAI,CAAC,SAAS,CAAC,IAAI;YACnB,IAAI,CAAC,SAAS,CAAC,OAAO,KAAK,MAAM;YAEjC,IAAI,CAAC,SAAS,GAAG,IAAI,SAAS,CAC5B,MAAM,EACN,WAAW,EAAE,CAAC,MAAM,EACpB,WAAW,CAAC,KAAK,EAAE,EACnB,SAAS,CACV,CAAA;QAEH,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAEO,IAAI;QACV,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,QAAQ,EAAE,EAAE,WAAW,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,CAAC,CAAA;QAE7E,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;CACF;AAED,4FAA4F;AAC5F,SAAS,IAAI,CAAC,OAAgB;IAC5B,OAAO,OAAO,CAAC,SAAS,KAAK,SAAS,CAAA;AACxC,CAAC"}

package/transpiled/Provider.d.ts

@@ -0,0 +1,142 @@
+import type { Property } from '@toa.io/definitions/extensions.chronicles';
+/**
+ * Where the log is read. A provider reads the log's tables — `events`, a row for everything a
+ * component did, `states`, each entity as it stands, and `encounters`, what clients sent — in a
+ * dialect of its own, which is what an agent writes its queries in. What it reads is what the store
+ * lets the context's user read; it creates nothing there but the views it is asked to.
+ */
+export interface Provider {
+    /** how the store is read: its dialect and what is particular to it, for whoever writes a query */
+    readonly guide: string;
+    /** the names a view cannot take: the provider's own tables */
+    readonly tables: string[];
+    /** the fields of declared properties, at every depth, each with the type its view reads it as */
+    fields(properties: Record<string, Property>): Field[];
+    /** the labels written, with their counts and their times */
+    labels(): Promise<Label[]>;
+    /** the components with a state, with how many entities each has */
+    states(): Promise<Summary[]>;
+    /** the names of encounters, with their counts, their times and the fields their payloads have */
+    encounters(): Promise<Encountered[]>;
+    /** a statement of the dialect, run as a reader that can read the log and nothing else */
+    query(sql: string): Promise<Result>;
+    /** refuses what a view could not be: anything but one statement a query could run */
+    validate(sql: string): Promise<void>;
+    /** the views defined over the log */
+    views(): Promise<View[]>;
+    /** a view of `name`, replacing one there is; with `refresh`, recomputed on that cycle */
+    define(definition: Definition): Promise<void>;
+    drop(name: string): Promise<void>;
+}
+/** A row of `events`. */
+export interface Row {
+    /** the same however many times it is delivered */
+    id: string;
+    /** `<component>.<event>`, or `<component>.<name>` for a fact */
+    label: string;
+    /** the component it is of */
+    component: string;
+    /** when it happened, in milliseconds */
+    time: number;
+    /** the id of the record that changed, where the payload carries one */
+    entity: string | null;
+    /** its `VERSION`, likewise */
+    version: number | null;
+    /** the identity it is of, where something says so */
+    identity: string | null;
+    /** the W3C traceparent of the call that caused it */
+    trace: string | null;
+    payload: object;
+}
+/** An entity as it stands, as the event a component names its `state` renders it. */
+export interface State {
+    component: string;
+    entity: string;
+    version: number;
+    identity: string | null;
+    time: number;
+    payload: object;
+}
+/** A row of `encounters`: what a client sent. */
+export interface Encounter {
+    /** the client's own */
+    id: string;
+    name: string;
+    /** when it happened, by the gateway's clock, at the distance from sending the client measured */
+    time: number;
+    /** when the gateway received it */
+    received: number;
+    /** the client's id of itself, and of the period of its activity, where it gave them */
+    visitor: string | null;
+    session: string | null;
+    /** the identity the gateway verified the client to be */
+    identity: string | null;
+    /** the address and the country the request came from */
+    ip: string | null;
+    country: string | null;
+    /** the origin of the page that sent it, and the client's `user-agent` */
+    origin: string | null;
+    agent: string | null;
+    /** what the agent says the client is: its browser, its system, its kind of device */
+    browser: string | null;
+    os: string | null;
+    device: string | null;
+    payload: object;
+}
+export interface Label {
+    label: string;
+    rows: number;
+    first: string;
+    last: string;
+}
+export interface Summary {
+    component: string;
+    entities: number;
+    /** when the latest change of an entity was made */
+    last: string;
+}
+export interface Encountered {
+    name: string;
+    rows: number;
+    first: string;
+    last: string;
+    received: string;
+    /** the paths of the latest payloads, each with the types it was sent as */
+    fields: Array<{
+        path: string;
+        types: string[];
+    }>;
+}
+/** A field of a declared payload, and the type its view reads it as. */
+export interface Field {
+    path: string;
+    type: string;
+    description?: string;
+    /** the expression that reads it from its table in its type, of a property of the payload */
+    read?: string;
+}
+export interface Definition {
+    name: string;
+    sql: string;
+    /** seconds between computations of a view that is a table */
+    refresh?: number;
+    title?: string;
+    description?: string;
+}
+export interface View extends Definition {
+    /** what a query reads it by */
+    read: string;
+    /** when a view that is a table was last computed */
+    refreshed?: string;
+}
+export interface Result {
+    columns: Array<{
+        name: string;
+        type: string;
+    }>;
+    rows: unknown[][];
+    truncated: boolean;
+}
+/** What a provider refused a statement with, in its own words. */
+export declare class Refusal extends Error {
+}

package/transpiled/Provider.js

@@ -0,0 +1,4 @@
+/** What a provider refused a statement with, in its own words. */
+export class Refusal extends Error {
+}
+//# sourceMappingURL=Provider.js.map

package/transpiled/Provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Provider.js","sourceRoot":"","sources":["../source/Provider.ts"],"names":[],"mappings":"AAiLA,kEAAkE;AAClE,MAAM,OAAO,OAAQ,SAAQ,KAAK;CAAG"}

package/transpiled/Publisher.d.ts

@@ -0,0 +1,50 @@
+import { Connector } from '@toa.io/core';
+import type { Encounter, Row, State } from './Provider.ts';
+import type { User } from './settings.ts';
+/**
+ * Rows to the broker of the log: each a JSON message to the exchange `chronicles` under the key of
+ * its table, with the scope of the context and when it expires. A publication resolves once the
+ * broker has confirmed it, which is what the caller acknowledges what it carried by.
+ *
+ * The connection is made by the first publication and not before, and nothing waits for it to
+ * start: while the broker is away, a publication waits for it, and what it carries waits, unacknowledged,
+ * where it came from.
+ */
+export declare class Publisher extends Connector {
+    private readonly url;
+    private readonly scope;
+    private readonly retention;
+    private io?;
+    private opened?;
+    /** aborted as the publisher stops: what waits for the broker then gives up, to be delivered again */
+    private closing;
+    private stopped;
+    /** where it publishes, which a publisher of other settings does not */
+    readonly address: string;
+    constructor(address: string, user: User, scope: string, retention?: number);
+    publish(rows: Row[], states?: State[], encounters?: Encounter[]): Promise<void>;
+    /**
+     * Fails what waits for the broker, and what is published from now on, so the service publishing
+     * through it is not held open by what would wait for the broker past the service's own end: it
+     * is delivered again, to this process or another.
+     */
+    get done(): boolean;
+    stop(): void;
+    protected open(): Promise<void>;
+    /**
+     * A connection still being made is not waited for — it may never be — but closed once it is,
+     * and what waits for it is failed, so it is delivered again, to this process or another.
+     */
+    protected close(): Promise<void>;
+    private connection;
+    private route;
+}
+/**
+ * A row as the store reads it: of a scope, its times in the store's format, and when it expires,
+ * where it does.
+ */
+export declare function message(row: Row | State | Encounter, scope: string, until: string | null): Record<string, unknown>;
+/** When a row stops being kept: its time and the retention, or the end of the store's time. */
+export declare function expires(from: number, retention: number | undefined): string;
+/** A `DateTime64(3)` as the store reads one without guessing: UTC, to the millisecond. */
+export declare function timestamp(ms: number): string;