bitvid/docs/storage-r2.md

Cloudflare R2 integration (r2Service)

Purpose and scope

js/services/r2Service.js is the client-side coordinator for Cloudflare R2 uploads. It owns:

• Local persistence of Cloudflare credentials and bucket metadata used by the Upload modal.
• Uploading the selected video/HLS asset via multipart S3 uploads and publishing the resulting public URL into the video note payload.
• Verifying public access via the configured Public Bucket URL.

The service is used from the Upload modal UI (via js/ui/components/UploadModal.js) and is not a backend integration.

Assets stored in R2

R2 is used as the URL-first playback source. The upload path supports a single file per upload, but file types include:

• Video files (MP4/WebM/MOV/MKV/MPG/MPEG).
• HLS/DASH assets (manifest .m3u8/.mpd and segment files like .ts/.m4s).
• Related static media if the operator chooses to upload them separately (images, subtitles such as .vtt/.srt), which benefit from cache-friendly headers set in the upload flow.

The object key format is generated by buildR2Key() in js/r2.js and looks like: u/<npub>/<YYYY>/<MM>/<slug>.<ext>, which keeps uploads scoped by user and month.

Setup Guide: Getting your Cloudflare Credentials

To enable R2 uploads, you must provide Cloudflare S3-compatible credentials and configure your bucket for public access and CORS.

Step 1: Create Bucket & Enable Public Access

1. Log in to the Cloudflare Dashboard.
2. Navigate to R2 -> Create Bucket.
3. In the bucket settings, enable Public Access (R2.dev subdomain) or connect a custom domain.
4. Copy the Public Bucket URL (e.g., https://pub-xxxxxx.r2.dev).

Step 2: Configure CORS

Manually add a CORS policy in the bucket settings to allow uploads from your app's origin (or *). (See content/upload-content.md for the recommended JSON configuration).

Step 3: Create S3 Credentials

1. In the R2 dashboard, click Manage R2 API Tokens.
2. Click Create API Token.
3. Select Object Read & Write permissions (Minimal).
4. Copy the Account ID, Access Key ID, and Secret Access Key.

Step 4: Configure the App

1. Open the Upload Modal in the app.
2. Expand Storage Settings.
3. Enter the Account ID, Access Key ID, Secret Access Key, and Public Bucket URL.
4. Click Verify & Save.

The app will attempt to upload a small test file to verify the credentials and public access configuration.

Upload lifecycle

1. Settings saved locally

   • The Upload modal calls r2Service.saveSettings() to persist Cloudflare credentials. Settings are stored in IndexedDB (bitvidSettings → kv) with a localStorage fallback (bitvid:r2Settings).

2. Bucket preparation

   • The service relies on the user ensuring the bucket exists and is configured for CORS.
   • It attempts a "best-effort" auto-configuration using the S3 keys (requires broader permissions), but strictly supports the manual "Object Read & Write" flow.

3. Upload and publish

   • The service builds the R2 object key and public URL.
   • multipartUpload() uploads the file using S3 multipart uploads.
   • On success, publishVideoNote() is called with the hosted URL, so playback can be URL-first with magnet fallback.

4. UI feedback

   • The Upload modal receives progress, status, and verification errors via r2Service events.

Download / playback flow

There is no direct “download” API for R2 in r2Service. Instead, R2 provides the public URL that gets saved into the video note payload. Playback uses that URL as the primary source and only falls back to magnet/WebTorrent when needed, preserving the URL-first playback promise.

Configuration keys and where they live

Stored locally (IndexedDB / localStorage):

• accountId: Cloudflare account ID.
• accessKeyId: R2 S3 access key ID.
• secretAccessKey: R2 S3 secret access key.
• baseDomain: The Public Bucket URL (e.g., https://pub-xxxx.r2.dev) used to generate file URLs.
• buckets: Cached map of npub → { bucket, publicBaseUrl, domainType, lastUpdated }.

Environment / global flags:

• globalThis.__BITVID_DISABLE_NETWORK_IMPORTS__: disables the AWS SDK network import used by the R2 S3 client loader (js/storage/r2-s3.js). When true, uploads will fail with a load error until the SDK is bundled or otherwise provided.

Config files:

• There are no R2-specific keys in config/ today; all R2 settings are entered through the UI and stored locally in the browser.

Retry and fallback behavior

• Bucket/domain setup:
  • The system now relies on explicit user configuration for the Public Bucket URL (baseDomain). If this is missing or incorrect, verification will fail.
• CORS:
  • The app attempts to set CORS if permissions allow, but largely assumes the user has configured it manually if using minimal tokens.
• Multipart uploads:
  • There is no custom retry loop inside multipartUpload(). Failures propagate to the UI; the caller can retry by re-initiating the upload.

Security considerations

• Credential storage: R2 credentials are stored in browser storage. Treat them as sensitive and avoid sharing browser profiles. Clear settings via the Upload modal when done.
• Public exposure: The generated URLs are public; uploaded assets should be safe for public access. Use signed URLs only if you add a separate access layer.
• CORS and origins: Ideally, scope CORS rules to the current origin to avoid overly broad exposure, though * is often used for ease of setup.
• Minimal Permissions: We recommend "Object Read & Write" tokens to limit the scope of the keys to specific buckets and prevent admin actions.

Impact on uploads and playback

• Uploads: Successful R2 uploads produce a hosted URL stored in the video note payload, enabling URL-first playback. Metadata such as MIME type and the public URL are also stitched into the NIP-71 metadata block during publish.
• Playback: The hosted URL is the primary stream source. If it fails, playback can still fall back to the magnet/WebTorrent path, so the R2 integration improves reliability without removing P2P fallback.