refresh_machines 0.7.3-x86_64-darwin

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: ced646c153d46447d261b4f8844540ce5d163f8706ab237a341fed2ee439c491
4
+ data.tar.gz: 664e77981f08f08d76732d01ffd769870995fd580d5c939b9b4565e2ac101519
5
+ SHA512:
6
+ metadata.gz: 6482d2b6b44a3d38b7022dfd7a0b0934d4c692c5b690c4d21a7a2682daf162966cb6b93839daedf3b95f1ff4d72c292f9f5ab04b2406bffa3d6d948a695e1dcb
7
+ data.tar.gz: e1d0c1b84d0f434566f2b9919704106188967e8f823c1b21722a87b5af53abb36553888945c74f6ac984cf52bf61f7114cae8d4387cebf43a25927752f606687
data/CHANGELOG.md ADDED
@@ -0,0 +1,109 @@
1
+ # Changelog
2
+
3
+ ## [0.7.3](https://github.com/seuros/refresh_machines/compare/refresh_machines/v0.7.2...refresh_machines/v0.7.3) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * accept every instant the gem returns ([9420a3d](https://github.com/seuros/refresh_machines/commit/9420a3d73340ad8d7d4299325ac616c91c6fd21c))
9
+
10
+ ## [0.7.2](https://github.com/seuros/refresh_machines/compare/refresh_machines/v0.7.1...refresh_machines/v0.7.2) (2026-11-16)
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * fix wrapped classes at load so building a value runs no Ruby ([d8531d6](https://github.com/seuros/refresh_machines/commit/d8531d6f7180c96632fe8f3fe19b914e840371d0))
16
+
17
+ ## [0.7.1](https://github.com/seuros/refresh_machines/compare/refresh_machines/v0.7.0...refresh_machines/v0.7.1) (2026-11-16)
18
+
19
+
20
+ ### Bug Fixes
21
+
22
+ * refresher core drops slot indexing for slot references ([f0ebbce](https://github.com/seuros/refresh_machines/commit/f0ebbce39e8414127b8a9ee3718397046ed63b60))
23
+
24
+ ## [0.7.0](https://github.com/seuros/refresh_machines/compare/refresh_machines/v0.6.1...refresh_machines/v0.7.0) (2026-11-14)
25
+
26
+
27
+ ### ⚠ BREAKING CHANGES
28
+
29
+ * refresh revalidation reads through symbol_or_fields
30
+
31
+ ### Features
32
+
33
+ * refresh revalidation reads through symbol_or_fields ([5ea9be7](https://github.com/seuros/refresh_machines/commit/5ea9be7d8a5b652e4a1ba32fddfdc9529f643b91))
34
+
35
+ ## [0.6.1](https://github.com/seuros/refresh_machines/compare/refresh_machines/v0.6.0...refresh_machines/v0.6.1) (2026-11-14)
36
+
37
+
38
+ ### Bug Fixes
39
+
40
+ * **deps:** require matryona-machines >= 0.3 and read revalidation with which ([92860cb](https://github.com/seuros/refresh_machines/commit/92860cb8bf82a4159e45c4a0301590c6e185120d))
41
+
42
+ ## [0.6.0](https://github.com/seuros/refresh_machines/compare/refresh_machines/v0.5.0...refresh_machines/v0.6.0) (2026-11-14)
43
+
44
+
45
+ ### ⚠ BREAKING CHANGES
46
+
47
+ * adopt matryona-machines 0.2: hooks name their field, instant for answered ages, symbols! tables, exact Policy fields
48
+
49
+ ### Features
50
+
51
+ * adopt matryona-machines 0.2: hooks name their field, instant for answered ages, symbols! tables, exact Policy fields ([c0d3932](https://github.com/seuros/refresh_machines/commit/c0d393265f5f0b0306cc82a8ea31f125346cc776))
52
+
53
+ ## [0.5.0](https://github.com/seuros/refresh_machines/compare/refresh_machines/v0.4.0...refresh_machines/v0.5.0) (2026-11-14)
54
+
55
+
56
+ ### ⚠ BREAKING CHANGES
57
+
58
+ * seal values, native Policy and Stale checks by exact class, clone-then-keep decide/sweep/poll/drain
59
+
60
+ ### Features
61
+
62
+ * seal values, native Policy and Stale checks by exact class, clone-then-keep decide/sweep/poll/drain ([5a6b1f8](https://github.com/seuros/refresh_machines/commit/5a6b1f8ac6907696939d2ad443836d8336f03365))
63
+
64
+ ## [0.4.0](https://github.com/seuros/refresh_machines/compare/refresh_machines/v0.3.0...refresh_machines/v0.4.0) (2026-11-13)
65
+
66
+
67
+ ### ⚠ BREAKING CHANGES
68
+
69
+ * leases, waiter ids and flight ids of a refresher share one sequence, so a handle rebuilt as the wrong kind names nothing. Requires coalesce-machines >= 0.6. Raw lease numbers change; capacity is checked before the sequence.
70
+
71
+ ### Features
72
+
73
+ * scope ids through periscope-machines and draw leases from the coalescer's sequence; add resumed and issued ([9a9537b](https://github.com/seuros/refresh_machines/commit/9a9537beef8a10e1be244167f4713698dfaa3f1a))
74
+
75
+ ## [0.3.0](https://github.com/seuros/refresh_machines/compare/refresh_machines/v0.2.0...refresh_machines/v0.3.0) (2026-11-13)
76
+
77
+
78
+ ### ⚠ BREAKING CHANGES
79
+
80
+ * see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats only when provable, Duration time, Ruby mirrors the core. No compatibility aliases. Requires coalesce-machines >= 0.5. Ruby times are Integer nanoseconds; the Refused alias is gone.
81
+
82
+ ### Features
83
+
84
+ * Duration instants and spans, Wait names its flight, forget answers Forgetting, Ruby mirrors Decision and Revalidation ([f275b16](https://github.com/seuros/refresh_machines/commit/f275b1663bed9b658d6477a5542886c230946b90))
85
+
86
+ ## [0.2.0](https://github.com/seuros/refresh_machines/compare/refresh_machines/v0.1.2...refresh_machines/v0.2.0) (2026-11-13)
87
+
88
+
89
+ ### ⚠ BREAKING CHANGES
90
+
91
+ * Refresher::drain takes &mut [Notification] and sweep takes &mut [u64] instead of Option slices; RefreshMachines::Notification gains flight_id as its second field. Refused is kept as a deprecated alias of Refusal. Requires coalesce-machines >= 0.4.
92
+
93
+ ### Features
94
+
95
+ * map leases to flights, carry flight_id in notifications, plain output buffers ([0564a61](https://github.com/seuros/refresh_machines/commit/0564a61d8588cbe390248eab537e67bce7b1a45e))
96
+
97
+ ## [0.1.2](https://github.com/seuros/refresh_machines/compare/refresh_machines/v0.1.1...refresh_machines/v0.1.2) (2026-11-13)
98
+
99
+
100
+ ### Features
101
+
102
+ * scope leases and waiter ids so separate refreshers never share one ([66940fb](https://github.com/seuros/refresh_machines/commit/66940fbca88d4e28e6045ef3ec21c8daf0c1325d))
103
+
104
+ ## [0.1.1](https://github.com/seuros/refresh_machines/compare/refresh_machines-v0.1.0...refresh_machines/v0.1.1) (2026-11-12)
105
+
106
+
107
+ ### Features
108
+
109
+ * initial extraction ([38f59b3](https://github.com/seuros/refresh_machines/commit/38f59b36131d87ca31a0ad348a9052a62045541d))
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Abdelkader Boudih
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,352 @@
1
+ # RefreshMachines
2
+
3
+ > A stale answer now beats a perfect answer after the timeout. Sometimes. 🧊
4
+
5
+ A freshness officer for Ruby caches. You tell it how old a value was when you stored it and three durations: how long it is fresh, how long it may be served while someone refreshes it, and how long it may be served if the refresh fails. Then you ask before every read. It answers serve it, serve it and refresh in the background, go fetch, or wait for the caller who is already fetching. One caller per key gets the refresh. Everyone else gets an answer.
6
+
7
+ Pre-1.0: breaking changes land in minor versions. It is a policy core, not a cache: it holds no values, makes no requests, and evicts nothing.
8
+
9
+ ## Quick Start
10
+
11
+ ```bash
12
+ gem 'refresh_machines'
13
+ ```
14
+
15
+ ```ruby
16
+ S = 1_000_000_000 # every instant and span is Integer nanoseconds
17
+ RULES = RefreshMachines::Policy.new(60 * S, 30 * S, 300 * S) # fresh 60s, +30s while revalidating, +300s on error
18
+ # Its own scope: two `Refresher.new` both count ids in scope zero, so their
19
+ # leases and waiter ids alias, and one handed to the other names a live lease there.
20
+ refresher = RefreshMachines::Refresher.with_scope(1)
21
+
22
+ def read(refresher, cache, key)
23
+ now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
24
+ case (decision = refresher.decide(key, now, 10 * S)) # the lease holder has 10s to report
25
+ in RefreshMachines::Fresh
26
+ cache[key]
27
+ in RefreshMachines::Stale(revalidation: RefreshMachines::Lead(lease:))
28
+ RefreshJob.enqueue(key, lease) # you are the one refreshing it
29
+ cache[key]
30
+ in RefreshMachines::Stale
31
+ cache[key] # someone else is on it, or the origin is resting
32
+ in RefreshMachines::Fetch(lease:)
33
+ begin
34
+ cache[key] = origin_fetch(key)
35
+ refresher.store(lease, now, 0, RULES)
36
+ cache[key]
37
+ rescue OriginDown
38
+ refresher.fail(lease, now, 5 * S).is_a?(Integer) ? cache[key] : raise
39
+ end
40
+ in RefreshMachines::Wait(waiter:, flight:)
41
+ park(waiter, flight) # woken from refresher.drain, then read again
42
+ in Symbol
43
+ raise "refresher refused #{key}: #{decision}"
44
+ end
45
+ end
46
+ ```
47
+
48
+ One refresher, one question, three ways to report back: `store`, `fail`, `abandon`. Keys are Integers. Time is Integer nanoseconds everywhere, in and out: `now` straight from `Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)`, and every age, window, `lead_for`, `retry_after` and `Backoff#until` in the same unit. No floats, no seconds, no milliseconds. The clock only goes forward.
49
+
50
+ ## A Message to the Resistance
51
+
52
+ So your product page is cached for sixty seconds. At second sixty-one, four hundred requests arrive, find the entry expired, and all four hundred go ask the database the same question. The database, which was fine, is now not fine. You have built a metronome that attacks you once a minute.
53
+
54
+ So you add a lock. One request refreshes, three hundred ninety-nine wait. They wait for a value that was perfectly good ninety seconds ago, on a page whose price changes twice a year. Then the pricing service has a bad afternoon, the refresh throws, and your cache dutifully serves four hundred errors, because the only thing it had was "expired" and expired means gone.
55
+
56
+ Mark Nottingham wrote this down in RFC 5861 in 2010, in two directives. `stale-while-revalidate`: keep serving the old one while one of you fetches the new one. `stale-if-error`: if the fetch fails, the old one is better than nothing, for a while. Your CDN has done this for years. Your application cache does `fetch(key, expires_in: 60)` and hopes.
57
+
58
+ The part you keep getting wrong isn't the fetch. It's the bookkeeping: how old is this, which window is it in, is anyone already refreshing it, did the last refresh fail, and is the caller who promised to refresh it still alive. That bookkeeping is this gem.
59
+
60
+ ## Chapter 1: Stardate 2026.316, the AMS Nottingham
61
+
62
+ > **AMS Nottingham**, NCC-4230, *Nottingham*-class resupply tender.
63
+ > Issue what is aboard. Send one boat for more.
64
+
65
+ The tender doesn't grow food and it doesn't decide what gets thrown overboard. It keeps the date stamps. Every crate in the hold has an age and three lines on its label: good until, usable while the resupply boat is out, usable if the boat comes back empty. The quartermaster reads the label and says issue it, issue it and launch the boat, or nobody eats until the boat is back.
66
+
67
+ On a bridge somewhere, a cadet volunteers:
68
+
69
+ ```ruby
70
+ def product(id)
71
+ Rails.cache.fetch("product:#{id}", expires_in: 60) { Product.find(id) }
72
+ end
73
+ ```
74
+
75
+ "That," says the tender's quartermaster, "throws out the rations at midnight and sends the whole crew to the planet for lunch."
76
+
77
+ ## The Flight Plan
78
+
79
+ Each value moves through its windows by age alone:
80
+
81
+ ```mermaid
82
+ stateDiagram-v2
83
+ [*] --> fresh: store / put
84
+ fresh --> stale: age reaches fresh_for
85
+ stale --> expired: age passes both stale windows
86
+ stale --> fresh: store
87
+ expired --> fresh: store
88
+ fresh --> [*]: forget
89
+ stale --> [*]: forget
90
+ expired --> [*]: forget / sweep
91
+ ```
92
+
93
+ And what a caller is told depends on the window, the lease, and the last refresh:
94
+
95
+ ```mermaid
96
+ flowchart TD
97
+ A[decide key, now] --> B{fresh?}
98
+ B -- yes --> F[Fresh]
99
+ B -- no --> C{in stale-while-revalidate window?}
100
+ C -- yes --> D{live lease for key?}
101
+ D -- yes --> S1[Stale :in_flight]
102
+ D -- no --> E{last refresh failed, still backing off?}
103
+ E -- yes --> S2[Stale Backoff until]
104
+ E -- no --> S3[Stale Lead lease]
105
+ C -- no --> G{in stale-if-error window AND backing off after a failure?}
106
+ G -- yes --> S2
107
+ G -- no --> H{live lease for key?}
108
+ H -- yes --> W[Wait + waiter id]
109
+ H -- no --> X[Fetch + lease]
110
+ ```
111
+
112
+ The minute the pricing service went down, with `Policy.new(60 * S, 30 * S, 300 * S)` (the diagram counts in seconds; the calls take nanoseconds):
113
+
114
+ ```mermaid
115
+ sequenceDiagram
116
+ participant A as Request A
117
+ participant R as Refresher
118
+ participant B as Request B
119
+ participant O as Origin
120
+
121
+ A->>R: decide(42, 70s)
122
+ R-->>A: Stale, Lead lease 4
123
+ Note over A: serves the old price
124
+ B->>R: decide(42, 71s)
125
+ R-->>B: Stale :in_flight
126
+ Note over B: serves the old price
127
+ A->>O: fetch 42
128
+ O-->>A: 503
129
+ A->>R: fail(lease 4, 72s, retry_after 20s)
130
+ R-->>A: 70s (stale is allowed, it is 70s old)
131
+ B->>R: decide(42, 80s)
132
+ R-->>B: Stale, Backoff until 92s
133
+ Note over B: serves the old price. Origin gets a rest.
134
+ ```
135
+
136
+ ## How the Refresher Works
137
+
138
+ ### Policy
139
+
140
+ ```ruby
141
+ S = 1_000_000_000
142
+ rules = RefreshMachines::Policy.new(10 * S, 5 * S, 20 * S)
143
+
144
+ rules.state(9 * S) # => :fresh
145
+ rules.state(10 * S) # => :stale
146
+ rules.while_revalidate?(14 * S) # => true
147
+ rules.while_revalidate?(15 * S) # => false
148
+ rules.if_error?(29 * S) # => true
149
+ rules.state(30 * S) # => :expired
150
+ ```
151
+
152
+ Three spans, in nanoseconds. Fresh while the age is below `fresh_for`. Both stale windows start when freshness ends, so this value is revalidate-servable from 10s up to (not including) 15s old and error-servable from 10s up to 30s old. A zero window turns its rule off. Past both, the value is `:expired` and is never served.
153
+
154
+ ### Decide
155
+
156
+ ```ruby
157
+ refresher = RefreshMachines::Refresher.new
158
+
159
+ t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
160
+
161
+ fetch = refresher.decide(42, t0, 100 * S) # key 42, now, lease good for 100s
162
+ fetch.class # => RefreshMachines::Fetch
163
+ wait = refresher.decide(42, t0 + S, 100 * S) # => #<data RefreshMachines::Wait waiter=3, flight=2>
164
+ wait.flight == refresher.flight(fetch.lease) # => true
165
+ ```
166
+
167
+ Nothing is cached, so the first caller fetches and the second waits. A `Fetch` has one field, `lease`: the lease id you report with. A `Wait` has `waiter` and `flight`, the same two fields in the same order as a `CoalesceMachines::Follower`: `waiter` is the id you park under, and `flight` is the refresh being shared, the one `flight(lease)` answers for the key's live lease and the one the notification will name. Neither carries the key; you already hold the one you asked about. The third argument is how long the lease holder has to report back.
168
+
169
+ ### Store
170
+
171
+ ```ruby
172
+ refresher.store(fetch.lease, t0 + (2 * S), 0, rules) # => :stored
173
+ refresher.decide(42, t0 + (5 * S), 100 * S) # => #<data RefreshMachines::Fresh age=3000000000>
174
+ refresher.drain(10).map(&:outcome) # => [:completed]
175
+ ```
176
+
177
+ `store` says the value under that lease's key is new as of `now`. The third argument is its age on arrival: zero if the origin just made it, more if it came through another cache that had held it a while. The waiter gets a notification and asks again.
178
+
179
+ To record a value you wrote without being asked, use `put(key, now, age, policy)`.
180
+
181
+ ### Stale while revalidate
182
+
183
+ ```ruby
184
+ stale = refresher.decide(42, t0 + (12 * S), 100 * S)
185
+ stale.revalidation # => #<data RefreshMachines::Lead lease=4>
186
+ lead = stale.revalidation
187
+ refresher.decide(42, t0 + (13 * S), 100 * S).revalidation # => :in_flight
188
+ refresher.waiting # => 0
189
+ ```
190
+
191
+ Ten seconds old, inside the revalidate window. Both callers serve the old value. The first one also gets a `Lead` with a `lease` and the job of refreshing it. Nobody waits.
192
+
193
+ A `Stale` has two fields, `age` and `revalidation`, and `revalidation` is one of four things:
194
+
195
+ | `revalidation` | Meaning |
196
+ | --- | --- |
197
+ | `Lead(lease)` | Nobody was refreshing this key. You are now: report with `lease`. |
198
+ | `:in_flight` | Another caller holds a live lease. Just serve. |
199
+ | `Backoff(until)` | The last refresh failed and asked for quiet until that instant. Just serve. |
200
+ | `Unavailable(refusal)` | A refresh is due but could not be registered; `decide` answers it with `refusal` `:flights_full` or `:exhausted`. Just serve. |
201
+
202
+ ### Fail, and stale if error
203
+
204
+ ```ruby
205
+ refresher.fail(lead.lease, t0 + (14 * S), 5 * S) # => 12000000000
206
+ quiet = refresher.decide(42, t0 + (18 * S), 100 * S)
207
+ # => #<data RefreshMachines::Stale age=16000000000, revalidation=#<data RefreshMachines::Backoff until=...>>
208
+ quiet.revalidation.until == t0 + (19 * S) # => true
209
+ ```
210
+
211
+ `fail` returns the age of the old value if its stale-if-error window is open, or `nil` if there is nothing to fall back on. The third argument is how long to leave the origin alone. Until then callers are served stale and nobody is handed a lease.
212
+
213
+ Outside the revalidate window the error window does not serve anything on its own. The caller gets `Fetch` and must try. Only a failure makes the old value servable:
214
+
215
+ ```ruby
216
+ fetch = refresher.decide(42, t0 + (19 * S), 100 * S)
217
+ fetch.class # => RefreshMachines::Fetch, at 17s old the revalidate window is over
218
+ ```
219
+
220
+ ### Abandon
221
+
222
+ ```ruby
223
+ refresher.abandon(fetch.lease) # => :abandoned
224
+ refresher.decide(42, t0 + (19 * S), 100 * S).class # => RefreshMachines::Fetch
225
+ ```
226
+
227
+ The request was cancelled, the job was shed, the fetch never ran. That isn't a failure, so no backoff starts. The next caller leads.
228
+
229
+ ### Overdue leases
230
+
231
+ ```ruby
232
+ refresher = RefreshMachines::Refresher.new
233
+ dead = refresher.decide(7, t0, 10 * S) # lease due back within 10s
234
+ refresher.decide(7, t0 + (9 * S), 10 * S).class # => RefreshMachines::Wait
235
+ heir = refresher.decide(7, t0 + (10 * S), 10 * S) # => a Fetch with a new lease
236
+ refresher.store(dead.lease, t0 + (11 * S), 0, rules) # => :stale
237
+ refresher.reap(t0 + (20 * S)) # => 1
238
+ ```
239
+
240
+ A worker that dies holding a lease would otherwise hold the key forever. At the deadline the next caller who needs a refresh takes it over, and the old lease is refused from then on. Waiters stay parked and are woken by the new leader. `reap(now)` revokes overdue leases nobody came back for, so their waiters get `:abandoned` instead of silence.
241
+
242
+ ### Notifications and flights
243
+
244
+ ```ruby
245
+ refresher = RefreshMachines::Refresher.new
246
+ fetch = refresher.decide(42, t0, 100 * S)
247
+ wait = refresher.decide(42, t0 + S, 100 * S)
248
+ flight = refresher.flight(fetch.lease) # the refresh this lease rides on
249
+ refresher.store(fetch.lease, t0 + (2 * S), 0, rules) # => :stored
250
+ refresher.drain(10)
251
+ # => [#<data RefreshMachines::Notification waiter=3, flight=2, key=42, outcome=:completed>]
252
+ refresher.flight(fetch.lease) # => nil, the lease is spent
253
+ ```
254
+
255
+ A notification has `waiter`, `flight`, `key` and `outcome`, the same four fields in the same order as a `CoalesceMachines::Notification`. `flight` names the refresh that settled, and `flight(lease)` tells you which one a live lease is riding, so you can file the result under it before you report and hand it to the waiters as they wake.
256
+
257
+ A takeover issues a new lease for the same flight: the heir's lease answers the same flight id, the dead one answers `nil`. So does any lease that was reported, abandoned, reaped, never issued, or issued by a refresher in another scope. Ask while the lease is live. Lease ids, waiter ids and flight ids all come from one sequence, so no two of them are ever the same number: here the lease is 1, its flight 2 and the waiter 3.
258
+
259
+ ### Forget and sweep
260
+
261
+ ```ruby
262
+ refresher.put(42, t0 + (20 * S), 0, rules) # => :stored
263
+ refresher.put(43, t0 + (20 * S), 0, rules) # => :stored
264
+ refresher.forget(43) # => :forgotten
265
+ refresher.forget(43) # => :not_held, nothing to drop, nothing changed
266
+ refresher.sweep(t0 + (1_000 * S), 50) # => [42]
267
+ ```
268
+
269
+ `forget` is for when your cache evicts a value. It never refuses: forgetting a key that has no metadata is the same request already satisfied, so it answers `:not_held`. `size` counts the keys with metadata and `empty?` says whether there are none. `sweep(now, max)` drops up to `max` expired entries and returns their keys so you can delete the values too. Call it again for the rest. A `max` past `CAPACITY` (for `drain`, past `WAITER_CAPACITY`) simply takes everything there is, since there is never more.
270
+
271
+ ### Capacity
272
+
273
+ ```ruby
274
+ RefreshMachines::Refresher::CAPACITY # => 256 keys with metadata
275
+ RefreshMachines::Refresher::FLIGHT_CAPACITY # => 64 refreshes in progress
276
+ RefreshMachines::Refresher::WAITER_CAPACITY # => 256 waiters plus undrained notifications
277
+ ```
278
+
279
+ Past those, `put` and `store` say `:entries_full`, and `decide` says `:flights_full` or `:waiters_full`. Nothing is evicted to make room. One exception that isn't one: if a stale value is servable and the refresh can't be registered, you still get `Stale`, with the reason in `revalidation`: `Unavailable(refusal: :flights_full)` or `Unavailable(refusal: :exhausted)`. That is an honoured answer, not a refusal: the stale value is served, and the refresh that couldn't be registered changed nothing.
280
+
281
+ ### Time only moves forward
282
+
283
+ ```ruby
284
+ refresher = RefreshMachines::Refresher.new
285
+ refresher.put(1, t0, 0, rules) # => :stored
286
+ refresher.decide(1, t0 - 1, 100 * S) # => :time_regressed
287
+ refresher.decide(1, t0, 0) # => :zero_lead, a zero lease is overdue at birth
288
+ ```
289
+
290
+ ## The Rules of the Quartermaster
291
+
292
+ - **Everything is an Integer** in `0..2**64-1`, except instants (below). Floats, nil and strings raise `TypeError`. Out of range raises `RangeError`. A policy argument that isn't a `Policy` raises `TypeError`. An id the refresher could never have issued, one whose sequence (the low 48 bits) is zero, raises `RangeError` wherever a lease or waiter id is taken (`store`, `fail`, `abandon`, `cancel`, `flight`), before the refresher is asked.
293
+ - **Values are valid or do not exist.** Every Data value checks itself through the core when it is built, by the gem or by hand: `Policy` windows in `0..2**64-1`; `Fresh#age`, `Stale#age` and `Backoff#until` Integer nanoseconds up to the core's `Duration::MAX`; a `Stale#revalidation` that is a `Lead`, `:in_flight`, a `Backoff` or an `Unavailable`; lease, waiter and flight ids with a nonzero sequence; a `Wait` or `Notification` whose waiter is of its flight's scope and issued after it; an `Unavailable#refusal` that is a refusal symbol; an `outcome` of `:completed` or `:abandoned`. The wrong type raises `TypeError`, a value outside that `RangeError`: `Fetch.new(0)`, `Wait.new(2, 3)` and `Unavailable.new(:nope)` raise.
294
+ - **The binding never loses work.** Every argument is converted before the core is called, and every class was resolved once, when the extension loaded. A mutating call whose answer is a Ruby object (`decide`, `sweep`, `poll`, `drain`) decides on a copy of the refresher and keeps it only once the answer is built, natively (allocate, fill, freeze, no Ruby `initialize`); `drain` and `sweep` read into a buffer first. Frozen meanwhile is `FrozenError`, changed meanwhile `RuntimeError`; a call that raises changed nothing.
295
+ - **Values are sealed, and the binding is the authority.** Subclassing a value class raises `TypeError` and `allocate` is undefined. Sealing stops accidents, not reflection (a named subclass's constant is bound before the raise, `Marshal.load` skips `initialize`), so a value the binding reads (a `Policy`, a `Stale`'s revalidation) must be an instance of exactly its class, and its fields are checked again: a forged one raises `TypeError` or `RangeError`.
296
+ - **Time is Integer nanoseconds.** Instants (`now`, `Backoff#until`) and spans (ages, the three policy windows, `lead_for`, `retry_after`) alike, in and out. A Float, a Rational or anything else that isn't an Integer raises `TypeError`. A span argument is in `0..2**64-1`; `now` runs over the whole Rust `Duration` range, `0..Duration::MAX` nanoseconds (about `1.8e28`), so every `Backoff#until` the refresher answers reads back as `now`. Outside its range a value raises `RangeError`. Nothing wraps: a returned age or `Backoff#until` is the exact sum, even past `2**64-1`.
297
+ - **Refusals don't raise.** `:time_regressed`, `:zero_lead`, `:entries_full`, `:flights_full`, `:waiters_full`, `:exhausted` and `:stale` are answers, and a refused call changes nothing.
298
+ - **Every answer, by method.**
299
+
300
+ | Method | Honoured | Refused | Records `now` |
301
+ | --- | --- | --- | --- |
302
+ | `decide(key, now, lead_for)` | a `Fresh`, `Stale`, `Fetch` or `Wait` | `:time_regressed`, `:zero_lead`, and, only when nothing is servable, `:flights_full`, `:waiters_full`, `:exhausted` | every honoured answer, `Stale` with an `Unavailable` included: each depends on the age and the lease deadline at `now` |
303
+ | `store(lease, now, age, policy)` | `:stored` | `:time_regressed`, `:stale`, `:entries_full` | yes: the stored value's age counts from `now` |
304
+ | `fail(lease, now, retry_after)` | the age of the value that covers for the failure (Integer), or `nil` when nothing does | `:time_regressed`, `:stale` | yes, both answers: the age, the window and the backoff are judged at `now` |
305
+ | `abandon(lease)` | `:abandoned` | `:stale` | takes no time |
306
+ | `reap(now)` | leases revoked (Integer) | `:time_regressed` | yes, `0` included: which leases are overdue depends on `now` |
307
+ | `put(key, now, age, policy)` | `:stored` | `:time_regressed`, `:entries_full` | yes: the value's age counts from `now` |
308
+ | `forget(key)` | `:forgotten` when there was metadata to drop, `:not_held` when there was none (an idempotent repeat) | never refuses | takes no time |
309
+ | `sweep(now, max)` | an Array of swept keys | `:time_regressed` | yes, `[]` included: which entries are expired depends on `now` |
310
+ | `cancel(waiter)` | `:cancelled` | `:stale` | takes no time |
311
+ | `poll` | the oldest queued `Notification`, `nil` when nothing is queued | never refuses | takes no time |
312
+ | `drain(max)` | an Array of `Notification`, `[]` when nothing is queued | never refuses | takes no time |
313
+
314
+ Every refusal has its own symbol; there is no catch-all. A refusal records no time: regression is judged against the latest honoured `now`, which `now` reads back.
315
+ - **A lease is a capability.** Whoever holds the lease id reports the refresh. Reported, abandoned, reaped or taken over, it answers `:stale` forever.
316
+ - **Scopes: ids belong to the refresher that issued them.** Lease, waiter and flight ids are plain Integers, so two refreshers in the same scope issue the same ones, and an id handed to the wrong refresher can name a live lease or waiter there. Two `Refresher.new` are both scope zero, so their ids alias. If you run more than one, or a `CoalesceMachines::Coalescer` beside it, give each its own scope: `Refresher.with_scope(3)`, any Integer in `0..65_535`. `Refresher.new` is scope zero and counts 1, 2, 3 across leases, flights and waiters alike. The scope rides in the top 16 bits of every id, above a 48-bit sequence, and an id from another scope is always `:stale` (`nil` from `flight`). The refresher can't pick a scope for you. `RefreshMachines.scope_of(id)` reads the scope back, so you can route an id to the refresher that issued it. It is the only layout helper the gem has: the layout belongs to the Rust crate `periscope-machines`, which has no gem. A scope that isn't an Integer raises `TypeError`; out of range raises `RangeError`.
317
+ - **One sequence: a lease number is never a waiter number.** Leases, waiter ids and flight ids are bare Integers, so nothing but their values tells them apart, and the refresher draws all three from one sequence: no two ids it issues are equal. Pass a lease to `cancel`, or a waiter or flight id to `store`, `fail`, `abandon` or `flight`, and you get `:stale` (`nil` from `flight`) with nothing changed. A new refresh takes two numbers, its lease and then its flight; a takeover and a wait take one. After `2**48 - 1` of them `decide` answers `:exhausted` wherever it would need an id, and a full table is reported first: `:flights_full` or `:waiters_full` before `:exhausted`.
318
+ - **Restarts: resume the sequence, or take a new scope.** A new refresher counts from one again, so a lease or waiter id that outlived a restart could name a new refresh. Either save `issued` and build the replacement with `Refresher.resumed(scope, issued)`, which is empty, at time zero, and carries on after the saved count (`nil` if `issued` is more than `2**48 - 1`), or give each incarnation a scope it never had before.
319
+ - **Repeats are refused.** A second `store`, `fail`, or `abandon` on a settled lease, and a second `cancel` on a waiter that left, are `:stale`: the refresher keeps nothing about how a lease or waiter ended.
320
+ - **Waiters ask again.** A notification says which refresh settled (`flight`) and how, `:completed` or `:abandoned`. It doesn't carry a decision. Call `decide` again.
321
+ - **Frozen means frozen.** `freeze` the refresher and every mutating call raises `FrozenError`.
322
+
323
+ ## What You Think You're Doing vs Reality
324
+
325
+ ### You Think: "The entry expired, so I refetch."
326
+ ### Reality: So does everyone else.
327
+
328
+ Expiry is one instant shared by every request for that key. `decide` hands the refresh to exactly one caller and tells the rest to serve what they have or wait.
329
+
330
+ ### You Think: "If the refresh fails I'll just raise."
331
+ ### Reality: You had a working answer and threw it away.
332
+
333
+ A value that was good enough a minute ago is usually good enough during an outage. `stale_if_error` is how long you're willing to believe that. `fail` tells you whether you still are.
334
+
335
+ ### You Think: "stale-if-error means I can serve stale whenever."
336
+ ### Reality: It means you tried.
337
+
338
+ Past the revalidate window `decide` says `Fetch`, not `Stale`. The old value becomes servable when a refresh has actually failed, and stays servable only for the backoff you asked for.
339
+
340
+ ## What's Yours
341
+
342
+ The values. The refresher never sees them, so keeping `cache[key]` and its metadata in step is your job: `forget` when you evict, delete when `sweep` tells you. Which keys to keep at all is an eviction question, and that's [cache_machines](https://github.com/seuros/cache_machines).
343
+
344
+ The clock, the fetch, the retry schedule and the parking lot. You pass `now`, you run the request, you pick each `retry_after`, and you wake whatever is waiting under a waiter id. Parsing `Cache-Control` into three durations is yours too.
345
+
346
+ The process boundary. State lives in memory in one refresher and is gone on restart. Two processes each elect their own leader for the same key. A lease that times out may belong to a worker that's still running: its late `store` is refused here, but its request already hit your origin.
347
+
348
+ ## License
349
+
350
+ MIT License. See [LICENSE.txt](LICENSE.txt) for details.
351
+
352
+ **Remember: the old value was fine a second ago. Ask before you throw it out.**
@@ -0,0 +1,77 @@
1
+ # Changelog
2
+
3
+ ## [0.8.1](https://github.com/seuros/refresh_machines/compare/refresh-machines-v0.8.0...refresh-machines-v0.8.1) (2026-11-16)
4
+
5
+
6
+ ### Bug Fixes
7
+
8
+ * refresher core drops slot indexing for slot references ([f0ebbce](https://github.com/seuros/refresh_machines/commit/f0ebbce39e8414127b8a9ee3718397046ed63b60))
9
+
10
+ ## [0.8.0](https://github.com/seuros/refresh_machines/compare/refresh-machines-v0.7.0...refresh-machines-v0.8.0) (2026-11-14)
11
+
12
+
13
+ ### ⚠ BREAKING CHANGES
14
+
15
+ * adopt matryona-machines 0.2: hooks name their field, instant for answered ages, symbols! tables, exact Policy fields
16
+
17
+ ### Features
18
+
19
+ * adopt matryona-machines 0.2: hooks name their field, instant for answered ages, symbols! tables, exact Policy fields ([c0d3932](https://github.com/seuros/refresh_machines/commit/c0d393265f5f0b0306cc82a8ea31f125346cc776))
20
+
21
+ ## [0.7.0](https://github.com/seuros/refresh_machines/compare/refresh-machines-v0.6.0...refresh-machines-v0.7.0) (2026-11-14)
22
+
23
+
24
+ ### ⚠ BREAKING CHANGES
25
+
26
+ * seal values, native Policy and Stale checks by exact class, clone-then-keep decide/sweep/poll/drain
27
+
28
+ ### Features
29
+
30
+ * seal values, native Policy and Stale checks by exact class, clone-then-keep decide/sweep/poll/drain ([5a6b1f8](https://github.com/seuros/refresh_machines/commit/5a6b1f8ac6907696939d2ad443836d8336f03365))
31
+
32
+ ## [0.6.0](https://github.com/seuros/refresh_machines/compare/refresh-machines-v0.5.0...refresh-machines-v0.6.0) (2026-11-13)
33
+
34
+
35
+ ### ⚠ BREAKING CHANGES
36
+
37
+ * leases, waiter ids and flight ids of a refresher share one sequence, so a handle rebuilt as the wrong kind names nothing. Requires coalesce-machines >= 0.6. Raw lease numbers change; capacity is checked before the sequence.
38
+
39
+ ### Features
40
+
41
+ * scope ids through periscope-machines and draw leases from the coalescer's sequence; add resumed and issued ([9a9537b](https://github.com/seuros/refresh_machines/commit/9a9537beef8a10e1be244167f4713698dfaa3f1a))
42
+
43
+ ## [0.5.0](https://github.com/seuros/refresh_machines/compare/refresh-machines-v0.4.0...refresh-machines-v0.5.0) (2026-11-13)
44
+
45
+
46
+ ### ⚠ BREAKING CHANGES
47
+
48
+ * see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats only when provable, Duration time, Ruby mirrors the core. No compatibility aliases. Requires coalesce-machines >= 0.5. Ruby times are Integer nanoseconds; the Refused alias is gone.
49
+
50
+ ### Features
51
+
52
+ * Duration instants and spans, Wait names its flight, forget answers Forgetting, Ruby mirrors Decision and Revalidation ([f275b16](https://github.com/seuros/refresh_machines/commit/f275b1663bed9b658d6477a5542886c230946b90))
53
+
54
+ ## [0.4.0](https://github.com/seuros/refresh_machines/compare/refresh-machines-v0.3.0...refresh-machines-v0.4.0) (2026-11-13)
55
+
56
+
57
+ ### ⚠ BREAKING CHANGES
58
+
59
+ * Refresher::drain takes &mut [Notification] and sweep takes &mut [u64] instead of Option slices; RefreshMachines::Notification gains flight_id as its second field. Refused is kept as a deprecated alias of Refusal. Requires coalesce-machines >= 0.4.
60
+
61
+ ### Features
62
+
63
+ * map leases to flights, carry flight_id in notifications, plain output buffers ([0564a61](https://github.com/seuros/refresh_machines/commit/0564a61d8588cbe390248eab537e67bce7b1a45e))
64
+
65
+ ## [0.3.0](https://github.com/seuros/refresh_machines/compare/refresh-machines-v0.2.0...refresh-machines-v0.3.0) (2026-11-13)
66
+
67
+
68
+ ### Features
69
+
70
+ * scope leases and waiter ids so separate refreshers never share one ([66940fb](https://github.com/seuros/refresh_machines/commit/66940fbca88d4e28e6045ef3ec21c8daf0c1325d))
71
+
72
+ ## [0.2.0](https://github.com/seuros/refresh_machines/compare/refresh-machines-v0.1.0...refresh-machines-v0.2.0) (2026-11-12)
73
+
74
+
75
+ ### Features
76
+
77
+ * initial extraction ([38f59b3](https://github.com/seuros/refresh_machines/commit/38f59b36131d87ca31a0ad348a9052a62045541d))
@@ -0,0 +1,175 @@
1
+ # refresh-machines
2
+
3
+ > **AMS Nottingham**, NCC-4230, *Nottingham*-class resupply tender.
4
+
5
+ Engine-room flight manual: decide whether the stores already aboard may be
6
+ issued, and which single crew goes out for the resupply.
7
+
8
+ Allocation-free `no_std` freshness metadata and refresh leases, after RFC 5861.
9
+ A `Policy` holds three `Duration`s: `fresh_for`, `stale_while_revalidate` and
10
+ `stale_if_error`. Given an explicit age it answers `Fresh`, `Stale` or
11
+ `Expired`. A `Refresher` keeps that metadata per key and turns a lookup into a
12
+ `Decision`: serve fresh, serve stale (and maybe lead the revalidation), fetch
13
+ under a lease, or wait for whoever is already fetching.
14
+
15
+ The refresher stores no values, fetches nothing and evicts nothing. The caller
16
+ holds the cache, runs the fetch, and reports `store`, `fail` or `abandon` with
17
+ the lease. Which keys stay in the cache is `cache-machines`' question; this
18
+ crate only says whether a value that is still there may be served.
19
+
20
+ ```rust
21
+ use core::time::Duration;
22
+
23
+ use refresh_machines::{Decision, Policy, Refresher, Revalidation};
24
+
25
+ // Instants are time since an epoch the caller picks; here, whole seconds.
26
+ let s = Duration::from_secs;
27
+ // Fresh for 60s, then 30s more while revalidating, 300s more if the origin errors.
28
+ let rules = Policy::new(s(60), s(30), s(300));
29
+ // Its own scope: two refreshers built with `new()` are both scope zero, so
30
+ // their ids alias and one handed to the other can name a live lease there.
31
+ let mut refresher = Refresher::<8, 4, 16>::with_scope(1);
32
+
33
+ // Nothing cached: this caller fetches, with 10s to report back.
34
+ let Ok(Decision::Fetch { lease }) = refresher.decide(42, s(0), s(10)) else { panic!("miss") };
35
+ // A second caller waits, and is told which flight it shares.
36
+ let Ok(Decision::Wait { flight, .. }) = refresher.decide(42, s(1), s(10)) else { panic!("waits") };
37
+ assert_eq!(refresher.flight(lease), Some(flight));
38
+ assert_eq!(refresher.store(lease, s(2), Duration::ZERO, rules), Ok(()));
39
+ assert_eq!(refresher.decide(42, s(50), s(10)), Ok(Decision::Fresh { age: s(48) }));
40
+
41
+ // Stale but inside the revalidate window: serve it, one caller refreshes.
42
+ let Ok(Decision::Stale { age, revalidation: Revalidation::Lead(lease) }) =
43
+ refresher.decide(42, s(70), s(10)) else { panic!("first stale caller leads") };
44
+ assert_eq!(age, s(68));
45
+ assert_eq!(
46
+ refresher.decide(42, s(71), s(10)),
47
+ Ok(Decision::Stale { age: s(69), revalidation: Revalidation::InFlight })
48
+ );
49
+
50
+ // The origin is down. The stale-if-error window is open, so the old value
51
+ // covers, and nobody is asked to refetch for the next 20s.
52
+ assert_eq!(refresher.fail(lease, s(72), s(20)), Ok(Some(s(70))));
53
+ assert_eq!(
54
+ refresher.decide(42, s(85), s(10)),
55
+ Ok(Decision::Stale { age: s(83), revalidation: Revalidation::Backoff { until: s(92) } })
56
+ );
57
+ ```
58
+
59
+ ## Contract
60
+
61
+ - **Time and ages.** Every instant and every span is a `core::time::Duration`:
62
+ `now` is monotonic time since an epoch the caller picks, and `lead_for`,
63
+ `retry_after`, ages and the three policy windows are spans. Every mutating
64
+ call takes `now` and refuses an earlier one with `Refusal::TimeRegressed`;
65
+ a zero `lead_for` is `Refusal::ZeroLead`, a lease overdue before it is
66
+ issued.
67
+ `store` and `put` take the value's age on arrival, so a response that was
68
+ already old upstream starts old here. Ages, deadlines and backoffs saturate
69
+ at `Duration::MAX`.
70
+ - **Windows.** Fresh while `age < fresh_for`. Both stale windows open when
71
+ freshness ends and are half-open: a `stale_while_revalidate` of 30s covers
72
+ ages `fresh_for .. fresh_for + 30s`. A zero window disables its rule. Past both
73
+ windows the value is `Expired` and is never served.
74
+ - **Decisions.** Inside the revalidate window the value is served and exactly
75
+ one caller gets `Revalidation::Lead`. Outside it but inside the error window
76
+ the caller must fetch (or wait); only a reported failure makes the old value
77
+ servable, for as long as the failure's `retry_after` and the window both
78
+ last. With nothing servable the answer is `Fetch` or `Wait`.
79
+ - **Leases.** One live lease per key, built on `coalesce-machines`. A lease is
80
+ a capability: whoever holds it reports the refresh. It carries a deadline
81
+ (`now + lead_for`); once that passes, the next caller needing a refresh takes
82
+ it over, and `reap` revokes overdue leases nobody replaced. A taken-over,
83
+ reaped, reported or abandoned lease is `Refusal::Stale` forever.
84
+ - **Waiters.** `Wait { waiter, flight }` returns a `WaiterId` and the `FlightId`
85
+ being shared, the same pair as `coalesce_machines::Joined::Follower`. The
86
+ flight is what `flight(lease)` answers for the key's live lease and what the
87
+ notification will carry. When the refresh settles each waiter
88
+ gets one `Notification` (`Completed` after `store`, `Abandoned` after `fail`,
89
+ `abandon` or `reap`) through `poll` or `drain`, then decides again. A takeover
90
+ keeps the waiters. `cancel` withdraws one.
91
+ - **Leases and flights.** Each refresh rides one `coalesce-machines` flight,
92
+ and `Notification::flight` names it. `flight(lease)` answers the `FlightId`
93
+ a live lease rides on, so a notification can be tied back to the lease that
94
+ caused it. A takeover issues a new lease for the same flight: the new lease
95
+ answers the old one's flight and the old one answers `None`, as does any
96
+ stale lease or one from another scope. The mapping ends when the refresh
97
+ settles, so record it while the lease is live.
98
+ - **One sequence.** Leases, waiter ids and flight ids all come from the one
99
+ sequence of the coalescer inside (leases through its `reserve`), so no two
100
+ ids of a refresher are equal, whatever their kind. A lease rebuilt as a
101
+ `WaiterId`, or a waiter or flight id rebuilt as a `Lease`, is
102
+ `Refusal::Stale` and changes nothing. A new refresh takes two ids, its
103
+ lease and then its flight; a takeover takes one, the new lease; a wait takes
104
+ one.
105
+ - **Output buffers.** `drain(out: &mut [Notification])` and
106
+ `sweep(now, out: &mut [u64])` write the first `n` entries, return `n` and
107
+ leave the rest untouched. `[Notification::default(); N]` and `[0; N]` size
108
+ them; the default notification is a placeholder that is never emitted (its
109
+ ids are raw zero, never issued). Read only the `n` entries reported.
110
+ - **Scopes.** Ids are only meaningful to the refresher that issued them. Two
111
+ refreshers in the same scope issue the same leases and waiter ids, and an id
112
+ handed to the wrong one can name a live lease or waiter there, so give each
113
+ refresher, and any bare coalescer beside it, its own scope:
114
+ `Refresher::with_scope(scope)` puts a caller-chosen `u16` in the top 16 bits
115
+ of every lease, waiter id and flight id. An id from another scope is always
116
+ `Refusal::Stale` (`None` from `flight`), refused before any table is read.
117
+ `new()` is scope zero and counts 1, 2, 3 across all three kinds. The
118
+ refresher cannot choose a scope itself. The layout belongs to
119
+ `periscope-machines`, so use its `scoped`, `scope_of` and `sequence_of` on
120
+ raw ids. After `periscope_machines::SEQUENCE_MAX` (2^48 - 1) ids `decide`
121
+ answers `Refusal::Exhausted` wherever it would need one, and already when a
122
+ new refresh would need two and one is left. A full table is reported before
123
+ a spent sequence (`FlightsFull` or `WaitersFull`, then `Exhausted`), and a
124
+ refused `decide` consumes no id.
125
+ - **Restarts.** A new refresher counts from one again, so a lease or waiter id
126
+ that outlived a restart could name a new refresh. Either save `issued()` and
127
+ build the replacement with `Refresher::resumed(scope, issued)` (empty, at
128
+ time zero, the sequence continuing; `None` when `issued` is beyond
129
+ `SEQUENCE_MAX`), or give each incarnation a new scope.
130
+ - **Repeats are not honoured.** The refresher keeps nothing about a lease once
131
+ it is reported, abandoned, reaped or taken over, nor about a waiter once it
132
+ leaves, so a second `store`, `fail`, `abandon` or `cancel` is
133
+ `Refusal::Stale` even though the id was provably issued here.
134
+ - **Capacities.** `Refresher<KEYS, FLIGHTS, WAITERS>`. A full table answers
135
+ `EntriesFull`, `FlightsFull` or `WaitersFull`; nothing is evicted. While a
136
+ stale value is servable a full flight table does not refuse the caller: it
137
+ answers `Ok(Decision::Stale { .. })` with `Revalidation::Unavailable(reason)`.
138
+ That is on purpose and not a refused call: the stale value is still served,
139
+ so the decision is honoured, and the registration that failed changed nothing
140
+ (no lease, no flight, no waiter). The next caller tries again.
141
+ - **Refusals change nothing.** Every `Err` leaves the refresher as it was.
142
+ - **Which answers record the clock.** A refusal records nothing. Every
143
+ honoured `decide`, `store`, `fail`, `put`, `reap` and `sweep` records `now`,
144
+ because each answer depends on it: a decision on the age and the lease
145
+ deadline at `now` (including `Stale` with `Revalidation::Unavailable`, which
146
+ is honoured and so advances the clock), a stored value's age counting from
147
+ `now`, `fail`'s covering age and backoff, which leases are overdue and which
148
+ entries expired at `now`, even when none are. `abandon`, `forget`,
149
+ `cancel`, `poll` and `drain` take no time and record none.
150
+ - **Ids are never zero.** `Lease::from_raw` answers `None` for a sequence of
151
+ zero, as `FlightId::from_raw` and `WaiterId::from_raw` do: no refresher
152
+ issues one. Ids are not ordered: each carries its refresher's scope, and an
153
+ order across scopes means nothing.
154
+ - **Rebuilt decisions.** `Decision::wait(waiter, flight)` rebuilds a
155
+ `Decision::Wait` only from ids one refresher could answer together (the
156
+ same scope, the waiter issued after its flight), as
157
+ `coalesce_machines::Joined::follower` judges; `None` otherwise.
158
+ - **Housekeeping.** `forget(key)` drops metadata when the cache evicts the
159
+ value. It never refuses and answers `Forgetting::Forgotten`, or
160
+ `Forgetting::NotHeld` when the key already had none: an idempotent repeat
161
+ that changes nothing. `sweep(now, out)` drops expired metadata into a caller-sized buffer and
162
+ resumes on the next call.
163
+
164
+ ## Not Included
165
+
166
+ No clock, values, payloads, hashing, I/O, threads or locks. No eviction or
167
+ admission. No negative caching: a miss that fails is forgotten and the next
168
+ caller fetches. No HTTP parsing: map `max-age`, `stale-while-revalidate` and
169
+ `stale-if-error` to the three durations yourself. No wall clock: turning a
170
+ timestamp into an age is the caller's job. No retry schedule: the caller
171
+ supplies each `retry_after`. Keys are caller-supplied `u64`s. State is in memory
172
+ and scoped to one refresher. Lookups are linear scans over the fixed tables,
173
+ which suits small capacities.
174
+
175
+ Pre-1.0: breaking changes land in minor versions.
@@ -0,0 +1,2 @@
1
+ # frozen_string_literal: true
2
+ require_relative 'ffi/extconf'
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module RefreshMachines
4
+ VERSION = '0.7.3'
5
+ end
@@ -0,0 +1,113 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative 'refresh_machines/version'
4
+
5
+ # Every Data value below is held to what the core accepts, whether the gem
6
+ # returned it or it was built by hand: TypeError for the wrong type,
7
+ # RangeError for a value outside the core's domain.
8
+ module RefreshMachines
9
+ # Freshness rules for one value, as three spans in Integer nanoseconds.
10
+ # Both stale windows open when `fresh_for` ends. `state`,
11
+ # `while_revalidate?` and `if_error?` are native and take an age.
12
+ #
13
+ # Every instant and span in this gem is Integer nanoseconds: `now` as read
14
+ # from `Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)`, and
15
+ # every age, window, `lead_for`, `retry_after` and `Backoff#until`.
16
+ # Span arguments, and the Policy windows, are in 0..2**64-1; `now` is in
17
+ # 0..`Duration::MAX`, so every instant the refresher answers reads back as
18
+ # `now`. An age or instant the core answers (Fresh, Stale, Backoff) may be
19
+ # past 2**64-1, up to `Duration::MAX`, because sums saturate instead of
20
+ # wrapping.
21
+ Policy = Data.define(:fresh_for, :stale_while_revalidate, :stale_if_error) do
22
+ def initialize(fresh_for:, stale_while_revalidate:, stale_if_error:)
23
+ RefreshMachines.__send__(:__policy, fresh_for, stale_while_revalidate, stale_if_error)
24
+ super
25
+ end
26
+ end
27
+ # Serve the cached value.
28
+ Fresh = Data.define(:age) do
29
+ def initialize(age:)
30
+ RefreshMachines.__send__(:__age, age)
31
+ super
32
+ end
33
+ end
34
+ # Serve the cached value, stale. `revalidation` says who refreshes it: a
35
+ # Lead (you do), :in_flight (someone else is), a Backoff (nobody until then)
36
+ # or an Unavailable (a refresh is due but could not be registered).
37
+ Stale = Data.define(:age, :revalidation) do
38
+ def initialize(age:, revalidation:)
39
+ RefreshMachines.__send__(:__age, age)
40
+ RefreshMachines.__send__(:__revalidation, revalidation)
41
+ super
42
+ end
43
+ end
44
+ # Nothing servable: fetch, then report with `lease`, a lease id (its
45
+ # sequence, the low 48 bits, is never zero).
46
+ Fetch = Data.define(:lease) do
47
+ def initialize(lease:)
48
+ RefreshMachines.__send__(:__lease, lease)
49
+ super
50
+ end
51
+ end
52
+ # Nothing servable and someone is already fetching: park under the `waiter`
53
+ # id (issued after `flight`, in its scope). `flight` names the refresh being shared: what `Refresher#flight`
54
+ # answers for the key's live lease, and the `flight` of the notification to come.
55
+ Wait = Data.define(:waiter, :flight) do
56
+ def initialize(waiter:, flight:)
57
+ RefreshMachines.__send__(:__wait, waiter, flight)
58
+ super
59
+ end
60
+ end
61
+ # Stale#revalidation: refresh in the background and report with `lease`.
62
+ Lead = Data.define(:lease) do
63
+ def initialize(lease:)
64
+ RefreshMachines.__send__(:__lease, lease)
65
+ super
66
+ end
67
+ end
68
+ # Stale#revalidation: the last refresh failed and asked for quiet `until` then.
69
+ Backoff = Data.define(:until) do
70
+ def initialize(until:)
71
+ RefreshMachines.__send__(:__until, binding.local_variable_get(:until))
72
+ super
73
+ end
74
+ end
75
+ # Stale#revalidation: a refresh is due but was not registered; `refusal` is
76
+ # the reason, a refusal symbol. The decision is still honoured: serve the
77
+ # stale value.
78
+ Unavailable = Data.define(:refusal) do
79
+ def initialize(refusal:)
80
+ RefreshMachines.__send__(:__refusal, refusal)
81
+ super
82
+ end
83
+ end
84
+ # One waiter to wake. `flight` names the refresh that settled, see
85
+ # `Refresher#flight`; `waiter` is of its scope and issued after it.
86
+ # `outcome` is :completed or :abandoned.
87
+ Notification = Data.define(:waiter, :flight, :key, :outcome) do
88
+ def initialize(waiter:, flight:, key:, outcome:)
89
+ RefreshMachines.__send__(:__notification, waiter, flight, key, outcome)
90
+ super
91
+ end
92
+ end
93
+ end
94
+
95
+ # Native is required: no algorithm fallback. It validates and builds the Data
96
+ # values above and adds the Policy predicates, so they must exist first.
97
+ require 'refresh_machines_native/refresh_machines_native'
98
+
99
+ module RefreshMachines
100
+ private_class_method :__policy, :__age, :__until, :__lease, :__wait, :__notification, :__refusal, :__revalidation
101
+
102
+ # The values are sealed. `initialize` is where each validates, and a
103
+ # subclass could override it, or `allocate` build an instance that never ran
104
+ # it: subclassing raises TypeError and `allocate` is gone. Sealing stops
105
+ # accidents, not reflection (a named subclass's constant is bound before
106
+ # `inherited` raises; `Marshal.load` skips `initialize`), so the native side
107
+ # is the authority: a value it reads (a Policy, a Stale's revalidation) must
108
+ # be exactly its class, and its fields are checked again.
109
+ [Policy, Fresh, Stale, Fetch, Wait, Lead, Backoff, Unavailable, Notification].each do |value|
110
+ value.singleton_class.undef_method(:allocate)
111
+ value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
112
+ end
113
+ end
@@ -0,0 +1,179 @@
1
+ module RefreshMachines
2
+ VERSION: String
3
+
4
+ # Every instant (`now`, `Backoff#until`) and span (ages, policy windows,
5
+ # `lead_for`, `retry_after`) is Integer nanoseconds. A span argument must be
6
+ # in 0..2**64-1; a `now` argument may be anything in 0..Duration::MAX, so
7
+ # every instant the refresher answers (a `Backoff#until` past 2**64-1
8
+ # included) reads back as `now`. A returned sum may be larger than 2**64-1,
9
+ # up to the core's Duration::MAX; it never wraps.
10
+ #
11
+ # Every Data value validates when built, by the gem or by hand: TypeError
12
+ # for the wrong type, RangeError for a value the core rejects.
13
+ type state = :fresh | :stale | :expired
14
+ # Refusals: the call was not honoured and changed nothing. Every reason has
15
+ # its own symbol; there is no catch-all.
16
+ type refusal = :time_regressed | :zero_lead | :entries_full | :flights_full
17
+ | :waiters_full | :exhausted | :stale
18
+
19
+ # The scope (0..65_535) a lease, waiter or flight id was issued under: the
20
+ # top 16 bits. Use it to route an id to the refresher that issued it.
21
+ def self.scope_of: (Integer id) -> Integer
22
+
23
+ # Private native checks behind the Data values: TypeError for the wrong
24
+ # type, RangeError for a value the core rejects. The value-returning ones
25
+ # answer their argument unchanged.
26
+ private def self.__policy: (Integer fresh_for, Integer stale_while_revalidate, Integer stale_if_error) -> nil
27
+ private def self.__age: (Integer age) -> nil
28
+ private def self.__until: (Integer until_) -> nil
29
+ private def self.__lease: (Integer lease) -> Integer
30
+ private def self.__wait: (Integer waiter, Integer flight) -> nil
31
+ private def self.__notification: (Integer waiter, Integer flight, Integer key, Notification::outcome outcome) -> nil
32
+ private def self.__refusal: (refusal refusal) -> refusal
33
+ private def self.__revalidation: (revalidation revalidation) -> revalidation
34
+
35
+ class Policy < Data
36
+ attr_reader fresh_for: Integer
37
+ attr_reader stale_while_revalidate: Integer
38
+ attr_reader stale_if_error: Integer
39
+ def self.new: (Integer fresh_for, Integer stale_while_revalidate, Integer stale_if_error) -> Policy
40
+ | (fresh_for: Integer, stale_while_revalidate: Integer, stale_if_error: Integer) -> Policy
41
+ def state: (Integer age) -> state
42
+ def while_revalidate?: (Integer age) -> bool
43
+ def if_error?: (Integer age) -> bool
44
+ end
45
+
46
+ # Ages and instants answered by the core: Integer nanoseconds in
47
+ # 0..Duration::MAX (about 1.8e28).
48
+ class Fresh < Data
49
+ attr_reader age: Integer
50
+ def self.new: (Integer age) -> Fresh
51
+ | (age: Integer) -> Fresh
52
+ end
53
+
54
+ # Who refreshes a stale value that is being served.
55
+ type revalidation = Lead | :in_flight | Backoff | Unavailable
56
+
57
+ class Stale < Data
58
+ attr_reader age: Integer
59
+ attr_reader revalidation: revalidation
60
+ def self.new: (Integer age, revalidation revalidation) -> Stale
61
+ | (age: Integer, revalidation: revalidation) -> Stale
62
+ end
63
+
64
+ # Ids are Integers: lease ids, waiter ids and flight ids, all from the one
65
+ # sequence of their refresher, so no two ids of a refresher are equal. An id
66
+ # whose sequence (the low 48 bits) is zero raises RangeError, in a Data
67
+ # value and as an argument alike.
68
+ class Fetch < Data
69
+ attr_reader lease: Integer
70
+ def self.new: (Integer lease) -> Fetch
71
+ | (lease: Integer) -> Fetch
72
+ end
73
+
74
+ # The waiter is of the flight's scope and issued after it, else RangeError.
75
+ class Wait < Data
76
+ attr_reader waiter: Integer
77
+ attr_reader flight: Integer
78
+ def self.new: (Integer waiter, Integer flight) -> Wait
79
+ | (waiter: Integer, flight: Integer) -> Wait
80
+ end
81
+
82
+ class Lead < Data
83
+ attr_reader lease: Integer
84
+ def self.new: (Integer lease) -> Lead
85
+ | (lease: Integer) -> Lead
86
+ end
87
+
88
+ class Backoff < Data
89
+ attr_reader until: Integer
90
+ def self.new: (Integer until_) -> Backoff
91
+ | (until: Integer) -> Backoff
92
+ end
93
+
94
+ # Why the refresh was not registered: any refusal symbol (RangeError for
95
+ # another symbol). `decide` answers it with :flights_full or :exhausted.
96
+ class Unavailable < Data
97
+ attr_reader refusal: refusal
98
+ def self.new: (refusal refusal) -> Unavailable
99
+ | (refusal: refusal) -> Unavailable
100
+ end
101
+
102
+ # The waiter is of the flight's scope and issued after it, else RangeError.
103
+ class Notification < Data
104
+ type outcome = :completed | :abandoned
105
+
106
+ attr_reader waiter: Integer
107
+ attr_reader flight: Integer
108
+ attr_reader key: Integer
109
+ attr_reader outcome: outcome
110
+ def self.new: (Integer waiter, Integer flight, Integer key, outcome outcome) -> Notification
111
+ | (waiter: Integer, flight: Integer, key: Integer, outcome: outcome) -> Notification
112
+ end
113
+
114
+ class Refresher
115
+ CAPACITY: Integer
116
+ FLIGHT_CAPACITY: Integer
117
+ WAITER_CAPACITY: Integer
118
+
119
+ # Scope zero.
120
+ def self.new: () -> Refresher
121
+ # `scope` is an Integer in 0..65_535, carried in the top 16 bits of every id.
122
+ def self.with_scope: (Integer scope) -> Refresher
123
+ # Empty, at time zero, the id sequence continuing after `issued` (a saved
124
+ # `#issued`): the constructor for a restart. nil when `issued` is beyond
125
+ # the sequence (more than 2**48 - 1).
126
+ def self.resumed: (Integer scope, Integer issued) -> Refresher
127
+ def scope: () -> Integer
128
+ # Ids issued so far, of every kind (leases, waiter ids, flight ids, all
129
+ # from one sequence): the count to save for `resumed`.
130
+ def issued: () -> Integer
131
+ # Methods taking a lease or waiter id raise RangeError for a zero sequence,
132
+ # before the core is asked. Every honoured decide, store, fail, reap, put
133
+ # and sweep records `now` (each answer depends on it); a refusal records
134
+ # nothing.
135
+ # Honoured: Fresh, Stale, Fetch, Wait. Refused: :time_regressed, :zero_lead,
136
+ # and, only when nothing is servable, :flights_full, :waiters_full, :exhausted.
137
+ def decide: (Integer key, Integer now, Integer lead_for) -> (Fresh | Stale | Fetch | Wait | :time_regressed | :zero_lead | :flights_full | :waiters_full | :exhausted)
138
+ # Honoured: :stored. Refused: :time_regressed, :stale, :entries_full.
139
+ def store: (Integer lease, Integer now, Integer age, Policy policy) -> (:stored | :time_regressed | :stale | :entries_full)
140
+ # Honoured: the age of the value that covers for the failure, or nil when
141
+ # nothing does. Refused: :time_regressed, :stale.
142
+ def fail: (Integer lease, Integer now, Integer retry_after) -> (Integer | nil | :time_regressed | :stale)
143
+ # Honoured: :abandoned. Refused: :stale.
144
+ def abandon: (Integer lease) -> (:abandoned | :stale)
145
+ # Honoured: leases revoked. Refused: :time_regressed.
146
+ def reap: (Integer now) -> (Integer | :time_regressed)
147
+ # Honoured: :stored. Refused: :time_regressed, :entries_full.
148
+ def put: (Integer key, Integer now, Integer age, Policy policy) -> (:stored | :time_regressed | :entries_full)
149
+ # Honoured: :forgotten when there was metadata to drop, and the repeat
150
+ # :not_held when the key had none (nothing changes). Never refuses.
151
+ def forget: (Integer key) -> (:forgotten | :not_held)
152
+ # Honoured: at most `max` swept keys (a `max` past CAPACITY sweeps
153
+ # whatever is expired, which is never more). Refused: :time_regressed.
154
+ def sweep: (Integer now, Integer max) -> (Array[Integer] | :time_regressed)
155
+ # Honoured: :cancelled. Refused: :stale.
156
+ def cancel: (Integer waiter) -> (:cancelled | :stale)
157
+ # The oldest queued notification, or nil when nothing is queued. Never refuses.
158
+ def poll: () -> Notification?
159
+ # At most `max` queued notifications, oldest first (a `max` past
160
+ # WAITER_CAPACITY takes them all, which is never more). Never refuses.
161
+ def drain: (Integer max) -> Array[Notification]
162
+ def age: (Integer key, Integer now) -> Integer?
163
+ def state: (Integer key, Integer now) -> state?
164
+ def stale_if_error: (Integer key, Integer now) -> Integer?
165
+ def leading: (Integer key) -> Integer?
166
+ def flight: (Integer lease) -> Integer?
167
+ def now: () -> Integer
168
+ # Keys with metadata (the core's `len`).
169
+ def size: () -> Integer
170
+ # Whether no key has metadata (the core's `is_empty`).
171
+ def empty?: () -> bool
172
+ def in_flight: () -> Integer
173
+ def waiting: () -> Integer
174
+ def pending: () -> Integer
175
+ def capacity: () -> Integer
176
+ def flight_capacity: () -> Integer
177
+ def waiter_capacity: () -> Integer
178
+ end
179
+ end
metadata ADDED
@@ -0,0 +1,61 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: refresh_machines
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.7.3
5
+ platform: x86_64-darwin
6
+ authors:
7
+ - Abdelkader Boudih
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2026-11-16 00:00:00.000000000 Z
12
+ dependencies: []
13
+ description: Classifies cached values as fresh, stale or expired and grants one refresh
14
+ lease per key. Stores no values, fetches nothing and evicts nothing.
15
+ email:
16
+ - oss@seuros.com
17
+ executables: []
18
+ extensions: []
19
+ extra_rdoc_files: []
20
+ files:
21
+ - CHANGELOG.md
22
+ - LICENSE.txt
23
+ - README.md
24
+ - ext/refresh_machines_native/core/CHANGELOG.md
25
+ - ext/refresh_machines_native/core/README.md
26
+ - ext/refresh_machines_native/extconf.rb
27
+ - lib/refresh_machines.rb
28
+ - lib/refresh_machines/version.rb
29
+ - lib/refresh_machines_native/refresh_machines_native.bundle
30
+ - sig/refresh_machines.rbs
31
+ homepage: https://github.com/seuros/refresh_machines
32
+ licenses:
33
+ - MIT
34
+ metadata:
35
+ source_code_uri: https://github.com/seuros/refresh_machines
36
+ rubygems_mfa_required: 'true'
37
+ cargo_crate_name: refresh_machines_native
38
+ cargo_manifest_path: ext/refresh_machines_native/ffi/Cargo.toml
39
+ post_install_message:
40
+ rdoc_options: []
41
+ require_paths:
42
+ - lib
43
+ required_ruby_version: !ruby/object:Gem::Requirement
44
+ requirements:
45
+ - - ">="
46
+ - !ruby/object:Gem::Version
47
+ version: '4.0'
48
+ - - "<"
49
+ - !ruby/object:Gem::Version
50
+ version: 4.1.dev
51
+ required_rubygems_version: !ruby/object:Gem::Requirement
52
+ requirements:
53
+ - - ">="
54
+ - !ruby/object:Gem::Version
55
+ version: '0'
56
+ requirements: []
57
+ rubygems_version: 3.5.23
58
+ signing_key:
59
+ specification_version: 4
60
+ summary: Stale-while-revalidate and stale-if-error decisions for Ruby
61
+ test_files: []