151 lines
4.4 KiB
Markdown
151 lines
4.4 KiB
Markdown
# Image Server
|
|
|
|
A FastAPI-based image server that serves files from directories or ZIP archives using hashed paths for secure, randomized access. The server provides a full-screen image viewing experience with navigation controls and optional auto-advance features.
|
|
|
|
## Features
|
|
|
|
- **Secure File Access**: Files are accessed via SHA-256 hashes of their paths (with salt) rather than direct file paths
|
|
- **Multiple Sources**: Supports serving from directories, individual ZIP files, or glob patterns (e.g., `*.zip`)
|
|
- **Password-protected ZIPs**: HTTP Basic Auth for encrypted files inside ZIP archives
|
|
- **Beautiful UI**: Full-screen responsive image viewer with keyboard navigation
|
|
- **Navigation Controls**:
|
|
- Previous/Next buttons (clickable chevrons or arrow keys)
|
|
- Random access mode
|
|
- Ordered sequential access with configurable delay
|
|
- Play/pause toggle for auto-advance
|
|
- **Keyboard Shortcuts**:
|
|
- Left/Right Arrow or H/L: Navigate previous/next
|
|
- Space: Toggle play/pause
|
|
- +/= or J: Increase slide delay
|
|
- - or K: Decrease slide delay
|
|
- O: Toggle between ordered and random modes
|
|
- **MIME Type Detection**: Automatically sets correct content types for served files
|
|
- **Health Check Endpoint**: Monitor server status and indexed file count
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.13 or higher
|
|
- [UV](https://github.com/astral-sh/uv) package manager (recommended) or pip
|
|
|
|
### Using UV (Recommended)
|
|
|
|
```bash
|
|
cd image_server
|
|
uv sync
|
|
```
|
|
|
|
### Using pip
|
|
|
|
```bash
|
|
pip install fastapi uvicorn
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# Serve files from a directory
|
|
uv run main.py /path/to/your/images
|
|
|
|
# Serve files from a ZIP archive
|
|
uv run main.py /path/to/archive.zip
|
|
|
|
# Serve files matching a glob pattern
|
|
uv run main.py "path/to/images/*.zip"
|
|
```
|
|
|
|
### Server Options
|
|
|
|
```bash
|
|
uv run main.py [SOURCE] [OPTIONS]
|
|
|
|
Arguments:
|
|
SOURCE Path to directory, ZIP archive, or glob pattern (e.g., *.zip, path/to/zips/*.zip)
|
|
|
|
Options:
|
|
--host TEXT Host to bind to (default: 0.0.0.0)
|
|
--port INTEGER Port to bind to (default: 8000)
|
|
--salt TEXT Salt for hashing file paths (default: random)
|
|
-h, --help Show help message and exit
|
|
```
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Start server on default port 8000
|
|
uv run main.py ./photos
|
|
|
|
# Start server on custom host and port
|
|
uv run main.py ./photos --host 127.0.0.1 --port 3000
|
|
|
|
# Start server with custom salt for consistent hashing
|
|
uv run main.py ./photos --salt mysecretkey123
|
|
|
|
# Start server serving from ZIP files
|
|
uv run main.py ./archives/*.zip
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### File Access
|
|
|
|
- `GET /api/{file_hash}/data` — Retrieve file data by hash
|
|
- Returns: File content with appropriate Content-Type header
|
|
- Response: StreamingResponse of the file data
|
|
|
|
### Navigation Pages
|
|
|
|
- `GET /{file_hash}` — View file with navigation controls (browse mode)
|
|
- Displays image with previous/next navigation
|
|
|
|
- `GET /{file_hash}?order=next&delay=5` — View file with auto-refresh
|
|
- `order`: `"next"` (sequential) or `"random"`
|
|
- `delay`: Seconds before auto-advancing
|
|
- Clicking the image pauses auto-refresh
|
|
|
|
### Special Endpoints
|
|
|
|
- `GET /` — Redirect to a random file
|
|
- `GET /?order=next&delay=5` — Redirect to random file with order/delay settings
|
|
- `GET /api/health` — Health check endpoint
|
|
- Returns: JSON with status and file count
|
|
|
|
## How It Works
|
|
|
|
### File Indexing
|
|
|
|
When started, the server indexes all files from the provided source(s):
|
|
- For directories: Walks the directory tree and indexes all files
|
|
- For ZIP archives: Indexes all files within the archive
|
|
- For glob patterns: Processes each matching file
|
|
|
|
Each file is assigned a unique SHA-256 hash based on:
|
|
- File path (relative to source or within ZIP)
|
|
- Salt value (random or user-provided)
|
|
|
|
### Security
|
|
|
|
- Direct file path access is prevented
|
|
- Files can only be accessed via their cryptographic hashes
|
|
- Salt prevents hash prediction attacks
|
|
- No filesystem traversal vulnerabilities
|
|
- Password-protected ZIP files require HTTP Basic Auth
|
|
|
|
### User Interface
|
|
|
|
The server serves a single-page application (`frontend.html`) that provides:
|
|
- Full-screen image display
|
|
- Click-to-navigate on image
|
|
- Chevron buttons for previous/next navigation
|
|
- Play/pause button for auto-advance control
|
|
- Responsive design that works on mobile and desktop
|
|
|
|
## Dependencies
|
|
|
|
- **FastAPI** — Modern web framework for building APIs
|
|
- **Uvicorn** — ASGI server for running the application
|
|
- **Python Standard Library** — hashlib, mimetypes, secrets, zipfile, etc.
|