Skip to content

Commit f34bb11

Browse files
BrocksiNetchr-hertel
authored andcommitted
[Docs] Add the preparation phase to the requestState key rotation
A rolling deployment that moves straight to `[$new, $old]` signs states its peers still on `[$old]` refuse. The builder docblock now names the `[$current, $new]` step, and the retirement TTL starts when the last instance stops signing with the old key.
1 parent 24360c3 commit f34bb11

2 files changed

Lines changed: 7 additions & 3 deletions

File tree

‎docs/handlers/input-required.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,7 +158,8 @@ To rotate without failing the calls in flight:
158158
A single-process deployment can skip this step.
159159
2. Move the new key to the front, `[$new, $current]`. States are signed with the new key from
160160
now on, and the ones the old key signed still verify.
161-
3. After one TTL, every state the old key signed has expired. Remove it, `[$new]`.
161+
3. Wait one TTL after the **last** process switched to `[$new, $current]`: only then has every
162+
state the old key signed expired. Remove it, `[$new]`.
162163

163164
Each key needs at least 32 bytes.
164165

‎src/Server/Builder.php‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -383,8 +383,11 @@ public function setCachePolicy(CachePolicy $policy): self
383383
* per-process random value only works for a single-process deployment.
384384
*
385385
* A list of keys is a key ring: the first key signs, every key verifies.
386-
* To rotate, put the new key first and keep the old one behind it until
387-
* the states it signed have expired, one TTL later.
386+
* To rotate across several instances, first add the new key behind the
387+
* current one everywhere, `[$current, $new]`, so every instance accepts it
388+
* before any signs with it. Then move it to the front, `[$new, $current]`,
389+
* and remove the old key one TTL after the last instance stopped signing
390+
* with it. See docs/handlers/input-required.md, "Rotating the key".
388391
*
389392
* A binder ties every state the modern era mints to the request it was
390393
* minted for, e.g. {@see Stateless\OriginatingRequestBinder} to the

0 commit comments

Comments
 (0)