@aephia/atlas-kit 0.6.0-next.17 → 0.6.0-next.170

package/dist/client/context.js

@@ -89,6 +89,19 @@ function validateDiscoveryFilters(filters) {
         }
     }
 }
+function assertDiscriminatorFilter(definition, filters) {
+    const discriminator = [...definition.discriminator];
+    const present = filters.some((filter) => filter.offset === 0 &&
+        filter.bytes.length >= discriminator.length &&
+        discriminator.every((byte, index) => filter.bytes[index] === byte));
+    if (!present) {
+        throw new InvalidDerivationInputError(`The ${definition.type} discovery subscription filter set`, `${filters.length} filter(s) without the account discriminator at offset 0`, 'Add the account discriminator filter at offset 0 so the program subscription streams only this account type.');
+    }
+}
+function matchesFilters(data, filters) {
+    return filters.every((filter) => filter.offset + filter.bytes.length <= data.length &&
+        filter.bytes.every((byte, index) => data[filter.offset + index] === byte));
+}
 function copyReadMetaFilters(filters) {
     return Object.freeze(filters.map((filter) => Object.freeze({
         bytes: Object.freeze([...filter.bytes]),
@@ -111,7 +124,7 @@ function assertWithinLimit(resource, actual, limit) {
 function configuredLimit(name, value, fallback) {
     const selected = value ?? fallback;
     if (!Number.isSafeInteger(selected) || selected < 1) {
-        throw new RangeError(`${name} must be a positive safe integer. Correct the context option before creating the SAGE context.`);
+        throw new InvalidDerivationInputError(`Context limit ${name}`, selected, 'Use a positive safe integer before creating the SAGE context.');
     }
     return selected;
 }
@@ -286,6 +299,7 @@ function createDataPort(cluster, provider, indexer, subscriptionProvider, defaul
     let invalidationSequence = 0;
     let reconciliationGeneration = 0;
     let nextRawReadSequence = 0;
+    let nextDiscoverySequence = 0;
     let nextDefinitionId = 0;
     lifecycle.signal.addEventListener('abort', () => {
         cache.clear();
@@ -557,10 +571,12 @@ function createDataPort(cluster, provider, indexer, subscriptionProvider, defaul
             }
         })();
     }
-    function sharedDiscovery(programAddress, filters, commitment, discoveryInvalidationGeneration, addressReconciliationGeneration) {
+    function sharedDiscovery(programAddress, filters, commitment, discoveryInvalidationGeneration, addressReconciliationGeneration, minimumSequence = 0) {
         const registryKey = discoveryReadKey(programAddress, filters, commitment, discoveryInvalidationGeneration, addressReconciliationGeneration);
         const existing = discoveryReads.get(registryKey);
-        if (existing !== undefined) {
+        // A stream closing a subscription gap cannot join a discovery that began
+        // before its registration or reconnect.
+        if (existing !== undefined && existing.sequence >= minimumSequence) {
             return existing;
         }
         let resolveDiscovery;
@@ -571,6 +587,7 @@ function createDataPort(cluster, provider, indexer, subscriptionProvider, defaul
         });
         const read = {
             promise,
+            sequence: nextDiscoverySequence++,
         };
         discoveryReads.set(registryKey, read);
         const operation = (async () => {
@@ -790,6 +807,43 @@ function createDataPort(cluster, provider, indexer, subscriptionProvider, defaul
         void promise.then(retainSettledResult, retainSettledResult);
         return promise;
     }
+    async function targetedDiscovery(definition, providerFilters, commitment, store, operationInvalidationSequence, signal, minimumSequence = 0) {
+        let accounts;
+        try {
+            const discoveryRead = sharedDiscovery(definition.programAddress, providerFilters, commitment, discoveryInvalidatedAt.get(definition.programAddress) ?? 0, reconciliationGeneration, minimumSequence);
+            accounts = await waitForCaller(discoveryRead.promise, signal);
+        }
+        catch (cause) {
+            if (signal?.aborted === true) {
+                throw abortReason(signal);
+            }
+            if (isDisposed()) {
+                throw new ContextDisposedError();
+            }
+            if (cause instanceof SageSdkError) {
+                throw cause;
+            }
+            throw new ProviderError('The configured provider could not discover the requested z.ink accounts. Check the discovery filters and provider connection, then retry.', { accountType: definition.type });
+        }
+        assertActive();
+        const snapshotsByAddress = new Map();
+        for (const account of accounts) {
+            assertProviderCommitment(account, commitment);
+            const snapshot = validateAndTimestamp(definition, copyRawAccount(account), provider.identity);
+            const existing = snapshotsByAddress.get(snapshot.address);
+            if (existing === undefined || isPreferredSnapshot(snapshot, existing)) {
+                snapshotsByAddress.set(snapshot.address, snapshot);
+            }
+        }
+        const snapshots = [...snapshotsByAddress.values()];
+        if (store) {
+            assertCacheCapacity(snapshots.map((snapshot) => keyFor(definition, snapshot.address)));
+            for (const snapshot of snapshots) {
+                storeSnapshot(keyFor(definition, snapshot.address), snapshot, operationInvalidationSequence);
+            }
+        }
+        return snapshots;
+    }
     async function readOptional(definition, address, options) {
         assertActive();
         throwIfAborted(options?.signal);
@@ -950,40 +1004,7 @@ function createDataPort(cluster, provider, indexer, subscriptionProvider, defaul
                     strategy: 'indexer',
                 }));
             }
-            let accounts;
-            try {
-                const discoveryRead = sharedDiscovery(definition.programAddress, providerFilters, commitment, discoveryInvalidatedAt.get(definition.programAddress) ?? 0, reconciliationGeneration);
-                accounts = await waitForCaller(discoveryRead.promise, request.signal);
-            }
-            catch (cause) {
-                if (request.signal?.aborted === true) {
-                    throw abortReason(request.signal);
-                }
-                if (isDisposed()) {
-                    throw new ContextDisposedError();
-                }
-                if (cause instanceof SageSdkError) {
-                    throw cause;
-                }
-                throw new ProviderError('The configured provider could not discover the requested z.ink accounts. Check the discovery filters and provider connection, then retry.', { accountType: definition.type });
-            }
-            assertActive();
-            const snapshotsByAddress = new Map();
-            for (const account of accounts) {
-                assertProviderCommitment(account, commitment);
-                const snapshot = validateAndTimestamp(definition, copyRawAccount(account), provider.identity);
-                const existing = snapshotsByAddress.get(snapshot.address);
-                if (existing === undefined || isPreferredSnapshot(snapshot, existing)) {
-                    snapshotsByAddress.set(snapshot.address, snapshot);
-                }
-            }
-            const snapshots = [...snapshotsByAddress.values()];
-            if (request.policy !== 'no-store') {
-                assertCacheCapacity(snapshots.map((snapshot) => keyFor(definition, snapshot.address)));
-                for (const snapshot of snapshots) {
-                    storeSnapshot(keyFor(definition, snapshot.address), snapshot, operationInvalidationSequence);
-                }
-            }
+            const snapshots = await targetedDiscovery(definition, providerFilters, commitment, request.policy !== 'no-store', operationInvalidationSequence, request.signal);
             const slot = snapshots.reduce((earliest, snapshot) => earliest === undefined || snapshot.slot < earliest
                 ? snapshot.slot
                 : earliest, undefined);
@@ -1014,6 +1035,9 @@ function createDataPort(cluster, provider, indexer, subscriptionProvider, defaul
                 rejectRegistration = reject;
             });
             let lastDelivered;
+            // The snapshot onSnapshot is processing, so a slow callback cannot let
+            // an older slot follow it; a rejected one can still be retried.
+            let inFlight;
             let stopPromise;
             let resolveCompletion;
             const completion = new Promise((resolve) => {
@@ -1078,6 +1102,7 @@ function createDataPort(cluster, provider, indexer, subscriptionProvider, defaul
                             return;
                         pendingSnapshot = undefined;
                         coalescedSnapshots = 0;
+                        inFlight = snapshot;
                         try {
                             const notification = observer.onSnapshot(snapshot);
                             resolveRegistrationDeliveryStarted();
@@ -1089,6 +1114,9 @@ function createDataPort(cluster, provider, indexer, subscriptionProvider, defaul
                             const error = normalizeSubscriptionError(cause, observerErrorMessage);
                             pendingErrors.set(error.code, error);
                         }
+                        finally {
+                            inFlight = undefined;
+                        }
                     }
                 }
                 finally {
@@ -1114,7 +1142,7 @@ function createDataPort(cluster, provider, indexer, subscriptionProvider, defaul
                 void runNotifications();
             };
             const queueSnapshotCandidate = (selected, awaitReconnect = false) => {
-                const deliveryBaseline = pendingSnapshot ?? lastDelivered;
+                const deliveryBaseline = pendingSnapshot ?? inFlight ?? lastDelivered;
                 if (deliveryBaseline !== undefined &&
                     !isPreferredSnapshot(selected, deliveryBaseline)) {
                     return;
@@ -1301,6 +1329,294 @@ function createDataPort(cluster, provider, indexer, subscriptionProvider, defaul
             await waitForCaller(registrationDeliveryStarted, registrationLifecycle.signal);
             return Object.freeze({ unsubscribe: stop });
         },
+        async subscribeDiscovery(definition, request, observer) {
+            assertActive();
+            throwIfAborted(request.signal);
+            const programProvider = subscriptionProvider;
+            if (programProvider?.subscribeProgram === undefined) {
+                throw new ProviderError('This SAGE context has no program subscription provider. Configure a WebSocket subscription provider that implements subscribeProgram, such as createRpcSubscriptionProvider over a Kit transport with programNotifications, before streaming account changes.', { accountType: definition.type });
+            }
+            validateDiscoveryFilters(request.filters);
+            assertDiscriminatorFilter(definition, request.filters);
+            const filters = copyProviderDiscoveryFilters(request.filters);
+            const commitment = requestedCommitment(request);
+            const registrationLifecycle = new AbortController();
+            const { signal } = registrationLifecycle;
+            let registration;
+            let registrationAttempt;
+            let stopPromise;
+            let resolveCompletion;
+            const completion = new Promise((resolve) => {
+                resolveCompletion = resolve;
+            });
+            trackSubscription(completion);
+            const streamErrorMessage = 'The account stream could not process a live z.ink update. Check the WebSocket provider and retry the subscription.';
+            const observerErrorMessage = 'The account stream onSnapshot callback could not process a validated snapshot. Fix the consumer callback before retrying delivery.';
+            // Every map is bounded by the addresses matching the filters, which is
+            // capped at maxDiscoveryResults; transient errors are bounded by code.
+            // The discovery round in which each address was last seen; a reconnect
+            // reports only addresses not seen since its discovery started.
+            const seenInRound = new Map();
+            let discoveryRound = 0;
+            const lastDelivered = new Map();
+            // The snapshot onSnapshot is processing, so a slow callback cannot let
+            // an older slot follow it; a rejected one can still be retried.
+            let inFlight;
+            const pending = new Map();
+            // Removals stay keyed by address: each one is reported exactly once.
+            const pendingRemovals = new Map();
+            const coalesced = new Map();
+            const pendingErrors = new Map();
+            const coalescedErrors = new Map();
+            let notificationRunning = false;
+            let discovering = false;
+            let rediscoveryPending = false;
+            let pendingDiscoverySequence = 0;
+            const emitDiagnostic = (event) => {
+                try {
+                    observer.onDiagnostic?.(event);
+                }
+                catch {
+                    // Diagnostics never interrupt delivery or transport cleanup.
+                }
+            };
+            const normalizeError = (cause, message) => cause instanceof SageSdkError
+                ? cause
+                : new ProviderError(message, {
+                    accountType: definition.type,
+                    cause,
+                });
+            const runNotifications = async () => {
+                if (notificationRunning)
+                    return;
+                notificationRunning = true;
+                try {
+                    while (!signal.aborted && !isDisposed()) {
+                        const errorEntry = pendingErrors.entries().next().value;
+                        if (errorEntry !== undefined) {
+                            pendingErrors.delete(errorEntry[0]);
+                            coalescedErrors.delete(errorEntry[0]);
+                            try {
+                                await observer.onError(errorEntry[1]);
+                            }
+                            catch {
+                                // Consumer observer failures never terminate transport.
+                            }
+                            continue;
+                        }
+                        const removal = pendingRemovals.entries().next().value;
+                        if (removal !== undefined) {
+                            pendingRemovals.delete(removal[0]);
+                            try {
+                                await observer.onError(removal[1]);
+                            }
+                            catch {
+                                // Consumer observer failures never terminate transport.
+                            }
+                            continue;
+                        }
+                        const next = pending.entries().next().value;
+                        if (next === undefined)
+                            return;
+                        pending.delete(next[0]);
+                        coalesced.delete(next[0]);
+                        inFlight = next[1];
+                        try {
+                            await observer.onSnapshot(next[1]);
+                            // A reconnect may have reported the account missing meanwhile.
+                            if (seenInRound.has(next[0])) {
+                                lastDelivered.set(next[0], next[1]);
+                            }
+                        }
+                        catch (cause) {
+                            const error = normalizeError(cause, observerErrorMessage);
+                            pendingErrors.set(error.code, error);
+                        }
+                        finally {
+                            inFlight = undefined;
+                        }
+                    }
+                }
+                finally {
+                    notificationRunning = false;
+                }
+            };
+            const reportError = (cause, message) => {
+                if (signal.aborted)
+                    return;
+                const error = normalizeError(cause, message);
+                if (pendingErrors.has(error.code)) {
+                    const count = (coalescedErrors.get(error.code) ?? 0) + 1;
+                    coalescedErrors.set(error.code, count);
+                    emitDiagnostic({
+                        accountType: definition.type,
+                        address: error.address ?? definition.programAddress,
+                        coalescedCount: count,
+                        errorCode: error.code,
+                        kind: 'subscription-error-coalesced',
+                    });
+                }
+                pendingErrors.set(error.code, error);
+                void runNotifications();
+            };
+            const queueSnapshot = (candidate) => {
+                const address = candidate.address;
+                const selected = cachedSnapshot(keyFor(definition, address), commitment) ??
+                    candidate;
+                const baseline = pending.get(address) ??
+                    (inFlight?.address === address ? inFlight : undefined) ??
+                    lastDelivered.get(address);
+                if (baseline !== undefined &&
+                    !isPreferredSnapshot(selected, baseline)) {
+                    return;
+                }
+                if (pending.has(address)) {
+                    const count = (coalesced.get(address) ?? 0) + 1;
+                    coalesced.set(address, count);
+                    emitDiagnostic({
+                        accountType: definition.type,
+                        address,
+                        coalescedCount: count,
+                        kind: 'subscription-snapshot-coalesced',
+                    });
+                }
+                pending.set(address, selected);
+                void runNotifications();
+            };
+            const track = (address, round) => {
+                if (!seenInRound.has(address)) {
+                    assertWithinLimit('streamed accounts', seenInRound.size + 1, maxDiscoveryResults);
+                }
+                seenInRound.set(address, round);
+                // A validated sighting supersedes a removal not yet reported.
+                pendingRemovals.delete(address);
+            };
+            const rediscover = () => {
+                pendingDiscoverySequence = nextDiscoverySequence;
+                if (discovering) {
+                    rediscoveryPending = true;
+                    return;
+                }
+                discovering = true;
+                void (async () => {
+                    try {
+                        do {
+                            rediscoveryPending = false;
+                            const minimumSequence = pendingDiscoverySequence;
+                            const round = ++discoveryRound;
+                            try {
+                                const snapshots = await targetedDiscovery(definition, filters, commitment, true, invalidationSequence, signal, minimumSequence);
+                                for (const snapshot of snapshots) {
+                                    track(snapshot.address, round);
+                                    queueSnapshot(snapshot);
+                                }
+                                for (const [address, seen] of [...seenInRound]) {
+                                    if (seen >= round)
+                                        continue;
+                                    seenInRound.delete(address);
+                                    lastDelivered.delete(address);
+                                    pending.delete(address);
+                                    coalesced.delete(address);
+                                    pendingRemovals.set(address, new AccountNotFoundError(definition.type, address));
+                                    void runNotifications();
+                                }
+                            }
+                            catch (cause) {
+                                reportError(cause, streamErrorMessage);
+                            }
+                        } while (rediscoveryPending && !signal.aborted && !isDisposed());
+                    }
+                    finally {
+                        discovering = false;
+                    }
+                })();
+            };
+            const enqueue = (event) => {
+                if (signal.aborted || isDisposed())
+                    return;
+                if (event.kind === 'reconnected') {
+                    rediscover();
+                    return;
+                }
+                try {
+                    assertAccountSize(event.account);
+                    const account = copyRawAccount(event.account);
+                    assertProviderCommitment(account, commitment);
+                    if (!matchesFilters(account.data, filters)) {
+                        throw new ProviderError(`The program subscription returned ${account.address}, which does not match the requested filters. Fix the WebSocket provider's program-subscription filters before retrying.`, { accountType: definition.type, address: account.address });
+                    }
+                    const snapshot = validateAndTimestamp(definition, account, programProvider.identity);
+                    track(snapshot.address, discoveryRound);
+                    storeSubscriptionSnapshot(keyFor(definition, snapshot.address), snapshot);
+                    queueSnapshot(snapshot);
+                }
+                catch (cause) {
+                    reportError(cause, streamErrorMessage);
+                }
+            };
+            const abortRegistration = () => registrationLifecycle.abort(request.signal?.aborted === true
+                ? request.signal.reason
+                : lifecycle.signal.reason);
+            request.signal?.addEventListener('abort', abortRegistration, {
+                once: true,
+            });
+            lifecycle.signal.addEventListener('abort', abortRegistration, {
+                once: true,
+            });
+            const stop = () => {
+                if (stopPromise !== undefined)
+                    return stopPromise;
+                let resolveStop;
+                stopPromise = new Promise((resolve) => {
+                    resolveStop = resolve;
+                });
+                registrationLifecycle.abort();
+                request.signal?.removeEventListener('abort', abortRegistration);
+                lifecycle.signal.removeEventListener('abort', abortRegistration);
+                void (async () => {
+                    try {
+                        if (registration !== undefined) {
+                            await registration.unsubscribe();
+                        }
+                        else {
+                            // A late registration is released in the background.
+                            void registrationAttempt?.then((late) => late.unsubscribe(), () => undefined);
+                        }
+                    }
+                    catch {
+                        // Disposal remains best-effort when a transport is already gone.
+                    }
+                    finally {
+                        resolveCompletion();
+                        resolveStop();
+                    }
+                })();
+                return stopPromise;
+            };
+            signal.addEventListener('abort', () => void stop(), { once: true });
+            try {
+                registrationAttempt = Promise.resolve().then(() => programProvider.subscribeProgram({
+                    commitment,
+                    filters,
+                    programAddress: definition.programAddress,
+                    signal,
+                }, (event) => void enqueue(event)));
+                void registrationAttempt.catch(() => undefined);
+                registration = await waitForCaller(registrationAttempt, signal);
+            }
+            catch (cause) {
+                const wasCancelled = signal.aborted;
+                const cancellationReason = signal.reason;
+                await stop();
+                if (wasCancelled)
+                    throw cancellationReason;
+                if (cause instanceof SageSdkError)
+                    throw cause;
+                throw new ProviderError('The configured WebSocket provider could not register the requested program subscription. Check the provider connection and retry.', { accountType: definition.type });
+            }
+            rediscover();
+            return Object.freeze({ unsubscribe: stop });
+        },
         async readRaw(address, options) {
             assertActive();
             throwIfAborted(options?.signal);