hecks 3.12.0 → 3.13.0

data/lib/hecks/grammar/translation.oidc.json

@@ -0,0 +1,48 @@
+{
+  "audience": "Translation",
+  "scopes": [
+    {
+      "scope": "translation:map.declare",
+      "verb": "Translation::Map.Declare",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:map.draft",
+      "verb": "Translation::Map.Draft",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:map.seal",
+      "verb": "Translation::Map.Seal",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:map.supersede",
+      "verb": "Translation::Map.Supersede",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:rule.admit",
+      "verb": "Translation::Rule.Admit",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:rule.execute",
+      "verb": "Translation::Rule.Execute",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:rule.propose",
+      "verb": "Translation::Rule.Propose",
+      "role": "Author"
+    },
+    {
+      "scope": "translation:rule.retire",
+      "verb": "Translation::Rule.Retire",
+      "role": "Author"
+    }
+  ],
+  "roles": [
+    "Author"
+  ]
+}

data/lib/hecks/hecks/adapters/codebase/test_runner.rb

@@ -45,12 +45,23 @@ module Hecks
         # What the runner printed for the example, when it passed.
         def run_example(path, example)
           out = StringIO.new
-          status = Dir.chdir(@tree.root) { runner.call(["--example", example, path], out, out) }
+          status = Dir.chdir(@tree.root) { at_reaction_depth_zero { runner.call(["--example", example, path], out, out) } }
           raise ConsoleCapture::Failure, out.string.strip unless status.zero?
 
           out.string.strip
         end
 
+        # The runner is asked for from inside a command's own reaction cascade, and the dispatcher
+        # keeps that cascade's depth on the thread. An example starts at depth zero, as a plain run
+        # does, so a spec that cascades four deep is not cut off by the cascade that launched it.
+        def at_reaction_depth_zero
+          depth = Thread.current[:hecks_reaction_depth]
+          Thread.current[:hecks_reaction_depth] = 0
+          yield
+        ensure
+          Thread.current[:hecks_reaction_depth] = depth
+        end
+
         def runner
           return self.class.runner if self.class.runner
 

data/lib/hecks/hecks/adapters/deploy_toolchain.rb

@@ -74,7 +74,8 @@ module Hecks
         { report: { value: child(:lint, paths).dig(:output, :value) } }
       end
 
-      # Projects each domain's OIDC client and scope manifest into its `oidc.json`, through
+      # Projects each domain's OIDC client and scope manifest into its `oidc.json`, or into one
+      # `<chapter>.oidc.json` for each chapter of a directory that holds several, through
       # `hecks deploy oidc_manifest.project_oidc`.
       #
       # @param held [Hash] the `OidcManifest` record: `domains` (comma separated directories; every

data/lib/hecks/projections/deploy/fargate/cdn/lines.rb

@@ -13,7 +13,8 @@ module Hecks
             #   (`:origin`,
             #   `:path` for an item, `:viewer_protocol`, `:methods`, `:compress`, `:cache_policy`,
             #   `:origin_request_policy`), and optionally `:response_headers_policy`, each policy as
-            #   `[id_or_intrinsic, comment_or_nil]`
+            #   `[id_or_intrinsic, comment_or_nil]`, and `:edge_function`, the logical id of a
+            #   viewer-request function
             # @param base [String] the indentation of `key`, or of the list item's dash
             # @return [Array<String>] the lines
             def behavior_lines(key, entry, base)
@@ -91,6 +92,16 @@ module Hecks
               lines << "#{pad}Compress: #{entry[:compress]}" if entry.key?(:compress)
               lines << policy_line(pad, "CachePolicyId", entry[:cache_policy])
               lines.concat(optional_policy_lines(entry, pad))
+              lines.concat(function_lines(entry, pad))
+            end
+
+            # The viewer-request function a behaviour names (`:edge_function`, the logical id of an
+            # `AWS::CloudFront::Function` in the same template), if any.
+            def function_lines(entry, pad)
+              return [] unless entry[:edge_function]
+
+              ["#{pad}FunctionAssociations:", "#{pad}  - EventType: viewer-request",
+               "#{pad}    FunctionARN: !GetAtt #{entry[:edge_function]}.FunctionARN"]
             end
 
             def optional_policy_lines(entry, pad)

