feat(utils): Add function to calculate surrogate key

fixes #123

src/index.js

@@ -13,6 +13,7 @@ const GitUrl = require('./GitUrl.js');
 const HelixConfig = require('./HelixConfig.js');
 const Strain = require('./Strain.js');
 const Logger = require('./Logger.js');
+const utils = require('./utils.js');
 const sequence = require('./sequence.js');
 const functional = require('./functional.js');
 const op = require('./op.js');
@@ -31,4 +32,5 @@ module.exports = {
   sequence,
   string,
   dom,
+  utils,
 };

src/utils.js

@@ -9,10 +9,18 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
+const crypto = require('crypto');
 
 /* eslint-disable class-methods-use-this */
 
 class Utils {
+  /**
+   * Iterates over the properties of the given object and removes all empty values.
+   * A value is considered empty, if it's not truthy or an empty array.
+   *
+   * @param {object} obj - The object to prune.
+   * @returns {object} the input object or {@code null} if the object is empty.
+   */
   pruneEmptyValues(obj) {
     const keys = Object.keys(obj);
     let i = 0;
@@ -25,6 +33,26 @@ class Utils {
     });
     return keys.length === i ? null : obj;
   }
+
+  /**
+   * Computes the caching Surrogate-Key for the given url. The computation uses a hmac_sha256
+   * with a fixed key: {@code "helix"}. the result is base64 encoded and truncated to 16 characters.
+   * This algorithm is chosen, because similar functionality exists in Fastly's VCL api:
+   *
+   * ```
+   * declare local var.key STRING;
+   * set var.key = digest.hmac_sha256_base64("helix", "input");
+   * set var.key = regsub(var.key, "(.{16}).*", "\1");
+   * ```
+   *
+   * @param {*} url - The input url.
+   * @returns {string} The computed key.
+   */
+  computeSurrogateKey(url) {
+    const hmac = crypto.createHmac('sha256', 'helix'); // lgtm [js/hardcoded-credentials]
+    hmac.update(String(url));
+    return hmac.digest('base64').substring(0, 16);
+  }
 }
 
 module.exports = new Utils();

test/surrogate.test.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2019 Adobe. All rights reserved.
+ * This file is licensed to you 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 REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/* eslint-env mocha */
+
+const assert = require('assert');
+const { GitUrl } = require('../src/index.js');
+const { computeSurrogateKey } = require('../src/index.js').utils;
+
+describe('Surrogate Test', () => {
+  it('computes a string', () => {
+    assert.equal(computeSurrogateKey('input'), 'LryzWp9TSqzkYkz6');
+  });
+
+  it('computes a empty string', () => {
+    assert.equal(computeSurrogateKey(''), '+furr1hlvWuvr9Xu');
+  });
+
+  it('computes a git url', () => {
+    const url = new GitUrl({
+      protocol: 'http',
+      hostname: 'git.example.com',
+      owner: 'company',
+      path: '/docs/main',
+      port: '1234',
+      ref: 'products/v2',
+      repo: 'repository',
+    });
+    assert.equal(computeSurrogateKey(url), 'KRBwmXdLOShWtk9P');
+  });
+});