Rustelo/content/public/README.md

# Static File Serving

This directory (`content/public`) contains static files that are served directly by the Rustelo server without any processing. Files placed here can be accessed via HTTP requests using the `/public/` URL prefix.

## How It Works

The server is configured to serve static files from this directory using Axum's `ServeDir` service. When a request is made to `/public/*`, the server will:

1. Look for the corresponding file in the `content/public` directory
2. Serve the file with appropriate MIME type headers
3. Return the file content as-is without any processing

## URL Structure

Files in this directory are accessible via the following URL pattern:
```
https://your-domain.com/public/{path-to-file}
```

### Examples

| File Path | URL |
|-----------|-----|
| `content/public/example.html` | `/public/example.html` |
| `content/public/images/logo.png` | `/public/images/logo.png` |
| `content/public/documents/manual.pdf` | `/public/documents/manual.pdf` |
| `content/public/styles/custom.css` | `/public/styles/custom.css` |
| `content/public/scripts/app.js` | `/public/scripts/app.js` |

## Supported File Types

The server automatically detects and serves the following file types with appropriate MIME types:

- **HTML files** (`.html`, `.htm`) - `text/html`
- **CSS files** (`.css`) - `text/css`
- **JavaScript files** (`.js`) - `application/javascript`
- **Images** (`.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`) - `image/*`
- **PDF documents** (`.pdf`) - `application/pdf`
- **Text files** (`.txt`, `.md`) - `text/plain`
- **JSON files** (`.json`) - `application/json`
- **XML files** (`.xml`) - `application/xml`

## Directory Organization

We recommend organizing your static files in subdirectories for better maintainability:

```
content/public/
├── images/          # Image files (PNG, JPG, SVG, etc.)
├── documents/       # PDF files, Word docs, etc.
├── styles/          # CSS stylesheets
├── scripts/         # JavaScript files
├── fonts/           # Web fonts
├── videos/          # Video files
└── downloads/       # Files for download
```

## Usage Examples

### 1. Serving Images
Place image files in `content/public/images/` and reference them in your content:

```html
<img src="/public/images/logo.png" alt="Logo">
```

### 2. Including CSS Files
Add CSS files to `content/public/styles/` and include them in your HTML:

```html
<link rel="stylesheet" href="/public/styles/custom.css">
```

### 3. JavaScript Files
Place JavaScript files in `content/public/scripts/` and include them:

```html
<script src="/public/scripts/app.js"></script>
```

### 4. Downloadable Documents
Store PDF files or other documents in `content/public/documents/`:

```html
<a href="/public/documents/user-manual.pdf" download>Download User Manual</a>
```

## Security Considerations

- **No server-side processing**: Files are served exactly as they are stored
- **No access control**: All files in this directory are publicly accessible
- **No authentication**: Anyone can access these files if they know the URL
- **File permissions**: Ensure files have appropriate read permissions
- **Content validation**: Validate file uploads if allowing user uploads

## Performance Notes

- Files are served directly by the web server for optimal performance
- Consider using a CDN for better global performance
- Large files should be optimized before placing in this directory
- Browser caching headers are automatically set for static files

## Configuration

The static file serving is configured in `server/src/main.rs`:

```rust
.nest_service("/public", ServeDir::new("content/public"))
```

This maps the `/public` URL prefix to the `content/public` directory.

## Development vs Production

### Development
- Files are served directly from the file system
- Changes to files are immediately visible
- No caching is enforced

### Production
- Consider using a reverse proxy (nginx) for better static file performance
- Implement proper caching headers
- Use a CDN for global distribution
- Compress files (gzip) for better transfer speeds

## Best Practices

1. **Organize by type**: Group similar files in subdirectories
2. **Use descriptive names**: Choose clear, descriptive filenames
3. **Optimize images**: Compress images before uploading
4. **Version control**: Keep track of file changes
5. **Security**: Don't store sensitive files in this directory
6. **Cleanup**: Remove unused files regularly

## Troubleshooting

### File Not Found (404)
- Check that the file exists in the `content/public` directory
- Verify the URL path matches the file path exactly
- Ensure the file has proper read permissions

### Wrong MIME Type
- Check the file extension
- Ensure the file is not corrupted
- Verify the file contains the expected content type

### Access Denied
- Check file permissions on the server
- Verify the server has read access to the directory
- Ensure the file is not being used by another process

## Examples in This Directory

- `example.html` - A complete HTML page demonstrating static file serving
- `styles/custom.css` - A CSS file with common styles and utilities

These files can be accessed at:
- `/public/example.html`
- `/public/styles/custom.css`