smartserve/readme.hints.md

SmartServe Development Hints

Architecture Overview

SmartServe is a cross-platform HTTP server for Node.js, Deno, and Bun using:

• Web Standards API (Request/Response) for cross-platform compatibility
• TC39 Stage 3 decorators (TypeScript 5.0+) for route definition
• Adapter pattern for runtime-specific implementations

Key Files

Core

• ts/core/smartserve.classes.smartserve.ts - Main server class
• ts/core/smartserve.interfaces.ts - All type definitions
• ts/core/smartserve.errors.ts - HTTP error classes

Adapters

• ts/adapters/adapter.factory.ts - Runtime detection via @push.rocks/smartenv
• ts/adapters/adapter.node.ts - Node.js with Request/Response conversion
• ts/adapters/adapter.deno.ts - Deno (zero overhead, native)
• ts/adapters/adapter.bun.ts - Bun (zero overhead, native)

Decorators

• ts/decorators/decorators.route.ts - @Route class decorator
• ts/decorators/decorators.methods.ts - @Get, @Post, etc.
• ts/decorators/decorators.interceptors.ts - @Guard, @Transform, @Intercept
• ts/decorators/decorators.registry.ts - Controller registration and route matching

Static Files

• ts/files/file.server.ts - Static file serving with streaming, ETags, directory listing
• ts/utils/utils.mime.ts - MIME type detection
• ts/utils/utils.etag.ts - ETag generation

Protocols

• ts/protocols/webdav/webdav.handler.ts - WebDAV RFC 4918 handler
• ts/protocols/webdav/webdav.xml.ts - XML generation (multistatus, lock responses)
• ts/protocols/webdav/webdav.types.ts - WebDAV type definitions

Decorator System

Uses TC39 decorators (NOT experimental decorators). Metadata stored via Symbol property on classes.

Interceptor Execution Order (Onion Model)

Request → Class Guards → Method Guards → Handler → Method Transforms → Class Transforms → Response

Guard vs Transform vs Intercept

• @Guard(fn) = @Intercept({ request: fn }) - returns boolean (true=allow, false=403)
• @Transform(fn) = @Intercept({ response: fn }) - modifies response
• @Intercept({ request?, response? }) - full control

Dependencies

Required:

• @push.rocks/smartenv - Runtime detection
• @push.rocks/smartpath - Path utilities
• @push.rocks/smartlog - Logging
• @push.rocks/lik - Collections

Optional:

• ws - WebSocket support for Node.js (Deno/Bun have native)

WebDAV Usage

import { SmartServe } from '@push.rocks/smartserve';

const server = new SmartServe({
  port: 8080,
  webdav: {
    root: '/path/to/files',
    auth: (ctx) => {
      // Optional auth - return true to allow, false to reject
      const auth = ctx.headers.get('Authorization');
      return auth === 'Basic dXNlcjpwYXNz';
    },
    locking: true, // Enable file locking (RFC 4918)
  }
});

await server.start();
// Mount at http://localhost:8080 as network drive

Supported WebDAV Methods

• OPTIONS - Capability discovery
• PROPFIND - Directory listing and file metadata
• PROPPATCH - Property modification (returns 403)
• MKCOL - Create directory
• COPY - Copy files/directories
• MOVE - Move/rename files/directories
• LOCK/UNLOCK - Exclusive write locking
• GET/HEAD/PUT/DELETE - Standard file operations

TODO

• WebDAV protocol support (PROPFIND, MKCOL, COPY, MOVE, LOCK, UNLOCK)
• HTTP/2 support investigation
• Performance benchmarks