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:

<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:

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

3. JavaScript Files

Place JavaScript files in content/public/scripts/ and include them:

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

4. Downloadable Documents

Store PDF files or other documents in content/public/documents/:

<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:

.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