cloudflare / cloudflare/workers-rs

[Feature] Bindings for the Workers Cache purge API (ctx.cache.purge)

Open
#1,024 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
3.7k
Forks
429
Avg merge
20h 28m
Merged PRs (30d)
7

Description

### Is there an existing issue for this?

- [x] I have searched the existing issues

### Description

The runtime now exposes the newer per-Worker **Workers Cache** (announcement: https://blog.cloudflare.com/workers-cache/, docs: https://developers.cloudflare.com/workers/cache/), which is driven by `Cache-Control` / `Cache-Tag` response headers and has one imperative API: `ctx.cache.purge()` (also available as the `cache` export of `cloudflare:workers`). This is distinct from the Service-Worker Cache API already covered by `worker::Cache` (`caches.default`).

There's currently no way to call `purge` from Rust — `worker::Context` doesn't expose `ctx.cache`, and `worker-sys` has no binding for the `CacheContext` object. I'd like to add bindings for it.

Proposed API:

```rust
use worker::CachePurgeOptions;

// From the execution context (mirrors JS `ctx.cache`)
if let Some(cache) = ctx.cache() {
let result = cache.purge(CachePurgeOptions::tags(["blog-posts"])).await?;
if !result.success {
console_error!("purge failed: {:?}", result.errors);
}
}

// Or without a `ctx` in scope, via the `cloudflare:workers` export
let cache = worker::cache();
cache.purge(CachePurgeOptions::everything()).await?;
```

Shape of the types:

- `Context::cache() -> Option` — `None` when the feature isn't enabled or the runtime predates it.
- `worker::cache() -> CacheContext` — the `cloudflare:workers` module export, for code with no `ctx` in scope.
- `CachePurgeOptions` with constructors `tags(...)`, `path_prefixes(...)`, and `everything()`, serialized to the runtime's camelCase keys (`tags`, `pathPrefixes`, `purgeEverything`). `purge_everything` is validated as mutually exclusive with the other two before crossing the FFI boundary.
- `CachePurgeResult { success: bool, errors: Vec }` mirroring the runtime's result object; a rejected promise (e.g. permission error) surfaces as `Err`.

Contributor guide

Open the contributing guide

Research direction

Start by tracing worker::Context and the worker-sys bindings to understand how existing runtime objects and promises are exposed. Compare the proposed CacheContext, CachePurgeOptions, and CachePurgeResult API with the Workers Cache documentation; done means both access paths, option validation, result handling, and runtime errors are represented consistently.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api, backend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.