docs/index.md (1)

26-28:Wording update looks good; keep storage list consistent across docs

"R2, KV, or S3" reads clearly and aligns with the new backend. No further changes needed here.

If you want absolute consistency with other pages that lead with S3 (due to precedence elsewhere), consider "S3, KV, or R2" – purely stylistic.

src/index.ts (1)

9-12:Env type extension for S3 is correct; add brief field docs to prevent misuse

The optional fields are typed appropriately. To reduce developer confusion between secrets vs non-secret config, add inline docs noting that credentials must be set via Wrangler secrets, while bucket/region can be plain vars.

Apply this diff to annotate the fields:

 export type Env = {   ENVIRONMENT: 'development' | 'production';   R2_STORE?: R2Bucket;   KV_STORE?: KVNamespace;-  S3_ACCESS_KEY_ID?: string;-  S3_SECRET_ACCESS_KEY?: string;-  S3_BUCKET_NAME?: string;-  S3_REGION?: string;+  /** Secret: set via `wrangler secret put S3_ACCESS_KEY_ID` */+  S3_ACCESS_KEY_ID?: string;+  /** Secret: set via `wrangler secret put S3_SECRET_ACCESS_KEY` */+  S3_SECRET_ACCESS_KEY?: string;+  /** Non-secret config: may be set in vars or secrets */+  S3_BUCKET_NAME?: string;+  /** Non-secret config: may be set in vars or secrets; defaults to 'us-east-1' if omitted */+  S3_REGION?: string;   TURBO_TOKEN: string;   BUCKET_OBJECT_EXPIRATION_HOURS: number;   STORAGE_MANAGER: StorageManager; };

docs/configuration/project-configuration.md (2)

11-14:Minor copy edits for bullets (punctuation and parallelism)

Tighten the bullets with terminal periods and consistent phrasing.

Apply this diff:

-- **🪣 [R2 Storage](/configuration/r2-storage)**: Cloudflare's object storage with zero egress fees-- **🔑 [KV Storage](/configuration/kv-storage)**: Cloudflare's key-value storage with global distribution-- **☁️ [S3 Storage](/configuration/s3-storage)**: Amazon S3 for maximum compatibility and flexibility+- **🪣 [R2 Storage](/configuration/r2-storage)**: Cloudflare's object storage with zero egress fees.+- **🔑 [KV Storage](/configuration/kv-storage)**: Cloudflare's key-value storage with global distribution.+- **☁️ [S3 Storage](/configuration/s3-storage)**: Amazon S3 for maximum compatibility and flexibility.

---

15-16:Clarify precedence scope (selection, not failover/replication)

Explicitly state that only one backend is active at a time and there’s no automatic cross-backend failover or replication.

Apply this diff:

-The storage priority order is: S3 > KV > R2. When multiple storage options are configured, the highest priority one will be used.+The storage priority order is: S3 > KV > R2. When multiple storage options are configured, only the highest-priority backend is used for all operations (no automatic cross-backend replication or failover).

README.md (2)

30-31:Minor wording polish to avoid repetition

Streamline the sentence to read more crisply.

Apply this diff:

