UHRP Server (Cloud Bucket)

A production-grade UHRP host server backed by Google Cloud Storage. Stores large files in cloud buckets with optional billing/micropayments and includes advertising infrastructure for overlay network discovery.

What it does

A TypeScript/Express server designed for Google Cloud Run that implements UHRP workflows backed by Google Cloud Storage. Static object retrieval is public; upload, list, find, and renewal require BRC-103 identity. A separate administrative advertisement endpoint uses a strong Bearer token.

Clients upload files with authentication, retrieve files via public GET, and server continuously advertises hosting capability.

When to deploy this

• Production UHRP hosting on Google Cloud Run or equivalent
• High-volume file storage with auto-scaling requirements
• Multi-region replication and disaster recovery needed
• Monetizing UHRP hosting via micropayments
• Advertising UHRP services to overlay network

Dependencies

HTTP endpoints

WebSocket endpoints

None; HTTP-only with background advertising worker.

Configuration (env vars)

See Public Service Edge Security for full edge controls.

Run locally

# Install dependencies
npm install

# Development with hot-reload
npm run dev

# Build TypeScript
npm run build

# Run production build
npm start

Requires GCP service account credentials or emulator for local testing.

Deploy to production

# Multi-stage build: pinned Node 24 alpine builder → production runtime
docker build -t uhrp-storage:latest .

# Deploy to Google Cloud Run
gcloud run deploy uhrp-storage \
  --image uhrp-storage:latest \
  --platform managed \
  --region us-central1 \
  --set-env-vars SERVER_PRIVATE_KEY=<hex-key>,GOOGLE_CLOUD_BUCKET=uhrp-storage-prod,ENABLE_PAYMENT_MIDDLEWARE=true

# Or deploy with docker-compose (local testing only)
docker compose up -d

Follows GCP 12-factor patterns: stateless design, cloud bucket for file storage, Cloud SQL for optional metadata, Cloud Logging integration, Bugsnag for error tracking. Graceful shutdown via SIGTERM signal handling.

Migrations

No database migrations. Google Cloud Storage is the durable source of truth.

Health checks

• GET /health and GET /healthz report process liveness.
• GET /ready returns 200 only after wallet-backed authentication and payment middleware initialization completes; the container health check uses it.

Spec conformance

• UHRP – Implements UHRP host protocol for file storage, retrieval, and metadata
• BRC-103 – Mutual authentication on upload, list, find, and renewal workflows
• BRC-100 – Payment verification for uploads (optional)
• Google Cloud – Follows Cloud Run best practices (health checks, graceful shutdown, 12-factor)

Integration with ts-stack

• UHRP clients upload/retrieve files using SERVER_PRIVATE_KEY and HOSTING_DOMAIN
• Wallet Storage derives keys, validates payments, manages user accounts
• Background worker advertises UHRP host via SHIP overlay protocol using ARC broadcaster
• Optional Cloud SQL metadata database for query optimization
• Bugsnag integration for production error tracking and monitoring

Common pitfalls

• GCP credentials: GOOGLE_APPLICATION_CREDENTIALS must point to valid service account JSON; Cloud Run uses default service account if not set
• Storage bucket policy: Ensure bucket exists and service account has storage.objects.create/get/delete permissions
• Cost management: Monitor storage usage and pricing; use Cloud Storage lifecycle policies for archival
• Payment enforcement: ENABLE_PAYMENT_MIDDLEWARE requires ARC_API_KEY and WALLET_STORAGE_URL; uploads fail if not configured
• Advertising loop: ADVERTISE_INTERVAL_MS should balance frequent updates vs transaction costs; 1 hour is conservative default
• Cloud Run and application request timeouts default to 60 seconds; use direct cloud upload workflows for large objects rather than unbounded application buffering
• Graceful shutdown: Cloud Run sends SIGTERM; ensure all writes complete before exit (transaction broadcasts, metadata flushes)

Source

• GitHub
• npm package