data/lib/hecks/projections/site/admin_cms/templates/membership.rb

@@ -15,10 +15,12 @@ module Hecks
               // Signing in (endpoints/sso.ts) proved the person was admitted then; this asks again, so that
               // disabling or removing someone locks them out on their next request, not when their session runs out.
               //
-              // The question is the host's own account route, which answers only for a person who holds a role
-              // and is not disabled, asked with a short account token signed by the secret the host checks (the
-              // content system's AUTH_SECRET is the host's SESSION_SECRET). The answer is remembered for a minute
-              // per email so every admin request does not cost a round trip.
+              // The question is the host's members list, which the host answers (403) only to a person holding
+              // one of the admin roles, and the list's own row for the caller must hold such a role and not be
+              // disabled. It is asked with a short account token signed by the secret the host checks (the content
+              // system's AUTH_SECRET is the host's SESSION_SECRET). The answer is remembered for a minute per
+              // email so every admin request does not cost a round trip. Being admitted to the site is not enough:
+              // a member with no admin role is refused here, as the site's own admin gate refuses them.
               import { accountToken, resolveAccountCookieName } from "@hecks/client";
 
               const DEFAULT_URL = __HOST_DEFAULT__;
@@ -38,7 +40,7 @@ module Hecks
 
               export interface MembershipOptions {
                 url?: string;
-                /** The host route asked: the account route (any admitted person) by default, the members list for admin roles only. */
+                /** The host route asked: the account route (any admitted person) by default; `adminCheck` asks the members list, for admin roles only. */
                 path?: string;
                 /** Decides from the host's answer; the default is any 2xx. */
                 accept?: (res: Response, email: string) => Promise<boolean>;
@@ -83,8 +85,6 @@ module Hecks
                 };
               }
 
-              export const membership = membershipCheck();
-
               /** The roles the host's own admin gate passes. */
               export const ADMIN_ROLES = __ROLES__;
 
@@ -106,6 +106,9 @@ module Hecks
                   path: __MEMBERS_PATH__,
                   accept: async (res, email) => holdsAdminRole(await res.json().catch(() => null), email),
                 });
+
+              /** The check the sign-in endpoint and the session strategy use: admin roles only, never a plain member. */
+              export const membership = adminCheck();
             TS
           end
         end

data/lib/hecks/projections/site/edge/behaviours.rb

@@ -10,7 +10,8 @@ module Hecks
         # compression give it. A route needs none of its own when the behaviour that would match its
         # path anyway (the nearest broader route's, else the default one) is the same. The rest keep
         # the order the table declares, which is the order CloudFront matches in, and a route that
-        # a broader, different one before it would shadow is refused.
+        # a broader, different one before it would shadow is refused. The edge function a route
+        # names is part of its behaviour, so a route is folded only into one that names the same.
         class Behaviours
           # The default behaviour's path: the row that holds the settings of everything else.
           DEFAULT_PATH = "/*"
@@ -58,11 +59,14 @@ module Hecks
             policy = @edge.policy(row.cache, row.origin)
             {
               path: pattern, origin: @edge.upstream(row.origin).id, methods: methods([row]),
-              viewer_protocol: protocol(row), compress: row.compress,
-              cache_policy: Checks.resolve(policy.cache),
-              origin_request_policy: reference(policy.origin_request),
-              response_headers_policy: reference(policy.response_headers)
-            }
+              viewer_protocol: protocol(row), compress: row.compress
+            }.merge(policies(policy)).merge(row.edge ? { edge_function: row.edge } : {})
+          end
+
+          def policies(policy)
+            { cache_policy:            Checks.resolve(policy.cache),
+              origin_request_policy:   reference(policy.origin_request),
+              response_headers_policy: reference(policy.response_headers) }
           end
 
           def reference(text) = text.nil? || text == "none" ? nil : Checks.resolve(text)

data/lib/hecks/projections/site/edge/checks.rb

@@ -2,6 +2,7 @@
 
 require_relative "findings"
 require_relative "route_checks"
