@milaboratories/pframes-rs-serv 1.0.64 → 1.0.67

package/README.md

@@ -4,15 +4,15 @@ A high-performance HTTP server for serving Parquet files with full RFC 9110 comp
 
 ## Overview
 
-This package provides HTTP server functionality for the PFrames ecosystem, specifically designed for serving Parquet files with proper HTTP semantics. It implements a complete HTTP/1.1 server that handles range requests, conditional requests, authentication, and caching according to web standards.
+This package provides HTTP(S) server functionality for the PFrames ecosystem, specifically designed for serving Parquet files with proper HTTP semantics. It implements a complete HTTP/1.1 server that handles range requests, conditional requests, Bearer token authentication, and range requests caching.
 
 ## Architecture
 
 ### Core Components
 
-- **Server** (`src/serve.ts`) - Generic HTTP server with lifecycle management
-- **HTTP Handler** (`src/handler.ts`) - RFC 9110 compliant HTTP request handler
-- **File System Store** (`src/fs-store.ts`) - Reader for local filesystem
+- **Server** (`src/serve.ts`) - Generic HTTP server with lifecycle management and optional authentication
+- **HTTP Handler** (`src/handler.ts`) - RFC 9110 compliant HTTP request handler with object store integration
+- **File System Store** (`src/fs-store.ts`) - Object store implementation for local filesystem
 
 ### Exports
 
@@ -22,17 +22,18 @@ This package provides HTTP server functionality for the PFrames ecosystem, speci
 - `createRequestHandler()` - HTTP request handler factory
 - `FileSystemStore` - Local file system object store implementation
 
-#### HttpHelpers (for re-export)
-
-The `HttpHelpers` export contains utility functions intended for re-export through the `@milaboratories/pframes-node` package and consumption by PFrameDriver in public monorepo:
+The `HttpHelpers` export contains functions intended for re-export through the `@milaboratories/pframes-rs-node` package.
 
 ### Binary Script
 
-The `bin/parquet-server.mjs` script is used by the `core` package tests via the `ParquetServer` helper class for integration testing. It provides a standalone server that can be spawned programmatically for testing HTTP compliance and file serving functionality.
+The `bin/parquet-server.mjs` script can be used for integration testing. It provides a standalone server that can be spawned programmatically and serve Parquet files over HTTP(S) from a local directory.
 
 ## HTTP Handler Flow
 
