bhs/.github/copilot-instructions.md

Black Hole Share – AI Guide

• Purpose: lightweight Actix-Web service for ephemeral image/text sharing; uploads saved as JSON files on disk and purged after their TTL.
• Base directory is data/: the server uses relative paths data/html/, data/logs/, data/storage/. Run from repo root locally; Docker mounts ./data:/data.
• HTTP entrypoint and routing live in src/main.rs: / serves index.html, /bhs/{id} serves view.html, /api/upload and /api/content/{id} registered from the API module, catch-all serves other static files under html/ (list cached at startup via STATIC_PAGES).
• Request JSON bodies capped at ~3 MiB via web::JsonConfig. Background cleanup task runs every 60s to delete expired assets in storage/.
• Upload API in src/api.rs: accepts JSON { duration: minutes, content_type, content }; text/plain content is stored raw bytes, other types are base64-decoded. On success returns { "link": "/bhs/<uuid>" }.
• Fetch API in src/api.rs: loads {id} from storage/, rejects missing or expired assets, responds with original MIME and bytes.
• Asset model and persistence in src/data_mgt.rs: assets serialized as JSON files named by UUID, with expires_at computed from share_duration (minutes). Cleanup logs removals to stdout.
• Logging helper in src/logs.rs: appends access lines with timing, IPs, scheme, UA to logs/access.log; runs for every handled request.
• Frontend upload page data/html/index.html: JS handles drag/drop, paste, or file picker; converts images to base64 or keeps text, POSTs to /api/upload, shows returned link and copies to clipboard. Styling/theme in data/html/style.css.
• Viewer page data/html/view.html: fetches /api/content/{id}, renders images with zoom overlay or text with zoomable modal; shows error when content missing/expired.
• Environment: BIND_ADDR and BIND_PORT (defaults 0.0.0.0:8080) are read via LazyLock on startup; tokio multi-thread runtime used.
• Build/dev: cargo run --release from repo root (ensure data/ exists with html/, logs/, storage/), or use Dockerfile (Arch base + rustup build) and docker-compose (Traefik labels, port 8080→80, volume ./data:/data).
• No test suite present; verify changes by running the server and exercising /api/upload and /api/content/{id} via the provided UI or curl.
• When adding features, keep payload sizes small or adjust the JSON limit in src/main.rs; ensure new routes log via log_to_file for observability; clean up expired artifacts consistently with clear_assets() patterns.