9792644557

Committed 04 Jul 2024 10:21AM UTC coverage: 87.939%. First build

Build # 9792644557

Build Type

Pull #6743

github

Committed by

web-flow

Commit Message

Merge 62aa390ea into f8aefa20e

Pull Request Pull Request #6743: RJS-2636: Add progress notifications and tests

Run Details

1247 of 1493 branches covered (83.52%)

Branch coverage included in aggregate %.

17 of 21 new or added lines in 2 files covered. (80.95%)

2938 of 3266 relevant lines covered (89.96%)

1132.94 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

89.05

/packages/realm/src/ProgressRealmPromise.ts

////////////////////////////////////////////////////////////////////////////
//
// Copyright 2022 Realm Inc.
//
// 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.
//
////////////////////////////////////////////////////////////////////////////

import {
  Configuration,
  OpenRealmBehaviorType,
  OpenRealmTimeOutBehavior,
  ProgressNotificationCallback,
  PromiseHandle,
  Realm,
  SubscriptionSetState,
  TimeoutError,
  TimeoutPromise,
  assert,
  binding,
  flags,
  isEstimateProgressNotificationCallback,
  validateConfiguration,
} from "./internal";

type OpenBehavior = {
  openBehavior: OpenRealmBehaviorType;
  timeOut?: number;
  timeOutBehavior?: OpenRealmTimeOutBehavior;
};

function determineBehavior(config: Configuration, realmExists: boolean): OpenBehavior {
  const { sync, openSyncedRealmLocally } = config;
  if (!sync || openSyncedRealmLocally) {
    return { openBehavior: OpenRealmBehaviorType.OpenImmediately };
  } else {
    const configProperty = realmExists ? "existingRealmFileBehavior" : "newRealmFileBehavior";
    const configBehavior = sync[configProperty];
    if (configBehavior) {
      const { type, timeOut, timeOutBehavior } = configBehavior;
      if (typeof timeOut !== "undefined") {
        assert.number(timeOut, "timeOut");
      }
      return { openBehavior: type, timeOut, timeOutBehavior };
    } else {
      return {
        openBehavior: OpenRealmBehaviorType.DownloadBeforeOpen,
        timeOut: 30 * 1000,
        timeOutBehavior: OpenRealmTimeOutBehavior.ThrowException,
      };
    }
  }
}

export class ProgressRealmPromise implements Promise<Realm> {
  /** @internal */
  private static instances = new Set<binding.WeakRef<ProgressRealmPromise>>();
  /**
   * Cancels all unresolved `ProgressRealmPromise` instances.
   * @internal
   */
  public static cancelAll() {
    for (const promiseRef of ProgressRealmPromise.instances) {
      promiseRef.deref()?.cancel();
    }
    ProgressRealmPromise.instances.clear();
  }
  /** @internal */
  private task: binding.AsyncOpenTask | null = null;
  /** @internal */
  private listeners = new Set<ProgressNotificationCallback>();
  /** @internal */
  private handle = new PromiseHandle<Realm>();
  /** @internal */
  private timeoutPromise: TimeoutPromise<Realm> | null = null;
  /**
   * Token used for unregistering the progress notifier.
   * @internal
   */
  private notifierToken: binding.Int64 | null = null;

