cloudflare / cloudflare/workers-rs
[Feature] Bindings for the Workers Cache purge API (ctx.cache.purge)
- 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
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