Open Workshop Storage

Requirements

• Python 3.10+
• System dependency: 7z (p7zip-full)

Ubuntu / Debian

sudo apt update
sudo apt install -y p7zip-full

Install Python deps

pip install -r requirements.txt

Transfer WebSocket

Progress for /transfer/start and /transfer/upload jobs is available via /transfer/ws/{job_id}?token=....

When a client connects, the server immediately sends the current snapshot:

{
  "event": "progress",
  "bytes": 1048576,
  "total": 7340032,
  "status": "uploading",
  "stage": "uploading",
  "percent": null
}

Supported WebSocket events:

• progress:
  • During uploading and downloading, sent at most once every 0.25s while bytes are still flowing.
  • During extracting and repacking, includes optional percent from 7z so the client can render archive progress for each phase.
• stage: sent whenever the transfer stage changes, for example uploading, uploaded, downloading, downloaded, extracting, repacking, packed.
• complete: sent when the final packed artifact is ready.
• error: sent when the transfer or repack fails.

Example progress event during archive repacking:

{
  "event": "progress",
  "bytes": 7340032,
  "total": 7340032,
  "status": "done",
  "stage": "repacking",
  "percent": 42
}

Notes:

• Every WebSocket event includes the current state snapshot (bytes, total, status, stage), so clients can safely replace local state even if they connected while a job was still pending.
• percent is only meaningful for stage = "extracting" and stage = "repacking". For other stages it is null in the initial snapshot and may be omitted in subsequent events.
• There is no heartbeat timer. Progress messages are emitted on actual state changes or data/progress updates.

Uptrace telemetry

Сервер отправляет трейсы в Uptrace через OpenTelemetry, если задан UPTRACE_DSN.

Пример запуска:

export UPTRACE_DSN="https://<token>@api.uptrace.dev/<project_id>"
export OTEL_SERVICE_NAME="open-workshop-storage"
export OTEL_SERVICE_VERSION="1.0.0"
export OTEL_DEPLOYMENT_ENVIRONMENT="production"
# export UPTRACE_OTLP_PROTOCOL="grpc"   # or "http"
# export UPTRACE_FASTAPI_EXCLUDED_URLS="^.*/docs$,^.*/openapi\\.json$,^/favicon\\.ico$,^/robots\\.txt$"
# export UPTRACE_FASTAPI_EXCLUDE_SPANS="receive,send"
uvicorn main:app --host 127.0.0.1 --port 7070

Опционально можно переопределить OTLP endpoint:

export UPTRACE_OTLP_TRACES_URL="https://api.uptrace.dev/v1/traces"
# export UPTRACE_OTLP_GRPC_URL="https://api.uptrace.dev:4317"