@firebase/remote-config 0.6.6 → 0.7.0-canary.cb3bdd812

package/dist/index.cjs.js

@@ -9,7 +9,7 @@ var logger = require('@firebase/logger');
 require('@firebase/installations');
 
 const name = "@firebase/remote-config";
-const version = "0.6.6";
+const version = "0.7.0-canary.cb3bdd812";
 
 /**
  * @license
@@ -105,7 +105,11 @@ const ERROR_DESCRIPTION_MAP = {
         ' Original error: {$originalErrorMessage}.',
     ["fetch-status" /* ErrorCode.FETCH_STATUS */]: 'Fetch server returned an HTTP error status. HTTP status: {$httpStatus}.',
     ["indexed-db-unavailable" /* ErrorCode.INDEXED_DB_UNAVAILABLE */]: 'Indexed DB is not supported by current browser',
-    ["custom-signal-max-allowed-signals" /* ErrorCode.CUSTOM_SIGNAL_MAX_ALLOWED_SIGNALS */]: 'Setting more than {$maxSignals} custom signals is not supported.'
+    ["custom-signal-max-allowed-signals" /* ErrorCode.CUSTOM_SIGNAL_MAX_ALLOWED_SIGNALS */]: 'Setting more than {$maxSignals} custom signals is not supported.',
+    ["stream-error" /* ErrorCode.CONFIG_UPDATE_STREAM_ERROR */]: 'The stream was not able to connect to the backend: {$originalErrorMessage}.',
+    ["realtime-unavailable" /* ErrorCode.CONFIG_UPDATE_UNAVAILABLE */]: 'The Realtime service is unavailable: {$originalErrorMessage}',
+    ["update-message-invalid" /* ErrorCode.CONFIG_UPDATE_MESSAGE_INVALID */]: 'The stream invalidation message was unparsable: {$originalErrorMessage}',
+    ["update-not-fetched" /* ErrorCode.CONFIG_UPDATE_NOT_FETCHED */]: 'Unable to fetch the latest config: {$originalErrorMessage}'
 };
 const ERROR_FACTORY = new util.ErrorFactory('remoteconfig' /* service */, 'Remote Config' /* service name */, ERROR_DESCRIPTION_MAP);
 // Note how this is like typeof/instanceof, but for ErrorCode.
