@milaboratories/pframes-rs-serv 1.0.61

package/README.md

@@ -0,0 +1,142 @@
+# @milaboratories/pframes-serv
+
+A high-performance HTTP server for serving Parquet files with full RFC 9110 compliance, authentication support, and optimized caching.
+
+## 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.
+
+## 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
+
+### Exports
+
+#### Public API
+
+- `serve()` - Main server function
+- `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:
+
+### 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.
+
+## 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:
+
+## Request Processing Flow
+
+```text
+┌─────────────────┐
+│ Request Arrives │
+└─────────┬───────┘
+          │
+          ▼
+┌─────────────────────┐
+│ Set Default Headers │ ← Content-Length: 0, Date: now
+│ (All Responses)     │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐    [FAIL] No Token
+│ Check Authentication│────────────┐
+└─────────┬───────────┘            │
+          │ [PASS] Authorized      │
+          ▼                        ▼
+┌─────────────────────┐    ┌──────────────┐
+│ Set Cache Headers   │    │ Return 401   │ ← WWW-Authenticate: Bearer
+└─────────┬───────────┘    │ Unauthorized │
+          │                └──────────────┘
+          ▼
+┌─────────────────────┐    [FAIL] Not GET/HEAD
+│ Check HTTP Method   │────────────┐
+└─────────┬───────────┘            │
+          │ [PASS] Valid Method    │
+          ▼                        ▼
+┌─────────────────────┐    ┌──────────────┐
+│ Parse URL           │    │ Return 405   │ ← Allow: GET, HEAD
+└─────────┬───────────┘    │ Not Allowed  │
+          │                └──────────────┘
+          ▼
+┌─────────────────────┐    [FAIL] Invalid Pattern
+│ Validate .parquet   │────────────┐
+│ Extension           │            │
+└─────────┬───────────┘            │
+          │ [PASS] Valid .parquet  │
+          ▼                        ▼
+┌─────────────────────┐    ┌──────────────┐
+│ Set Content Headers │    │ Return 410   │ ← Permanently Gone
+│ (Accept-Ranges,     │    │ Gone         │
+│  Content-Type)      │    └──────────────┘
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐    [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 │            │
+└─────────┬───────────┘            │
+          │ [PASS] Conditions Met  │
+          ▼                        ▼
+┌─────────────────────┐    ┌──────────────┐
+│ Check If-None-Match │    │ Return 412   │ ← Precondition Failed
+└─────────┬───────────┘    │ Precondition │
+          │                │ Failed       │
+          ▼                └──────────────┘
+          │ [FAIL] Not Modified
+          ├────────────────────────┐
+          │                        ▼
+          │                ┌──────────────┐
+          │                │ Return 304   │ ← ETag, Not Modified
+          │                │ Not Modified │
+          │                └──────────────┘
+          │ [PASS] Modified
+          ▼
+┌─────────────────────┐
+│ Parse Range Header  │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐    [FAIL] Invalid Range
+│ Validate Range      │────────────┐
+│ Against File Size   │            │
+└─────────┬───────────┘            │
+          │ [PASS] Valid Range     │
+          ▼                        ▼
+┌─────────────────────┐    ┌──────────────┐
+│ Set Status & Length │    │ Return 416   │ ← Content-Range: bytes */size
+│ 200 (full) or       │    │ Range Not    │
+│ 206 (partial)       │    │ Satisfiable  │
+└─────────┬───────────┘    └──────────────┘
+          │
+          ▼
+┌─────────────────────┐    [HEAD] Request
+│ Check Request Type  │────────────┐
+└─────────┬───────────┘            │
+          │ [GET] Request          │
+          ▼                        ▼
+┌─────────────────────┐    ┌──────────────┐
+│ Stream File Content │    │ Send Headers │ ← Headers Only
+│ (with range support)│    │ Only (HEAD)  │
+└─────────────────────┘    └──────────────┘
+```

package/bin/parquet-server.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\parquet-server" %*

package/bin/parquet-server.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+import { runParquetServer } from '../dist/index.js';
+runParquetServer(); // all the code is in the TS file

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@milaboratories/pframes-rs-serv",
+  "description": "PFrames - Node.js HTTP(S) Parquet Server",
+  "version": "1.0.61",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "bin": {
+    "parquet-server": "./bin/parquet-server.mjs"
+  },
+  "files": [
+    "src/**/*",
+    "dist/**/*",
+    "bin/**/*"
+  ],
+  "devDependencies": {
+    "@milaboratories/helpers": "1.6.22",
+    "@milaboratories/pl-model-common": "1.19.13",
+    "@milaboratories/pl-model-middle-layer": "1.8.15",
+    "@milaboratories/ts-builder": "1.0.5",
+    "@milaboratories/ts-configs": "1.0.6",
+    "@types/autocannon": "^7.12.7",
+    "@types/node": "^20.19.11",
+    "@vitest/coverage-istanbul": "^3.2.4",
+    "autocannon": "^8.0.0",
+    "commander": "^14.0.0",
+    "selfsigned": "^3.0.1",
+    "typescript": "^5.9.2",
+    "undici": "^7.14.0",
+    "vite": "^7.1.3",
+    "vitest": "^3.2.4"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "homepage": "https://github.com/milaboratory/pframes-rs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/milaboratory/pframes-rs.git"
+  },
+  "scripts": {
+    "ts-build": "pnpm exec ts-builder build --target node",
+    "build": "pnpm run ts-build",
+    "pretest": "pnpm run build",
+    "test": "pnpm exec vitest",
+    "dev-test": "pnpm run test",
+    "coverage-vscode": "pnpm exec vitest run --coverage",
+    "precoverage-html": "pnpm run coverage-vscode",
+    "coverage-html": "pnpm exec vite preview --outDir ./tests/coverage/lcov-report"
+  }
+}

package/src/export.ts

@@ -0,0 +1,23 @@
+import { RequestListener } from 'http';
+import { FileSystemStore } from './fs-store';
+import { createRequestHandler } from './handler';
+import { serve } from './serve';
+import { PFrameInternal } from '@milaboratories/pl-model-middle-layer';
+
+export const HttpHelpers: PFrameInternal.HttpHelpers = {
+  createFsStore: async (
+    options: PFrameInternal.FsStoreOptions
+  ): Promise<PFrameInternal.ObjectStore> => {
+    return await FileSystemStore.init(options);
+  },
+  createRequestHandler: (
+    options: PFrameInternal.RequestHandlerOptions
+  ): RequestListener => {
+    return createRequestHandler(options);
+  },
+  createHttpServer: async (
+    options: PFrameInternal.HttpServerOptions
+  ): Promise<PFrameInternal.HttpServer> => {
+    return await serve(options);
+  }
+};

package/src/fs-store.ts

@@ -0,0 +1,110 @@
+import type { Readable } from 'node:stream';
+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';
+
+/** Object store for serving files from a local directory */
+export class FileSystemStore extends PFrameInternal.ObjectStore {
+  private readonly rootDir: string;
+
+  private constructor(options: PFrameInternal.FsStoreOptions) {
+    super(options);
+
+    this.rootDir = options.rootDir;
+  }
+
+  static async init(
+    options: PFrameInternal.FsStoreOptions
+  ): Promise<FileSystemStore> {
+    const resolvedRootDir = resolve(options.rootDir);
+
+    const rootStats = await stat(resolvedRootDir).catch(() => {
+      throw new Error(
+        `File system store root directory does not exist: ${resolvedRootDir}`
+      );
+    });
+    if (!rootStats.isDirectory()) {
+      throw new Error(
+        `File system store root path is not a directory: ${resolvedRootDir}`
+      );
+    }
+
+    return new FileSystemStore({
+      ...options,
+      rootDir: resolvedRootDir
+    });
+  }
+
+  override async request(
+    filename: PFrameInternal.ParquetFileName,
+    params: {
+      method: PFrameInternal.HttpMethod;
+      range?: PFrameInternal.HttpRange;
+      signal: AbortSignal;
+      callback: (response: PFrameInternal.ObjectStoreResponse) => Promise<void>;
+    }
+  ): Promise<void> {
+    let file: FileHandle;
+    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 {
+      let size: number;
+      try {
+        ({ size } = await file.stat());
+      } catch (error: unknown) {
+        this.logger(
+          'error',
+          `File system store failed to get size of file ${filename}: ${ensureError(error)}`
+        );
+        return await params.callback({ type: 'InternalError' });
+      }
+
+      const range = this.translate(size, params.range);
+      if (!range) {
+        return await params.callback({ type: 'RangeNotSatisfiable', size });
+      }
+
+      if (params.method === 'HEAD') {
+        return await params.callback({ type: 'Ok', size, range });
+      }
+
+      let data: Readable;
+      try {
+        data = createReadStream('ignored', {
+          fd: file.fd,
+          autoClose: false,
+          start: range.start,
+          end: range.end,
+          signal: params.signal
+        });
+        this.logger(
+          'info',
+          `File system store created read stream for ${filename}[${range.start}..=${range.end}]`
+        );
+      } catch (error: unknown) {
+        this.logger(
+          'error',
+          `File system store failed to create read stream for ${filename}[${range.start}..=${range.end}]: ${ensureError(error)}`
+        );
+        return await params.callback({ type: 'InternalError' });
+      }
+
+      return await params
+        .callback({ type: 'Ok', size, range, data })
+        .catch(() => {});
+    } finally {
+      await file.close();
+    }
+  }
+}

package/src/handler.ts

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

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './handler';
+export * from './fs-store';
+export * from './serve';
+export * from './export';
+export * from './parquet-server';

package/src/parquet-server.ts

@@ -0,0 +1,58 @@
+import { Command } from 'commander';
+import { FileSystemStore } from './fs-store';
+import { createRequestHandler } from './handler';
+import { serve } from './serve';
+
+/**
+ * Serves parquet files from the given root directory.
+ * Manages the server lifecycle with graceful shutdown.
+ */
+export async function runParquetServer(): Promise<void> {
+  const program = new Command();
+
+  program
+    .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')
+    .action(
+      async (rootDir: string, options: { http: boolean; auth: boolean }) => {
+        const abortController = new AbortController();
+        process
+          .on('SIGINT', () => abortController.abort())
+          .on('SIGTERM', () => abortController.abort());
+        abortController.signal.throwIfAborted();
+
+        const store = await FileSystemStore.init({
+          rootDir,
+          logger: (level, message) => {
+            const timestamp = new Date(Date.now()).toISOString();
+            console.log(`[${timestamp}] [${level}] ${message}`);
+          }
+        });
+        abortController.signal.throwIfAborted();
+        const handler = createRequestHandler({ store });
+
+        const server = await serve({
+          handler,
+          ...(options.http && { http: true }),
+          ...(!options.auth && { noAuth: true })
+        });
+        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 })
+          })
+        );
+
+        await server.stopped;
+      }
+    );
+
+  await program.parseAsync();
+}

package/src/serve.ts

@@ -0,0 +1,159 @@
+import {
+  createServer as createHttpServer,
+  RequestListener,
+  type Server as HttpServer,
+  type ServerOptions
+} from 'node:http';
+import {
+  createServer as createHttpsServer,
+  Server as HttpsServer
+} from 'node:https';
+import { AddressInfo } from 'node:net';
+import { Deferred } from '@milaboratories/helpers';
+import type { PFrameInternal } from '@milaboratories/pl-model-middle-layer';
+import {
+  base64Encode,
+  Base64Encoded,
+  ensureError,
+  PFrameError
+} from '@milaboratories/pl-model-common';
+import { generate, type GenerateResult } from 'selfsigned';
+import { randomUUID } from 'node:crypto';
+import { authorizeRequestHandler } from './handler';
+
+/** Generate a self-signed certificate for localhost */
+async function generateCertificate(): Promise<GenerateResult> {
+  const generateResult = new Deferred<GenerateResult>();
+  generate(
+    [{ name: 'commonName', value: 'localhost' }],
+    {
+      keySize: 2048,
+      algorithm: 'sha256',
+      extensions: [
+        {
+          name: 'subjectAltName',
+          altNames: [
+            { type: 2, value: 'localhost' }, // DNS
+            { type: 7, ip: '127.0.0.1' }, // IPv4
+            { type: 7, ip: '::1' } // IPv6
+          ]
+        }
+      ]
+    },
+    (error, result) => {
+      if (error) {
+        generateResult.reject(error);
+      } else {
+        generateResult.resolve(result);
+      }
+    }
+  );
+  return await generateResult.promise;
+}
+
+/** Create an object store URL from the server address info. */
+function createObjectStoreUrl(
+  info: AddressInfo,
+  http?: true
+): PFrameInternal.ObjectStoreUrl {
+  const protocol = http ? '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}`
+      );
+  }
+}
+
+/**
+ * Serve HTTP requests using the provided handler.
+ * Returns a promise that resolves when the server is stopped.
+ */
+export async function serve({
+  handler,
+  port = 0,
+  http,
+  noAuth
+}: PFrameInternal.HttpServerOptions): Promise<PFrameInternal.HttpServer> {
+  const started = new Deferred<PFrameInternal.HttpServer>();
+  try {
+    let stopped: Deferred<void> | null = null;
+
+    let authToken: PFrameInternal.HttpAuthorizationToken | undefined;
+    let effectiveHandler: RequestListener = handler;
+    if (!noAuth) {
+      authToken = randomUUID() as PFrameInternal.HttpAuthorizationToken;
+      effectiveHandler = authorizeRequestHandler(effectiveHandler, authToken);
+    }
+
+    // Create HTTP server
+    let certificateBase64:
+      | Base64Encoded<PFrameInternal.PemCertificate>
+      | undefined;
+    const defaultOptions: ServerOptions = {
+      keepAlive: true
+    };
+    let server: HttpServer | HttpsServer;
+
+    if (http) {
+      server = createHttpServer(defaultOptions, effectiveHandler);
+    } else {
+      const { cert, private: key, public: ca } = await generateCertificate();
+      certificateBase64 = 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(
+          server.address() as AddressInfo,
+          http
+        );
+        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 stopped(): Promise<void> {
+            return stopped!.promise;
+          },
+          stop(): Promise<void> {
+            abortController.abort();
+            return stopped!.promise;
+          }
+        });
+      })
+      .on('error', (err) => {
+        started.reject(err);
+        stopped?.reject(err);
+      })
+      .on('close', () => stopped?.resolve())
+      .listen({
+        host: 'localhost',
+        port,
+        signal: abortController.signal
+      });
+  } catch (error: unknown) {
+    started.reject(ensureError(error));
+  }
+
+  return started.promise;
+}

