Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 12 additions & 0 deletions docs/firmware-ota.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
192 changes: 192 additions & 0 deletions src/__tests__/cloudflare-r2-url.test.ts
Original file line number Diff line number Diff line change
@@ -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();
});
});
24 changes: 21 additions & 3 deletions src/service/CloudflareR2.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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) {
Expand Down Expand Up @@ -64,16 +67,26 @@ export async function createPresignedUploadUrl(key: string): Promise<string | nu
* @param body - Buffer to upload
* @param contentType - MIME type (default: 'image/jpeg' for backward compatibility with camera uploads)
* @param bucket - Optional bucket override (defaults to R2_BUCKET_NAME)
* @param publicBaseUrlOverride - Optional public base URL override for this upload
*/
export async function uploadToR2(
key: string,
body: Buffer,
contentType = 'image/jpeg',
bucket?: string
bucket?: string,
publicBaseUrlOverride?: string
): Promise<string | null> {
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({
Expand All @@ -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}`;
Expand Down
Loading