feat: Add Parse Server option cleanupInvalidInstallations to remove invalid device tokens

spec/PushWorker.spec.js

@@ -271,6 +271,69 @@ describe('PushWorker', () => {
       toAwait.then(done).catch(done);
     });
 
+    describe('option cleanupInvalidInstallations', () => {
+      const results = [
+        {
+          transmitted: false,
+          device: { deviceToken: 'invalid-token', deviceType: 'ios' },
+          response: { error: 'Unregistered' },
+        },
+        {
+          transmitted: true,
+          device: { deviceToken: 'valid-token', deviceType: 'ios' },
+        },
+      ];
+
+      const installationUpdates = spy =>
+        spy.calls.allArgs().filter(args => args[0] === '_Installation');
+
+      it('removes device tokens of invalid installations if set to true', async () => {
+        await reconfigureServer({ cleanupInvalidInstallations: true });
+        const config = Config.get('test');
+        const spy = spyOn(config.database, 'update').and.callFake(() => Promise.resolve({}));
+        await pushStatusHandler(config).trackSent(results);
+        const calls = installationUpdates(spy);
+        expect(calls.length).toBe(1);
+        const args = calls[0];
+        expect(args[1]).toEqual({ deviceToken: { $in: ['invalid-token'] } });
+        expect(args[2]).toEqual({ deviceToken: { __op: 'Delete' } });
+      });
+
+      it('does not remove device tokens of invalid installations if set to false', async () => {
+        await reconfigureServer({ cleanupInvalidInstallations: false });
+        const config = Config.get('test');
+        const spy = spyOn(config.database, 'update').and.callFake(() => Promise.resolve({}));
+        await pushStatusHandler(config).trackSent(results);
+        expect(installationUpdates(spy).length).toBe(0);
+      });
+
+      it('option takes precedence over the environment variable', async () => {
+        process.env.PARSE_SERVER_CLEANUP_INVALID_INSTALLATIONS = 'true';
+        try {
+          await reconfigureServer({ cleanupInvalidInstallations: false });
+          const config = Config.get('test');
+          const spy = spyOn(config.database, 'update').and.callFake(() => Promise.resolve({}));
+          await pushStatusHandler(config).trackSent(results);
+          expect(installationUpdates(spy).length).toBe(0);
+        } finally {
+          delete process.env.PARSE_SERVER_CLEANUP_INVALID_INSTALLATIONS;
+        }
+      });
+
+      it('falls back to the environment variable if the option is not set', async () => {
+        process.env.PARSE_SERVER_CLEANUP_INVALID_INSTALLATIONS = 'true';
+        try {
+          await reconfigureServer();
+          const config = Config.get('test');
+          const spy = spyOn(config.database, 'update').and.callFake(() => Promise.resolve({}));
+          await pushStatusHandler(config).trackSent(results);
+          expect(installationUpdates(spy).length).toBe(1);
+        } finally {
+          delete process.env.PARSE_SERVER_CLEANUP_INVALID_INSTALLATIONS;
+        }
+      });
+    });
+
     it_id('764d28ab-241b-4b96-8ce9-e03541850e3f')(it)('tracks push status per UTC offsets', done => {
       const config = Config.get('test');
       const handler = pushStatusHandler(config);

src/Options/Definitions.js

@@ -128,6 +128,11 @@ module.exports.ParseServerOptions = {
     action: parsers.numberParser('cacheTTL'),
     default: 5000,
   },
+  cleanupInvalidInstallations: {
+    env: 'PARSE_SERVER_CLEANUP_INVALID_INSTALLATIONS',
+    help: 'Optional. If set to `true`, the `deviceToken` of an installation is removed when a push notification to that device fails because the push provider reports the token as invalid or unregistered (for example `Unregistered` or `BadDeviceToken` for APNS, `NotRegistered` or `InvalidRegistration` for FCM). This avoids repeatedly sending to devices that are known to be unreachable, which push providers may penalize. Note that the removal is based on error responses of the push provider, so valid tokens may be removed if the provider reports an error incorrectly. If `false`, installations are not modified. Defaults to the value of the environment variable `PARSE_SERVER_CLEANUP_INVALID_INSTALLATIONS`, otherwise `false`.',
+    action: parsers.booleanParser,
+  },
   clientKey: {
     env: 'PARSE_SERVER_CLIENT_KEY',
     help: 'Key for iOS, MacOS, tvOS clients',

src/Options/index.js

@@ -99,6 +99,8 @@ export interface ParseServerOptions {
   filesAdapter: ?Adapter<FilesAdapter>;
   /* Configuration for push, as stringified JSON. See http://docs.parseplatform.org/parse-server/guide/#push-notifications */
   push: ?any;
+  /* Optional. If set to `true`, the `deviceToken` of an installation is removed when a push notification to that device fails because the push provider reports the token as invalid or unregistered (for example `Unregistered` or `BadDeviceToken` for APNS, `NotRegistered` or `InvalidRegistration` for FCM). This avoids repeatedly sending to devices that are known to be unreachable, which push providers may penalize. Note that the removal is based on error responses of the push provider, so valid tokens may be removed if the provider reports an error incorrectly. If `false`, installations are not modified. Defaults to the value of the environment variable `PARSE_SERVER_CLEANUP_INVALID_INSTALLATIONS`, otherwise `false`. */
+  cleanupInvalidInstallations: ?boolean;
   /* Configuration for push scheduling, defaults to false.
   :DEFAULT: false */
   scheduledPush: ?boolean;

src/StatusHandler.js

@@ -200,7 +200,8 @@ export function pushStatusHandler(config, existingObjectId) {
   const trackSent = function (
     results,
     UTCOffset,
-    cleanupInstallations = process.env.PARSE_SERVER_CLEANUP_INVALID_INSTALLATIONS
+    cleanupInstallations = config.cleanupInvalidInstallations ??
+      process.env.PARSE_SERVER_CLEANUP_INVALID_INSTALLATIONS
   ) {
     const update = {
       numSent: 0,

types/Options/index.d.ts

@@ -56,6 +56,7 @@ export interface ParseServerOptions {
     analyticsAdapter?: Adapter<AnalyticsAdapter>;
     filesAdapter?: Adapter<FilesAdapter>;
     push?: any;
+    cleanupInvalidInstallations?: boolean;
     scheduledPush?: boolean;
     loggerAdapter?: Adapter<LoggerAdapter>;
     jsonLogs?: boolean;