@yamf/services-file-server

Static file serving service for YAMF microservices with flexible routing and security features.

Installation

npm install @yamf/services-file-server

Quick Start

import { createStaticFileService } from '@yamf/services-file-server'

const staticServer = await createStaticFileService({
  rootDir: './public',
  urlRoot: '/assets',
  fileMap: {
    '/': 'index.html',
    '/styles/*': 'css',
    '/scripts/*': 'js',
    '/images/*': 'images'
  }
})

// Now visit: http://localhost:9999/assets/styles/main.css

Features

• Flexible Routing - Map URL patterns to file paths
• MIME Type Detection - Automatic content-type headers
• Range Request Support - Enable audio/video seeking
• Path Traversal Protection - Basic security features
• Wildcard Patterns - Directory-level routing
• Auto-refresh - Development mode with live reload

Configuration

Basic Setup

await createStaticFileService({
  rootDir: './public',      // Base directory for files
  urlRoot: '/static',       // URL prefix
  simpleSecurity: true      // Enable path traversal protection
})

File Mapping

await createStaticFileService({
  rootDir: './public',
  fileMap: {
    // Direct mapping
    '/': 'index.html',
    
    // Wildcard directory mapping
    '/css/*': 'styles',
    '/js/*': 'scripts',
    
    // Specific file mapping
    '/favicon.ico': 'assets/favicon.ico',
    
    // Nested paths
    '/assets/images/*': 'public/images'
  }
})

URL Patterns

Direct Files

fileMap: {
  '/': 'index.html',              // http://localhost/
  '/about': 'about.html'          // http://localhost/about
}

Wildcard Directories

fileMap: {
  '/styles/*': 'css',             // http://localhost/styles/main.css
  '/scripts/*': 'js',             // http://localhost/scripts/app.js
  '/downloads/*': 'public/files'  // http://localhost/downloads/doc.pdf
}

SPA Mode (First-Class Fallback)

Use spa when you want client-side routes to resolve to a single entry file (index.html) while keeping API/data routes as real 404s.

await createStaticFileService({
  rootDir: './public',
  fileMap: {
    '/': 'index.html',
    '/assets/*': 'assets'
  },
  spa: {
    entry: 'index.html',
    excludePrefixes: ['/api', '/assets', '/audio', '/images'],
    excludeExtensions: true
  }
})

Behavior:

• Unknown routes like /dashboard fall back to index.html
• Missing extension paths like /missing.js remain 404
• Excluded prefixes (for APIs or data paths) remain 404 when missing

fileMap['/*'] still works for legacy behavior, but spa is now the recommended pattern for SPAs.

Advanced Features

Range Requests (Audio/Video Streaming)

The file server automatically supports HTTP range requests, enabling:

• Video/audio seeking
• Bandwidth-efficient streaming
• Progressive downloads

// Range requests are enabled by default
// Browser automatically sends: Range: bytes=0-1023
// Server responds with: 206 Partial Content

Auto-refresh (Development Mode)

import { createStaticFileService } from '@yamf/services-file-server'

await createStaticFileService({
  rootDir: './public',
  autoRefresh: true,      // Enable live reload
  refreshInterval: 1000   // Check every second
})

Security

Path Traversal Protection

await createStaticFileService({
  simpleSecurity: true  // Blocks paths with '..' or null bytes
})

// Blocked requests:
// - /files/../../../etc/passwd
// - /files/%00.txt
// - /files/..%2F..%2Fetc%2Fpasswd

simpleSecurityCheck blocks sensitive system directories by path segment (for example /etc), while allowing normal paths that only contain those strings (for example /library/app.js).

MIME Types

Automatic content-type detection for common file types:

• Text: .html, .css, .js, .txt, .json, .xml
• Images: .jpg, .png, .gif, .svg, .webp, .ico
• Audio: .mp3, .wav, .ogg, .m4a, .flac
• Video: .mp4, .webm, .ogv, .mov
• Documents: .pdf, .zip, .tar, .gz

Use Cases

• Serve static website assets
• Host downloadable files
• Stream audio/video content
• Provide API documentation
• Development server with live reload

Performance

• Streaming - Files are streamed, not loaded into memory
• Caching - Browser caching headers included
• Range Requests - Efficient partial content delivery
• Zero Dependencies - Pure Node.js implementation

License

MIT