Switch to allow/denylist (#2325)

packages/workbox-build/src/lib/populate-sw-template.js

@@ -24,8 +24,8 @@ module.exports = ({
   importScripts,
   manifestEntries = [],
   navigateFallback,
-  navigateFallbackBlacklist,
-  navigateFallbackWhitelist,
+  navigateFallbackDenylist,
+  navigateFallbackAllowlist,
   navigationPreload,
   offlineGoogleAnalytics,
   runtimeCaching = [],
@@ -78,8 +78,8 @@ module.exports = ({
       importScripts,
       manifestEntries,
       navigateFallback,
-      navigateFallbackBlacklist,
-      navigateFallbackWhitelist,
+      navigateFallbackDenylist,
+      navigateFallbackAllowlist,
       navigationPreload,
       offlineAnalyticsConfigString,
       precacheOptionsString,

packages/workbox-build/src/lib/write-sw-using-default-template.js

@@ -26,8 +26,8 @@ module.exports = async ({
   manifestEntries,
   mode,
   navigateFallback,
-  navigateFallbackBlacklist,
-  navigateFallbackWhitelist,
+  navigateFallbackDenylist,
+  navigateFallbackAllowlist,
   navigationPreload,
   offlineGoogleAnalytics,
   runtimeCaching,
@@ -53,8 +53,8 @@ module.exports = async ({
     importScripts,
     manifestEntries,
     navigateFallback,
-    navigateFallbackBlacklist,
-    navigateFallbackWhitelist,
+    navigateFallbackDenylist,
+    navigateFallbackAllowlist,
     navigationPreload,
     offlineGoogleAnalytics,
     runtimeCaching,

packages/workbox-build/src/options/partials/generate.js

@@ -23,8 +23,12 @@ module.exports = {
   importScripts: joi.array().items(joi.string()),
   inlineWorkboxRuntime: joi.boolean().default(defaults.inlineWorkboxRuntime),
   navigateFallback: joi.string().default(defaults.navigateFallback),
-  navigateFallbackBlacklist: joi.array().items(regExpObject),
-  navigateFallbackWhitelist: joi.array().items(regExpObject),
+  navigateFallbackAllowlist: joi.array().items(regExpObject),
+  navigateFallbackBlacklist: joi.forbidden().error(new Error(
+      'navigateFallbackBlacklist has been renamed navigateFallbackDenylist.')),
+  navigateFallbackDenylist: joi.array().items(regExpObject),
+  navigateFallbackWhitelist: joi.forbidden().error(new Error(
+      'navigateFallbackWhitelist has been renamed navigateFallbackAllowlist.')),
   navigationPreload: joi.boolean().default(defaults.navigationPreload),
   offlineGoogleAnalytics: joi.alternatives().try(joi.boolean(), joi.object())
       .default(defaults.offlineGoogleAnalytics),

packages/workbox-build/src/templates/sw-template.js

@@ -47,9 +47,9 @@ self.addEventListener('message', (event) => {
  */
 <%= use('workbox-precaching', 'precacheAndRoute') %>(<%= JSON.stringify(manifestEntries, null, 2) %>, <%= precacheOptionsString %>);
 <% if (cleanupOutdatedCaches) { %><%= use('workbox-precaching', 'cleanupOutdatedCaches') %>();<% } %>
-<% if (navigateFallback) { %><%= use('workbox-routing', 'registerRoute') %>(new <%= use('workbox-routing', 'NavigationRoute') %>(<%= use('workbox-precaching', 'createHandlerBoundToURL') %>(<%= JSON.stringify(navigateFallback) %>)<% if (navigateFallbackWhitelist || navigateFallbackBlacklist) { %>, {
-  <% if (navigateFallbackWhitelist) { %>whitelist: [<%= navigateFallbackWhitelist %>],<% } %>
-  <% if (navigateFallbackBlacklist) { %>blacklist: [<%= navigateFallbackBlacklist %>],<% } %>
+<% if (navigateFallback) { %><%= use('workbox-routing', 'registerRoute') %>(new <%= use('workbox-routing', 'NavigationRoute') %>(<%= use('workbox-precaching', 'createHandlerBoundToURL') %>(<%= JSON.stringify(navigateFallback) %>)<% if (navigateFallbackAllowlist || navigateFallbackDenylist) { %>, {
+  <% if (navigateFallbackAllowlist) { %>allowlist: [<%= navigateFallbackAllowlist %>],<% } %>
+  <% if (navigateFallbackDenylist) { %>denylist: [<%= navigateFallbackDenylist %>],<% } %>
 }<% } %>));<% } %>
 <% } %>
 

packages/workbox-routing/src/NavigationRoute.ts

@@ -13,8 +13,8 @@ import {Handler, MatchCallbackOptions} from './_types.js';
 import './_version.js';
 
 export interface NavigationRouteMatchOptions {
-  whitelist?: RegExp[],
-  blacklist?: RegExp[],
+  allowlist?: RegExp[],
+  denylist?: RegExp[],
 }
 
 /**
@@ -27,20 +27,20 @@ export interface NavigationRouteMatchOptions {
  * is set to `navigate`.
  *
  * You can optionally only apply this route to a subset of navigation requests
- * by using one or both of the `blacklist` and `whitelist` parameters.
+ * by using one or both of the `denylist` and `allowlist` parameters.
  *
  * @memberof workbox.routing
  * @extends workbox.routing.Route
  */
 class NavigationRoute extends Route {
-  private _whitelist: RegExp[];
-  private _blacklist: RegExp[];
+  private _allowlist: RegExp[];
+  private _denylist: RegExp[];
 
   /**
-   * If both `blacklist` and `whiltelist` are provided, the `blacklist` will
+   * If both `denylist` and `allowlist` are provided, the `denylist` will
    * take precedence and the request will not match this route.
    *
-   * The regular expressions in `whitelist` and `blacklist`
+   * The regular expressions in `allowlist` and `denylist`
    * are matched against the concatenated
    * [`pathname`]{@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/pathname}
    * and [`search`]{@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/search}
@@ -49,33 +49,33 @@ class NavigationRoute extends Route {
    * @param {workbox.routing.Route~handlerCallback} handler A callback
    * function that returns a Promise resulting in a Response.
    * @param {Object} options
-   * @param {Array<RegExp>} [options.blacklist] If any of these patterns match,
-   * the route will not handle the request (even if a whitelist RegExp matches).
-   * @param {Array<RegExp>} [options.whitelist=[/./]] If any of these patterns
+   * @param {Array<RegExp>} [options.denylist] If any of these patterns match,
+   * the route will not handle the request (even if a allowlist RegExp matches).
+   * @param {Array<RegExp>} [options.allowlist=[/./]] If any of these patterns
    * match the URL's pathname and search parameter, the route will handle the
-   * request (assuming the blacklist doesn't match).
+   * request (assuming the denylist doesn't match).
    */
   constructor(handler: Handler,
-      {whitelist = [/./], blacklist = []}: NavigationRouteMatchOptions = {}) {
+      {allowlist = [/./], denylist = []}: NavigationRouteMatchOptions = {}) {
     if (process.env.NODE_ENV !== 'production') {
-      assert!.isArrayOfClass(whitelist, RegExp, {
+      assert!.isArrayOfClass(allowlist, RegExp, {
         moduleName: 'workbox-routing',
         className: 'NavigationRoute',
         funcName: 'constructor',
-        paramName: 'options.whitelist',
+        paramName: 'options.allowlist',
       });
-      assert!.isArrayOfClass(blacklist, RegExp, {
+      assert!.isArrayOfClass(denylist, RegExp, {
         moduleName: 'workbox-routing',
         className: 'NavigationRoute',
         funcName: 'constructor',
-        paramName: 'options.blacklist',
+        paramName: 'options.denylist',
       });
     }
 
     super((options: MatchCallbackOptions) => this._match(options), handler);
 
-    this._whitelist = whitelist;
-    this._blacklist = blacklist;
+    this._allowlist = allowlist;
+    this._denylist = denylist;
   }
 
   /**
@@ -95,18 +95,18 @@ class NavigationRoute extends Route {
 
     const pathnameAndSearch = url.pathname + url.search;
 
-    for (const regExp of this._blacklist) {
+    for (const regExp of this._denylist) {
       if (regExp.test(pathnameAndSearch)) {
         if (process.env.NODE_ENV !== 'production') {
           logger.log(`The navigation route ${pathnameAndSearch} is not ` +
-              `being used, since the URL matches this blacklist pattern: ` +
+              `being used, since the URL matches this denylist pattern: ` +
               `${regExp}`);
         }
         return false;
       }
     }
 
-    if (this._whitelist.some((regExp) => regExp.test(pathnameAndSearch))) {
+    if (this._allowlist.some((regExp) => regExp.test(pathnameAndSearch))) {
       if (process.env.NODE_ENV !== 'production') {
         logger.debug(`The navigation route ${pathnameAndSearch} ` +
             `is being used.`);
@@ -117,7 +117,7 @@ class NavigationRoute extends Route {
     if (process.env.NODE_ENV !== 'production') {
       logger.log(`The navigation route ${pathnameAndSearch} is not ` +
           `being used, since the URL being navigated to doesn't ` +
-          `match the whitelist.`);
+          `match the allowlist.`);
     }
     return false;
   }

test/workbox-build/node/generate-sw.js

@@ -48,8 +48,8 @@ describe(`[workbox-build] generate-sw.js (End to End)`, function() {
     'mode',
     'modifyURLPrefix',
     'navigateFallback',
-    'navigateFallbackBlacklist',
-    'navigateFallbackWhitelist',
+    'navigateFallbackDenylist',
+    'navigateFallbackAllowlist',
     'navigationPreload',
     'offlineGoogleAnalytics',
     'runtimeCaching',
@@ -395,12 +395,12 @@ describe(`[workbox-build] generate-sw.js (End to End)`, function() {
       const outputDir = tempy.directory();
       const swDest = upath.join(outputDir, 'sw.js');
       const navigateFallback = 'test.html';
-      const navigateFallbackBlacklist = [/test1/, /test2/];
-      const navigateFallbackWhitelist = [/test3/, /test4/];
+      const navigateFallbackDenylist = [/test1/, /test2/];
+      const navigateFallbackAllowlist = [/test3/, /test4/];
       const options = Object.assign({}, BASE_OPTIONS, {
         navigateFallback,
-        navigateFallbackBlacklist,
-        navigateFallbackWhitelist,
+        navigateFallbackDenylist,
+        navigateFallbackAllowlist,
         swDest,
       });
 
@@ -435,8 +435,8 @@ describe(`[workbox-build] generate-sw.js (End to End)`, function() {
         }], {}]],
         registerRoute: [[{name: 'NavigationRoute'}]],
         NavigationRoute: [['/urlWithCacheKey', {
-          blacklist: navigateFallbackBlacklist,
-          whitelist: navigateFallbackWhitelist,
+          denylist: navigateFallbackDenylist,
+          allowlist: navigateFallbackAllowlist,
         }]],
       }});
     });
@@ -1092,6 +1092,29 @@ describe(`[workbox-build] generate-sw.js (End to End)`, function() {
   });
 
   describe(`[workbox-build] removed options`, function() {
+    // These were removed in v5.
+    const navigateFallbackOptions = {
+      navigateFallbackBlacklist: [],
+      navigateFallbackWhitelist: [],
+    };
+
+    for (const [option, value] of Object.entries(navigateFallbackOptions)) {
+      it(`should fail validation when ${option} is used`, async function() {
+        const options = Object.assign({}, BASE_OPTIONS, {
+          [option]: value,
+        });
+
+        try {
+          await generateSW(options);
+          throw new Error('Unexpected success.');
+        } catch (error) {
+          // They fail by throwing an Error with a custom message,
+          // not a ValidationError.
+          expect(error.message).to.include(option);
+        }
+      });
+    }
+
     // These were deprecated in v4, and formally removed in v5.
     const oldOptionsToValue = {
       dontCacheBustUrlsMatching: /ignored/,

test/workbox-build/node/get-manifest.js

@@ -39,7 +39,7 @@ describe(`[workbox-build] get-manifest.js (End to End)`, function() {
     'importWorkboxFrom',
     'injectionPointRegexp',
     'navigateFallback',
-    'navigateFallbackWhitelist',
+    'navigateFallbackAllowlist',
     'runtimeCaching',
     'skipWaiting',
     'swSrc',

test/workbox-build/node/inject-manifest.js

@@ -49,7 +49,7 @@ describe(`[workbox-build] inject-manifest.js (End to End)`, function() {
     'importScripts',
     'importWorkboxFrom',
     'navigateFallback',
-    'navigateFallbackWhitelist',
+    'navigateFallbackAllowlist',
     'runtimeCaching',
     'skipWaiting',
   ];

test/workbox-build/node/lib/populate-sw-template.js

@@ -75,8 +75,8 @@ describe(`[workbox-build] lib/populate-sw-template.js`, function() {
       disableDevLogs: undefined,
       importScripts: undefined,
       navigateFallback: undefined,
-      navigateFallbackBlacklist: undefined,
-      navigateFallbackWhitelist: undefined,
+      navigateFallbackDenylist: undefined,
+      navigateFallbackAllowlist: undefined,
       navigationPreload: undefined,
       offlineAnalyticsConfigString: undefined,
       precacheOptionsString,
@@ -96,8 +96,8 @@ describe(`[workbox-build] lib/populate-sw-template.js`, function() {
     const importScripts = ['test.js'];
     const manifestEntries = [{url: '/path/to/index.html', revision: '1234'}];
     const navigateFallback = '/shell.html';
-    const navigateFallbackBlacklist = [/another-test/];
-    const navigateFallbackWhitelist = [/test/];
+    const navigateFallbackDenylist = [/another-test/];
+    const navigateFallbackAllowlist = [/test/];
     const navigationPreload = true;
     const offlineGoogleAnalytics = true;
     const offlineAnalyticsConfigString = '{}';
@@ -130,8 +130,8 @@ describe(`[workbox-build] lib/populate-sw-template.js`, function() {
       importScripts,
       manifestEntries,
       navigateFallback,
-      navigateFallbackBlacklist,
-      navigateFallbackWhitelist,
+      navigateFallbackDenylist,
+      navigateFallbackAllowlist,
       navigationPreload,
       offlineGoogleAnalytics,
       runtimeCaching,
@@ -152,8 +152,8 @@ describe(`[workbox-build] lib/populate-sw-template.js`, function() {
       importScripts,
       manifestEntries,
       navigateFallback,
-      navigateFallbackBlacklist,
-      navigateFallbackWhitelist,
+      navigateFallbackDenylist,
+      navigateFallbackAllowlist,
       navigationPreload,
       offlineAnalyticsConfigString,
       runtimeCaching: runtimeCachingPlaceholder,
@@ -202,8 +202,8 @@ describe(`[workbox-build] lib/populate-sw-template.js`, function() {
       disableDevLogs: undefined,
       importScripts: undefined,
       navigateFallback: undefined,
-      navigateFallbackBlacklist: undefined,
-      navigateFallbackWhitelist: undefined,
+      navigateFallbackDenylist: undefined,
+      navigateFallbackAllowlist: undefined,
       navigationPreload: undefined,
       offlineAnalyticsConfigString,
       precacheOptionsString,

test/workbox-routing/sw/test-NavigationRoute.mjs

@@ -82,37 +82,37 @@ describe(`NavigationRoute`, function() {
     });
   });
 
-  it(`should not include urls in blacklist that completely match`, function() {
+  it(`should not include urls in denylist that completely match`, function() {
     const url = new URL('/testing/path.html', self.location);
     const request = new Request(url);
     Object.defineProperty(request, 'mode', {value: 'navigate'});
 
     const navigationRoute = new NavigationRoute(handler, {
-      blacklist: [/\/testing\/.*/],
+      denylist: [/\/testing\/.*/],
     });
 
     expect(navigationRoute.match({request, url})).to.equal(false);
   });
 
-  it(`should blacklist urls with search params that result in partial match with regex`, function() {
+  it(`should denylist urls with search params that result in partial match with regex`, function() {
     const url = new URL('/testing/path.html?test=hello', self.location);
     const request = new Request(url);
     Object.defineProperty(request, 'mode', {value: 'navigate'});
 
     const navigationRoute = new NavigationRoute(handler, {
-      blacklist: [/\/testing\/path.html/],
+      denylist: [/\/testing\/path.html/],
     });
 
     expect(navigationRoute.match({request, url})).to.equal(false);
   });
 
-  it(`should only match urls in custom whitelist`, function() {
+  it(`should only match urls in custom allowlist`, function() {
     let url = new URL('/testing/path.html?test=hello', self.location);
     let request = new Request(url);
     Object.defineProperty(request, 'mode', {value: 'navigate'});
 
     const navigationRoute = new NavigationRoute(handler, {
-      whitelist: [/\/testing\/path.html/],
+      allowlist: [/\/testing\/path.html/],
     });
 
     expect(navigationRoute.match({request, url})).to.equal(true);
@@ -124,14 +124,14 @@ describe(`NavigationRoute`, function() {
     expect(navigationRoute.match({request, url})).to.equal(false);
   });
 
-  it(`should take blacklist as priority`, function() {
+  it(`should take denylist as priority`, function() {
     let url = new URL('/testing/path.html?test=hello', self.location);
     let request = new Request(url);
     Object.defineProperty(request, 'mode', {value: 'navigate'});
 
     const navigationRoute = new NavigationRoute(handler, {
-      whitelist: [/\/testing\/.*/],
-      blacklist: [/\/testing\/path.html/],
+      allowlist: [/\/testing\/.*/],
+      denylist: [/\/testing\/path.html/],
     });
 
     expect(navigationRoute.match({request, url})).to.equal(false);