@usehenri/redis 0.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# @usehenri/redis
+
+## 1.2.0
+
+### Minor Changes
+
+- [#419](https://github.com/usehenri/henri/pull/419) [`43a0e1a`](https://github.com/usehenri/henri/commit/43a0e1a6a320baa43298391e1c1e0334d6cd28d5) Thanks [@reel](https://github.com/reel)! - `henri.flags`: feature flags declared in one file, on for everyone, for a named set, for a stable share of them, or for a group the application writes in code.
+  
+  `config/flags.js` is the declaration — `checkout: false` is a whole flag, and the long form adds `description`, `expose` and `group`. `await req.flag('checkout')` and `await henri.flags.enabled('checkout', user)` are the read; `henri flags`, `flags:on`, `flags:off`, `flags:percentage` and `flags:reset` are what an operator has. `flipper` is what this learns from: the gates and the `enable`/`disable` vocabulary are kept, `percentage_of_time` is not (a feature that flickers within one page load is a bug henri would have caused), and neither are the expression gates, the web UI or the metrics.
+  
+  **A name nothing declares is a failure, not a `false`** — the position `req.permit()`, `params`, `answers` and `filters` already take. A typo that answers `false` forever is a feature that silently never ships; a typo that throws is a stack trace in development, in the suite, and on the first request that reaches it. Both messages name the closest declared flag, and the cost is stated out loud in the guide: removing a flag is two deploys.
+  
+  **The percentage is stable and it is hashed carefully.** The bucket is `sha256(flag + actor)`, computed and never stored, so the same person keeps the same answer across processes and restarts and a rollout only ever adds people. The flag name is in the hash so two features at ten percent are not on for the same ten percent, and the identifier — the `externalId`, never the primary key — is hashed **whole**: a uuid v7 is time-ordered, so bucketing on any prefix of one would roll a feature out by signup date rather than at random.
+  
+  **The state is where every process can read it.** `config.shared` when there is a backend, `.henri/flags.json` otherwise, this process's memory under `NODE_ENV=test`, and the boot line says which and says its limit. Reads come from an in-memory snapshot re-read on a timer (`flags.refresh`, ten seconds, which is the whole staleness window), not through `henri.cache` — a cache's answer to a backend that is down is a miss, and a miss here would revert every flag to its default mid-incident. **A store that cannot be read flips nothing**: the snapshot stands and it is reported at most once a minute.
+  
+  `henri flags` boots to runlevel 2 and no further, so a kill switch can be flipped while the database is unreachable. There is **no HTTP surface** in any environment: an application that wants a page writes the controller and puts a policy on it.
+  
+  New configuration key `flags` (`store`, `refresh`, `enabled`), four `HENRI_FLAGS_*` codes, and `@usehenri/redis` gains a key-value write with no expiry, for the state that must outlive a restart. See the new [Feature flags](https://usehenri.io/guides/feature-flags/) guide.
+
+- [#373](https://github.com/usehenri/henri/pull/373) [`2c8a826`](https://github.com/usehenri/henri/commit/2c8a8265262dbf6ea5c3e73e8e7892a230d4d0f0) Thanks [@reel](https://github.com/reel)! - `config.shared`: one backend for the counters that only worked with one process
+  
+  The rate limit, the sign-in lockout and the idempotency keys each keep a
+  number per key, and all three were kept in the process's memory unless the
+  application named a store in three separate configuration keys. Two processes
+  therefore meant two sets of counters: a rate limit that is twice what it says,
+  a lockout an attacker escapes by being routed elsewhere, and an idempotency
+  key that stops being idempotent.
+  
+  `config.shared` is the one place to say where they live instead:
+  
+  ```json
+  {
+    "shared": {
+      "adapter": "redis",
+      "url": "redis://127.0.0.1:6379",
+      "prefix": "lineup:",
+      "onError": "closed"
+    }
+  }
+  ```
+  
+  `@usehenri/redis` is the backend, a package an application installs
+  (`pnpm add @usehenri/redis`), resolved from the application the way a store
+  adapter is; nothing is added to an application that does not name it. It talks
+  to Redis through node-redis and counts the rate limits with `rate-limit-redis`.
+  `rateLimit.store`, `user.lockout.store` and `api.idempotency.store` keep
+  working and still win, key by key.
+  
+  When the backend does not answer, `shared.onError` decides: `closed` (the
+  default) refuses the request with a `503` and a `Retry-After`, `open` serves it
+  uncounted; either is logged, at most once every ten seconds per counter. The
+  idempotency keys are always closed, whatever `onError` says. A backend that is
+  unreachable at boot does not fail the boot: the client keeps reconnecting and
+  `GET /readyz` reports it (`"shared": { "ok": false }`), so the process leaves
+  the load balancer instead of the fleet.
+  
+  The boot says which it is on every application -- `counted in redis (fail
+  closed)` or `counted in this process` -- and warns outright when the
+  environment says this process is one of several (a cluster worker, a numbered
+  pm2 instance, `WEB_CONCURRENCY`, a Heroku dyno past the first) and no shared
+  backend is configured. `henri doctor` reports a shared store that does not
+  answer (`shared.unreachable`) and asks for the adapter package when the
+  configuration names one; `--no-reach` skips the connection.
+  
+  Sessions are not part of this: they already go through the database adapter,
+  which every process shares.
+
+- [#374](https://github.com/usehenri/henri/pull/374) [`0b32fbd`](https://github.com/usehenri/henri/commit/0b32fbde19c95da8fe07fab76933840a4242c71c) Thanks [@reel](https://github.com/reel)! - `henri.cache`: a cache store with `fetch`, on this process's memory or on the backend `config.shared` already names.
+  
+  `henri.cache.fetch(key, [options], fn)` answers from the cache or runs the function and keeps what it returned; `get`, `set`, `delete`, `clear` and `scope(name)` are the store underneath, and `stats()` says what it has been doing. Every entry has a TTL (`config.cache.ttl`, five minutes by default) — there is no way to keep a value forever, by accident or on purpose.
+  
+  **The stampede.** A key that expires under load is missed by every request at once. `fetch` keeps one promise per key while the function runs and hands it to everyone who missed it, so a hundred concurrent misses of one key in one process run the function once. Across processes the bound is the number of processes, deliberately: a cross-process lock needs a lease, and a lease means guessing how long the function may take — guess short and it runs twice anyway, guess long and one crashed process blocks every reader of that key.
+  
+  **Two backends, named once.** Without `config.shared` the cache is this process's memory, bounded twice (`maxEntries`, 1000, and `maxSize`, 32mb) and evicting the least recently used, so it cannot become a leak. With `config.shared` — the block that already says where the rate limit, the sign-in lockout and the idempotency keys are counted — the cache is on that backend, in a key space of its own, with nothing else to configure. `config.cache.store` still names a module of its own for whoever wants the cache somewhere the counters are not.
+  
+  **What a value may be.** JSON, plus `Date` (which comes back a `Date`). A model instance, any other class instance, `undefined`, `NaN`, `Infinity`, a `Map`, a `Set`, a `Buffer`, a `RegExp`, a function, a symbol, a bigint or anything circular is refused with `HENRI_CACHE_VALUE_UNSUPPORTED`, naming where it sat and what it was but never what it held — rather than stored to come back wrong. A value bigger than `maxEntrySize` (256kb) is not stored at all: `set` answers `false` and says so once, and nothing is ever truncated.
+  
+  **A backend that is down is a miss**, whatever `config.shared.onError` says. The counters block because a guard that cannot count is not a guard; a cache holds no truth, so refusing a request over a copy would turn an optimization into an outage. Every fallthrough is logged at most once every ten seconds, like the counters'. Keys reaching a log line are masked by `config.filterParameters`, and values never reach one.
+  
+  **henri invalidates nothing for you**: no model callback, no query cache, no route. `delete` is yours to call, and with the memory backend it reaches one process — which is the reason a deployment running several of them wants `config.shared`.
+  
+  New configuration key `cache` (`ttl`, `maxEntries`, `maxSize`, `maxEntrySize`, `store`, `enabled`; `false` turns the cache off). `@usehenri/redis` gains a raw mode on its key-value store, so the cache's already-encoded entry is not wrapped in JSON a second time, and a `clear(prefix)` that walks its own key space with `SCAN` and `UNLINK` — never `FLUSHDB`. See the new [Caching](https://usehenri.io/guides/caching/) guide.
+
+### Patch Changes
+
+- Updated dependencies [[`792a15a`](https://github.com/usehenri/henri/commit/792a15ade614cf8b920d9197586f9866700d458e), [`1e23664`](https://github.com/usehenri/henri/commit/1e23664829bd1a356de28f404cfb21c9ae211388), [`5b627ad`](https://github.com/usehenri/henri/commit/5b627adfa37e9f16bc75af96cc8ff5308a91f688), [`4dff51e`](https://github.com/usehenri/henri/commit/4dff51edc050e29398c793a5aedb48776b7b7119), [`60dbf33`](https://github.com/usehenri/henri/commit/60dbf33c2a4f14e328a0df1cb44be061e15431e5), [`1b316c6`](https://github.com/usehenri/henri/commit/1b316c6f3c5d5eb5752c70b534092d1052956cc6), [`d074e8b`](https://github.com/usehenri/henri/commit/d074e8b482582e25f80d8a14b4735e69a2b7821e), [`7fd13f6`](https://github.com/usehenri/henri/commit/7fd13f631b75f7aa152b73046b50c6902ae3ca93), [`b559fb7`](https://github.com/usehenri/henri/commit/b559fb72b391eeb21a3f6a0cda1515e01ecbfafc), [`1c0dfe8`](https://github.com/usehenri/henri/commit/1c0dfe84a98eff2122512256c4f42ec7ccde4212), [`93060a8`](https://github.com/usehenri/henri/commit/93060a86df795dbbd99bf1895beb0cf14c4b86de), [`e031900`](https://github.com/usehenri/henri/commit/e031900082f28aec72af4cda9cd959f932e2ebc7), [`9173000`](https://github.com/usehenri/henri/commit/91730005efa88f073bfaaf67078c3ec0e137b459), [`62fac46`](https://github.com/usehenri/henri/commit/62fac46fd6cae5581979b73daf99700fd246e0ea), [`b7f33e2`](https://github.com/usehenri/henri/commit/b7f33e28a5e4844391befd75d08e42c4cf6212ed), [`3d6f3fc`](https://github.com/usehenri/henri/commit/3d6f3fc048d05db41be86069608d342e437408cb), [`b278119`](https://github.com/usehenri/henri/commit/b2781190de436eb5838e866446c9a0c8210bb6ca), [`b161e1b`](https://github.com/usehenri/henri/commit/b161e1b8fad94af2d2afc351dc1bc07dabbb1379), [`7cb0b04`](https://github.com/usehenri/henri/commit/7cb0b04b29b61dedaa82fcd1972646fb3765acfc), [`1616e34`](https://github.com/usehenri/henri/commit/1616e343a612be2bffffcfa5b23bfa8ad191bbe3), [`c8f5367`](https://github.com/usehenri/henri/commit/c8f53678b33341d086b467f801e959314afc7860), [`bcf4ce2`](https://github.com/usehenri/henri/commit/bcf4ce22bcd294844504164fac1fa4aef1ffec41), [`ab5a8e4`](https://github.com/usehenri/henri/commit/ab5a8e4a88c80cca070a2b8ad398c80babdaff11), [`43d267f`](https://github.com/usehenri/henri/commit/43d267f0f9d192b2c01e89c3925b7daf5000041b), [`9f868f3`](https://github.com/usehenri/henri/commit/9f868f3d9162fa218e34304110210e6949f97d5c), [`d88bf7f`](https://github.com/usehenri/henri/commit/d88bf7fe038a6b58e7bed02ff4c90755f6c0e65e), [`49398a6`](https://github.com/usehenri/henri/commit/49398a6308f0760f01c6ff2ec98aaa35f484474d), [`89dda62`](https://github.com/usehenri/henri/commit/89dda62da456a0a55600e79cfb65ce89f11258e2), [`62fac46`](https://github.com/usehenri/henri/commit/62fac46fd6cae5581979b73daf99700fd246e0ea), [`a93d6cc`](https://github.com/usehenri/henri/commit/a93d6cc39b33b261089e91f3e757b54fefc9fe15), [`d9f3be4`](https://github.com/usehenri/henri/commit/d9f3be49c5929d929a220220bf6e72fdcb135595), [`c44f025`](https://github.com/usehenri/henri/commit/c44f025acec3d5bbbb57e2310d02184a1053a10d), [`67cfb20`](https://github.com/usehenri/henri/commit/67cfb200ea0e0b31bacf2af183db6467b0fa011d), [`e661f98`](https://github.com/usehenri/henri/commit/e661f98fe8f8acce15aa10ce2dc320c5a2cb006f), [`43a0e1a`](https://github.com/usehenri/henri/commit/43a0e1a6a320baa43298391e1c1e0334d6cd28d5), [`cee57b9`](https://github.com/usehenri/henri/commit/cee57b9d3521a4a70c715222eae1f18ff4a6c128), [`61bf75c`](https://github.com/usehenri/henri/commit/61bf75cbaccda1aecff34408a175b2d85447d7a8), [`2c8a826`](https://github.com/usehenri/henri/commit/2c8a8265262dbf6ea5c3e73e8e7892a230d4d0f0), [`46d5dbc`](https://github.com/usehenri/henri/commit/46d5dbcc983c03e96ae5a87d7288c5d8a5adbc24), [`ba97ea9`](https://github.com/usehenri/henri/commit/ba97ea968f0b34cd67b7a3e803ecd34543b8aaaf), [`5ccd537`](https://github.com/usehenri/henri/commit/5ccd537b3621b54d11e7f24ccca39643ae7d5cf7), [`d88bf7f`](https://github.com/usehenri/henri/commit/d88bf7fe038a6b58e7bed02ff4c90755f6c0e65e), [`9895cbf`](https://github.com/usehenri/henri/commit/9895cbf4be85b476e341a5be915e3049e5a027de), [`61bf75c`](https://github.com/usehenri/henri/commit/61bf75cbaccda1aecff34408a175b2d85447d7a8), [`5a150d5`](https://github.com/usehenri/henri/commit/5a150d576208571c32b9cd12827d035e31ed4313), [`3c1c5b8`](https://github.com/usehenri/henri/commit/3c1c5b83ea135b000ddd6ffbfd05457b000f2f7c), [`2625067`](https://github.com/usehenri/henri/commit/26250673d91ab70ad024739d02b647754f75267d), [`aa3f90b`](https://github.com/usehenri/henri/commit/aa3f90bd6f42bb05431c33f3e4bf2202cb6bb7c6), [`a1c6769`](https://github.com/usehenri/henri/commit/a1c6769099e3dc28b22b5338a2a57b13bdf69f7a), [`0a8bb41`](https://github.com/usehenri/henri/commit/0a8bb415d352cd75b12d07e591c8ec7c16774a99), [`ec1c8c4`](https://github.com/usehenri/henri/commit/ec1c8c419f4d9063a7617472b2970fdb8a929fa1), [`dd2731d`](https://github.com/usehenri/henri/commit/dd2731d6a20fd96aa1be1aeb5e6ec0155001326b), [`ab52e18`](https://github.com/usehenri/henri/commit/ab52e187c420dfe381f03ed51c5c141fda525acb), [`b7b56e1`](https://github.com/usehenri/henri/commit/b7b56e190ae774abc0096fe2aebaf91f823115af), [`b7038ce`](https://github.com/usehenri/henri/commit/b7038ceaa430f4a0b9eaf7e983fc2844421bf636), [`1ea0f85`](https://github.com/usehenri/henri/commit/1ea0f85066b86fba31f58937cc10abb6359e6a26), [`762062a`](https://github.com/usehenri/henri/commit/762062aadc450d49b1a2d15524f9d579ab4f60e7), [`01a561a`](https://github.com/usehenri/henri/commit/01a561aa58650ec15df1c2659795a5e4c5bbfd53), [`bd1b630`](https://github.com/usehenri/henri/commit/bd1b63083b3817b8c47b8a187de76027458a1b32), [`27b5513`](https://github.com/usehenri/henri/commit/27b5513d1cae8aba734fe27da0ace2a82423e2f4), [`e31a3f7`](https://github.com/usehenri/henri/commit/e31a3f73e7e8facf3cedf7460f115e57995f32c3), [`2689779`](https://github.com/usehenri/henri/commit/26897798b840fd28a4bc091c050a83457b36905d), [`72cd1d3`](https://github.com/usehenri/henri/commit/72cd1d35ffb99311bbca815c1f6ab41ee3682f64), [`a2e1ec2`](https://github.com/usehenri/henri/commit/a2e1ec29df52462f12ebaae9bfbc1ad4f427b27f), [`afead74`](https://github.com/usehenri/henri/commit/afead7489498ed42e1893a25123ea772cac2ca09), [`a4ecba5`](https://github.com/usehenri/henri/commit/a4ecba50c663f4d5c741adbb6cd9bc0eefe0e5cc), [`baec3fd`](https://github.com/usehenri/henri/commit/baec3fd22be92bf8ffbaeb251b0b6c2771f8347a), [`1103628`](https://github.com/usehenri/henri/commit/110362808f8ec6d73a75ff7fc89a77f3e943d773), [`e865d94`](https://github.com/usehenri/henri/commit/e865d945d65419ac676f5a2fe3ba3b6114a1e53d), [`4274567`](https://github.com/usehenri/henri/commit/4274567e20a980657f07df9ec7db25296c7d55f5), [`aea429c`](https://github.com/usehenri/henri/commit/aea429ca99338a62370ab3e3d94bdc6b8c227601), [`8a8e3b3`](https://github.com/usehenri/henri/commit/8a8e3b33d7967b81f66633aa25c3075318f01d60), [`18715f9`](https://github.com/usehenri/henri/commit/18715f90ea8958dc57da1bb029b8209c36b84cc6), [`0d2ebc3`](https://github.com/usehenri/henri/commit/0d2ebc344bfcd80533ef900638083e4c105407bb), [`49398a6`](https://github.com/usehenri/henri/commit/49398a6308f0760f01c6ff2ec98aaa35f484474d), [`ec64e44`](https://github.com/usehenri/henri/commit/ec64e44e7b79a02da5fc587a72a9a6c900836982), [`831aa5c`](https://github.com/usehenri/henri/commit/831aa5c011f3432630c68b8d26755d2582f82f74), [`16824e8`](https://github.com/usehenri/henri/commit/16824e8fe9ccc6a04dab5d9b2481c29ff4f6b64b), [`fda9366`](https://github.com/usehenri/henri/commit/fda9366e9ed2b072764a995c5aa60205ca7a4725), [`1a86acb`](https://github.com/usehenri/henri/commit/1a86acbf15e4a43e5fb81277bb22e101c06e77a4), [`808d824`](https://github.com/usehenri/henri/commit/808d82471d59e64ccc735f617bab293eb572c46b), [`0b32fbd`](https://github.com/usehenri/henri/commit/0b32fbde19c95da8fe07fab76933840a4242c71c), [`c0c16e8`](https://github.com/usehenri/henri/commit/c0c16e873ba440aee9832160553cbb12ab81bd2c), [`41470bf`](https://github.com/usehenri/henri/commit/41470bf378d83ca3d35d00e8c31796fea5eb15e0), [`8e44e7e`](https://github.com/usehenri/henri/commit/8e44e7e882dd8741b3ac632651b453389d76bf2c), [`de1c1e0`](https://github.com/usehenri/henri/commit/de1c1e02ed83d13dcfeb8e44012f309eb663f03e), [`4b4677d`](https://github.com/usehenri/henri/commit/4b4677d4a09d39fe50b1fa4af577600342578daf)]:
+  - @usehenri/core@1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016-present, Félix-Antoine Paradis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
+<!-- generated by scripts/prepublish.js -->
+
 # @usehenri/redis
 
-Placeholder release. Install a real version: see https://usehenri.io.
+Henri shared store: the rate limit, the sign-in lockout and the idempotency keys counted in Redis instead of one process.
+
+Part of [henri](https://usehenri.io), the Rails-like React framework for
+Node.js: [documentation](https://usehenri.io),
+[source and issues](https://github.com/usehenri/henri),
+[changelog](https://github.com/usehenri/henri/blob/master/packages/redis/CHANGELOG.md).

package/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@usehenri/redis`: the shared store `config.shared` names.
+ *
+ * ```json
+ * { "shared": { "adapter": "redis", "url": "redis://127.0.0.1:6379" } }
+ * ```
+ *
+ * Core resolves this package from the application (`utils.resolveFrom`) and
+ * constructs the default export with the normalized block, the way it loads
+ * a database adapter. See `packages/core/src/base/shared.js`.
+ */
+module.exports = require('./src/backend');

package/package.json

@@ -1,15 +1,50 @@
 {
-  "description": "Placeholder creating @usehenri/redis on npm; the first real version is published by the henri release workflow",
-  "homepage": "https://usehenri.io",
-  "license": "MIT",
   "name": "@usehenri/redis",
-  "publishConfig": {
-    "access": "public"
-  },
+  "version": "1.2.0",
+  "description": "henri shared store: the rate limit, the sign-in lockout and the idempotency keys counted in Redis instead of one process",
+  "license": "MIT",
+  "author": "Felix-Antoine Paradis",
+  "homepage": "https://usehenri.io",
   "repository": {
-    "directory": "packages/redis",
     "type": "git",
-    "url": "git+https://github.com/usehenri/henri.git"
+    "url": "git+https://github.com/usehenri/henri.git",
+    "directory": "packages/redis"
+  },
+  "bugs": {
+    "url": "https://github.com/usehenri/henri/issues"
+  },
+  "keywords": [
+    "henri",
+    "redis",
+    "rate-limit",
+    "idempotency",
+    "lockout",
+    "shared"
+  ],
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "src",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "debug": "^4.4.3",
+    "rate-limit-redis": "^6.0.1",
+    "redis": "^6.2.1"
+  },
+  "peerDependencies": {
+    "@usehenri/core": "^1.2.0"
   },
-  "version": "0.0.0"
-}
+  "devDependencies": {
+    "@usehenri/core": "^1.2.0",
+    "express": "^5.2.1",
+    "supertest": "^7.2.2"
+  }
+}

package/src/backend.js

@@ -0,0 +1,335 @@
+const { RedisStore } = require('rate-limit-redis');
+const debug = require('debug')('henri:redis');
+const { createClient } = require('redis');
+
+const KeyValueStore = require('./kv');
+
+/**
+ * The Redis backend of `config.shared`.
+ *
+ * henri's rate limit, sign-in lockout and idempotency keys are numbers per
+ * key, and all three were per process. `config.shared` names where they are
+ * counted instead; this is what that name resolves to:
+ *
+ * ```json
+ * {
+ *   "shared": {
+ *     "adapter": "redis",
+ *     "url": "redis://127.0.0.1:6379",
+ *     "prefix": "lineup:"
+ *   }
+ * }
+ * ```
+ *
+ * Core loads it from the application with `utils.resolveFrom`, the way it
+ * loads a store adapter, so an application that does not name it never
+ * installs it. Nothing here is a henri module: there is no runlevel to sit
+ * at, because the server needs the counters at runlevel 2 and the sign-in
+ * lockout at 4.
+ *
+ * ## Why node-redis
+ *
+ * `redis` (node-redis), not `ioredis`. ioredis' own README now sends new
+ * projects to node-redis and calls its own maintenance best-effort, and
+ * node-redis is the client Redis develops. Two of its properties are the
+ * reason it fits here rather than merely being acceptable:
+ *
+ * - `connect()` is explicit, so a deployment learns at boot that the server
+ *   is unreachable instead of at the first request that needed a counter;
+ * - `disableOfflineQueue` turns a command sent while disconnected into an
+ *   immediate rejection rather than a queued promise. A fail-closed guard
+ *   has to answer 503 in milliseconds; a queued command would hang the
+ *   request until the reconnect, which is the worst of both answers.
+ *
+ * `rate-limit-redis` (the store express-rate-limit's own author maintains)
+ * takes `sendCommand`, so the limiter behaves exactly as it does in every
+ * other express-rate-limit deployment.
+ *
+ * ## Connecting
+ *
+ * The reconnect never gives up and never storms: the delay doubles from
+ * 100ms to ten seconds. `start()` waits `connectTimeout` for the first
+ * connection and then stops waiting, without failing -- the client keeps
+ * reconnecting, `GET /readyz` reports it, and requests meanwhile follow
+ * `config.shared.onError`.
+ */
+
+/** How long `start()` waits for the first connection (ms) */
+const CONNECT_TIMEOUT = 5000;
+
+/** The longest the reconnect ever waits between attempts (ms) */
+const MAX_BACKOFF = 10000;
+
+/**
+ * How long to wait before the next connection attempt: 100ms doubling to
+ * ten seconds, so a server that is down for an hour costs a handful of
+ * connections a minute instead of a storm
+ *
+ * @param {number} retries how many attempts have failed
+ * @returns {number} the delay (ms)
+ */
+const backoff = (retries) =>
+  Math.min(100 * 2 ** Math.min(Number(retries) || 0, 7), MAX_BACKOFF);
+
+/**
+ * The url with its password replaced, so it can be printed
+ *
+ * @param {string} url a connection string
+ * @returns {string} the url, without the password
+ */
+function redact(url) {
+  return String(url).replace(/^(\w+:\/\/[^:/@]*:)[^@/]*@/u, '$1[FILTERED]@');
+}
+
+/**
+ * A promise that rejects after a delay
+ *
+ * @param {Promise} promise the promise to bound
+ * @param {number} ms how long it may take
+ * @param {string} message what to say when it does not
+ * @returns {Promise} the promise, bounded
+ */
+function withTimeout(promise, ms, message) {
+  let timer = null;
+
+  return Promise.race([
+    promise,
+    new Promise((resolve, reject) => {
+      timer = setTimeout(() => reject(new Error(message)), ms);
+      timer.unref();
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * The keys of `config.shared` henri owns; everything else is a node-redis
+ * option and reaches `createClient()`
+ */
+const OWN = ['adapter', 'connectTimeout', 'enabled', 'onError', 'prefix'];
+
+/**
+ * The Redis shared store
+ *
+ * @class RedisBackend
+ */
+class RedisBackend {
+  /**
+   * Creates an instance of RedisBackend.
+   *
+   * @param {object} [settings={}] the normalized `config.shared`
+   * @param {?object} [henri=null] the henri instance, when there is one
+   *   (`henri doctor` builds one without booting)
+   * @memberof RedisBackend
+   */
+  constructor(settings = {}, henri = null) {
+    const options = {};
+
+    for (const key of Object.keys(settings)) {
+      if (!OWN.includes(key)) {
+        options[key] = settings[key];
+      }
+    }
+
+    this.name = 'redis';
+    this.henri = henri;
+    this.prefix = settings.prefix || 'henri:';
+    this.connectTimeout =
+      Number(settings.connectTimeout) > 0
+        ? Number(settings.connectTimeout)
+        : CONNECT_TIMEOUT;
+    this.url = options.url || 'redis://127.0.0.1:6379';
+    this.options = Object.assign({ url: this.url }, options, {
+      // A command sent while the connection is down fails now instead of
+      // waiting for a reconnect that may be minutes away
+      disableOfflineQueue: true,
+      socket: Object.assign(
+        { connectTimeout: this.connectTimeout, reconnectStrategy: backoff },
+        options.socket
+      ),
+    });
+
+    this.client = null;
+    this.connecting = null;
+    this.lastError = null;
+    this.sendCommand = this.sendCommand.bind(this);
+    this.connected = this.connected.bind(this);
+  }
+
+  /**
+   * What this is talking to, with the password taken out
+   *
+   * @returns {string} the redacted url
+   * @memberof RedisBackend
+   */
+  describe() {
+    return redact(this.url);
+  }
+
+  /**
+   * Opens the connection, at most once at a time.
+   *
+   * It resolves when the client is ready and rejects when the first attempt
+   * has not landed within `connectTimeout` -- which does not stop the
+   * client: it keeps reconnecting on its own, and the next call finds it
+   * ready.
+   *
+   * @returns {Promise<object>} the client
+   * @throws when the first connection does not land in time
+   * @memberof RedisBackend
+   */
+  async start() {
+    if (this.client && this.client.isReady) {
+      return this.client;
+    }
+
+    if (!this.client) {
+      this.client = createClient(this.options);
+      // An unhandled `error` event throws, and there is one on every failed
+      // reconnect. The log is not the place for them: what a request does
+      // about it is core's business (`config.shared.onError`), and the boot
+      // line and `GET /readyz` already say whether the server is up.
+      this.client.on('error', (error) => {
+        this.lastError = error;
+        debug('client error: %s', error.message);
+      });
+    }
+
+    if (!this.connecting) {
+      this.connecting = Promise.resolve()
+        .then(() => (this.client.isOpen ? null : this.client.connect()))
+        .finally(() => {
+          this.connecting = null;
+        });
+    }
+
+    await withTimeout(
+      this.connecting,
+      this.connectTimeout,
+      `redis did not answer within ${this.connectTimeout}ms${
+        this.lastError ? ` (${this.lastError.message})` : ''
+      }`
+    );
+
+    return this.client;
+  }
+
+  /**
+   * The connected client, connecting when it is not.
+   *
+   * Every store call goes through this: a client that is up answers with no
+   * added work, and one that is not fails now rather than queueing.
+   *
+   * @returns {Promise<object>} the client
+   * @throws when it is not connected
+   * @memberof RedisBackend
+   */
+  async connected() {
+    if (this.client && this.client.isReady) {
+      return this.client;
+    }
+
+    if (this.client && this.client.isOpen) {
+      // Open but not ready: reconnecting. Fail now; the guard decides.
+      throw new Error(
+        `redis is not connected${this.lastError ? ` (${this.lastError.message})` : ''}`
+      );
+    }
+
+    return this.start();
+  }
+
+  /**
+   * Sends a raw command, which is all `rate-limit-redis` needs
+   *
+   * @param {...string} args the command and its arguments
+   * @returns {Promise<*>} what Redis answered
+   * @memberof RedisBackend
+   */
+  async sendCommand(...args) {
+    const client = await this.connected();
+
+    return client.sendCommand(args.map(String));
+  }
+
+  /**
+   * Whether the server answers
+   *
+   * @returns {Promise<boolean>} true when it did
+   * @throws when it did not
+   * @memberof RedisBackend
+   */
+  async ping() {
+    const client = await this.connected();
+
+    await withTimeout(
+      client.ping(),
+      this.connectTimeout,
+      `redis did not answer PING within ${this.connectTimeout}ms`
+    );
+
+    return true;
+  }
+
+  /**
+   * An express-rate-limit store, one key space per limiter
+   *
+   * @param {string} feature the limiter name (`global`, `auth`, `lockout`)
+   * @returns {object} the store
+   * @memberof RedisBackend
+   */
+  rateLimitStore(feature) {
+    return new RedisStore({
+      prefix: `${this.prefix}rl:${feature}:`,
+      sendCommand: this.sendCommand,
+    });
+  }
+
+  /**
+   * A `{ get, set, add, delete, clear }` store, one key space per feature
+   *
+   * @param {string} feature what the keys are for (`idempotency`, `cache`)
+   * @param {object} [options={}] `raw` stores the string it is handed as it
+   *   is, for a caller that has serialized already (the cache)
+   * @returns {KeyValueStore} the store
+   * @memberof RedisBackend
+   */
+  keyValueStore(feature, options = {}) {
+    return new KeyValueStore({
+      client: this.connected,
+      prefix: `${this.prefix}kv:${feature}:`,
+      raw: options.raw === true,
+    });
+  }
+
+  /**
+   * Closes the connection
+   *
+   * @returns {Promise<boolean>} done
+   * @memberof RedisBackend
+   */
+  async stop() {
+    const { client } = this;
+
+    this.client = null;
+    this.connecting = null;
+
+    if (!client) {
+      return true;
+    }
+
+    try {
+      await withTimeout(client.close(), 1000, 'redis did not close in time');
+    } catch (error) {
+      debug('closing: %s', error.message);
+      client.destroy();
+    }
+
+    return true;
+  }
+}
+
+module.exports = RedisBackend;
+module.exports.CONNECT_TIMEOUT = CONNECT_TIMEOUT;
+module.exports.MAX_BACKOFF = MAX_BACKOFF;
+module.exports.backoff = backoff;
+module.exports.redact = redact;

package/src/kv.js

@@ -0,0 +1,200 @@
+const debug = require('debug')('henri:redis');
+
+/** How many keys a `clear()` asks Redis for per round trip */
+const SCAN_COUNT = 250;
+
+/**
+ * The `{ get, set, add, delete }` store the idempotency keys use, on Redis.
+ *
+ * Values are JSON, the expiry is Redis' own (`PX`), and `add()` is one
+ * `SET ... NX PX` -- an atomic claim, which is what makes two processes
+ * racing on the same `Idempotency-Key` end with one execution and one 409
+ * rather than two executions.
+ *
+ * `raw` turns the JSON off, for a caller that has already serialized: the
+ * cache hands over the string it encoded and measured, and encoding it a
+ * second time would only escape every quote in it.
+ *
+ * Nothing here catches: a command that fails rejects, and `base/shared.js`
+ * in core decides what that means (for these keys, always a 503).
+ *
+ * @class KeyValueStore
+ */
+class KeyValueStore {
+  /**
+   * Creates an instance of KeyValueStore.
+   *
+   * @param {object} options options
+   * @param {function(): Promise<object>} options.client resolves the connected client
+   * @param {string} options.prefix what every key is prefixed with
+   * @param {boolean} [options.raw=false] store the string as it arrives
+   * @memberof KeyValueStore
+   */
+  constructor({ client, prefix, raw = false }) {
+    this.client = client;
+    this.prefix = prefix;
+    this.raw = Boolean(raw);
+  }
+
+  /**
+   * The Redis key of an entry
+   *
+   * @param {string} key the key the caller used
+   * @returns {string} the prefixed key
+   * @memberof KeyValueStore
+   */
+  key(key) {
+    return `${this.prefix}${key}`;
+  }
+
+  /**
+   * Reads an entry
+   *
+   * @param {string} key the key
+   * @returns {Promise<*>} the value, or undefined when there is none
+   * @memberof KeyValueStore
+   */
+  async get(key) {
+    const client = await this.client();
+    const raw = await client.get(this.key(key));
+
+    if (raw === null || typeof raw === 'undefined') {
+      return undefined;
+    }
+
+    if (this.raw) {
+      return raw;
+    }
+
+    try {
+      return JSON.parse(raw);
+    } catch (error) {
+      // Something else wrote this key: forget it rather than fail every
+      // retry of a request that can never replay
+      debug('unreadable entry at %s: %s', key, error.message);
+      await client.del(this.key(key));
+
+      return undefined;
+    }
+  }
+
+  /**
+   * What is written down for a value: JSON, or the string itself in `raw`
+   *
+   * @param {*} value what the caller is storing
+   * @returns {string} what Redis is handed
+   * @memberof KeyValueStore
+   */
+  payload(value) {
+    return this.raw ? String(value) : JSON.stringify(value);
+  }
+
+  /**
+   * How long an entry lives, as Redis takes it, or nothing at all.
+   *
+   * A ttl is what every counter here has, but not everything on this
+   * backend is a counter: `henri.flags` keeps the state of a feature
+   * switch, and a switch that turned itself back on after a fortnight
+   * would be the worst failure that module could have. So a call that
+   * names no expiry gets none, rather than a very long one that is a bug
+   * with a date on it.
+   *
+   * @param {*} ttl how long it lives (ms), or nothing
+   * @returns {?object} the options for `SET`, or null for no expiry
+   * @memberof KeyValueStore
+   */
+  expiry(ttl) {
+    const found = Number(ttl);
+
+    return Number.isFinite(found) && found > 0
+      ? { PX: Math.max(1, Math.round(found)) }
+      : null;
+  }
+
+  /**
+   * Writes an entry, replacing whatever was there
+   *
+   * @param {string} key the key
+   * @param {*} value anything JSON-serializable (a string in `raw`)
+   * @param {number} [ttl] how long it lives (ms); forever without one
+   * @returns {Promise<void>} done
+   * @memberof KeyValueStore
+   */
+  async set(key, value, ttl) {
+    const client = await this.client();
+    const expiry = this.expiry(ttl);
+
+    await client.set(this.key(key), this.payload(value), expiry || undefined);
+  }
+
+  /**
+   * Writes an entry unless the key is taken. One round trip, atomic across
+   * every process talking to this server.
+   *
+   * @param {string} key the key
+   * @param {*} value anything JSON-serializable
+   * @param {number} [ttl] how long it lives (ms); forever without one
+   * @returns {Promise<boolean>} true when this call wrote it
+   * @memberof KeyValueStore
+   */
+  async add(key, value, ttl) {
+    const client = await this.client();
+    const answer = await client.set(this.key(key), this.payload(value), {
+      NX: true,
+      ...this.expiry(ttl),
+    });
+
+    return answer !== null;
+  }
+
+  /**
+   * Removes an entry
+   *
+   * @param {string} key the key
+   * @returns {Promise<void>} done
+   * @memberof KeyValueStore
+   */
+  async delete(key) {
+    const client = await this.client();
+
+    await client.del(this.key(key));
+  }
+
+  /**
+   * Removes every key of this store, or of a prefix inside it.
+   *
+   * `SCAN` and `UNLINK`, never `KEYS` and never `FLUSHDB`: the server may
+   * be holding somebody else's data and this only ever touches the store's
+   * own key space. It walks the whole keyspace to do it, so it belongs in a
+   * teardown or a console rather than in a request.
+   *
+   * @param {string} [prefix=''] a prefix inside the store (all of it when empty)
+   * @returns {Promise<number>} how many keys were removed
+   * @memberof KeyValueStore
+   */
+  async clear(prefix = '') {
+    const client = await this.client();
+    const match = `${this.key(prefix)}*`;
+    let cursor = '0';
+    let removed = 0;
+
+    do {
+      const page = await client.scan(cursor, {
+        COUNT: SCAN_COUNT,
+        MATCH: match,
+      });
+
+      cursor = String(page.cursor);
+
+      if (page.keys.length > 0) {
+        removed += await client.unlink(page.keys);
+      }
+    } while (cursor !== '0');
+
+    debug('cleared %d keys matching %s', removed, match);
+
+    return removed;
+  }
+}
+
+module.exports = KeyValueStore;