Implement proxy mount read caching by scuffi · Pull Request #751 · cloudflare/sandbox-sdk

scuffi · 2026-06-11T10:32:00Z

Summary

Reduce redundant upstream requests during credential-proxy mounted reads by adding a short-lived HEAD metadata response cache.

s3fs issues frequent HEAD requests for metadata (getattr) on every file open, stat, and read. With credential-proxy mounts, each HEAD request was forwarded upstream through the signing proxy, adding latency to repeated reads. This PR keeps the existing aws4fetch/AwsClient signing path and focuses the optimization on safe metadata caching.

Changes

HEAD metadata cache (`s3-credential-proxy-handler.ts`)

Positive cache: Cache successful HEAD responses for 60s.
Negative cache: Cache 404 HEAD responses for 5s to avoid repeated existence checks for non-existent paths (s3fs probes path/, path_$folder$ variants).
PUT priming: After a successful PUT, synthesize and cache a HEAD-equivalent entry from request/response metadata such as content-length, content-type, etag, last-modified, and x-amz-meta-*.
Conservative bypasses: Do not cache ranged, conditional, checksum-mode, SSE-C, or GCS customer-encryption HEAD requests.
Selective invalidation: Mutating methods (PUT, POST, DELETE) invalidate cached metadata. GET requests preserve cached metadata.
Copy/multipart safety: Do not prime from query-string PUTs or copy operations; multipart/query mutations invalidate affected metadata.
Size bound: Cache is limited to 1,000 entries with TTL-aware eviction, falling back to FIFO eviction if still over limit.

Cache lifecycle (`sandbox.ts`)

evictHeadMetadataCacheForMount is called during unmount, mount-failure cleanup, and sandbox teardown, matching the existing SigV4 client and directory-marker cache cleanup paths.

Request forwarding safety

Strip hop-by-hop/proxy headers before forwarding credential-proxy requests upstream.
Preserve SigV4 request bodies that do not include content-length instead of dropping the stream.
Keep SigV4 signing on the existing aws4fetch AwsClient path.

Benchmark results (from repro)

Step	Direct S3	Credential Proxy	Delta
read-small (1 KiB)	133ms	206ms	+73ms
read-large (512 KiB)	69ms	100ms	+31ms
read-large-repeat (5x)	388ms	285ms	-103ms
cached-head 20x reads	2102ms	1297ms	-805ms
list-files	1898ms	107ms	-1791ms

Credential-proxy now avoids redundant upstream HEAD requests on repeated metadata reads.

changeset-bot · 2026-06-11T10:32:06Z

🦋 Changeset detected

Latest commit: 9b670bf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/sandbox	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2026-06-11T10:34:00Z

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/sandbox-sdk/@cloudflare/sandbox@751

commit: 9b670bf

github-actions · 2026-06-11T10:34:01Z

📦 Preview Build

Version: 0.0.0-pr-751-9b670bfd

Install the SDK preview:

npm i https://pkg.pr.new/cloudflare/sandbox-sdk/@cloudflare/sandbox@751

🐳 Docker images were not rebuilt — no container changes detected. Use the latest release images from Docker Hub.

Keep the established SigV4 signer for credential-proxy mounts while retaining the metadata cache behavior. This keeps the cache change focused on reducing redundant HEAD requests without expanding signing risk.

devin-ai-integration

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

aron-cf

Thanks for digging into the HEAD traffic. Did you look at tweaking s3fs’s own stat cache? I don't really want to add an additional layer when the one in s3fs should be doing this already (unless I've missed something).

Right now sandbox-sdk sets these defaults for R2-backed s3fs mounts:

stat_cache_expire: '60',
enable_noobj_cache: true,
multipart_size: '5'

s3fs also supports max_stat_cache_size, stat_cache_expire, and negative caching (enable_negative_cache / disable_negative_cache; negative cache appears to be enabled by default in current s3fs).

Have we tried to repro with larger s3fs options first? for example:

s3fsOptions: [
  'stat_cache_expire=300',
  'max_stat_cache_size=100000',
  'enable_negative_cache'
]

aron-cf

After looking at s3fs I think this is probably useful for common cases where a bucket is mounted and owned by a single container or the bucket is largely read only.

It's a bit risky for anything intended to be shared collaboratively. I'd suggest we roll this out under an opt-in flag, with configurable timeouts and document which usecases will benefit and which wont.

aron-cf · 2026-06-22T12:31:05Z

 const DEFAULT_SLOW_REQUEST_MS = 1000;
 const ERROR_RESPONSE_BODY_LIMIT = 2048;
 const MAX_DIAGNOSTIC_EVENTS = 500;
