@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(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 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

Public API

• serve() - Main server function
• createRequestHandler() - HTTP request handler factory
• FileSystemStore - Local file system object store implementation

The HttpHelpers export contains functions intended for re-export through the @milaboratories/pframes-rs-node package.

Binary Script

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) and RFC 9111 (HTTP Caching). 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

┌─────────────────┐
│ Request Arrives │
└─────────┬───────┘
          │
          ▼
┌─────────────────────┐
│ Set Default Headers │ ← Content-Length: 0, Date: now
│ (All Responses)     │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐    [FAIL] Invalid/Missing Token
│ Check Bearer Token  │────────────┐
│ (Timing-Safe)       │            │
└─────────┬───────────┘            │
          │ [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] GET or HEAD     │
          ▼                        ▼
┌─────────────────────┐    ┌──────────────┐
│ Parse URL &         │    │ Return 405   │ ← Allow: GET, HEAD
│ Extract Filename    │    │ Not Allowed  │
└─────────┬───────────┘    └──────────────┘
          │
          ▼
┌─────────────────────┐    [FAIL] Invalid Pattern
│ Validate .parquet   │────────────┐
│ Extension           │            │
└─────────┬───────────┘            │
          │ [PASS] Valid .parquet  │
          ▼                        ▼
┌─────────────────────┐    ┌──────────────┐
│ Set Content Headers │    │ Return 410   │
│ (Accept-Ranges,     │    │ Gone         │
│  Content-Type),     │    └──────────────┘
│ Generate ETag &     │ ← ETag from filename
│ Set Cache Headers   │   Last-Modified: UTC(0)
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐    [FAIL] Precondition Failed
│ Check If-Match &    │────────────┐
│ If-Unmodified-Since │            │
└─────────┬───────────┘            │
          │                        │
          ▼                        ▼
┌─────────────────────┐    ┌─────────────────────┐
│ Check If-None-Match │    │ Return 412          │
│ & If-Modified-Since │    │ Precondition Failed │
└─────────┬───────────┘    └─────────────────────┘
          │ [FAIL] Not Modified
          ├────────────────────────┐
          │                        ▼
          │                ┌──────────────┐
          │                │ Return 304   │
          │                │ Not Modified │
          │                └──────────────┘
          ▼
┌─────────────────────┐    [FAIL] Invalid Range
│ Parse Range Header  │────────────┐
└─────────┬───────────┘            │
          │ [PASS] Valid Range     │
          ▼                        ▼
┌─────────────────────┐    ┌──────────────┐
│ 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] Headers Only
│ Check Request       │────────────┐
│ Method              │            │
└─────────┬───────────┘            │
          │ [GET] Send Body        │
          ▼                        ▼
┌─────────────────────┐    ┌──────────────┐
│ Stream File Content │    │ Send Headers │
└─────────────────────┘    └──────────────┘