# 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.