balda-js 0.0.1 → 0.0.2

package/docs/docs/plugins/static.md

@@ -1,352 +0,0 @@
----
-sidebar_position: 4
----
-
-# Static Plugin
-
-The Static plugin serves static files from a specified directory. It automatically handles file serving, MIME type detection, and provides a clean API for serving static assets like images, CSS, JavaScript, and other files.
-
-## Features
-
-- **Automatic MIME Type Detection**: Detects content types based on file extensions
-- **Path-Based Routing**: Serves files from any API path
-- **Security**: Only serves files from the specified directory
-- **Performance**: Efficient file serving with proper headers
-- **Swagger Integration**: Optional Swagger documentation for static routes
-
-## Basic Configuration
-
-### Simple Setup
-
-```typescript
-import { Server } from 'balda-js';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    static: 'public'
-  }
-});
-```
-
-### With Custom Path
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    static: {
-      path: 'assets',
-      root: './public'
-    }
-  }
-});
-```
-
-## Configuration Options
-
-### Basic Configuration
-
-```typescript
-// Serve from 'public' directory at '/public' path
-static: 'public'
-
-// Serve from 'assets' directory at '/assets' path
-static: 'assets'
-
-// Serve from 'static' directory at '/static' path
-static: 'static'
-```
-
-### Advanced Configuration
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    static: {
-      path: 'assets',
-      root: './public',
-      swagger: {
-        name: 'Static Assets',
-        description: 'Serve static files and assets',
-        service: 'StaticFiles'
-      }
-    }
-  }
-});
-```
-
-## Usage Examples
-
-### Basic File Serving
-
-```typescript
-// Directory structure:
-// public/
-//   ├── index.html
-//   ├── css/
-//   │   └── style.css
-//   ├── js/
-//   │   └── app.js
-//   └── images/
-//       └── logo.png
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    static: 'public'
-  }
-});
-
-// Files will be available at:
-// http://localhost:3000/public/index.html
-// http://localhost:3000/public/css/style.css
-// http://localhost:3000/public/js/app.js
-// http://localhost:3000/public/images/logo.png
-```
-
-### Custom Path Configuration
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    static: 'assets' // Serves from 'assets' directory
-  }
-});
-
-// Files will be available at:
-// http://localhost:3000/assets/index.html
-// http://localhost:3000/assets/css/style.css
-```
-
-### Multiple Static Directories
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    static: ['public', 'assets', 'uploads']
-  }
-});
-
-// Files will be available at:
-// http://localhost:3000/public/...
-// http://localhost:3000/assets/...
-// http://localhost:3000/uploads/...
-```
-
-## File Types and MIME Types
-
-The static plugin automatically detects MIME types for common file extensions:
-
-### Supported File Types
-
-| Extension | MIME Type | Description |
-|-----------|-----------|-------------|
-| `.html` | `text/html` | HTML files |
-| `.css` | `text/css` | CSS stylesheets |
-| `.js` | `application/javascript` | JavaScript files |
-| `.png` | `image/png` | PNG images |
-| `.jpg`, `.jpeg` | `image/jpeg` | JPEG images |
-| `.gif` | `image/gif` | GIF images |
-| `.svg` | `image/svg+xml` | SVG images |
-| `.json` | `application/json` | JSON files |
-| `.txt` | `text/plain` | Text files |
-| `.ico` | `image/x-icon` | Favicon files |
-| `.webp` | `image/webp` | WebP images |
-| `.mp4` | `video/mp4` | MP4 videos |
-| `.mp3` | `audio/mpeg` | MP3 audio |
-| `.wav` | `audio/wav` | WAV audio |
-| `.ogg` | `audio/ogg` | OGG audio |
-| `.webm` | `video/webm` | WebM videos |
-
-### Custom MIME Types
-
-For unsupported file types, the plugin defaults to `application/octet-stream`.
-
-## Security Considerations
-
-### Directory Traversal Protection
-
-The static plugin automatically protects against directory traversal attacks:
-
-```typescript
-// ❌ This will NOT work (directory traversal attempt)
-// GET /public/../../../etc/passwd
-
-// ✅ This will work (valid file path)
-// GET /public/css/style.css
-```
-
-### File Access Control
-
-```typescript
-// Only files within the specified directory are accessible
-const server = new Server({
-  port: 3000,
-  plugins: {
-    static: 'public' // Only files in ./public are served
-  }
-});
-
-// Files outside the public directory are not accessible
-// GET /public/../secret.txt -> 404 Not Found
-```
-
-## Performance Optimization
-
-### Caching Headers
-
-Consider adding caching middleware for static assets:
-
-```typescript
-@controller('/public')
-export class StaticController {
-  @get('/*')
-  async serveStatic(req: Request, res: Response) {
-    // Add caching headers for static assets
-    res.setHeader('Cache-Control', 'public, max-age=31536000'); // 1 year
-    res.setHeader('ETag', generateETag(req.url));
-
-    // Serve the file
-    return staticFileHandler(req, res, 'public');
-  }
-}
-```
-
-### Compression
-
-For better performance, consider enabling compression:
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    static: 'public',
-    // Add compression plugin for static assets
-    compression: {
-      filter: (req) => {
-        // Compress static assets
-        return req.url.startsWith('/public/');
-      }
-    }
-  }
-});
-```
-
-## Error Handling
-
-### File Not Found
-
-```typescript
-// Request: GET /public/nonexistent.html
-// Response: 404 Not Found
-{
-  "error": "Route not found",
-  "message": "GET /public/nonexistent.html not found"
-}
-```
-
-### Method Not Allowed
-
-```typescript
-// Request: POST /public/index.html
-// Response: 405 Method Not Allowed
-{
-  "error": "Method not allowed",
-  "message": "POST not allowed for /public/index.html"
-}
-```
-
-## Integration with Other Plugins
-
-### With CORS
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    cors: {
-      origin: '*',
-      methods: ['GET', 'HEAD']
-    },
-    static: 'public'
-  }
-});
-```
-
-### With Helmet
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    helmet: {
-      contentSecurityPolicy: {
-        directives: {
-          defaultSrc: ["'self'"],
-          styleSrc: ["'self'", "'unsafe-inline'"],
-          scriptSrc: ["'self'"],
-          imgSrc: ["'self'", "data:", "https:"]
-        }
-      }
-    },
-    static: 'public'
-  }
-});
-```
-
-## Swagger Documentation
-
-### Basic Swagger Integration
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    static: {
-      path: 'public',
-      swagger: {
-        name: 'Static Files',
-        description: 'Serve static files and assets',
-        service: 'StaticFiles'
-      }
-    }
-  }
-});
-```
-
-### Custom Swagger Configuration
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    static: {
-      path: 'assets',
-      swagger: {
-        name: 'Asset Files',
-        description: 'Serve application assets',
-        service: 'Assets',
-        responses: {
-          "200": {
-            type: "object",
-            properties: {
-              file: { type: "string" },
-              size: { type: "number" }
-            }
-          },
-          "404": {
-            type: "object",
-            properties: {
-              error: { type: "string" }
-            }
-          }
-        }
-      }
-    }
-  }
-});
-```