package/src/utils/etag.ts

@@ -0,0 +1,20 @@
+import { Branded } from '@milaboratories/pl-model-common';
+import { PFrameInternal } from '@milaboratories/pl-model-middle-layer';
+
+/**
+ * See <https://datatracker.ietf.org/doc/html/rfc9110#section-8.8.3>
+ *
+ * Examples:
+ *
+ * ```text
+ * ETag: "xyzzy"
+ * ETag: W/"xyzzy"
+ * ```
+ */
+export type Etag = Branded<string, 'Etag'>;
+
+export function createETag(filename: PFrameInternal.ParquetFileName): Etag {
+  // For immutable files, use URL-safe base64 encoded filename as ETag
+  const filenameETag = Buffer.from(filename, 'utf8').toString('base64url');
+  return `"${filenameETag}"` as Etag;
+}

package/src/utils/filename.ts

@@ -0,0 +1,16 @@
+import { PFrameInternal } from '@milaboratories/pl-model-middle-layer';
+import { IncomingMessage } from 'node:http';
+
+const PARQUET_FILENAME_REGEX = /^\/([\w\-.]+.parquet)$/;
+
+export function getFilenameFromUrl(
+  request: IncomingMessage
+): PFrameInternal.ParquetFileName | null {
+  const url = request.url;
+  if (url === undefined) return null;
+
+  const match = url.match(PARQUET_FILENAME_REGEX);
+  if (!match) return null;
+
+  return match[1] as PFrameInternal.ParquetFileName;
+}