+require_relative "function_checks"
 
 module Hecks
   module Projections
@@ -47,6 +48,7 @@ module Hecks
             check_policies
             check_upstreams
             RouteChecks.new(@edge, @rows, @vocabulary, @problems).call
+            FunctionChecks.new(@edge, @rows, @vocabulary, @problems).call
           end
 
           private

data/lib/hecks/projections/site/edge/function_checks.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "findings"
+require_relative "function_code"
+
+module Hecks
+  module Projections
+    module Site
+      class Edge
+        # The part of the edge checks that reads the `EdgeFunction` rows and the routes that name
+        # them: each row is well formed and safe to write into a function, each route names a row
+        # that exists, and no row is left that nothing names.
+        class FunctionChecks
+          include Findings
+
+          # The longest logical id a function takes; the name it is given in the account adds the
+          # stack name, and CloudFront allows 64 characters in all.
+          NAME_LIMIT = 40
+
+          # @param edge [Edge] the edge being read, its rows set
+          # @param rows [Array<Table::Row>] the route table's rows
+          # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(edge, rows, vocabulary, problems)
+            @edge = edge
+            @rows = rows
+            @vocabulary = vocabulary
+            @problems = problems
+          end
+
+          # @return [void]
+          def call
+            @edge.functions.each { |function| check_function(function) }
+            repeated(@edge.functions.map(&:name), "EdgeFunction", &:itself)
+            check_derived_names
+            check_routes
+            check_unused
+          end
+
+          private
+
+          def check_function(function)
+            label = "EdgeFunction #{function.name}"
+            check_name(label, function)
+            member_of(label, "kind", function.kind, :edge_function_kind)
+            check_host(label, "host", function.host)
+            function.alias_list.each { |host| check_alias(label, function, host) }
+            check_paths(label, function)
+          end
+
+          # Two logical ids that differ only in case would be given one function name.
+          def check_derived_names
+            names = @edge.functions.map { |function| function.name.to_s }.uniq
+            names.group_by { |name| FunctionCode.kebab(name) }.each do |kebab, together|
+              problem("EdgeFunction", "#{together.join(" and ")} would both be named #{kebab}") if together.size > 1
+            end
+          end
+
+          def check_name(label, function)
+            name = function.name.to_s
+            problem(label, "is not a logical id") unless Checks::LOGICAL_ID.match?(name)
+            problem(label, "is longer than #{NAME_LIMIT} characters") if name.size > NAME_LIMIT
+          end
+
+          def check_host(label, field, host)
+            return if FunctionCode.host?(host)
+
+            problem(label, "has #{field} #{host.inspect}; #{field == "alias" ? "an" : "a"} #{field} is a lowercase hostname " \
+                           "such as app.example.test")
+          end
+
+          def check_alias(label, function, host)
+            check_host(label, "alias", host)
+            problem(label, "has alias #{host}, which is its host; an alias is another host") if host == function.host
+          end
+
+          def check_paths(label, function)
+            problem(label, "needs at least one path to watch") if function.path_list.empty?
+            function.path_list.each do |path|
+              next if FunctionCode.path?(path)
+
+              problem(label, "has path #{path.inspect}; a path is exact, starts with / and holds letters, digits and . _ ~ - /")
+            end
+          end
+
+          # Every `edge:` names a row, and a route the CDN never sees has no edge to run it.
+          def check_routes
+            @rows.select(&:edge).each do |row|
+              problem(row.path, "names edge #{row.edge}, which no EdgeFunction declares") unless @edge.function(row.edge)
+              problem(row.path, "names edge #{row.edge} and has cdn false; the edge never sees it") unless row.cdn
+            end
+          end
+
+          def check_unused
+            named = @rows.select(&:edge).map(&:edge)
+            @edge.functions.reject { |function| named.include?(function.name) }.each do |function|
+              problem("EdgeFunction #{function.name}", "is named by no route; remove the row or add edge: to a route")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/edge/function_code.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      class Edge
+        # The CloudFront function resource of a `redirect_host` row, and the JavaScript in it.
+        #
+        # The code is a fixed template (`redirect_host.js.tmpl`) with three values filled in: the
+        # canonical host, the alias hosts and the watched paths. A value is never escaped. One
+        # outside the strict shape of a lowercase hostname, or of a path made of unreserved
+        # characters, is refused, so no value can end a JavaScript string, a YAML block or a
+        # CloudFormation expression. The checks refuse such a row when it is read, and `code`
+        # refuses again, since it is the last step before the text is written.
+        module FunctionCode
+          # A lowercase hostname of at least two labels, as the host header is compared after
+          # lowercasing.
+          HOST = /\A([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}\z/
+
+          # A path of unreserved characters and slashes; no query, no percent escape, no quote.
+          PATH = %r{\A/[A-Za-z0-9._~/-]*\z}
+
+          # The longest hostname and path a function takes.
+          HOST_LIMIT = 253
+          PATH_LIMIT = 200
+
+          TEMPLATE = File.join(__dir__, "redirect_host.js.tmpl")
+          PLACEHOLDER = /__(CANONICAL|ALIASES|WATCHED)__/
+
+          module_function
+
+          # @param text [String] a candidate hostname
+          # @return [Boolean] whether it may be written into a function
+          def host?(text) = text.is_a?(String) && text.size <= HOST_LIMIT && HOST.match?(text)
+
+          # @param text [String] a candidate path
+          # @return [Boolean] whether it may be written into a function
+          def path?(text) = text.is_a?(String) && text.size <= PATH_LIMIT && PATH.match?(text)
+
+          # @param function [Edge::Function] a `redirect_host` row
+          # @return [String] the function's JavaScript, ending in a newline
+          # @raise [ArgumentError] when a host or path is outside the strict shapes
+          def code(function)
+            ensure_safe(function)
+            values = { "CANONICAL" => function.host, "ALIASES" => function.alias_list, "WATCHED" => function.path_list }
+            File.read(TEMPLATE).gsub(PLACEHOLDER) { JSON.generate(values.fetch(Regexp.last_match(1))) }
+          end
+
+          # @param name [String] a function's logical id
+          # @return [String] the hyphenated name the function carries, such as `host-redirect`
+          def kebab(name) = name.gsub(/([a-z0-9])([A-Z])/, '\1-\2').downcase
+
+          # @param function [Edge::Function] a `redirect_host` row
+          # @return [String] the resource, from the left margin, ending in a newline
+          def resource(function)
+            [
+              "#{function.name}:", "  Type: AWS::CloudFront::Function", "  Properties:",
+              "    Name: !Sub \"${AWS::StackName}-#{kebab(function.name)}\"", "    AutoPublish: true",
+              "    FunctionConfig:", "      Comment: Redirect the watched paths from an alias to the canonical host",
+              "      Runtime: cloudfront-js-2.0", "    FunctionCode: |",
+              *code(function).each_line.map { |line| line.strip.empty? ? "" : "      #{line.chomp}" }
+            ].join("\n") << "\n"
+          end
+
+          def ensure_safe(function)
+            raise ArgumentError, "EdgeFunction #{function.name} has no path to watch" if function.path_list.empty?
+
+            bad = unsafe_values(function)
+            return if bad.empty?
+
+            raise ArgumentError, "EdgeFunction #{function.name} has values outside the hostname and path shapes: " \
+                                 "#{bad.map(&:inspect).join(", ")}"
+          end
+
+          def unsafe_values(function)
+            [function.host, *function.alias_list].reject { |host| host?(host) } +
+              function.path_list.reject { |path| path?(path) }
+          end
+          private_class_method :ensure_safe, :unsafe_values
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/edge/redirect_host.js.tmpl

@@ -0,0 +1,65 @@
+function handler(event) {
+  var request = event.request;
+  var canonical = __CANONICAL__;
+  var aliases = __ALIASES__;
+  var watched = __WATCHED__;
+  var header = request.headers.host;
+  var host = header && header.value ? header.value.toLowerCase().replace(/:\d+$/, "") : "";
+  var reads = request.method === "GET" || request.method === "HEAD";
+  if (!reads || watched.indexOf(request.uri) < 0) { return request; }
+  if (host === canonical || aliases.indexOf(host) < 0) { return request; }
+  var parts = [];
+  Object.keys(request.querystring).forEach(function (key) {
+    var entry = request.querystring[key];
+    var values = entry.multiValue ? entry.multiValue.map(function (item) { return item.value; }) : [entry.value];
+    values.forEach(function (value) {
+      var name = encode(key);
+      parts.push(value === "" || value === undefined ? name : name + "=" + encode(value));
+    });
+  });
+  var query = parts.length ? "?" + parts.join("&") : "";
+  return {
+    statusCode: 302,
+    statusDescription: "Found",
+    headers: {
+      location: { value: "https://" + canonical + request.uri + query },
+      "cache-control": { value: "no-store" }
+    }
+  };
+}
+
+// Percent-encodes what cannot stand in a query string and keeps what is already encoded, so the
+// location header carries no space, control character, "&" or "#" whether the runtime hands over
+// the raw text or the decoded one. It walks the text one UTF-16 unit at a time and pairs the
+// surrogates itself (a lone one becomes U+FFFD), because CloudFront's regex engine refuses a
+// pattern that names a surrogate code point and fails the whole function at compile time.
+var SAFE = /[A-Za-z0-9\-._~!$'()*,;:@\/?+]/;
+var HEX = /^[0-9A-Fa-f]{2}$/;
+var REPLACEMENT = "%EF%BF%BD";
+
+function encode(text) {
+  var input = String(text);
+  var output = "";
+  var index = 0;
+  while (index < input.length) {
+    var unit = input.charAt(index);
+    var code = input.charCodeAt(index);
+    index += 1;
+    if (code >= 55296 && code <= 56319) {
+      var next = index < input.length ? input.charCodeAt(index) : 0;
+      if (next >= 56320 && next <= 57343) {
+        output += encodeURIComponent(unit + input.charAt(index));
+        index += 1;
+      } else {
+        output += REPLACEMENT;
+      }
+    } else if (code >= 56320 && code <= 57343) {
+      output += REPLACEMENT;
+    } else if (unit === "%") {
+      output += HEX.test(input.substr(index, 2)) ? unit : "%25";
+    } else {
+      output += SAFE.test(unit) ? unit : encodeURIComponent(unit);
+    }
+  }
+  return output;
+}

data/lib/hecks/projections/site/edge.rb

@@ -7,6 +7,7 @@ require_relative "edge/row_reader"
 require_relative "edge/checks"
 require_relative "edge/behaviours"
 require_relative "edge/rules"
+require_relative "edge/function_code"
 
 module Hecks
   module Projections
@@ -16,17 +17,33 @@ module Hecks
       #
       # The routes are the table's own `Route` rows. What a table cannot know, the names a template
       # gives its policies, origins, target groups and listener, a project declares as `member`
-      # rows of four more value objects of the same chapter: `Edge` (the template and listener),
-      # `EdgePolicy`, `EdgeOrigin` and `EdgeRule`. `docs/site-routes.md` lists their fields. A
-      # project that declares none of the four has no edge to project.
+      # rows of five more value objects of the same chapter: `Edge` (the template and listener),
+      # `EdgePolicy`, `EdgeOrigin`, `EdgeRule` and `EdgeFunction` (a viewer-request function a route
+      # names with `edge:`). `docs/site-routes.md` lists their fields. A project that declares none
+      # of the five has no edge to project.
       class Edge
         Setting  = Struct.new(:template, :listener, :secret_header, :secret_value, :alb, keyword_init: true)
         Policy   = Struct.new(:cache_class, :origin, :cache, :origin_request, :response_headers, keyword_init: true)
         Upstream = Struct.new(:origin, :id, :target_group, keyword_init: true)
         Rule     = Struct.new(:rule, :priority, :origin, keyword_init: true)
 
+        # A function the generator writes: `kind` says which, and the rest are its settings, the
+        # lists as comma-separated text.
+        Function = Struct.new(:name, :kind, :host, :aliases, :paths, keyword_init: true) do
+          # @return [Array<String>] the alias hosts that are redirected
+          def alias_list = split(aliases)
+
+          # @return [Array<String>] the exact paths the function watches
+          def path_list = split(paths)
+
+          private
+
+          def split(text) = text.to_s.split(",").map(&:strip).reject(&:empty?)
+        end
+
         # The value objects a project declares its edge rows in, by the kind of record each holds.
-        OBJECTS = { setting: "Edge", policy: "EdgePolicy", upstream: "EdgeOrigin", rule: "EdgeRule" }.freeze
+        OBJECTS = { setting: "Edge", policy: "EdgePolicy", upstream: "EdgeOrigin", rule: "EdgeRule",
+                    function: "EdgeFunction" }.freeze
 
         # The fields each kind of row may carry, with the Ruby class each takes.
         FIELDS = {
@@ -34,14 +51,15 @@ module Hecks
           policy:   { cache_class: String, origin: String, cache: String, origin_request: String,
                     response_headers: String },
           upstream: { origin: String, id: String, target_group: String },
-          rule:     { rule: String, priority: Integer, origin: String }
+          rule:     { rule: String, priority: Integer, origin: String },
+          function: { name: String, kind: String, host: String, aliases: String, paths: String }
         }.freeze
 
         # The fields a row of each kind must carry. The template may instead be named to the tool.
         REQUIRED = { setting: [], policy: %i[cache_class cache], upstream: %i[origin id],
-                     rule: %i[rule priority origin] }.freeze
+                     rule: %i[rule priority origin], function: %i[name kind host aliases paths] }.freeze
 
-        STRUCTS = { setting: Setting, policy: Policy, upstream: Upstream, rule: Rule }.freeze
+        STRUCTS = { setting: Setting, policy: Policy, upstream: Upstream, rule: Rule, function: Function }.freeze
 
         # @return [Setting] the template and the listener
         attr_reader :setting
@@ -51,6 +69,8 @@ module Hecks
         attr_reader :upstreams
         # @return [Array<Rule>] the listener rules
         attr_reader :rules
+        # @return [Array<Function>] the edge functions the generator writes
+        attr_reader :functions
         # @return [Hash{Symbol => Object}] the default behaviour as `Cdn.behavior_lines` takes it
         attr_reader :default_behaviour
         # @return [Array<Hash{Symbol => Object}>] the other behaviours, in matching order
@@ -65,11 +85,12 @@ module Hecks
         # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
         # @param template [String, nil] the template the caller names, which stands in for the
         #   `Edge` row's own `template:`
-        # @return [Edge, nil] the checked edge, or nil when the chapter declares none
+        # @return [Edge, nil] the checked edge, or nil when the chapter declares none and no route
+        #   names an edge function
         # @raise [Table::Invalid] when a row is refused or the edge contradicts the routes
         def self.read(chapter, table:, vocabulary:, template: nil)
           declared = OBJECTS.transform_values { |name| Table.rows_of(chapter, name) }
-          return nil if declared.values.all?(&:empty?)
+          return nil if declared.values.all?(&:empty?) && table.rows.none?(&:edge)
 
           problems = []
           records = declared.to_h { |kind, members| [kind, build(kind, members, problems)] }
@@ -104,6 +125,7 @@ module Hecks
           @policies = records.fetch(:policy)
           @upstreams = records.fetch(:upstream)
           @rules = records.fetch(:rule)
+          @functions = records.fetch(:function)
         end
         private :assign
 
@@ -119,6 +141,10 @@ module Hecks
         #   unless the `Edge` row says `alb: false`
         def alb? = setting.nil? || setting.alb != false
 
+        # @param name [String] a logical id
+        # @return [Function, nil] the function row of that name
+        def function(name) = functions.find { |candidate| candidate.name == name }
+
         # @param origin [String] an origin of the Origin set
         # @return [Upstream, nil] its CloudFront origin and target group
         def upstream(origin) = upstreams.find { |candidate| candidate.origin == origin }

data/lib/hecks/projections/site/site_cdn.rb

@@ -7,12 +7,14 @@ require_relative "edge"
 module Hecks
   module Projections
     module Site
-      # The edge of a site's route table as the two blocks of a CloudFormation template that depend
-      # on it: the distribution's cache behaviours and the load balancer's listener rules.
+      # The edge of a site's route table as the blocks of a CloudFormation template that depend on
+      # it: the distribution's cache behaviours, the load balancer's listener rules and the
+      # functions the behaviours attach.
       #
-      # The blocks are returned by name, `"behaviors"` and `"listener_rules"`, as text from the
-      # left margin; a project whose `Edge` row says `alb: false` has no load balancer and gets
-      # `"behaviors"` alone. `Regions` puts each between the markers of the same name in the
+      # The blocks are returned by name, `"behaviors"`, `"listener_rules"` and `"edge_functions"`,
+      # as text from the left margin; a project whose `Edge` row says `alb: false` has no load
+      # balancer and gets no `"listener_rules"`, and one with no `EdgeFunction` row gets no
+      # `"edge_functions"`. `Regions` puts each between the markers of the same name in the
       # project's template, at the markers' indentation. The text is a pure function of the table
       # and the edge rows.
       module SiteCdn
@@ -34,9 +36,21 @@ module Hecks
           edge = options[:edge] || Edge.read(bluebook, table: table, vocabulary: Table.vocabulary(registry))
           return {} unless edge
 
-          return { "behaviors" => behaviors(edge) } unless edge.alb?
+          regions(edge)
+        end
 
-          { "behaviors" => behaviors(edge), "listener_rules" => listener_rules(edge) }
+        # @param edge [Edge] a checked edge
+        # @return [Hash{String => String}] the regions the edge needs
+        def regions(edge)
+          { "behaviors" => behaviors(edge) }
+            .merge(edge.alb? ? { "listener_rules" => listener_rules(edge) } : {})
+            .merge(edge.functions.any? ? { "edge_functions" => edge_functions(edge) } : {})
+        end
+
+        # @param edge [Edge] a checked edge
+        # @return [String] one function resource per `EdgeFunction` row, ending in a newline
+        def edge_functions(edge)
+          edge.functions.map { |function| Edge::FunctionCode.resource(function) }.join("\n")
         end
 
         # @param edge [Edge] a checked edge

data/lib/hecks/projections/site/table/row_builder.rb

@@ -11,7 +11,7 @@ module Hecks
                          :indexable, :switch, :off, :preview, :label, :seo, :redirect_to, :aliases,
                          :nav_group, :nav_order, :mobile_order, :footer_column, :footer_order,
                          :admin_key, :admin_order, :compress, :alb_rule, :cdn,
-                         :seo_title, :edge_verbs, :mobile_heading, :explicit_cache, keyword_init: true)
+                         :seo_title, :edge_verbs, :mobile_heading, :explicit_cache, :edge, keyword_init: true)
 
         # Turns a declared member into a `Row`: checks its fields and their types, fills the
         # defaults, and checks each closed-set value against the Site chapter's vocabulary.
