initial

readme.hints.md

@@ -0,0 +1,100 @@
+# 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