@kilnjs/kiche

An encrypted cache for KilnJS whose entries are invalidated by the database driver, packaged as a module core is given rather than one it contains.

Install

yarn add @kilnjs/kiche

// app.config.ts
import { kiche } from "@kilnjs/kiche";

export default {
  modules: [kiche()],
} satisfies AppConfig;

That is the whole installation. Declaring it is what makes every write consult the vaults and retire whatever went stale.

What kiche() takes

Each of these has an environment variable behind it, so a deployment can set one without a build, and each is a default the call site can still override.

kiche({
  scope: process.env.FLY_APP_NAME,

  freshFor: 30_000,
  undeclaredReads: "report",
});

| | | | | --- | --- | --- | | prefix | what every key sits under | CACHE_PREFIX | | scope | separates this deployment's entries from another's | CACHE_SCOPE | | freshFor | the lifetime where a read named none | CACHE_FRESH_FOR_MS | | scanBatch | keys per round of the scan that clears a namespace | CACHE_SCAN_BATCH | | undeclaredReads | throw or report on a gap in an invalidation | CACHE_UNDECLARED_READS |

freshFor is the one worth thinking about: with no lifetime an entry is permanent until a write stales it, which is right where the invalidation is complete and wrong where a vault reaches something the database never wrote.

undeclaredReads is loud in development and reported in production unless this says otherwise, which is the one place the choice belongs: a boot that refuses is worse than a stale answer in some deployments and better in others.

| It adds | Where | | --- | --- | | server.kiche - the vaults, and the invalidation they drive | FastifyInstance | | a Prisma extension that invalidates after every write | KilnModule.extendDatabase |

A vault

One file in src/cache/, and it exports one thing.

// src/cache/timeline.ts
import { Kiche } from "@kilnjs/kiche";
import type { Fallback } from "@kilnjs/kiche";

export default Kiche.vault("timeline")
  .invalidation({
    Post: ["writes"],
    Comment: ["updates", "deletes"],
    User: ["updates"],
  })
  .methods((cache) => {
    return {
      forUser: async (userId: string, fallback: Fallback<Timeline>) => {
        return await cache.findByKey(`timeline:${userId}`, fallback, {
          freshFor: 30_000,
        });
      },
    };
  });

A handler reaches it by importing the file and calling a method on it. The methods are typed from the builder, which is why the two steps are a chain and not two assignments: a property assignment cannot refine the type a consumer imports, so vault.methods = ... would have left every call site untyped.

kiln/vault-is-the-only-export refuses a named export beside the vault. A second way into a namespace is a way the invalidation rule does not cover.

The rule is the point

invalidation comes before methods and both are required, because a vault nobody can stale is a bug rather than a configuration. {} is how one says it means never, which is a sentence rather than an omission.

What a model's writes may say:

| | | | --- | --- | | writes | every operation that can change a row. What almost every rule wants | | creates, updates, deletes | the obvious subsets | | reads | for a vault holding something derived from a read | | create, updateMany, ... | one Prisma operation exactly |

A group is expanded where it is declared, so a write is a map lookup rather than a membership test on every query. A name that is neither a group nor an operation is refused there too, with the groups listed, because a vault listening for write listens to nothing and whatever it holds never goes stale.

A model the schema does not have is refused at boot for the same reason: a rule naming one can never fire, so whatever it was meant to stale never does. Nothing checked this, and the create-kiln template shipped a vault invalidating on Membership writes in a project with no Membership model. On a fresh clone with nothing generated yet there is no schema to check against, and nothing is refused.

The framework does the clearing

A vault used to declare invalidate as well, and every one of the six across three applications wrote the same line: clear the namespace. There is nothing better to do in the general case, because a write names a row and not the shape of the answer built from it. So that line is the framework's now.

Where a write does say which entries it staled, the rule names the column that carries the id:

.invalidation({
  Session: { on: ["writes"], tag: "id" },
  User: { on: ["writes"], tag: "id" },
  Membership: { on: ["writes"], tag: "user_id" },
})

The prefix is derived rather than written, because the column already says what its ids are ids of:

| the column | the tag | | --- | --- | | id | the model's own row, so the model names it: session:<id> | | user_id | what it points at: user:<id> |

So a Membership write retires user:<the user it named>, which is the entry holding that caller's standing, rather than every caller's. A column that is neither id nor a <thing>_id is refused where it is declared, because there is nothing to derive a prefix from and the tag would name nothing.

Where the row is not that simple, tag takes a function instead, returning the tag or nothing. Either way, nothing readable clears the vault, which is what a bulk write answers with: a count, naming no row. Without any of this, a Session write would cold-start every session in the deployment.

A raw statement is the one write nothing attributes

Invalidation comes from an extension on $allModels. $executeRaw and $queryRaw reach no model, so they cannot appear in invalidation at all and naming them there is refused. Call vault.clear() on the next line.

The rule is checked against the query

invalidation is compared against the models a fallback actually touches, relations included, and a vault that reads a model its rule does not name is refused. A role change that invalidated nothing is how an admin kept admin authority for a week.

The check is keyed by the file's name, and so is the vault's. A vault named anything else is refused for that reason: KilnJS held createSecureCache("kiln-auth") in src/cache/auth.ts, and because the two keys never met, the check on the cache that authenticates every request had never run.

What a method is given

methods receives one handle, scoped to this vault's namespace:

| | | | --- | --- | | findByKey(name, fallback, options) | read through, with a lifetime and tags | | invalidate({ keys, tags }, reason) | retire named entries | | invalidateAll(reason) | retire the namespace |

Every vault also has clear(), for the raw statement case, and kiche, which is where the framework reads what the vault declared. A method called either is refused when the vault is built, because it would shadow one of them.

How long an entry lives

Two ways, and never both at once: giving both is a type error rather than a rule somebody has to know.

cache.findByKey(key, fallback, { freshFor: 15_000 });
cache.findByKey(key, fallback, { validUntil: (s) => s.expires_at.getTime() });

A lifetime declared once in kiche({ freshFor }) stands behind both of them, so a vault that wants the same number everywhere does not repeat it per call.

freshFor is a duration in milliseconds, which is what a dashboard list wants: "hold this for fifteen seconds" used to be written as validUntil: () => Date.now() + FRESH, and that arithmetic was in every call site. validUntil is an instant read off the value, which is what a session wants: its expiry is a column rather than a policy. Neither means permanent, and only an invalidation retires that.

What it answers

Whatever the fallback answers. findByKey used to be typed T | null however the fallback was written, so a call site that could never see null paid a ?? [] for a branch that cannot be taken, and learnt a habit that would swallow a real empty answer somewhere else.

A fallback that can answer nothing still can, and nothing is not cached: a row absent now is a row that may be there on the next request.

Two deployments, one Redis

A vault whose write cannot say which rows it staled clears its whole namespace. That is the honest answer, and it is what a list overview does: a task write names a list, not the organization the list is in, so guessing would be wrong exactly when two organizations were busy at once.

Broad across one deployment is correct. Broad across two sharing a Redis is not, and nothing separated them, because the key prefix was a constant. A task written in staging would cold-start production's cache.

CACHE_SCOPE goes in the prefix, so each deployment clears only its own:

CACHE_SCOPE=staging

Optional, and absent means the keys this package has always written, so introducing it does not cold-start an existing cache.

It was found as a flaky test rather than as an outage, which is the usual way. Four jest workers share one Redis, so a task written by one worker cleared an overview another had just cached: one application's cache suite failed about one full-suite run in three under load and passed every time it ran alone. kiln test now sets this to the worker id, so a suite is isolated without an application configuring anything.

Without it

Leave the module out and core still boots. The vaults in src/cache are never consulted, so a read through one still works and never goes stale, which is why a server that caches anything should declare it.

The Redis connections themselves are core's (@kilnjs/core/redis), because the rate limiter, the login lockout and the graceful drain need them whether or not a cache is installed.

Development

yarn verify   # ts:check, lint, build, exports:check, test

The routing is pure, so its tests reach no Redis and no configuration.