@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/connections.d.ts

@@ -0,0 +1,353 @@
+import { type HiddenColumnRules } from './hiddenColumns.js';
+export { redact, scrubSecrets } from './connectionRedaction.js';
+import { type HttpAuthConfig, type HttpConnectionConfig } from './httpConnection.js';
+import { type ConfigSections, type ServiceConfig, type ServiceKind, type ServiceKinds } from './configSections.js';
+import { type CacheStore } from '../adapters/cache/cacheStore.js';
+import type { HttpDescription } from '../adapters/http/httpDescription.js';
+import type { Adapter } from '../adapters/adapter.js';
+import type { PoolRoleStats } from '../adapters/poolMetrics.js';
+import { type PoolSize } from './poolConfig.js';
+import type { DatabaseSchema } from '../shared/schema.js';
+import type { PublicConnection } from '../shared/connection.js';
+export { sqliteTargetFrom } from './configPaths.js';
+export type { PublicConnection } from '../shared/connection.js';
+export interface ConnectionConfig {
+    /** Stable identifier, used by the client and in URLs. */
+    id: string;
+    name: string;
+    /**
+     * SQLite path, database URL, or an API's base URL. Never leaves the server. A SQLite path a config file wrote
+     * relative to itself is already located here (`loadConfig`): every reader of the url opens the one file.
+     */
+    url: string;
+    /** The url as the config file wrote it, when locating it changed it: what a save writes back. */
+    writtenUrl?: string;
+    /** Postgres only. */
+    schemas?: string[];
+    /**
+     * Whether this connection may be written to at all.
+     *
+     * Read-only unless the config says otherwise, and the server enforces it —
+     * the browser's write toggle is a second gate, not the only one. A guard in
+     * the browser is not a guard: the client decides whether to *offer* editing,
+     * and until now the server took that decision on trust, so anything that
+     * could reach the endpoint could write.
+     *
+     * Per connection rather than per process because that is the shape of the
+     * actual risk. The same session usually holds a local database you want to
+     * edit and a production one you emphatically do not, and a global flag
+     * forces you to choose between restarting to fix a row and leaving
+     * production editable all afternoon.
+     */
+    writable?: boolean;
+    /**
+     * Where this database's migrations are (`tablewalk migrate`): a directory
+     * relative to the config file, and the history table's name when it is not
+     * tablewalk's own `__mistri_schema_history` (a team moving over from
+     * Flyway names `flyway_schema_history`). Read by the migrate command only.
+     */
+    migrations?: {
+        dir: string;
+        table?: string;
+    };
+    /**
+     * Whether rows may leave this connection at all. Default true.
+     *
+     * `"rows": false` is the enforced form of the boundary the README states
+     * in prose: shape is safe to hand an agent, row values are not, and a
+     * production database is exactly where that distinction matters. The
+     * catalog, counts, null fractions, plans and lint still answer; anything
+     * that would return a value out of a row refuses, at the adapter, for
+     * every endpoint and tool at once.
+     */
+    rows?: boolean;
+    /**
+     * Columns no one is served over this connection: table (id, bare name or
+     * "*") → column names, `*` a wildcard within a name. The Workbench, MCP and
+     * every App on it see a catalog without them, and raw SQL is refused
+     * (hiddenColumns.ts).
+     */
+    hidden?: HiddenColumnRules;
+    /**
+     * A PostgreSQL connection's pools: `{ "read": 16, "write": 8 }` lets
+     * sixteen reads and eight App writes hold a connection at once (each 1–64;
+     * `--read-pool` and `--write-pool`, else sized from the cores, when absent). The database
+     * browser writes through one whatever `write` says (writeLanes.ts).
+     */
+    pool?: PoolSize;
+    /**
+     * Read replicas of a PostgreSQL database, by URL, each resolved
+     * as `url` is. Lists, dashboards, counts and exports read from them in
+     * turn; record pages, writes, commands and a person's reads just after
+     * their own write stay on the primary (packages/engine/src/adapters/replicas.ts).
+     */
+    replicas?: string[];
+    /**
+     * A PostgreSQL connection's direct URL for `LISTEN`, used by a jobs host
+     * when `url` goes through a transaction-mode pooler, which cannot hold a
+     * listening session (packages/mistri/src/adapters/events/postgresCommandEventWake.ts).
+     */
+    listen?: string;
+    /**
+     * Present for an API read through its description (`"kind": "http"` in the
+     * config file); `url` is then the API's base URL. It holds no secret:
+     * `auth` keeps its `${VAR}` references until the connection opens.
+     */
+    http?: HttpConnectionConfig;
+    /** Where this came from, so the UI can say why it is listed. */
+    source: 'argument' | 'config' | 'session';
+}
+export declare class Registry {
+    /** The environment this registry's references resolve in: an App's own in a suite, else the process's (undefined). */
+    readonly environment?: NodeJS.ProcessEnv;
+    /** A suite captures each App's references once; standalone registries retain
+     * the existing process-environment lookup when a connection opens. */
+    constructor(options?: {
+        environment?: NodeJS.ProcessEnv;
+    });
+    private entries;
+    private activeId;
+    private invalidateAdapter;
+    /** Private serving-owner fence, not an authorization proof or a lease.
+     * Refuses synchronously once closure starts, even while drain/close awaits. */
+    captureAdapterLifetime(id: string, expectedAdapter: Adapter): () => void;
+    /** Told of each adapter a connection dials, before anything can write through it. */
+    private readonly dialedHooks;
+    /** Record history binds its tables here, so a reconnect records exactly as the adapter it replaced did (recordHistory.ts). */
+    onAdapterDialed(hook: (id: string, adapter: Adapter) => void): void;
+    /**
+     * The adapter a connection has open now, as dialed: the object the dial
+     * hooks were told of and a write capture is keyed by, or undefined while
+     * none is open. Nothing is dialed. Trusted server code only (live sync's
+     * binding): it is beneath the hidden-column and shape-only wrappers, so it
+     * is never handed to a reader.
+     */
+    dialedAdapter(id: string): Adapter | undefined;
+    /** Where a connection's one-time notices go: stderr, where startup speaks. Tests replace it. */
+    onWarning: (message: string) => void;
+    /** The services the config names beside its databases: not databases, never listed or browsed. The cache is the engine's; the App framework registers the rest (configSections.ts). */
+    private readonly services;
+    /** The config sections this registry's services were read under: what saves them back and what makes a kind a singleton. */
+    sections: ConfigSections;
+    private cacheStore?;
+    private cacheWarnedAt;
+    private readonly moduleState;
+    private readonly rolesSaid;
+    /** A service from the config. Names are unique among services; a kind that is a singleton (the cache, the email service) is configured once. */
+    addService(service: ServiceConfig): void;
+    /** The entries of kinds this binary does not read (`others: 'keep'`), as written, for a save to put back. */
+    private readonly kept;
+    keep(entry: Record<string, unknown>): void;
+    keptEntries(): ReadonlyArray<Record<string, unknown>>;
+    /** The services as written — references intact — for saving the config back. */
+    serviceConfigs(): ServiceConfig[];
+    /** The services of one kind, as written. */
+    servicesOfKind<K extends ServiceKind>(kind: K): Array<ServiceKinds[K]>;
+    /** State a module keeps for this registry, made on first use; `resetOnClose` state is forgotten by `closeServices`. */
+    serviceState<T>(key: string, make: () => T, options?: {
+        resetOnClose?: boolean;
+    }): T;
+    /**
+     * The deployment's cache: the Valkey a cache connection names, dialed on
+     * first use, or this process's own. Its outages are said at most once a
+     * minute; meanwhile every read is a miss.
+     */
+    cache(): CacheStore;
+    closeServices(): Promise<void>;
+    add(config: Omit<ConnectionConfig, 'id'> & {
+        id?: string;
+    }, options?: {
+        untrusted?: boolean;
+        resolved?: boolean;
+    }): ConnectionConfig;
+    /** The file a SQLite connection opens, absolute, where its URL is written out (no `${VAR}`): what a refusal names. */
+    sqliteFile(id: string): string | undefined;
+    has(id: string): boolean;
+    /** The stored configuration, for the manager to edit and to write back. */
+    configOf(id: string): ConnectionConfig | undefined;
+    /** Every stored configuration, in order, including its secrets as written. */
+    configs(): ConnectionConfig[];
+    /**
+     * Each database connection's URL as opening it would read it: `${VAR}` references resolved through this
+     * registry's captured environment (an untrusted URL as written), an API's left out. Read in one pass with no
+     * await, so an update between reads cannot retarget a connection already visited.
+     */
+    openableUrls(): string[];
+    /**
+     * Change a connection's name, target or schema list.
+     *
+     * The open adapter is discarded whenever the target changes, because an
+     * entry whose URL says one database while its schema describes another is
+     * the worst of both: it looks edited and behaves as it did before. The name
+     * alone can change without reconnecting.
+     */
+    update(id: string, patch: Partial<Omit<ConnectionConfig, 'id'>>, options?: {
+        untrusted?: boolean;
+    }): Promise<ConnectionConfig>;
+    /**
+     * Replace a connection's stored URL with one that names the same database.
+     *
+     * This is how a password moves out of the URL and into the keychain when
+     * the connections are saved: the target has not changed, only how the
+     * secret is remembered, so nothing that `update` does for a retarget —
+     * closing the adapter, dropping the writable flag, marking the URL as an
+     * untrusted client's — applies. The same-target rule is checked, not assumed: with
+     * the password blanked on both sides the two URLs must be identical, or
+     * this refuses rather than quietly becoming a retarget with the guards off.
+     */
+    rewriteUrl(id: string, url: string): ConnectionConfig;
+    /**
+     * Forget a connection.
+     *
+     * This used to refuse the last one, and the reason it gave was honest: a
+     * browser with no database to browse was a page that could not do anything,
+     * and the way out of that state was not obvious. Both halves of that have
+     * stopped being true — the server starts with nothing now, and the page it
+     * serves in that state exists to do exactly one thing, which is get you out
+     * of it. A rule that guards against a state the product supports is just a
+     * connection you cannot remove.
+     *
+     * The active connection moves to whatever remains, or to nothing.
+     */
+    remove(id: string): Promise<void>;
+    get active(): string | null;
+    /**
+     * Choose the default connection, or `null` for none.
+     *
+     * Null is reachable now that the server starts with nothing, and it is what
+     * an add has to fall back to when the connection it just made turns out not
+     * to open: `add` makes the first one active before anything has tried to
+     * dial it, so a failed first add left the whole application pointed at a
+     * connection that had never worked.
+     */
+    setActive(id: string | null): void;
+    list(): PublicConnection[];
+    /**
+     * Open a connection if it is not already open, and return it with its
+     * schema. A failure is recorded on the entry rather than thrown away, so
+     * the sidebar can show which connection is broken and why.
+     */
+    open(id: string): Promise<{
+        adapter: Adapter;
+        schema: DatabaseSchema;
+    }>;
+    private warnWiderRole;
+    private resolveReplicas;
+    private dial;
+    /**
+     * Hold a connection open for the length of one request.
+     *
+     * Closing an adapter is not an operation the thing using it finds out
+     * about. A slow `/api/run` in one tab and a `refresh` in another meant the
+     * pg client was ended mid-query — the read came back as a driver-level
+     * "connection closed" 500, and on SQLite as a use-after-close. Nothing
+     * counted who was using what.
+     *
+     * The lease is taken when a request resolves its connection and released
+     * when the response ends, whichever way it ends.
+     */
+    lease(id: string): () => void;
+    /**
+     * Wait for the requests using a connection to finish.
+     *
+     * Bounded, because a query can be stuck for as long as the statement
+     * timeout allows and "the close hangs" is a worse failure than "the close
+     * was slightly rude". After the wait it closes anyway — which is the old
+     * behaviour, now as a last resort rather than as the only one.
+     */
+    private drain;
+    /** Drop the cached schema so the next open re-reads the catalog. */
+    refresh(id: string): Promise<{
+        adapter: Adapter;
+        schema: DatabaseSchema;
+    }>;
+    closeAll(): Promise<void>;
+    /**
+     * Every open connection's pool meters, for the operator surface. A
+     * connection is named by its position among the configured ones — the
+     * order of tablewalk.json, then the command line — and never by its name
+     * or URL, which that surface must not carry. A connection not yet opened
+     * has no pool to report.
+     */
+    poolStats(): ConnectionPoolStats[];
+}
+/** One open pool's meters, by its connection's position among the configured ones. */
+export type ConnectionPoolStats = PoolRoleStats & {
+    readonly position: number;
+    readonly dialect: string;
+};
+interface ConfigFile {
+    connections: Array<{
+        name: string;
+        url: string;
+        schemas?: string[];
+        /** Opt in to writes. Absent or false means the server refuses them. */
+        writable?: boolean;
+        /** `false` makes the connection shape-only: no row values leave it. */
+        rows?: boolean;
+        /** Table → columns never served over the connection (hiddenColumns.ts). */
+        hidden?: HiddenColumnRules;
+        /** `{ "read": n, "write": m }`: a PostgreSQL connection's pool sizes, checked by poolOf. */
+        pool?: unknown;
+        /** Read replicas' URLs, checked by replicasOf. */
+        replicas?: unknown;
+        /** A direct URL for LISTEN behind a pooler, checked by listenOf. */
+        listen?: unknown;
+        /** `"http"` for an API, `"cache"`, `"webhook"`, … for a service (serviceConnections.ts); absent for a database. */
+        kind?: 'http' | ServiceKind;
+        /** A description file relative to this one, or the description itself. */
+        description?: string | HttpDescription;
+        auth?: HttpAuthConfig;
+        insecure?: boolean;
+        allowLinkLocal?: boolean;
+        cache?: {
+            ttl: number;
+        };
+        /** Where its migrations are (tablewalk migrate), checked below. */
+        migrations?: {
+            dir: string;
+            table?: string;
+        };
+    }>;
+}
+export interface LoadedConfig {
+    path: string;
+    /** As written — a SQLite path located against the file (`writtenUrl` keeps the spelling) — plus an HTTP connection's fields checked and its description resolved against the file, and a checked pool. */
+    connections: Array<Omit<ConfigFile['connections'][number], 'pool' | 'replicas' | 'listen'> & {
+        writtenUrl?: string;
+        http?: HttpConnectionConfig;
+        pool?: PoolSize;
+        replicas?: string[];
+        listen?: string;
+    }>;
+    /** The services the file names beside its databases, checked; never databases, never listed as connections. */
+    services: ServiceConfig[];
+    /** Entries of kinds these sections keep unread (`others: 'keep'`), as written. */
+    kept?: Array<Record<string, unknown>>;
+}
+/**
+ * Read the first config file that exists.
+ *
+ * A missing file is not an error — most people will never write one. A file
+ * that exists but is malformed *is* an error, and is reported rather than
+ * skipped: silently ignoring a config someone wrote is worse than refusing.
+ *
+ * A SQLite path written relative to the file is located here, once, against
+ * the file's folder (`sqliteTargetFrom`), and `writtenUrl` keeps the spelling
+ * for a save. Every tool reads its connections through here — a start, check,
+ * build, migrate, seed, a suite, the token and test commands — and each used
+ * to apply the rule itself or not at all: a migrate run from an App's folder
+ * looked for `./shop.db` there while the server beside it opened the file
+ * next to the config, and the command journal a start puts beside the
+ * database was made in the working directory. A value from the environment
+ * (`"${DATABASE_URL}"`) is not the file's: it is read as given, from where
+ * tablewalk runs, as the same variable is without a config.
+ */
+export declare function loadConfig(explicit: string | undefined, sections: ConfigSections): Promise<LoadedConfig | undefined>;
+interface StoreResult {
+    stored: 'keychain' | 'file';
+    /** The URL to keep, with the password removed. */
+    url: string;
+}
+export declare function storeSecret(name: string, url: string): Promise<StoreResult | undefined>;
+export declare function saveConfig(path: string, connections: ConnectionConfig[], services?: readonly ServiceConfig[], sections?: ConfigSections, kept?: ReadonlyArray<Record<string, unknown>>): Promise<void>;