-- 💿 **Storage Options**: Choose between 🪣 [R2](https://adirishi.github.io/turborepo-remote-cache-cloudflare/configuration/r2-storage), 🔑 [KV](https://adirishi.github.io/turborepo-remote-cache-cloudflare/configuration/kv-storage), or ☁️ [S3](https://adirishi.github.io/turborepo-remote-cache-cloudflare/configuration/s3-storage) storage for your build artifacts. This gives you the flexibility to choose the storage option that best fits your needs.+- 💿 **Storage Options**: Choose between 🪣 [R2](https://adirishi.github.io/turborepo-remote-cache-cloudflare/configuration/r2-storage), 🔑 [KV](https://adirishi.github.io/turborepo-remote-cache-cloudflare/configuration/kv-storage), or ☁️ [S3](https://adirishi.github.io/turborepo-remote-cache-cloudflare/configuration/s3-storage) for your build artifacts, providing the flexibility to pick what best fits your needs.

---

73-79:README still mentions “bound R2 bucket” for deletion; update to “configured storage backend”

Elsewhere (docs/configuration/project-configuration.md) you’ve generalized deletion to the active backend. Mirror that here for consistency.

Apply this diff:

-This project sets up a [cron trigger](https://developers.cloudflare.com/workers/platform/triggers/cron-triggers/) for Cloudflare workers, which automatically deletes old cache files within the bound R2 bucket. This behavior can be customized:+This project sets up a [cron trigger](https://developers.cloudflare.com/workers/platform/triggers/cron-triggers/) for Cloudflare Workers, which automatically deletes old cache files within the configured storage backend. This behavior can be customized:

wrangler.jsonc (1)

13-17:Differentiate secrets vs non-secret vars in comments to guide users

Credentials should be set as Wrangler secrets, while bucket name and region can be plain vars. Adjust the comments to make this explicit.

Apply this diff:

-    // - S3_ACCESS_KEY_ID (AWS access key ID for S3 storage)-    // - S3_SECRET_ACCESS_KEY (AWS secret access key for S3 storage)-    // - S3_BUCKET_NAME (S3 bucket name for storage)-    // - S3_REGION (AWS region for S3 bucket, defaults to us-east-1)-    // Run `echo <VALUE> | wrangler secret put <NAME>` for each of these+    // Secrets (set via `echo <VALUE> | wrangler secret put <NAME>`):+    // - S3_ACCESS_KEY_ID (AWS access key ID for S3 storage)+    // - S3_SECRET_ACCESS_KEY (AWS secret access key for S3 storage)+    //+    // Non-secret config (can be set here in "vars" or via secrets if preferred):+    // - S3_BUCKET_NAME (S3 bucket name for storage)+    // - S3_REGION (AWS region for the S3 bucket; defaults to us-east-1)

docs/configuration/s3-storage.md (2)

84-87:Clarify that R2/KV can remain configured; S3 already takes precedence.

Commenting out R2/KV is optional because the code prioritizes S3 > KV > R2. This change avoids implying that other bindings must be removed.

-  // Comment out R2 and KV configurations when using S3+  // Optional: You can keep R2 and KV configured; S3 takes precedence automatically.+  // Remove these bindings only if you don't want to provision them for this Worker.   // "r2_buckets": [...],   // "kv_namespaces": [...]

---

99-99:Capitalize “GitHub Actions”.

-Once you've updated your Worker script and `wrangler.jsonc` file, deploy your Worker using the Wrangler CLI or your GitHub actions workflow.+Once you've updated your Worker script and `wrangler.jsonc` file, deploy your Worker using the Wrangler CLI or your GitHub Actions workflow.

examples/README.md (1)

20-26:Note the default for S3_REGION to reduce confusion.

Call out that S3_REGION is optional and defaults to us-east-1, matching the implementation and docs.

 For S3 storage, you'll need to set these secrets:  ```bash echo "your-access-key-id" | wrangler secret put S3_ACCESS_KEY_ID echo "your-secret-access-key" | wrangler secret put S3_SECRET_ACCESS_KEY

+Note: S3_REGION is optional; it defaults to "us-east-1" if not provided.

</blockquote></details><details><summary>examples/s3-config.jsonc (1)</summary><blockquote>`10-15`: **Add secrets reminder and quote TTL in examples/s3-config.jsonc**Wrangler’s `vars` values are always treated as strings, and sensitive keys should never live in source.  • File: examples/s3-config.jsonc (around lines 10–15)  • Wrap `BUCKET_OBJECT_EXPIRATION_HOURS` in quotes to satisfy the schema  • Add a JSONC comment directing users to use `wrangler secret put` for their S3 credentials  Suggested diff:```diff-  "vars": {+  // Set S3 credentials via Wrangler secrets; do not include them in "vars":+  //   wrangler secret put S3_ACCESS_KEY_ID+  //   wrangler secret put S3_SECRET_ACCESS_KEY+  "vars": {     "ENVIRONMENT": "production",-    "BUCKET_OBJECT_EXPIRATION_HOURS": 720,+    "BUCKET_OBJECT_EXPIRATION_HOURS": "720",     "S3_BUCKET_NAME": "your-turborepo-cache-bucket",     "S3_REGION": "us-east-1",   },

tests/storage/storage-manager.test.ts (1)

19-23:Make tests resilient by explicitly clearing all S3 fields where S3 should not be chosen.

Future default envs could set S3 creds, which would break these tests. Clear all S3 fields in the scenarios that should not pick S3.

   test('getActiveStorage() returns r2 if available', () => {-    const r2OnlyEnv = { ...workerEnv, KV_STORE: undefined };+    const r2OnlyEnv = {+      ...workerEnv,+      KV_STORE: undefined,+      S3_ACCESS_KEY_ID: undefined,+      S3_SECRET_ACCESS_KEY: undefined,+      S3_BUCKET_NAME: undefined,+    };     storageManager = new StorageManager(r2OnlyEnv);     expect(storageManager.getActiveStorage()).toBeInstanceOf(R2Storage);   });   test('getActiveStorage() returns kv if r2 is not available', () => {-    const kvOnlyEnv = { ...workerEnv, R2_STORE: undefined };+    const kvOnlyEnv = {+      ...workerEnv,+      R2_STORE: undefined,+      S3_ACCESS_KEY_ID: undefined,+      S3_SECRET_ACCESS_KEY: undefined,+      S3_BUCKET_NAME: undefined,+    };     storageManager = new StorageManager(kvOnlyEnv);     expect(storageManager.getActiveStorage()).toBeInstanceOf(KvStorage);   });   test('getActiveStorage() throws if no storage is available', () => {     const emptyEnv = {       ...workerEnv,       R2_STORE: undefined,       KV_STORE: undefined,       S3_ACCESS_KEY_ID: undefined,+      S3_SECRET_ACCESS_KEY: undefined,+      S3_BUCKET_NAME: undefined,     };     expect(() => new StorageManager(emptyEnv)).toThrowError('No storage provided');   });   test('getActiveStorage() returns kv if both r2 and kv are available', () => {-    const r2KvEnv = { ...workerEnv, S3_ACCESS_KEY_ID: undefined };+    const r2KvEnv = {+      ...workerEnv,+      S3_ACCESS_KEY_ID: undefined,+      S3_SECRET_ACCESS_KEY: undefined,+      S3_BUCKET_NAME: undefined,+    };     storageManager = new StorageManager(r2KvEnv);     expect(storageManager.getActiveStorage()).toBeInstanceOf(KvStorage);   });

Also applies to: 25-29, 31-38, 41-45

tests/storage/s3-storage.test.ts (1)

253-262:Add coverage for keys containing slashes and special characters.

S3 keys commonly include path-like prefixes. Add tests to ensure URLs don’t encode “/” within keys and that spaces/special chars are encoded correctly. This will prevent regressions around path encoding.

test('writes data with key containing slashes and spaces',async()=>{mockFetch.mockResolvedValueOnce({ok:true,status:200});awaitstorage.write('foo/bar baz.txt','v');expect(mockFetch).toHaveBeenCalledWith('https://test-bucket.s3.us-east-1.amazonaws.com/foo/bar%20baz.txt',expect.objectContaining({method:'PUT'}asRequestInit),);});test('reads data with key containing slashes',async()=>{mockFetch.mockResolvedValueOnce({ok:true,status:200,body:newReadableStream({start(c){c.enqueue(newTextEncoder().encode('ok'));c.close();}}),headers:newHeaders({'last-modified':'Wed, 01 Jan 2024 00:00:00 GMT'}),});awaitstorage.read('a/b/c');expect(mockFetch).toHaveBeenCalledWith('https://test-bucket.s3.us-east-1.amazonaws.com/a/b/c',expect.objectContaining({method:'GET'}asRequestInit),);});

Also applies to: 268-279

src/storage/s3-storage.ts (4)

36-41:Nit: avoid trailing ampersand in ListObjectsV2 URL when no params.

Current construction can yield …/?list-type=2&. Not harmful, but easy to tidy.

-    const url = `https://${this.bucketName}.s3.${this.region}.amazonaws.com/?list-type=2&${params.toString()}`;+    const qs = params.toString();+    const url = `https://${this.bucketName}.s3.${this.region}.amazonaws.com/?list-type=2${qs ? `&${qs}` : ''}`;

---

145-162:Metadata extraction is sensible; consider stricter fallback.

Minor: using Date.now() as fallback mixes numeric and string overloads. Using new Date() keeps intent crystal-clear.

-        createdAt: new Date(headers.get('last-modified') ?? Date.now()),+        createdAt: new Date(headers.get('last-modified') ?? new Date()),

---

164-202:Regex-based XML parsing is brittle; consider minimal XML parsing.

Regex parsing will break if AWS introduces whitespace/layout changes or namespaces. In Workers, DOMParser may not be available; a tiny, dependency-free parser for the few tags you need or fast-xml-parser (small and robust) would be safer. Not blocking given current tests.

If you want, I can draft a minimal, dependency-free parser tailored to the current fields (<Key/LastModified>, , ).

---

5-5:Testability: inject AwsClient or relax visibility (optional).

Tests had to poke a private field. Prefer DI or protected visibility:

• Option A (DI): add an optional client param.
• Option B (protected): change s3Client to protected so a test subclass can override it.

Example (DI):

constructor(accessKeyId: string,secretAccessKey: string,bucketName: string,region='us-east-1',client?:AwsClient){this.s3Client=client??newAwsClient({ accessKeyId, secretAccessKey, region});this.bucketName=bucketName;this.region=region;}

This removes the need for private-field hacks in tests.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/contributing-guidelines.mdc:0-0Timestamp: 2025-06-24T14:11:47.733ZLearning: When adding a new storage backend, ensure it implements StorageInterface, is initialized in storage-manager, has corresponding tests, and is configured in wrangler.jsonc.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/project-overview.mdc:0-0Timestamp: 2025-06-24T14:12:11.842ZLearning: The storage layer is pluggable, supporting both Cloudflare R2 and KV backends, which allows for flexible deployment and storage strategies.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/development-workflow.mdc:0-0Timestamp: 2025-06-24T14:12:02.195ZLearning: Environment variables such as TURBO_TOKEN, BUCKET_OBJECT_EXPIRATION_HOURS, and ENVIRONMENT should be managed securely, preferably via Wrangler secrets.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/contributing-guidelines.mdc:0-0Timestamp: 2025-06-24T14:11:47.733ZLearning: Always use Wrangler secrets for sensitive environment variables and document which variables are required versus optional.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/storage-architecture.mdc:0-0Timestamp: 2025-06-24T14:12:20.659ZLearning: Storage backends are configured through Cloudflare Workers environment bindings, specifically R2_STORE for R2, KV_STORE for KV, and BUCKET_OBJECT_EXPIRATION_HOURS for TTL management.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/storage-architecture.mdc:0-0Timestamp: 2025-06-24T14:12:20.659ZLearning: The storage manager (src/storage/storage-manager.ts) is responsible for initializing available storage backends based on environment bindings, prioritizing KV over R2, and providing utility methods for stream conversion. It throws an InvalidStorageError if no storage is configured.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/development-workflow.mdc:0-0Timestamp: 2025-06-24T14:12:02.195ZLearning: Cron jobs for scheduled tasks (e.g., cache cleanup) should be defined in both code (e.g., src/crons/deleteOldCache.ts) and configuration (wrangler.jsonc) for clarity and reliability.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/storage-architecture.mdc:0-0Timestamp: 2025-06-24T14:12:20.659ZLearning: All storage backends in the project must implement a common StorageInterface, which includes methods for listing, reading, writing, and deleting objects, with support for optional metadata. This ensures pluggability and consistency across storage implementations.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/storage-architecture.mdc:0-0Timestamp: 2025-06-24T14:12:20.659ZLearning: Storage backend selection follows a strict priority: KV is used if available, otherwise R2 is used, and an error is thrown if neither is configured.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/development-workflow.mdc:0-0Timestamp: 2025-06-24T14:12:02.195ZLearning: Testing should be performed using Vitest with a Cloudflare Workers-specific test environment, and tests should mirror the src/ directory structure for clarity and maintainability.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/storage-architecture.mdc:0-0Timestamp: 2025-06-24T14:12:20.659ZLearning: Cloudflare R2 storage is intended for large artifacts and long-term storage, supports custom metadata and automatic expiration, and is configured via the R2_STORE binding.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/storage-architecture.mdc:0-0Timestamp: 2025-06-24T14:12:20.659ZLearning: Cloudflare KV storage is best suited for smaller artifacts due to its 25MB per value size limitation and offers faster access. It uses BUCKET_OBJECT_EXPIRATION_HOURS for TTL and is configured via the KV_STORE binding.

Learnt from: CRPR: AdiRishi/turborepo-remote-cache-cloudflare#0File: .cursor/rules/development-workflow.mdc:0-0Timestamp: 2025-06-24T14:12:02.195ZLearning: Use R2 and KV bindings for object and key-value storage in Cloudflare Workers, and reference them explicitly in configuration and code.