package/src/utils/headers.ts

@@ -0,0 +1,31 @@
+'use strict';
+
+/** HTTP header names used in the parquet server handler */
+export const HeaderName = {
+  Accept: 'accept',
+  AcceptRanges: 'accept-ranges',
+  Allow: 'allow',
+  Authorization: 'authorization',
+  CacheControl: 'cache-control',
+  ContentLength: 'content-length',
+  ContentRange: 'content-range',
+  ContentType: 'content-type',
+  Date: 'date',
+  ETag: 'etag',
+  IfMatch: 'if-match',
+  IfModifiedSince: 'if-modified-since',
+  IfNoneMatch: 'if-none-match',
+  IfUnmodifiedSince: 'if-unmodified-since',
+  LastModified: 'last-modified',
+  Range: 'range',
+  WWWAuthenticate: 'www-authenticate'
+} as const;
+
+/** HTTP header values used in the parquet server handler */
+export const HeaderValue = {
+  AcceptRanges: 'bytes',
+  Allow: 'GET, HEAD',
+  CacheControl: 'public, immutable, max-age=31536000',
+  ContentType: 'application/octet-stream',
+  WWWAuthenticate: 'Bearer realm="parquet-server"'
+} as const;

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+export * from './filename';
+export * from './etag';
+export * from './headers';
+export * from './options';
+export * from './range';
+export * from './method';
+export * from './status';