  /** @internal */
  constructor(config: Configuration) {
    if (flags.ALLOW_CLEAR_TEST_STATE) {
      ProgressRealmPromise.instances.add(new binding.WeakRef(this));
    }
    try {
      validateConfiguration(config);
      // Calling `Realm.exists()` before `binding.Realm.getSynchronizedRealm()` is necessary to capture
      // the correct value when this constructor was called since `binding.Realm.getSynchronizedRealm()`
      // will open the realm. This is needed when calling the Realm constructor.
      const realmExists = Realm.exists(config);
      const { openBehavior, timeOut, timeOutBehavior } = determineBehavior(config, realmExists);
      if (openBehavior === OpenRealmBehaviorType.OpenImmediately) {
        const realm = new Realm(config);
        this.handle.resolve(realm);
      } else if (openBehavior === OpenRealmBehaviorType.DownloadBeforeOpen) {
        const { bindingConfig } = Realm.transformConfig(config);

        // Construct an async open task
        this.task = binding.Realm.getSynchronizedRealm(bindingConfig);
        // If the promise handle gets rejected, we should cancel the open task
        // to avoid consuming a thread safe reference which is no longer registered
        this.handle.promise.catch(() => this.task?.cancel());

        this.createTimeoutPromise(config, { openBehavior, timeOut, timeOutBehavior });

        this.task
          .start()
          .then(async (tsr) => {
            const realm = new Realm(config, {
              internal: binding.Helpers.consumeThreadSafeReferenceToSharedRealm(tsr),
              // Do not call `Realm.exists()` here in case the realm has been opened by this point in time.
              realmExists,
            });
            if (config.sync?.flexible && !config.openSyncedRealmLocally) {
              const { subscriptions } = realm;
              if (subscriptions.state === SubscriptionSetState.Pending) {
                await subscriptions.waitForSynchronization();
              }
            }
            return realm;
          })
          .then(this.handle.resolve, (err) => {
            assert.undefined(err.code, "Update this to use the error code instead of matching on message");
            if (err instanceof Error && err.message === "Sync session became inactive") {
              // This can happen when two async tasks are opened for the same Realm and one gets canceled
              this.rejectAsCanceled();
            } else {
              this.handle.reject(err);
            }
          });
        this.notifierToken = this.task.registerDownloadProgressNotifier(this.emitProgress.bind(this));
      } else {
        throw new Error(`Unexpected open behavior '${openBehavior}'`);
      }
    } catch (err) {
      if (this.notifierToken !== null) {
        this.task?.unregisterDownloadProgressNotifier(this.notifierToken);
        this.notifierToken = null;
      }
      this.handle.reject(err);
    }
  }

  /**
   * Cancels the download of the Realm
   * If multiple `ProgressRealmPromise` instances are in progress for the same Realm, then canceling one of them
   * will cancel all of them.
   */
  cancel(): void {
    this.cancelAndResetTask();
    this.timeoutPromise?.cancel();
    if (this.notifierToken !== null) {
      this.task?.unregisterDownloadProgressNotifier(this.notifierToken);
      this.notifierToken = null;
    }
    // Clearing all listeners to avoid accidental progress notifications
    this.listeners.clear();
    // Tell anything awaiting the promise
    this.rejectAsCanceled();
  }

  /**
   * Register to receive progress notifications while the download is in progress.
   * @param callback Called multiple times as the client receives data.
   */
  progress(callback: ProgressNotificationCallback): this {
    this.listeners.add(callback);
    if (isEstimateProgressNotificationCallback(callback)) {
      callback(1.0);
    } else {
      callback(0.0, 0.0);
    }
    return this;
  }

  then = this.handle.promise.then.bind(this.handle.promise);
  catch = this.handle.promise.catch.bind(this.handle.promise);
  finally = this.handle.promise.finally.bind(this.handle.promise);

  /** @internal */
  private emitProgress(transferredArg: binding.Int64, transferableArg: binding.Int64, progressEstimate: number) {
    const transferred = binding.Int64.intToNum(transferredArg);
    const transferable = binding.Int64.intToNum(transferableArg);
    for (const listener of this.listeners) {
      if (isEstimateProgressNotificationCallback(listener)) {
        listener(progressEstimate);
      } else {
        listener(transferred, transferable);
      }
    }
  }

