request-scope.ts (14833B)
1 import { PUBLIC_REQUEST_BUDGETS } from '../config/budgets.ts'; 2 import type { RelayPolicy } from '../config/relays.ts'; 3 import { canonicalPublicKey } from '../contracts/public-key.ts'; 4 import { requireNip50Source } from './search-sources.ts'; 5 import { 6 createPublicIngress, 7 publicIngressStats, 8 type PublicIngress 9 } from './ingress.ts'; 10 import { 11 createObservationJournal, 12 closeObservationJournal, 13 publicObservations, 14 type ObservationJournal 15 } from '../catalog/observations.ts'; 16 import { 17 createPublicRequestResult, 18 createInboxRequestResult, 19 handlePublicRequestMessage, 20 publicRequestSnapshot, 21 disposePublicRequestResult, 22 type PublicRequestResult 23 } from './request-result.ts'; 24 import type { PublicPoolMessage } from './exports.ts'; 25 import type { VerifiedEnvelope } from './verified-envelope.ts'; 26 declare const schedulerBrand: unique symbol; 27 declare const runBrand: unique symbol; 28 declare const requestBrand: unique symbol; 29 export type PublicScheduler = Readonly<{ readonly [schedulerBrand]: true }>; 30 export type PublicRun = Readonly<{ readonly [runBrand]: true }>; 31 export type PublicRequest = Readonly<{ readonly [requestBrand]: true }>; 32 export type RequestKind = 'search' | 'head' | 'deletion' | 'profile' | 'inbox'; 33 export type RequestState = 34 'active' | 'eose' | 'partial' | 'cancelled' | 'deadline' | 'limit' | 'error'; 35 export interface RequestClock { 36 readonly now: () => number; 37 readonly schedule: (callback: () => void, delay: number) => () => void; 38 } 39 const browserClock: RequestClock = { 40 now: () => performance.now(), 41 schedule(callback, delay) { 42 const timer = setTimeout(() => callback(), delay); 43 return () => clearTimeout(timer); 44 } 45 }; 46 interface SchedulerOwner { 47 readonly now: () => number; 48 readonly sampledNow: () => number; 49 readonly schedule: RequestClock['schedule']; 50 readonly available: () => void; 51 readonly reserve: (token: PublicRequest, close: () => boolean) => void; 52 readonly release: (token: PublicRequest) => void; 53 readonly register: (token: PublicRun, dispose: () => boolean) => void; 54 readonly unregister: (token: PublicRun) => void; 55 readonly snapshot: () => Readonly<{ 56 activeRequests: number; 57 closed: boolean; 58 }>; 59 readonly close: () => void; 60 } 61 interface RunOwner { 62 readonly scheduler: SchedulerOwner; 63 readonly ingress: PublicIngress; 64 readonly journal: ObservationJournal; 65 readonly deadline: number; 66 readonly result: (request: PublicRequest) => PublicRequestResult; 67 readonly open: ( 68 kind: RequestKind, 69 open: (next: (message: PublicPoolMessage) => void) => () => void, 70 onVerified: (event: VerifiedEnvelope, inboxSource?: string) => void, 71 sampleSource?: string, 72 inboxAuthor?: string 73 ) => PublicRequest; 74 readonly active: () => boolean; 75 readonly currentAfterSample: () => boolean; 76 readonly snapshot: () => Readonly<{ 77 deadline: number; 78 active: boolean; 79 activeRequests: number; 80 ingress: ReturnType<typeof publicIngressStats>; 81 }>; 82 readonly cancel: () => boolean; 83 readonly dispose: () => boolean; 84 } 85 interface RequestOwner { 86 readonly run: PublicRun; 87 readonly result: PublicRequestResult; 88 readonly snapshot: () => Readonly<{ 89 kind: RequestKind; 90 deadline: number; 91 state: RequestState; 92 inboxSettled?: boolean; 93 result: ReturnType<typeof publicRequestSnapshot>; 94 }>; 95 readonly close: () => boolean; 96 } 97 const schedulers = new WeakMap<PublicScheduler, SchedulerOwner>(); 98 const runs = new WeakMap<PublicRun, RunOwner>(); 99 const requests = new WeakMap<PublicRequest, RequestOwner>(); 100 function schedulerOf(token: PublicScheduler): SchedulerOwner { 101 const owner = schedulers.get(token); 102 if (!owner) throw new Error('public_scheduler_invalid'); 103 return owner; 104 } 105 function runOf(token: PublicRun): RunOwner { 106 const owner = runs.get(token); 107 if (!owner) throw new Error('public_run_invalid'); 108 return owner; 109 } 110 function requestOf(token: PublicRequest): RequestOwner { 111 const owner = requests.get(token); 112 if (!owner) throw new Error('public_request_invalid'); 113 return owner; 114 } 115 export function createPublicScheduler( 116 clock: RequestClock = browserClock 117 ): PublicScheduler { 118 const active = new Map<PublicRequest, () => boolean>(), 119 registered = new Map<PublicRun, () => boolean>(); 120 let closed = false, 121 last = 0; 122 const owner: SchedulerOwner = { 123 now() { 124 const value = clock.now(); 125 if (!Number.isFinite(value) || value < 0) 126 throw new Error('public_clock_invalid'); 127 last = Math.max(last, value); 128 return last; 129 }, 130 sampledNow: () => last, 131 schedule: (callback, delay) => clock.schedule(callback, delay), 132 available() { 133 if (closed) throw new Error('public_scheduler_closed'); 134 }, 135 reserve(token, close) { 136 owner.available(); 137 if (active.size >= PUBLIC_REQUEST_BUDGETS.parallelScopes) 138 throw new Error('public_request_concurrency_limit'); 139 active.set(token, close); 140 }, 141 release(token) { 142 active.delete(token); 143 }, 144 register(token, dispose) { 145 owner.available(); 146 registered.set(token, dispose); 147 }, 148 unregister(token) { 149 registered.delete(token); 150 }, 151 snapshot() { 152 return { activeRequests: active.size, closed: closed }; 153 }, 154 close() { 155 closed = true; 156 let failed = false; 157 for (const dispose of registered.values()) if (!dispose()) failed = true; 158 for (const close of active.values()) if (!close()) failed = true; 159 if (failed) throw new Error('public_scheduler_close_failed'); 160 } 161 }; 162 const token = Object.freeze({}) as PublicScheduler; 163 schedulers.set(token, owner); 164 return token; 165 } 166 // One immutable run owns the aggregate event/byte budget and observation journal. 167 // All request kinds use the same admission owner; no per-auxiliary budget reset. 168 export function createPublicRun( 169 scheduler: PublicScheduler, 170 policy: RelayPolicy 171 ): PublicRun { 172 const shared = schedulerOf(scheduler); 173 shared.available(); 174 const deadline = shared.now() + PUBLIC_REQUEST_BUDGETS.runMilliseconds; 175 const ingress = createPublicIngress(), 176 journal = createObservationJournal(policy), 177 active = new Map<PublicRequest, () => boolean>(); 178 let cancelled = false, 179 disposed = false; 180 const token = Object.freeze({}) as PublicRun; 181 function cancel(): boolean { 182 cancelled = true; 183 let failed = false; 184 for (const close of active.values()) if (!close()) failed = true; 185 return !failed; 186 } 187 function dispose(): boolean { 188 const settled = cancel(); 189 disposed = true; 190 closeObservationJournal(journal); 191 if (settled) shared.unregister(token); 192 return settled; 193 } 194 const owner: RunOwner = { 195 scheduler: shared, 196 ingress, 197 journal, 198 deadline, 199 result(request) { 200 const row = requestOf(request); 201 if (row.run !== token) throw new Error('public_request_run_changed'); 202 return row.result; 203 }, 204 currentAfterSample: () => 205 !cancelled && 206 !disposed && 207 !shared.snapshot().closed && 208 shared.sampledNow() < deadline && 209 !publicIngressStats(ingress).stopped, 210 active: () => 211 !cancelled && 212 !disposed && 213 !shared.snapshot().closed && 214 shared.now() < deadline && 215 !publicIngressStats(ingress).stopped, 216 snapshot: () => ({ 217 deadline: deadline, 218 active: owner.active(), 219 activeRequests: active.size, 220 ingress: publicIngressStats(ingress) 221 }), 222 cancel, 223 dispose, 224 open(kind, open, onVerified, sampleSource, inboxAuthor) { 225 if (kind === 'inbox' && !canonicalPublicKey(inboxAuthor)) 226 throw new Error('inbox_author_invalid'); 227 if (kind !== 'inbox' && inboxAuthor !== undefined) 228 throw new Error('inbox_request_kind_invalid'); 229 if (sampleSource !== undefined) { 230 if (kind !== 'search') throw new Error('nip50_request_kind'); 231 requireNip50Source(policy, sampleSource); 232 } 233 shared.available(); 234 if (!owner.active()) throw new Error('public_run_inactive'); 235 if (!['search', 'head', 'deletion', 'profile', 'inbox'].includes(kind)) 236 throw new Error('public_request_kind_invalid'); 237 const request = Object.freeze({}) as PublicRequest; 238 const expires = Math.min( 239 deadline, 240 shared.now() + PUBLIC_REQUEST_BUDGETS.requestMilliseconds 241 ); 242 let state: RequestState = 'active', 243 opening = true, 244 cleanupComplete = false, 245 timerCancelled = false, 246 stopCompleted = false, 247 stop = () => {}, 248 cancelTimer = () => {}; 249 // Reserve before acquiring SDK subscriptions or scheduling their callbacks. 250 shared.reserve(request, () => finish('cancelled')); 251 let result: PublicRequestResult; 252 try { 253 result = 254 inboxAuthor === undefined 255 ? createPublicRequestResult(policy, ingress, journal, sampleSource) 256 : createInboxRequestResult(policy, ingress, journal, inboxAuthor); 257 } catch { 258 shared.release(request); 259 throw new Error('public_request_prepare_failed'); 260 } 261 function finish(next: Exclude<RequestState, 'active'>): boolean { 262 if (cleanupComplete) return true; 263 if (state === 'active') state = next; 264 disposePublicRequestResult(result); 265 let failed = false; 266 if (!timerCancelled) { 267 try { 268 cancelTimer(); 269 timerCancelled = true; 270 } catch { 271 failed = true; 272 } 273 } 274 if (!opening) { 275 if (!stopCompleted) { 276 try { 277 stop(); 278 stopCompleted = true; 279 } catch { 280 failed = true; 281 } 282 } 283 if (!failed && timerCancelled && stopCompleted) { 284 cleanupComplete = true; 285 active.delete(request); 286 shared.release(request); 287 } 288 } 289 return !failed; 290 } 291 active.set(request, () => finish('cancelled')); 292 requests.set(request, { 293 run: token, 294 result, 295 snapshot: () => ({ 296 kind: kind, 297 deadline: expires, 298 state: state, 299 ...(kind === 'inbox' ? { inboxSettled: cleanupComplete } : {}), 300 result: publicRequestSnapshot(result) 301 }), 302 close: () => finish('cancelled') 303 }); 304 function next(message: PublicPoolMessage): void { 305 if (state !== 'active') return; 306 try { 307 if (!owner.active()) { 308 finish(shared.now() >= deadline ? 'deadline' : 'cancelled'); 309 return; 310 } 311 if (shared.now() >= expires) { 312 finish('deadline'); 313 return; 314 } 315 } catch { 316 finish('error'); 317 return; 318 } 319 const outcome = handlePublicRequestMessage(result, message); 320 let callbackFailed = false; 321 if (outcome.status === 'accepted' || outcome.status === 'duplicate') { 322 try { 323 if (outcome.inboxSource === undefined) onVerified(outcome.value); 324 else onVerified(outcome.value, outcome.inboxSource); 325 } catch { 326 finish('error'); 327 callbackFailed = true; 328 } 329 } 330 if (publicIngressStats(ingress).stopped || outcome.status === 'limit') { 331 finish('limit'); 332 cancel(); 333 return; 334 } 335 if (callbackFailed) return; 336 const sources = publicRequestSnapshot(result).sources; 337 if ( 338 sources.length > 0 && 339 sources.every((row) => row.state !== 'pending') 340 ) 341 finish( 342 sources.every((row) => row.state === 'eose' && row.rejected === 0) 343 ? 'eose' 344 : 'partial' 345 ); 346 } 347 function expire(): void { 348 if (state !== 'active') return; 349 try { 350 const remaining = expires - shared.now(); 351 if (remaining > 0) { 352 cancelTimer = shared.schedule(() => expire(), remaining); 353 timerCancelled = false; 354 return; 355 } 356 finish('deadline'); 357 } catch { 358 finish('error'); 359 } 360 } 361 try { 362 cancelTimer = shared.schedule( 363 () => expire(), 364 Math.max(0, expires - shared.now()) 365 ); 366 // A trusted test scheduler may invoke synchronously before returning its 367 // control. Ensure the returned control is still settled before release. 368 timerCancelled = false; 369 if (state === 'active') stop = open(next); 370 opening = false; 371 if (state !== 'active') finish(state); 372 } catch { 373 opening = false; 374 finish('error'); 375 throw new Error('public_request_open_failed'); 376 } 377 return request; 378 } 379 }; 380 runs.set(token, owner); 381 shared.register(token, dispose); 382 return token; 383 } 384 export function openPublicRequest( 385 run: PublicRun, 386 kind: RequestKind, 387 open: (next: (message: PublicPoolMessage) => void) => () => void, 388 onVerified: (event: VerifiedEnvelope) => void, 389 sampleSource?: string 390 ): PublicRequest { 391 return runOf(run).open(kind, open, onVerified, sampleSource); 392 } 393 export function closePublicRequest(request: PublicRequest): void { 394 if (!requestOf(request).close()) 395 throw new Error('public_request_close_failed'); 396 } 397 export function openInboxRequest( 398 run: PublicRun, 399 author: unknown, 400 open: (next: (message: PublicPoolMessage) => void) => () => void, 401 onVerified: (event: VerifiedEnvelope, inboxSource?: string) => void 402 ): PublicRequest { 403 const key = canonicalPublicKey(author); 404 if (!key) throw new Error('inbox_author_invalid'); 405 return runOf(run).open('inbox', open, onVerified, undefined, key); 406 } 407 export function cancelPublicRun(run: PublicRun): void { 408 if (!runOf(run).cancel()) throw new Error('public_run_close_failed'); 409 } 410 export function disposePublicRun(run: PublicRun): void { 411 if (!runOf(run).dispose()) throw new Error('public_run_close_failed'); 412 } 413 export function closePublicScheduler(scheduler: PublicScheduler): void { 414 schedulerOf(scheduler).close(); 415 } 416 export function publicSchedulerSnapshot(scheduler: PublicScheduler) { 417 return schedulerOf(scheduler).snapshot(); 418 } 419 // Final fence after callers sample their relevant clocks. No external clock 420 // call or fresh wall-time promise: cached monotonic sample plus actual owners. 421 export function publicRunCurrentAfterSample(run: PublicRun): boolean { 422 return runOf(run).currentAfterSample(); 423 } 424 export function publicRunSnapshot(run: PublicRun) { 425 return runOf(run).snapshot(); 426 } 427 export function publicRequestScopeSnapshot(request: PublicRequest) { 428 return requestOf(request).snapshot(); 429 } 430 export function publicRunObservations(run: PublicRun, request: PublicRequest) { 431 const owner = runOf(run); 432 const result = owner.result(request); 433 return publicObservations( 434 owner.journal, 435 publicRequestSnapshot(result).context 436 ); 437 }