Your data layer, cached, without your callers knowing.
protoc-gen-cache is a protoc plugin that turns
cache.v1 annotations on your AIP protobuf into typed read-through
caches in front of the stores and repositories
protoc-gen-store
generates, in Go and Rust, and
refuses to emit when the result would let one tenant read
another's rows.
Caution
Early development. The generated output may change between versions. Pin a release tag in CI and review the diff before shipping a regenerated cache — a changed namespace orphans a live cache on deploy.
- Why
- Languages
- The problem it actually solves
- Setup
- Strategies
- Annotations
- Scoping and the namespace
- What a write reaches
- Caching lists
- Two paths, and they do not stack
- Go
- Rust
- Architecture
- What it does not do
- Adding a language
- Development
- License
A cache in front of a database is four hard problems wearing a trench coat, and the hand-written version gets three of them wrong. It stampedes: a thousand concurrent misses on a hot key become a thousand identical loads at the worst possible moment. It caches the value but not its absence, so a request for something that does not exist reloads forever. It blocks every reader the instant a hot key expires. And it invalidates by hand, which means the invalidation is correct until the day someone adds a write path and forgets.
The runtimes already solve all four:
runtime-go's cache and
runtime-rs's tpp-cache,
over Redis, Dragonfly and memcached. What a runtime cannot know is your schema:
which resources are worth caching, what separates one tenant's entries from
another's, which column you look things up by, and which writes make which other
entries stale. That is in your protos already, as AIP annotations, and this
plugin is the part that reads it.
In every language the output has the same shape as what it wraps, so a caller
cannot tell a cached data layer from an uncached one: in Go, a decorator
implementing the <Model>StoreIface protoc-gen-store emitted; in Rust, the same
Repositories struct, with each cached resource's repository replaced by a
cached one.
flowchart LR
P[".proto + AIP<br/>+ cache.v1"] --> IR["protokit IR<br/>databases, schemas,<br/>tables, columns"]
IR --> ST["protoc-gen-store<br/>stores / repositories"]
IR --> CA["protoc-gen-cache<br/>strategy, namespace,<br/>indexes, edges"]
ST --> D["the same interface,<br/>cached"]
CA --> D
D --> RT["the language's cache runtime<br/>singleflight, negative caching,<br/>TTL, stale, index maintenance"]
Neither plugin knows the other ran. They agree on every database, schema, table
and column name because they read the neutral vocabulary through the same
imported reader — not a shared convention, a shared function. That is the claim
TestIRAgreement holds them to, against the real protoc-gen-store rather than a
stand-in.
One spec is built from your annotations, and every language renders it, so the same refusals, namespaces, strategies, indexes and edges apply everywhere.
| Language | Option | What you get | Wraps (from protoc-gen-store) | Runtime |
|---|---|---|---|---|
| Go | (default) | One cache.go per schema: a typed decorator per resource (NewCached<Model>Store), its scope and Open<Model>Cache, declared invalidation edges; with list, a list cache in list.go |
target=gorm stores=true's <Model>StoreIface; lists wrap target=repository |
runtime-go cache |
| Rust | lang=rust |
One cache.rs per proto package: each resource's cache plan as data, cache_repositories(…), declared invalidation edges; record and list caching |
lang=rust target=repository's Repositories |
runtime-rs tpp-database (cached) + tpp-cache |
Both lay keys out the same way ({prefix}:{namespace}:cache:…), with the
namespace derived the same way. The record values are encoded differently (Go's
store decorator caches its GORM model, Rust caches the proto message), so when a
Go and a Rust service share a cache server, give each its own Config.Prefix.
Rust details the rest, and the few features one language has that the
other doesn't yet.
Generating cache wiring is the easy half. The hard half is that a cache answers before the store is consulted, so on a hit the store's scoping never runs.
Every row-level guard a store applies — a WHERE on a parent id, a policy on a
connection, a tenant column — lives inside the loader, and the loader runs only
on a miss. Put a cache in front of a nested resource without binding the parent
into the key, and two tenants share a keyspace:
message Document {
option (google.api.resource) = {
type: "tenancy.v1/Document"
pattern: "users/{user}/documents/{document}" // ← nested under {user}
};
option (cache.v1.cache) = {enabled: true};
string user_id = 2 [(google.api.field_behavior) = REQUIRED]; // ← binds nothing
}The first hit serves whichever tenant was cached first. Nothing downstream recovers from it: not a review, not a test that happens to use one tenant, not a runtime check the runtime has no way to make. So this is the one thing the generator refuses to emit:
$ buf generate
cache: tenancy.v1.Document: the resource pattern "users/{user}/documents/{document}"
nests this resource under {user}, but no field binds that segment into the
cache namespace.
A cache answers before the store is consulted, so on a hit the store's
row-level scoping never runs. With {user} unbound, every parent's entries
share one keyspace and the first hit serves whichever was cached first —
one tenant reading another's rows. This is the one thing this generator
refuses to emit.
Bind it on the field that carries the parent's id:
string user_id = N [(cache.v1.cache_scope) = {}];A warning would not do. It would be printed into a build log next to a hundred others, and the output would still be generated, and it would still compile, and it would still be wrong.
From nothing to a cached data layer that compiles, in Go or Rust. protoc-gen-cache caches what protoc-gen-store generates, so you run both plugins; steps 1–3 are the same for every language.
You need: buf (or protoc), your
language's toolchain, and a cache server for running it (Redis, Dragonfly or
memcached). Go is not required unless you generate Go.
Install both plugins, any one way each, and make sure they are on your PATH:
# Homebrew (macOS / Linux)
brew install the-protobuf-project/tap/protoc-gen-cache
brew install the-protobuf-project/tap/protoc-gen-store
# Or a prebuilt binary (linux / darwin / windows, amd64 / arm64) from each
# repository's Releases page, unpacked onto your PATH
# Or build them with Go
go install github.com/the-protobuf-project/cache/plugin/cmd/protoc-gen-cache@latest
go install github.com/the-protobuf-project/store/plugin/cmd/protoc-gen-store@latestCheck them: protoc-gen-cache --version, protoc-gen-store --version. In CI,
pin releases: the versions are written into the generated banners, so pinning
keeps regenerated output byte-identical.
cache.v1 and the entity.v1 / store.v1 vocabulary it builds on are
published on the Buf Schema Registry:
# buf.yaml
version: v2
modules:
- path: proto
deps:
- buf.build/googleapis/googleapis # google.api.resource, field_behavior
- buf.build/the-protobuf-project/store # entity.v1 + store.v1
- buf.build/the-protobuf-project/cache # cache.v1buf dep updateA resource is cached when it says so. A nested resource must bind each parent segment of its pattern into the cache namespace, or generation is refused:
// proto/bookstore/v1/bookstore.proto
syntax = "proto3";
package bookstore.v1;
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "entity/v1/annotations.proto";
import "cache/v1/annotations.proto";
option (entity.v1.datasource) = {database: "bookstore_db" provider: "postgres"};
message Author {
option (google.api.resource) = {
type: "bookstore.v1/Author"
pattern: "authors/{author}"
singular: "author"
plural: "authors"
};
option (entity.v1.table) = {id: ID_STRATEGY_ULID, timestamps: true};
option (cache.v1.cache) = {enabled: true, ttl: {seconds: 300}};
string name = 1 [(google.api.field_behavior) = IDENTIFIER];
string display_name = 2 [(google.api.field_behavior) = REQUIRED];
}
message Book {
option (google.api.resource) = {
type: "bookstore.v1/Book"
pattern: "authors/{author}/books/{book}"
singular: "book"
plural: "books"
};
option (entity.v1.table) = {id: ID_STRATEGY_ULID, timestamps: true};
option (cache.v1.cache) = {
enabled: true
strategy: STRATEGY_INDEXED
ttl: {seconds: 120}
};
string name = 1 [(google.api.field_behavior) = IDENTIFIER];
string title = 2 [(google.api.field_behavior) = REQUIRED];
// Binds {author}: each author's books get their own keyspace. The reference
// also declares an edge: writing a Book invalidates its Author's entry.
string author_id = 3 [
(google.api.resource_reference) = {type: "bookstore.v1/Author"},
(cache.v1.cache_scope) = {}
];
// A secondary index: books are findable by ISBN.
string isbn = 4 [(cache.v1.cache_index) = {}];
}Note
protoc asks every plugin for a Go import path, even when nothing it writes is
Go. The templates below supply one with buf's
managed mode
(go_package_prefix), so your protos need no option go_package; for Rust the
value is never used.
protoc-gen-store writes the GORM models and the typed stores
(stores=true is what emits the <Model>StoreIface the cache decorates);
protoc-gen-cache writes the decorators. store_module is the import path of
store's output: the only thing connecting the two runs.
# buf.gen.yaml
version: v2
managed:
enabled: true
override:
- file_option: go_package_prefix
value: example.com/app/gen/go/pb
disable:
- module: buf.build/googleapis/googleapis
- module: buf.build/the-protobuf-project/store
- module: buf.build/the-protobuf-project/cache
inputs:
- directory: proto
plugins:
- remote: buf.build/protocolbuffers/go:v1.36.11
out: gen/go/pb
opt: module=example.com/app/gen/go/pb
- local: protoc-gen-store
out: gen/go/gorm
strategy: all
opt:
- target=gorm
- stores=true # required: emits <Model>StoreIface
- go_module=example.com/app/gen/go/gorm
- local: protoc-gen-cache
out: gen/go/cache
strategy: all
opt:
- store_module=example.com/app/gen/go/gorm # store's go_modulebuf generate
# Require the plugin modules at the releases you generate with: the generated
# code imports their annotation packages.
go get gorm.io/gorm gorm.io/driver/postgres \
github.com/the-protobuf-project/store@v1.8.0 \
github.com/the-protobuf-project/cache@v0.4.0 \
github.com/the-protobuf-project/runtime-go/cache@main
go mod tidyWire the cache in front of the stores:
import (
"example.com/app/gen/go/cache/bookstore_db/bookstorev1cache"
"example.com/app/gen/go/gorm/bookstoredb/bookstorev1"
"github.com/the-protobuf-project/runtime-go/cache"
"github.com/the-protobuf-project/runtime-go/cache/redis"
)
notFound := bookstorev1cache.WithNotFound(func(err error) bool {
return errors.Is(err, gorm.ErrRecordNotFound) // lets absences be cached
})
client, err := redis.NewClient(ctx, redis.Config{Address: "localhost:6379"})
provider := redis.New(client, cache.Config{Prefix: "bookstore", DefaultTTL: 5 * time.Minute})
authorDB, err := bookstorev1cache.OpenAuthorCache(ctx, provider)
authors, err := bookstorev1cache.NewCachedAuthorStore(ctx,
bookstorev1.NewAuthorStore(gdb), authorDB, notFound)
scope := bookstorev1cache.BookScope{AuthorID: authorID} // one author's books
bookDB, err := bookstorev1cache.OpenBookCache(ctx, provider, scope)
books, err := bookstorev1cache.NewCachedBookStore(ctx,
bookstorev1.NewBookStore(gdb), bookDB, scope,
bookstorev1cache.BookEdges{Author: authors.(bookstorev1cache.Invalidator)},
notFound)books is a bookstorev1.BookStoreIface, the interface the uncached store
satisfies, so callers don't change. Close each cache database and the client on
shutdown. Next: Go covers the repositories, list caching and the runnable
example.
protoc-gen-store writes the repositories and protoc-gen-cache writes each
package's cache.rs beside them, into the same out:: store's mod.rs
declares pub mod cache; for every package with a cached resource.
# buf.gen.yaml
version: v2
managed:
enabled: true
override:
- file_option: go_package_prefix
value: example.com/unused # see the note above
disable:
- module: buf.build/googleapis/googleapis
- module: buf.build/the-protobuf-project/store
- module: buf.build/the-protobuf-project/cache
inputs:
- directory: proto
plugins:
- local: protoc-gen-store
out: gen/rust/repository
strategy: all
opt:
- lang=rust
- target=repository
- crate=bookstore
- local: protoc-gen-cache
out: gen/rust/repository # the same out: as store
strategy: all
opt:
- lang=rust
- rust_repository_module=crate::repository # where you mount store's cratebuf generate
buf build proto --exclude-source-info -o descriptor.binpbSet up the crate exactly as
store's Rust setup
does (build.rs deriving prost_reflect::ReflectMessage, the messages at
crate::pb, the generated tree at crate::repository), then add the cached
feature and the cache runtime:
[dependencies]
tpp-database = { git = "https://github.com/the-protobuf-project/runtime-rs", branch = "main", default-features = false, features = ["orm-postgres", "cached"] }
tpp-cache = { git = "https://github.com/the-protobuf-project/runtime-rs", branch = "main" }
prost = "0.14"
prost-types = "0.14"
prost-reflect = { version = "0.16", features = ["derive"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
[build-dependencies]
prost = "0.14"
prost-build = "0.14"
prost-types = "0.14"Commit Cargo.lock: it records which runtime-rs commit you build against.
Wire the cache in front of the repositories:
use std::{sync::Arc, time::Duration};
use cache::Provider as _; // set_database on the cache provider
use cache::drivers::redis::{RedisClient, RedisConfig, RedisProvider};
use database::orm::{OrmProvider, sqlx::postgres::PgPoolOptions};
use database::records::Provider as _; // set_database on the records provider
use my_app::{DESCRIPTOR_POOL, repository::bookstore::v1 as bookstore};
let pool = PgPoolOptions::new().connect(&std::env::var("DATABASE_URL")?).await?;
let db = OrmProvider::new(pool).set_database("").await?;
let repos = bookstore::repositories(&db, &DESCRIPTOR_POOL)?; // protoc-gen-store
let client = Arc::new(RedisClient::connect(RedisConfig {
address: "localhost:6379".to_owned(),
..RedisConfig::default()
}).await?);
let provider = RedisProvider::new(client, cache::Config {
prefix: "bookstore".to_owned(),
default_ttl: Duration::from_secs(300),
..cache::Config::default()
});
let cdb = provider.set_database("bookstore").await?;
let repos = bookstore::cache::cache_repositories(repos, Arc::new(cdb)); // protoc-gen-cache
let book = repos.books.get("authors/ursula/books/lhd").await?;repos is the same Repositories type, with authors and books now cached;
uncached resources pass through. One cached repository serves every author: each
record's namespace is read from its name. Next: Rust.
| Symptom | Cause and fix |
|---|---|
program not found or is not executable |
A plugin isn't on PATH. Check protoc-gen-cache --version and protoc-gen-store --version. |
cache/v1/annotations.proto: file does not exist |
Add buf.build/the-protobuf-project/cache to deps and run buf dep update. |
cache: …: the resource pattern … nests this resource under {x}, but no field binds that segment |
Working as intended: the cache would mix parents' entries. Mark the field that carries the parent's id (cache.v1.cache_scope) = {}. See Scoping. |
cache: the store_module opt is required |
Go: set store_module to protoc-gen-store's go_module. |
Go: undefined: …StoreIface |
protoc-gen-store ran without stores=true. |
Go: undefined: <Model>Edges |
The resource declares no edge: only a google.api.resource_reference to another cached resource makes one. |
Go: ambiguous import: … store/plugin/entity/pb/entitypbv1 in multiple modules |
Require the store module itself: go get github.com/the-protobuf-project/store@v1.8.0. |
Go: … is configured as INDEXED, which requires core.Sets at startup |
The backend can't serve the strategy (memcached has no sets). Use Redis or Dragonfly, or STRATEGY_ASIDE. |
Rust: unresolved module … cache or crate::bookstore not found |
cache.rs must land beside store's mod.rs (the same out:), and rust_repository_module must name where store's crate is mounted. |
Rust: no method named set_database |
Bring the provider's trait into scope: use cache::Provider as _; / use database::records::Provider as _;. |
Rust: generation refused for a cache_scope field that is not a pattern segment |
A Rust repository is asked for a record by name alone, so a scope must come from the name. Scope by a pattern segment. |
| Entries never invalidate after writes from another service | A write that bypasses the generated layer (hand-written SQL, another service) is seen by nothing; ttl bounds how long it stays stale. |
Four, because runtime-go implements four. A vocabulary that could express a fifth would describe output nothing will honor.
| Strategy | Reads by | Enumerates | Secondary index | Needs |
|---|---|---|---|---|
ASIDE (default) |
id, read-through | no | no | — |
INDEXED |
id + any indexed field | yes | yes | core.Sets |
DOCUMENT |
id | yes | no | core.Sets |
VOLATILE |
key | no | no | — |
A stale window on any of them additionally needs core.Leases.
Nothing in cache.v1 names a backend. Redis, Dragonfly and memcached differ in
what they can do, and the runtime already models that as capabilities a driver
either has or does not:
---
title: "What each backend can serve"
config:
themeVariables:
cScale0: "#D22128"
cScale1: "#1F9D55"
cScale2: "#4285F4"
---
radar-beta
axis sets["Sets<br/>(index)"], leases["Leases<br/>(stale)"], setscan["SetScanner"]
axis scan["Scanner"], bulk["Bulk"], fenced["Fenced"]
curve redis["Redis"]{1, 1, 1, 1, 1, 1}
curve dragonfly["Dragonfly"]{1, 1, 1, 1, 1, 1}
curve memcached["memcached"]{0, 0, 0, 0, 1, 0}
max 1
min 0
Redis and Dragonfly trace the same shape because they are the same driver — both speak RESP and share one RESP implementation in each runtime. Swapping one for the other is a change of constructor and nothing else.
memcached is the shape that matters. It has Bulk and nothing else: no
server-side sets, so no index and no enumeration, and a protocol that stores an
expiry but will never say what is left of it, so no stale window. An INDEXED
resource on memcached would compile, construct, and then fail every lookup it
exists to serve — on a code path a developer running Redis locally never reaches.
So the generated Go constructor probes and refuses at startup, naming the resource, the strategy and the missing capability (Rust's constructor is infallible and reports it per write instead; see Rust):
cache: bookstore.v1.Book is configured as INDEXED, which requires core.Sets, and
the memcache backend behind this cache database does not implement it:
cache: unsupported
A backend with no server-side sets cannot maintain a secondary index or enumerate
entries. Either move this resource to STRATEGY_ASIDE or STRATEGY_VOLATILE, or
wire it to a backend with sets (redis, dragonfly).The same requirement is also declared in plugin.yaml, under
requires_capability, so whatever eventually schedules a multi-plugin run can
refuse a plan before anything is written. The two are not redundant: that one
fails early, and this one is the only check that sees the driver a process
actually wired up.
Message — (cache.v1.cache)
| Field | Meaning |
|---|---|
enabled |
Cache this resource. Explicit, so a configuration can be switched off without being deleted. |
strategy |
ASIDE (default), INDEXED, DOCUMENT, VOLATILE. |
ttl |
How long an entry stays fresh. |
stale |
How long past ttl an entry may be served while it refreshes. Needs core.Leases. |
negative_ttl |
How long an absence is remembered. |
namespace |
Override the derived namespace. Must bind every parent segment. |
File — (cache.v1.cache_defaults): strategy, ttl, stale,
negative_ttl. A per-message value always wins.
Field — (cache.v1.cache_index) files a secondary index; string columns only,
because the runtime's index is keyed by string end to end and inventing a
rendering for an int would mean anything else reading that index has to guess the
same one. (cache.v1.cache_scope) binds a field into the namespace.
There is deliberately no prefix. The runtime owns that, as
cache.Config.Prefix, because a prefix separates one deployment's keys from
another's — and an annotation that travels with the proto cannot express that.
cache.v1 shipped one once; the first program to set both simply concatenated
them. See finding 6.
Every parent segment of a resource pattern must be bound. How a segment finds its binding, in order:
flowchart TD
S["parent segment {org}"] --> A{"a field says<br/>segment: 'org'?"}
A -- yes --> U["use it<br/><i>explicit always wins</i>"]
A -- no --> B{"a scope field's column<br/>is 'org' or 'org_id'?"}
B -- yes --> U
B -- no --> C{"a scope field's<br/>resource_reference names<br/>the parent's type?"}
C -- yes --> U
C -- no --> D{"an explicit namespace<br/>template contains {org}?"}
D -- yes --> T["bind through the template"]
D -- no --> R["REFUSE<br/>naming the resource,<br/>the pattern and the fix"]
Binding is deliberately explicit — a field must carry
(cache.v1.cache_scope) to be a candidate at all. protokit materializes a parent
FK column for every nested resource whether or not anyone thought about tenancy,
so an inference that fired on a column's shape alone would make the refusal
unreachable.
Two more guards run when Go's decorator is constructed, because they depend on facts only the deployment knows (in Rust, each record's namespace is derived from its name, so there is no scope value to get wrong):
- Namespace. The
*cache.DByou pass must have been opened under the namespace this decorator's keys are derived for. Use the generatedOpen<Model>Cache, or get an error naming the resource. - Capabilities. The probe above.
And one that no namespace check would catch: an empty scope value is refused.
BookScope{} produces a self-consistent namespace, so the decorator and the
database agree and the namespace assertion passes — while every parent collapses
into one keyspace, which is the exact failure the scope exists to prevent.
A write to Book invalidates the Author entries that preload it. Those edges
are declared in the output, not walked at runtime:
var InvalidationEdges = []Edge{
{From: "bookstore.v1.Book", To: "bookstore.v1.Author", Via: "author_id",
Reason: "Book.author_id references Author, so writing a Book changes what that Author preloads"},
}In Rust the same edges are INVALIDATION_EDGES, and each is part of the
resource's plan. Go's decorator fires them through named fields on BookEdges —
a nil field is a decision not to invalidate, made in the open. The set is emitted alongside so the
blast radius of a write is legible, and so a CDC consumer can read it later
without regenerating anything.
Here is that blast radius, for one Create of one Book — an INDEXED resource
with one index and one edge:
sankey-beta
"Book.Create","database",2
"Book.Create","cache",4
"database","INSERT the row",1
"database","SELECT it back (the aside loader)",1
"cache","write aside:entry",1
"cache","idx:entry Update - misses",1
"cache","idx:entry Create",1
"cache","DEL the Author entry",1
Widths are round trips. Two of them are worth knowing about before you reach for
INDEXED, and neither is this generator's to fix:
- The
SELECT.Aside.Refreshruns the loader, and the loader isGetByID— so everyCreateandUpdatere-reads from the database the row it was just handed.cache.AsidehasGetOrLoad,RefreshandInvalidateand noPut, so there is no way to hand it the value in hand. Finding 7. - Two entries for one row.
GetByIDreads the Aside entry whileByISBNreads the Indexed one, and they live under different keys. Finding 8.
A failed invalidation does not fail your write. The store write commits before any of this runs, so returning the error would tell a caller their write failed when it did not — and the ordinary response to that is a retry, which makes a second row. By default the error does not travel; staleness bounded by the TTL is the better trade. Both halves are opt-in:
// Go
WithWriteErrors(func(ctx context.Context, resource, op string, err error) { ... })
WithStrictWrites() // the other trade: fail the call rather than serve stale// Rust: cache_repositories_with(repos, cache, hooks)
Hooks { write_errors: Some(/* observe */), strict_writes: true, ..Hooks::default() }Mind the resource with no ttl: its entries persist until something invalidates
them, so a dropped invalidation there is not stale-for-a-minute, it is stale until
the next successful write.
A record decorator never caches List. A page is keyed by everything the
List was asked — parent, filter, order, page size and token — and one write can
change many pages: a new record lands on some page and shifts every page after
it. Which pages a write reached is not knowable, so a list cache does not try.
(cache.v1.cache).list turns on a separate cache for a resource's pages:
message Book {
option (cache.v1.cache) = {
list: {enabled: true, ttl: {seconds: 60}}
};
}In Go it is generated into list.go, beside the record decorators, and it wraps
protoc-gen-store's repository (<Model>Repository) rather than its store,
so one cache serves the GORM and the GraphQL backend alike. It needs the
repository_module opt, pointing at the repository target's output. In Rust the
cached repository serves pages itself, under the same versioning scheme and the
same page keys as Go.
How a page stays correct. Each parent has a version. A page is cached under
its parent's version, and a write to any record under the parent replaces that
version with a fresh one. Pages under the old version are never read again and
expire on their own. A List across parents (an AIP-159 -) reads a version
every write moves on. Readers never write a version — one finding none reads
under "0" — so a reader can never resurrect a page a write retired.
How a write is seen (Go). runtime-go's database/repox Conn (which protoc-gen-store's repositories build on) carries a
ChangeObserver, and every repository and Batch built from that connection
reports each record it writes to it, after the write commits. The generated
<Model>ListCache is that observer:
db, _ := bookstorev1cache.OpenBookListCache(ctx, provider)
lists, _ := bookstorev1cache.NewBookListCache(db, bookstorev1cache.WithListErrors(logIt))
conn := repox.Conn{Gorm: gdb, Changes: repox.Changes{lists}}
books := lists.Wrap(bookstorev1.New(conn).Books)Putting the observer on the connection, not on one repository, is the point: a process builds many repositories, and a write through any of them must reach the cache. In Rust the cached repository is the write path, so it sees its own writes and needs no observer.
What bounds it. A write that does not go through the generated
repositories — SQL by hand, another service on the same table — is seen by
nothing, and the pages it made stale are served until ttl ends. That is why
ttl is required, and generation is refused without one. Between a write
committing and its version moving on there is also a window of one round trip
in which a reader can still be handed the old page.
What it never does. A cache failure never fails a List or the write behind
it. A read the cache cannot answer goes to the repository; a page that cannot be
stored, or a version that cannot be moved on, is reported to WithListErrors.
Wire that: a version that silently stopped moving is a list served stale for its
whole ttl.
Each language's runtime also has an untyped cache at the driver level: Go's
cached.Wrap, and Rust's database::cached (the cached feature). The generated
cache and the untyped one are different tools:
| Generated cache (this plugin) | Untyped driver cache (the runtime) | |
|---|---|---|
| Level | Typed, per resource | Untyped, per driver |
| Wraps | Go: BookStoreIface; Rust: Repository<Book> |
Go: store.Driver; Rust: a records driver |
| Payload | Your model (Go: JSON; Rust: proto) | Raw bytes |
| Knows about | Namespaces, scopes, index fields, invalidation edges | Keys and values |
| Setup | Generated from annotations | One call |
// Go, untyped: decorates any store.Driver at the byte level
db = cached.Wrap(db, cached.FromAside(cdb, cache.TTL(time.Minute)))They are alternatives, not layers. Stacking them puts two caches on one read: the decorator hits, or misses and calls a store whose driver caches the same row again under a different key — and an invalidation through one leaves the other serving what it just invalidated.
The Go output is one cache.go per schema (<out>/<database>/<package>cache/),
holding for each cached resource a decorator over protoc-gen-store's
<Model>StoreIface, its scope type and Open<Model>Cache, and the declared
InvalidationEdges; with list caching, list.go beside it. Setup is in
Setup → Go.
Under protoc-gen-store's repositories (store v1.7.0 and later), put it there with
the repository option With<Model>Store, which builds the store a repository
goes through over each handle it uses — its own, or the transaction a write runs
in. A repository's Get of a one-row resource then reads through the decorator:
repos := bookstore.New(conn, bookstore.WithBookStore(func(db *gorm.DB) gormbookstore.BookStoreIface {
s, err := bookstorev1cache.NewCachedBookStore(ctx, gormbookstore.NewBookStore(db), cdb, scope)
if err != nil {
return gormbookstore.NewBookStore(db) // the cache is optional; the store is not
}
return s
}))The function runs for every repository read and write, so open the cache (cdb)
once, outside it.
Lists wrap protoc-gen-store's repositories rather than its stores; see Caching lists for the wiring.
docker run --rm -p 6379:6379 redis:7 # or: redis-server --port 6379
cd examples && go run ./cmd/bookstoreThe example is one straight run of numbered steps, deliberately unfactored, so the lifecycle reads top to bottom:
1. open redis client
2. build provider
3. open author cache database
4. seed the inner author store
5. build cached author store
6. bind the book scope
7. open book cache database
8. build cached book store (asserts core.Sets)
9. read author -> Ursula K. Le Guin (miss, loaded from store, store loads: 1)
10. read author -> Ursula K. Le Guin (hit, store loads: 1)
11. write book -> created, edge fired at bookstore.v1.Author
12. read author -> reloaded (store loads: 2 — the edge worked)
13. by isbn -> 1 book(s) filed under 9780441013593
14. declared invalidation edges:
bookstore.v1.Book -> bookstore.v1.Author (via author_id)
15. entries left in redis, by namespace: ...
teardown (reverse order):
close book cache database
close author cache database
close redis client
The store-load counter is doing the work: unchanged between 9 and 10 is the cache hit, moving at 12 is the declared edge having actually dropped the Author entry. Steps 10 and 12 fail rather than print if either stops being true — a demo that can only ever print success is not showing you anything.
Nothing is deleted on the way out. The teardown closes; it does not drop. The argument about who owns which part of a key is only convincing if you can go and look:
$ redis-cli --scan --pattern 'bookstore:*'
bookstore:bookstore.v1.author:cache:aside:entry:author-ursula
bookstore:bookstore.v1.book.author.author-ursula:cache:aside:entry:book-lhd
bookstore:bookstore.v1.book.author.author-ursula:cache:idx:by:isbn:9780441013593
bookstore:bookstore.v1.book.author.author-ursula:cache:idx:entry:book-lhd
bookstore:bookstore.v1.book.author.author-ursula:cache:idx:fields:book-lhd
bookstore:bookstore.v1.book.author.author-ursula:cache:idx:indexTake one apart:
bookstore : bookstore.v1.book.author.author-ursula : cache:idx:by:isbn:9780441013593
───────── ──────────────────────────────────────── ──────────────────────────────
Config.Prefix this plugin runtime-go/cache/core
your deployment the namespace the keyspace
Three segments, three owners, no overlap. The middle one is the whole of what this
plugin emits about keys — author.author-ursula is the tenancy boundary, and a
decorator built for another author cannot reach these entries.
lang=rust renders the spec for
runtime-rs: one cache.rs per
proto package (bookstore/v1/cache.rs), in front of the repositories protoc-gen-store
generates with lang=rust target=repository. Setup is in Setup → Rust.
plugins:
- local: protoc-gen-cache
out: src/generated
opt:
- lang=rust
- rust_repository_module=crate # the default
- rust_proto_module=crate::pb # the defaultBoth options are base modules, and the proto package is appended to each as a module
path (bookstore.v1 -> ::bookstore::v1), exactly as protoc-gen-store's and
protoc-gen-service's Rust targets read rust_proto_module:
| Option | Default | Names |
|---|---|---|
rust_proto_module |
crate::pb |
the prost types: use crate::pb::bookstore::v1 as pb; |
rust_repository_module |
crate |
protoc-gen-store's lang=rust target=repository modules, which it writes at <crate>::<package path>: use crate::bookstore::v1::Repositories; |
So protoc-gen-store and protoc-gen-cache run into one crate need no options. Each
package's cache.rs lands beside protoc-gen-store's mod.rs for it
(bookstore/v1/cache.rs); mount it from there (pub mod cache;) or from wherever the
crate keeps it. Mounted elsewhere, or with the repositories in another crate, set
rust_repository_module to that base (my_store, crate::store). Neither option
takes a template, and a value that is not a module path is refused. No go_package or
M option is needed.
Per package, exactly this to wire against:
pub fn cache_repositories(repos: Repositories, cache: Arc<cache::DB>) -> Repositories;
pub fn cache_repositories_with(repos: Repositories, cache: Arc<cache::DB>, hooks: Hooks) -> Repositories;Each field of Repositories whose resource is annotated is replaced by a cached
Arc<dyn Repository<pb::Model>>; every other field is returned as it was. Beside them:
a Keyspace static per cached resource, a <model>_plan() per resource, and
INVALIDATION_EDGES, the declared edges as data.
let repos = bookstore::v1::repositories(db, pool)?; // protoc-gen-store
let cdb = provider.set_database("bookstore").await?; // any name; see below
let repos = bookstore::v1::cache::cache_repositories(repos, Arc::new(cdb)); // pub mod cache; in bookstore/v1/mod.rsGenerated versus generic. The decorator is not generated: it is runtime-rs's
database::repository::cached, written and tested once. What is generated is each
resource's Plan, everything that differs between resources, as data: its namespace
parts and pattern, strategy, ttl and stale, its index fields, its edges and their
targets' keyspaces, its list cache, and one plain function per proto field the decorator
reads (the name, each index value, each edge's reference).
The two languages render one spec. Where they meet, and the few places one has reached and the other hasn't:
- Refusals. The same spec builds both outputs, so every refusal above applies
unchanged. Rust adds one: a field forced into scope with
(cache.v1.cache_scope)that is not a segment of the pattern. A Rust repository is asked for a record by name alone, and the decorator derives the namespace from that name, so on a get nothing says what such a field's value is. Generation is refused rather than caching without it. - Keys. Byte for byte Go's:
{prefix}:{namespace}:cache:aside:entry:{id}, the namespace derived exactly as Go derives it. Go is constructed per scope; a Rust repository serves every parent, so each record's namespace is read from its name (authors/ursula/books/lhd->bookstore.v1.book.author.ursula) and the cache database is selected under it (cache::DB::under). The database you pass supplies the connection, prefix and policy; its own name is not used. The scope value is the parent segment of the name, which matches Go's when the Go caller's scope field holds that same segment. - Ids and values. The id is the resource name, the record's key in runtime-rs. The
value is the proto wire encoding as a base64 JSON string, Go's encoding of a
[]byteand what runtime-go'sdatabase/cachedstores. Go's store decorator caches its GORM model as JSON, keyed by the store's primary key, so the two record caches meet only where that primary key is the name, and do not read each other's values: a value the Rust decorator cannot decode is dropped and read through, never returned. Give each its ownConfig.Prefixif both run. - Writes. As Go: create, update and undelete refresh the entry (one load, finding 7),
refile the indexes (update, then create), and fire every declared edge; delete and purge
unfile and invalidate, and fire no edge, as Go's
DeleteByIDdoes not. A failure after the commit does not fail the write;Hooks::write_errorsobserves it andHooks::strict_writesmakes it fail, Go'sWithWriteErrorsandWithStrictWrites. An edge's reference may hold the target's name or, for a one-variable pattern, its id. - Lists. Go's scheme: per-parent versions, pages under
{base}.list, the page key Go's SHA-256 of the request (encoded as Go'sencoding/jsonencodes it), the page Go'slistPage. The decorator sees its own writes, so no observer is wired.ListInput.parentis Go'sList(ctx, parent, in)parent: a list reads that parent's version (every parent's for a-, or for an empty parent on a nested resource), and the page key hashes it besiderepox.ListInputexactly as Go does, so nested and top-level pages are shared with Go. The key matches a Gorepox.ListInputwithWhereandReadMaskunset.
Gaps. The constructor is infallible, so there is no startup capability probe: an
INDEXED resource on memcached reports Unsupported to the write hook on each write
instead of refusing at startup, and reads still work. There are no typed index
accessors (ByISBN): the Repository contract has nowhere to put them, so INDEXED
maintains the index for other readers. negative_ttl is not applied, in either language.
service's examples/rust-store
runs both plugins' real Rust output together, under generated servers.
examples/rust here compiles the golden output against runtime-rs and tests hit, miss,
absence, scoping, edges, refiling, the write-error policy and both list shapes over an
in-memory repository and tpp-cache's in-memory driver:
(cd examples/rust && cargo test)Built on protokit, the same IR engine behind store, and laid out the same way.
cache/
├─ protobuf/cache/v1/ the vocabulary — the only thing published
│ annotations.proto the four extensions (52000–52003)
│ cache.proto the option messages and the Strategy enum
├─ plugin/
│ cmd/protoc-gen-cache/ the binary
│ pb/cachepbv1/ generated stubs
│ cachev1/ reads annotations. Decides nothing
│ spec/ decides everything. Every refusal lives here
│ generator/ renders. Nothing is left to check by then
│ templates/ one partial per thing the generated file contains
├─ examples/ its own module
│ proto/ the schemas
│ generated/ both plugins' output
│ cmd/bookstore/ the runnable Redis program
│ decorator/ the tests over the generated decorator
│ fakecache/ a core.Driver whose capabilities are per-instance
│ fakestore/ the store protoc-gen-store would have generated
├─ docs/boundary-findings.md every place the plugin boundary was thinner than it looked
└─ scripts/aip.sh the AIP lint, run in CI and runnable by hand
protobuf/cache/v1 is the vocabulary, published as a BSR module and the only
thing published. Everything under plugin/ runs at generation time:
flowchart TB
subgraph read["reads. Decides nothing"]
CV["cachev1<br/>the cache.v1 FacetReader,<br/>store.v1's unique bit,<br/>plugin.yaml"]
ER["store/plugin/entity<br/><i>imported, never reimplemented</i>"]
end
subgraph decide["decides. Every refusal lives here"]
SP["spec<br/>strategy · namespace · scope<br/>indexes · edges"]
end
subgraph render["renders. Nothing left to check"]
GN["generator<br/>view + target"]
TM["templates/<br/>one partial per thing<br/>the file contains"]
end
CV --> SP
ER --> SP
SP --> GN
GN --> TM
TM --> OUT["cache.go (Go, per schema)<br/>cache.rs (Rust, per package)"]
The dependency runs one way and the three packages are split by how they fail.
cachev1 can only fail on a malformed descriptor. spec is where a schema is
rejected, so its errors have the proto in hand and no template context to muddy
them. generator cannot fail on a schema at all, which is what keeps the
templates free of validation.
The most load-bearing thing in the tree is an omission. cachev1 implements
schema.FacetReader and deliberately not schema.StructureReader. Structure
is how a vocabulary tells protokit what things are called; cache.v1 has
opinions about none of it. So agreement with protoc-gen-store is not a property
anyone maintains — this plugin has no mechanism by which it could move a name.
TestReaderIsNotAStructureReader pins the omission, because the golden and
agreement tests would only catch a violation on names some case happens to
exercise.
It does not generate key templates. The runtime owns key layout (in Go,
runtime-go/cache/core/keyspace.go; in Rust, tpp-cache's keyspace) —
{head}cache:aside:entry:{id} and the rest. This plugin generates
the namespace the keyspace is built under and never a key inside it. Two
keyspaces that have to agree is one keyspace too many, and a golden test asserts
the generated file imports no core.
It does not implement singleflight, negative caching, TTL enforcement, alias/reverse index maintenance, or stale-while-revalidate. All of that is in the runtime, and better than a generator would emit.
The record decorator does not cache lists. It embeds the store interface, so
List, Count and anything protoc-gen-store adds later pass straight through,
uncached. A page is a different cache with different invalidation; that is the
list cache, opted into separately (see Caching lists).
It does not translate your store's errors. Negative caching engages only when
the loader returns something wrapping cache.ErrNotFound, and the generated store
returns its driver's error unchanged. Translating gorm.ErrRecordNotFound here
would mean importing gorm into generated cache code, so it is a constructor
option — WithNotFound — instead.
It does not name a backend. Redis, Dragonfly and memcached differ in capabilities, which the runtime already models; a proto is the wrong place to choose a deployment's infrastructure.
A language renders the spec; it decides nothing. Every refusal, namespace,
strategy, index and edge is decided once in plugin/spec, so a new language
gets them unchanged, and the renderer only lays them out against that
language's cache runtime and protoc-gen-store's output for it.
A new language is done when:
- it renders from
specalone and adds no decisions of its own (a refusal it needs beyond the shared ones goes inspec, as Rust's scope rule did); - its keys match the other languages' byte for byte, so they can share a cache;
- it has golden cases under
plugin/generator/testdataand a compiled example CI builds and tests, asexamples/rustdoes; - it has a Setup section and a section of its own in this README.
Everything resolves from the module proxy — no workspace required, as of
store v1.5.1 being tagged under its own module path.
buf lint && buf format --diff --exit-code && buf build
go build ./... && go vet ./... && go test ./...
(cd examples && go build ./... && go vet ./... && go test ./...)
(cd examples/rust && cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test)
golangci-lint run && (cd examples && golangci-lint run) # both modules: it does not cross one
./scripts/aip.sh # AIP lint, no config and one suppression
# end to end: both plugins over one set of protos, then compile the result.
# The version pin is required, not cosmetic: it lands in the generated banner,
# and an unpinned build reports whatever Go derives from the checkout — a
# pseudo-version at a clean commit, "(devel)" on a dirty tree — so the committed
# examples would never reproduce. CI pins the same value.
go install github.com/the-protobuf-project/store/plugin/cmd/protoc-gen-store@v1.8.0
go install -ldflags "-X main.version=dev" ./plugin/cmd/protoc-gen-cache
buf generate --template buf.gen.example.yamlThe committed go.work groups the two modules for an editor and a
repository-wide test run. It carries no replace directives and nothing depends
on it; GOWORK=off passes in both modules independently, and CI keeps that true.
Two module-graph facts will bite you if you touch go.mod, both in finding 5 of
docs/boundary-findings.md:
- Never require
github.com/the-protobuf-project/store/plugin/entity. It was a nested module, it was deleted, and its old commits are still resolvable — so requiring it puts two modules in the graph that both contain that package and every build fails withambiguous import. Requirestore; the package comes from the root module now. examples/go.modneeds its threereplacelines.runtime-gois untagged, andruntime-go/cachereplaces its siblings in its own go.mod, which Go ignores in a dependency. Arequirecannot substitute: a pseudo-version ofv0.0.0sorts belowv0.0.0, so MVS picks the version that does not exist.
| Job | Covers |
|---|---|
Test (Go) |
the generator: goldens, IR agreement, refusals, manifest, boundary |
Test (examples) |
the generated code — a separate module, so the root's go test ./... never reaches it |
Modules build standalone |
GOWORK=off in both modules, and a guard on the deleted store/plugin/entity |
Integration (Redis) |
the decorator against a real backend, asserting on the keyspace |
Examples reproduce |
the committed output still matches what both plugins emit |
Build (os/arch) |
six platforms |
Lint (Go / Proto / AIP) |
gofmt, vet, golangci-lint; buf build/lint/format and stub freshness; api-linter |
Integration (Redis) is the one that earns its keep. Findings 6, 8 and 9 in
docs/boundary-findings.md — a duplicated key prefix,
an INDEXED resource stored twice, index sets that never expire — passed every
unit test here and were caught only by running the generated code against Redis
and reading the keyspace back. A generator's tests prove its output is consistent
with itself; nothing but a real backend proves it is right.
Tagging v* runs GoReleaser and buf push. Dependabot pull requests merge
themselves once every check passes — see
.github/AUTOMATION.md for how that gate works and why it
does not use GitHub's native auto-merge.
Both the vocabulary and the examples pass
api-linter with one suppression, in
the proto and with its reasoning beside it: AIP-123 wants a google.api.resource
on any message carrying a name field, and IndexOptions is an annotation
payload rather than a resource.
Apache-2.0, matching every other repository in the organization.