diff --git a/.env.example b/.env.example index 3fe4304..c669357 100644 --- a/.env.example +++ b/.env.example @@ -35,6 +35,7 @@ TELEMETRY_ACK_ENABLED=false # R2_BUCKET_NAME=garage-camera # R2_PUBLIC_URL= # R2_FIRMWARE_BUCKET_NAME= # Optional: separate bucket for firmware (defaults to R2_BUCKET_NAME) +# R2_FIRMWARE_PUBLIC_URL= # Optional: public URL for firmware bucket (e.g., https://pub-xxxx.r2.dev) # Firmware upload configuration FIRMWARE_UPLOAD_MAX_SIZE_MB=10 diff --git a/docs/firmware-ota.md b/docs/firmware-ota.md index 1e2d908..5d8ca81 100644 --- a/docs/firmware-ota.md +++ b/docs/firmware-ota.md @@ -10,6 +10,18 @@ The OTA update flow consists of three main steps: 2. **Notify**: Notify devices that an update is available 3. **Download**: Devices download and flash the firmware +## Configuration + +Firmware OTA requires the following environment variables: + +- `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`: Cloudflare R2 credentials +- `R2_FIRMWARE_BUCKET_NAME`: Bucket name for firmware storage (optional, defaults to `R2_BUCKET_NAME`) +- `R2_FIRMWARE_PUBLIC_URL`: Public URL for the firmware bucket (e.g., `https://pub-xxxx.r2.dev`) + - If not set, falls back to `R2_PUBLIC_URL` + - If neither is set, uses the private `r2.cloudflarestorage.com` endpoint (devices won't be able to download) + +When using a separate firmware bucket (`R2_FIRMWARE_BUCKET_NAME`), you must configure `R2_FIRMWARE_PUBLIC_URL` or `R2_PUBLIC_URL` to allow devices to download firmware. The proxy will log a warning at first firmware upload if no public URL is configured. + ## Firmware Version Format ### Device Firmware Version String diff --git a/src/__tests__/cloudflare-r2-url.test.ts b/src/__tests__/cloudflare-r2-url.test.ts new file mode 100644 index 0000000..5542441 --- /dev/null +++ b/src/__tests__/cloudflare-r2-url.test.ts @@ -0,0 +1,192 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; + +const mockSend = vi.fn(); + +vi.mock('@aws-sdk/client-s3', () => ({ + S3Client: vi.fn().mockImplementation(() => ({ + send: mockSend, + })), + PutObjectCommand: vi.fn(), +})); + +describe('CloudflareR2 URL selection', () => { + let originalEnv: NodeJS.ProcessEnv; + + beforeEach(() => { + originalEnv = { ...process.env }; + mockSend.mockClear(); + mockSend.mockResolvedValue({}); + vi.resetModules(); + }); + + afterEach(() => { + process.env = originalEnv; + vi.resetModules(); + }); + + it('should use R2_FIRMWARE_PUBLIC_URL for firmware uploads when set', async () => { + process.env.R2_ACCOUNT_ID = 'test-account'; + process.env.R2_ACCESS_KEY_ID = 'test-key'; + process.env.R2_SECRET_ACCESS_KEY = 'test-secret'; + process.env.R2_BUCKET_NAME = 'camera-bucket'; + process.env.R2_FIRMWARE_BUCKET_NAME = 'firmware-bucket'; + process.env.R2_PUBLIC_URL = 'https://camera.r2.dev'; + process.env.R2_FIRMWARE_PUBLIC_URL = 'https://firmware.r2.dev'; + + const { uploadToR2, getFirmwareBucketName } = await import('../service/CloudflareR2'); + + const url = await uploadToR2( + 'firmware/test/1.0.0/firmware.bin', + Buffer.from('test'), + 'application/octet-stream', + getFirmwareBucketName() + ); + + expect(url).toBe('https://firmware.r2.dev/firmware/test/1.0.0/firmware.bin'); + }); + + it('should fall back to R2_PUBLIC_URL for firmware when R2_FIRMWARE_PUBLIC_URL is not set', async () => { + process.env.R2_ACCOUNT_ID = 'test-account'; + process.env.R2_ACCESS_KEY_ID = 'test-key'; + process.env.R2_SECRET_ACCESS_KEY = 'test-secret'; + process.env.R2_BUCKET_NAME = 'camera-bucket'; + process.env.R2_FIRMWARE_BUCKET_NAME = 'firmware-bucket'; + process.env.R2_PUBLIC_URL = 'https://public.r2.dev'; + delete process.env.R2_FIRMWARE_PUBLIC_URL; + + const { uploadToR2, getFirmwareBucketName } = await import('../service/CloudflareR2'); + + const url = await uploadToR2( + 'firmware/test/1.0.0/firmware.bin', + Buffer.from('test'), + 'application/octet-stream', + getFirmwareBucketName() + ); + + expect(url).toBe('https://public.r2.dev/firmware/test/1.0.0/firmware.bin'); + }); + + it('should fall back to cloudflarestorage.com when no public URL is set', async () => { + process.env.R2_ACCOUNT_ID = 'test-account'; + process.env.R2_ACCESS_KEY_ID = 'test-key'; + process.env.R2_SECRET_ACCESS_KEY = 'test-secret'; + process.env.R2_BUCKET_NAME = 'camera-bucket'; + process.env.R2_FIRMWARE_BUCKET_NAME = 'firmware-bucket'; + delete process.env.R2_PUBLIC_URL; + delete process.env.R2_FIRMWARE_PUBLIC_URL; + + const { uploadToR2, getFirmwareBucketName } = await import('../service/CloudflareR2'); + + const url = await uploadToR2( + 'firmware/test/1.0.0/firmware.bin', + Buffer.from('test'), + 'application/octet-stream', + getFirmwareBucketName() + ); + + expect(url).toBe('https://test-account.r2.cloudflarestorage.com/firmware-bucket/firmware/test/1.0.0/firmware.bin'); + }); + + it('should trim trailing slashes from public URLs', async () => { + process.env.R2_ACCOUNT_ID = 'test-account'; + process.env.R2_ACCESS_KEY_ID = 'test-key'; + process.env.R2_SECRET_ACCESS_KEY = 'test-secret'; + process.env.R2_BUCKET_NAME = 'camera-bucket'; + process.env.R2_FIRMWARE_BUCKET_NAME = 'firmware-bucket'; + process.env.R2_FIRMWARE_PUBLIC_URL = 'https://firmware.r2.dev/'; + + const { uploadToR2, getFirmwareBucketName } = await import('../service/CloudflareR2'); + + const url = await uploadToR2( + 'firmware/test/1.0.0/firmware.bin', + Buffer.from('test'), + 'application/octet-stream', + getFirmwareBucketName() + ); + + expect(url).toBe('https://firmware.r2.dev/firmware/test/1.0.0/firmware.bin'); + }); + + it('should use R2_PUBLIC_URL for camera uploads (unchanged behavior)', async () => { + process.env.R2_ACCOUNT_ID = 'test-account'; + process.env.R2_ACCESS_KEY_ID = 'test-key'; + process.env.R2_SECRET_ACCESS_KEY = 'test-secret'; + process.env.R2_BUCKET_NAME = 'camera-bucket'; + process.env.R2_FIRMWARE_BUCKET_NAME = 'firmware-bucket'; + process.env.R2_PUBLIC_URL = 'https://camera.r2.dev'; + process.env.R2_FIRMWARE_PUBLIC_URL = 'https://firmware.r2.dev'; + + const { uploadToR2 } = await import('../service/CloudflareR2'); + + const url = await uploadToR2( + 'camera/request-123.jpg', + Buffer.from('test'), + 'image/jpeg' + ); + + expect(url).toBe('https://camera.r2.dev/camera/request-123.jpg'); + }); + + it('should log warning once when firmware bucket is set but no public URL configured', async () => { + process.env.R2_ACCOUNT_ID = 'test-account'; + process.env.R2_ACCESS_KEY_ID = 'test-key'; + process.env.R2_SECRET_ACCESS_KEY = 'test-secret'; + process.env.R2_BUCKET_NAME = 'camera-bucket'; + process.env.R2_FIRMWARE_BUCKET_NAME = 'firmware-bucket'; + delete process.env.R2_PUBLIC_URL; + delete process.env.R2_FIRMWARE_PUBLIC_URL; + + const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}); + + const { uploadToR2, getFirmwareBucketName } = await import('../service/CloudflareR2'); + + await uploadToR2( + 'firmware/test/1.0.0/firmware.bin', + Buffer.from('test'), + 'application/octet-stream', + getFirmwareBucketName() + ); + + await uploadToR2( + 'firmware/test/1.0.1/firmware.bin', + Buffer.from('test'), + 'application/octet-stream', + getFirmwareBucketName() + ); + + expect(consoleWarnSpy).toHaveBeenCalledTimes(1); + expect(consoleWarnSpy).toHaveBeenCalledWith( + expect.stringContaining('R2_FIRMWARE_BUCKET_NAME is set but neither R2_FIRMWARE_PUBLIC_URL nor R2_PUBLIC_URL is configured') + ); + + consoleWarnSpy.mockRestore(); + }); + + it('should not log warning when firmware bucket equals camera bucket', async () => { + process.env.R2_ACCOUNT_ID = 'test-account'; + process.env.R2_ACCESS_KEY_ID = 'test-key'; + process.env.R2_SECRET_ACCESS_KEY = 'test-secret'; + process.env.R2_BUCKET_NAME = 'shared-bucket'; + delete process.env.R2_FIRMWARE_BUCKET_NAME; + delete process.env.R2_PUBLIC_URL; + delete process.env.R2_FIRMWARE_PUBLIC_URL; + + const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}); + + const { uploadToR2, getFirmwareBucketName } = await import('../service/CloudflareR2'); + + await uploadToR2( + 'firmware/test/1.0.0/firmware.bin', + Buffer.from('test'), + 'application/octet-stream', + getFirmwareBucketName() + ); + + const warningCalls = consoleWarnSpy.mock.calls.filter(call => + call[0]?.includes?.('R2_FIRMWARE_BUCKET_NAME') + ); + expect(warningCalls).toHaveLength(0); + + consoleWarnSpy.mockRestore(); + }); +}); diff --git a/src/service/CloudflareR2.ts b/src/service/CloudflareR2.ts index bb45f3d..13ff95e 100644 --- a/src/service/CloudflareR2.ts +++ b/src/service/CloudflareR2.ts @@ -6,6 +6,7 @@ * R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET_NAME * R2_PUBLIC_URL (e.g. https://pub-xxx.r2.dev or custom domain) * R2_FIRMWARE_BUCKET_NAME (optional, defaults to R2_BUCKET_NAME) + * R2_FIRMWARE_PUBLIC_URL (optional, public URL for firmware bucket) */ import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'; @@ -17,8 +18,10 @@ const secretAccessKey = process.env.R2_SECRET_ACCESS_KEY || ''; const bucketName = process.env.R2_BUCKET_NAME || 'garage-camera'; const firmwareBucketName = process.env.R2_FIRMWARE_BUCKET_NAME || bucketName; const publicBaseUrl = process.env.R2_PUBLIC_URL || ''; // e.g. https://pub-xxx.r2.dev +const firmwarePublicBaseUrl = process.env.R2_FIRMWARE_PUBLIC_URL || ''; let s3Client: S3Client | null = null; +let hasLoggedFirmwareUrlWarning = false; function getClient(): S3Client | null { if (!accountId || !accessKeyId || !secretAccessKey) { @@ -64,16 +67,26 @@ export async function createPresignedUploadUrl(key: string): Promise { const client = getClient(); if (!client) return null; const targetBucket = bucket || bucketName; + + if (targetBucket === firmwareBucketName && firmwareBucketName !== bucketName) { + if (!hasLoggedFirmwareUrlWarning && !firmwarePublicBaseUrl && !publicBaseUrl) { + console.warn('[R2] Warning: R2_FIRMWARE_BUCKET_NAME is set but neither R2_FIRMWARE_PUBLIC_URL nor R2_PUBLIC_URL is configured. Devices will not be able to download firmware from the private storage endpoint.'); + hasLoggedFirmwareUrlWarning = true; + } + } + try { await client.send( new PutObjectCommand({ @@ -83,8 +96,13 @@ export async function uploadToR2( ContentType: contentType, }) ); - if (publicBaseUrl) { - const base = publicBaseUrl.replace(/\/$/, ''); + + const effectivePublicUrl = publicBaseUrlOverride + || (targetBucket === firmwareBucketName ? firmwarePublicBaseUrl : '') + || publicBaseUrl; + + if (effectivePublicUrl) { + const base = effectivePublicUrl.replace(/\/$/, ''); return `${base}/${key}`; } return `https://${accountId}.r2.cloudflarestorage.com/${targetBucket}/${key}`;