# 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

```typescript
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

- [x] WebDAV protocol support (PROPFIND, MKCOL, COPY, MOVE, LOCK, UNLOCK)
- [ ] HTTP/2 support investigation
- [ ] Performance benchmarks