@milaboratories/pl-model-middle-layer 1.8.13 → 1.8.15

package/dist/pframe/internal_api/common.d.ts

@@ -1,4 +1,5 @@
 import { AxisSpec, ValueType } from '@milaboratories/pl-model-common';
+export type Logger = (level: 'info' | 'warn' | 'error', message: string) => void;
 export interface SingleAxisSelector {
     name: string;
     type?: ValueType;

package/dist/pframe/internal_api/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,QAAQ,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAE9E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,kBAAkB,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,cAAc,EAAE,iBAAiB,EAAE,CAAC;CACrC;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B,CAAA"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAEtE,MAAM,MAAM,MAAM,GAAG,CACnB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAChC,OAAO,EAAE,MAAM,KACZ,IAAI,CAAC;AAEV,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,kBAAkB,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,cAAc,EAAE,iBAAiB,EAAE,CAAC;CACrC;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B,CAAA"}

package/dist/pframe/internal_api/http_helpers.cjs

@@ -0,0 +1,31 @@
+'use strict';
+
+/** File system abstraction for request handler factory, @see HttpHelpers.createRequestHandler */
+class ObjectStore {
+    logger;
+    constructor(options) {
+        this.logger = options.logger ?? (() => { });
+    }
+    /** Translate HTTP range to file range, @returns null if the range is not satisfiable */
+    translate(fileSize, range) {
+        if (!range)
+            return { start: 0, end: fileSize - 1 };
+        switch (range.type) {
+            case 'bounded':
+                if (range.end >= fileSize)
+                    return null;
+                return { start: range.start, end: range.end };
+            case 'offset':
+                if (range.offset >= fileSize)
+                    return null;
+                return { start: range.offset, end: fileSize - 1 };
+            case 'suffix':
+                if (range.suffix > fileSize)
+                    return null;
+                return { start: fileSize - range.suffix, end: fileSize - 1 };
+        }
+    }
+}
+
+exports.ObjectStore = ObjectStore;
+//# sourceMappingURL=http_helpers.cjs.map

