@cyanheads/mcp-ts-core 0.13.8 → 0.13.9

package/dist/services/canvas/providers/duckdb/DuckdbProvider.d.ts

@@ -20,9 +20,16 @@ export interface DuckdbProviderOptions {
     /** Number of rows to sniff for schema inference. */
     schemaSniffRows: number;
     /**
-     * Root for scratch I/O — DuckDB's `temp_directory` plus the transient files
-     * behind stream exports and the spillover round-trip. Defaults to
-     * `<os.tmpdir()>/mcp-canvas` when unset; never the process cwd.
+     * Parent of the provider's private scratch directory. On first use the
+     * provider creates `mcp-canvas-XXXXXX` inside it with `mkdtemp` (mode
+     * `0700` on POSIX) and keeps every scratch path there: each canvas's DuckDB
+     * `temp_directory` and the transient files behind stream exports and
+     * `importFrom`. `shutdown()` removes it once the calls still running
+     * against it settle. Defaults to `os.tmpdir()`, never the process cwd. A
+     * configured parent is created if missing and gets no ownership or mode
+     * check, so it must not be a directory another local user controls. On
+     * Windows the private directory inherits the parent's ACL, so there the
+     * parent must also not grant other users access.
      */
     tempRootPath?: string | undefined;
 }
@@ -30,20 +37,50 @@ export declare class DuckdbProvider implements IDataCanvasProvider {
     private readonly options;
     readonly name = "duckdb";
     private readonly canvases;
+    /** One pending promise per held canvas record, resolved on release — see {@link holdCanvas}. */
+    private readonly holds;
+    /** The private scratch directory once first requested — see {@link ensureTempRoot}. */
+    private tempRoot;
     constructor(options: DuckdbProviderOptions);
     /**
-     * Absolute scratch root, created on first use.
+     * The provider's private scratch directory, created once on first use.
      *
-     * DuckDB defaults an in-memory database's `temp_directory` to a
-     * cwd-relative `.tmp`, so the first query that spills `mkdir`s under the
-     * process working directory — which fails with `EACCES` whenever the
-     * container runs non-root or on a read-only rootfs. Resolving scratch to an
-     * explicitly writable directory keeps spills working regardless of cwd.
+     * `mkdtemp` makes a directory no other local user can have pre-created,
+     * planted links in, or read (`0700` on POSIX; on Windows it inherits the
+     * parent's ACL, so there the parent must not grant other users access), so
+     * no scratch path resolves through a fixed shared name (#554). It also
+     * keeps scratch off the process cwd: DuckDB defaults an in-memory
+     * database's `temp_directory` to a cwd-relative `.tmp`, which fails on a
+     * non-root or read-only rootfs. Concurrent first calls share one directory;
+     * a failed attempt is dropped so the next call retries.
      */
     private ensureTempRoot;
+    private createTempRoot;
     initCanvas(canvasId: string, _context: RequestContext): Promise<void>;
+    /**
+     * Close the canvas's instance and remove its spill directory. A call still
+     * running on the canvas keeps the database open on its own connection and
+     * can still read spilled blocks back from that directory, so the directory
+     * goes once the last such call settles, and this does not wait for it.
+     * DuckDB removes a `temp_directory` it created when the database finally
+     * closes; the removal here covers every other case, so nothing of the
+     * canvas outlives it.
+     */
     destroyCanvas(canvasId: string, _context: RequestContext): Promise<void>;
     healthCheck(): Promise<boolean>;
+    /**
+     * Destroy every canvas, then remove the private scratch directory. A call
+     * that reached a canvas before shutdown began can still be writing there —
+     * an open per-query connection outlives its closed instance — so the
+     * directory goes once the last such call settles, and shutdown does not
+     * wait for it. Until then the directory stays in place and private, which
+     * keeps another local user from re-creating its name while that call still
+     * writes inside it. A canvas whose creation straddles the shutdown is
+     * refused rather than bound to the retired directory. A provider used
+     * again afterwards creates a fresh one. After an abnormal exit the
+     * directory stays behind, still private; nothing sweeps it on the next
+     * start.
+     */
     shutdown(): Promise<void>;
     registerTable(canvasId: string, name: string, rows: RegisterRows, _context: RequestContext, options?: RegisterTableOptions): Promise<RegisterTableResult>;
     query(canvasId: string, sql: string, _context: RequestContext, options?: QueryOptions): Promise<QueryResult>;
@@ -54,7 +91,28 @@ export declare class DuckdbProvider implements IDataCanvasProvider {
     private describeOne;
     drop(canvasId: string, name: string, _context: RequestContext): Promise<boolean>;
     clear(canvasId: string, _context: RequestContext): Promise<number>;
-    private requireCanvas;
+    /**
+     * `canvasId`'s record, held until the caller's `using` scope exits, on
+     * return or throw. {@link destroyCanvas} removes the canvas's spill
+     * directory only once every hold on that canvas is released, so a call
+     * already running can still read back the blocks it spilled. {@link shutdown}
+     * removes the scratch directory only once every hold taken before it began
+     * is released, so a call already running finishes inside the private
+     * directory, never in one another local user re-created under its name.
+     * Every data-plane call reaches its record through a hold.
+     */
+    private holdCanvas;
+    /** Host directories an engine message can quote and a caller must not see. */
+    private hostPaths;
+    /** {@link classifyDuckdbError} with this canvas's host directories redacted. */
+    private classify;
+    /**
+     * `err` classified and redacted when it is an engine error naming a host
+     * directory; anything else as it came. For blocks that also run code other
+     * than the engine's — a caller's row source, a cancellation check — whose
+     * failures must reach the caller as thrown.
+     */
+    private redactHostPaths;
     /**
      * Runs `fn` on a connection of its own, so an abort interrupts only this
      * call. A failure after the abort surfaces as `Timeout` (cancelled); any
@@ -67,8 +125,9 @@ export declare class DuckdbProvider implements IDataCanvasProvider {
     private columnNames;
     /**
      * The rejection for a statement that failed to parse or prepare: a
-     * SELECT-shaped statement surfaces the sanitized binder message (the SQL
-     * itself is probably wrong), anything else is rejected as non-SELECT.
+     * SELECT-shaped statement surfaces the binder message, host directories
+     * redacted (the SQL itself is probably wrong), anything else is rejected as
+     * non-SELECT.
      */
     private prepareFailure;
     /**
@@ -130,7 +189,10 @@ export declare function toUint8Array(value: unknown, columnName: string): Uint8A
 export declare const DUCKDB_ERROR_REASONS: {
     /** SQL the engine could not parse. */
     readonly sqlParseError: 'sql_parse_error';
-    /** A write the engine refused, or a permission it denied. */
+    /**
+     * A write the engine refused, or file access its configuration denies —
+     * never the operating system refusing a file, which is an I/O fault.
+     */
     readonly sqlReadOnly: 'sql_read_only';
     /** A gated SELECT that prepared cleanly and then failed on the staged data. */
     readonly sqlExecutionError: 'sql_execution_error';
@@ -145,11 +207,13 @@ export type DuckdbErrorReason = (typeof DUCKDB_ERROR_REASONS)[keyof typeof DUCKD
  * validations) must keep their code and `data.reason` instead of being
  * reclassified as `DatabaseError`.
  *
- * The three caller-side classes are `ValidationError`; everything else — I/O,
- * internal, out-of-memory, transaction, interrupt — stays `DatabaseError`,
- * which is what an export or Parquet round-trip failing on the filesystem
- * must remain.
+ * The three caller-side classes are `ValidationError`, each matched on the
+ * engine's own class prefix; everything else — I/O, internal, out-of-memory,
+ * transaction conflict, interrupt — stays `DatabaseError`, which is what an
+ * export or Parquet round-trip failing on the filesystem must remain (#565).
+ * Every `redact` path in the message becomes `[path]`; the raw engine error,
+ * paths included, stays on `cause`.
  * @internal Exported for unit testing.
  */
-export declare function classifyDuckdbError(err: unknown): Error;
+export declare function classifyDuckdbError(err: unknown, redact?: readonly string[]): Error;
 //# sourceMappingURL=DuckdbProvider.d.ts.map

package/dist/services/canvas/providers/duckdb/DuckdbProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DuckdbProvider.d.ts","sourceRoot":"","sources":["../../../../../src/services/canvas/providers/duckdb/DuckdbProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DuckdbProvider.d.ts","sourceRoot":"","sources":["../../../../../src/services/canvas/providers/duckdb/DuckdbProvider.ts"],"names":[],"mappings":"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"}