@@ -205,6 +209,7 @@ function getRemoteConfig(app$1 = app.getApp(), options = {}) {
         rc._initializePromise = Promise.all([
             rc._storage.setLastSuccessfulFetchResponse(options.initialFetchResponse),
             rc._storage.setActiveConfigEtag(options.initialFetchResponse?.eTag || ''),
+            rc._storage.setActiveConfigTemplateVersion(options.initialFetchResponse.templateVersion || 0),
             rc._storageCache.setLastSuccessfulFetchTimestampMillis(Date.now()),
             rc._storageCache.setLastFetchStatus('success'),
             rc._storageCache.setActiveConfig(options.initialFetchResponse?.config || {})
@@ -232,6 +237,7 @@ async function activate(remoteConfig) {
     if (!lastSuccessfulFetchResponse ||
         !lastSuccessfulFetchResponse.config ||
         !lastSuccessfulFetchResponse.eTag ||
+        !lastSuccessfulFetchResponse.templateVersion ||
         lastSuccessfulFetchResponse.eTag === activeConfigEtag) {
         // Either there is no successful fetched config, or is the same as current active
         // config.
@@ -239,7 +245,8 @@ async function activate(remoteConfig) {
     }
     await Promise.all([
         rc._storageCache.setActiveConfig(lastSuccessfulFetchResponse.config),
-        rc._storage.setActiveConfigEtag(lastSuccessfulFetchResponse.eTag)
+        rc._storage.setActiveConfigEtag(lastSuccessfulFetchResponse.eTag),
+        rc._storage.setActiveConfigTemplateVersion(lastSuccessfulFetchResponse.templateVersion)
     ]);
     return true;
 }
@@ -449,6 +456,29 @@ async function setCustomSignals(remoteConfig, customSignals) {
         rc._logger.error(`Error encountered while setting custom signals: ${error}`);
     }
 }
+// TODO: Add public document for the Remote Config Realtime API guide on the Web Platform.
+/**
+ * Starts listening for real-time config updates from the Remote Config backend and automatically
+ * fetches updates from the Remote Config backend when they are available.
+ *
+ * @remarks
+ * If a connection to the Remote Config backend is not already open, calling this method will
+ * open it. Multiple listeners can be added by calling this method again, but subsequent calls
+ * re-use the same connection to the backend.
+ *
+ * @param remoteConfig - The {@link RemoteConfig} instance.
+ * @param observer - The {@link ConfigUpdateObserver} to be notified of config updates.
+ * @returns An {@link Unsubscribe} function to remove the listener.
+ *
+ * @public
+ */
+function onConfigUpdate(remoteConfig, observer) {
+    const rc = util.getModularInstance(remoteConfig);
+    rc._realtimeHandler.addObserver(observer);
+    return () => {
+        rc._realtimeHandler.removeObserver(observer);
+    };
+}
 
 /**
  * @license
@@ -622,6 +652,8 @@ class RestClient {
             // Deviates from pure decorator by not passing max-age header since we don't currently have
             // service behavior using that header.
             'If-None-Match': request.eTag || '*'
+            // TODO: Add this header once CORS error is fixed internally.
+            //'X-Firebase-RC-Fetch-Type': `${fetchType}/${fetchAttempt}`
         };
         const requestBody = {
             /* eslint-disable camelcase */
@@ -668,6 +700,7 @@ class RestClient {
         const responseEtag = response.headers.get('ETag') || undefined;
         let config;
         let state;
+        let templateVersion;
         // JSON parsing throws SyntaxError if the response body isn't a JSON string.
         // Requesting application/json and checking for a 200 ensures there's JSON data.
         if (response.status === 200) {
@@ -682,6 +715,7 @@ class RestClient {
             }
             config = responseBody['entries'];
             state = responseBody['state'];
+            templateVersion = responseBody['templateVersion'];
         }
         // Normalizes based on legacy state.
         if (state === 'INSTANCE_STATE_UNSPECIFIED') {
@@ -703,7 +737,7 @@ class RestClient {
                 httpStatus: status
             });
         }
-        return { status, eTag: responseEtag, config };
+        return { status, eTag: responseEtag, config, templateVersion };
     }
 }
 
@@ -865,12 +899,17 @@ class RemoteConfig {
     /**
      * @internal
      */
-    _logger) {
+    _logger, 
+    /**
+     * @internal
+     */
+    _realtimeHandler) {
         this.app = app;
         this._client = _client;
         this._storageCache = _storageCache;
         this._storage = _storage;
         this._logger = _logger;
+        this._realtimeHandler = _realtimeHandler;
         /**
          * Tracks completion of initialization promise.
          * @internal
@@ -1003,6 +1042,18 @@ class Storage {
     getCustomSignals() {
         return this.get('custom_signals');
     }
+    getRealtimeBackoffMetadata() {
+        return this.get('realtime_backoff_metadata');
+    }
+    setRealtimeBackoffMetadata(realtimeMetadata) {
+        return this.set('realtime_backoff_metadata', realtimeMetadata);
+    }
+    getActiveConfigTemplateVersion() {
+        return this.get('last_known_template_version');
+    }
+    setActiveConfigTemplateVersion(version) {
+        return this.set('last_known_template_version', version);
+    }
 }
 class IndexedDbStorage extends Storage {
     /**
@@ -1263,6 +1314,683 @@ class StorageCache {
     }
 }
 
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// TODO: Consolidate the Visibility monitoring API code into a shared utility function in firebase/util to be used by both packages/database and packages/remote-config.
+/**
+ * Base class to be used if you want to emit events. Call the constructor with
+ * the set of allowed event names.
+ */
+class EventEmitter {
+    constructor(allowedEvents_) {
+        this.allowedEvents_ = allowedEvents_;
+        this.listeners_ = {};
+        util.assert(Array.isArray(allowedEvents_) && allowedEvents_.length > 0, 'Requires a non-empty array');
+    }
+    /**
+     * To be called by derived classes to trigger events.
+     */
+    trigger(eventType, ...varArgs) {
+        if (Array.isArray(this.listeners_[eventType])) {
+            // Clone the list, since callbacks could add/remove listeners.
+            const listeners = [...this.listeners_[eventType]];
+            for (let i = 0; i < listeners.length; i++) {
+                listeners[i].callback.apply(listeners[i].context, varArgs);
+            }
+        }
+    }
+    on(eventType, callback, context) {
+        this.validateEventType_(eventType);
+        this.listeners_[eventType] = this.listeners_[eventType] || [];
+        this.listeners_[eventType].push({ callback, context });
+        const eventData = this.getInitialEvent(eventType);
+        if (eventData) {
+            //@ts-ignore
+            callback.apply(context, eventData);
+        }
+    }
+    off(eventType, callback, context) {
+        this.validateEventType_(eventType);
+        const listeners = this.listeners_[eventType] || [];
+        for (let i = 0; i < listeners.length; i++) {
+            if (listeners[i].callback === callback &&
+                (!context || context === listeners[i].context)) {
+                listeners.splice(i, 1);
+                return;
+            }
+        }
+    }
+    validateEventType_(eventType) {
+        util.assert(this.allowedEvents_.find(et => {
+            return et === eventType;
+        }), 'Unknown event: ' + eventType);
+    }
+}
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// TODO: Consolidate the Visibility monitoring API code into a shared utility function in firebase/util to be used by both packages/database and packages/remote-config.
+class VisibilityMonitor extends EventEmitter {
+    static getInstance() {
+        return new VisibilityMonitor();
+    }
+    constructor() {
+        super(['visible']);
+        let hidden;
+        let visibilityChange;
+        if (typeof document !== 'undefined' &&
+            typeof document.addEventListener !== 'undefined') {
+            if (typeof document['hidden'] !== 'undefined') {
+                // Opera 12.10 and Firefox 18 and later support
+                visibilityChange = 'visibilitychange';
+                hidden = 'hidden';
+            } // @ts-ignore
+            else if (typeof document['mozHidden'] !== 'undefined') {
+                visibilityChange = 'mozvisibilitychange';
+                hidden = 'mozHidden';
+            } // @ts-ignore
+            else if (typeof document['msHidden'] !== 'undefined') {
+                visibilityChange = 'msvisibilitychange';
+                hidden = 'msHidden';
+            } // @ts-ignore
+            else if (typeof document['webkitHidden'] !== 'undefined') {
+                visibilityChange = 'webkitvisibilitychange';
+                hidden = 'webkitHidden';
+            }
+        }
+        // Initially, we always assume we are visible. This ensures that in browsers
+        // without page visibility support or in cases where we are never visible
+        // (e.g. chrome extension), we act as if we are visible, i.e. don't delay
+        // reconnects
+        this.visible_ = true;
+        // @ts-ignore
+        if (visibilityChange) {
+            document.addEventListener(visibilityChange, () => {
+                // @ts-ignore
+                const visible = !document[hidden];
+                if (visible !== this.visible_) {
+                    this.visible_ = visible;
+                    this.trigger('visible', visible);
+                }
+            }, false);
+        }
+    }
+    getInitialEvent(eventType) {
+        util.assert(eventType === 'visible', 'Unknown event type: ' + eventType);
+        return [this.visible_];
+    }
+}
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const API_KEY_HEADER = 'X-Goog-Api-Key';
+const INSTALLATIONS_AUTH_TOKEN_HEADER = 'X-Goog-Firebase-Installations-Auth';
+const ORIGINAL_RETRIES = 8;
+const MAXIMUM_FETCH_ATTEMPTS = 3;
+const NO_BACKOFF_TIME_IN_MILLIS = -1;
+const NO_FAILED_REALTIME_STREAMS = 0;
+const REALTIME_DISABLED_KEY = 'featureDisabled';
+const REALTIME_RETRY_INTERVAL = 'retryIntervalSeconds';
+const TEMPLATE_VERSION_KEY = 'latestTemplateVersionNumber';
+class RealtimeHandler {
+    constructor(firebaseInstallations, storage, sdkVersion, namespace, projectId, apiKey, appId, logger, storageCache, cachingClient) {
+        this.firebaseInstallations = firebaseInstallations;
+        this.storage = storage;
+        this.sdkVersion = sdkVersion;
+        this.namespace = namespace;
+        this.projectId = projectId;
+        this.apiKey = apiKey;
+        this.appId = appId;
+        this.logger = logger;
+        this.storageCache = storageCache;
+        this.cachingClient = cachingClient;
+        this.observers = new Set();
+        this.isConnectionActive = false;
+        this.isRealtimeDisabled = false;
+        this.httpRetriesRemaining = ORIGINAL_RETRIES;
+        this.isInBackground = false;
+        this.decoder = new TextDecoder('utf-8');
+        this.isClosingConnection = false;
+        this.propagateError = (e) => this.observers.forEach(o => o.error?.(e));
+        /**
+         * HTTP status code that the Realtime client should retry on.
+         */
+        this.isStatusCodeRetryable = (statusCode) => {
+            const retryableStatusCodes = [
+                408, // Request Timeout
+                429, // Too Many Requests
+                502, // Bad Gateway
+                503, // Service Unavailable
+                504 // Gateway Timeout
+            ];
+            return !statusCode || retryableStatusCodes.includes(statusCode);
+        };
+        void this.setRetriesRemaining();
+        void VisibilityMonitor.getInstance().on('visible', this.onVisibilityChange, this);
+    }
+    async setRetriesRemaining() {
+        // Retrieve number of remaining retries from last session. The minimum retry count being one.
+        const metadata = await this.storage.getRealtimeBackoffMetadata();
+        const numFailedStreams = metadata?.numFailedStreams || 0;
+        this.httpRetriesRemaining = Math.max(ORIGINAL_RETRIES - numFailedStreams, 1);
+    }
+    /**
+     * Increment the number of failed stream attempts, increase the backoff duration, set the backoff
+     * end time to "backoff duration" after `lastFailedStreamTime` and persist the new
+     * values to storage metadata.
+     */
+    async updateBackoffMetadataWithLastFailedStreamConnectionTime(lastFailedStreamTime) {
+        const numFailedStreams = ((await this.storage.getRealtimeBackoffMetadata())?.numFailedStreams ||
+            0) + 1;
+        const backoffMillis = util.calculateBackoffMillis(numFailedStreams, 60000, 2);
+        await this.storage.setRealtimeBackoffMetadata({
+            backoffEndTimeMillis: new Date(lastFailedStreamTime.getTime() + backoffMillis),
+            numFailedStreams
+        });
+    }
+    /**
+     * Increase the backoff duration with a new end time based on Retry Interval.
+     */
+    async updateBackoffMetadataWithRetryInterval(retryIntervalSeconds) {
+        const currentTime = Date.now();
+        const backoffDurationInMillis = retryIntervalSeconds * 1000;
+        const backoffEndTime = new Date(currentTime + backoffDurationInMillis);
+        const numFailedStreams = 0;
+        await this.storage.setRealtimeBackoffMetadata({
+            backoffEndTimeMillis: backoffEndTime,
+            numFailedStreams
+        });
+        await this.retryHttpConnectionWhenBackoffEnds();
+    }
+    /**
+     * Closes the realtime HTTP connection.
+     * Note: This method is designed to be called only once at a time.
+     * If a call is already in progress, subsequent calls will be ignored.
+     */
+    async closeRealtimeHttpConnection() {
+        if (this.isClosingConnection) {
+            return;
+        }
+        this.isClosingConnection = true;
+        try {
+            if (this.reader) {
+                await this.reader.cancel();
+            }
+        }
+        catch (e) {
+            // The network connection was lost, so cancel() failed.
+            // This is expected in a disconnected state, so we can safely ignore the error.
+            this.logger.debug('Failed to cancel the reader, connection was lost.');
+        }
+        finally {
+            this.reader = undefined;
+        }
+        if (this.controller) {
+            await this.controller.abort();
+            this.controller = undefined;
+        }
+        this.isClosingConnection = false;
+    }
+    async resetRealtimeBackoff() {
+        await this.storage.setRealtimeBackoffMetadata({
+            backoffEndTimeMillis: new Date(-1),
+            numFailedStreams: 0
+        });
+    }
+    resetRetryCount() {
+        this.httpRetriesRemaining = ORIGINAL_RETRIES;
+    }
+    /**
+     * Assembles the request headers and body and executes the fetch request to
+     * establish the real-time streaming connection. This is the "worker" method
+     * that performs the actual network communication.
+     */
+    async establishRealtimeConnection(url, installationId, installationTokenResult, signal) {
+        const eTagValue = await this.storage.getActiveConfigEtag();
+        const lastKnownVersionNumber = await this.storage.getActiveConfigTemplateVersion();
+        const headers = {
+            [API_KEY_HEADER]: this.apiKey,
+            [INSTALLATIONS_AUTH_TOKEN_HEADER]: installationTokenResult,
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+            'If-None-Match': eTagValue || '*',
+            'Content-Encoding': 'gzip'
+        };
+        const requestBody = {
+            project: this.projectId,
+            namespace: this.namespace,
+            lastKnownVersionNumber,
+            appId: this.appId,
+            sdkVersion: this.sdkVersion,
+            appInstanceId: installationId
+        };
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(requestBody),
+            signal
+        });
+        return response;
+    }
+    getRealtimeUrl() {
+        const urlBase = window.FIREBASE_REMOTE_CONFIG_URL_BASE ||
+            'https://firebaseremoteconfigrealtime.googleapis.com';
+        const urlString = `${urlBase}/v1/projects/${this.projectId}/namespaces/${this.namespace}:streamFetchInvalidations?key=${this.apiKey}`;
+        return new URL(urlString);
+    }
+    async createRealtimeConnection() {
+        const [installationId, installationTokenResult] = await Promise.all([
+            this.firebaseInstallations.getId(),
+            this.firebaseInstallations.getToken(false)
+        ]);
+        this.controller = new AbortController();
+        const url = this.getRealtimeUrl();
+        const realtimeConnection = await this.establishRealtimeConnection(url, installationId, installationTokenResult, this.controller.signal);
+        return realtimeConnection;
+    }
+    /**
+     * Retries HTTP stream connection asyncly in random time intervals.
+     */
+    async retryHttpConnectionWhenBackoffEnds() {
+        let backoffMetadata = await this.storage.getRealtimeBackoffMetadata();
+        if (!backoffMetadata) {
+            backoffMetadata = {
+                backoffEndTimeMillis: new Date(NO_BACKOFF_TIME_IN_MILLIS),
+                numFailedStreams: NO_FAILED_REALTIME_STREAMS
+            };
+        }
+        const backoffEndTime = new Date(backoffMetadata.backoffEndTimeMillis).getTime();
+        const currentTime = Date.now();
+        const retryMillis = Math.max(0, backoffEndTime - currentTime);
+        await this.makeRealtimeHttpConnection(retryMillis);
+    }
+    setIsHttpConnectionRunning(connectionRunning) {
+        this.isConnectionActive = connectionRunning;
+    }
+    /**
+     * Combines the check and set operations to prevent multiple asynchronous
+     * calls from redundantly starting an HTTP connection. This ensures that
+     * only one attempt is made at a time.
+     */
+    checkAndSetHttpConnectionFlagIfNotRunning() {
+        const canMakeConnection = this.canEstablishStreamConnection();
+        if (canMakeConnection) {
+            this.setIsHttpConnectionRunning(true);
+        }
+        return canMakeConnection;
+    }
+    fetchResponseIsUpToDate(fetchResponse, lastKnownVersion) {
+        // If there is a config, make sure its version is >= the last known version.
+        if (fetchResponse.config != null && fetchResponse.templateVersion) {
+            return fetchResponse.templateVersion >= lastKnownVersion;
+        }
+        // If there isn't a config, return true if the fetch was successful and backend had no update.
+        // Else, it returned an out of date config.
+        return this.storageCache.getLastFetchStatus() === 'success';
+    }
+    parseAndValidateConfigUpdateMessage(message) {
+        const left = message.indexOf('{');
+        const right = message.indexOf('}', left);
+        if (left < 0 || right < 0) {
+            return '';
+        }
+        return left >= right ? '' : message.substring(left, right + 1);
+    }
+    isEventListenersEmpty() {
+        return this.observers.size === 0;
+    }
+    getRandomInt(max) {
+        return Math.floor(Math.random() * max);
+    }
+    executeAllListenerCallbacks(configUpdate) {
+        this.observers.forEach(observer => observer.next(configUpdate));
+    }
+    /**
+     * Compares two configuration objects and returns a set of keys that have changed.
+     * A key is considered changed if it's new, removed, or has a different value.
+     */
+    getChangedParams(newConfig, oldConfig) {
+        const changedKeys = new Set();
+        const newKeys = new Set(Object.keys(newConfig || {}));
+        const oldKeys = new Set(Object.keys(oldConfig || {}));
+        for (const key of newKeys) {
+            if (!oldKeys.has(key) || newConfig[key] !== oldConfig[key]) {
+                changedKeys.add(key);
+            }
+        }
+        for (const key of oldKeys) {
+            if (!newKeys.has(key)) {
+                changedKeys.add(key);
+            }
+        }
+        return changedKeys;
+    }
+    async fetchLatestConfig(remainingAttempts, targetVersion) {
+        const remainingAttemptsAfterFetch = remainingAttempts - 1;
+        const currentAttempt = MAXIMUM_FETCH_ATTEMPTS - remainingAttemptsAfterFetch;
+        const customSignals = this.storageCache.getCustomSignals();
+        if (customSignals) {
+            this.logger.debug(`Fetching config with custom signals: ${JSON.stringify(customSignals)}`);
+        }
+        const abortSignal = new RemoteConfigAbortSignal();
+        try {
+            const fetchRequest = {
+                cacheMaxAgeMillis: 0,
+                signal: abortSignal,
+                customSignals,
+                fetchType: 'REALTIME',
+                fetchAttempt: currentAttempt
+            };
+            const fetchResponse = await this.cachingClient.fetch(fetchRequest);
+            let activatedConfigs = await this.storage.getActiveConfig();
+            if (!this.fetchResponseIsUpToDate(fetchResponse, targetVersion)) {
+                this.logger.debug("Fetched template version is the same as SDK's current version." +
+                    ' Retrying fetch.');
+                // Continue fetching until template version number is greater than current.
+                await this.autoFetch(remainingAttemptsAfterFetch, targetVersion);
+                return;
+            }
+            if (fetchResponse.config == null) {
+                this.logger.debug('The fetch succeeded, but the backend had no updates.');
+                return;
+            }
+            if (activatedConfigs == null) {
+                activatedConfigs = {};
+            }
+            const updatedKeys = this.getChangedParams(fetchResponse.config, activatedConfigs);
+            if (updatedKeys.size === 0) {
+                this.logger.debug('Config was fetched, but no params changed.');
+                return;
+            }
+            const configUpdate = {
+                getUpdatedKeys() {
+                    return new Set(updatedKeys);
+                }
+            };
+            this.executeAllListenerCallbacks(configUpdate);
+        }
+        catch (e) {
+            const errorMessage = e instanceof Error ? e.message : String(e);
+            const error = ERROR_FACTORY.create("update-not-fetched" /* ErrorCode.CONFIG_UPDATE_NOT_FETCHED */, {
+                originalErrorMessage: `Failed to auto-fetch config update: ${errorMessage}`
+            });
+            this.propagateError(error);
+        }
+    }
+    async autoFetch(remainingAttempts, targetVersion) {
+        if (remainingAttempts === 0) {
+            const error = ERROR_FACTORY.create("update-not-fetched" /* ErrorCode.CONFIG_UPDATE_NOT_FETCHED */, {
+                originalErrorMessage: 'Unable to fetch the latest version of the template.'
+            });
+            this.propagateError(error);
+            return;
+        }
+        const timeTillFetchSeconds = this.getRandomInt(4);
+        const timeTillFetchInMiliseconds = timeTillFetchSeconds * 1000;
+        await new Promise(resolve => setTimeout(resolve, timeTillFetchInMiliseconds));
+        await this.fetchLatestConfig(remainingAttempts, targetVersion);
+    }
+    /**
+     * Processes a stream of real-time messages for configuration updates.
+     * This method reassembles fragmented messages, validates and parses the JSON,
+     * and automatically fetches a new config if a newer template version is available.
+     * It also handles server-specified retry intervals and propagates errors for
+     * invalid messages or when real-time updates are disabled.
+     */
+    async handleNotifications(reader) {
+        let partialConfigUpdateMessage;
+        let currentConfigUpdateMessage = '';
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            partialConfigUpdateMessage = this.decoder.decode(value, { stream: true });
+            currentConfigUpdateMessage += partialConfigUpdateMessage;
+            if (partialConfigUpdateMessage.includes('}')) {
+                currentConfigUpdateMessage = this.parseAndValidateConfigUpdateMessage(currentConfigUpdateMessage);
+                if (currentConfigUpdateMessage.length === 0) {
+                    continue;
+                }
+                try {
+                    const jsonObject = JSON.parse(currentConfigUpdateMessage);
+                    if (this.isEventListenersEmpty()) {
+                        break;
+                    }
+                    if (REALTIME_DISABLED_KEY in jsonObject &&
+                        jsonObject[REALTIME_DISABLED_KEY] === true) {
+                        const error = ERROR_FACTORY.create("realtime-unavailable" /* ErrorCode.CONFIG_UPDATE_UNAVAILABLE */, {
+                            originalErrorMessage: 'The server is temporarily unavailable. Try again in a few minutes.'
+                        });
+                        this.propagateError(error);
+                        break;
+                    }
+                    if (TEMPLATE_VERSION_KEY in jsonObject) {
+                        const oldTemplateVersion = await this.storage.getActiveConfigTemplateVersion();
+                        const targetTemplateVersion = Number(jsonObject[TEMPLATE_VERSION_KEY]);
+                        if (oldTemplateVersion &&
+                            targetTemplateVersion > oldTemplateVersion) {
+                            await this.autoFetch(MAXIMUM_FETCH_ATTEMPTS, targetTemplateVersion);
+                        }
+                    }
+                    // This field in the response indicates that the realtime request should retry after the
+                    // specified interval to establish a long-lived connection. This interval extends the
+                    // backoff duration without affecting the number of retries, so it will not enter an
+                    // exponential backoff state.
+                    if (REALTIME_RETRY_INTERVAL in jsonObject) {
+                        const retryIntervalSeconds = Number(jsonObject[REALTIME_RETRY_INTERVAL]);
+                        await this.updateBackoffMetadataWithRetryInterval(retryIntervalSeconds);
+                    }
+                }
+                catch (e) {
+                    this.logger.debug('Unable to parse latest config update message.', e);
+                    const errorMessage = e instanceof Error ? e.message : String(e);
+                    this.propagateError(ERROR_FACTORY.create("update-message-invalid" /* ErrorCode.CONFIG_UPDATE_MESSAGE_INVALID */, {
+                        originalErrorMessage: errorMessage
+                    }));
+                }
+                currentConfigUpdateMessage = '';
+            }
+        }
+    }
+    async listenForNotifications(reader) {
+        try {
+            await this.handleNotifications(reader);
+        }
+        catch (e) {
+            // If the real-time connection is at an unexpected lifecycle state when the app is
+            // backgrounded, it's expected closing the connection will throw an exception.
+            if (!this.isInBackground) {
+                // Otherwise, the real-time server connection was closed due to a transient issue.
+                this.logger.debug('Real-time connection was closed due to an exception.');
+            }
+        }
+    }
+    /**
+     * Open the real-time connection, begin listening for updates, and auto-fetch when an update is
+     * received.
+     *
+     * If the connection is successful, this method will block on its thread while it reads the
+     * chunk-encoded HTTP body. When the connection closes, it attempts to reestablish the stream.
+     */
+    async prepareAndBeginRealtimeHttpStream() {
+        if (!this.checkAndSetHttpConnectionFlagIfNotRunning()) {
+            return;
+        }
+        let backoffMetadata = await this.storage.getRealtimeBackoffMetadata();
+        if (!backoffMetadata) {
+            backoffMetadata = {
+                backoffEndTimeMillis: new Date(NO_BACKOFF_TIME_IN_MILLIS),
+                numFailedStreams: NO_FAILED_REALTIME_STREAMS
+            };
+        }
+        const backoffEndTime = backoffMetadata.backoffEndTimeMillis.getTime();
+        if (Date.now() < backoffEndTime) {
+            await this.retryHttpConnectionWhenBackoffEnds();
+            return;
+        }
+        let response;
+        let responseCode;
+        try {
+            response = await this.createRealtimeConnection();
+            responseCode = response.status;
+            if (response.ok && response.body) {
+                this.resetRetryCount();
+                await this.resetRealtimeBackoff();
+                const reader = response.body.getReader();
+                this.reader = reader;
+                // Start listening for realtime notifications.
+                await this.listenForNotifications(reader);
+            }
+        }
+        catch (error) {
+            if (this.isInBackground) {
+                // It's possible the app was backgrounded while the connection was open, which
+                // threw an exception trying to read the response. No real error here, so treat
+                // this as a success, even if we haven't read a 200 response code yet.
+                this.resetRetryCount();
+            }
+            else {
+                //there might have been a transient error so the client will retry the connection.
+                this.logger.debug('Exception connecting to real-time RC backend. Retrying the connection...:', error);
+            }
+        }
+        finally {
+            // Close HTTP connection and associated streams.
+            await this.closeRealtimeHttpConnection();
+            this.setIsHttpConnectionRunning(false);
+            // Update backoff metadata if the connection failed in the foreground.
+            const connectionFailed = !this.isInBackground &&
+                (responseCode === undefined ||
+                    this.isStatusCodeRetryable(responseCode));
+            if (connectionFailed) {
+                await this.updateBackoffMetadataWithLastFailedStreamConnectionTime(new Date());
+            }
+            // If responseCode is null then no connection was made to server and the SDK should still retry.
+            if (connectionFailed || response?.ok) {
+                await this.retryHttpConnectionWhenBackoffEnds();
+            }
+            else {
+                const errorMessage = `Unable to connect to the server. HTTP status code: ${responseCode}`;
+                const firebaseError = ERROR_FACTORY.create("stream-error" /* ErrorCode.CONFIG_UPDATE_STREAM_ERROR */, {
+                    originalErrorMessage: errorMessage
+                });
+                this.propagateError(firebaseError);
+            }
+        }
+    }
+    /**
+     * Checks whether connection can be made or not based on some conditions
+     * @returns booelean
+     */
+    canEstablishStreamConnection() {
+        const hasActiveListeners = this.observers.size > 0;
+        const isNotDisabled = !this.isRealtimeDisabled;
+        const isNoConnectionActive = !this.isConnectionActive;
+        const inForeground = !this.isInBackground;
+        return (hasActiveListeners &&
+            isNotDisabled &&
+            isNoConnectionActive &&
+            inForeground);
+    }
+    async makeRealtimeHttpConnection(delayMillis) {
+        if (!this.canEstablishStreamConnection()) {
+            return;
+        }
+        if (this.httpRetriesRemaining > 0) {
+            this.httpRetriesRemaining--;
+            await new Promise(resolve => setTimeout(resolve, delayMillis));
+            void this.prepareAndBeginRealtimeHttpStream();
+        }
+        else if (!this.isInBackground) {
+            const error = ERROR_FACTORY.create("stream-error" /* ErrorCode.CONFIG_UPDATE_STREAM_ERROR */, {
+                originalErrorMessage: 'Unable to connect to the server. Check your connection and try again.'
+            });
+            this.propagateError(error);
+        }
+    }
+    async beginRealtime() {
+        if (this.observers.size > 0) {
+            await this.makeRealtimeHttpConnection(0);
+        }
+    }
+    /**
+     * Adds an observer to the realtime updates.
+     * @param observer The observer to add.
+     */
+    addObserver(observer) {
+        this.observers.add(observer);
+        void this.beginRealtime();
+    }
+    /**
+     * Removes an observer from the realtime updates.
+     * @param observer The observer to remove.
+     */
+    removeObserver(observer) {
+        if (this.observers.has(observer)) {
+            this.observers.delete(observer);
+        }
+    }
+    /**
+     * Handles changes to the application's visibility state, managing the real-time connection.
+     *
+     * When the application is moved to the background, this method closes the existing
+     * real-time connection to save resources. When the application returns to the
+     * foreground, it attempts to re-establish the connection.
+     */
+    async onVisibilityChange(visible) {
+        this.isInBackground = !visible;
+        if (!visible) {
+            await this.closeRealtimeHttpConnection();
+        }
+        else if (visible) {
+            await this.beginRealtime();
+        }
+    }
+}
+
 /**
  * @license
  * Copyright 2020 Google LLC
@@ -1317,7 +2045,8 @@ function registerRemoteConfig() {
         app.SDK_VERSION, namespace, projectId, apiKey, appId);
         const retryingClient = new RetryingClient(restClient, storage);
         const cachingClient = new CachingClient(retryingClient, storage, storageCache, logger$1);
-        const remoteConfigInstance = new RemoteConfig(app$1, cachingClient, storageCache, storage, logger$1);
+        const realtimeHandler = new RealtimeHandler(installations, storage, app.SDK_VERSION, namespace, projectId, apiKey, appId, logger$1, storageCache, cachingClient);
+        const remoteConfigInstance = new RemoteConfig(app$1, cachingClient, storageCache, storage, logger$1, realtimeHandler);
         // Starts warming cache.
         // eslint-disable-next-line @typescript-eslint/no-floating-promises
         ensureInitialized(remoteConfigInstance);
@@ -1402,6 +2131,7 @@ exports.getRemoteConfig = getRemoteConfig;
 exports.getString = getString;
 exports.getValue = getValue;
 exports.isSupported = isSupported;
+exports.onConfigUpdate = onConfigUpdate;
 exports.setCustomSignals = setCustomSignals;
 exports.setLogLevel = setLogLevel;
 //# sourceMappingURL=index.cjs.js.map