@milaboratories/pframes-rs-serv 1.0.68 → 1.0.69

package/dist/utils/status.d.ts

@@ -7,6 +7,7 @@ export declare const StatusCode: {
     readonly Unauthorized: 401;
     readonly NotFound: 404;
     readonly MethodNotAllowed: 405;
+    readonly RequestTimeout: 408;
     readonly Gone: 410;
     readonly PreconditionFailed: 412;
     readonly RangeNotSatisfiable: 416;

package/dist/utils/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/utils/status.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,eAAO,MAAM,UAAU;;;;;;;;;;;;;CAab,CAAC"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/utils/status.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,eAAO,MAAM,UAAU;;;;;;;;;;;;;;CAcb,CAAC"}

package/dist/utils/status.js

@@ -7,6 +7,7 @@ const StatusCode = {
     Unauthorized: 401, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401>
     NotFound: 404, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404>
     MethodNotAllowed: 405, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405>
+    RequestTimeout: 408, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408>
     Gone: 410, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410>
     PreconditionFailed: 412, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412>
     RangeNotSatisfiable: 416, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/416>

package/dist/utils/status.js.map

@@ -1 +1 @@
-{"version":3,"file":"status.js","sources":["../../src/utils/status.ts"],"sourcesContent":["/** HTTP status codes used in the parquet server handler */\nexport const StatusCode = {\n  Ok: 200, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200>\n  PartialContent: 206, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206>\n  NotModified: 304, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304>\n  BadRequest: 400, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400>\n  Unauthorized: 401, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401>\n  NotFound: 404, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404>\n  MethodNotAllowed: 405, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405>\n  Gone: 410, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410>\n  PreconditionFailed: 412, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412>\n  RangeNotSatisfiable: 416, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/416>\n  InternalServerError: 500, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500>\n  GatewayTimeout: 504 // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504>\n} as const;\n"],"names":[],"mappings":"AAAA;AACO,MAAM,UAAU,GAAG;IACxB,EAAE,EAAE,GAAG;IACP,cAAc,EAAE,GAAG;IACnB,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,GAAG;IACf,YAAY,EAAE,GAAG;IACjB,QAAQ,EAAE,GAAG;IACb,gBAAgB,EAAE,GAAG;IACrB,IAAI,EAAE,GAAG;IACT,kBAAkB,EAAE,GAAG;IACvB,mBAAmB,EAAE,GAAG;IACxB,mBAAmB,EAAE,GAAG;IACxB,cAAc,EAAE,GAAG;;;;;"}
+{"version":3,"file":"status.js","sources":["../../src/utils/status.ts"],"sourcesContent":["/** HTTP status codes used in the parquet server handler */\nexport const StatusCode = {\n  Ok: 200, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200>\n  PartialContent: 206, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206>\n  NotModified: 304, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304>\n  BadRequest: 400, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400>\n  Unauthorized: 401, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401>\n  NotFound: 404, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404>\n  MethodNotAllowed: 405, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405>\n  RequestTimeout: 408, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408>\n  Gone: 410, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410>\n  PreconditionFailed: 412, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412>\n  RangeNotSatisfiable: 416, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/416>\n  InternalServerError: 500, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500>\n  GatewayTimeout: 504 // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504>\n} as const;\n"],"names":[],"mappings":"AAAA;AACO,MAAM,UAAU,GAAG;IACxB,EAAE,EAAE,GAAG;IACP,cAAc,EAAE,GAAG;IACnB,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,GAAG;IACf,YAAY,EAAE,GAAG;IACjB,QAAQ,EAAE,GAAG;IACb,gBAAgB,EAAE,GAAG;IACrB,cAAc,EAAE,GAAG;IACnB,IAAI,EAAE,GAAG;IACT,kBAAkB,EAAE,GAAG;IACvB,mBAAmB,EAAE,GAAG;IACxB,mBAAmB,EAAE,GAAG;IACxB,cAAc,EAAE,GAAG;;;;;"}

package/package.json

@@ -8,7 +8,7 @@
     "proxy",
     "server"
   ],
-  "version": "1.0.68",
+  "version": "1.0.69",
   "type": "module",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