-The request handler implements a complete HTTP/1.1 server following [RFC 9110 (HTTP Semantics)](https://datatracker.ietf.org/doc/html/rfc9110) and [RFC 9111 (HTTP Caching)](https://datatracker.ietf.org/doc/html/rfc9111). Here's the detailed request processing flow:
+The request handler implements a complete HTTP/1.1 server following [RFC 9110 (HTTP Semantics)](https://datatracker.ietf.org/doc/html/rfc9110) and [RFC 9111 (HTTP Caching)](https://datatracker.ietf.org/doc/html/rfc9111). The handler consists of two layers:
+
+1. **Authorization Layer** (`authorizeRequestHandler`) - Optional Bearer token authentication
+2. **Core Handler** (`handleRequest`) - Main HTTP processing logic
 
 ## Request Processing Flow
 
@@ -48,25 +49,31 @@ The request handler implements a complete HTTP/1.1 server following [RFC 9110 (H
 └─────────┬───────────┘
           │
           ▼
-┌─────────────────────┐    [FAIL] No Token
-│ Check Authentication│────────────┐
+┌─────────────────────┐    [FAIL] Invalid/Missing Token
+│ Check Bearer Token  │────────────┐
+│ (Timing-Safe)       │            │
 └─────────┬───────────┘            │
-          │ [PASS] Authorized      │
-          ▼                        ▼
-┌─────────────────────┐    ┌──────────────┐
-│ Set Cache Headers   │    │ Return 401   │ ← WWW-Authenticate: Bearer
-└─────────┬───────────┘    │ Unauthorized │
-          │                └──────────────┘
+          │ [PASS] Valid Token     ▼
+          │                ┌──────────────┐
+          │                │ Return 401   │ ← WWW-Authenticate: Bearer
+          │                │ Unauthorized │
+          ▼                └──────────────┘
+┌─────────────────────┐
+│ Set Cache Control   │ ← Cache-Control: public, max-age=31536000
+│ Headers             │
+└─────────┬───────────┘
+          │
           ▼
 ┌─────────────────────┐    [FAIL] Not GET/HEAD
 │ Check HTTP Method   │────────────┐
 └─────────┬───────────┘            │
-          │ [PASS] Valid Method    │
+          │ [PASS] GET or HEAD     │
           ▼                        ▼
 ┌─────────────────────┐    ┌──────────────┐
-│ Parse URL           │    │ Return 405   │ ← Allow: GET, HEAD
-└─────────┬───────────┘    │ Not Allowed  │
-          │                └──────────────┘
+│ Parse URL &         │    │ Return 405   │ ← Allow: GET, HEAD
+│ Extract Filename    │    │ Not Allowed  │
+└─────────┬───────────┘    └──────────────┘
+          │
           ▼
 ┌─────────────────────┐    [FAIL] Invalid Pattern
 │ Validate .parquet   │────────────┐
@@ -75,68 +82,69 @@ The request handler implements a complete HTTP/1.1 server following [RFC 9110 (H
           │ [PASS] Valid .parquet  │
           ▼                        ▼
 ┌─────────────────────┐    ┌──────────────┐
-│ Set Content Headers │    │ Return 410   │ ← Permanently Gone
+│ Set Content Headers │    │ Return 410   │
 │ (Accept-Ranges,     │    │ Gone         │
-│  Content-Type)      │    └──────────────┘
+│  Content-Type),     │    └──────────────┘
+│ Generate ETag &     │ ← ETag from filename
+│ Set Cache Headers   │   Last-Modified: UTC(0)
 └─────────┬───────────┘
           │
           ▼
-┌─────────────────────┐    [FAIL] File Missing
-│ Check File Exists   │────────────┐
-└─────────┬───────────┘            │
-          │ [PASS] File Found      │
-          ▼                        ▼
-┌─────────────────────┐    ┌──────────────┐
-│ Generate ETag       │    │ Return 404   │ ← File Not Found
-│ Set ETag Header     │    │ Not Found    │
-└─────────┬───────────┘    └──────────────┘
-          │
-          ▼
 ┌─────────────────────┐    [FAIL] Precondition Failed
-│ Check If-Match      │────────────┐
-│ Conditional Headers │            │
+│ Check If-Match &    │────────────┐
+│ If-Unmodified-Since │            │
 └─────────┬───────────┘            │
-          │ [PASS] Conditions Met  │
+          │                        │
           ▼                        ▼
-┌─────────────────────┐    ┌──────────────┐
-│ Check If-None-Match │    │ Return 412   │ ← Precondition Failed
-└─────────┬───────────┘    │ Precondition │
-          │                │ Failed       │
-          ▼                └──────────────┘
+┌─────────────────────┐    ┌─────────────────────┐
+│ Check If-None-Match │    │ Return 412          │
+│ & If-Modified-Since │    │ Precondition Failed │
+└─────────┬───────────┘    └─────────────────────┘
           │ [FAIL] Not Modified
           ├────────────────────────┐
           │                        ▼
           │                ┌──────────────┐
-          │                │ Return 304   │ ← ETag, Not Modified
+          │                │ Return 304   │
           │                │ Not Modified │
           │                └──────────────┘
-          │ [PASS] Modified
-          ▼
-┌─────────────────────┐
-│ Parse Range Header  │
-└─────────┬───────────┘
-          │
           ▼
 ┌─────────────────────┐    [FAIL] Invalid Range
-│ Validate Range      │────────────┐
-│ Against File Size   │            │
+│ Parse Range Header  │────────────┐
 └─────────┬───────────┘            │
           │ [PASS] Valid Range     │
           ▼                        ▼
 ┌─────────────────────┐    ┌──────────────┐
-│ Set Status & Length │    │ Return 416   │ ← Content-Range: bytes */size
-│ 200 (full) or       │    │ Range Not    │
-│ 206 (partial)       │    │ Satisfiable  │
+│ Proxy Request to    │    │ Return 400   │
+│ Object Store        │    │ Bad Request  │
 └─────────┬───────────┘    └──────────────┘
+          │
+          ├─────────┬─────────┬─────────┐
+          │         │         │         │
+          ▼         ▼         ▼         ▼
+      ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
+      │  Ok   │ │  Not  │ │Invalid│ │ Server│
+      │Success│ │ Found │ │ Range │ │ Error │
+      └───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘
+          │         │         │         │
+          ▼         ▼         ▼         ▼
+      ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
+      │200/206│ │ 404   │ │ 416   │ │ 500   │
+      └───┬───┘ └───────┘ └───────┘ └───────┘
+          │
+          ▼
+┌─────────────────────┐
+│ Set Content-Length  │ ← Full size or range size
+│ & Content-Range     │   Content-Range for 206 responses
+└─────────┬───────────┘
           │
           ▼
-┌─────────────────────┐    [HEAD] Request
-│ Check Request Type  │────────────┐
+┌─────────────────────┐    [HEAD] Headers Only
+│ Check Request       │────────────┐
+│ Method              │            │
 └─────────┬───────────┘            │
-          │ [GET] Request          │
+          │ [GET] Send Body        │
           ▼                        ▼
 ┌─────────────────────┐    ┌──────────────┐
-│ Stream File Content │    │ Send Headers │ ← Headers Only
-│ (with range support)│    │ Only (HEAD)  │
+│ Stream File Content │    │ Send Headers │
 └─────────────────────┘    └──────────────┘
 ```

package/dist/handler.cjs

@@ -112,7 +112,7 @@ async function handleRequest(request, response, store) {
  * - <https://datatracker.ietf.org/doc/html/rfc9110>
  * - <https://datatracker.ietf.org/doc/html/rfc9111>
  *
- * Accepts only paths of the form `/<filename>.parquet`, returns 404 otherwise
+ * Accepts only paths of the form `/<filename>.parquet`, returns 410 Gone otherwise
  * Assumes that files are immutable (and sets cache headers accordingly)
  */
 function createRequestHandler(options) {
@@ -127,7 +127,7 @@ function authorizeRequest(request, response, handler, authHeader) {
     response.strictContentLength = true;
     response.setHeader(headers.HeaderName.ContentLength, 0);
     // Note: setting Content-Length disables Node.js default Transfer-Encoding: chunked
-    const actualHeader = request.headers['authorization'];
+    const actualHeader = request.headers[headers.HeaderName.Authorization];
     // Early length check to avoid unnecessary processing
     if (!actualHeader || actualHeader.length !== authHeader.length) {
         // RFC 9110 section 11.6.1: WWW-Authenticate header field

package/dist/handler.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"handler.cjs","sources":["../src/handler.ts"],"sourcesContent":["import type {\n  IncomingMessage,\n  RequestListener,\n  ServerResponse\n} from 'node:http';\nimport { pipeline } from 'node:stream/promises';\nimport { timingSafeEqual } from 'node:crypto';\nimport type { PFrameInternal } from '@milaboratories/pl-model-middle-layer';\nimport {\n  createETag,\n  getFilenameFromUrl,\n  parseRange,\n  isGetOrHead,\n  isHead,\n  Options,\n  StatusCode,\n  HeaderName,\n  HeaderValue,\n  isGet\n} from './utils';\n\n/** Main request handler for parquet files */\nasync function handleRequest(\n  request: IncomingMessage,\n  response: ServerResponse,\n  store: PFrameInternal.ObjectStore\n): Promise<void> {\n  // RFC 9110 section 6.6.1: Date header should be present in all responses\n  response.sendDate = true;\n  // RFC 9110 section 8.6: Content-Length 0 as default for error responses\n  response.strictContentLength = true;\n  response.setHeader(HeaderName.ContentLength, 0);\n  // Note: setting Content-Length disables Node.js default Transfer-Encoding: chunked\n\n  // RFC 9111 section 5.2: Cache-Control header with public allows to cache authenticated responses\n  response.setHeader(HeaderName.CacheControl, HeaderValue.CacheControl);\n\n  // RFC 9110 section 15.5.6: Method not allowed\n  const method = request.method;\n  if (!isGetOrHead(method)) {\n    response.setHeader(HeaderName.Allow, HeaderValue.Allow);\n    return void response.writeHead(StatusCode.MethodNotAllowed).end();\n  }\n\n  const filename = getFilenameFromUrl(request);\n  if (filename === null) {\n    return void response.writeHead(StatusCode.Gone).end();\n  }\n\n  // From now on we are sure that the response would be a Parquet file\n  response.setHeader(HeaderName.AcceptRanges, HeaderValue.AcceptRanges);\n  response.setHeader(HeaderName.ContentType, HeaderValue.ContentType);\n\n  // RFC 9110 section 8.8.3: ETag header is used for cache versioning\n  const etag = createETag(filename);\n  // RFC 9110 section 8.8.2: Last-Modified header field for cache validation\n  const mtime = new Date(0); // Using fake fixed date since files are immutable\n  // RFC 9111 section 5.2: Cache-Control header with public allows to cache authenticated responses\n  response.setHeader(HeaderName.CacheControl, HeaderValue.CacheControl);\n  response.setHeader(HeaderName.ETag, etag);\n  response.setHeader(HeaderName.LastModified, mtime.toUTCString());\n\n  const options = new Options(request);\n  // RFC 9110 section 13.1.1: If-Match precondition evaluation\n  // RFC 9110 section 13.1.4: If-Unmodified-Since precondition evaluation\n  if (options.preconditionFailed(etag, mtime)) {\n    return void response.writeHead(StatusCode.PreconditionFailed).end();\n  }\n  // RFC 9110 section 13.1.2: If-None-Match precondition evaluation\n  // RFC 9110 section 13.1.3: If-Modified-Since precondition evaluation\n  else if (options.notModified(etag, mtime)) {\n    return void response.writeHead(StatusCode.NotModified).end();\n  }\n\n  const range = parseRange(request);\n  if (range === null) {\n    return void response.writeHead(StatusCode.BadRequest).end();\n  }\n\n  const abortController = new AbortController();\n  request.on('close', () => abortController.abort());\n  const signal = abortController.signal;\n\n  store.request(filename, {\n    method: 'GET',\n    range,\n    signal,\n    // pipeline automatically destroys the streams if they were not gracefully closed\n    callback: async (result) => {\n      if (response.destroyed) return void response.destroy();\n\n      switch (result.type) {\n        case 'InternalError':\n          // object store encountered network error, retry by client can help\n          return void response.writeHead(StatusCode.InternalServerError).end();\n        case 'NotFound':\n          // RFC 9110 section 15.4.5: Not found\n          return void response.writeHead(StatusCode.NotFound).end();\n        case 'RangeNotSatisfiable':\n          // RFC 9110 section 15.5.17: Range not satisfiable\n          response.setHeader(HeaderName.ContentRange, `bytes */${result.size}`);\n          return void response.writeHead(StatusCode.RangeNotSatisfiable).end();\n        case 'Ok':\n          break;\n      }\n\n      if (isGet(method) && !result.data) {\n        // object store implementation is incorrect, retry by client cannot help\n        return void response.writeHead(StatusCode.GatewayTimeout).end();\n      }\n\n      if (range) {\n        // RFC 9110 section 14.4: Partial content response\n        response.setHeader(\n          HeaderName.ContentLength,\n          result.range.end - result.range.start + 1\n        );\n        response.setHeader(\n          HeaderName.ContentRange,\n          `bytes ${result.range.start}-${result.range.end}/${result.size}`\n        );\n        response.writeHead(StatusCode.PartialContent);\n      } else {\n        // RFC 9110 section 15.3.1: OK response\n        response.setHeader(HeaderName.ContentLength, result.size);\n        response.writeHead(StatusCode.Ok);\n      }\n\n      // RFC 9110 section 9.3.2: HEAD method must not return message body\n      if (isHead(method)) {\n        return void response.end();\n      }\n\n      return await pipeline(result.data!, response, { signal }).catch(() => {\n        // Pipeline errors are expected when request is aborted or connection is lost\n        // Response head was already written, so we can't change status code\n        // Just mute the error - pipeline destroys the response stream\n      });\n    }\n  });\n}\n\n/**\n * Create a request handler for serving files from an object store\n * compatible with HTTP/1.1 as defined in RFC 9110 and RFC 9111:\n * - <https://datatracker.ietf.org/doc/html/rfc9110>\n * - <https://datatracker.ietf.org/doc/html/rfc9111>\n *\n * Accepts only paths of the form `/<filename>.parquet`, returns 404 otherwise\n * Assumes that files are immutable (and sets cache headers accordingly)\n */\nexport function createRequestHandler(\n  options: PFrameInternal.RequestHandlerOptions\n): RequestListener {\n  const { store } = options;\n  return (request, response) => void handleRequest(request, response, store);\n}\n\n/** Request authorization middleware */\nfunction authorizeRequest(\n  request: IncomingMessage,\n  response: ServerResponse,\n  handler: RequestListener,\n  authHeader: string\n): void {\n  // RFC 9110 section 6.6.1: Date header should be present in all responses\n  response.sendDate = true;\n  // RFC 9110 section 8.6: Content-Length 0 as default for error responses\n  response.strictContentLength = true;\n  response.setHeader(HeaderName.ContentLength, 0);\n  // Note: setting Content-Length disables Node.js default Transfer-Encoding: chunked\n\n  const actualHeader = request.headers['authorization'];\n\n  // Early length check to avoid unnecessary processing\n  if (!actualHeader || actualHeader.length !== authHeader.length) {\n    // RFC 9110 section 11.6.1: WWW-Authenticate header field\n    response.setHeader(HeaderName.WWWAuthenticate, HeaderValue.WWWAuthenticate);\n    return void response.writeHead(StatusCode.Unauthorized).end();\n  }\n\n  // Use timing-safe comparison to prevent timing attacks\n  // <https://developers.cloudflare.com/workers/examples/protect-against-timing-attacks/>\n  const encoder = new TextEncoder();\n  const receivedBuffer = encoder.encode(actualHeader);\n  const expectedBuffer = encoder.encode(authHeader);\n\n  if (\n    receivedBuffer.byteLength !== expectedBuffer.byteLength ||\n    !timingSafeEqual(receivedBuffer, expectedBuffer)\n  ) {\n    response.setHeader(HeaderName.WWWAuthenticate, HeaderValue.WWWAuthenticate);\n    return void response.writeHead(StatusCode.Unauthorized).end();\n  }\n\n  return handler(request, response);\n}\n\n/** Apply Bearer token authorization to @param handler */\nexport function authorizeRequestHandler(\n  handler: RequestListener,\n  authToken: PFrameInternal.HttpAuthorizationToken\n): RequestListener {\n  const authHeader = `Bearer ${authToken}`;\n  return (request, response) =>\n    authorizeRequest(request, response, handler, authHeader);\n}\n"],"names":["HeaderName","HeaderValue","method","isGetOrHead","StatusCode","filename","getFilenameFromUrl","etag","createETag","options","Options","range","parseRange","isGet","isHead","pipeline","timingSafeEqual"],"mappings":"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"}
+{"version":3,"file":"handler.cjs","sources":["../src/handler.ts"],"sourcesContent":["import type {\n  IncomingMessage,\n  RequestListener,\n  ServerResponse\n} from 'node:http';\nimport { pipeline } from 'node:stream/promises';\nimport { timingSafeEqual } from 'node:crypto';\nimport type { PFrameInternal } from '@milaboratories/pl-model-middle-layer';\nimport {\n  createETag,\n  getFilenameFromUrl,\n  parseRange,\n  isGetOrHead,\n  isGet,\n  isHead,\n  Options,\n  StatusCode,\n  HeaderName,\n  HeaderValue\n} from './utils';\n\n/** Main request handler for parquet files */\nasync function handleRequest(\n  request: IncomingMessage,\n  response: ServerResponse,\n  store: PFrameInternal.ObjectStore\n): Promise<void> {\n  // RFC 9110 section 6.6.1: Date header should be present in all responses\n  response.sendDate = true;\n  // RFC 9110 section 8.6: Content-Length 0 as default for error responses\n  response.strictContentLength = true;\n  response.setHeader(HeaderName.ContentLength, 0);\n  // Note: setting Content-Length disables Node.js default Transfer-Encoding: chunked\n\n  // RFC 9111 section 5.2: Cache-Control header with public allows to cache authenticated responses\n  response.setHeader(HeaderName.CacheControl, HeaderValue.CacheControl);\n\n  // RFC 9110 section 15.5.6: Method not allowed\n  const method = request.method;\n  if (!isGetOrHead(method)) {\n    response.setHeader(HeaderName.Allow, HeaderValue.Allow);\n    return void response.writeHead(StatusCode.MethodNotAllowed).end();\n  }\n\n  const filename = getFilenameFromUrl(request);\n  if (filename === null) {\n    return void response.writeHead(StatusCode.Gone).end();\n  }\n\n  // From now on we are sure that the response would be a Parquet file\n  response.setHeader(HeaderName.AcceptRanges, HeaderValue.AcceptRanges);\n  response.setHeader(HeaderName.ContentType, HeaderValue.ContentType);\n\n  // RFC 9110 section 8.8.3: ETag header is used for cache versioning\n  const etag = createETag(filename);\n  // RFC 9110 section 8.8.2: Last-Modified header field for cache validation\n  const mtime = new Date(0); // Using fake fixed date since files are immutable\n  // RFC 9111 section 5.2: Cache-Control header with public allows to cache authenticated responses\n  response.setHeader(HeaderName.CacheControl, HeaderValue.CacheControl);\n  response.setHeader(HeaderName.ETag, etag);\n  response.setHeader(HeaderName.LastModified, mtime.toUTCString());\n\n  const options = new Options(request);\n  // RFC 9110 section 13.1.1: If-Match precondition evaluation\n  // RFC 9110 section 13.1.4: If-Unmodified-Since precondition evaluation\n  if (options.preconditionFailed(etag, mtime)) {\n    return void response.writeHead(StatusCode.PreconditionFailed).end();\n  }\n  // RFC 9110 section 13.1.2: If-None-Match precondition evaluation\n  // RFC 9110 section 13.1.3: If-Modified-Since precondition evaluation\n  else if (options.notModified(etag, mtime)) {\n    return void response.writeHead(StatusCode.NotModified).end();\n  }\n\n  const range = parseRange(request);\n  if (range === null) {\n    return void response.writeHead(StatusCode.BadRequest).end();\n  }\n\n  const abortController = new AbortController();\n  request.on('close', () => abortController.abort());\n  const signal = abortController.signal;\n\n  store.request(filename, {\n    method: 'GET',\n    range,\n    signal,\n    // pipeline automatically destroys the streams if they were not gracefully closed\n    callback: async (result) => {\n      if (response.destroyed) return void response.destroy();\n\n      switch (result.type) {\n        case 'InternalError':\n          // object store encountered network error, retry by client can help\n          return void response.writeHead(StatusCode.InternalServerError).end();\n        case 'NotFound':\n          // RFC 9110 section 15.4.5: Not found\n          return void response.writeHead(StatusCode.NotFound).end();\n        case 'RangeNotSatisfiable':\n          // RFC 9110 section 15.5.17: Range not satisfiable\n          response.setHeader(HeaderName.ContentRange, `bytes */${result.size}`);\n          return void response.writeHead(StatusCode.RangeNotSatisfiable).end();\n        case 'Ok':\n          break;\n      }\n\n      if (isGet(method) && !result.data) {\n        // object store implementation is incorrect, retry by client cannot help\n        return void response.writeHead(StatusCode.GatewayTimeout).end();\n      }\n\n      if (range) {\n        // RFC 9110 section 14.4: Partial content response\n        response.setHeader(\n          HeaderName.ContentLength,\n          result.range.end - result.range.start + 1\n        );\n        response.setHeader(\n          HeaderName.ContentRange,\n          `bytes ${result.range.start}-${result.range.end}/${result.size}`\n        );\n        response.writeHead(StatusCode.PartialContent);\n      } else {\n        // RFC 9110 section 15.3.1: OK response\n        response.setHeader(HeaderName.ContentLength, result.size);\n        response.writeHead(StatusCode.Ok);\n      }\n\n      // RFC 9110 section 9.3.2: HEAD method must not return message body\n      if (isHead(method)) {\n        return void response.end();\n      }\n\n      return await pipeline(result.data!, response, { signal }).catch(() => {\n        // Pipeline errors are expected when request is aborted or connection is lost\n        // Response head was already written, so we can't change status code\n        // Just mute the error - pipeline destroys the response stream\n      });\n    }\n  });\n}\n\n/**\n * Create a request handler for serving files from an object store\n * compatible with HTTP/1.1 as defined in RFC 9110 and RFC 9111:\n * - <https://datatracker.ietf.org/doc/html/rfc9110>\n * - <https://datatracker.ietf.org/doc/html/rfc9111>\n *\n * Accepts only paths of the form `/<filename>.parquet`, returns 410 Gone otherwise\n * Assumes that files are immutable (and sets cache headers accordingly)\n */\nexport function createRequestHandler(\n  options: PFrameInternal.RequestHandlerOptions\n): RequestListener {\n  const { store } = options;\n  return (request, response) => void handleRequest(request, response, store);\n}\n\n/** Request authorization middleware */\nfunction authorizeRequest(\n  request: IncomingMessage,\n  response: ServerResponse,\n  handler: RequestListener,\n  authHeader: string\n): void {\n  // RFC 9110 section 6.6.1: Date header should be present in all responses\n  response.sendDate = true;\n  // RFC 9110 section 8.6: Content-Length 0 as default for error responses\n  response.strictContentLength = true;\n  response.setHeader(HeaderName.ContentLength, 0);\n  // Note: setting Content-Length disables Node.js default Transfer-Encoding: chunked\n\n  const actualHeader = request.headers[HeaderName.Authorization];\n\n  // Early length check to avoid unnecessary processing\n  if (!actualHeader || actualHeader.length !== authHeader.length) {\n    // RFC 9110 section 11.6.1: WWW-Authenticate header field\n    response.setHeader(HeaderName.WWWAuthenticate, HeaderValue.WWWAuthenticate);\n    return void response.writeHead(StatusCode.Unauthorized).end();\n  }\n\n  // Use timing-safe comparison to prevent timing attacks\n  // <https://developers.cloudflare.com/workers/examples/protect-against-timing-attacks/>\n  const encoder = new TextEncoder();\n  const receivedBuffer = encoder.encode(actualHeader);\n  const expectedBuffer = encoder.encode(authHeader);\n\n  if (\n    receivedBuffer.byteLength !== expectedBuffer.byteLength ||\n    !timingSafeEqual(receivedBuffer, expectedBuffer)\n  ) {\n    response.setHeader(HeaderName.WWWAuthenticate, HeaderValue.WWWAuthenticate);\n    return void response.writeHead(StatusCode.Unauthorized).end();\n  }\n\n  return handler(request, response);\n}\n\n/** Apply Bearer token authorization to @param handler */\nexport function authorizeRequestHandler(\n  handler: RequestListener,\n  authToken: PFrameInternal.HttpAuthorizationToken\n): RequestListener {\n  const authHeader = `Bearer ${authToken}`;\n  return (request, response) =>\n    authorizeRequest(request, response, handler, authHeader);\n}\n"],"names":["HeaderName","HeaderValue","method","isGetOrHead","StatusCode","filename","getFilenameFromUrl","etag","createETag","options","Options","range","parseRange","isGet","isHead","pipeline","timingSafeEqual"],"mappings":"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"}

package/dist/handler.d.ts

@@ -6,7 +6,7 @@ import type { PFrameInternal } from '@milaboratories/pl-model-middle-layer';
  * - <https://datatracker.ietf.org/doc/html/rfc9110>
  * - <https://datatracker.ietf.org/doc/html/rfc9111>
  *
- * Accepts only paths of the form `/<filename>.parquet`, returns 404 otherwise
+ * Accepts only paths of the form `/<filename>.parquet`, returns 410 Gone otherwise
  * Assumes that files are immutable (and sets cache headers accordingly)
  */
 export declare function createRequestHandler(options: PFrameInternal.RequestHandlerOptions): RequestListener;

package/dist/handler.js

@@ -110,7 +110,7 @@ async function handleRequest(request, response, store) {
  * - <https://datatracker.ietf.org/doc/html/rfc9110>
  * - <https://datatracker.ietf.org/doc/html/rfc9111>
  *
- * Accepts only paths of the form `/<filename>.parquet`, returns 404 otherwise
+ * Accepts only paths of the form `/<filename>.parquet`, returns 410 Gone otherwise
  * Assumes that files are immutable (and sets cache headers accordingly)
  */
 function createRequestHandler(options) {
@@ -125,7 +125,7 @@ function authorizeRequest(request, response, handler, authHeader) {
     response.strictContentLength = true;
     response.setHeader(HeaderName.ContentLength, 0);
     // Note: setting Content-Length disables Node.js default Transfer-Encoding: chunked
-    const actualHeader = request.headers['authorization'];
+    const actualHeader = request.headers[HeaderName.Authorization];
     // Early length check to avoid unnecessary processing
     if (!actualHeader || actualHeader.length !== authHeader.length) {
         // RFC 9110 section 11.6.1: WWW-Authenticate header field

package/dist/handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"handler.js","sources":["../src/handler.ts"],"sourcesContent":["import type {\n  IncomingMessage,\n  RequestListener,\n  ServerResponse\n} from 'node:http';\nimport { pipeline } from 'node:stream/promises';\nimport { timingSafeEqual } from 'node:crypto';\nimport type { PFrameInternal } from '@milaboratories/pl-model-middle-layer';\nimport {\n  createETag,\n  getFilenameFromUrl,\n  parseRange,\n  isGetOrHead,\n  isHead,\n  Options,\n  StatusCode,\n  HeaderName,\n  HeaderValue,\n  isGet\n} from './utils';\n\n/** Main request handler for parquet files */\nasync function handleRequest(\n  request: IncomingMessage,\n  response: ServerResponse,\n  store: PFrameInternal.ObjectStore\n): Promise<void> {\n  // RFC 9110 section 6.6.1: Date header should be present in all responses\n  response.sendDate = true;\n  // RFC 9110 section 8.6: Content-Length 0 as default for error responses\n  response.strictContentLength = true;\n  response.setHeader(HeaderName.ContentLength, 0);\n  // Note: setting Content-Length disables Node.js default Transfer-Encoding: chunked\n\n  // RFC 9111 section 5.2: Cache-Control header with public allows to cache authenticated responses\n  response.setHeader(HeaderName.CacheControl, HeaderValue.CacheControl);\n\n  // RFC 9110 section 15.5.6: Method not allowed\n  const method = request.method;\n  if (!isGetOrHead(method)) {\n    response.setHeader(HeaderName.Allow, HeaderValue.Allow);\n    return void response.writeHead(StatusCode.MethodNotAllowed).end();\n  }\n\n  const filename = getFilenameFromUrl(request);\n  if (filename === null) {\n    return void response.writeHead(StatusCode.Gone).end();\n  }\n\n  // From now on we are sure that the response would be a Parquet file\n  response.setHeader(HeaderName.AcceptRanges, HeaderValue.AcceptRanges);\n  response.setHeader(HeaderName.ContentType, HeaderValue.ContentType);\n\n  // RFC 9110 section 8.8.3: ETag header is used for cache versioning\n  const etag = createETag(filename);\n  // RFC 9110 section 8.8.2: Last-Modified header field for cache validation\n  const mtime = new Date(0); // Using fake fixed date since files are immutable\n  // RFC 9111 section 5.2: Cache-Control header with public allows to cache authenticated responses\n  response.setHeader(HeaderName.CacheControl, HeaderValue.CacheControl);\n  response.setHeader(HeaderName.ETag, etag);\n  response.setHeader(HeaderName.LastModified, mtime.toUTCString());\n\n  const options = new Options(request);\n  // RFC 9110 section 13.1.1: If-Match precondition evaluation\n  // RFC 9110 section 13.1.4: If-Unmodified-Since precondition evaluation\n  if (options.preconditionFailed(etag, mtime)) {\n    return void response.writeHead(StatusCode.PreconditionFailed).end();\n  }\n  // RFC 9110 section 13.1.2: If-None-Match precondition evaluation\n  // RFC 9110 section 13.1.3: If-Modified-Since precondition evaluation\n  else if (options.notModified(etag, mtime)) {\n    return void response.writeHead(StatusCode.NotModified).end();\n  }\n\n  const range = parseRange(request);\n  if (range === null) {\n    return void response.writeHead(StatusCode.BadRequest).end();\n  }\n\n  const abortController = new AbortController();\n  request.on('close', () => abortController.abort());\n  const signal = abortController.signal;\n\n  store.request(filename, {\n    method: 'GET',\n    range,\n    signal,\n    // pipeline automatically destroys the streams if they were not gracefully closed\n    callback: async (result) => {\n      if (response.destroyed) return void response.destroy();\n\n      switch (result.type) {\n        case 'InternalError':\n          // object store encountered network error, retry by client can help\n          return void response.writeHead(StatusCode.InternalServerError).end();\n        case 'NotFound':\n          // RFC 9110 section 15.4.5: Not found\n          return void response.writeHead(StatusCode.NotFound).end();\n        case 'RangeNotSatisfiable':\n          // RFC 9110 section 15.5.17: Range not satisfiable\n          response.setHeader(HeaderName.ContentRange, `bytes */${result.size}`);\n          return void response.writeHead(StatusCode.RangeNotSatisfiable).end();\n        case 'Ok':\n          break;\n      }\n\n      if (isGet(method) && !result.data) {\n        // object store implementation is incorrect, retry by client cannot help\n        return void response.writeHead(StatusCode.GatewayTimeout).end();\n      }\n\n      if (range) {\n        // RFC 9110 section 14.4: Partial content response\n        response.setHeader(\n          HeaderName.ContentLength,\n          result.range.end - result.range.start + 1\n        );\n        response.setHeader(\n          HeaderName.ContentRange,\n          `bytes ${result.range.start}-${result.range.end}/${result.size}`\n        );\n        response.writeHead(StatusCode.PartialContent);\n      } else {\n        // RFC 9110 section 15.3.1: OK response\n        response.setHeader(HeaderName.ContentLength, result.size);\n        response.writeHead(StatusCode.Ok);\n      }\n\n      // RFC 9110 section 9.3.2: HEAD method must not return message body\n      if (isHead(method)) {\n        return void response.end();\n      }\n\n      return await pipeline(result.data!, response, { signal }).catch(() => {\n        // Pipeline errors are expected when request is aborted or connection is lost\n        // Response head was already written, so we can't change status code\n        // Just mute the error - pipeline destroys the response stream\n      });\n    }\n  });\n}\n\n/**\n * Create a request handler for serving files from an object store\n * compatible with HTTP/1.1 as defined in RFC 9110 and RFC 9111:\n * - <https://datatracker.ietf.org/doc/html/rfc9110>\n * - <https://datatracker.ietf.org/doc/html/rfc9111>\n *\n * Accepts only paths of the form `/<filename>.parquet`, returns 404 otherwise\n * Assumes that files are immutable (and sets cache headers accordingly)\n */\nexport function createRequestHandler(\n  options: PFrameInternal.RequestHandlerOptions\n): RequestListener {\n  const { store } = options;\n  return (request, response) => void handleRequest(request, response, store);\n}\n\n/** Request authorization middleware */\nfunction authorizeRequest(\n  request: IncomingMessage,\n  response: ServerResponse,\n  handler: RequestListener,\n  authHeader: string\n): void {\n  // RFC 9110 section 6.6.1: Date header should be present in all responses\n  response.sendDate = true;\n  // RFC 9110 section 8.6: Content-Length 0 as default for error responses\n  response.strictContentLength = true;\n  response.setHeader(HeaderName.ContentLength, 0);\n  // Note: setting Content-Length disables Node.js default Transfer-Encoding: chunked\n\n  const actualHeader = request.headers['authorization'];\n\n  // Early length check to avoid unnecessary processing\n  if (!actualHeader || actualHeader.length !== authHeader.length) {\n    // RFC 9110 section 11.6.1: WWW-Authenticate header field\n    response.setHeader(HeaderName.WWWAuthenticate, HeaderValue.WWWAuthenticate);\n    return void response.writeHead(StatusCode.Unauthorized).end();\n  }\n\n  // Use timing-safe comparison to prevent timing attacks\n  // <https://developers.cloudflare.com/workers/examples/protect-against-timing-attacks/>\n  const encoder = new TextEncoder();\n  const receivedBuffer = encoder.encode(actualHeader);\n  const expectedBuffer = encoder.encode(authHeader);\n\n  if (\n    receivedBuffer.byteLength !== expectedBuffer.byteLength ||\n    !timingSafeEqual(receivedBuffer, expectedBuffer)\n  ) {\n    response.setHeader(HeaderName.WWWAuthenticate, HeaderValue.WWWAuthenticate);\n    return void response.writeHead(StatusCode.Unauthorized).end();\n  }\n\n  return handler(request, response);\n}\n\n/** Apply Bearer token authorization to @param handler */\nexport function authorizeRequestHandler(\n  handler: RequestListener,\n  authToken: PFrameInternal.HttpAuthorizationToken\n): RequestListener {\n  const authHeader = `Bearer ${authToken}`;\n  return (request, response) =>\n    authorizeRequest(request, response, handler, authHeader);\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"handler.js","sources":["../src/handler.ts"],"sourcesContent":["import type {\n  IncomingMessage,\n  RequestListener,\n  ServerResponse\n} from 'node:http';\nimport { pipeline } from 'node:stream/promises';\nimport { timingSafeEqual } from 'node:crypto';\nimport type { PFrameInternal } from '@milaboratories/pl-model-middle-layer';\nimport {\n  createETag,\n  getFilenameFromUrl,\n  parseRange,\n  isGetOrHead,\n  isGet,\n  isHead,\n  Options,\n  StatusCode,\n  HeaderName,\n  HeaderValue\n} from './utils';\n\n/** Main request handler for parquet files */\nasync function handleRequest(\n  request: IncomingMessage,\n  response: ServerResponse,\n  store: PFrameInternal.ObjectStore\n): Promise<void> {\n  // RFC 9110 section 6.6.1: Date header should be present in all responses\n  response.sendDate = true;\n  // RFC 9110 section 8.6: Content-Length 0 as default for error responses\n  response.strictContentLength = true;\n  response.setHeader(HeaderName.ContentLength, 0);\n  // Note: setting Content-Length disables Node.js default Transfer-Encoding: chunked\n\n  // RFC 9111 section 5.2: Cache-Control header with public allows to cache authenticated responses\n  response.setHeader(HeaderName.CacheControl, HeaderValue.CacheControl);\n\n  // RFC 9110 section 15.5.6: Method not allowed\n  const method = request.method;\n  if (!isGetOrHead(method)) {\n    response.setHeader(HeaderName.Allow, HeaderValue.Allow);\n    return void response.writeHead(StatusCode.MethodNotAllowed).end();\n  }\n\n  const filename = getFilenameFromUrl(request);\n  if (filename === null) {\n    return void response.writeHead(StatusCode.Gone).end();\n  }\n\n  // From now on we are sure that the response would be a Parquet file\n  response.setHeader(HeaderName.AcceptRanges, HeaderValue.AcceptRanges);\n  response.setHeader(HeaderName.ContentType, HeaderValue.ContentType);\n\n  // RFC 9110 section 8.8.3: ETag header is used for cache versioning\n  const etag = createETag(filename);\n  // RFC 9110 section 8.8.2: Last-Modified header field for cache validation\n  const mtime = new Date(0); // Using fake fixed date since files are immutable\n  // RFC 9111 section 5.2: Cache-Control header with public allows to cache authenticated responses\n  response.setHeader(HeaderName.CacheControl, HeaderValue.CacheControl);\n  response.setHeader(HeaderName.ETag, etag);\n  response.setHeader(HeaderName.LastModified, mtime.toUTCString());\n\n  const options = new Options(request);\n  // RFC 9110 section 13.1.1: If-Match precondition evaluation\n  // RFC 9110 section 13.1.4: If-Unmodified-Since precondition evaluation\n  if (options.preconditionFailed(etag, mtime)) {\n    return void response.writeHead(StatusCode.PreconditionFailed).end();\n  }\n  // RFC 9110 section 13.1.2: If-None-Match precondition evaluation\n  // RFC 9110 section 13.1.3: If-Modified-Since precondition evaluation\n  else if (options.notModified(etag, mtime)) {\n    return void response.writeHead(StatusCode.NotModified).end();\n  }\n\n  const range = parseRange(request);\n  if (range === null) {\n    return void response.writeHead(StatusCode.BadRequest).end();\n  }\n\n  const abortController = new AbortController();\n  request.on('close', () => abortController.abort());\n  const signal = abortController.signal;\n\n  store.request(filename, {\n    method: 'GET',\n    range,\n    signal,\n    // pipeline automatically destroys the streams if they were not gracefully closed\n    callback: async (result) => {\n      if (response.destroyed) return void response.destroy();\n\n      switch (result.type) {\n        case 'InternalError':\n          // object store encountered network error, retry by client can help\n          return void response.writeHead(StatusCode.InternalServerError).end();\n        case 'NotFound':\n          // RFC 9110 section 15.4.5: Not found\n          return void response.writeHead(StatusCode.NotFound).end();\n        case 'RangeNotSatisfiable':\n          // RFC 9110 section 15.5.17: Range not satisfiable\n          response.setHeader(HeaderName.ContentRange, `bytes */${result.size}`);\n          return void response.writeHead(StatusCode.RangeNotSatisfiable).end();\n        case 'Ok':\n          break;\n      }\n\n      if (isGet(method) && !result.data) {\n        // object store implementation is incorrect, retry by client cannot help\n        return void response.writeHead(StatusCode.GatewayTimeout).end();\n      }\n\n      if (range) {\n        // RFC 9110 section 14.4: Partial content response\n        response.setHeader(\n          HeaderName.ContentLength,\n          result.range.end - result.range.start + 1\n        );\n        response.setHeader(\n          HeaderName.ContentRange,\n          `bytes ${result.range.start}-${result.range.end}/${result.size}`\n        );\n        response.writeHead(StatusCode.PartialContent);\n      } else {\n        // RFC 9110 section 15.3.1: OK response\n        response.setHeader(HeaderName.ContentLength, result.size);\n        response.writeHead(StatusCode.Ok);\n      }\n\n      // RFC 9110 section 9.3.2: HEAD method must not return message body\n      if (isHead(method)) {\n        return void response.end();\n      }\n\n      return await pipeline(result.data!, response, { signal }).catch(() => {\n        // Pipeline errors are expected when request is aborted or connection is lost\n        // Response head was already written, so we can't change status code\n        // Just mute the error - pipeline destroys the response stream\n      });\n    }\n  });\n}\n\n/**\n * Create a request handler for serving files from an object store\n * compatible with HTTP/1.1 as defined in RFC 9110 and RFC 9111:\n * - <https://datatracker.ietf.org/doc/html/rfc9110>\n * - <https://datatracker.ietf.org/doc/html/rfc9111>\n *\n * Accepts only paths of the form `/<filename>.parquet`, returns 410 Gone otherwise\n * Assumes that files are immutable (and sets cache headers accordingly)\n */\nexport function createRequestHandler(\n  options: PFrameInternal.RequestHandlerOptions\n): RequestListener {\n  const { store } = options;\n  return (request, response) => void handleRequest(request, response, store);\n}\n\n/** Request authorization middleware */\nfunction authorizeRequest(\n  request: IncomingMessage,\n  response: ServerResponse,\n  handler: RequestListener,\n  authHeader: string\n): void {\n  // RFC 9110 section 6.6.1: Date header should be present in all responses\n  response.sendDate = true;\n  // RFC 9110 section 8.6: Content-Length 0 as default for error responses\n  response.strictContentLength = true;\n  response.setHeader(HeaderName.ContentLength, 0);\n  // Note: setting Content-Length disables Node.js default Transfer-Encoding: chunked\n\n  const actualHeader = request.headers[HeaderName.Authorization];\n\n  // Early length check to avoid unnecessary processing\n  if (!actualHeader || actualHeader.length !== authHeader.length) {\n    // RFC 9110 section 11.6.1: WWW-Authenticate header field\n    response.setHeader(HeaderName.WWWAuthenticate, HeaderValue.WWWAuthenticate);\n    return void response.writeHead(StatusCode.Unauthorized).end();\n  }\n\n  // Use timing-safe comparison to prevent timing attacks\n  // <https://developers.cloudflare.com/workers/examples/protect-against-timing-attacks/>\n  const encoder = new TextEncoder();\n  const receivedBuffer = encoder.encode(actualHeader);\n  const expectedBuffer = encoder.encode(authHeader);\n\n  if (\n    receivedBuffer.byteLength !== expectedBuffer.byteLength ||\n    !timingSafeEqual(receivedBuffer, expectedBuffer)\n  ) {\n    response.setHeader(HeaderName.WWWAuthenticate, HeaderValue.WWWAuthenticate);\n    return void response.writeHead(StatusCode.Unauthorized).end();\n  }\n\n  return handler(request, response);\n}\n\n/** Apply Bearer token authorization to @param handler */\nexport function authorizeRequestHandler(\n  handler: RequestListener,\n  authToken: PFrameInternal.HttpAuthorizationToken\n): RequestListener {\n  const authHeader = `Bearer ${authToken}`;\n  return (request, response) =>\n    authorizeRequest(request, response, handler, authHeader);\n}\n"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -13,5 +13,6 @@ exports.createRequestHandler = handler.createRequestHandler;
 exports.FileSystemStore = fsStore.FileSystemStore;
 exports.serve = serve.serve;
 exports.HttpHelpers = _export.HttpHelpers;
+exports.ParquetServer = parquetServer.ParquetServer;
 exports.runParquetServer = parquetServer.runParquetServer;
 //# sourceMappingURL=index.cjs.map

package/dist/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/index.js

@@ -2,5 +2,5 @@ export { authorizeRequestHandler, createRequestHandler } from './handler.js';
 export { FileSystemStore } from './fs-store.js';
 export { serve } from './serve.js';
 export { HttpHelpers } from './export.js';
-export { runParquetServer } from './parquet-server.js';
+export { ParquetServer, runParquetServer } from './parquet-server.js';
 //# sourceMappingURL=index.js.map

package/dist/parquet-server.cjs

@@ -1,10 +1,20 @@
 'use strict';
 
+var node_child_process = require('node:child_process');
+var promises = require('node:readline/promises');
+var node_path = require('node:path');
+var node_url = require('node:url');
 var commander = require('commander');
 var fsStore = require('./fs-store.cjs');
 var handler = require('./handler.cjs');
 var serve = require('./serve.cjs');
+var plModelCommon = require('@milaboratories/pl-model-common');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const Options = {
+    Http: '--http',
+    NoAuth: '--no-auth'
+};
 /**
  * Serves parquet files from the given root directory.
  * Manages the server lifecycle with graceful shutdown.
@@ -15,8 +25,8 @@ async function runParquetServer() {
         .name('parquet-server')
         .description('Serve parquet files from a directory over HTTP(S)')
         .argument('<root-directory>', 'Root directory containing parquet files')
-        .option('--http', 'Use HTTP instead of HTTPS', false)
-        .option('--no-auth', 'Disable authentication')
+        .option(Options.Http, 'Use HTTP instead of HTTPS', false)
+        .option(Options.NoAuth, 'Disable authentication')
         .action(async (rootDir, options) => {
         const abortController = new AbortController();
         process
@@ -39,15 +49,58 @@ async function runParquetServer() {
         });
         abortController.signal.onabort = () => server.stop();
         abortController.signal.throwIfAborted();
-        console.log(JSON.stringify({
+        const serverConfig = plModelCommon.stringifyJson({
             url: server.address,
             ...(server.authToken && { authToken: server.authToken }),
             ...(server.encodedCaCert && { caCert: server.encodedCaCert })
-        }));
+        });
+        console.log(serverConfig);
         await server.stopped;
     });
     await program.parseAsync();
 }
+/**
+ * Reference implementation of a parquet server runner for tests:
+ * - Reads the server configuration from the spawned process stdout
+ * - Forwards the server logs to the console
+ * - Shuts down the server on dispose
+ */
+class ParquetServer {
+    #process;
+    #config;
+    #lineReader;
+    constructor(process, config, lineReader) {
+        this.#process = process;
+        this.#config = config;
+        this.#lineReader = lineReader;
+    }
+    get config() {
+        return this.#config;
+    }
+    static async serve(rootDir, options) {
+        const nodeFileUrl = (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('parquet-server.cjs', document.baseURI).href));
+        const nodeDirname = node_path.dirname(node_url.fileURLToPath(nodeFileUrl));
+        const binPath = node_path.join(nodeDirname, '..', 'bin', 'parquet-server.mjs');
+        const serverProcess = node_child_process.spawn('node', [
+            binPath,
+            rootDir,
+            ...(options?.http ? [Options.Http] : []),
+            ...(options?.noAuth ? [Options.NoAuth] : [])
+        ], {
+            stdio: ['ignore', 'pipe', 'ignore']
+        });
+        const lineReader = promises.createInterface({ input: serverProcess.stdout });
+        const firstLine = await lineReader[Symbol.asyncIterator]().next();
+        const serverConfig = plModelCommon.parseJson(firstLine.value);
+        lineReader.on('line', console.log);
+        return new ParquetServer(serverProcess, serverConfig, lineReader);
+    }
+    [Symbol.dispose]() {
+        this.#lineReader.close();
+        this.#process.kill();
+    }
+}
 
+exports.ParquetServer = ParquetServer;
 exports.runParquetServer = runParquetServer;
 //# sourceMappingURL=parquet-server.cjs.map

package/dist/parquet-server.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"parquet-server.cjs","sources":["../src/parquet-server.ts"],"sourcesContent":["import { Command } from 'commander';\nimport { FileSystemStore } from './fs-store';\nimport { createRequestHandler } from './handler';\nimport { serve } from './serve';\n\n/**\n * Serves parquet files from the given root directory.\n * Manages the server lifecycle with graceful shutdown.\n */\nexport async function runParquetServer(): Promise<void> {\n  const program = new Command();\n\n  program\n    .name('parquet-server')\n    .description('Serve parquet files from a directory over HTTP(S)')\n    .argument('<root-directory>', 'Root directory containing parquet files')\n    .option('--http', 'Use HTTP instead of HTTPS', false)\n    .option('--no-auth', 'Disable authentication')\n    .action(\n      async (rootDir: string, options: { http: boolean; auth: boolean }) => {\n        const abortController = new AbortController();\n        process\n          .on('SIGINT', () => abortController.abort())\n          .on('SIGTERM', () => abortController.abort());\n        abortController.signal.throwIfAborted();\n\n        const store = await FileSystemStore.init({\n          rootDir,\n          logger: (level, message) => {\n            const timestamp = new Date(Date.now()).toISOString();\n            console.log(`[${timestamp}] [${level}] ${message}`);\n          }\n        });\n        abortController.signal.throwIfAborted();\n        const handler = createRequestHandler({ store });\n\n        const server = await serve({\n          handler,\n          ...(options.http && { http: true }),\n          ...(!options.auth && { noAuth: true })\n        });\n        abortController.signal.onabort = () => server.stop();\n        abortController.signal.throwIfAborted();\n\n        console.log(\n          JSON.stringify({\n            url: server.address,\n            ...(server.authToken && { authToken: server.authToken }),\n            ...(server.encodedCaCert && { caCert: server.encodedCaCert })\n          })\n        );\n\n        await server.stopped;\n      }\n    );\n\n  await program.parseAsync();\n}\n"],"names":["Command","FileSystemStore","handler","createRequestHandler","serve"],"mappings":";;;;;;;AAKA;;;AAGG;AACI,eAAe,gBAAgB,GAAA;AACpC,IAAA,MAAM,OAAO,GAAG,IAAIA,iBAAO,EAAE;IAE7B;SACG,IAAI,CAAC,gBAAgB;SACrB,WAAW,CAAC,mDAAmD;AAC/D,SAAA,QAAQ,CAAC,kBAAkB,EAAE,yCAAyC;AACtE,SAAA,MAAM,CAAC,QAAQ,EAAE,2BAA2B,EAAE,KAAK;AACnD,SAAA,MAAM,CAAC,WAAW,EAAE,wBAAwB;AAC5C,SAAA,MAAM,CACL,OAAO,OAAe,EAAE,OAAyC,KAAI;AACnE,QAAA,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE;QAC7C;aACG,EAAE,CAAC,QAAQ,EAAE,MAAM,eAAe,CAAC,KAAK,EAAE;aAC1C,EAAE,CAAC,SAAS,EAAE,MAAM,eAAe,CAAC,KAAK,EAAE,CAAC;AAC/C,QAAA,eAAe,CAAC,MAAM,CAAC,cAAc,EAAE;AAEvC,QAAA,MAAM,KAAK,GAAG,MAAMC,uBAAe,CAAC,IAAI,CAAC;YACvC,OAAO;AACP,YAAA,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAI;AACzB,gBAAA,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE;gBACpD,OAAO,CAAC,GAAG,CAAC,CAAA,CAAA,EAAI,SAAS,CAAA,GAAA,EAAM,KAAK,CAAA,EAAA,EAAK,OAAO,CAAA,CAAE,CAAC;YACrD;AACD,SAAA,CAAC;AACF,QAAA,eAAe,CAAC,MAAM,CAAC,cAAc,EAAE;QACvC,MAAMC,SAAO,GAAGC,4BAAoB,CAAC,EAAE,KAAK,EAAE,CAAC;AAE/C,QAAA,MAAM,MAAM,GAAG,MAAMC,WAAK,CAAC;qBACzBF,SAAO;YACP,IAAI,OAAO,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YACnC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;AACtC,SAAA,CAAC;AACF,QAAA,eAAe,CAAC,MAAM,CAAC,OAAO,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE;AACpD,QAAA,eAAe,CAAC,MAAM,CAAC,cAAc,EAAE;AAEvC,QAAA,OAAO,CAAC,GAAG,CACT,IAAI,CAAC,SAAS,CAAC;YACb,GAAG,EAAE,MAAM,CAAC,OAAO;AACnB,YAAA,IAAI,MAAM,CAAC,SAAS,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;AACxD,YAAA,IAAI,MAAM,CAAC,aAAa,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,aAAa,EAAE;AAC7D,SAAA,CAAC,CACH;QAED,MAAM,MAAM,CAAC,OAAO;AACtB,IAAA,CAAC,CACF;AAEH,IAAA,MAAM,OAAO,CAAC,UAAU,EAAE;AAC5B;;;;"}
+{"version":3,"file":"parquet-server.cjs","sources":["../src/parquet-server.ts"],"sourcesContent":["import { type ChildProcess, spawn } from 'node:child_process';\nimport { createInterface, type Interface } from 'node:readline/promises';\nimport { join, dirname } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { Command } from 'commander';\nimport { FileSystemStore } from './fs-store';\nimport { createRequestHandler } from './handler';\nimport { serve } from './serve';\nimport {\n  parseJson,\n  type StringifiedJson,\n  stringifyJson\n} from '@milaboratories/pl-model-common';\nimport { type PFrameInternal } from '@milaboratories/pl-model-middle-layer';\n\nconst Options = {\n  Http: '--http',\n  NoAuth: '--no-auth'\n} as const;\n\ntype Config = StringifiedJson<PFrameInternal.ParquetServerConfig>;\n\n/**\n * Serves parquet files from the given root directory.\n * Manages the server lifecycle with graceful shutdown.\n */\nexport async function runParquetServer(): Promise<void> {\n  const program = new Command();\n\n  program\n    .name('parquet-server')\n    .description('Serve parquet files from a directory over HTTP(S)')\n    .argument('<root-directory>', 'Root directory containing parquet files')\n    .option(Options.Http, 'Use HTTP instead of HTTPS', false)\n    .option(Options.NoAuth, 'Disable authentication')\n    .action(\n      async (rootDir: string, options: { http: boolean; auth: boolean }) => {\n        const abortController = new AbortController();\n        process\n          .on('SIGINT', () => abortController.abort())\n          .on('SIGTERM', () => abortController.abort());\n        abortController.signal.throwIfAborted();\n\n        const store = await FileSystemStore.init({\n          rootDir,\n          logger: (level, message) => {\n            const timestamp = new Date(Date.now()).toISOString();\n            console.log(`[${timestamp}] [${level}] ${message}`);\n          }\n        });\n        abortController.signal.throwIfAborted();\n        const handler = createRequestHandler({ store });\n\n        const server = await serve({\n          handler,\n          ...(options.http && { http: true }),\n          ...(!options.auth && { noAuth: true })\n        });\n        abortController.signal.onabort = () => server.stop();\n        abortController.signal.throwIfAborted();\n\n        const serverConfig: Config = stringifyJson({\n          url: server.address,\n          ...(server.authToken && { authToken: server.authToken }),\n          ...(server.encodedCaCert && { caCert: server.encodedCaCert })\n        });\n        console.log(serverConfig);\n\n        await server.stopped;\n      }\n    );\n\n  await program.parseAsync();\n}\n\n/**\n * Reference implementation of a parquet server runner for tests:\n * - Reads the server configuration from the spawned process stdout\n * - Forwards the server logs to the console\n * - Shuts down the server on dispose\n */\nexport class ParquetServer implements Disposable {\n  readonly #process: ChildProcess;\n  readonly #config: PFrameInternal.ParquetServerConfig;\n  readonly #lineReader: Interface;\n\n  private constructor(\n    process: ChildProcess,\n    config: PFrameInternal.ParquetServerConfig,\n    lineReader: Interface\n  ) {\n    this.#process = process;\n    this.#config = config;\n    this.#lineReader = lineReader;\n  }\n\n  get config(): PFrameInternal.ParquetServerConfig {\n    return this.#config;\n  }\n\n  static async serve(\n    rootDir: string,\n    options?: {\n      http?: boolean;\n      noAuth?: boolean;\n    }\n  ): Promise<ParquetServer> {\n    const nodeFileUrl = import.meta.url;\n    const nodeDirname = dirname(fileURLToPath(nodeFileUrl));\n    const binPath = join(nodeDirname, '..', 'bin', 'parquet-server.mjs');\n\n    const serverProcess = spawn(\n      'node',\n      [\n        binPath,\n        rootDir,\n        ...(options?.http ? [Options.Http] : []),\n        ...(options?.noAuth ? [Options.NoAuth] : [])\n      ],\n      {\n        stdio: ['ignore', 'pipe', 'ignore']\n      }\n    );\n\n    const lineReader = createInterface({ input: serverProcess.stdout! });\n\n    const firstLine = await lineReader[Symbol.asyncIterator]().next();\n    const serverConfig = parseJson(firstLine.value as Config);\n\n    lineReader.on('line', console.log);\n\n    return new ParquetServer(serverProcess, serverConfig, lineReader);\n  }\n\n  [Symbol.dispose](): void {\n    this.#lineReader.close();\n    this.#process.kill();\n  }\n}\n"],"names":["Command","FileSystemStore","handler","createRequestHandler","serve","stringifyJson","dirname","fileURLToPath","join","spawn","createInterface","parseJson"],"mappings":"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"}

package/dist/parquet-server.d.ts

@@ -1,6 +1,23 @@
+import { type PFrameInternal } from '@milaboratories/pl-model-middle-layer';
 /**
  * Serves parquet files from the given root directory.
  * Manages the server lifecycle with graceful shutdown.
  */
 export declare function runParquetServer(): Promise<void>;
+/**
+ * Reference implementation of a parquet server runner for tests:
+ * - Reads the server configuration from the spawned process stdout
+ * - Forwards the server logs to the console
+ * - Shuts down the server on dispose
+ */
+export declare class ParquetServer implements Disposable {
+    #private;
+    private constructor();
+    get config(): PFrameInternal.ParquetServerConfig;
+    static serve(rootDir: string, options?: {
+        http?: boolean;
+        noAuth?: boolean;
+    }): Promise<ParquetServer>;
+    [Symbol.dispose](): void;
+}
 //# sourceMappingURL=parquet-server.d.ts.map

package/dist/parquet-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parquet-server.d.ts","sourceRoot":"","sources":["../src/parquet-server.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgDtD"}
+{"version":3,"file":"parquet-server.d.ts","sourceRoot":"","sources":["../src/parquet-server.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAS5E;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CA+CtD;AAED;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,UAAU;;IAK9C,OAAO;IAUP,IAAI,MAAM,IAAI,cAAc,CAAC,mBAAmB,CAE/C;WAEY,KAAK,CAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GACA,OAAO,CAAC,aAAa,CAAC;IA4BzB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAIzB"}

package/dist/parquet-server.js

@@ -1,8 +1,17 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { FileSystemStore } from './fs-store.js';
 import { createRequestHandler } from './handler.js';
 import { serve } from './serve.js';
+import { stringifyJson, parseJson } from '@milaboratories/pl-model-common';
 
+const Options = {
+    Http: '--http',
+    NoAuth: '--no-auth'
+};
 /**
  * Serves parquet files from the given root directory.
  * Manages the server lifecycle with graceful shutdown.
@@ -13,8 +22,8 @@ async function runParquetServer() {
         .name('parquet-server')
         .description('Serve parquet files from a directory over HTTP(S)')
         .argument('<root-directory>', 'Root directory containing parquet files')
-        .option('--http', 'Use HTTP instead of HTTPS', false)
-        .option('--no-auth', 'Disable authentication')
+        .option(Options.Http, 'Use HTTP instead of HTTPS', false)
+        .option(Options.NoAuth, 'Disable authentication')
         .action(async (rootDir, options) => {
         const abortController = new AbortController();
         process
@@ -37,15 +46,57 @@ async function runParquetServer() {
         });
         abortController.signal.onabort = () => server.stop();
         abortController.signal.throwIfAborted();
-        console.log(JSON.stringify({
+        const serverConfig = stringifyJson({
             url: server.address,
             ...(server.authToken && { authToken: server.authToken }),
             ...(server.encodedCaCert && { caCert: server.encodedCaCert })
-        }));
+        });
+        console.log(serverConfig);
         await server.stopped;
     });
     await program.parseAsync();
 }
+/**
+ * Reference implementation of a parquet server runner for tests:
+ * - Reads the server configuration from the spawned process stdout
+ * - Forwards the server logs to the console
+ * - Shuts down the server on dispose
+ */
+class ParquetServer {
+    #process;
+    #config;
+    #lineReader;
+    constructor(process, config, lineReader) {
+        this.#process = process;
+        this.#config = config;
+        this.#lineReader = lineReader;
+    }
+    get config() {
+        return this.#config;
+    }
+    static async serve(rootDir, options) {
+        const nodeFileUrl = import.meta.url;
+        const nodeDirname = dirname(fileURLToPath(nodeFileUrl));
+        const binPath = join(nodeDirname, '..', 'bin', 'parquet-server.mjs');
+        const serverProcess = spawn('node', [
+            binPath,
+            rootDir,
+            ...(options?.http ? [Options.Http] : []),
+            ...(options?.noAuth ? [Options.NoAuth] : [])
+        ], {
+            stdio: ['ignore', 'pipe', 'ignore']
+        });
+        const lineReader = createInterface({ input: serverProcess.stdout });
+        const firstLine = await lineReader[Symbol.asyncIterator]().next();
+        const serverConfig = parseJson(firstLine.value);
+        lineReader.on('line', console.log);
+        return new ParquetServer(serverProcess, serverConfig, lineReader);
+    }
+    [Symbol.dispose]() {
+        this.#lineReader.close();
+        this.#process.kill();
+    }
+}
 
-export { runParquetServer };
+export { ParquetServer, runParquetServer };
 //# sourceMappingURL=parquet-server.js.map

package/dist/parquet-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"parquet-server.js","sources":["../src/parquet-server.ts"],"sourcesContent":["import { Command } from 'commander';\nimport { FileSystemStore } from './fs-store';\nimport { createRequestHandler } from './handler';\nimport { serve } from './serve';\n\n/**\n * Serves parquet files from the given root directory.\n * Manages the server lifecycle with graceful shutdown.\n */\nexport async function runParquetServer(): Promise<void> {\n  const program = new Command();\n\n  program\n    .name('parquet-server')\n    .description('Serve parquet files from a directory over HTTP(S)')\n    .argument('<root-directory>', 'Root directory containing parquet files')\n    .option('--http', 'Use HTTP instead of HTTPS', false)\n    .option('--no-auth', 'Disable authentication')\n    .action(\n      async (rootDir: string, options: { http: boolean; auth: boolean }) => {\n        const abortController = new AbortController();\n        process\n          .on('SIGINT', () => abortController.abort())\n          .on('SIGTERM', () => abortController.abort());\n        abortController.signal.throwIfAborted();\n\n        const store = await FileSystemStore.init({\n          rootDir,\n          logger: (level, message) => {\n            const timestamp = new Date(Date.now()).toISOString();\n            console.log(`[${timestamp}] [${level}] ${message}`);\n          }\n        });\n        abortController.signal.throwIfAborted();\n        const handler = createRequestHandler({ store });\n\n        const server = await serve({\n          handler,\n          ...(options.http && { http: true }),\n          ...(!options.auth && { noAuth: true })\n        });\n        abortController.signal.onabort = () => server.stop();\n        abortController.signal.throwIfAborted();\n\n        console.log(\n          JSON.stringify({\n            url: server.address,\n            ...(server.authToken && { authToken: server.authToken }),\n            ...(server.encodedCaCert && { caCert: server.encodedCaCert })\n          })\n        );\n\n        await server.stopped;\n      }\n    );\n\n  await program.parseAsync();\n}\n"],"names":[],"mappings":";;;;;AAKA;;;AAGG;AACI,eAAe,gBAAgB,GAAA;AACpC,IAAA,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE;IAE7B;SACG,IAAI,CAAC,gBAAgB;SACrB,WAAW,CAAC,mDAAmD;AAC/D,SAAA,QAAQ,CAAC,kBAAkB,EAAE,yCAAyC;AACtE,SAAA,MAAM,CAAC,QAAQ,EAAE,2BAA2B,EAAE,KAAK;AACnD,SAAA,MAAM,CAAC,WAAW,EAAE,wBAAwB;AAC5C,SAAA,MAAM,CACL,OAAO,OAAe,EAAE,OAAyC,KAAI;AACnE,QAAA,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE;QAC7C;aACG,EAAE,CAAC,QAAQ,EAAE,MAAM,eAAe,CAAC,KAAK,EAAE;aAC1C,EAAE,CAAC,SAAS,EAAE,MAAM,eAAe,CAAC,KAAK,EAAE,CAAC;AAC/C,QAAA,eAAe,CAAC,MAAM,CAAC,cAAc,EAAE;AAEvC,QAAA,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC;YACvC,OAAO;AACP,YAAA,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAI;AACzB,gBAAA,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE;gBACpD,OAAO,CAAC,GAAG,CAAC,CAAA,CAAA,EAAI,SAAS,CAAA,GAAA,EAAM,KAAK,CAAA,EAAA,EAAK,OAAO,CAAA,CAAE,CAAC;YACrD;AACD,SAAA,CAAC;AACF,QAAA,eAAe,CAAC,MAAM,CAAC,cAAc,EAAE;QACvC,MAAM,OAAO,GAAG,oBAAoB,CAAC,EAAE,KAAK,EAAE,CAAC;AAE/C,QAAA,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC;YACzB,OAAO;YACP,IAAI,OAAO,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YACnC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;AACtC,SAAA,CAAC;AACF,QAAA,eAAe,CAAC,MAAM,CAAC,OAAO,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE;AACpD,QAAA,eAAe,CAAC,MAAM,CAAC,cAAc,EAAE;AAEvC,QAAA,OAAO,CAAC,GAAG,CACT,IAAI,CAAC,SAAS,CAAC;YACb,GAAG,EAAE,MAAM,CAAC,OAAO;AACnB,YAAA,IAAI,MAAM,CAAC,SAAS,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;AACxD,YAAA,IAAI,MAAM,CAAC,aAAa,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,aAAa,EAAE;AAC7D,SAAA,CAAC,CACH;QAED,MAAM,MAAM,CAAC,OAAO;AACtB,IAAA,CAAC,CACF;AAEH,IAAA,MAAM,OAAO,CAAC,UAAU,EAAE;AAC5B;;;;"}
+{"version":3,"file":"parquet-server.js","sources":["../src/parquet-server.ts"],"sourcesContent":["import { type ChildProcess, spawn } from 'node:child_process';\nimport { createInterface, type Interface } from 'node:readline/promises';\nimport { join, dirname } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { Command } from 'commander';\nimport { FileSystemStore } from './fs-store';\nimport { createRequestHandler } from './handler';\nimport { serve } from './serve';\nimport {\n  parseJson,\n  type StringifiedJson,\n  stringifyJson\n} from '@milaboratories/pl-model-common';\nimport { type PFrameInternal } from '@milaboratories/pl-model-middle-layer';\n\nconst Options = {\n  Http: '--http',\n  NoAuth: '--no-auth'\n} as const;\n\ntype Config = StringifiedJson<PFrameInternal.ParquetServerConfig>;\n\n/**\n * Serves parquet files from the given root directory.\n * Manages the server lifecycle with graceful shutdown.\n */\nexport async function runParquetServer(): Promise<void> {\n  const program = new Command();\n\n  program\n    .name('parquet-server')\n    .description('Serve parquet files from a directory over HTTP(S)')\n    .argument('<root-directory>', 'Root directory containing parquet files')\n    .option(Options.Http, 'Use HTTP instead of HTTPS', false)\n    .option(Options.NoAuth, 'Disable authentication')\n    .action(\n      async (rootDir: string, options: { http: boolean; auth: boolean }) => {\n        const abortController = new AbortController();\n        process\n          .on('SIGINT', () => abortController.abort())\n          .on('SIGTERM', () => abortController.abort());\n        abortController.signal.throwIfAborted();\n\n        const store = await FileSystemStore.init({\n          rootDir,\n          logger: (level, message) => {\n            const timestamp = new Date(Date.now()).toISOString();\n            console.log(`[${timestamp}] [${level}] ${message}`);\n          }\n        });\n        abortController.signal.throwIfAborted();\n        const handler = createRequestHandler({ store });\n\n        const server = await serve({\n          handler,\n          ...(options.http && { http: true }),\n          ...(!options.auth && { noAuth: true })\n        });\n        abortController.signal.onabort = () => server.stop();\n        abortController.signal.throwIfAborted();\n\n        const serverConfig: Config = stringifyJson({\n          url: server.address,\n          ...(server.authToken && { authToken: server.authToken }),\n          ...(server.encodedCaCert && { caCert: server.encodedCaCert })\n        });\n        console.log(serverConfig);\n\n        await server.stopped;\n      }\n    );\n\n  await program.parseAsync();\n}\n\n/**\n * Reference implementation of a parquet server runner for tests:\n * - Reads the server configuration from the spawned process stdout\n * - Forwards the server logs to the console\n * - Shuts down the server on dispose\n */\nexport class ParquetServer implements Disposable {\n  readonly #process: ChildProcess;\n  readonly #config: PFrameInternal.ParquetServerConfig;\n  readonly #lineReader: Interface;\n\n  private constructor(\n    process: ChildProcess,\n    config: PFrameInternal.ParquetServerConfig,\n    lineReader: Interface\n  ) {\n    this.#process = process;\n    this.#config = config;\n    this.#lineReader = lineReader;\n  }\n\n  get config(): PFrameInternal.ParquetServerConfig {\n    return this.#config;\n  }\n\n  static async serve(\n    rootDir: string,\n    options?: {\n      http?: boolean;\n      noAuth?: boolean;\n    }\n  ): Promise<ParquetServer> {\n    const nodeFileUrl = import.meta.url;\n    const nodeDirname = dirname(fileURLToPath(nodeFileUrl));\n    const binPath = join(nodeDirname, '..', 'bin', 'parquet-server.mjs');\n\n    const serverProcess = spawn(\n      'node',\n      [\n        binPath,\n        rootDir,\n        ...(options?.http ? [Options.Http] : []),\n        ...(options?.noAuth ? [Options.NoAuth] : [])\n      ],\n      {\n        stdio: ['ignore', 'pipe', 'ignore']\n      }\n    );\n\n    const lineReader = createInterface({ input: serverProcess.stdout! });\n\n    const firstLine = await lineReader[Symbol.asyncIterator]().next();\n    const serverConfig = parseJson(firstLine.value as Config);\n\n    lineReader.on('line', console.log);\n\n    return new ParquetServer(serverProcess, serverConfig, lineReader);\n  }\n\n  [Symbol.dispose](): void {\n    this.#lineReader.close();\n    this.#process.kill();\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/utils/headers.cjs

@@ -4,6 +4,7 @@
 const HeaderName = {
     AcceptRanges: 'accept-ranges',
     Allow: 'allow',
+    Authorization: 'authorization',
     CacheControl: 'cache-control',
     ContentLength: 'content-length',
     ContentRange: 'content-range',

package/dist/utils/headers.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"headers.cjs","sources":["../../src/utils/headers.ts"],"sourcesContent":["/** HTTP header names used in the parquet server handler */\nexport const HeaderName = {\n  Accept: 'accept',\n  AcceptRanges: 'accept-ranges',\n  Allow: 'allow',\n  Authorization: 'authorization',\n  CacheControl: 'cache-control',\n  ContentLength: 'content-length',\n  ContentRange: 'content-range',\n  ContentType: 'content-type',\n  Date: 'date',\n  ETag: 'etag',\n  IfMatch: 'if-match',\n  IfModifiedSince: 'if-modified-since',\n  IfNoneMatch: 'if-none-match',\n  IfUnmodifiedSince: 'if-unmodified-since',\n  LastModified: 'last-modified',\n  Range: 'range',\n  WWWAuthenticate: 'www-authenticate'\n} as const;\n\n/** HTTP header values used in the parquet server handler */\nexport const HeaderValue = {\n  AcceptRanges: 'bytes',\n  Allow: 'GET, HEAD',\n  CacheControl: 'public, immutable, max-age=31536000',\n  ContentType: 'application/octet-stream',\n  WWWAuthenticate: 'Bearer realm=\"parquet-server\"'\n} as const;\n"],"names":[],"mappings":";;AAAA;AACO,MAAM,UAAU,GAAG;AACxB,IACA,YAAY,EAAE,eAAe;AAC7B,IAAA,KAAK,EAAE,OAAO;AACd,IACA,YAAY,EAAE,eAAe;AAC7B,IAAA,aAAa,EAAE,gBAAgB;AAC/B,IAAA,YAAY,EAAE,eAAe;AAC7B,IAAA,WAAW,EAAE,cAAc;AAC3B,IACA,IAAI,EAAE,MAAM;AACZ,IAIA,YAAY,EAAE,eAAe;AAC7B,IACA,eAAe,EAAE;;AAGnB;AACO,MAAM,WAAW,GAAG;AACzB,IAAA,YAAY,EAAE,OAAO;AACrB,IAAA,KAAK,EAAE,WAAW;AAClB,IAAA,YAAY,EAAE,qCAAqC;AACnD,IAAA,WAAW,EAAE,0BAA0B;AACvC,IAAA,eAAe,EAAE;;;;;;"}
+{"version":3,"file":"headers.cjs","sources":["../../src/utils/headers.ts"],"sourcesContent":["/** HTTP header names used in the parquet server handler */\nexport const HeaderName = {\n  Accept: 'accept',\n  AcceptRanges: 'accept-ranges',\n  Allow: 'allow',\n  Authorization: 'authorization',\n  CacheControl: 'cache-control',\n  ContentLength: 'content-length',\n  ContentRange: 'content-range',\n  ContentType: 'content-type',\n  Date: 'date',\n  ETag: 'etag',\n  IfMatch: 'if-match',\n  IfModifiedSince: 'if-modified-since',\n  IfNoneMatch: 'if-none-match',\n  IfUnmodifiedSince: 'if-unmodified-since',\n  LastModified: 'last-modified',\n  Range: 'range',\n  WWWAuthenticate: 'www-authenticate'\n} as const;\n\n/** HTTP header values used in the parquet server handler */\nexport const HeaderValue = {\n  AcceptRanges: 'bytes',\n  Allow: 'GET, HEAD',\n  CacheControl: 'public, immutable, max-age=31536000',\n  ContentType: 'application/octet-stream',\n  WWWAuthenticate: 'Bearer realm=\"parquet-server\"'\n} as const;\n"],"names":[],"mappings":";;AAAA;AACO,MAAM,UAAU,GAAG;AACxB,IACA,YAAY,EAAE,eAAe;AAC7B,IAAA,KAAK,EAAE,OAAO;AACd,IAAA,aAAa,EAAE,eAAe;AAC9B,IAAA,YAAY,EAAE,eAAe;AAC7B,IAAA,aAAa,EAAE,gBAAgB;AAC/B,IAAA,YAAY,EAAE,eAAe;AAC7B,IAAA,WAAW,EAAE,cAAc;AAC3B,IACA,IAAI,EAAE,MAAM;AACZ,IAIA,YAAY,EAAE,eAAe;AAC7B,IACA,eAAe,EAAE;;AAGnB;AACO,MAAM,WAAW,GAAG;AACzB,IAAA,YAAY,EAAE,OAAO;AACrB,IAAA,KAAK,EAAE,WAAW;AAClB,IAAA,YAAY,EAAE,qCAAqC;AACnD,IAAA,WAAW,EAAE,0BAA0B;AACvC,IAAA,eAAe,EAAE;;;;;;"}

package/dist/utils/headers.js

@@ -2,6 +2,7 @@
 const HeaderName = {
     AcceptRanges: 'accept-ranges',
     Allow: 'allow',
+    Authorization: 'authorization',
     CacheControl: 'cache-control',
     ContentLength: 'content-length',
     ContentRange: 'content-range',

package/dist/utils/headers.js.map

@@ -1 +1 @@
-{"version":3,"file":"headers.js","sources":["../../src/utils/headers.ts"],"sourcesContent":["/** HTTP header names used in the parquet server handler */\nexport const HeaderName = {\n  Accept: 'accept',\n  AcceptRanges: 'accept-ranges',\n  Allow: 'allow',\n  Authorization: 'authorization',\n  CacheControl: 'cache-control',\n  ContentLength: 'content-length',\n  ContentRange: 'content-range',\n  ContentType: 'content-type',\n  Date: 'date',\n  ETag: 'etag',\n  IfMatch: 'if-match',\n  IfModifiedSince: 'if-modified-since',\n  IfNoneMatch: 'if-none-match',\n  IfUnmodifiedSince: 'if-unmodified-since',\n  LastModified: 'last-modified',\n  Range: 'range',\n  WWWAuthenticate: 'www-authenticate'\n} as const;\n\n/** HTTP header values used in the parquet server handler */\nexport const HeaderValue = {\n  AcceptRanges: 'bytes',\n  Allow: 'GET, HEAD',\n  CacheControl: 'public, immutable, max-age=31536000',\n  ContentType: 'application/octet-stream',\n  WWWAuthenticate: 'Bearer realm=\"parquet-server\"'\n} as const;\n"],"names":[],"mappings":"AAAA;AACO,MAAM,UAAU,GAAG;AACxB,IACA,YAAY,EAAE,eAAe;AAC7B,IAAA,KAAK,EAAE,OAAO;AACd,IACA,YAAY,EAAE,eAAe;AAC7B,IAAA,aAAa,EAAE,gBAAgB;AAC/B,IAAA,YAAY,EAAE,eAAe;AAC7B,IAAA,WAAW,EAAE,cAAc;AAC3B,IACA,IAAI,EAAE,MAAM;AACZ,IAIA,YAAY,EAAE,eAAe;AAC7B,IACA,eAAe,EAAE;;AAGnB;AACO,MAAM,WAAW,GAAG;AACzB,IAAA,YAAY,EAAE,OAAO;AACrB,IAAA,KAAK,EAAE,WAAW;AAClB,IAAA,YAAY,EAAE,qCAAqC;AACnD,IAAA,WAAW,EAAE,0BAA0B;AACvC,IAAA,eAAe,EAAE;;;;;"}
+{"version":3,"file":"headers.js","sources":["../../src/utils/headers.ts"],"sourcesContent":["/** HTTP header names used in the parquet server handler */\nexport const HeaderName = {\n  Accept: 'accept',\n  AcceptRanges: 'accept-ranges',\n  Allow: 'allow',\n  Authorization: 'authorization',\n  CacheControl: 'cache-control',\n  ContentLength: 'content-length',\n  ContentRange: 'content-range',\n  ContentType: 'content-type',\n  Date: 'date',\n  ETag: 'etag',\n  IfMatch: 'if-match',\n  IfModifiedSince: 'if-modified-since',\n  IfNoneMatch: 'if-none-match',\n  IfUnmodifiedSince: 'if-unmodified-since',\n  LastModified: 'last-modified',\n  Range: 'range',\n  WWWAuthenticate: 'www-authenticate'\n} as const;\n\n/** HTTP header values used in the parquet server handler */\nexport const HeaderValue = {\n  AcceptRanges: 'bytes',\n  Allow: 'GET, HEAD',\n  CacheControl: 'public, immutable, max-age=31536000',\n  ContentType: 'application/octet-stream',\n  WWWAuthenticate: 'Bearer realm=\"parquet-server\"'\n} as const;\n"],"names":[],"mappings":"AAAA;AACO,MAAM,UAAU,GAAG;AACxB,IACA,YAAY,EAAE,eAAe;AAC7B,IAAA,KAAK,EAAE,OAAO;AACd,IAAA,aAAa,EAAE,eAAe;AAC9B,IAAA,YAAY,EAAE,eAAe;AAC7B,IAAA,aAAa,EAAE,gBAAgB;AAC/B,IAAA,YAAY,EAAE,eAAe;AAC7B,IAAA,WAAW,EAAE,cAAc;AAC3B,IACA,IAAI,EAAE,MAAM;AACZ,IAIA,YAAY,EAAE,eAAe;AAC7B,IACA,eAAe,EAAE;;AAGnB;AACO,MAAM,WAAW,GAAG;AACzB,IAAA,YAAY,EAAE,OAAO;AACrB,IAAA,KAAK,EAAE,WAAW;AAClB,IAAA,YAAY,EAAE,qCAAqC;AACnD,IAAA,WAAW,EAAE,0BAA0B;AACvC,IAAA,eAAe,EAAE;;;;;"}

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@milaboratories/pframes-rs-serv",
   "description": "PFrames - Node.js HTTP(S) Parquet Server",
-  "version": "1.0.64",
+  "keywords": [
+    "http",
+    "https",
+    "parquet",
+    "proxy",
+    "server"
+  ],
+  "version": "1.0.67",
   "type": "module",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
@@ -23,7 +30,7 @@
   "dependencies": {
     "@milaboratories/helpers": "1.6.22",
     "@milaboratories/pl-model-common": "1.19.14",
-    "@milaboratories/pl-model-middle-layer": "1.8.16",
+    "@milaboratories/pl-model-middle-layer": "1.8.17",
     "commander": "^14.0.0",
     "selfsigned": "^3.0.1"
   },
@@ -34,6 +41,7 @@
     "@types/node": "^20.19.11",
     "@vitest/coverage-istanbul": "^3.2.4",
     "autocannon": "^8.0.0",
+    "tslib": "^2.8.1",
     "typescript": "^5.9.2",
     "undici": "^7.14.0",
     "vite": "^7.1.3",

package/src/handler.ts

@@ -11,12 +11,12 @@ import {
   getFilenameFromUrl,
   parseRange,
   isGetOrHead,
+  isGet,
   isHead,
   Options,
   StatusCode,
   HeaderName,
-  HeaderValue,
-  isGet
+  HeaderValue
 } from './utils';
 
 /** Main request handler for parquet files */
@@ -146,7 +146,7 @@ async function handleRequest(
  * - <https://datatracker.ietf.org/doc/html/rfc9110>
  * - <https://datatracker.ietf.org/doc/html/rfc9111>
  *
- * Accepts only paths of the form `/<filename>.parquet`, returns 404 otherwise
+ * Accepts only paths of the form `/<filename>.parquet`, returns 410 Gone otherwise
  * Assumes that files are immutable (and sets cache headers accordingly)
  */
 export function createRequestHandler(
@@ -170,7 +170,7 @@ function authorizeRequest(
   response.setHeader(HeaderName.ContentLength, 0);
   // Note: setting Content-Length disables Node.js default Transfer-Encoding: chunked
 
-  const actualHeader = request.headers['authorization'];
+  const actualHeader = request.headers[HeaderName.Authorization];
 
   // Early length check to avoid unnecessary processing
   if (!actualHeader || actualHeader.length !== authHeader.length) {

package/src/parquet-server.ts

@@ -1,7 +1,24 @@
+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 {
+  parseJson,
+  type StringifiedJson,
+  stringifyJson
+} from '@milaboratories/pl-model-common';
+import { type PFrameInternal } from '@milaboratories/pl-model-middle-layer';
+
+const Options = {
+  Http: '--http',
+  NoAuth: '--no-auth'
+} as const;
+
+type Config = StringifiedJson<PFrameInternal.ParquetServerConfig>;
 
 /**
  * Serves parquet files from the given root directory.
@@ -14,8 +31,8 @@ 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('--http', 'Use HTTP instead of HTTPS', false)
-    .option('--no-auth', 'Disable authentication')
+    .option(Options.Http, 'Use HTTP instead of HTTPS', false)
+    .option(Options.NoAuth, 'Disable authentication')
     .action(
       async (rootDir: string, options: { http: boolean; auth: boolean }) => {
         const abortController = new AbortController();
@@ -42,13 +59,12 @@ export async function runParquetServer(): Promise<void> {
         abortController.signal.onabort = () => server.stop();
         abortController.signal.throwIfAborted();
 
-        console.log(
-          JSON.stringify({
-            url: server.address,
-            ...(server.authToken && { authToken: server.authToken }),
-            ...(server.encodedCaCert && { caCert: server.encodedCaCert })
-          })
-        );
+        const serverConfig: Config = stringifyJson({
+          url: server.address,
+          ...(server.authToken && { authToken: server.authToken }),
+          ...(server.encodedCaCert && { caCert: server.encodedCaCert })
+        });
+        console.log(serverConfig);
 
         await server.stopped;
       }
@@ -56,3 +72,68 @@ export async function runParquetServer(): Promise<void> {
 
   await program.parseAsync();
 }
+
+/**
+ * Reference implementation of a parquet server runner for tests:
+ * - Reads the server configuration from the spawned process stdout
+ * - Forwards the server logs to the console
+ * - Shuts down the server on dispose
+ */
+export class ParquetServer implements Disposable {
+  readonly #process: ChildProcess;
+  readonly #config: PFrameInternal.ParquetServerConfig;
+  readonly #lineReader: Interface;
+
+  private constructor(
+    process: ChildProcess,
+    config: PFrameInternal.ParquetServerConfig,
+    lineReader: Interface
+  ) {
+    this.#process = process;
+    this.#config = config;
+    this.#lineReader = lineReader;
+  }
+
+  get config(): PFrameInternal.ParquetServerConfig {
+    return this.#config;
+  }
+
+  static async serve(
+    rootDir: string,
+    options?: {
+      http?: boolean;
+      noAuth?: boolean;
+    }
+  ): Promise<ParquetServer> {
+    const nodeFileUrl = import.meta.url;
+    const nodeDirname = dirname(fileURLToPath(nodeFileUrl));
+    const binPath = join(nodeDirname, '..', 'bin', 'parquet-server.mjs');
+
+    const serverProcess = spawn(
+      'node',
+      [
+        binPath,
+        rootDir,
+        ...(options?.http ? [Options.Http] : []),
+        ...(options?.noAuth ? [Options.NoAuth] : [])
+      ],
+      {
+        stdio: ['ignore', 'pipe', 'ignore']
+      }
+    );
+
+    const lineReader = createInterface({ input: serverProcess.stdout! });
+
+    const firstLine = await lineReader[Symbol.asyncIterator]().next();
+    const serverConfig = parseJson(firstLine.value as Config);
+
+    lineReader.on('line', console.log);
+
+    return new ParquetServer(serverProcess, serverConfig, lineReader);
+  }
+
+  [Symbol.dispose](): void {
+    this.#lineReader.close();
+    this.#process.kill();
+  }
+}