@@ -23,7 +23,10 @@ module Hecks
                      aliases: String, nav_group: String, nav_order: Integer, mobile_order: Integer,
                      footer_column: String, footer_order: Integer, admin_key: String,
                      admin_order: Integer, compress: :bool, alb_rule: String, cdn: :bool,
-                     seo_title: String, edge_methods: String, mobile_heading: String }.freeze
+                     seo_title: String, edge_methods: String, mobile_heading: String, edge: String }.freeze
+
+          # What an `edge:` names: the logical id of an `EdgeFunction` row.
+          EDGE_NAME = /\A[A-Za-z][A-Za-z0-9]*\z/
 
           # The value objects of the Site chapter's `Route` aggregate whose members are the closed
           # sets, by the row field each constrains.
@@ -103,6 +106,13 @@ module Hecks
               problem(label, "has #{field} #{row[field].inspect}; #{field} is one of #{@vocabulary.fetch(field).join(", ")}")
             end
             check_verbs(row, label)
+            check_edge(row, label)
+          end
+
+          def check_edge(row, label)
+            return unless row.edge.is_a?(String) && !EDGE_NAME.match?(row.edge)
+
+            problem(label, "has edge #{row.edge.inspect}; an edge is the logical id of an EdgeFunction row")
           end
 
           def check_verbs(row, label)