@yolk-sdk/pool 0.0.0-stage → 0.1.0-canary.118
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.
- package/LICENSE +21 -0
- package/README.md +123 -2
- package/dist/index.d.mts +4 -0
- package/dist/index.mjs +4 -0
- package/dist/model.d.mts +58 -0
- package/dist/model.d.mts.map +1 -0
- package/dist/model.mjs +68 -0
- package/dist/model.mjs.map +1 -0
- package/dist/pool.d.mts +73 -0
- package/dist/pool.d.mts.map +1 -0
- package/dist/pool.mjs +290 -0
- package/dist/pool.mjs.map +1 -0
- package/dist/rank.d.mts +164 -0
- package/dist/rank.d.mts.map +1 -0
- package/dist/rank.mjs +139 -0
- package/dist/rank.mjs.map +1 -0
- package/dist/store.d.mts +89 -0
- package/dist/store.d.mts.map +1 -0
- package/dist/store.mjs +253 -0
- package/dist/store.mjs.map +1 -0
- package/package.json +59 -3
- package/src/index.ts +32 -0
- package/src/model.ts +81 -0
- package/src/pool.ts +570 -0
- package/src/rank.ts +307 -0
- package/src/store.ts +392 -0
package/src/rank.ts
ADDED
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
import { Data, Predicate } from 'effect'
|
|
2
|
+
import type { ProviderSubscriptionUsageSnapshot } from '@yolk-sdk/agent/providers/subscription-usage'
|
|
3
|
+
import type { PoolCooldown } from './model.ts'
|
|
4
|
+
|
|
5
|
+
/** One usage window of a reading, as the ranking reads it. */
|
|
6
|
+
export type PoolWindow = {
|
|
7
|
+
/** Window length; absent when the provider's window has no fixed length (a billing month). */
|
|
8
|
+
readonly durationMinutes?: number
|
|
9
|
+
readonly usedPercent: number
|
|
10
|
+
/** When the window resets; absent when it has not started. */
|
|
11
|
+
readonly resetsAtMs?: number
|
|
12
|
+
/** Lowercase model substrings the window limits; empty for every model. */
|
|
13
|
+
readonly models: ReadonlyArray<string>
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
type MutablePoolWindow = { -readonly [Key in keyof PoolWindow]: PoolWindow[Key] }
|
|
17
|
+
|
|
18
|
+
/** The latest quota reading of one account. */
|
|
19
|
+
export type PoolReading = {
|
|
20
|
+
readonly fetchedAtMs: number
|
|
21
|
+
readonly windows: ReadonlyArray<PoolWindow>
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** A configured account as the ranking sees it. */
|
|
25
|
+
export type PoolCandidate = {
|
|
26
|
+
readonly id: string
|
|
27
|
+
readonly priority: number
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* The route a request pins: its model id, trimmed and lowercased. Reasoning effort is a separate
|
|
32
|
+
* request field and never part of the route.
|
|
33
|
+
*/
|
|
34
|
+
export const poolRoute = (model: string) => model.trim().toLowerCase()
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* A usage snapshot as the ranking reads it; an unreadable `fetchedAt` yields no reading. Windows
|
|
38
|
+
* without a length still block a used-up account but never rank it. A window that reports only
|
|
39
|
+
* `resetsAfterSeconds` resets that long after the reading.
|
|
40
|
+
*/
|
|
41
|
+
export const poolReadingFromSnapshot = (
|
|
42
|
+
snapshot: ProviderSubscriptionUsageSnapshot
|
|
43
|
+
): PoolReading | undefined => {
|
|
44
|
+
const fetchedAtMs = Date.parse(snapshot.fetchedAt)
|
|
45
|
+
|
|
46
|
+
if (!Number.isFinite(fetchedAtMs)) {
|
|
47
|
+
return undefined
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const windows = Array.from(snapshot.windows).map((window): PoolWindow => {
|
|
51
|
+
const resetsAtMs =
|
|
52
|
+
window.resetsAt !== undefined
|
|
53
|
+
? Date.parse(window.resetsAt)
|
|
54
|
+
: window.resetsAfterSeconds !== undefined
|
|
55
|
+
? fetchedAtMs + window.resetsAfterSeconds * 1000
|
|
56
|
+
: Number.NaN
|
|
57
|
+
|
|
58
|
+
const models = (window.models ?? []).flatMap(model => {
|
|
59
|
+
const normalized = model.trim().toLowerCase()
|
|
60
|
+
|
|
61
|
+
return normalized === '' ? [] : [normalized]
|
|
62
|
+
})
|
|
63
|
+
|
|
64
|
+
const fields: MutablePoolWindow = { usedPercent: window.usedPercent, models }
|
|
65
|
+
|
|
66
|
+
if (window.windowDurationMinutes !== undefined) {
|
|
67
|
+
fields.durationMinutes = window.windowDurationMinutes
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
if (Number.isFinite(resetsAtMs)) {
|
|
71
|
+
fields.resetsAtMs = resetsAtMs
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
return fields
|
|
75
|
+
})
|
|
76
|
+
|
|
77
|
+
return { fetchedAtMs, windows }
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Why the ranking chose an account. */
|
|
81
|
+
export type PoolDecision = Data.TaggedEnum<{
|
|
82
|
+
/** Fresh readings ranked it first; `resetsAtMs` is its longest window's reset, if started. */
|
|
83
|
+
Quota: { readonly accountId: string; readonly resetsAtMs: number | undefined }
|
|
84
|
+
/** No candidate is usable by a fresh reading; the route's pin is still available. */
|
|
85
|
+
Sticky: { readonly accountId: string }
|
|
86
|
+
/** No candidate is usable by a fresh reading and no pin is: highest priority, then lowest id. */
|
|
87
|
+
FillFirst: { readonly accountId: string }
|
|
88
|
+
}>
|
|
89
|
+
|
|
90
|
+
export const PoolDecision = Data.taggedEnum<PoolDecision>()
|
|
91
|
+
|
|
92
|
+
export type PoolRankInput = {
|
|
93
|
+
/** Configured accounts. */
|
|
94
|
+
readonly accounts: ReadonlyArray<PoolCandidate>
|
|
95
|
+
/** Accounts that cannot serve now: an active cooldown, or already tried by this request. */
|
|
96
|
+
readonly unavailable: ReadonlySet<string>
|
|
97
|
+
readonly readings: ReadonlyMap<string, PoolReading>
|
|
98
|
+
/** The account the route is pinned to, if any. */
|
|
99
|
+
readonly pin: string | undefined
|
|
100
|
+
readonly route: string
|
|
101
|
+
readonly nowMs: number
|
|
102
|
+
readonly maxAgeMs: number
|
|
103
|
+
readonly reservePercent: number
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
const appliesTo = (window: PoolWindow, route: string) =>
|
|
107
|
+
window.models.length === 0 || window.models.some(model => route.includes(model))
|
|
108
|
+
|
|
109
|
+
const hasStarted = (window: PoolWindow, nowMs: number) =>
|
|
110
|
+
window.resetsAtMs !== undefined && window.resetsAtMs > nowMs
|
|
111
|
+
|
|
112
|
+
type AccountRank =
|
|
113
|
+
/** No window of the reading applies to the route: the reading says nothing. */
|
|
114
|
+
| { readonly kind: 'unknown' }
|
|
115
|
+
/** An applicable started window is used up to the reserve. */
|
|
116
|
+
| { readonly kind: 'exhausted' }
|
|
117
|
+
| { readonly kind: 'usable'; readonly resetsAtMs: number | undefined }
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* The reset of the account's longest window with a length that applies to the route (undefined
|
|
121
|
+
* when it has not started, or no applicable window has a length). Unusable when no window applies
|
|
122
|
+
* or an applicable started window is used up to the reserve; a window whose reset has passed counts
|
|
123
|
+
* as fresh, whatever the reading said.
|
|
124
|
+
*/
|
|
125
|
+
const accountRank = (
|
|
126
|
+
reading: PoolReading,
|
|
127
|
+
route: string,
|
|
128
|
+
nowMs: number,
|
|
129
|
+
reservePercent: number
|
|
130
|
+
): AccountRank => {
|
|
131
|
+
let usable = false
|
|
132
|
+
let longest = 0
|
|
133
|
+
let resetsAtMs: number | undefined
|
|
134
|
+
|
|
135
|
+
for (const window of reading.windows) {
|
|
136
|
+
if (!appliesTo(window, route)) {
|
|
137
|
+
continue
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
const started = hasStarted(window, nowMs)
|
|
141
|
+
|
|
142
|
+
if (started && window.usedPercent >= 100 - reservePercent) {
|
|
143
|
+
return { kind: 'exhausted' }
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
usable = true
|
|
147
|
+
|
|
148
|
+
if (window.durationMinutes === undefined) {
|
|
149
|
+
continue
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
if (window.durationMinutes > longest) {
|
|
153
|
+
longest = window.durationMinutes
|
|
154
|
+
resetsAtMs = started ? window.resetsAtMs : undefined
|
|
155
|
+
} else if (
|
|
156
|
+
window.durationMinutes === longest &&
|
|
157
|
+
started &&
|
|
158
|
+
window.resetsAtMs !== undefined &&
|
|
159
|
+
(resetsAtMs === undefined || window.resetsAtMs < resetsAtMs)
|
|
160
|
+
) {
|
|
161
|
+
resetsAtMs = window.resetsAtMs
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
return usable ? { kind: 'usable', resetsAtMs } : { kind: 'unknown' }
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
type Ranked = { readonly candidate: PoolCandidate; readonly resetsAtMs: number | undefined }
|
|
169
|
+
|
|
170
|
+
/** Code-unit id order, so ties never depend on locale. */
|
|
171
|
+
const idBefore = (a: string, b: string) => a < b
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* Started windows by soonest reset, then windows that have not started; ties by higher priority,
|
|
175
|
+
* then lower id.
|
|
176
|
+
*/
|
|
177
|
+
const ranksBefore = (a: Ranked, b: Ranked) => {
|
|
178
|
+
if (a.resetsAtMs !== undefined && b.resetsAtMs !== undefined) {
|
|
179
|
+
if (a.resetsAtMs !== b.resetsAtMs) {
|
|
180
|
+
return a.resetsAtMs < b.resetsAtMs
|
|
181
|
+
}
|
|
182
|
+
} else if (a.resetsAtMs !== undefined || b.resetsAtMs !== undefined) {
|
|
183
|
+
return a.resetsAtMs !== undefined
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
if (a.candidate.priority !== b.candidate.priority) {
|
|
187
|
+
return a.candidate.priority > b.candidate.priority
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
return idBefore(a.candidate.id, b.candidate.id)
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** Highest priority, then lowest id. */
|
|
194
|
+
const fillFirst = (candidates: ReadonlyArray<PoolCandidate>): PoolCandidate | undefined => {
|
|
195
|
+
let best: PoolCandidate | undefined
|
|
196
|
+
|
|
197
|
+
for (const candidate of candidates) {
|
|
198
|
+
if (
|
|
199
|
+
best === undefined ||
|
|
200
|
+
candidate.priority > best.priority ||
|
|
201
|
+
(candidate.priority === best.priority && idBefore(candidate.id, best.id))
|
|
202
|
+
) {
|
|
203
|
+
best = candidate
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
return best
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* Expiring-first: the available account whose longest applicable window resets soonest and still
|
|
212
|
+
* has quota. When no available account is usable by a fresh reading (within `maxAgeMs`), it routes
|
|
213
|
+
* stickily: the pin while it is available, else fill-first, preferring accounts that no fresh
|
|
214
|
+
* reading shows used up; those serve only when nothing else is left, so the provider's own answer
|
|
215
|
+
* decides. Undefined when no account is available.
|
|
216
|
+
*/
|
|
217
|
+
export const rankPool = (input: PoolRankInput): PoolDecision | undefined => {
|
|
218
|
+
const candidates = input.accounts.filter(account => !input.unavailable.has(account.id))
|
|
219
|
+
const exhausted = new Set<string>()
|
|
220
|
+
|
|
221
|
+
let best: Ranked | undefined
|
|
222
|
+
|
|
223
|
+
for (const candidate of candidates) {
|
|
224
|
+
const reading = input.readings.get(candidate.id)
|
|
225
|
+
|
|
226
|
+
if (reading === undefined || input.nowMs - reading.fetchedAtMs > input.maxAgeMs) {
|
|
227
|
+
continue
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
const rank = accountRank(reading, input.route, input.nowMs, input.reservePercent)
|
|
231
|
+
|
|
232
|
+
if (rank.kind === 'exhausted') {
|
|
233
|
+
exhausted.add(candidate.id)
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
if (rank.kind !== 'usable') {
|
|
237
|
+
continue
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
const next: Ranked = { candidate, resetsAtMs: rank.resetsAtMs }
|
|
241
|
+
|
|
242
|
+
if (best === undefined || ranksBefore(next, best)) {
|
|
243
|
+
best = next
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
if (best !== undefined) {
|
|
248
|
+
return PoolDecision.Quota({ accountId: best.candidate.id, resetsAtMs: best.resetsAtMs })
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
const unexhausted = candidates.filter(candidate => !exhausted.has(candidate.id))
|
|
252
|
+
const fallback = unexhausted.length > 0 ? unexhausted : candidates
|
|
253
|
+
|
|
254
|
+
if (input.pin !== undefined && fallback.some(candidate => candidate.id === input.pin)) {
|
|
255
|
+
return PoolDecision.Sticky({ accountId: input.pin })
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
const first = fillFirst(fallback)
|
|
259
|
+
|
|
260
|
+
return first === undefined ? undefined : PoolDecision.FillFirst({ accountId: first.id })
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/** Whether a cooldown still keeps its account out at `nowMs`. */
|
|
264
|
+
export const isCooldownActive = (cooldown: PoolCooldown, nowMs: number) => cooldown.untilMs > nowMs
|
|
265
|
+
|
|
266
|
+
/**
|
|
267
|
+
* Every account-wide window of the reading has quota left or has reset; model-scoped windows block
|
|
268
|
+
* only their models through ranking, never the whole account. A reading without account-wide
|
|
269
|
+
* windows proves nothing.
|
|
270
|
+
*/
|
|
271
|
+
const hasQuotaLeft = (reading: PoolReading, nowMs: number) => {
|
|
272
|
+
const accountWide = reading.windows.filter(window => window.models.length === 0)
|
|
273
|
+
|
|
274
|
+
return (
|
|
275
|
+
accountWide.length > 0 &&
|
|
276
|
+
accountWide.every(window => !hasStarted(window, nowMs) || window.usedPercent < 100)
|
|
277
|
+
)
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/**
|
|
281
|
+
* Active quota cooldowns that a fresh reading taken after they began shows to be over (a limit
|
|
282
|
+
* reset was spent, or the provider reset early). A reading from before the lockout never clears
|
|
283
|
+
* one, and auth cooldowns are never cleared by readings.
|
|
284
|
+
*/
|
|
285
|
+
export const staleQuotaCooldowns = (input: {
|
|
286
|
+
readonly cooldowns: ReadonlyArray<PoolCooldown>
|
|
287
|
+
readonly readings: ReadonlyMap<string, PoolReading>
|
|
288
|
+
readonly nowMs: number
|
|
289
|
+
readonly maxAgeMs: number
|
|
290
|
+
}): ReadonlyArray<PoolCooldown> =>
|
|
291
|
+
input.cooldowns.filter(cooldown => {
|
|
292
|
+
if (
|
|
293
|
+
!Predicate.isTagged(cooldown, 'PoolQuotaCooldown') ||
|
|
294
|
+
!isCooldownActive(cooldown, input.nowMs)
|
|
295
|
+
) {
|
|
296
|
+
return false
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
const reading = input.readings.get(cooldown.accountId)
|
|
300
|
+
|
|
301
|
+
return (
|
|
302
|
+
reading !== undefined &&
|
|
303
|
+
input.nowMs - reading.fetchedAtMs <= input.maxAgeMs &&
|
|
304
|
+
reading.fetchedAtMs > cooldown.startedAtMs &&
|
|
305
|
+
hasQuotaLeft(reading, input.nowMs)
|
|
306
|
+
)
|
|
307
|
+
})
|
package/src/store.ts
ADDED
|
@@ -0,0 +1,392 @@
|
|
|
1
|
+
import { Chunk, Effect, Predicate } from 'effect'
|
|
2
|
+
import * as Schema from 'effect/Schema'
|
|
3
|
+
import { ProviderSubscriptionUsageSnapshot } from '@yolk-sdk/agent/providers/subscription-usage'
|
|
4
|
+
import {
|
|
5
|
+
PoolAccountId,
|
|
6
|
+
PoolAuthCooldown,
|
|
7
|
+
PoolPin,
|
|
8
|
+
PoolQuotaCooldown,
|
|
9
|
+
type PoolCooldown,
|
|
10
|
+
type PoolStoreError
|
|
11
|
+
} from './model.ts'
|
|
12
|
+
|
|
13
|
+
export { PoolStoreError } from './model.ts'
|
|
14
|
+
|
|
15
|
+
/** The latest usage snapshot of one account. */
|
|
16
|
+
export class PoolStoredReading extends Schema.Class<PoolStoredReading>('PoolStoredReading')({
|
|
17
|
+
accountId: PoolAccountId,
|
|
18
|
+
snapshot: ProviderSubscriptionUsageSnapshot
|
|
19
|
+
}) {}
|
|
20
|
+
|
|
21
|
+
/** What one pick reads: the route's pin plus the cooldowns and readings of the pool's accounts. */
|
|
22
|
+
export type PoolStoreSnapshot = {
|
|
23
|
+
readonly pin: PoolPin | undefined
|
|
24
|
+
readonly cooldowns: ReadonlyArray<PoolCooldown>
|
|
25
|
+
readonly readings: ReadonlyArray<PoolStoredReading>
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Everything a store holds for one pool, for host UIs. */
|
|
29
|
+
export type PoolStoreState = {
|
|
30
|
+
readonly pins: ReadonlyArray<PoolPin>
|
|
31
|
+
readonly cooldowns: ReadonlyArray<PoolCooldown>
|
|
32
|
+
readonly readings: ReadonlyArray<PoolStoredReading>
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Pool state shared by every instance of a host (ADR 0011). Hosts implement it on their database;
|
|
37
|
+
* `makeMemoryPoolStore` serves tests and single-process hosts, and `poolStoreContract` pins the
|
|
38
|
+
* semantics every implementation must meet.
|
|
39
|
+
*
|
|
40
|
+
* - Pins are keyed by `(poolId, route)`; cooldowns and readings by account id, so a cooldown or
|
|
41
|
+
* reading applies to every pool the account is in.
|
|
42
|
+
* - Operations must be atomic per key: concurrent `movePin` calls with the same `expected` let
|
|
43
|
+
* exactly one through.
|
|
44
|
+
*/
|
|
45
|
+
export type PoolStoreApi = {
|
|
46
|
+
/** The route's pin and the requested accounts' cooldowns (expired ones included) and readings. */
|
|
47
|
+
readonly load: (input: {
|
|
48
|
+
readonly poolId: string
|
|
49
|
+
readonly route: string
|
|
50
|
+
readonly accountIds: ReadonlyArray<string>
|
|
51
|
+
}) => Effect.Effect<PoolStoreSnapshot, PoolStoreError>
|
|
52
|
+
/**
|
|
53
|
+
* Compare-and-set: writes `pin` when the route's current account is `expected` (`undefined`:
|
|
54
|
+
* the route has no pin yet). Returns whether it wrote.
|
|
55
|
+
*/
|
|
56
|
+
readonly movePin: (input: {
|
|
57
|
+
readonly expected: string | undefined
|
|
58
|
+
readonly pin: PoolPin
|
|
59
|
+
}) => Effect.Effect<boolean, PoolStoreError>
|
|
60
|
+
/**
|
|
61
|
+
* Records a cooldown; when the account already has one, the one that ends later stays, and of two
|
|
62
|
+
* that end together the one that started later (a newer failure must not be cleared by a reading
|
|
63
|
+
* taken before it).
|
|
64
|
+
*/
|
|
65
|
+
readonly putCooldown: (cooldown: PoolCooldown) => Effect.Effect<void, PoolStoreError>
|
|
66
|
+
/**
|
|
67
|
+
* Removes the account's cooldown only when it is the one observed (same `startedAtMs`). Returns
|
|
68
|
+
* whether it removed one.
|
|
69
|
+
*/
|
|
70
|
+
readonly clearCooldown: (input: {
|
|
71
|
+
readonly accountId: string
|
|
72
|
+
readonly startedAtMs: number
|
|
73
|
+
}) => Effect.Effect<boolean, PoolStoreError>
|
|
74
|
+
/** Records a reading unless the stored one was fetched later. */
|
|
75
|
+
readonly putReading: (reading: PoolStoredReading) => Effect.Effect<void, PoolStoreError>
|
|
76
|
+
/** The pool's pins and the requested accounts' cooldowns and readings. */
|
|
77
|
+
readonly state: (input: {
|
|
78
|
+
readonly poolId: string
|
|
79
|
+
readonly accountIds: ReadonlyArray<string>
|
|
80
|
+
}) => Effect.Effect<PoolStoreState, PoolStoreError>
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
const pinKey = (poolId: string, route: string) => JSON.stringify([poolId, route])
|
|
84
|
+
|
|
85
|
+
const fetchedAtMs = (reading: PoolStoredReading) => Date.parse(reading.snapshot.fetchedAt)
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* An in-memory `PoolStoreApi`: state lives in this process only, so it suits tests and hosts that
|
|
89
|
+
* run one long-lived process. Serverless hosts implement the port on their database.
|
|
90
|
+
*/
|
|
91
|
+
export const makeMemoryPoolStore = (): PoolStoreApi => {
|
|
92
|
+
const pins = new Map<string, PoolPin>()
|
|
93
|
+
const cooldowns = new Map<string, PoolCooldown>()
|
|
94
|
+
const readings = new Map<string, PoolStoredReading>()
|
|
95
|
+
|
|
96
|
+
const pick = <A>(source: Map<string, A>, accountIds: ReadonlyArray<string>) =>
|
|
97
|
+
accountIds.flatMap(accountId => {
|
|
98
|
+
const value = source.get(accountId)
|
|
99
|
+
|
|
100
|
+
return value === undefined ? [] : [value]
|
|
101
|
+
})
|
|
102
|
+
|
|
103
|
+
return {
|
|
104
|
+
load: input =>
|
|
105
|
+
Effect.sync(() => ({
|
|
106
|
+
pin: pins.get(pinKey(input.poolId, input.route)),
|
|
107
|
+
cooldowns: pick(cooldowns, input.accountIds),
|
|
108
|
+
readings: pick(readings, input.accountIds)
|
|
109
|
+
})),
|
|
110
|
+
movePin: input =>
|
|
111
|
+
Effect.sync(() => {
|
|
112
|
+
const key = pinKey(input.pin.poolId, input.pin.route)
|
|
113
|
+
|
|
114
|
+
if (pins.get(key)?.accountId !== input.expected) {
|
|
115
|
+
return false
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
pins.set(key, input.pin)
|
|
119
|
+
|
|
120
|
+
return true
|
|
121
|
+
}),
|
|
122
|
+
putCooldown: cooldown =>
|
|
123
|
+
Effect.sync(() => {
|
|
124
|
+
const current = cooldowns.get(cooldown.accountId)
|
|
125
|
+
|
|
126
|
+
if (
|
|
127
|
+
current === undefined ||
|
|
128
|
+
cooldown.untilMs > current.untilMs ||
|
|
129
|
+
(cooldown.untilMs === current.untilMs && cooldown.startedAtMs > current.startedAtMs)
|
|
130
|
+
) {
|
|
131
|
+
cooldowns.set(cooldown.accountId, cooldown)
|
|
132
|
+
}
|
|
133
|
+
}),
|
|
134
|
+
clearCooldown: input =>
|
|
135
|
+
Effect.sync(() => {
|
|
136
|
+
const current = cooldowns.get(input.accountId)
|
|
137
|
+
|
|
138
|
+
if (current === undefined || current.startedAtMs !== input.startedAtMs) {
|
|
139
|
+
return false
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
cooldowns.delete(input.accountId)
|
|
143
|
+
|
|
144
|
+
return true
|
|
145
|
+
}),
|
|
146
|
+
putReading: reading =>
|
|
147
|
+
Effect.sync(() => {
|
|
148
|
+
const current = readings.get(reading.accountId)
|
|
149
|
+
|
|
150
|
+
if (current === undefined || fetchedAtMs(reading) >= fetchedAtMs(current)) {
|
|
151
|
+
readings.set(reading.accountId, reading)
|
|
152
|
+
}
|
|
153
|
+
}),
|
|
154
|
+
state: input =>
|
|
155
|
+
Effect.sync(() => ({
|
|
156
|
+
pins: Array.from(pins.values())
|
|
157
|
+
.filter(pin => pin.poolId === input.poolId)
|
|
158
|
+
.sort((a, b) => (a.route < b.route ? -1 : a.route > b.route ? 1 : 0)),
|
|
159
|
+
cooldowns: pick(cooldowns, input.accountIds),
|
|
160
|
+
readings: pick(readings, input.accountIds)
|
|
161
|
+
}))
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** A `PoolStoreApi` implementation broke the store contract. */
|
|
166
|
+
export class PoolStoreContractViolation extends Schema.TaggedError<PoolStoreContractViolation>()(
|
|
167
|
+
'PoolStoreContractViolation',
|
|
168
|
+
{
|
|
169
|
+
case: Schema.String,
|
|
170
|
+
message: Schema.String
|
|
171
|
+
}
|
|
172
|
+
) {}
|
|
173
|
+
|
|
174
|
+
/** One semantic every `PoolStoreApi` must meet. Run each case against a fresh, empty store. */
|
|
175
|
+
export type PoolStoreContractCase = {
|
|
176
|
+
readonly name: string
|
|
177
|
+
readonly run: (
|
|
178
|
+
store: PoolStoreApi
|
|
179
|
+
) => Effect.Effect<void, PoolStoreContractViolation | PoolStoreError>
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
const contractCase = (
|
|
183
|
+
name: string,
|
|
184
|
+
run: (
|
|
185
|
+
store: PoolStoreApi,
|
|
186
|
+
expect: (condition: boolean, message: string) => Effect.Effect<void, PoolStoreContractViolation>
|
|
187
|
+
) => Effect.Effect<void, PoolStoreContractViolation | PoolStoreError>
|
|
188
|
+
): PoolStoreContractCase => ({
|
|
189
|
+
name,
|
|
190
|
+
run: store =>
|
|
191
|
+
run(store, (condition, message) =>
|
|
192
|
+
condition ? Effect.void : Effect.fail(new PoolStoreContractViolation({ case: name, message }))
|
|
193
|
+
)
|
|
194
|
+
})
|
|
195
|
+
|
|
196
|
+
const contractPin = (route: string, accountId: string, pinnedAtMs: number, poolId = 'pool') =>
|
|
197
|
+
PoolPin.make({ poolId, route, accountId, pinnedAtMs })
|
|
198
|
+
|
|
199
|
+
const contractReading = (accountId: string, fetchedAt: string) =>
|
|
200
|
+
PoolStoredReading.make({
|
|
201
|
+
accountId,
|
|
202
|
+
snapshot: ProviderSubscriptionUsageSnapshot.make({
|
|
203
|
+
provider: 'contract',
|
|
204
|
+
fetchedAt,
|
|
205
|
+
windows: Chunk.empty()
|
|
206
|
+
})
|
|
207
|
+
})
|
|
208
|
+
|
|
209
|
+
/** The `PoolStoreApi` contract. Hosts run every case against a fresh store of their implementation. */
|
|
210
|
+
export const poolStoreContract: ReadonlyArray<PoolStoreContractCase> = [
|
|
211
|
+
contractCase('pins are created once and moved by compare-and-set', (store, expect) =>
|
|
212
|
+
Effect.gen(function* () {
|
|
213
|
+
const load = store.load({ poolId: 'pool', route: 'model', accountIds: [] })
|
|
214
|
+
|
|
215
|
+
yield* expect((yield* load).pin === undefined, 'a new route has no pin')
|
|
216
|
+
yield* expect(
|
|
217
|
+
yield* store.movePin({ expected: undefined, pin: contractPin('model', 'a', 1) }),
|
|
218
|
+
'the first pin is written'
|
|
219
|
+
)
|
|
220
|
+
yield* expect(
|
|
221
|
+
!(yield* store.movePin({ expected: undefined, pin: contractPin('model', 'b', 2) })),
|
|
222
|
+
'creating a pin that already exists is refused'
|
|
223
|
+
)
|
|
224
|
+
yield* expect(
|
|
225
|
+
!(yield* store.movePin({ expected: 'b', pin: contractPin('model', 'c', 3) })),
|
|
226
|
+
'a move expecting another account is refused'
|
|
227
|
+
)
|
|
228
|
+
yield* expect(
|
|
229
|
+
yield* store.movePin({ expected: 'a', pin: contractPin('model', 'b', 4) }),
|
|
230
|
+
'a move expecting the current account is written'
|
|
231
|
+
)
|
|
232
|
+
|
|
233
|
+
const pin = (yield* load).pin
|
|
234
|
+
|
|
235
|
+
yield* expect(
|
|
236
|
+
pin?.accountId === 'b' && pin.pinnedAtMs === 4,
|
|
237
|
+
'load returns the latest pin with its time'
|
|
238
|
+
)
|
|
239
|
+
})
|
|
240
|
+
),
|
|
241
|
+
contractCase('pins are keyed by pool and route', (store, expect) =>
|
|
242
|
+
Effect.gen(function* () {
|
|
243
|
+
yield* store.movePin({ expected: undefined, pin: contractPin('one', 'a', 1) })
|
|
244
|
+
yield* store.movePin({ expected: undefined, pin: contractPin('two', 'b', 1) })
|
|
245
|
+
yield* store.movePin({ expected: undefined, pin: contractPin('one', 'c', 1, 'other') })
|
|
246
|
+
|
|
247
|
+
const one = yield* store.load({ poolId: 'pool', route: 'one', accountIds: [] })
|
|
248
|
+
const two = yield* store.load({ poolId: 'pool', route: 'two', accountIds: [] })
|
|
249
|
+
const other = yield* store.load({ poolId: 'other', route: 'one', accountIds: [] })
|
|
250
|
+
|
|
251
|
+
yield* expect(
|
|
252
|
+
one.pin?.accountId === 'a' && two.pin?.accountId === 'b' && other.pin?.accountId === 'c',
|
|
253
|
+
'each (pool, route) keeps its own pin'
|
|
254
|
+
)
|
|
255
|
+
|
|
256
|
+
const state = yield* store.state({ poolId: 'pool', accountIds: [] })
|
|
257
|
+
|
|
258
|
+
yield* expect(
|
|
259
|
+
state.pins.map(pin => pin.route).join() === 'one,two',
|
|
260
|
+
'state lists the pool’s pins only, ordered by route'
|
|
261
|
+
)
|
|
262
|
+
})
|
|
263
|
+
),
|
|
264
|
+
contractCase('concurrent moves from the same pin let exactly one through', (store, expect) =>
|
|
265
|
+
Effect.gen(function* () {
|
|
266
|
+
yield* store.movePin({ expected: undefined, pin: contractPin('model', 'a', 1) })
|
|
267
|
+
|
|
268
|
+
const results = yield* Effect.all(
|
|
269
|
+
['b', 'c', 'd', 'e'].map(accountId =>
|
|
270
|
+
store.movePin({ expected: 'a', pin: contractPin('model', accountId, 2) })
|
|
271
|
+
),
|
|
272
|
+
{ concurrency: 'unbounded' }
|
|
273
|
+
)
|
|
274
|
+
|
|
275
|
+
yield* expect(results.filter(Boolean).length === 1, 'exactly one move is written')
|
|
276
|
+
})
|
|
277
|
+
),
|
|
278
|
+
contractCase('cooldowns keep the later end and clear only when observed', (store, expect) =>
|
|
279
|
+
Effect.gen(function* () {
|
|
280
|
+
const load = store.load({ poolId: 'pool', route: 'model', accountIds: ['a', 'b'] })
|
|
281
|
+
|
|
282
|
+
yield* store.putCooldown(
|
|
283
|
+
PoolQuotaCooldown.make({ accountId: 'a', startedAtMs: 1, untilMs: 100 })
|
|
284
|
+
)
|
|
285
|
+
yield* store.putCooldown(
|
|
286
|
+
PoolAuthCooldown.make({ accountId: 'a', startedAtMs: 2, untilMs: 50 })
|
|
287
|
+
)
|
|
288
|
+
|
|
289
|
+
const kept = (yield* load).cooldowns
|
|
290
|
+
|
|
291
|
+
yield* expect(
|
|
292
|
+
kept.length === 1 &&
|
|
293
|
+
Predicate.isTagged(kept[0], 'PoolQuotaCooldown') &&
|
|
294
|
+
kept[0].untilMs === 100,
|
|
295
|
+
'an earlier-ending cooldown does not replace a later one'
|
|
296
|
+
)
|
|
297
|
+
|
|
298
|
+
yield* store.putCooldown(
|
|
299
|
+
PoolAuthCooldown.make({ accountId: 'a', startedAtMs: 3, untilMs: 200 })
|
|
300
|
+
)
|
|
301
|
+
|
|
302
|
+
const replaced = (yield* load).cooldowns
|
|
303
|
+
|
|
304
|
+
yield* expect(
|
|
305
|
+
replaced.length === 1 &&
|
|
306
|
+
Predicate.isTagged(replaced[0], 'PoolAuthCooldown') &&
|
|
307
|
+
replaced[0].startedAtMs === 3,
|
|
308
|
+
'a later-ending cooldown replaces the current one'
|
|
309
|
+
)
|
|
310
|
+
|
|
311
|
+
yield* store.putCooldown(
|
|
312
|
+
PoolQuotaCooldown.make({ accountId: 'a', startedAtMs: 4, untilMs: 200 })
|
|
313
|
+
)
|
|
314
|
+
|
|
315
|
+
yield* store.putCooldown(
|
|
316
|
+
PoolQuotaCooldown.make({ accountId: 'a', startedAtMs: 2, untilMs: 200 })
|
|
317
|
+
)
|
|
318
|
+
|
|
319
|
+
const renewed = (yield* load).cooldowns
|
|
320
|
+
|
|
321
|
+
yield* expect(
|
|
322
|
+
renewed.length === 1 && renewed[0]?.startedAtMs === 4,
|
|
323
|
+
'of two cooldowns that end together, the later-started one stays, whatever the write order'
|
|
324
|
+
)
|
|
325
|
+
yield* expect(
|
|
326
|
+
!(yield* store.clearCooldown({ accountId: 'a', startedAtMs: 3 })),
|
|
327
|
+
'clearing a cooldown that is no longer current is refused'
|
|
328
|
+
)
|
|
329
|
+
yield* expect(
|
|
330
|
+
yield* store.clearCooldown({ accountId: 'a', startedAtMs: 4 }),
|
|
331
|
+
'clearing the observed cooldown succeeds'
|
|
332
|
+
)
|
|
333
|
+
yield* expect((yield* load).cooldowns.length === 0, 'a cleared cooldown is gone')
|
|
334
|
+
yield* expect(
|
|
335
|
+
!(yield* store.clearCooldown({ accountId: 'b', startedAtMs: 3 })),
|
|
336
|
+
'clearing an account without a cooldown is refused'
|
|
337
|
+
)
|
|
338
|
+
})
|
|
339
|
+
),
|
|
340
|
+
contractCase(
|
|
341
|
+
'cooldowns and readings are returned for the requested accounts only',
|
|
342
|
+
(store, expect) =>
|
|
343
|
+
Effect.gen(function* () {
|
|
344
|
+
yield* store.putCooldown(
|
|
345
|
+
PoolQuotaCooldown.make({ accountId: 'a', startedAtMs: 1, untilMs: 9 })
|
|
346
|
+
)
|
|
347
|
+
yield* store.putCooldown(
|
|
348
|
+
PoolQuotaCooldown.make({ accountId: 'b', startedAtMs: 1, untilMs: 9 })
|
|
349
|
+
)
|
|
350
|
+
yield* store.putReading(contractReading('a', '2026-10-15T12:00:00.000Z'))
|
|
351
|
+
yield* store.putReading(contractReading('b', '2026-10-15T12:00:00.000Z'))
|
|
352
|
+
|
|
353
|
+
const snapshot = yield* store.load({ poolId: 'pool', route: 'model', accountIds: ['b'] })
|
|
354
|
+
const state = yield* store.state({ poolId: 'pool', accountIds: ['a'] })
|
|
355
|
+
|
|
356
|
+
yield* expect(
|
|
357
|
+
snapshot.cooldowns.every(cooldown => cooldown.accountId === 'b') &&
|
|
358
|
+
snapshot.cooldowns.length === 1 &&
|
|
359
|
+
snapshot.readings.every(reading => reading.accountId === 'b') &&
|
|
360
|
+
snapshot.readings.length === 1,
|
|
361
|
+
'load filters by account'
|
|
362
|
+
)
|
|
363
|
+
yield* expect(
|
|
364
|
+
state.cooldowns.length === 1 &&
|
|
365
|
+
state.cooldowns[0]?.accountId === 'a' &&
|
|
366
|
+
state.readings.length === 1 &&
|
|
367
|
+
state.readings[0]?.accountId === 'a',
|
|
368
|
+
'state filters by account'
|
|
369
|
+
)
|
|
370
|
+
})
|
|
371
|
+
),
|
|
372
|
+
contractCase('readings keep the latest fetch', (store, expect) =>
|
|
373
|
+
Effect.gen(function* () {
|
|
374
|
+
const load = store.load({ poolId: 'pool', route: 'model', accountIds: ['a'] })
|
|
375
|
+
|
|
376
|
+
yield* store.putReading(contractReading('a', '2026-10-15T12:00:00.000Z'))
|
|
377
|
+
yield* store.putReading(contractReading('a', '2026-10-15T11:00:00.000Z'))
|
|
378
|
+
|
|
379
|
+
yield* expect(
|
|
380
|
+
(yield* load).readings[0]?.snapshot.fetchedAt === '2026-10-15T12:00:00.000Z',
|
|
381
|
+
'an older reading does not replace a newer one'
|
|
382
|
+
)
|
|
383
|
+
|
|
384
|
+
yield* store.putReading(contractReading('a', '2026-10-15T13:00:00.000Z'))
|
|
385
|
+
|
|
386
|
+
yield* expect(
|
|
387
|
+
(yield* load).readings[0]?.snapshot.fetchedAt === '2026-10-15T13:00:00.000Z',
|
|
388
|
+
'a newer reading replaces the stored one'
|
|
389
|
+
)
|
|
390
|
+
})
|
|
391
|
+
)
|
|
392
|
+
]
|