package/dist/pframe/internal_api/http_helpers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"http_helpers.cjs","sources":["../../../src/pframe/internal_api/http_helpers.ts"],"sourcesContent":["import type { Readable } from 'node:stream';\nimport type { RequestListener } from 'node:http';\nimport type { Branded, Base64Encoded } from '@milaboratories/pl-model-common';\nimport type { Logger } from './common';\n\n/** Parquet file name */\nexport type ParquetFileName = Branded<`${string}.parquet`, 'PFrameInternal.ParquetFileName'>;\n\nexport type FileRange = {\n  /** Start byte position (inclusive) */\n  start: number;\n  /** End byte position (inclusive) */\n  end: number;\n}\n\n/** HTTP range as of RFC 9110 <https://datatracker.ietf.org/doc/html/rfc9110#name-range> */\nexport type HttpRange =\n  | {\n      /**\n       * Get file content in the specified byte range\n       * \n       * @example\n       * ```\n       * GET /file.parquet HTTP/1.1\n       * Range: bytes=0-1023\n       * ```\n       */\n      type: 'bounded';\n      /** Start byte position (inclusive) */\n      start: number;\n      /** End byte position (inclusive) */\n      end: number;\n    }\n  | {\n      /**\n       * Get byte range starting from the specified offset\n       * \n       * @example\n       * ```\n       * GET /file.parquet HTTP/1.1\n       * Range: bytes=1024-\n       * ```\n       */\n      type: 'offset';\n      /** Start byte position (inclusive) */\n      offset: number;\n    }\n  | {\n      /**\n       * Get byte range starting from the specified suffix\n       * \n       * @example\n       * ```\n       * GET /file.parquet HTTP/1.1\n       * Range: bytes=-1024\n       * ```\n       */\n      type: 'suffix';\n      /** End byte position (inclusive) */\n      suffix: number;\n    };\n\n/** HTTP method passed to object store */\nexport type HttpMethod = 'GET' | 'HEAD';\n\n/** HTTP response from object store */\nexport type ObjectStoreResponse =\n  | {\n      /** Will be translated to 500 Internal Server Error by the handler */\n      type: 'InternalError';\n    }\n  | {\n      /** Will be translated to 404 Not Found by the handler */\n      type: 'NotFound';\n    }\n  | {\n      /** Will be translated to 416 Range Not Satisfiable by the handler */\n      type: 'RangeNotSatisfiable';\n      /** Total file size in bytes */\n      size: number;\n    }\n  | {\n      /** Will be translated to 200 OK or 206 Partial Content by the handler */\n      type: 'Ok';\n      /** Total file size in bytes */\n      size: number;\n      /** File range translated from HTTP range */\n      range: FileRange;\n      /** Stream of file content, undefined for HEAD requests */\n      data?: Readable;\n    }\n\n/** Common options for object store creation */\nexport interface ObjectStoreOptions {\n  /** Logger instance, no logging is performed when not provided */\n  logger?: Logger;\n}\n\n/** Options for file system object store creation */\nexport interface FsStoreOptions extends ObjectStoreOptions {\n  /** Local directory to serve files from */\n  rootDir: string;\n}\n\n/** File system abstraction for request handler factory, @see HttpHelpers.createRequestHandler */\nexport abstract class ObjectStore {\n  protected readonly logger: Logger;\n\n  constructor(options: ObjectStoreOptions) {\n    this.logger = options.logger ?? (() => {});\n  }\n\n  /** Translate HTTP range to file range, @returns null if the range is not satisfiable */\n  protected translate(fileSize: number, range?: HttpRange): FileRange | null {\n    if (!range) return { start: 0, end: fileSize - 1 };\n    switch (range.type) {\n      case 'bounded':\n        if (range.end >= fileSize) return null;\n        return { start: range.start, end: range.end };\n      case 'offset':\n        if (range.offset >= fileSize) return null;\n        return { start: range.offset, end: fileSize - 1 };\n      case 'suffix':\n        if (range.suffix > fileSize) return null;\n        return { start: fileSize - range.suffix, end: fileSize - 1 };\n    }\n  }\n\n  /**\n   * Proxy HTTP(S) request for parquet file to object store.\n   * Callback promise resolves when stream is closed by handler @see HttpHelpers.createRequestHandler\n   * Callback API is used so that ObjectStore can limit the number of concurrent requests.\n   */\n  abstract request(\n    filename: ParquetFileName,\n    params: {\n      method: HttpMethod;\n      range?: HttpRange;\n      signal: AbortSignal;\n      callback: (response: ObjectStoreResponse) => Promise<void>;\n    }\n  ): void;\n}\n\n/** Object store base URL in format accepted by Apache DataFusion and DuckDB */\nexport type ObjectStoreUrl = Branded<string, 'PFrameInternal.ObjectStoreUrl'>;\n\n/** HTTP(S) request handler creation options */\nexport type RequestHandlerOptions = {\n  /** Object store to serve files from, @see HttpHelpers.createFsStore */\n  store: ObjectStore;\n  /** Here will go caching options... */\n}\n\n/** Server configuration options */\nexport type HttpServerOptions = {\n  /** HTTP(S) request handler function, @see HttpHelpers.createRequestHandler */\n  handler: RequestListener;\n  /** Port to bind to, @default 0 for auto-assignment */\n  port?: number;\n  /** Do not apply authorization middleware to @param handler */\n  noAuth?: true;\n  /** Downgrade default HTTPS server to plain HTTP, @warning use only for testing */\n  http?: true;\n};\n\n/**\n * Long unique opaque string for use in Bearer authorization header\n * \n * @example\n * ```ts\n * request.setHeader('Authorization', `Bearer ${authToken}`);\n * ```\n */\nexport type HttpAuthorizationToken = Branded<string, 'PFrameInternal.HttpAuthorizationToken'>;\n\n/**\n * TLS certificate in PEM format\n * \n * @example\n * ```txt\n * -----BEGIN CERTIFICATE-----\n * MIIC2zCCAcOgAwIBAgIJaVW7...\n * ...\n * ...Yf9CRK8fgnukKM7TJ\n * -----END CERTIFICATE-----\n * ```\n */\nexport type PemCertificate = Branded<string, 'PFrameInternal.PemCertificate'>;\n\n/** HTTP(S) server information and controls, @see HttpHelpers.createHttpServer */\nexport interface HttpServer {\n  /** Server address info formatted as `http{s}://<host>:<port>/` */\n  get address(): ObjectStoreUrl;\n  /** Authorization token for Bearer scheme, undefined when @see HttpServerOptions.noAuth flag is set */\n  get authToken(): HttpAuthorizationToken | undefined;\n  /** Base64-encoded CA certificate in PEM format, undefined when @see HttpServerOptions.http flag is set */\n  get encodedCaCert(): Base64Encoded<PemCertificate> | undefined;\n  /** Promise that resolves when the server is stopped */\n  get stopped(): Promise<void>;\n  /** Request server stop, returns the same promise as @see HttpServer.stopped */\n  stop(): Promise<void>;\n}\n\n/** List of HTTP(S) related helper functions exposed by PFrame module */\nexport interface HttpHelpers {\n  /**\n   * Create an object store for serving files from a local directory.\n   * Rejects if the provided path does not exist or is not a directory.\n   */\n  createFsStore(options: FsStoreOptions): Promise<ObjectStore>;\n\n  /**\n   * Create an HTTP request handler for serving files from an object store.\n   * Accepts only paths of the form `/<filename>.parquet`, returns 410 otherwise.\n   * Assumes that files are immutable (and sets cache headers accordingly).\n   */\n  createRequestHandler(options: RequestHandlerOptions): RequestListener;\n\n  /**\n   * Serve HTTP(S) requests using the provided handler on localhost port.\n   * @returns promise that resolves when the server has stopped.\n   *\n   * @example\n   * ```ts\n   * const rootDir = '/path/to/directory/with/parquet/files';\n   *\n   * let store = await HttpHelpers.createFsStore({ rootDir }).catch((err: unknown) => {\n   *   throw new Error(`Failed to create file store for ${rootDir} - ${ensureError(err)}`);\n   * });\n   *\n   * const server = await HttpHelpers.createHttpServer({\n   *   handler: HttpHelpers.createRequestHandler(store),\n   * }).catch((err: unknown) => {\n   *   throw new Error(`Failed to start HTTP server - ${ensureError(err)}`);\n   * });\n   *\n   * const { address, authToken, base64EncodedCaCert } = server;\n   *\n   * await server.stop();\n   * ```\n   */\n  createHttpServer(options: HttpServerOptions): Promise<HttpServer>;\n}\n"],"names":[],"mappings":";;AAwGA;MACsB,WAAW,CAAA;AACZ,IAAA,MAAM;AAEzB,IAAA,WAAA,CAAY,OAA2B,EAAA;AACrC,QAAA,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,MAAK,EAAE,CAAC,CAAC;IAC5C;;IAGU,SAAS,CAAC,QAAgB,EAAE,KAAiB,EAAA;AACrD,QAAA,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,EAAE;AAClD,QAAA,QAAQ,KAAK,CAAC,IAAI;AAChB,YAAA,KAAK,SAAS;AACZ,gBAAA,IAAI,KAAK,CAAC,GAAG,IAAI,QAAQ;AAAE,oBAAA,OAAO,IAAI;AACtC,gBAAA,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE;AAC/C,YAAA,KAAK,QAAQ;AACX,gBAAA,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ;AAAE,oBAAA,OAAO,IAAI;AACzC,gBAAA,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,EAAE;AACnD,YAAA,KAAK,QAAQ;AACX,gBAAA,IAAI,KAAK,CAAC,MAAM,GAAG,QAAQ;AAAE,oBAAA,OAAO,IAAI;AACxC,gBAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,EAAE;;IAElE;AAgBD;;;;"}

