oscars-pool/python_video_server/README.md

Python video server (Range streaming + JWT + Mongo)

This is a small standalone server that mirrors the app’s /api/video/:id behavior:

• Looks up movies._id == :id in MongoDB and reads the video_file field
• Streams the file from VIDEO_FILES_DIR with HTTP Range support (seeking works)
• Auth via the same JWT (Authorization: Bearer ...), plus a video_auth cookie for <video>

Run

python -m pip install -r python_video_server/requirements.txt
export MONGO_URI="..."
export MONGO_DB_NAME="..."                            # optional; required if MONGO_URI doesn't include /<dbName>
export JWT_SECRET="..."
export VIDEO_FILES_DIR="/absolute/path/to/public/video"  # optional (default: ./public/video)
export VIDEO_SESSION_MAX_AGE_SECONDS="28800"             # optional (default: 8h)
uvicorn python_video_server.server:app --host 0.0.0.0 --port 8000

Extra environment variables (optional)

# CORS (needed when the main app is on a different origin)
export CORS_ALLOW_ORIGINS="https://your-app.example.com"  # default: "*"

# Cookie behavior for /api/video/session
export VIDEO_COOKIE_SAMESITE="Lax"                        # Lax|Strict|None (default: Lax)

# Mongo TLS / connectivity troubleshooting (Atlas, odd hosts, etc.)
export MONGO_TLS_CA_FILE="/path/to/ca.pem"                # prefer a valid CA bundle
export MONGO_TLS_FORCE_TLS12="1"                          # force TLS 1.2 if TLS 1.3 breaks
export MONGO_TLS_INSECURE="1"                             # NOT recommended; debug only
export MONGO_SERVER_SELECTION_TIMEOUT_MS="8000"
export MONGO_CONNECT_TIMEOUT_MS="8000"
export MONGO_SOCKET_TIMEOUT_MS="20000"

Video auth / usage

GET /api/video/{movieId} accepts auth in three ways (in priority order):

1. video_auth cookie (best for browser <video> tags)
2. Authorization: Bearer <token> header
3. ?token=<token> query param (debug only; tokens in URLs leak via logs/referrers)

Browser <video> (cookie flow)

Because HTML <video> cannot send an Authorization header, the pattern is:

1. Your JS calls POST /api/video/session with Authorization: Bearer <token>
2. The server responds 204 and sets a video_auth cookie (scoped to /api/video)
3. Your <video> loads /api/video/{movieId} and the cookie is used automatically

Example (curl):

# 1) exchange header token -> cookie
curl -i -X POST "https://video.example.com/api/video/session" \
  -H "Authorization: Bearer $JWT"

# 2) then the <video> element can simply use:
# https://video.example.com/api/video/<movieId>

Cross-site note (frontend on a different origin):

• Set CORS_ALLOW_ORIGINS to your exact app origin (not *) and ensure your frontend uses credentials: "include" on the /api/video/session request.
• If the video host is cross-site, you’ll usually need VIDEO_COOKIE_SAMESITE=None and HTTPS, otherwise browsers may block the cookie.

Non-browser clients (header flow)

curl -I "https://video.example.com/api/video/<movieId>" \
  -H "Authorization: Bearer $JWT"

Token in URL (debug flow)

curl -I "https://video.example.com/api/video/<movieId>?token=$JWT"

Seeking / Range requests (example)

curl -i "https://video.example.com/api/video/<movieId>" \
  -H "Authorization: Bearer $JWT" \
  -H "Range: bytes=0-1023"

HTTPS (optional)

You can run behind a reverse proxy/ingress, or run uvicorn with TLS directly:

uvicorn python_video_server.server:app --host 0.0.0.0 --port 443 \
  --ssl-certfile /path/to/fullchain.pem \
  --ssl-keyfile  /path/to/privkey.pem

Notes:

• If you’re behind a proxy, forward X-Forwarded-Proto: https so /api/video/session can set Secure cookies correctly.

Let’s Encrypt certs (python-only helper)

This repo includes python_video_server/letsencrypt.py, a wrapper around the certbot Python package (no system certbot needed).

Certificates (and certbot state) are stored under:

• python_video_server/certs/config/live/<primary-domain>/fullchain.pem
• python_video_server/certs/config/live/<primary-domain>/privkey.pem

You can override the storage directory with LETSENCRYPT_BASE_DIR (optional).

Issue a cert (HTTP-01 standalone, easiest)

Requirements:

• DNS A/AAAA records point to this host
• Port 80 reachable from the internet
• You can bind port 80 (often requires sudo)

python -m pip install -r python_video_server/requirements.txt

# staging by default (recommended first)
sudo -E python -m python_video_server.letsencrypt certonly \
  --email [email protected] \
  --domains example.com,www.example.com

# production (real cert)
sudo -E python -m python_video_server.letsencrypt certonly \
  --email [email protected] \
  --domains example.com,www.example.com \
  --production

Then run uvicorn with those certs:

sudo -E uvicorn python_video_server.server:app --host 0.0.0.0 --port 443 \
  --ssl-certfile python_video_server/certs/config/live/example.com/fullchain.pem \
  --ssl-keyfile  python_video_server/certs/config/live/example.com/privkey.pem

Issue a cert (DNS-01 manual TXT, no port 80)

Use this if you cannot expose/bind port 80. Certbot will prompt you to create a TXT record.

python -m pip install -r python_video_server/requirements.txt

python -m python_video_server.letsencrypt certonly \
  --challenge dns \
  --email [email protected] \
  --domains example.com,www.example.com \
  --production

Renew certs

# dry-run (safe)
sudo -E python -m python_video_server.letsencrypt renew --dry-run

# real renewal
sudo -E python -m python_video_server.letsencrypt renew --production

Endpoints

• POST /api/video/session
  Sets video_auth cookie (send Authorization: Bearer <token>).

• GET|HEAD /api/video/{movieId}
  Streams the movie file (supports Range: bytes=...).

• GET /healthz