@@ -30,11 +30,12 @@
   "dependencies": {
     "@milaboratories/helpers": "1.6.22",
     "@milaboratories/pl-model-common": "1.19.14",
-    "@milaboratories/pl-model-middle-layer": "1.8.17",
+    "@milaboratories/pl-model-middle-layer": "1.8.21",
     "commander": "^14.0.0",
     "selfsigned": "^3.0.1"
   },
   "devDependencies": {
+    "@datadog/pprof": "^5.9.0",
     "@milaboratories/ts-builder": "1.0.5",
     "@milaboratories/ts-configs": "1.0.6",
     "@types/autocannon": "^7.12.7",
@@ -43,7 +44,7 @@
     "autocannon": "^8.0.0",
     "tslib": "^2.8.1",
     "typescript": "^5.9.2",
-    "undici": "^7.14.0",
+    "undici": "^7.15.0",
     "vite": "^7.1.3",
     "vitest": "^3.2.4"
   },

package/src/fs-store.ts

@@ -3,7 +3,7 @@ import { createReadStream } from 'node:fs';
 import { stat, open, type FileHandle } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { PFrameInternal } from '@milaboratories/pl-model-middle-layer';
-import { ensureError } from '@milaboratories/pl-model-common';
+import { ensureError, isAbortError } from '@milaboratories/pl-model-common';
 
 /** Object store for serving files from a local directory */
 export class FileSystemStore extends PFrameInternal.ObjectStore {
@@ -46,19 +46,20 @@ export class FileSystemStore extends PFrameInternal.ObjectStore {
       callback: (response: PFrameInternal.ObjectStoreResponse) => Promise<void>;
     }
   ): Promise<void> {
-    let file: FileHandle;
+    let file: FileHandle | undefined;
     try {
-      const path = join(this.rootDir, filename);
-      file = await open(path, 'r');
-    } catch (error: unknown) {
-      this.logger(
-        'error',
-        `File system store failed to open file ${filename}: ${ensureError(error)}`
-      );
-      return await params.callback({ type: 'NotFound' });
-    }
+      try {
+        const path = join(this.rootDir, filename);
+        file = await open(path, 'r');
+      } catch (error: unknown) {
+        this.logger(
+          'error',
+          `File system store failed to open file ${filename}: ${ensureError(error)}`
+        );
+        return await params.callback({ type: 'NotFound' });
+      }
+      params.signal.throwIfAborted();
 
-    try {
       let size: number;
       try {
         ({ size } = await file.stat());
@@ -69,6 +70,7 @@ export class FileSystemStore extends PFrameInternal.ObjectStore {
         );
         return await params.callback({ type: 'InternalError' });
       }
+      params.signal.throwIfAborted();
 
       const range = this.translate(size, params.range);
       if (!range) {
@@ -83,7 +85,6 @@ export class FileSystemStore extends PFrameInternal.ObjectStore {
       try {
         data = createReadStream('ignored', {
           fd: file.fd,
-          autoClose: false,
           start: range.start,
           end: range.end,
           signal: params.signal
@@ -100,11 +101,28 @@ export class FileSystemStore extends PFrameInternal.ObjectStore {
         return await params.callback({ type: 'InternalError' });
       }
 
-      return await params
-        .callback({ type: 'Ok', size, range, data })
-        .catch(() => {});
+      try {
+        return await params.callback({ type: 'Ok', size, range, data });
+      } catch (error: unknown) {
+        if (!isAbortError(error)) {
+          this.logger(
+            'error',
+            `File system store received unexpected rejection from callback: ${ensureError(error)}`
+          );
+        }
+      }
+    } catch (error: unknown) {
+      if (!isAbortError(error)) {
+        this.logger(
+          'error',
+          `File system store unhandled error: ${ensureError(error)}`
+        );
+      }
+      return await params.callback({ type: 'InternalError' });
     } finally {
-      await file.close();
+      await file?.close().catch(() => {
+        // already closed
+      });
     }
   }
 }

package/src/handler.ts

@@ -18,13 +18,14 @@ import {
   HeaderName,
   HeaderValue
 } from './utils';
+import { isAbortError } from '@milaboratories/pl-model-common';
 
 /** Main request handler for parquet files */
-async function handleRequest(
+function handleRequest(
   request: IncomingMessage,
   response: ServerResponse,
   store: PFrameInternal.ObjectStore
-): Promise<void> {
+): void {
   // RFC 9110 section 6.6.1: Date header should be present in all responses
   response.sendDate = true;
   // RFC 9110 section 8.6: Content-Length 0 as default for error responses
@@ -87,7 +88,11 @@ async function handleRequest(
     signal,
     // pipeline automatically destroys the streams if they were not gracefully closed
     callback: async (result) => {
-      if (response.destroyed) return void response.destroy();
+      if (request.destroyed) {
+        // request has timed out, close the connection
+        response.setHeader(HeaderName.Connection, HeaderValue.Connection);
+        return void response.writeHead(StatusCode.RequestTimeout).end();
+      }
 
       switch (result.type) {
         case 'InternalError':
@@ -131,11 +136,11 @@ async function handleRequest(
         return void response.end();
       }
 
-      return await pipeline(result.data!, response, { signal }).catch(() => {
-        // Pipeline errors are expected when request is aborted or connection is lost
-        // Response head was already written, so we can't change status code
-        // Just mute the error - pipeline destroys the response stream
-      });
+      try {
+        return await pipeline(result.data!, response, { signal });
+      } catch (error: unknown) {
+        if (!isAbortError(error)) throw error;
+      }
     }
   });
 }
@@ -153,7 +158,7 @@ export function createRequestHandler(
   options: PFrameInternal.RequestHandlerOptions
 ): RequestListener {
   const { store } = options;
-  return (request, response) => void handleRequest(request, response, store);
+  return (request, response) => handleRequest(request, response, store);
 }
 
 /** Request authorization middleware */

package/src/parquet-server.ts

@@ -2,23 +2,22 @@ import { type ChildProcess, spawn } from 'node:child_process';
 import { createInterface, type Interface } from 'node:readline/promises';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { Command } from 'commander';
-import { FileSystemStore } from './fs-store';
-import { createRequestHandler } from './handler';
-import { serve } from './serve';
+import { Command, InvalidArgumentError } from 'commander';
+import { HttpHelpers } from './export';
 import {
   parseJson,
-  type StringifiedJson,
-  stringifyJson
+  stringifyJson,
+  type StringifiedJson
 } from '@milaboratories/pl-model-common';
 import { type PFrameInternal } from '@milaboratories/pl-model-middle-layer';
 
 const Options = {
-  Http: '--http',
-  NoAuth: '--no-auth'
+  NoHttps: '--no-https',
+  NoAuth: '--no-auth',
+  Port: '--port'
 } as const;
 
-type Config = StringifiedJson<PFrameInternal.ParquetServerConfig>;
+type Info = StringifiedJson<PFrameInternal.HttpServerInfo>;
 
 /**
  * Serves parquet files from the given root directory.
@@ -31,17 +30,36 @@ export async function runParquetServer(): Promise<void> {
     .name('parquet-server')
     .description('Serve parquet files from a directory over HTTP(S)')
     .argument('<root-directory>', 'Root directory containing parquet files')
-    .option(Options.Http, 'Use HTTP instead of HTTPS', false)
-    .option(Options.NoAuth, 'Disable authentication')
+    .option(Options.NoHttps, 'Downgrade HTTPS to HTTP')
+    .option(Options.NoAuth, 'Disable authorization')
+    .option(
+      `${Options.Port} <number>`,
+      'Port to listen on',
+      (value) => {
+        const port = parseInt(value, 10);
+        if (isNaN(port) || port < 0 || port > 65535) {
+          throw new InvalidArgumentError('valid port numbers are 0-65535');
+        }
+        return port;
+      },
+      0
+    )
     .action(
-      async (rootDir: string, options: { http: boolean; auth: boolean }) => {
+      async (
+        rootDir: string,
+        options: {
+          https: boolean;
+          auth: boolean;
+          port: number;
+        }
+      ) => {
         const abortController = new AbortController();
         process
           .on('SIGINT', () => abortController.abort())
           .on('SIGTERM', () => abortController.abort());
         abortController.signal.throwIfAborted();
 
-        const store = await FileSystemStore.init({
+        const store = await HttpHelpers.createFsStore({
           rootDir,
           logger: (level, message) => {
             const timestamp = new Date(Date.now()).toISOString();
@@ -49,22 +67,19 @@ export async function runParquetServer(): Promise<void> {
           }
         });
         abortController.signal.throwIfAborted();
-        const handler = createRequestHandler({ store });
+        const handler = HttpHelpers.createRequestHandler({ store });
 
-        const server = await serve({
+        const server = await HttpHelpers.createHttpServer({
           handler,
-          ...(options.http && { http: true }),
-          ...(!options.auth && { noAuth: true })
+          ...(!options.https && { noHttps: true }),
+          ...(!options.auth && { noAuth: true }),
+          port: options.port
         });
         abortController.signal.onabort = () => server.stop();
         abortController.signal.throwIfAborted();
 
-        const serverConfig: Config = stringifyJson({
-          url: server.address,
-          ...(server.authToken && { authToken: server.authToken }),
-          ...(server.encodedCaCert && { caCert: server.encodedCaCert })
-        });
-        console.log(serverConfig);
+        const serverInfo: Info = stringifyJson(server.info);
+        console.log(serverInfo);
 
         await server.stopped;
       }
@@ -81,32 +96,32 @@ export async function runParquetServer(): Promise<void> {
  */
 export class ParquetServer implements Disposable {
   readonly #process: ChildProcess;
-  readonly #config: PFrameInternal.ParquetServerConfig;
+  readonly #info: PFrameInternal.HttpServerInfo;
   readonly #lineReader: Interface;
 
   private constructor(
     process: ChildProcess,
-    config: PFrameInternal.ParquetServerConfig,
+    info: PFrameInternal.HttpServerInfo,
     lineReader: Interface
   ) {
     this.#process = process;
-    this.#config = config;
+    this.#info = info;
     this.#lineReader = lineReader;
   }
 
-  get config(): PFrameInternal.ParquetServerConfig {
-    return this.#config;
+  get info(): PFrameInternal.HttpServerInfo {
+    return this.#info;
   }
 
   static async serve(
     rootDir: string,
     options?: {
-      http?: boolean;
-      noAuth?: boolean;
+      noHttps?: true;
+      noAuth?: true;
+      port?: number;
     }
   ): Promise<ParquetServer> {
-    const nodeFileUrl = import.meta.url;
-    const nodeDirname = dirname(fileURLToPath(nodeFileUrl));
+    const nodeDirname = dirname(fileURLToPath(import.meta.url));
     const binPath = join(nodeDirname, '..', 'bin', 'parquet-server.mjs');
 
     const serverProcess = spawn(
@@ -114,8 +129,9 @@ export class ParquetServer implements Disposable {
       [
         binPath,
         rootDir,
-        ...(options?.http ? [Options.Http] : []),
-        ...(options?.noAuth ? [Options.NoAuth] : [])
+        ...(options?.noHttps ? [Options.NoHttps] : []),
+        ...(options?.noAuth ? [Options.NoAuth] : []),
+        ...(options?.port ? [Options.Port, options.port.toString()] : [])
       ],
       {
         stdio: ['ignore', 'pipe', 'ignore']
@@ -125,11 +141,11 @@ export class ParquetServer implements Disposable {
     const lineReader = createInterface({ input: serverProcess.stdout! });
 
     const firstLine = await lineReader[Symbol.asyncIterator]().next();
-    const serverConfig = parseJson(firstLine.value as Config);
+    const serverInfo = parseJson(firstLine.value as Info);
 
     lineReader.on('line', console.log);
 
-    return new ParquetServer(serverProcess, serverConfig, lineReader);
+    return new ParquetServer(serverProcess, serverInfo, lineReader);
   }
 
   [Symbol.dispose](): void {

package/src/serve.ts

@@ -14,8 +14,7 @@ import type { PFrameInternal } from '@milaboratories/pl-model-middle-layer';
 import {
   base64Encode,
   Base64Encoded,
-  ensureError,
-  PFrameError
+  ensureError
 } from '@milaboratories/pl-model-common';
 import { generate, type GenerateResult } from 'selfsigned';
 import { randomUUID } from 'node:crypto';
@@ -54,18 +53,16 @@ async function generateCertificate(): Promise<GenerateResult> {
 /** Create an object store URL from the server address info. */
 function createObjectStoreUrl(
   info: AddressInfo,
-  http?: true
+  noHttps?: true
 ): PFrameInternal.ObjectStoreUrl {
-  const protocol = http ? 'http' : 'https';
+  const protocol = noHttps ? 'http' : 'https';
   switch (info.family) {
     case 'IPv4':
       return `${protocol}://${info.address}:${info.port}/` as PFrameInternal.ObjectStoreUrl;
     case 'IPv6':
       return `${protocol}://[${info.address}]:${info.port}/` as PFrameInternal.ObjectStoreUrl;
     default:
-      throw new PFrameError(
-        `PFrame helper HTTP(S) server bound to 'localhost' has unknown address family: ${info.family}`
-      );
+      return `${protocol}://localhost:${info.port}/` as PFrameInternal.ObjectStoreUrl;
   }
 }
 
@@ -76,7 +73,7 @@ function createObjectStoreUrl(
 export async function serve({
   handler,
   port = 0,
-  http,
+  noHttps,
   noAuth
 }: PFrameInternal.HttpServerOptions): Promise<PFrameInternal.HttpServer> {
   const started = new Deferred<PFrameInternal.HttpServer>();
@@ -91,52 +88,41 @@ export async function serve({
     }
 
     // Create HTTP server
-    let certificateBase64:
-      | Base64Encoded<PFrameInternal.PemCertificate>
-      | undefined;
+    let encodedCaCert: Base64Encoded<PFrameInternal.PemCertificate> | undefined;
     const defaultOptions: ServerOptions = {
       keepAlive: true
     };
     let server: HttpServer | HttpsServer;
 
-    if (http) {
+    if (noHttps) {
       server = createHttpServer(defaultOptions, effectiveHandler);
     } else {
       const { cert, private: key, public: ca } = await generateCertificate();
-      certificateBase64 = base64Encode(cert as PFrameInternal.PemCertificate);
+      encodedCaCert = base64Encode(cert as PFrameInternal.PemCertificate);
       server = createHttpsServer(
         { ...defaultOptions, cert, key, ca },
         effectiveHandler
       );
     }
 
-    const abortController = new AbortController();
     server
       .on('listening', () => {
         // Cast is safe by specification <https://nodejs.org/api/net.html#serveraddress>
-        const address = createObjectStoreUrl(
+        const url = createObjectStoreUrl(
           server.address() as AddressInfo,
-          http
+          noHttps
         );
         stopped = new Deferred<void>();
 
         started.resolve({
-          get address(): PFrameInternal.ObjectStoreUrl {
-            return address;
-          },
-          get authToken(): PFrameInternal.HttpAuthorizationToken | undefined {
-            return authToken;
-          },
-          get encodedCaCert():
-            | Base64Encoded<PFrameInternal.PemCertificate>
-            | undefined {
-            return certificateBase64;
+          get info(): PFrameInternal.HttpServerInfo {
+            return { url, authToken, encodedCaCert };
           },
           get stopped(): Promise<void> {
             return stopped!.promise;
           },
           stop(): Promise<void> {
-            abortController.abort();
+            server.close();
             return stopped!.promise;
           }
         });
@@ -148,8 +134,7 @@ export async function serve({
       .on('close', () => stopped?.resolve())
       .listen({
         host: 'localhost',
-        port,
-        signal: abortController.signal
+        port
       });
   } catch (error: unknown) {
     started.reject(ensureError(error));

package/src/utils/headers.ts

@@ -5,6 +5,7 @@ export const HeaderName = {
   Allow: 'allow',
   Authorization: 'authorization',
   CacheControl: 'cache-control',
+  Connection: 'connection',
   ContentLength: 'content-length',
   ContentRange: 'content-range',
   ContentType: 'content-type',
@@ -24,6 +25,7 @@ export const HeaderValue = {
   AcceptRanges: 'bytes',
   Allow: 'GET, HEAD',
   CacheControl: 'public, immutable, max-age=31536000',
+  Connection: 'close',
   ContentType: 'application/octet-stream',
   WWWAuthenticate: 'Bearer realm="parquet-server"'
 } as const;

package/src/utils/status.ts

@@ -7,6 +7,7 @@ export const StatusCode = {
   Unauthorized: 401, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401>
   NotFound: 404, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404>
   MethodNotAllowed: 405, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405>
+  RequestTimeout: 408, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408>
   Gone: 410, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410>
   PreconditionFailed: 412, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412>
   RangeNotSatisfiable: 416, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/416>