  /** @internal */
  private createTimeoutPromise(config: Configuration, { timeOut, timeOutBehavior }: OpenBehavior) {
    if (typeof timeOut === "number") {
      this.timeoutPromise = new TimeoutPromise(
        this.handle.promise, // Ensures the timeout gets cancelled when the realm opens
        {
          ms: timeOut,
          message: `Realm could not be downloaded in the allocated time: ${timeOut} ms.`,
        },
      );
      if (timeOutBehavior === OpenRealmTimeOutBehavior.ThrowException) {
        // Make failing the timeout, reject the promise
        this.timeoutPromise.catch(this.handle.reject);
      } else if (timeOutBehavior === OpenRealmTimeOutBehavior.OpenLocalRealm) {
        // Make failing the timeout, resolve the promise
        this.timeoutPromise.catch((err) => {
          if (err instanceof TimeoutError) {
            this.cancelAndResetTask();
            const realm = new Realm(config);
            this.handle.resolve(realm);
          } else {
            this.handle.reject(err);
          }
        });
      } else {
        throw new Error(
          `Invalid 'timeOutBehavior': '${timeOutBehavior}'. Only 'throwException' and 'openLocalRealm' is allowed.`,
        );
      }
    }
  }

  /** @internal */
  private cancelAndResetTask() {
    if (this.task) {
      this.task.cancel();
      this.task.$resetSharedPtr();
      this.task = null;
    }
  }

  /** @internal */
  private rejectAsCanceled() {
    const err = new Error("Async open canceled");
    this.handle.reject(err);
  }

  get [Symbol.toStringTag]() {
    return ProgressRealmPromise.name;
  }
}

