refresh_machines 0.7.3-aarch64-linux
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 +7 -0
- data/CHANGELOG.md +109 -0
- data/LICENSE.txt +21 -0
- data/README.md +352 -0
- data/ext/refresh_machines_native/core/CHANGELOG.md +77 -0
- data/ext/refresh_machines_native/core/README.md +175 -0
- data/ext/refresh_machines_native/extconf.rb +2 -0
- data/lib/refresh_machines/version.rb +5 -0
- data/lib/refresh_machines.rb +113 -0
- data/lib/refresh_machines_native/refresh_machines_native.so +0 -0
- data/sig/refresh_machines.rbs +179 -0
- metadata +61 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: e958110f59f842395f6b3831c2ce7c453c1d31d2dfef6c18419c419d818fd018
|
|
4
|
+
data.tar.gz: f2faf342ecf9d93bea4423a4c6f6861329f6f2330b1e7586316caf7580c59027
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 6104098753752f8c2c7fc21465ca836916a06577f43fcbf28dcc3084a7facd7588b4c1ae5dc16299e25dfdf7e571eab15159dd7368e6e981621e805a82645ec2
|
|
7
|
+
data.tar.gz: 7c51d605cff3fde612362512397443b61730cf186062d7fccd64ca2a74523f00cc5861c2856cf774dcfa295851b1408d52fe7124865aec8e1d9051b36198f74e
|
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,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
|
|
Binary file
|
|
@@ -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: aarch64-linux
|
|
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.so
|
|
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: []
|