@tablecraft-app/plugin-api 1.5.0 → 1.6.0

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 /** Failures the host tells apart; anything else a plugin throws is reported as `statementFailed`. */
-export declare const PLUGIN_ERROR_CODES: readonly ["cancelled", "connectionFailed", "statementFailed", "introspectionFailed", "definitionNotFound", "explainUnsupported", "connectionLost", "sessionBusy", "conflict"];
+export declare const PLUGIN_ERROR_CODES: readonly ["cancelled", "connectionFailed", "statementFailed", "introspectionFailed", "definitionNotFound", "explainUnsupported", "connectionLost", "sessionBusy", "conflict", "timedOut"];
 export type PluginErrorCode = (typeof PLUGIN_ERROR_CODES)[number];
 /**
  * Where the database located a failure, relative to the statement text the plugin received:

package/dist/errors.js

@@ -23,6 +23,11 @@ export const PLUGIN_ERROR_CODES = [
      * nothing (decision 115); the host offers to reload or to overwrite.
      */
     "conflict",
+    /**
+     * The server stopped the statement at the limit `ExecuteOptions.serverTimeoutMs` set (decision
+     * 129); the message names the server's setting.
+     */
+    "timedOut",
 ];
 /** What a plugin throws when the host should react to the kind of failure, not just show it. */
 export class PluginError extends Error {

package/dist/explain.d.ts

@@ -44,6 +44,8 @@ export interface ExplainedPlan {
 export interface ExplainOptions {
     /** Run the statement and report what it did (Explain Analyse), not only how it would run. */
     readonly analyze: boolean;
+    /** `ExecuteOptions.serverTimeoutMs` for the statement `explain` runs (decision 129). */
+    readonly serverTimeoutMs?: number;
 }
 /**
  * Whether a statement can be explained, decided without a database. `writes` says the statement

package/dist/index.d.ts

@@ -5,9 +5,9 @@ export { ConflictError, DefinitionNotFoundError, type ErrorPosition, errorPositi
 export { type ExplainedPlan, type Explainability, type ExplainOptions, type PlanNode, type PlanProperty, } from "./explain.js";
 export { KEY_TYPES, type KeyApplied, type KeyApplyOptions, type KeyBytes, type KeyChange, type KeyContents, type KeyDatabase, type KeyDetails, type KeyExpiry, type KeyInfo, type KeyName, type KeyReadRequest, type KeyScan, type KeyScanRequest, type KeySource, type Keyspace, type KeyType, } from "./keyspace.js";
 export { OBJECT_KINDS, type CatalogObject, type CheckDesign, type ColumnDesign, type DdlContext, type DdlScript, type ForeignKeyDesign, type IndexDesign, type ObjectChange, type ObjectChangeKind, type ObjectEditor, type ObjectFeatures, type ObjectKind, type TableDesign, } from "./objects.js";
-export { CONNECTION_FIELD_GROUPS, CONNECTION_FIELD_KINDS, CONNECTION_URL_FORMS, CONNECTION_URL_PARTS, connectionFieldSchema, connectionUrlSchema, MANIFEST_FILE, networkSpecSchema, pluginManifestSchema, TLS_FIELD_ROLES, tlsSpecSchema, type ConnectionField, type ConnectionFieldGroup, type ConnectionFieldKind, type ConnectionUrl, type ConnectionUrlForm, type ConnectionUrlPart, type NetworkSpec, type PluginManifest, type TlsFieldRole, type TlsSpec, } from "./manifest.js";
+export { BRAND_ID, brandSchema, CONNECTION_FIELD_GROUPS, CONNECTION_FIELD_KINDS, CONNECTION_URL_FORMS, CONNECTION_URL_PARTS, connectionFieldSchema, connectionUrlSchema, MANIFEST_FILE, networkSpecSchema, pluginManifestSchema, TLS_FIELD_ROLES, tlsSpecSchema, type Brand, type ConnectionField, type ConnectionFieldGroup, type ConnectionFieldKind, type ConnectionUrl, type ConnectionUrlForm, type ConnectionUrlPart, type NetworkSpec, type PluginManifest, type TlsFieldRole, type TlsSpec, } from "./manifest.js";
 export { ConnectionUrlError, formatConnectionUrl, parseConnectionUrl, type ConnectionForm, type ConnectionUrlSpec, type ConnectionValue, type ParsedConnectionUrl, } from "./url.js";
-export { type BoundStatement, CAPABILITIES, type Capability, type Column, type ColumnOrigin, type CommandLanguage, type CommandReply, type ConnectOptions, type DatasourcePlugin, type ExecuteOptions, type ExecuteResult, type FormatOptions, FORMAT_STYLES, type FormatStyle, GENERATED_STATEMENTS, type GeneratedStatement, IMPORT_KINDS, type ImportKind, type InferredColumn, type InsertRow, type InsertTarget, KEYWORD_CASES, type NamespaceSwitch, NODE_ALL_PRIMARIES, NODE_AUTO, NODE_ROLES, type NodeRole, type ServerInfo, type ServerInfoSection, type ServerNode, type SlowCommand, switchableTo, type NewColumn, type KeywordCase, PARAMETER_STYLES, type ParameterStyle, type ParameterValue, type RoutineArgument, type RoutineCall, type Row, type SavepointStatements, type SelectSource, omittedMessages, SERVER_MESSAGE_LEVELS, SERVER_MESSAGE_LIMIT, type ServerMessage, type ServerMessageLevel, type SqlParameter, type Session, type SqlLanguage, STATEMENT_KINDS, type StatementClass, type StatementKind, type StatementSpan, type StatementStream, type StreamedStatement, type TlsInfo, TRANSACTION_MODES, type TransactionMode, type Transactions, } from "./plugin.js";
+export { type BoundStatement, CAPABILITIES, type Capability, type Column, type ColumnOrigin, type CommandLanguage, type CommandReply, type ConnectOptions, type DatasourcePlugin, type ExecuteOptions, type ExecuteResult, type FormatOptions, FORMAT_STYLES, type FormatStyle, GENERATED_STATEMENTS, type GeneratedStatement, IMPORT_KINDS, type ImportKind, type InferredColumn, type InsertRow, type InsertTarget, KEYWORD_CASES, type NamespaceSwitch, NODE_ALL_PRIMARIES, NODE_AUTO, NODE_ROLES, type NodeRole, type ServerInfo, type ServerInfoSection, type ServerNode, type ServerTimeout, type SlowCommand, switchableTo, type NewColumn, type KeywordCase, PARAMETER_STYLES, type ParameterStyle, type ParameterValue, type RoutineArgument, type RoutineCall, type Row, type SavepointStatements, type SelectSource, omittedMessages, SERVER_MESSAGE_LEVELS, SERVER_MESSAGE_LIMIT, type ServerMessage, type ServerMessageLevel, type SqlParameter, type Session, type SqlLanguage, STATEMENT_KINDS, type StatementClass, type StatementKind, type StatementSpan, type StatementStream, type StreamedStatement, type TlsInfo, TRANSACTION_MODES, type TransactionMode, type Transactions, } from "./plugin.js";
 export { SERVER_SESSION_STATES, type ServerSession, type ServerSessionState, type SessionListing, type SessionMonitor, type SessionTarget, } from "./sessions.js";
 export { TLS_CHAIN_CODES, TLS_HOST_CODE, homeExpanded, tlsFailureMessage, tlsFileMessage, tlsKeyIsEncrypted, tlsKeyMessage, type TlsVerification, } from "./tls.js";
 export { BYTES_PREVIEW_LENGTH, toBytesValue, toWireInteger, toWireValue, type WireValueOptions, type BigIntValue, type BytesValue, type DateValue, type JsonValue, type TypeClass, type WireValue, } from "./values.js";

package/dist/index.js

@@ -5,7 +5,7 @@ export { ConflictError, DefinitionNotFoundError, errorPositionOf, isPluginError,
 export {} from "./explain.js";
 export { KEY_TYPES, } from "./keyspace.js";
 export { OBJECT_KINDS, } from "./objects.js";
-export { CONNECTION_FIELD_GROUPS, CONNECTION_FIELD_KINDS, CONNECTION_URL_FORMS, CONNECTION_URL_PARTS, connectionFieldSchema, connectionUrlSchema, MANIFEST_FILE, networkSpecSchema, pluginManifestSchema, TLS_FIELD_ROLES, tlsSpecSchema, } from "./manifest.js";
+export { BRAND_ID, brandSchema, CONNECTION_FIELD_GROUPS, CONNECTION_FIELD_KINDS, CONNECTION_URL_FORMS, CONNECTION_URL_PARTS, connectionFieldSchema, connectionUrlSchema, MANIFEST_FILE, networkSpecSchema, pluginManifestSchema, TLS_FIELD_ROLES, tlsSpecSchema, } from "./manifest.js";
 export { ConnectionUrlError, formatConnectionUrl, parseConnectionUrl, } from "./url.js";
 export { CAPABILITIES, FORMAT_STYLES, GENERATED_STATEMENTS, IMPORT_KINDS, KEYWORD_CASES, NODE_ALL_PRIMARIES, NODE_AUTO, NODE_ROLES, switchableTo, PARAMETER_STYLES, omittedMessages, SERVER_MESSAGE_LEVELS, SERVER_MESSAGE_LIMIT, STATEMENT_KINDS, TRANSACTION_MODES, } from "./plugin.js";
 export { SERVER_SESSION_STATES, } from "./sessions.js";

package/dist/manifest.d.ts

@@ -106,6 +106,14 @@ export type TlsSpec = z.infer<typeof tlsSpecSchema>;
 /** The roles of `TlsSpec` that name a field, in the order the dialog draws them. */
 export declare const TLS_FIELD_ROLES: readonly ["mode", "caFile", "certFile", "keyFile", "keyPassphrase"];
 export type TlsFieldRole = (typeof TLS_FIELD_ROLES)[number];
+/** A simple-icons slug, the one public catalogue of database product ids (decision 128). */
+export declare const BRAND_ID: RegExp;
+/** A database product a plugin speaks; `id` is a simple-icons slug, `name` what a row shows. */
+export declare const brandSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strict>;
+export type Brand = z.infer<typeof brandSchema>;
 export declare const pluginManifestSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -131,8 +139,13 @@ export declare const pluginManifestSchema: z.ZodObject<{
         keyValue: "keyValue";
         nodes: "nodes";
         serverInfo: "serverInfo";
+        serverTimeout: "serverTimeout";
     }>>;
     highlight: z.ZodString;
+    brands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>>;
     connection: z.ZodObject<{
         fields: z.ZodArray<z.ZodObject<{
             key: z.ZodString;

package/dist/manifest.js

@@ -157,6 +157,15 @@ function urlSetsDeclared(connection) {
     return Object.entries(url.sets).every(([scheme, values]) => url.schemes.includes(scheme) &&
         Object.keys(values).every((key) => connection.fields.some((field) => field.key === key)));
 }
+/** A simple-icons slug, the one public catalogue of database product ids (decision 128). */
+export const BRAND_ID = /^[a-z0-9_]+$/;
+/** A database product a plugin speaks; `id` is a simple-icons slug, `name` what a row shows. */
+export const brandSchema = z.strictObject({
+    id: z
+        .string()
+        .regex(BRAND_ID, { message: "expected a simple-icons slug: lower-case letters, digits and underscores" }),
+    name: z.string().min(1),
+});
 function includesAny(capabilities, ...wanted) {
     return wanted.some((capability) => capabilities.includes(capability));
 }
@@ -171,6 +180,14 @@ export const pluginManifestSchema = z
     capabilities: z.array(z.enum(CAPABILITIES)),
     /** The highlighter the console uses for this plugin's dialect (decision 008). */
     highlight: z.string().min(1),
+    /** The database products the plugin speaks, its default first (decision 128). Absent: rows name the plugin. */
+    brands: z
+        .array(brandSchema)
+        .min(1)
+        .refine((brands) => new Set(brands.map((brand) => brand.id)).size === brands.length, {
+        message: "brand ids must be unique",
+    })
+        .optional(),
     /** The connection form, readable without running plugin code (decision 019). */
     connection: z
         .strictObject({

package/dist/plugin.d.ts

@@ -11,7 +11,7 @@ import type { TypeClass, WireValue } from "./values.js";
  * What a plugin can do. The UI branches on these, never on a plugin id (decision 007), and a
  * capability without contract-suite coverage cannot be declared (decision 013).
  */
-export declare const CAPABILITIES: readonly ["sql", "cancel", "schemaTree", "transactions", "ddl", "explain", "explainAnalyze", "currentNamespace", "keepAlive", "bulkInsert", "objects", "serverMessages", "sessions", "routineCall", "commands", "keyValue", "nodes", "serverInfo"];
+export declare const CAPABILITIES: readonly ["sql", "cancel", "schemaTree", "transactions", "ddl", "explain", "explainAnalyze", "currentNamespace", "keepAlive", "bulkInsert", "objects", "serverMessages", "sessions", "routineCall", "commands", "keyValue", "nodes", "serverInfo", "serverTimeout"];
 export type Capability = (typeof CAPABILITIES)[number];
 /** Statements `SqlLanguage.generate` writes from a catalog relation (plan 010). */
 export declare const GENERATED_STATEMENTS: readonly ["drop", "select", "insert", "update"];
@@ -128,6 +128,25 @@ export interface ExecuteOptions {
      * many times and answers with the last run; any other plugin never receives it.
      */
     readonly repeat?: number;
+    /**
+     * Have the server itself stop the statement after this many milliseconds, at least 1 (decision
+     * 129), through its own setting, never above a limit the server already had. The host sends it
+     * only to a session whose `serverTimeout` is not null. Absent: the plugin puts back the
+     * server's own value. A statement the server stops rejects with `timedOut`.
+     */
+    readonly serverTimeoutMs?: number;
+}
+/** What the connected server stops by itself once `ExecuteOptions.serverTimeoutMs` passes (decision 129). */
+export interface ServerTimeout {
+    /** The server's own name for it, for messages: `max_execution_time`, `statement_timeout`. */
+    readonly setting: string;
+    /** `reads`: only `SELECT` (and `SELECT … FOR UPDATE`); `all`: every statement. */
+    readonly covers: "reads" | "all";
+    /**
+     * `statement`: from the start until the last row is sent, so a result read slowly is cut too;
+     * `serverWork`: only while the server works on it.
+     */
+    readonly counts: "statement" | "serverWork";
 }
 /** `ExecuteOptions.node`: the plugin routes the command by its keys (decision 114). */
 export declare const NODE_AUTO = "auto";
@@ -275,6 +294,8 @@ export interface Session {
     close(): Promise<void>;
     /** What the server reports about itself, such as `17.4`; null when it reports nothing. */
     readonly serverVersion: string | null;
+    /** The manifest `brands` id of the product this session reached; absent when the plugin declares no brands or cannot tell. */
+    readonly serverBrand?: string;
     /**
      * True when another session on the same configuration sees a different database, as with
      * SQLite's `:memory:`; the engine then never re-runs this session's statements elsewhere.
@@ -285,6 +306,12 @@ export interface Session {
      * (decision 072).
      */
     readonly tls?: TlsInfo | null;
+    /**
+     * Present exactly when the plugin declares `serverTimeout` (decision 129): what this server stops
+     * by itself under `ExecuteOptions.serverTimeoutMs`, read once at connect; null when this server
+     * version has no such setting.
+     */
+    readonly serverTimeout?: ServerTimeout | null;
 }
 /** What a TLS handshake agreed, as Node's socket names it: `TLSv1.3`, `TLS_AES_256_GCM_SHA384`. */
 export interface TlsInfo {

package/dist/plugin.js

@@ -21,6 +21,7 @@ export const CAPABILITIES = [
     "keyValue",
     "nodes",
     "serverInfo",
+    "serverTimeout",
 ];
 /** Statements `SqlLanguage.generate` writes from a catalog relation (plan 010). */
 export const GENERATED_STATEMENTS = ["drop", "select", "insert", "update"];

package/dist/testing/index.d.ts

@@ -9,6 +9,18 @@ export interface ContractFixture {
     readonly statements?: {
         /** A statement that runs for `seconds`; required when the plugin declares `cancel`. */
         readonly sleep?: (seconds: number) => string;
+        /**
+         * A read that runs at least `seconds` on an idle server and then ends by itself, which the
+         * server's own limit stops with an error; required when a session reports a `serverTimeout`
+         * (decision 129). Not `sleep`, which MySQL answers with 1 instead of an error when the limit
+         * cuts it.
+         */
+        readonly slowRead?: (seconds: number) => string;
+        /**
+         * Sets the session's own statement limit to `ms`, as a DBA's per-user default would; required
+         * with `slowRead`.
+         */
+        readonly sessionTimeout?: (ms: number) => string;
         /**
          * A write that succeeds on a writable session and leaves the fixture unchanged, such as an
          * update setting a column to itself; the read-only case is skipped without one.

package/dist/testing/index.js

@@ -179,6 +179,16 @@ const SLEEP_SECONDS = 30;
 const CANCEL_DELAY_MS = 500;
 /** Well under `SLEEP_SECONDS`, so a cancel that did nothing fails the test instead of passing late. */
 const CANCEL_DEADLINE_MS = 10_000;
+/** The limit the `serverTimeout` cases ask for; servers check theirs about every 100 ms. */
+const SERVER_LIMIT_MS = 1500;
+/** Far past `SERVER_LIMIT_MS`, so a limit that did nothing fails the test instead of passing late. */
+const SLOW_READ_SECONDS = 8;
+/** Long enough to show a read ran past `SERVER_LIMIT_MS` with no limit, short enough to wait for. */
+const SHORT_READ_SECONDS = 3;
+/** A limit the slow read never reaches, for the cases where something else must stop it first. */
+const UNREACHED_LIMIT_MS = 2 * SLOW_READ_SECONDS * 1000;
+/** When a stopped statement must have rejected: the limit plus the server's slack. */
+const SERVER_LIMIT_DEADLINE_MS = 5_000;
 const KEEPALIVE_DELAY_MS = 1000;
 /** How long a listing may take to show what another connection just did. */
 const LISTING_DEADLINE_MS = 10_000;
@@ -360,6 +370,15 @@ export function runPluginContract(plugin, fixture) {
                 return Promise.resolve();
             });
         });
+        const brands = fixture.manifest.brands;
+        it.runIf(brands !== undefined)("givenBrands_whenSessionOpens_thenServerBrandIsDeclared", async () => {
+            await withSession(plugin, fixture, (session) => {
+                if (session.serverBrand !== undefined) {
+                    expect(brands?.map((brand) => brand.id)).toContain(session.serverBrand);
+                }
+                return Promise.resolve();
+            });
+        });
         it("givenSession_whenConnected_thenTlsIsNullOrDescribed", async () => {
             await withSession(plugin, fixture, (session) => {
                 if (session.tls !== undefined && session.tls !== null) {
@@ -2143,6 +2162,76 @@ export function runPluginContract(plugin, fixture) {
                 });
             });
         });
+        describe.runIf(plugin.capabilities.includes("serverTimeout"))("serverTimeout", () => {
+            function slowRead(seconds) {
+                const read = fixture.statements?.slowRead;
+                if (read === undefined)
+                    throw new Error("A server with a serverTimeout needs fixture.statements.slowRead.");
+                return read(seconds);
+            }
+            /** Runs `sql` to its last row, so a limit that strikes while rows stream counts too. */
+            async function runToEnd(session, sql, serverTimeoutMs) {
+                const options = serverTimeoutMs === undefined ? undefined : { serverTimeoutMs };
+                await collect((await session.execute(sql, undefined, options)).rows);
+            }
+            /** Runs `use` on a session whose server enforces a limit; a server without one has nothing to check. */
+            async function withLimitedSession(use) {
+                await withSession(plugin, fixture, async (session) => {
+                    if (session.serverTimeout === null || session.serverTimeout === undefined)
+                        return;
+                    await use(session);
+                });
+            }
+            it("givenSession_whenInspected_thenReportsServerTimeout", async () => {
+                await withSession(plugin, fixture, (session) => {
+                    expect(session.serverTimeout).not.toBeUndefined();
+                    if (session.serverTimeout !== null && session.serverTimeout !== undefined) {
+                        expect(session.serverTimeout.setting).toMatch(/\S/);
+                    }
+                    return Promise.resolve();
+                });
+            });
+            it("givenServerTimeout_whenSlowReadPastLimit_thenRejectsTimedOut", async () => {
+                await withLimitedSession(async (session) => {
+                    const started = Date.now();
+                    const code = await rejectionCode(runToEnd(session, slowRead(SLOW_READ_SECONDS), SERVER_LIMIT_MS));
+                    expect(code).toBe("timedOut");
+                    expect(Date.now() - started).toBeLessThan(SERVER_LIMIT_DEADLINE_MS);
+                    await expectAlive(session);
+                });
+            });
+            it("givenServerTimeoutThenNone_whenSlowRead_thenRunsPastIt", async () => {
+                await withLimitedSession(async (session) => {
+                    await runToEnd(session, selectOne, SERVER_LIMIT_MS);
+                    const started = Date.now();
+                    await runToEnd(session, slowRead(SHORT_READ_SECONDS));
+                    expect(Date.now() - started).toBeGreaterThan(SERVER_LIMIT_MS);
+                });
+            });
+            it("givenOwnLowerLimit_whenHigherAsked_thenOwnStops", async () => {
+                await withLimitedSession(async (session) => {
+                    const own = fixture.statements?.sessionTimeout;
+                    if (own === undefined)
+                        throw new Error("A server with a serverTimeout needs fixture.statements.sessionTimeout.");
+                    await runToEnd(session, own(SERVER_LIMIT_MS));
+                    const started = Date.now();
+                    const code = await rejectionCode(runToEnd(session, slowRead(SLOW_READ_SECONDS), UNREACHED_LIMIT_MS));
+                    expect(code).toBe("timedOut");
+                    expect(Date.now() - started).toBeLessThan(SERVER_LIMIT_DEADLINE_MS);
+                });
+            });
+            it("givenServerTimeout_whenCancelled_thenCancelledNotTimedOut", async () => {
+                await withLimitedSession(async (session) => {
+                    const started = Date.now();
+                    const running = rejectionCode(runToEnd(session, slowRead(SLOW_READ_SECONDS), UNREACHED_LIMIT_MS));
+                    await delay(CANCEL_DELAY_MS);
+                    await session.cancel?.();
+                    expect(await running).toBe("cancelled");
+                    expect(Date.now() - started).toBeLessThan(CANCEL_DEADLINE_MS);
+                    await expectAlive(session);
+                });
+            });
+        });
         describe.runIf(plugin.capabilities.includes("keepAlive"))("keepAlive", () => {
             it("givenKeepAlive_whenConnectedWithDelay_thenPingResolvesAndSessionWorks", async () => {
                 await withSession(plugin, fixture, async (session) => {

package/dist/version.js

@@ -2,7 +2,7 @@
  * The plugin contract's version, by semver (decision 106): a host loads a plugin built for the same
  * major and an older or equal minor. Typed `string` so a bump does not change the API report.
  */
-export const API_VERSION = "1.5.0";
+export const API_VERSION = "1.6.0";
 const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 /** `major.minor.patch` and nothing else; pre-release and build tags are not accepted. */
 export function parseVersion(text) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tablecraft-app/plugin-api",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "The datasource plugin contract for TableCraft",
   "license": "MIT",
   "type": "module",