package/src/utils/method.ts

@@ -0,0 +1,20 @@
+import { PFrameInternal } from '@milaboratories/pl-model-middle-layer';
+import { IncomingHttpHeaders } from 'node:http';
+
+export function isGetOrHead(
+  method: IncomingHttpHeaders['method']
+): method is PFrameInternal.HttpMethod {
+  return method === 'GET' || method === 'HEAD';
+}
+
+export function isGet(
+  method: PFrameInternal.HttpMethod
+): method is Extract<PFrameInternal.HttpMethod, 'GET'> {
+  return method === 'GET';
+}
+
+export function isHead(
+  method: PFrameInternal.HttpMethod
+): method is Extract<PFrameInternal.HttpMethod, 'HEAD'> {
+  return method === 'HEAD';
+}

package/src/utils/options.ts

@@ -0,0 +1,152 @@
+import { IncomingHttpHeaders, IncomingMessage } from 'node:http';
+import { type Etag } from './etag';
+
+type EtagMatchType =
+  | {
+      type: 'match';
+      value: Etag[];
+    }
+  | {
+      type: 'wildcard';
+    };
+
+class EtagMatch {
+  private constructor(private readonly etagMatch: EtagMatchType) {}
+
+  static parse(etagMatch: string | undefined): EtagMatch | null {
+    if (etagMatch === undefined) return null;
+    if (etagMatch === '*') {
+      return new EtagMatch({ type: 'wildcard' });
+    } else {
+      return new EtagMatch({
+        type: 'match',
+        value: etagMatch.split(',').map((etag) => etag.trim() as Etag)
+      });
+    }
+  }
+
+  matches(etag: Etag): boolean {
+    switch (this.etagMatch.type) {
+      case 'match':
+        return this.etagMatch.value.includes(etag);
+      case 'wildcard':
+        return true;
+    }
+  }
+}
+
+class DateMatch {
+  private constructor(private readonly mtime: Date) {}
+
+  static parse(dateMatch: string | undefined): DateMatch | null {
+    if (dateMatch === undefined) return null;
+    const time = Date.parse(dateMatch);
+    if (isNaN(time)) return null;
+    return new DateMatch(new Date(time));
+  }
+
+  matches(mtime: Date): boolean {
+    return this.mtime.getTime() / 1_000 === mtime.getTime() / 1_000;
+  }
+}
+
+export class Options {
+  /**
+   * See <https://datatracker.ietf.org/doc/html/rfc9110#name-if-match>
+   *
+   * Examples:
+   *
+   * ```text
+   * If-Match: "xyzzy"
+   * If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+   * If-Match: *
+   * ```
+   */
+  private ifMatch: EtagMatch | null;
+
+  /**
+   * See <https://datatracker.ietf.org/doc/html/rfc9110#section-13.1.2>
+   *
+   * Examples:
+   *
+   * ```text
+   * If-None-Match: "xyzzy"
+   * If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+   * If-None-Match: *
+   * ```
+   */
+  private ifNoneMatch: EtagMatch | null;
+
+  /**
+   * See <https://datatracker.ietf.org/doc/html/rfc9110#section-13.1.3>
+   *
+   * Examples:
+   *
+   * ```text
+   * If-Modified-Since: Mon, 07 Jan 2002 19:43:36 GMT
+   * ```
+   */
+  private ifModifiedSince: DateMatch | null;
+
+  /**
+   * See <https://datatracker.ietf.org/doc/html/rfc9110#section-13.1.4>
+   *
+   * Examples:
+   *
+   * ```text
+   * If-Unmodified-Since: Mon, 07 Jan 2002 19:43:36 GMT
+   * ```
+   */
+  private ifUnmodifiedSince: DateMatch | null;
+
+  constructor(request: IncomingMessage) {
+    this.ifMatch = EtagMatch.parse(request.headers['if-match']);
+    this.ifNoneMatch = EtagMatch.parse(request.headers['if-none-match']);
+    this.ifModifiedSince = DateMatch.parse(
+      request.headers['if-modified-since']
+    );
+    this.ifUnmodifiedSince = DateMatch.parse(
+      request.headers['if-unmodified-since']
+    );
+  }
+
+  /**
+   * RFC 9110 section 13.1.1: If-Match precondition evaluation
+   * RFC 9110 section 13.1.4: If-Unmodified-Since precondition evaluation
+   * See <https://datatracker.ietf.org/doc/html/rfc9110#section-13.1.1>
+   * See <https://datatracker.ietf.org/doc/html/rfc9110#section-13.1.4>
+   */
+  preconditionFailed(etag: Etag, mtime: Date): boolean {
+    // If-Match precondition takes precedence
+    if (this.ifMatch !== null && !this.ifMatch.matches(etag)) {
+      return true;
+    }
+
+    // If-Unmodified-Since precondition (only if no If-Match header)
+    if (this.ifMatch === null && this.ifUnmodifiedSince !== null) {
+      return !this.ifUnmodifiedSince.matches(mtime);
+    }
+
+    return false;
+  }
+
+  /**
+   * RFC 9110 section 13.1.2: If-None-Match precondition evaluation
+   * RFC 9110 section 13.1.3: If-Modified-Since precondition evaluation
+   * See <https://datatracker.ietf.org/doc/html/rfc9110#section-13.1.2>
+   * See <https://datatracker.ietf.org/doc/html/rfc9110#section-13.1.3>
+   */
+  notModified(etag: Etag, mtime: Date): boolean {
+    // If-None-Match takes precedence over If-Modified-Since
+    if (this.ifNoneMatch !== null) {
+      return this.ifNoneMatch.matches(etag);
+    }
+
+    // If-Modified-Since (only if no If-None-Match header)
+    if (this.ifModifiedSince !== null) {
+      return this.ifModifiedSince.matches(mtime);
+    }
+
+    return false;
+  }
+}

