101 lines
3.3 KiB
Markdown
101 lines
3.3 KiB
Markdown
|
# 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
|