package/dist/pframe/internal_api/http_helpers.d.ts

@@ -1,70 +1,109 @@
 import type { Readable } from 'node:stream';
 import type { RequestListener } from 'node:http';
 import type { Branded, Base64Encoded } from '@milaboratories/pl-model-common';
-/** File range specification */
+import type { Logger } from './common';
+/** Parquet file name */
+export type ParquetFileName = Branded<`${string}.parquet`, 'PFrameInternal.ParquetFileName'>;
 export type FileRange = {
     /** Start byte position (inclusive) */
     start: number;
     /** End byte position (inclusive) */
     end: number;
 };
-/**
- * File system abstraction for request handler factory,
- * @see HttpHelpers.createRequestHandler.
- * Assumes that it is working with flat directory structure.
- * Accepts filenames with extension as input (e.g. `file.parquet`).
- */
-export interface ObjectStore {
+/** HTTP range as of RFC 9110 <https://datatracker.ietf.org/doc/html/rfc9110#name-range> */
+export type HttpRange = {
     /**
-     * @returns file size in bytes or `-1` if file does not exist or permissions do not allow access.
-     * @throws if file can become accessible after retry (e.g. on network error)
+     * Get file content in the specified byte range
      *
      * @example
-     * ```ts
-     * async getFileSize(filename: string): Promise<number> {
-     *   const filePath = this.resolve(filename);
-     *   return await fs
-     *     .stat(filePath)
-     *     .then((stat) => ({ size: stat.isFile() ? stat.size : -1 }))
-     *     .catch(() => ({ size: -1 }));
-     * }
+     * ```
+     * GET /file.parquet HTTP/1.1
+     * Range: bytes=0-1023
      * ```
      */
-    getFileSize(filename: string): Promise<number>;
+    type: 'bounded';
+    /** Start byte position (inclusive) */
+    start: number;
+    /** End byte position (inclusive) */
+    end: number;
+} | {
     /**
-     * Execute action with readable stream (actions can be concurrency limited by the store).
-     * Action resolves when stream is closed by handler @see HttpHelpers.createRequestHandler
-     *
-     * @param filename - existing file name (for which @see ObjectStore.getFileSize returned non-negative value)
-     * @param range - valid range of bytes to read from the file (store may skip validation)
-     * @param action - function to execute with the stream, responsible for closing the stream
-     * @returns promise that resolves after the action is completed
+     * Get byte range starting from the specified offset
      *
      * @example
-     * ```ts
-     * async withReadStream(params: {
-     *   filename: string;
-     *   range: FileRange;
-     *   action: (stream: Readable) => Promise<void>;
-     * }): Promise<void> {
-     *   const { filename, range, action } = params;
-     *   const filePath = this.resolve(filename);
+     * ```
+     * GET /file.parquet HTTP/1.1
+     * Range: bytes=1024-
+     * ```
+     */
+    type: 'offset';
+    /** Start byte position (inclusive) */
+    offset: number;
+} | {
+    /**
+     * Get byte range starting from the specified suffix
      *
-     *   try {
-     *     const stream = createReadStream(filePath, range);
-     *     return await action(stream);
-     *   } catch (err: unknown) {
-     *     console.error(`failed to create read stream for ${filename} - ${ensureError(err)}`);
-     *     throw;
-     *   }
-     * }
+     * @example
+     * ```
+     * GET /file.parquet HTTP/1.1
+     * Range: bytes=-1024
      * ```
      */
-    withReadStream(params: {
-        filename: string;
-        range: FileRange;
-        action: (stream: Readable) => Promise<void>;
-    }): Promise<void>;
+    type: 'suffix';
+    /** End byte position (inclusive) */
+    suffix: number;
+};
+/** HTTP method passed to object store */
+export type HttpMethod = 'GET' | 'HEAD';
+/** HTTP response from object store */
+export type ObjectStoreResponse = {
+    /** Will be translated to 500 Internal Server Error by the handler */
+    type: 'InternalError';
+} | {
+    /** Will be translated to 404 Not Found by the handler */
+    type: 'NotFound';
+} | {
+    /** Will be translated to 416 Range Not Satisfiable by the handler */
+    type: 'RangeNotSatisfiable';
+    /** Total file size in bytes */
+    size: number;
+} | {
+    /** Will be translated to 200 OK or 206 Partial Content by the handler */
+    type: 'Ok';
+    /** Total file size in bytes */
+    size: number;
+    /** File range translated from HTTP range */
+    range: FileRange;
+    /** Stream of file content, undefined for HEAD requests */
+    data?: Readable;
+};
+/** Common options for object store creation */
+export interface ObjectStoreOptions {
+    /** Logger instance, no logging is performed when not provided */
+    logger?: Logger;
+}
+/** Options for file system object store creation */
+export interface FsStoreOptions extends ObjectStoreOptions {
+    /** Local directory to serve files from */
+    rootDir: string;
+}
+/** File system abstraction for request handler factory, @see HttpHelpers.createRequestHandler */
+export declare abstract class ObjectStore {
+    protected readonly logger: Logger;
+    constructor(options: ObjectStoreOptions);
+    /** Translate HTTP range to file range, @returns null if the range is not satisfiable */
+    protected translate(fileSize: number, range?: HttpRange): FileRange | null;
+    /**
+     * Proxy HTTP(S) request for parquet file to object store.
+     * Callback promise resolves when stream is closed by handler @see HttpHelpers.createRequestHandler
+     * Callback API is used so that ObjectStore can limit the number of concurrent requests.
+     */
+    abstract request(filename: ParquetFileName, params: {
+        method: HttpMethod;
+        range?: HttpRange;
+        signal: AbortSignal;
+        callback: (response: ObjectStoreResponse) => Promise<void>;
+    }): void;
 }
 /** Object store base URL in format accepted by Apache DataFusion and DuckDB */
 export type ObjectStoreUrl = Branded<string, 'PFrameInternal.ObjectStoreUrl'>;
@@ -77,7 +116,7 @@ export type RequestHandlerOptions = {
 export type HttpServerOptions = {
     /** HTTP(S) request handler function, @see HttpHelpers.createRequestHandler */
     handler: RequestListener;
-    /** Port to bind to (@default 0 for auto-assignment) */
+    /** Port to bind to, @default 0 for auto-assignment */
     port?: number;
     /** Do not apply authorization middleware to @param handler */
     noAuth?: true;
@@ -125,7 +164,7 @@ export interface HttpHelpers {
      * Create an object store for serving files from a local directory.
      * Rejects if the provided path does not exist or is not a directory.
      */
-    createFsStore(rootDir: string): Promise<ObjectStore>;
+    createFsStore(options: FsStoreOptions): Promise<ObjectStore>;
     /**
      * Create an HTTP request handler for serving files from an object store.
      * Accepts only paths of the form `/<filename>.parquet`, returns 410 otherwise.
@@ -140,7 +179,7 @@ export interface HttpHelpers {
      * ```ts
      * const rootDir = '/path/to/directory/with/parquet/files';
      *
-     * let store = await HttpHelpers.createFsStore(rootDir).catch((err: unknown) => {
+     * let store = await HttpHelpers.createFsStore({ rootDir }).catch((err: unknown) => {
      *   throw new Error(`Failed to create file store for ${rootDir} - ${ensureError(err)}`);
      * });
      *

package/dist/pframe/internal_api/http_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http_helpers.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/http_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAE9E,+BAA+B;AAC/B,MAAM,MAAM,SAAS,GAAG;IACtB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,cAAc,CAAC,MAAM,EAAE;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,SAAS,CAAC;QACjB,MAAM,EAAE,CAAC,MAAM,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC7C,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC;AAE9E,+CAA+C;AAC/C,MAAM,MAAM,qBAAqB,GAAG;IAClC,uEAAuE;IACvE,KAAK,EAAE,WAAW,CAAC;CAEpB,CAAA;AAED,mCAAmC;AACnC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,eAAe,CAAC;IACzB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,kFAAkF;IAClF,IAAI,CAAC,EAAE,IAAI,CAAC;CACb,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,uCAAuC,CAAC,CAAC;AAE9F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC;AAE9E,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,IAAI,OAAO,IAAI,cAAc,CAAC;IAC9B,sGAAsG;IACtG,IAAI,SAAS,IAAI,sBAAsB,GAAG,SAAS,CAAC;IACpD,0GAA0G;IAC1G,IAAI,aAAa,IAAI,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAC/D,uDAAuD;IACvD,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,+EAA+E;IAC/E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAErD;;;;OAIG;IACH,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,CAAC;IAEtE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACnE"}
+{"version":3,"file":"http_helpers.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/http_helpers.ts"],"names":[],"mappings":"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"}

package/dist/pframe/internal_api/http_helpers.js

@@ -0,0 +1,29 @@
+/** File system abstraction for request handler factory, @see HttpHelpers.createRequestHandler */
+class ObjectStore {
+    logger;
+    constructor(options) {
+        this.logger = options.logger ?? (() => { });
+    }
+    /** Translate HTTP range to file range, @returns null if the range is not satisfiable */
+    translate(fileSize, range) {
+        if (!range)
+            return { start: 0, end: fileSize - 1 };
+        switch (range.type) {
+            case 'bounded':
+                if (range.end >= fileSize)
+                    return null;
+                return { start: range.start, end: range.end };
+            case 'offset':
+                if (range.offset >= fileSize)
+                    return null;
+                return { start: range.offset, end: fileSize - 1 };
+            case 'suffix':
+                if (range.suffix > fileSize)
+                    return null;
+                return { start: fileSize - range.suffix, end: fileSize - 1 };
+        }
+    }
+}
+
+export { ObjectStore };
+//# sourceMappingURL=http_helpers.js.map

package/dist/pframe/internal_api/http_helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http_helpers.js","sources":["../../../src/pframe/internal_api/http_helpers.ts"],"sourcesContent":["import type { Readable } from 'node:stream';\nimport type { RequestListener } from 'node:http';\nimport type { Branded, Base64Encoded } from '@milaboratories/pl-model-common';\nimport type { Logger } from './common';\n\n/** Parquet file name */\nexport type ParquetFileName = Branded<`${string}.parquet`, 'PFrameInternal.ParquetFileName'>;\n\nexport type FileRange = {\n  /** Start byte position (inclusive) */\n  start: number;\n  /** End byte position (inclusive) */\n  end: number;\n}\n\n/** HTTP range as of RFC 9110 <https://datatracker.ietf.org/doc/html/rfc9110#name-range> */\nexport type HttpRange =\n  | {\n      /**\n       * Get file content in the specified byte range\n       * \n       * @example\n       * ```\n       * GET /file.parquet HTTP/1.1\n       * Range: bytes=0-1023\n       * ```\n       */\n      type: 'bounded';\n      /** Start byte position (inclusive) */\n      start: number;\n      /** End byte position (inclusive) */\n      end: number;\n    }\n  | {\n      /**\n       * Get byte range starting from the specified offset\n       * \n       * @example\n       * ```\n       * GET /file.parquet HTTP/1.1\n       * Range: bytes=1024-\n       * ```\n       */\n      type: 'offset';\n      /** Start byte position (inclusive) */\n      offset: number;\n    }\n  | {\n      /**\n       * Get byte range starting from the specified suffix\n       * \n       * @example\n       * ```\n       * GET /file.parquet HTTP/1.1\n       * Range: bytes=-1024\n       * ```\n       */\n      type: 'suffix';\n      /** End byte position (inclusive) */\n      suffix: number;\n    };\n\n/** HTTP method passed to object store */\nexport type HttpMethod = 'GET' | 'HEAD';\n\n/** HTTP response from object store */\nexport type ObjectStoreResponse =\n  | {\n      /** Will be translated to 500 Internal Server Error by the handler */\n      type: 'InternalError';\n    }\n  | {\n      /** Will be translated to 404 Not Found by the handler */\n      type: 'NotFound';\n    }\n  | {\n      /** Will be translated to 416 Range Not Satisfiable by the handler */\n      type: 'RangeNotSatisfiable';\n      /** Total file size in bytes */\n      size: number;\n    }\n  | {\n      /** Will be translated to 200 OK or 206 Partial Content by the handler */\n      type: 'Ok';\n      /** Total file size in bytes */\n      size: number;\n      /** File range translated from HTTP range */\n      range: FileRange;\n      /** Stream of file content, undefined for HEAD requests */\n      data?: Readable;\n    }\n\n/** Common options for object store creation */\nexport interface ObjectStoreOptions {\n  /** Logger instance, no logging is performed when not provided */\n  logger?: Logger;\n}\n\n/** Options for file system object store creation */\nexport interface FsStoreOptions extends ObjectStoreOptions {\n  /** Local directory to serve files from */\n  rootDir: string;\n}\n\n/** File system abstraction for request handler factory, @see HttpHelpers.createRequestHandler */\nexport abstract class ObjectStore {\n  protected readonly logger: Logger;\n\n  constructor(options: ObjectStoreOptions) {\n    this.logger = options.logger ?? (() => {});\n  }\n\n  /** Translate HTTP range to file range, @returns null if the range is not satisfiable */\n  protected translate(fileSize: number, range?: HttpRange): FileRange | null {\n    if (!range) return { start: 0, end: fileSize - 1 };\n    switch (range.type) {\n      case 'bounded':\n        if (range.end >= fileSize) return null;\n        return { start: range.start, end: range.end };\n      case 'offset':\n        if (range.offset >= fileSize) return null;\n        return { start: range.offset, end: fileSize - 1 };\n      case 'suffix':\n        if (range.suffix > fileSize) return null;\n        return { start: fileSize - range.suffix, end: fileSize - 1 };\n    }\n  }\n\n  /**\n   * Proxy HTTP(S) request for parquet file to object store.\n   * Callback promise resolves when stream is closed by handler @see HttpHelpers.createRequestHandler\n   * Callback API is used so that ObjectStore can limit the number of concurrent requests.\n   */\n  abstract request(\n    filename: ParquetFileName,\n    params: {\n      method: HttpMethod;\n      range?: HttpRange;\n      signal: AbortSignal;\n      callback: (response: ObjectStoreResponse) => Promise<void>;\n    }\n  ): void;\n}\n\n/** Object store base URL in format accepted by Apache DataFusion and DuckDB */\nexport type ObjectStoreUrl = Branded<string, 'PFrameInternal.ObjectStoreUrl'>;\n\n/** HTTP(S) request handler creation options */\nexport type RequestHandlerOptions = {\n  /** Object store to serve files from, @see HttpHelpers.createFsStore */\n  store: ObjectStore;\n  /** Here will go caching options... */\n}\n\n/** Server configuration options */\nexport type HttpServerOptions = {\n  /** HTTP(S) request handler function, @see HttpHelpers.createRequestHandler */\n  handler: RequestListener;\n  /** Port to bind to, @default 0 for auto-assignment */\n  port?: number;\n  /** Do not apply authorization middleware to @param handler */\n  noAuth?: true;\n  /** Downgrade default HTTPS server to plain HTTP, @warning use only for testing */\n  http?: true;\n};\n\n/**\n * Long unique opaque string for use in Bearer authorization header\n * \n * @example\n * ```ts\n * request.setHeader('Authorization', `Bearer ${authToken}`);\n * ```\n */\nexport type HttpAuthorizationToken = Branded<string, 'PFrameInternal.HttpAuthorizationToken'>;\n\n/**\n * TLS certificate in PEM format\n * \n * @example\n * ```txt\n * -----BEGIN CERTIFICATE-----\n * MIIC2zCCAcOgAwIBAgIJaVW7...\n * ...\n * ...Yf9CRK8fgnukKM7TJ\n * -----END CERTIFICATE-----\n * ```\n */\nexport type PemCertificate = Branded<string, 'PFrameInternal.PemCertificate'>;\n\n/** HTTP(S) server information and controls, @see HttpHelpers.createHttpServer */\nexport interface HttpServer {\n  /** Server address info formatted as `http{s}://<host>:<port>/` */\n  get address(): ObjectStoreUrl;\n  /** Authorization token for Bearer scheme, undefined when @see HttpServerOptions.noAuth flag is set */\n  get authToken(): HttpAuthorizationToken | undefined;\n  /** Base64-encoded CA certificate in PEM format, undefined when @see HttpServerOptions.http flag is set */\n  get encodedCaCert(): Base64Encoded<PemCertificate> | undefined;\n  /** Promise that resolves when the server is stopped */\n  get stopped(): Promise<void>;\n  /** Request server stop, returns the same promise as @see HttpServer.stopped */\n  stop(): Promise<void>;\n}\n\n/** List of HTTP(S) related helper functions exposed by PFrame module */\nexport interface HttpHelpers {\n  /**\n   * Create an object store for serving files from a local directory.\n   * Rejects if the provided path does not exist or is not a directory.\n   */\n  createFsStore(options: FsStoreOptions): Promise<ObjectStore>;\n\n  /**\n   * Create an HTTP request handler for serving files from an object store.\n   * Accepts only paths of the form `/<filename>.parquet`, returns 410 otherwise.\n   * Assumes that files are immutable (and sets cache headers accordingly).\n   */\n  createRequestHandler(options: RequestHandlerOptions): RequestListener;\n\n  /**\n   * Serve HTTP(S) requests using the provided handler on localhost port.\n   * @returns promise that resolves when the server has stopped.\n   *\n   * @example\n   * ```ts\n   * const rootDir = '/path/to/directory/with/parquet/files';\n   *\n   * let store = await HttpHelpers.createFsStore({ rootDir }).catch((err: unknown) => {\n   *   throw new Error(`Failed to create file store for ${rootDir} - ${ensureError(err)}`);\n   * });\n   *\n   * const server = await HttpHelpers.createHttpServer({\n   *   handler: HttpHelpers.createRequestHandler(store),\n   * }).catch((err: unknown) => {\n   *   throw new Error(`Failed to start HTTP server - ${ensureError(err)}`);\n   * });\n   *\n   * const { address, authToken, base64EncodedCaCert } = server;\n   *\n   * await server.stop();\n   * ```\n   */\n  createHttpServer(options: HttpServerOptions): Promise<HttpServer>;\n}\n"],"names":[],"mappings":"AAwGA;MACsB,WAAW,CAAA;AACZ,IAAA,MAAM;AAEzB,IAAA,WAAA,CAAY,OAA2B,EAAA;AACrC,QAAA,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,MAAK,EAAE,CAAC,CAAC;IAC5C;;IAGU,SAAS,CAAC,QAAgB,EAAE,KAAiB,EAAA;AACrD,QAAA,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,EAAE;AAClD,QAAA,QAAQ,KAAK,CAAC,IAAI;AAChB,YAAA,KAAK,SAAS;AACZ,gBAAA,IAAI,KAAK,CAAC,GAAG,IAAI,QAAQ;AAAE,oBAAA,OAAO,IAAI;AACtC,gBAAA,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE;AAC/C,YAAA,KAAK,QAAQ;AACX,gBAAA,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ;AAAE,oBAAA,OAAO,IAAI;AACzC,gBAAA,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,EAAE;AACnD,YAAA,KAAK,QAAQ;AACX,gBAAA,IAAI,KAAK,CAAC,MAAM,GAAG,QAAQ;AAAE,oBAAA,OAAO,IAAI;AACxC,gBAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,EAAE;;IAElE;AAgBD;;;;"}

package/dist/pframe/internal_api/index.cjs

@@ -1,3 +1,8 @@
 'use strict';
 
+var http_helpers = require('./http_helpers.cjs');
+
+
+
+exports.ObjectStore = http_helpers.ObjectStore;
 //# sourceMappingURL=index.cjs.map

package/dist/pframe/internal_api/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;"}

package/dist/pframe/internal_api/index.js

@@ -1,2 +1,2 @@
-
+export { ObjectStore } from './http_helpers.js';
 //# sourceMappingURL=index.js.map

package/dist/pframe/internal_api/pframe.d.ts

@@ -1,6 +1,6 @@
 import type { PFrameFactoryAPIV2, PFrameFactoryAPIV3 } from './api_factory';
 import type { PFrameReadAPIV8, PFrameReadAPIV9 } from './api_read';
-export type Logger = (level: 'info' | 'warn' | 'error', message: string) => void;
+import type { Logger } from './common';
 export interface PFrameV9 extends PFrameFactoryAPIV2, PFrameReadAPIV8 {
 }
 export interface PFrameV10 extends PFrameFactoryAPIV3, PFrameReadAPIV9 {

package/dist/pframe/internal_api/pframe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pframe.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/pframe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,MAAM,MAAM,GAAG,CACnB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAChC,OAAO,EAAE,MAAM,KACZ,IAAI,CAAC;AAEV,MAAM,WAAW,QAAS,SAAQ,kBAAkB,EAAE,eAAe;CAAG;AAExE,MAAM,WAAW,SAAU,SAAQ,kBAAkB,EAAE,eAAe;CAAG;AAEzE,MAAM,MAAM,aAAa,GAAG;IAC1B,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAA;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;IAEhD;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;CACtC"}
+{"version":3,"file":"pframe.d.ts","sourceRoot":"","sources":["../../../src/pframe/internal_api/pframe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,WAAW,QAAS,SAAQ,kBAAkB,EAAE,eAAe;CAAG;AAExE,MAAM,WAAW,SAAU,SAAQ,kBAAkB,EAAE,eAAe;CAAG;AAEzE,MAAM,MAAM,aAAa,GAAG;IAC1B,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAA;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;IAEhD;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;CACtC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-model-middle-layer",
-  "version": "1.8.13",
+  "version": "1.8.15",
   "description": "Common model between middle layer and non-block UI code",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -25,8 +25,8 @@
   "devDependencies": {
     "typescript": "~5.6.3",
     "@milaboratories/build-configs": "1.0.8",
-    "@milaboratories/ts-configs": "1.0.6",
-    "@milaboratories/ts-builder": "1.0.5"
+    "@milaboratories/ts-builder": "1.0.5",
+    "@milaboratories/ts-configs": "1.0.6"
   },
   "scripts": {
     "type-check": "ts-builder types --target node",

package/src/pframe/internal_api/common.ts

@@ -1,4 +1,9 @@
-import { AxisId, AxisSpec, ValueType } from '@milaboratories/pl-model-common';
+import { AxisSpec, ValueType } from '@milaboratories/pl-model-common';
+
+export type Logger = (
+  level: 'info' | 'warn' | 'error',
+  message: string
+) => void;
 
 export interface SingleAxisSelector {
   name: string;

package/src/pframe/internal_api/http_helpers.ts

@@ -1,73 +1,145 @@
 import type { Readable } from 'node:stream';
 import type { RequestListener } from 'node:http';
 import type { Branded, Base64Encoded } from '@milaboratories/pl-model-common';
+import type { Logger } from './common';
+
+/** Parquet file name */
+export type ParquetFileName = Branded<`${string}.parquet`, 'PFrameInternal.ParquetFileName'>;
 
-/** File range specification */
 export type FileRange = {
   /** Start byte position (inclusive) */
   start: number;
   /** End byte position (inclusive) */
   end: number;
-};
+}
 
-/**
- * File system abstraction for request handler factory,
- * @see HttpHelpers.createRequestHandler.
- * Assumes that it is working with flat directory structure.
- * Accepts filenames with extension as input (e.g. `file.parquet`).
- */
-export interface ObjectStore {
-  /**
-   * @returns file size in bytes or `-1` if file does not exist or permissions do not allow access.
-   * @throws if file can become accessible after retry (e.g. on network error)
-   *
-   * @example
-   * ```ts
-   * async getFileSize(filename: string): Promise<number> {
-   *   const filePath = this.resolve(filename);
-   *   return await fs
-   *     .stat(filePath)
-   *     .then((stat) => ({ size: stat.isFile() ? stat.size : -1 }))
-   *     .catch(() => ({ size: -1 }));
-   * }
-   * ```
-   */
-  getFileSize(filename: string): Promise<number>;
+/** HTTP range as of RFC 9110 <https://datatracker.ietf.org/doc/html/rfc9110#name-range> */
+export type HttpRange =
+  | {
+      /**
+       * Get file content in the specified byte range
+       * 
+       * @example
+       * ```
+       * GET /file.parquet HTTP/1.1
+       * Range: bytes=0-1023
+       * ```
+       */
+      type: 'bounded';
+      /** Start byte position (inclusive) */
+      start: number;
+      /** End byte position (inclusive) */
+      end: number;
+    }
+  | {
+      /**
+       * Get byte range starting from the specified offset
+       * 
+       * @example
+       * ```
+       * GET /file.parquet HTTP/1.1
+       * Range: bytes=1024-
+       * ```
+       */
+      type: 'offset';
+      /** Start byte position (inclusive) */
+      offset: number;
+    }
+  | {
+      /**
+       * Get byte range starting from the specified suffix
+       * 
+       * @example
+       * ```
+       * GET /file.parquet HTTP/1.1
+       * Range: bytes=-1024
+       * ```
+       */
+      type: 'suffix';
+      /** End byte position (inclusive) */
+      suffix: number;
+    };
+
+/** HTTP method passed to object store */
+export type HttpMethod = 'GET' | 'HEAD';
+
+/** HTTP response from object store */
+export type ObjectStoreResponse =
+  | {
+      /** Will be translated to 500 Internal Server Error by the handler */
+      type: 'InternalError';
+    }
+  | {
+      /** Will be translated to 404 Not Found by the handler */
+      type: 'NotFound';
+    }
+  | {
+      /** Will be translated to 416 Range Not Satisfiable by the handler */
+      type: 'RangeNotSatisfiable';
+      /** Total file size in bytes */
+      size: number;
+    }
+  | {
+      /** Will be translated to 200 OK or 206 Partial Content by the handler */
+      type: 'Ok';
+      /** Total file size in bytes */
+      size: number;
+      /** File range translated from HTTP range */
+      range: FileRange;
+      /** Stream of file content, undefined for HEAD requests */
+      data?: Readable;
+    }
+
+/** Common options for object store creation */
+export interface ObjectStoreOptions {
+  /** Logger instance, no logging is performed when not provided */
+  logger?: Logger;
+}
+
+/** Options for file system object store creation */
+export interface FsStoreOptions extends ObjectStoreOptions {
+  /** Local directory to serve files from */
+  rootDir: string;
+}
+
+/** File system abstraction for request handler factory, @see HttpHelpers.createRequestHandler */
+export abstract class ObjectStore {
+  protected readonly logger: Logger;
+
+  constructor(options: ObjectStoreOptions) {
+    this.logger = options.logger ?? (() => {});
+  }
+
+  /** Translate HTTP range to file range, @returns null if the range is not satisfiable */
+  protected translate(fileSize: number, range?: HttpRange): FileRange | null {
+    if (!range) return { start: 0, end: fileSize - 1 };
+    switch (range.type) {
+      case 'bounded':
+        if (range.end >= fileSize) return null;
+        return { start: range.start, end: range.end };
+      case 'offset':
+        if (range.offset >= fileSize) return null;
+        return { start: range.offset, end: fileSize - 1 };
+      case 'suffix':
+        if (range.suffix > fileSize) return null;
+        return { start: fileSize - range.suffix, end: fileSize - 1 };
+    }
+  }
 
   /**
-   * Execute action with readable stream (actions can be concurrency limited by the store).
-   * Action resolves when stream is closed by handler @see HttpHelpers.createRequestHandler
-   * 
-   * @param filename - existing file name (for which @see ObjectStore.getFileSize returned non-negative value)
-   * @param range - valid range of bytes to read from the file (store may skip validation)
-   * @param action - function to execute with the stream, responsible for closing the stream
-   * @returns promise that resolves after the action is completed
-   *
-   * @example
-   * ```ts
-   * async withReadStream(params: {
-   *   filename: string;
-   *   range: FileRange;
-   *   action: (stream: Readable) => Promise<void>;
-   * }): Promise<void> {
-   *   const { filename, range, action } = params;
-   *   const filePath = this.resolve(filename);
-   *
-   *   try {
-   *     const stream = createReadStream(filePath, range);
-   *     return await action(stream);
-   *   } catch (err: unknown) {
-   *     console.error(`failed to create read stream for ${filename} - ${ensureError(err)}`);
-   *     throw;
-   *   }
-   * }
-   * ```
+   * Proxy HTTP(S) request for parquet file to object store.
+   * Callback promise resolves when stream is closed by handler @see HttpHelpers.createRequestHandler
+   * Callback API is used so that ObjectStore can limit the number of concurrent requests.
    */
-  withReadStream(params: {
-    filename: string;
-    range: FileRange;
-    action: (stream: Readable) => Promise<void>;
-  }): Promise<void>;
+  abstract request(
+    filename: ParquetFileName,
+    params: {
+      method: HttpMethod;
+      range?: HttpRange;
+      signal: AbortSignal;
+      callback: (response: ObjectStoreResponse) => Promise<void>;
+    }
+  ): void;
 }
 
 /** Object store base URL in format accepted by Apache DataFusion and DuckDB */
@@ -84,7 +156,7 @@ export type RequestHandlerOptions = {
 export type HttpServerOptions = {
   /** HTTP(S) request handler function, @see HttpHelpers.createRequestHandler */
   handler: RequestListener;
-  /** Port to bind to (@default 0 for auto-assignment) */
+  /** Port to bind to, @default 0 for auto-assignment */
   port?: number;
   /** Do not apply authorization middleware to @param handler */
   noAuth?: true;
@@ -136,7 +208,7 @@ export interface HttpHelpers {
    * Create an object store for serving files from a local directory.
    * Rejects if the provided path does not exist or is not a directory.
    */
-  createFsStore(rootDir: string): Promise<ObjectStore>;
+  createFsStore(options: FsStoreOptions): Promise<ObjectStore>;
 
   /**
    * Create an HTTP request handler for serving files from an object store.
@@ -153,7 +225,7 @@ export interface HttpHelpers {
    * ```ts
    * const rootDir = '/path/to/directory/with/parquet/files';
    *
-   * let store = await HttpHelpers.createFsStore(rootDir).catch((err: unknown) => {
+   * let store = await HttpHelpers.createFsStore({ rootDir }).catch((err: unknown) => {
    *   throw new Error(`Failed to create file store for ${rootDir} - ${ensureError(err)}`);
    * });
    *

package/src/pframe/internal_api/pframe.ts

@@ -1,10 +1,6 @@
 import type { PFrameFactoryAPIV2, PFrameFactoryAPIV3 } from './api_factory';
 import type { PFrameReadAPIV8, PFrameReadAPIV9 } from './api_read';
-
-export type Logger = (
-  level: 'info' | 'warn' | 'error',
-  message: string
-) => void;
+import type { Logger } from './common';
 
 export interface PFrameV9 extends PFrameFactoryAPIV2, PFrameReadAPIV8 {}