+const HEAD_METADATA_CACHE_TTL_MS = 60_000;


This feels risky, if something updates/deletes the object, we keep serving the old HEAD result for up to a minute. Could we make this shorter or configurable... this works well for cases where this bucket is not changing often but if the bucket is shared with another writer then this will get problematic.

aron-cf · 2026-06-22T12:31:33Z

 const ERROR_RESPONSE_BODY_LIMIT = 2048;
 const MAX_DIAGNOSTIC_EVENTS = 500;
+const HEAD_METADATA_CACHE_TTL_MS = 60_000;
+const NEGATIVE_HEAD_METADATA_CACHE_TTL_MS = 5_000;


Ditto here, this means an object created externally will be missing for 5s.

aron-cf · 2026-06-22T12:32:33Z

+  }
+}
+
+function getHeadMetadataCacheKey(


The cache key is scoped by mountId, not by the underlying bucket/endpoint identity, this doesn't feel right. If you have the same bucket mounted in two places the cache should be the same right?

aron-cf · 2026-06-22T12:33:44Z

+  return `${mountId}:${realPath}${url.search}`;
+}
+
+function getCachedHeadMetadataResponse(


This defeats s3fs’s open-time revalidation. s3fs intentionally drops its own stat cache on reopen and sends a HEAD; with this cache, that HEAD may be answered locally instead of actually revalidating against the bucket. I think this behaviour in s3fs is probably what led to this PR. But it makes me think that this cache layer should be opt-in and extremely configurable.

aron-cf · 2026-06-22T12:35:59Z

+  });
+}
+
+function cacheHeadMetadataFromPUT(


This is neat. How do we ensure that we're accurately matching what the provider actually responds with? Feels like this might need an integration test to verify our code matches the various provider implementations.

aron-cf · 2026-06-22T12:37:52Z

+    }
+  } else if (isMutatingMethod(method)) {
    deleteDirectoryMarkerCacheEntry(mountId, realPath);
+    deleteHeadMetadataCacheEntriesForObject(mountId, realPath);


For non-HEAD mutating requests, we invalidate before forwarding. There’s a possible race where a HEAD during an in-flight DELETE/POST/copy/multipart operation can cache an old upstream metadata, and then the mutation succeeds. Should we also invalidate after successful mutations?

aron-cf · 2026-06-22T12:39:17Z

              );

        if (response.ok) {
          directoryMarkerCache.set(


The directory marker cache looks like it has no TTL. External changes can leave us with stale directory metadata for the lifetime of the mount unless something local invalidates it. Can we add the same invalidation pattern?

Implement proxy mount read caching

ca359fe

scuffi added 3 commits June 16, 2026 15:40

ci: re-trigger pipeline to regenerate expired build artifact

f7b324e

fix stale metadata requests

5250f16

Use AwsClient for proxy signing

9b670bf

Keep the established SigV4 signer for credential-proxy mounts while retaining the metadata cache behavior. This keeps the cache change focused on reducing redundant HEAD requests without expanding signing risk.

scuffi marked this pull request as ready for review June 18, 2026 10:25

scuffi requested review from aron-cf, ghostwriternr and whoiskatrin as code owners June 18, 2026 10:25

devin-ai-integration Bot reviewed Jun 18, 2026

View reviewed changes

aron-cf reviewed Jun 22, 2026

View reviewed changes

aron-cf requested changes Jun 22, 2026

View reviewed changes

Conversation

scuffi commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

HEAD metadata cache (s3-credential-proxy-handler.ts)

Cache lifecycle (sandbox.ts)

Request forwarding safety

Benchmark results (from repro)

Uh oh!

changeset-bot Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Preview Build

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

✅ Devin Review: No Issues Found

Uh oh!

aron-cf left a comment

Choose a reason for hiding this comment

Uh oh!

aron-cf left a comment

Choose a reason for hiding this comment

Uh oh!

aron-cf Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

aron-cf Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

aron-cf Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

aron-cf Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

aron-cf Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

aron-cf Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

aron-cf Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

scuffi commented Jun 11, 2026 •

edited

Loading

HEAD metadata cache (`s3-credential-proxy-handler.ts`)

Cache lifecycle (`sandbox.ts`)

changeset-bot Bot commented Jun 11, 2026 •

edited

Loading

pkg-pr-new Bot commented Jun 11, 2026 •

edited

Loading

github-actions Bot commented Jun 11, 2026 •

edited

Loading