1	////////////////////////////////////////////////////////////////////////////
2	//
3	// Copyright 2022 Realm Inc.
4	//
5	// Licensed under the Apache License, Version 2.0 (the "License");
6	// you may not use this file except in compliance with the License.
7	// You may obtain a copy of the License at
8	//
9	// http://www.apache.org/licenses/LICENSE-2.0
10	//
11	// Unless required by applicable law or agreed to in writing, software
12	// distributed under the License is distributed on an "AS IS" BASIS,
13	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14	// See the License for the specific language governing permissions and
15	// limitations under the License.
16	//
17	////////////////////////////////////////////////////////////////////////////
18
19	import {	1✔
20	Configuration,
21	OpenRealmBehaviorType,
22	OpenRealmTimeOutBehavior,
23	ProgressNotificationCallback,
24	PromiseHandle,
25	Realm,
26	SubscriptionSetState,
27	TimeoutError,
28	TimeoutPromise,
29	assert,
30	binding,
31	flags,
32	isEstimateProgressNotificationCallback,
33	validateConfiguration,
34	} from "./internal";
35
36	type OpenBehavior = {
37	openBehavior: OpenRealmBehaviorType;
38	timeOut?: number;
39	timeOutBehavior?: OpenRealmTimeOutBehavior;
40	};
41
42	function determineBehavior(config: Configuration, realmExists: boolean): OpenBehavior {
43	const { sync, openSyncedRealmLocally } = config;	740✔
44	if (!sync \|\| openSyncedRealmLocally) {	740✔
45	return { openBehavior: OpenRealmBehaviorType.OpenImmediately };	425✔
46	} else {
47	const configProperty = realmExists ? "existingRealmFileBehavior" : "newRealmFileBehavior";	315✔
48	const configBehavior = sync[configProperty];	315✔
49	if (configBehavior) {	315✔
50	const { type, timeOut, timeOutBehavior } = configBehavior;	15✔
51	if (typeof timeOut !== "undefined") {	15✔
52	assert.number(timeOut, "timeOut");	5✔
53	}
54	return { openBehavior: type, timeOut, timeOutBehavior };	15✔
55	} else {
56	return {	300✔
57	openBehavior: OpenRealmBehaviorType.DownloadBeforeOpen,
58	timeOut: 30 * 1000,
59	timeOutBehavior: OpenRealmTimeOutBehavior.ThrowException,
60	};
61	}
62	}
63	}
64
65	export class ProgressRealmPromise implements Promise<Realm> {	1✔
66	/** @internal */
67	private static instances = new Set<binding.WeakRef<ProgressRealmPromise>>();	1✔
68	/**
69	* Cancels all unresolved `ProgressRealmPromise` instances.
70	* @internal
71	*/
72	public static cancelAll() {
73	for (const promiseRef of ProgressRealmPromise.instances) {	973✔
74	promiseRef.deref()?.cancel();	747✔
75	}
76	ProgressRealmPromise.instances.clear();	973✔
77	}
78	/** @internal */
79	private task: binding.AsyncOpenTask \| null = null;	747✔
80	/** @internal */
81	private listeners = new Set<ProgressNotificationCallback>();	747✔
82	/** @internal */
83	private handle = new PromiseHandle<Realm>();	747✔
84	/** @internal */
85	private timeoutPromise: TimeoutPromise<Realm> \| null = null;	747✔
86	/**
87	* Token used for unregistering the progress notifier.
88	* @internal
89	*/
90	private notifierToken: binding.Int64 \| null = null;	747✔
91
92	/** @internal */
93	constructor(config: Configuration) {
94	if (flags.ALLOW_CLEAR_TEST_STATE) {	747!
95	ProgressRealmPromise.instances.add(new binding.WeakRef(this));	747✔
96	}
97	try {	747✔
98	validateConfiguration(config);	747✔
99	// Calling `Realm.exists()` before `binding.Realm.getSynchronizedRealm()` is necessary to capture
100	// the correct value when this constructor was called since `binding.Realm.getSynchronizedRealm()`
101	// will open the realm. This is needed when calling the Realm constructor.
102	const realmExists = Realm.exists(config);	740✔
103	const { openBehavior, timeOut, timeOutBehavior } = determineBehavior(config, realmExists);	740✔
104	if (openBehavior === OpenRealmBehaviorType.OpenImmediately) {	740✔
105	const realm = new Realm(config);	430✔
106	this.handle.resolve(realm);	430✔
107	} else if (openBehavior === OpenRealmBehaviorType.DownloadBeforeOpen) {	310!
108	const { bindingConfig } = Realm.transformConfig(config);	310✔
109
110	// Construct an async open task
111	this.task = binding.Realm.getSynchronizedRealm(bindingConfig);	310✔
112	// If the promise handle gets rejected, we should cancel the open task
113	// to avoid consuming a thread safe reference which is no longer registered
114	this.handle.promise.catch(() => this.task?.cancel());	310✔
115
116	this.createTimeoutPromise(config, { openBehavior, timeOut, timeOutBehavior });	310✔
117
118	this.task	310✔
119	.start()
120	.then(async (tsr) => {
121	const realm = new Realm(config, {	298✔
122	internal: binding.Helpers.consumeThreadSafeReferenceToSharedRealm(tsr),
123	// Do not call `Realm.exists()` here in case the realm has been opened by this point in time.
124	realmExists,
125	});
126	if (config.sync?.flexible && !config.openSyncedRealmLocally) {	298✔
127	const { subscriptions } = realm;	225✔
128	if (subscriptions.state === SubscriptionSetState.Pending) {	225✔
129	await subscriptions.waitForSynchronization();	7✔
130	}
131	}
132	return realm;	298✔
133	})
134	.then(this.handle.resolve, (err) => {
135	assert.undefined(err.code, "Update this to use the error code instead of matching on message");	3✔
136	if (err instanceof Error && err.message === "Sync session became inactive") {	3✔
137	// This can happen when two async tasks are opened for the same Realm and one gets canceled
138	this.rejectAsCanceled();	1✔
139	} else {
140	this.handle.reject(err);	2✔
141	}
142	});
143	this.notifierToken = this.task.registerDownloadProgressNotifier(this.emitProgress.bind(this));	310✔
144	} else {
145	throw new Error(`Unexpected open behavior '${openBehavior}'`);	×
146	}
147	} catch (err) {
148	if (this.notifierToken !== null) {	7!
NEW 149	this.task?.unregisterDownloadProgressNotifier(this.notifierToken);	×
NEW 150	this.notifierToken = null;	×
151	}
152	this.handle.reject(err);	7✔
153	}
154	}
155
156	/**
157	* Cancels the download of the Realm
158	* If multiple `ProgressRealmPromise` instances are in progress for the same Realm, then canceling one of them
159	* will cancel all of them.
160	*/
161	cancel(): void {
162	this.cancelAndResetTask();	649✔
163	this.timeoutPromise?.cancel();	649✔
164	if (this.notifierToken !== null) {	649✔
165	this.task?.unregisterDownloadProgressNotifier(this.notifierToken);	228✔
166	this.notifierToken = null;	228✔
167	}
168	// Clearing all listeners to avoid accidental progress notifications
169	this.listeners.clear();	649✔
170	// Tell anything awaiting the promise
171	this.rejectAsCanceled();	649✔
172	}
173
174	/**
175	* Register to receive progress notifications while the download is in progress.
176	* @param callback Called multiple times as the client receives data.
177	*/
178	progress(callback: ProgressNotificationCallback): this {
179	this.listeners.add(callback);	2✔
180	if (isEstimateProgressNotificationCallback(callback)) {	2!
NEW 181	callback(1.0);	×
182	} else {
183	callback(0.0, 0.0);	2✔
184	}
185	return this;	2✔
186	}
187
188	then = this.handle.promise.then.bind(this.handle.promise);	747✔
189	catch = this.handle.promise.catch.bind(this.handle.promise);	747✔
190	finally = this.handle.promise.finally.bind(this.handle.promise);	747✔
191
192	/** @internal */
193	private emitProgress(transferredArg: binding.Int64, transferableArg: binding.Int64, progressEstimate: number) {
194	const transferred = binding.Int64.intToNum(transferredArg);	64✔
195	const transferable = binding.Int64.intToNum(transferableArg);	64✔
196	for (const listener of this.listeners) {	64✔
197	if (isEstimateProgressNotificationCallback(listener)) {	1!
NEW 198	listener(progressEstimate);	×
199	} else {
200	listener(transferred, transferable);	1✔
201	}
202	}
203	}
204
205	/** @internal */
206	private createTimeoutPromise(config: Configuration, { timeOut, timeOutBehavior }: OpenBehavior) {
207	if (typeof timeOut === "number") {	310✔
208	this.timeoutPromise = new TimeoutPromise(	305✔
209	this.handle.promise, // Ensures the timeout gets cancelled when the realm opens
210	{
211	ms: timeOut,
212	message: `Realm could not be downloaded in the allocated time: ${timeOut} ms.`,
213	},
214	);
215	if (timeOutBehavior === OpenRealmTimeOutBehavior.ThrowException) {	305✔
216	// Make failing the timeout, reject the promise
217	this.timeoutPromise.catch(this.handle.reject);	302✔
218	} else if (timeOutBehavior === OpenRealmTimeOutBehavior.OpenLocalRealm) {	3!
219	// Make failing the timeout, resolve the promise
220	this.timeoutPromise.catch((err) => {	3✔
221	if (err instanceof TimeoutError) {	2!
222	this.cancelAndResetTask();	2✔
223	const realm = new Realm(config);	2✔
224	this.handle.resolve(realm);	2✔
225	} else {
226	this.handle.reject(err);	×
227	}
228	});
229	} else {
230	throw new Error(	×
231	`Invalid 'timeOutBehavior': '${timeOutBehavior}'. Only 'throwException' and 'openLocalRealm' is allowed.`,
232	);
233	}
234	}
235	}
236
237	/** @internal */
238	private cancelAndResetTask() {
239	if (this.task) {	651✔
240	this.task.cancel();	228✔
241	this.task.$resetSharedPtr();	228✔
242	this.task = null;	228✔
243	}
244	}
245
246	/** @internal */
247	private rejectAsCanceled() {
248	const err = new Error("Async open canceled");	650✔
249	this.handle.reject(err);	650✔
250	}
251
252	get [Symbol.toStringTag]() {
253	return ProgressRealmPromise.name;	×
254	}
255	}

realm / realm-js / 9792644557

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous