public-pool.ts (19139B)
1 import { createScopedRelayPool } from './pool-factory.ts'; 2 import { deploymentRelayPolicy } from '../config/deployment-relays.ts'; 3 import { 4 publicRelayTargets, 5 readRelayPolicy, 6 type RelayPolicy 7 } from '../config/relays.ts'; 8 import type { PublicFilter, PublicPoolMessage } from './exports.ts'; 9 import { requireNip50Source } from './search-sources.ts'; 10 import { 11 takePreferencePublication, 12 type PreferencePublication 13 } from './inbox-preference-publication.ts'; 14 import { 15 takeListingPublication, 16 type ListingAttemptPermission 17 } from './listing-publisher.ts'; 18 import { 19 verifyEnvelope, 20 verifiedEnvelopeSnapshot 21 } from './verified-envelope.ts'; 22 export type ListingReadbackResult = 23 | Readonly<{ status: 'found'; wire: string }> 24 | Readonly<{ status: 'missing' | 'unknown' | 'stopped' }>; 25 export type PreferenceAttemptResult = Readonly<{ 26 status: 'accepted' | 'refused' | 'timed_out' | 'unknown' | 'stopped'; 27 }>; 28 29 declare const ownedPool: unique symbol; 30 export type PublicPool = Readonly<{ readonly [ownedPool]: true }>; 31 interface Owner { 32 readonly policy: RelayPolicy; 33 readonly token: PublicPool; 34 readonly origins: readonly string[]; 35 readonly closed: () => boolean; 36 readonly subscribe: ( 37 filters: readonly PublicFilter[], 38 onMessage: (message: PublicPoolMessage) => void, 39 sampleSource?: string 40 ) => () => void; 41 readonly close: () => void; 42 readonly preference: ( 43 permission: PreferencePublication, 44 origin: string, 45 signal: AbortSignal, 46 remaining: number 47 ) => Promise<PreferenceAttemptResult>; 48 readonly listing: ( 49 permission: ListingAttemptPermission, 50 origin: string, 51 signal: AbortSignal, 52 remaining: number 53 ) => Promise<PreferenceAttemptResult>; 54 readonly readListing: ( 55 permission: ListingAttemptPermission, 56 origin: string, 57 signal: AbortSignal, 58 remaining: number 59 ) => Promise<ListingReadbackResult>; 60 } 61 const owners = new WeakMap<PublicPool, Owner>(); 62 let lifetime: Owner | undefined; 63 64 // Anonymous state exists only after browser acquisition. No socket, information 65 // fetch, identity or extension operation occurs during import or SSR. 66 export function getPublicPool( 67 policy: RelayPolicy = deploymentRelayPolicy 68 ): PublicPool | undefined { 69 if (typeof window === 'undefined') return undefined; 70 readRelayPolicy(policy); 71 if (lifetime) { 72 if (lifetime.closed()) throw new Error('public_pool_closed'); 73 if (lifetime.policy !== policy) 74 throw new Error('public_pool_policy_changed'); 75 return lifetime.token; 76 } 77 const token = Object.freeze({}) as PublicPool; 78 const origins = publicRelayTargets(policy, 'read'); 79 const sdk = createScopedRelayPool(); 80 const active = new Map<() => void, true>(); 81 let closed = false; 82 let cleanupComplete = false; 83 let publicationCleanupRequired = false; 84 const owner: Owner = { 85 policy, 86 token, 87 origins, 88 closed: () => closed, 89 async preference(permission, origin, signal, remaining) { 90 const admitted = takePreferencePublication(permission, policy, origin); 91 if ( 92 closed || 93 publicationCleanupRequired || 94 !admitted || 95 signal.aborted || 96 !Number.isFinite(remaining) || 97 remaining <= 0 || 98 remaining > 45000 99 ) 100 return { status: 'stopped' }; 101 return await new Promise<PreferenceAttemptResult>((resolve) => { 102 let ended = false; 103 let release = () => {}; 104 let fenceTimer: ReturnType<typeof setTimeout> | undefined; 105 function finish(status: PreferenceAttemptResult['status']) { 106 if (ended) return; 107 ended = true; 108 clearTimeout(timer); 109 if (fenceTimer !== undefined) clearTimeout(fenceTimer); 110 signal.removeEventListener('abort', stopped); 111 try { 112 release(); 113 } catch { 114 publicationCleanupRequired = true; 115 status = 'unknown'; 116 } 117 resolve({ status }); 118 } 119 function stopped() { 120 if (ended) { 121 release(); 122 return; 123 } 124 finish('stopped'); 125 } 126 function fence() { 127 if (ended) return; 128 if (closed || signal.aborted || !admitted!.current()) { 129 finish('stopped'); 130 return; 131 } 132 fenceTimer = setTimeout(() => fence(), 50); 133 } 134 signal.addEventListener('abort', stopped, { once: true }); 135 // Arm our finite deadline before subscribing. The SDK uses the same 136 // response shape for its timer and a relay refusal saying "Timeout"; 137 // only this owned deadline supplies retryable timeout evidence. 138 const relay = sdk.relay(origin); 139 const timeout = 140 Number.isFinite(relay.eventTimeout) && relay.eventTimeout > 0 141 ? Math.min(remaining, relay.eventTimeout) 142 : remaining; 143 const timer = setTimeout(() => finish('timed_out'), timeout); 144 try { 145 if (!admitted.current() || signal.aborted) { 146 finish('stopped'); 147 return; 148 } 149 // This SDK invocation is an attempted effect. Stop cannot reverse an 150 // already emitted/buffered EVENT, but teardown schedules no new one. 151 const subscription = relay.event(admitted.event, 'EVENT').subscribe({ 152 next(response) { 153 if (ended) return; 154 if ( 155 (response.from !== origin && response.from !== origin + '/') || 156 typeof response.ok !== 'boolean' 157 ) { 158 finish('unknown'); 159 return; 160 } 161 if (response.ok) finish('accepted'); 162 else if (response.message === 'Timeout') finish('unknown'); 163 else if ( 164 typeof response.message === 'string' && 165 response.message.startsWith('auth-required:') 166 ) 167 finish('unknown'); 168 else finish('refused'); 169 }, 170 error: () => finish('unknown'), 171 complete: () => { 172 if (!ended) finish('unknown'); 173 } 174 }); 175 const stop = () => { 176 subscription.unsubscribe(); 177 active.delete(stop); 178 }; 179 release = () => { 180 stop(); 181 active.delete(stopped); 182 }; 183 active.set(stopped, true); 184 if (ended) { 185 try { 186 release(); 187 } catch { 188 publicationCleanupRequired = true; 189 } 190 } else { 191 fence(); 192 } 193 } catch { 194 finish('unknown'); 195 } 196 }); 197 }, 198 async listing(permission, origin, signal, remaining) { 199 const admitted = takeListingPublication( 200 permission, 201 policy, 202 origin, 203 'publish' 204 ); 205 if ( 206 closed || 207 publicationCleanupRequired || 208 !admitted || 209 signal.aborted || 210 !Number.isFinite(remaining) || 211 remaining <= 0 || 212 remaining > 45000 213 ) 214 return { status: 'stopped' }; 215 return await new Promise<PreferenceAttemptResult>((resolve) => { 216 let ended = false; 217 let release = () => {}; 218 let fenceTimer: ReturnType<typeof setTimeout> | undefined; 219 function finish(status: PreferenceAttemptResult['status']) { 220 if (ended) return; 221 ended = true; 222 clearTimeout(timer); 223 if (fenceTimer !== undefined) clearTimeout(fenceTimer); 224 signal.removeEventListener('abort', stopped); 225 try { 226 release(); 227 } catch { 228 publicationCleanupRequired = true; 229 status = 'unknown'; 230 } 231 resolve({ status }); 232 } 233 function stopped() { 234 if (ended) { 235 release(); 236 return; 237 } 238 finish('stopped'); 239 } 240 function fence() { 241 if (ended) return; 242 if (closed || signal.aborted || !admitted!.current()) { 243 finish('stopped'); 244 return; 245 } 246 fenceTimer = setTimeout(() => fence(), 50); 247 } 248 signal.addEventListener('abort', stopped, { once: true }); 249 // Arm our finite deadline before subscribing. The SDK uses the same 250 // response shape for its timer and a relay refusal saying "Timeout"; 251 // only this owned deadline supplies retryable timeout evidence. 252 const relay = sdk.relay(origin); 253 const timeout = 254 Number.isFinite(relay.eventTimeout) && relay.eventTimeout > 0 255 ? Math.min(remaining, relay.eventTimeout) 256 : remaining; 257 const timer = setTimeout(() => finish('timed_out'), timeout); 258 try { 259 if (!admitted.current() || signal.aborted) { 260 finish('stopped'); 261 return; 262 } 263 // This SDK invocation is an attempted effect. Stop cannot reverse an 264 // already emitted/buffered EVENT, but teardown schedules no new one. 265 const subscription = relay.event(admitted.event, 'EVENT').subscribe({ 266 next(response) { 267 if (ended) return; 268 if ( 269 (response.from !== origin && response.from !== origin + '/') || 270 typeof response.ok !== 'boolean' 271 ) { 272 finish('unknown'); 273 return; 274 } 275 if (response.ok) finish('accepted'); 276 else if (response.message === 'Timeout') finish('unknown'); 277 else if ( 278 typeof response.message === 'string' && 279 response.message.startsWith('auth-required:') 280 ) 281 finish('unknown'); 282 else finish('refused'); 283 }, 284 error: () => finish('unknown'), 285 complete: () => { 286 if (!ended) finish('unknown'); 287 } 288 }); 289 const stop = () => { 290 subscription.unsubscribe(); 291 active.delete(stop); 292 }; 293 release = () => { 294 stop(); 295 active.delete(stopped); 296 }; 297 active.set(stopped, true); 298 if (ended) { 299 try { 300 release(); 301 } catch { 302 publicationCleanupRequired = true; 303 } 304 } else { 305 fence(); 306 } 307 } catch { 308 finish('unknown'); 309 } 310 }); 311 }, 312 async readListing(permission, origin, signal, remaining) { 313 const admitted = takeListingPublication( 314 permission, 315 policy, 316 origin, 317 'readback' 318 ); 319 if ( 320 closed || 321 publicationCleanupRequired || 322 !admitted || 323 signal.aborted || 324 !Number.isFinite(remaining) || 325 remaining <= 0 || 326 remaining > 45000 327 ) 328 return { status: 'stopped' }; 329 return await new Promise<ListingReadbackResult>((resolve) => { 330 let ended = false, 331 release = () => {}; 332 let fenceTimer: ReturnType<typeof setTimeout> | undefined; 333 function finish(result: ListingReadbackResult) { 334 if (ended) return; 335 ended = true; 336 clearTimeout(timer); 337 if (fenceTimer !== undefined) clearTimeout(fenceTimer); 338 signal.removeEventListener('abort', stopped); 339 try { 340 release(); 341 } catch { 342 publicationCleanupRequired = true; 343 result = { status: 'unknown' }; 344 } 345 resolve(result); 346 } 347 function stopped() { 348 finish({ status: 'stopped' }); 349 } 350 function fence() { 351 if (ended) return; 352 if (closed || signal.aborted || !admitted!.current()) { 353 stopped(); 354 return; 355 } 356 fenceTimer = setTimeout(fence, 50); 357 } 358 const timer = setTimeout( 359 () => finish({ status: 'unknown' }), 360 remaining 361 ); 362 signal.addEventListener('abort', stopped, { once: true }); 363 try { 364 if (!admitted.current() || signal.aborted) { 365 stopped(); 366 return; 367 } 368 const expected = admitted.event; 369 // Exact frozen target and ID only. No generic filter/relay/request API. 370 const subscription = sdk 371 .req( 372 [origin], 373 [ 374 { 375 ids: [expected.id], 376 authors: [expected.pubkey], 377 kinds: [expected.kind], 378 limit: 1 379 } 380 ], 381 { waitForAuth: false, reconnect: false, resubscribe: false } 382 ) 383 .subscribe({ 384 next(message) { 385 if ( 386 ended || 387 (message.from !== origin && message.from !== origin + '/') 388 ) 389 return; 390 if (message.type === 'EOSE') { 391 finish({ status: 'missing' }); 392 return; 393 } 394 if (message.type !== 'EVENT' || !admitted.current()) return; 395 const checked = verifyEnvelope(JSON.stringify(message.event)); 396 const observed = 397 checked.ok && verifiedEnvelopeSnapshot(checked.value); 398 const fields = (event: typeof expected) => 399 JSON.stringify([ 400 event.id, 401 event.pubkey, 402 event.created_at, 403 event.kind, 404 event.tags, 405 event.content, 406 event.sig 407 ]); 408 if (observed && fields(observed) === fields(expected)) 409 // SDK object ingress is independently verified signed fields, 410 // not a claim to preserve the relay's original JSON encoding. 411 finish({ status: 'found', wire: admitted.wire }); 412 }, 413 error: () => finish({ status: 'unknown' }), 414 complete: () => { 415 if (!ended) finish({ status: 'missing' }); 416 } 417 }); 418 release = () => { 419 subscription.unsubscribe(); 420 active.delete(stopped); 421 }; 422 active.set(stopped, true); 423 if (ended) release(); 424 else fence(); 425 } catch { 426 finish({ status: 'unknown' }); 427 } 428 }); 429 }, 430 subscribe(filters, onMessage, sampleSource) { 431 if (closed) throw new Error('public_pool_closed'); 432 let release = () => {}; 433 const subscription = sdk 434 .req( 435 sampleSource === undefined 436 ? [...origins] 437 : [requireNip50Source(policy, sampleSource)], 438 [...filters], 439 { 440 waitForAuth: false, 441 reconnect: false, 442 resubscribe: false 443 } 444 ) 445 .subscribe({ 446 next: (message) => { 447 if (!closed) onMessage(message); 448 }, 449 complete: () => release(), 450 error: () => release() 451 }); 452 const stop = () => { 453 try { 454 subscription.unsubscribe(); 455 } finally { 456 active.delete(stop); 457 } 458 }; 459 release = stop; 460 if (closed) stop(); 461 else if (!subscription.closed) active.set(stop, true); 462 return stop; 463 }, 464 close() { 465 if (cleanupComplete) return; 466 closed = true; 467 let failed = false; 468 for (const stop of active.keys()) { 469 try { 470 stop(); 471 } catch { 472 failed = true; 473 } 474 } 475 try { 476 sdk.close(); 477 } catch { 478 failed = true; 479 } 480 cleanupComplete = !failed && active.size === 0; 481 if (!cleanupComplete) throw new Error('public_pool_close_failed'); 482 } 483 }; 484 owners.set(token, owner); 485 lifetime = owner; 486 return token; 487 } 488 489 function ownerOf(token: PublicPool): Owner { 490 const owner = owners.get(token); 491 if (!owner) throw new Error('public_pool_invalid'); 492 return owner; 493 } 494 export function publicPoolOrigins(token: PublicPool): readonly string[] { 495 return [...ownerOf(token).origins]; 496 } 497 498 // Filter construction and event verification/work budgets have separate owners. 499 // Accept no SDK filter callback (which would expose a raw relay), arbitrary 500 // destination, AUTH method, information fetch or retry option through this API. 501 export function subscribePublicPool( 502 token: PublicPool, 503 filters: readonly PublicFilter[], 504 onMessage: (message: PublicPoolMessage) => void, 505 sampleSource?: string 506 ): () => void { 507 const owner = ownerOf(token); 508 if (owner.closed()) throw new Error('public_pool_closed'); 509 if ( 510 !Array.isArray(filters) || 511 filters.length === 0 || 512 filters.some( 513 (filter) => !filter || typeof filter !== 'object' || Array.isArray(filter) 514 ) 515 ) 516 throw new Error('public_pool_filters_invalid'); 517 if (sampleSource !== undefined) 518 requireNip50Source(owner.policy, sampleSource); 519 if ( 520 sampleSource === undefined && 521 filters.some((filter) => 'search' in filter) 522 ) 523 throw new Error('public_pool_search_requires_source'); 524 return owner.subscribe(filters, onMessage, sampleSource); 525 } 526 527 // Terminal browser-lifetime shutdown: cancel request controls before closing the 528 // SDK sockets and its keepalive/reconnect watchers. Routes cannot recreate it. 529 export function closePublicPool(token: PublicPool): void { 530 ownerOf(token).close(); 531 } 532 // Narrow once-only preference capability; no raw event, arbitrary SDK options, 533 // AUTH or general UI publisher. Pool remains the anonymous lifetime owner. 534 export function publishPublicPreferenceAttempt( 535 token: PublicPool, 536 permission: PreferencePublication, 537 policy: RelayPolicy, 538 origin: string, 539 signal: AbortSignal, 540 remaining: number 541 ): Promise<PreferenceAttemptResult> { 542 try { 543 const owner = ownerOf(token); 544 if (owner.policy !== policy) return Promise.resolve({ status: 'stopped' }); 545 return owner.preference(permission, origin, signal, remaining); 546 } catch { 547 return Promise.resolve({ status: 'unknown' }); 548 } 549 } 550 // Listing and preference permissions stay separate despite the shared SDK owner. 551 export function publishPublicListingAttempt( 552 token: PublicPool, 553 permission: ListingAttemptPermission, 554 policy: RelayPolicy, 555 origin: string, 556 signal: AbortSignal, 557 remaining: number 558 ): Promise<PreferenceAttemptResult> { 559 try { 560 const owner = ownerOf(token); 561 if (owner.policy !== policy) return Promise.resolve({ status: 'stopped' }); 562 return owner.listing(permission, origin, signal, remaining); 563 } catch { 564 return Promise.resolve({ status: 'unknown' }); 565 } 566 } 567 export function readPublicListingExactAttempt( 568 token: PublicPool, 569 permission: ListingAttemptPermission, 570 policy: RelayPolicy, 571 origin: string, 572 signal: AbortSignal, 573 remaining: number 574 ): Promise<ListingReadbackResult> { 575 try { 576 const owner = ownerOf(token); 577 if (owner.policy !== policy) return Promise.resolve({ status: 'stopped' }); 578 return owner.readListing(permission, origin, signal, remaining); 579 } catch { 580 return Promise.resolve({ status: 'unknown' }); 581 } 582 }