package/src/utils/range.ts

@@ -0,0 +1,40 @@
+import { PFrameInternal } from '@milaboratories/pl-model-middle-layer';
+import { IncomingMessage } from 'node:http';
+
+export function parseRange(
+  request: IncomingMessage
+): PFrameInternal.HttpRange | null | undefined {
+  const range = request.headers['range'];
+  if (range === undefined) return undefined;
+
+  const match = range.match(/^bytes=(\d*)-(\d*)$/);
+  if (!match) return null;
+
+  const [, startStr, endStr] = match;
+  const start = startStr ? parseInt(startStr, 10) : null;
+  const end = endStr ? parseInt(endStr, 10) : null;
+  if (
+    (start !== null && (isNaN(start) || start < 0)) ||
+    (end !== null && (isNaN(end) || end < 0)) ||
+    (start !== null && end !== null && start > end)
+  )
+    return null;
+
+  // Both start and end are specified - bounded range
+  if (start !== null && end !== null) {
+    return { type: 'bounded', start, end };
+  }
+
+  // Only start is specified - offset range (e.g., bytes=500-)
+  if (start !== null && end === null) {
+    return { type: 'offset', offset: start };
+  }
+
+  // Only end is specified - suffix range (e.g., bytes=-500)
+  if (start === null && end !== null) {
+    return { type: 'suffix', suffix: end };
+  }
+
+  // Neither start nor end specified (bytes=-) - invalid
+  return null;
+}

package/src/utils/status.ts

@@ -0,0 +1,15 @@
+/** HTTP status codes used in the parquet server handler */
+export const StatusCode = {
+  Ok: 200, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200>
+  PartialContent: 206, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206>
+  NotModified: 304, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304>
+  BadRequest: 400, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400>
+  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>
+  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>
+  InternalServerError: 500, // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500>
+  GatewayTimeout: 504 // <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504>
+} as const;