Configure Fastly during deploy via generated route snippets

.github/workflows/deploy.yml

@@ -94,3 +94,25 @@ jobs:
       - name: Upload to S3
         run: |
           aws s3 sync ./build s3://${{ vars.AWS_S3_BUCKET }}/junior/
+
+  configure-fastly:
+    needs: [setup, lint, build]
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment: ${{ needs.setup.outputs.environment }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node 22x
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+      - name: Install Dependencies
+        run: npm ci --legacy-peer-deps
+      - name: Configure Fastly
+        run: npm run sync-fastly
+        env:
+          FASTLY_API_KEY: ${{ secrets.FASTLY_API_KEY }}
+          FASTLY_SERVICE_ID: ${{ vars.FASTLY_SERVICE_ID }}
+          # Set this var in an Environment to have that environment's deploys
+          # activate the new version; leave it unset to configure + validate only.
+          FASTLY_ACTIVATE_CHANGES: ${{ vars.FASTLY_ACTIVATE_CHANGES }}

README.md

@@ -49,4 +49,3 @@ Use `^C` to stop the node process `npm start` starts.
 | `FASTLY_ACTIVATE_CHANGES`| `false` | Activate changes and purge all after configuring |
 | `AWS_ACCESS_KEY_ID`      | `''`    | AWS access key id for S3                         |
 | `AWS_SECRET_ACCESS_KEY`  | `''`    | AWS secret access key for S3                     |
-| `S3_BUCKET_NAME`         | `''`    | S3 bucket name to deploy into                    |

bin/configure-fastly.js

@@ -1,30 +1,10 @@
-const defaults = require('lodash.defaults');
-
 const routeJson = require('../src/routes.json');
+const {routesToSnippets} = require('./lib/routes-to-vcl');
 
 const FASTLY_SERVICE_ID = process.env.FASTLY_SERVICE_ID || '';
-const S3_BUCKET_NAME = process.env.S3_BUCKET_NAME || '';
-const BUCKET_NAME_HEADER_NAME = 'Bucket name';
 
 const fastly = require('./lib/fastly-extended')(process.env.FASTLY_API_KEY, FASTLY_SERVICE_ID);
 
-/*
- * Translate an express-style pattern e.g. /path/:arg/ to a regex
- * all :arguments become .+?
- */
-const expressPatternToRegex = pattern => pattern.replace(/(:[^/]+)/gi, '.+?');
-
-const getConditionNameForRoute = (route, type) => `routes/${route.pattern} (${type})`;
-
-const getHeaderNameForRoute = route => {
-    if (route.name) return `rewrites/${route.name}`;
-    if (route.redirect) return `redirects/${route.pattern}`;
-};
-
-const getResponseNameForRoute = route => `redirects/${route.pattern}`;
-
-const routes = routeJson.map(route => defaults({}, {pattern: expressPatternToRegex(route.pattern)}, route));
-
 // Get the latest version, cloning it first if it is already active or locked.
 const getWorkingVersion = async () => {
     const response = await fastly.getLatestVersion();
@@ -40,83 +20,19 @@ const getWorkingVersion = async () => {
     return response.number;
 };
 
-const setBucketNameHeader = version => fastly.setFastlyHeader(version, {
-    name: BUCKET_NAME_HEADER_NAME,
-    action: 'set',
-    ignore_if_set: 0,
-    type: 'REQUEST',
-    dst: 'http.host',
-    src: `"${S3_BUCKET_NAME}"`,
-    priority: 1
-});
-
-// Create a request condition per route and return them keyed by route index.
-const setAppRouteRequestConditions = async version => {
-    const conditions = [];
-    await Promise.all(routes.map(async (route, id) => {
-        conditions[id] = await fastly.setCondition(version, {
-            name: getConditionNameForRoute(route, 'request'),
-            statement: `req.url ~ "${route.pattern}"`,
-            type: 'REQUEST',
-            // Priority needs to be > 1 to not interact with http->https redirect
-            priority: 10 + id
-        });
-    }));
-    return conditions;
-};
-
-const setRedirectRouteHeader = async (version, route, id) => {
-    const responseCondition = await fastly.setCondition(version, {
-        name: getConditionNameForRoute(route, 'response'),
-        statement: `req.url ~ "${route.pattern}"`,
-        type: 'RESPONSE',
-        priority: id
-    });
-    await fastly.setResponseObject(version, {
-        name: getResponseNameForRoute(route),
-        status: 301,
-        response: 'Moved Permanently',
-        request_condition: getConditionNameForRoute(route, 'request')
-    });
-    return fastly.setFastlyHeader(version, {
-        name: getHeaderNameForRoute(route),
-        action: 'set',
-        ignore_if_set: 0,
-        type: 'RESPONSE',
-        dst: 'http.Location',
-        src: `"${route.redirect}"`,
-        response_condition: responseCondition.name
-    });
-};
-
-const setRewriteRouteHeader = (version, route, requestCondition) => fastly.setFastlyHeader(version, {
-    name: getHeaderNameForRoute(route, 'request'),
-    action: 'set',
-    ignore_if_set: 0,
-    type: 'REQUEST',
-    dst: 'url',
-    src: `"/${route.name}.html"`,
-    request_condition: requestCondition.name,
-    priority: 10
-});
-
-// Create the response/request header for every route (redirects vs. rewrites).
-const setAppRouteHeaders = (version, requestConditions) => Promise.all(routes.map((route, id) => {
-    if (route.redirect) {
-        return setRedirectRouteHeader(version, route, id);
-    }
-    return setRewriteRouteHeader(version, route, requestConditions[id]);
-}));
+// Render routes.json into VCL snippets and write them to the version.
+const setAppRouteSnippets = version => Promise.all(
+    routesToSnippets(routeJson).map(snippet => fastly.setSnippet(version, snippet))
+);
 
 const configureFastly = async () => {
     const version = await getWorkingVersion();
-    // The bucket header and the request conditions depend only on the version,
-    // so run them together; the route headers depend on the request conditions.
-    const results = await Promise.all([
-        setBucketNameHeader(version),
-        setAppRouteRequestConditions(version)
-    ]);
-    await setAppRouteHeaders(version, results[1]);
+    await setAppRouteSnippets(version);
+    // Compile-check the generated VCL before anything tries to activate it.
+    const validation = await fastly.validateVersion(version);
+    if (validation.status !== 'ok') {
+        throw new Error(`Version ${version} failed validation: ${validation.msg}`);
+    }
     return version;
 };
 

bin/lib/fastly-extended.js

@@ -3,9 +3,8 @@ const Fastly = require('fastly');
 /*
  * Fastly configuration helpers built on the official fastly-js client.
  *
- * Wraps the per-resource API classes and exposes Promise-returning, upsert-by-
- * name helpers with stable signatures so callers don't deal with the client's
- * create-vs-update split. Authenticates the shared ApiClient on construction.
+ * Wraps the per-resource API classes and exposes Promise-returning helpers with
+ * stable signatures. Authenticates the shared ApiClient on construction.
  *
  * @param {string} apiToken Fastly API token
  * @param {string} serviceId Fastly service id
@@ -14,17 +13,13 @@ module.exports = (apiToken, serviceId) => {
     Fastly.ApiClient.instance.authenticate(apiToken);
 
     const versionApi = new Fastly.VersionApi();
-    const conditionApi = new Fastly.ConditionApi();
-    const headerApi = new Fastly.HeaderApi();
-    const responseObjectApi = new Fastly.ResponseObjectApi();
+    const snippetApi = new Fastly.SnippetApi();
     const purgeApi = new Fastly.PurgeApi();
 
-    // Upsert-by-name: fastly-js has no upsert, so update (PUT by name) and fall
-    // back to create (POST) when the resource does not yet exist (404).
-    const upsert = (update, create) => update().catch(err => {
-        if (err && err.status === 404) return create();
+    const ignoreMissing = err => {
+        if (err && err.status === 404) return null;
         throw err;
-    });
+    };
 
     const withService = (version, extra) => Object.assign(
         {service_id: serviceId, version_id: version},
@@ -55,45 +50,30 @@ module.exports = (apiToken, serviceId) => {
             return versionApi.cloneServiceVersion({service_id: serviceId, version_id: version});
         },
 
-        // Upsert a Fastly condition entry.
-        setCondition: (version, condition) => {
-            if (!serviceId) {
-                return Promise.reject(new Error('Failed to set condition. No serviceId configured'));
-            }
-            const params = withService(version, condition);
-            return upsert(
-                () => conditionApi.updateCondition(Object.assign({condition_name: condition.name}, params)),
-                () => conditionApi.createCondition(params)
-            );
-        },
-
-        // Upsert a Fastly header entry.
-        setFastlyHeader: (version, header) => {
+        // Compile-check a version's generated VCL without activating it. Resolves
+        // with {status, msg}; status is 'ok' when the version is valid.
+        validateVersion: version => {
             if (!serviceId) {
-                return Promise.reject(new Error('Failed to set header. No serviceId configured'));
+                return Promise.reject(new Error('Failed to validate version. No serviceId configured.'));
             }
-            const params = withService(version, header);
-            return upsert(
-                () => headerApi.updateHeaderObject(Object.assign({header_name: header.name}, params)),
-                () => headerApi.createHeaderObject(params)
-            );
+            return versionApi.validateServiceVersion({service_id: serviceId, version_id: version});
         },
 
-        // Upsert a Fastly response object. The client takes the body wrapped in
-        // create_response_object_request for both create and update.
-        setResponseObject: (version, responseObject) => {
+        // Replace a versioned VCL snippet. fastly-js updateSnippet sends no body,
+        // so delete any existing snippet of this name (ignoring 404) then create.
+        setSnippet: (version, snippet) => {
             if (!serviceId) {
-                return Promise.reject(new Error('Failed to set response object. No serviceId configured'));
+                return Promise.reject(new Error('Failed to set snippet. No serviceId configured'));
             }
-            return upsert(
-                () => responseObjectApi.updateResponseObject(withService(version, {
-                    response_object_name: responseObject.name,
-                    create_response_object_request: responseObject
-                })),
-                () => responseObjectApi.createResponseObject(withService(version, {
-                    create_response_object_request: responseObject
-                }))
-            );
+            return snippetApi.deleteSnippet({service_id: serviceId, version_id: version, name: snippet.name})
+                .catch(ignoreMissing)
+                .then(() => snippetApi.createSnippet(withService(version, {
+                    name: snippet.name,
+                    type: snippet.type,
+                    content: snippet.content,
+                    priority: snippet.priority,
+                    dynamic: '0'
+                })));
         },
 
         // Activate a version.

bin/lib/routes-to-vcl.js

@@ -0,0 +1,104 @@
+/*
+ * Turn routes.json into Fastly VCL snippets.
+ *
+ * Instead of creating one Fastly condition + response object + header per route
+ * (which accumulates objects and burns a synthetic status code per redirect),
+ * the whole route table is rendered into a few snippets that are overwritten by
+ * name on every run. Exact redirects and section rewrites become table lookups;
+ * a single reused internal status code drives every 301.
+ *
+ * Returns an array of snippet specs: {name, type, priority, content}.
+ */
+
+// Internal-only status used to signal "issue a redirect": caught in the error
+// snippet and turned into a 301, never returned to a client. Any value >= 600
+// works as long as it does not collide with another error code in the service's
+// VCL; the value is arbitrary. Verify against the live generated VCL if unsure.
+const REDIRECT_STATUS = 700;
+
+// Escape a string for use inside a VCL double-quoted literal.
+const vclString = value => `"${String(value).replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')}"`;
+
+// Derive the literal source path a redirect route matches, from its pattern.
+// Redirect patterns are anchored literal paths (e.g. "^/about\\.html"); strip
+// the anchors and unescape. Throws if the pattern isn't a literal path, so a
+// regex redirect can never be silently dropped into an exact-match table.
+const redirectSourcePath = route => {
+    const body = route.pattern.replace(/^\^/, '').replace(/\$$/, '');
+    const unescaped = body.replace(/\\(.)/g, '$1');
+    // After unescaping, a literal path re-escaped must match the original body.
+    const reEscaped = unescaped.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (reEscaped !== body) {
+        throw new Error(`Redirect pattern is not a literal path, cannot map to a lookup table: ${route.pattern}`);
+    }
+    return unescaped;
+};
+
+// The first path segment a section route keys on (its name is that segment).
+const sectionKey = route => route.name;
+
+const renderTable = (name, entries) => {
+    const lines = entries.map(([key, value]) => `    ${vclString(key)}: ${vclString(value)},`);
+    return `table ${name} {\n${lines.join('\n')}\n}`;
+};
+
+const routesToSnippets = routes => {
+    const redirectEntries = [];
+    const sectionEntries = [];
+
+    routes.forEach(route => {
+        if (route.redirect) {
+            redirectEntries.push([redirectSourcePath(route), route.redirect]);
+            return;
+        }
+        if (route.name === 'index') return; // handled explicitly in recv
+        sectionEntries.push([sectionKey(route), `/${route.name}.html`]);
+    });
+
+    const tables = [
+        renderTable('redirects', redirectEntries),
+        renderTable('sections', sectionEntries)
+    ].join('\n\n');
+
+    const recv = [
+        '# Redirect legacy .html paths to their clean URL (single reused status).',
+        'declare local var.redirect STRING;',
+        'set var.redirect = table.lookup(redirects, req.url.path, "");',
+        'if (var.redirect != "") {',
+        '    set req.http.X-Redirect-Location = var.redirect;',
+        `    error ${REDIRECT_STATUS};`,
+        '}',
+        '',
+        '# Serve section pages by rewriting to their static html file.',
+        'if (req.url.path == "/") {',
+        '    set req.url = "/index.html";',
+        '} else {',
+        '    declare local var.section STRING;',
+        '    set var.section = regsub(req.url.path, "^/([^/?]+).*$", "\\1");',
+        '    declare local var.view STRING;',
+        '    set var.view = table.lookup(sections, var.section, "");',
+        '    if (var.view != "") {',
+        '        set req.url = var.view;',
+        '    }',
+        '}'
+    ].join('\n');
+
+    const error = [
+        `if (obj.status == ${REDIRECT_STATUS}) {`,
+        '    set obj.status = 301;',
+        '    set obj.response = "Moved Permanently";',
+        '    set obj.http.Location = req.http.X-Redirect-Location;',
+        '    synthetic {""};',
+        '    return(deliver);',
+        '}'
+    ].join('\n');
+
+    return [
+        {name: 'app-routes-tables', type: 'init', priority: '100', content: tables},
+        {name: 'app-routes-recv', type: 'recv', priority: '10', content: recv},
+        {name: 'app-routes-error', type: 'error', priority: '100', content: error}
+    ];
+};
+
+module.exports = {routesToSnippets, redirectSourcePath, REDIRECT_STATUS};

package.json

@@ -8,7 +8,8 @@
     "lint": "eslint . --ext .js,.jsx && sass-lint -v ./src/**/*.scss",
     "start": "node ./dev-server/index.js",
     "sync-fastly": "node ./bin/configure-fastly.js",
-    "test": "npm run lint && npm run build"
+    "test:unit": "node ./test/routes-to-vcl.test.js",
+    "test": "npm run lint && npm run test:unit && npm run build"
   },
   "repository": {
     "type": "git",
@@ -39,7 +40,6 @@
     "html-loader": "5.1.0",
     "html-webpack-plugin": "5.6.4",
     "lodash.debounce": "4.0.8",
-    "lodash.defaults": "4.2.0",
     "postcss": "8.5.6",
     "postcss-loader": "8.2.0",
     "postcss-simple-vars": "7.0.1",