hecks 3.5.0 → 3.6.0

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "findings"
+
+module Hecks
+  module Projections
+    module Site
+      class Edge
+        # The part of the edge checks that reads the listener rules and the routes: each rule is
+        # well formed and reaches a target group, and every route the edge serves has the origin and
+        # the policy it needs.
+        class RouteChecks
+          include Findings
+
+          PRIORITIES = (1..50_000)
+
+          # @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
+            check_rules
+            check_routes
+          end
+
+          private
+
+          def check_rules
+            return check_no_alb unless @edge.alb?
+
+            check_listener
+            @edge.rules.each { |rule| check_rule(rule) }
+            repeated(@edge.rules.map(&:rule), "EdgeRule", &:itself)
+            repeated(@edge.rules.map(&:priority), "EdgeRule priority", &:to_s)
+          end
+
+          def check_listener
+            problem("EdgeRule", "rows need an Edge row with listener:") if @edge.rules.any? && !@edge.setting&.listener
+          end
+
+          # With `alb: false` nothing routes by listener rule, so a rule row, or a route that names
+          # one, describes a load balancer the project says it does not have. Every route that is
+          # served by a server behind the edge still needs the origin that reaches it.
+          def check_no_alb
+            problem("EdgeRule", "rows describe a load balancer, and the Edge row says alb: false") if @edge.rules.any?
+            @rows.select(&:alb_rule).each do |row|
+              problem(row.path, "names alb_rule #{row.alb_rule}, and the Edge row says alb: false")
+            end
+            @rows.each { |row| check_reachable(row) }
+          end
+
+          def check_reachable(row)
+            return if row.cdn || !%w[cms domain].include?(row.origin) || @edge.upstream(row.origin)
+
+            problem(row.path, "is served from #{row.origin}, which no EdgeOrigin maps, and with alb: false " \
+                              "nothing else reaches it")
+          end
+
+          def check_rule(rule)
+            label = "EdgeRule #{rule.rule}"
+            member_of(label, "origin", rule.origin, :origin)
+            problem(label, "has origin assets; the load balancer does not front the assets origin") if rule.origin == "assets"
+            problem(label, "is not a logical id") unless Checks::LOGICAL_ID.match?(rule.rule.to_s)
+            check_priority(label, rule)
+            check_target_group(label, rule)
+          end
+
+          def check_priority(label, rule)
+            return if PRIORITIES.cover?(rule.priority.to_i)
+
+            problem(label, "has priority #{rule.priority}; a priority is #{PRIORITIES.first} to #{PRIORITIES.last}")
+          end
+
+          def check_target_group(label, rule)
+            return if rule.origin.nil? || @edge.upstream(rule.origin)&.target_group
+
+            problem(label, "forwards to #{rule.origin}, whose EdgeOrigin names no target_group")
+          end
+
+          def check_routes
+            @rows.select { |row| row.cdn || row.alb_rule }.each { |row| check_route(row) }
+            default_rows = @rows.select { |row| row.path == "/*" && row.cdn }
+            problem("the route table", "needs one row for /* : the default behaviour") if default_rows.empty?
+          end
+
+          def check_route(row)
+            return if row.origin == "assets" && !row.cdn
+
+            problem(row.path, "has origin #{row.origin}, which no EdgeOrigin maps") unless @edge.upstream(row.origin)
+            check_policy_mapped(row)
+          end
+
+          def check_policy_mapped(row)
+            return unless row.cdn && !@edge.policy(row.cache, row.origin)
+
+            problem(row.path, "has cache class #{row.cache} on #{row.origin}, which no EdgePolicy maps")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      class Edge
+        # Reads the declared rows of one kind into structs, recording a problem for each unknown
+        # field, each missing required field and each field of the wrong type.
+        class RowReader
+          # @param kind [Symbol] a key of `Edge::OBJECTS`
+          # @param problems [Array<String>] collects each problem found
+          def initialize(kind, problems)
+            @kind = kind
+            @problems = problems
+            @fields = FIELDS.fetch(kind)
+          end
+
+          # @param members [Array<Hash{Symbol => Object}>] the declared rows
+          # @return [Array<Struct>] the rows that carry known, well-typed fields
+          def call(members)
+            members.each_with_index.map { |member, index| read(member, "#{OBJECTS.fetch(@kind)} row #{index + 1}") }
+          end
+
+          private
+
+          def read(member, label)
+            check_fields(member, label)
+            STRUCTS.fetch(@kind).new(**typed_fields(member, label))
+          end
+
+          def check_fields(member, label)
+            unknown = member.keys - @fields.keys
+            @problems << "#{label} has no field #{unknown.join(", ")}; fields are #{@fields.keys.join(", ")}" if unknown.any?
+            (REQUIRED.fetch(@kind) - member.keys).each { |field| @problems << "#{label} needs #{field}" }
+          end
+
+          # A field of the wrong type is recorded as a problem and kept, so its row still builds.
+          def typed_fields(member, label)
+            member.slice(*@fields.keys).select do |field, value|
+              typed?(value, @fields.fetch(field)) ||
+                (@problems << "#{label} has #{field} #{value.inspect}; #{field} is #{type_name(@fields.fetch(field))}")
+            end
+          end
+
+          def typed?(value, type) = type == :bool ? [true, false].include?(value) : value.is_a?(type)
+
+          def type_name(type) = type == :bool ? "true or false" : "a #{type}"
+        end
+      end
+    end
+  end
+end

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

@@ -60,15 +60,19 @@ module Hecks
 
           def check_names
             names = @edge.rules.map(&:rule)
-            @rows.select(&:alb_rule).each do |row|
-              rule = @edge.rules.find { |candidate| candidate.rule == row.alb_rule }
-              next problem(row.path, "names alb_rule #{row.alb_rule}; rules are #{names.join(', ')}") unless rule
-              next if rule.origin == row.origin
+            @rows.select(&:alb_rule).each { |row| check_named(row, names) }
+          end
 
-              problem(row.path, "is served from #{row.origin} but its rule #{rule.rule} forwards to #{rule.origin}")
-            end
+          def check_named(row, names)
+            rule = rule_named(row.alb_rule)
+            return problem(row.path, "names alb_rule #{row.alb_rule}; rules are #{names.join(", ")}") unless rule
+            return if rule.origin == row.origin
+
+            problem(row.path, "is served from #{row.origin} but its rule #{rule.rule} forwards to #{rule.origin}")
           end
 
+          def rule_named(name) = @edge.rules.find { |rule| rule.rule == name }
+
           # A route of a server behind the load balancer other than the website has a rule of its
           # own or sits under a broader route of the same server that has one.
           def check_carried
@@ -81,22 +85,16 @@ module Hecks
           end
 
           # The rule that carries a route: its own, else the nearest broader route's of its server.
-          def rule_of(row)
-            named = @edge.rules.find { |rule| rule.rule == row.alb_rule }
-            return named if named
+          def rule_of(row) = rule_named(row.alb_rule) || covering_rule(row)
 
-            covers = @rows.select do |other|
-              other.alb_rule && other.origin == row.origin &&
-                Pattern.strictly_covers?(Pattern.edge(other.path), Pattern.edge(row.path))
-            end
-            covering = covers.find do |one|
-              covers.none? do |other|
-                Pattern.strictly_covers?(Pattern.edge(one.path), Pattern.edge(other.path))
-              end
-            end
-            covering && @edge.rules.find { |rule| rule.rule == covering.alb_rule }
+          def covering_rule(row)
+            covers = @rows.select { |other| other.alb_rule && other.origin == row.origin && strictly_covers?(other, row) }
+            covering = covers.find { |one| covers.none? { |other| strictly_covers?(one, other) } }
+            covering && rule_named(covering.alb_rule)
           end
 
+          def strictly_covers?(one, other) = Pattern.strictly_covers?(Pattern.edge(one.path), Pattern.edge(other.path))
+
           # A rule of another server, with a lower priority, whose paths include one a route's own
           # rule would answer later, is a route answered by the wrong server.
           def check_cross_origin
@@ -105,16 +103,20 @@ module Hecks
               next if row.origin == "assets"
 
               own = rule_of(row)&.priority || fallback
-              @edge.rules.each do |rule|
-                next if rule.origin == row.origin || rule.priority >= own
-                next unless carried(rule).any? { |other| Pattern.covers?(Pattern.edge(other.path), Pattern.edge(row.path)) }
-
-                problem(row.path, "is served from #{row.origin} but rule #{rule.rule} (priority #{rule.priority}) " \
-                                  "sends it to #{rule.origin} first")
-              end
+              @edge.rules.each { |rule| check_answered_first(row, rule, own) }
             end
           end
 
+          def check_answered_first(row, rule, own)
+            return if rule.origin == row.origin || rule.priority >= own
+            return unless carried(rule).any? { |other| covers?(other, row) }
+
+            problem(row.path, "is served from #{row.origin} but rule #{rule.rule} (priority #{rule.priority}) " \
+                              "sends it to #{rule.origin} first")
+          end
+
+          def covers?(one, other) = Pattern.covers?(Pattern.edge(one.path), Pattern.edge(other.path))
+
           def default_priority
             default = @rows.find { |row| row.path == "/*" }
             @edge.rules.find { |rule| rule.rule == default&.alb_rule }&.priority || Float::INFINITY

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

@@ -3,6 +3,7 @@
 require_relative "../deploy/fargate/cdn"
 require_relative "table"
 require_relative "edge/pattern"
+require_relative "edge/row_reader"
 require_relative "edge/checks"
 require_relative "edge/behaviours"
 require_relative "edge/rules"
@@ -79,30 +80,9 @@ module Hecks
         # @param members [Array<Hash{Symbol => Object}>] the declared rows
         # @param problems [Array<String>] collects each problem found
         # @return [Array<Struct>] the rows that carry known, well-typed fields
-        def self.build(kind, members, problems)
-          members.each_with_index.map do |member, index|
-            label = "#{OBJECTS.fetch(kind)} row #{index + 1}"
-            unknown = member.keys - FIELDS.fetch(kind).keys
-            if unknown.any?
-              problems << "#{label} has no field #{unknown.join(', ')}; fields are #{FIELDS.fetch(kind).keys.join(', ')}"
-            end
-            (REQUIRED.fetch(kind) - member.keys).each { |field| problems << "#{label} needs #{field}" }
-            typed = member.slice(*FIELDS.fetch(kind).keys).select do |field, value|
-              typed?(value, FIELDS.fetch(kind).fetch(field)) ||
-                (problems << "#{label} has #{field} #{value.inspect}; " \
-                             "#{field} is #{type_name(FIELDS.fetch(kind).fetch(field))}")
-            end
-            STRUCTS.fetch(kind).new(**typed)
-          end
-        end
+        def self.build(kind, members, problems) = RowReader.new(kind, problems).call(members)
         private_class_method :build
 
-        def self.typed?(value, type) = type == :bool ? [true, false].include?(value) : value.is_a?(type)
-        private_class_method :typed?
-
-        def self.type_name(type) = type == :bool ? "true or false" : "a #{type}"
-        private_class_method :type_name
-
         # @param records [Hash{Symbol => Array<Struct>}] the rows of each kind
         # @param table [Table] the checked route table
         # @param vocabulary [Hash{Symbol => Array<String>}] the closed sets
@@ -110,21 +90,30 @@ module Hecks
         # @param template [String, nil] the template the caller names, if any
         # @raise [Table::Invalid] naming every problem when there is one
         def initialize(records, table:, vocabulary:, problems:, template: nil)
+          assign(records)
+          Checks.new(self, table.rows, vocabulary, problems, template_named: !template.nil?).call
+          build_outputs(table, problems) if problems.empty?
+          return if problems.empty?
+
+          raise Table::Invalid, "the edge is refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
+        end
+
+        # Reads the checked rows into the accessors, then builds what the routes need from them.
+        def assign(records)
           @setting = records.fetch(:setting).first
           @policies = records.fetch(:policy)
           @upstreams = records.fetch(:upstream)
           @rules = records.fetch(:rule)
-          Checks.new(self, table.rows, vocabulary, problems, template_named: !template.nil?).call
-          if problems.empty?
-            @listener_rules = alb? ? Rules.new(self, table.rows, problems).call : []
-            built = Behaviours.new(self, table.rows, problems).call
-            @default_behaviour = built.fetch(:default)
-            @behaviours = built.fetch(:list)
-          end
-          return if problems.empty?
+        end
+        private :assign
 
-          raise Table::Invalid, "the edge is refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
+        def build_outputs(table, problems)
+          @listener_rules = alb? ? Rules.new(self, table.rows, problems).call : []
+          built = Behaviours.new(self, table.rows, problems).call
+          @default_behaviour = built.fetch(:default)
+          @behaviours = built.fetch(:list)
         end
+        private :build_outputs
 
         # @return [Boolean] whether the project has a load balancer, and so listener rules; true
         #   unless the `Edge` row says `alb: false`

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

@@ -88,12 +88,14 @@ module Hecks
 
         def generated_behaviours
           list = [[DEFAULT, @edge.default_behaviour], *@edge.behaviours.map { |entry| [entry[:path], entry] }]
-          list.to_h do |path, entry|
-            [path, { path: path, origin: entry[:origin], methods: Array(entry[:methods]).sort, cached: %w[GET HEAD],
-                     protocol: entry[:viewer_protocol], compress: entry[:compress] == true,
-                     cache: policy_id(entry[:cache_policy]), request: policy_id(entry[:origin_request_policy]),
-                     response: policy_id(entry[:response_headers_policy]) }]
-          end
+          list.to_h { |path, entry| [path, generated_entry(path, entry)] }
+        end
+
+        def generated_entry(path, entry)
+          { path: path, origin: entry[:origin], methods: Array(entry[:methods]).sort, cached: %w[GET HEAD],
+            protocol: entry[:viewer_protocol], compress: entry[:compress] == true,
+            cache: policy_id(entry[:cache_policy]), request: policy_id(entry[:origin_request_policy]),
+            response: policy_id(entry[:response_headers_policy]) }
         end
 
         def policy_id(policy) = policy&.first
@@ -154,7 +156,7 @@ module Hecks
           theirs = current.keys.reject { |path| path == DEFAULT || !generated.key?(path) }
           return [] if mine == theirs
 
-          ["order differs among the behaviours both have:\n    project: #{mine.join(' ')}\n    live:    #{theirs.join(' ')}"]
+          ["order differs among the behaviours both have:\n    project: #{mine.join(" ")}\n    live:    #{theirs.join(" ")}"]
         end
       end
     end

data/lib/hecks/projections/site/payload/fields/definitions.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        module Fields
+          # The TypeScript literals of a collection's field definitions: one `{ name, type, ... }`
+          # for a scalar, an array field for a list, and an array of sub-fields for a composite.
+          module Definitions
+            module_function
+
+            # @return [Array<Array<String>>] the `[key, value]` pairs of a scalar field's literal
+            def base(attr, row, name, required)
+              kind = Fields.kind_of(attr, row)
+              required = row[:required] if row.key?(:required)
+              pairs = [["name", name.to_json], ["type", KINDS.fetch(kind).to_json]]
+              pairs << ["required", "true"] if required
+              pairs << ["unique", "true"] if attr.name == "slug"
+              pairs << ["defaultValue", row[:default].to_json] if row[:default]
+              pairs.concat(extras(kind, row))
+            end
+
+            def extras(kind, row, describe: true)
+              pairs = []
+              pairs << ["options", options(row[:options])] if kind == "select" && row[:options]
+              pairs << ["relationTo", row[:relation].to_json] if row[:relation]
+              admin = admin_pairs(kind, row, describe)
+              pairs << ["admin", "{ #{admin.map { |key, value| "#{key}: #{value}" }.join(", ")} }"] if admin.any?
+              pairs
+            end
+
+            def admin_pairs(kind, row, describe)
+              admin = []
+              admin << ["description", row[:description].to_json] if describe && row[:description]
+              if KINDS[kind] == "date"
+                admin << ["date",
+                          "{ pickerAppearance: #{(kind == "day" ? "dayOnly" : "dayAndTime").to_json} }"]
+              end
+              admin
+            end
+
+            def options(text)
+              items = text.split(",").map(&:strip).reject(&:empty?).map do |item|
+                value, label = item.split("=", 2)
+                label ? "{ label: #{label.to_json}, value: #{value.to_json} }" : value.to_json
+              end
+              "[#{items.join(", ")}]"
+            end
+
+            def literal(pairs) = "{ #{pairs.map { |key, value| "#{key}: #{value}" }.join(", ")} }"
+
+            def array(_attr, row, name)
+              kind = row[:kind] || "text"
+              element = literal([["name", '"value"'], ["type", KINDS.fetch(kind).to_json], ["required", "true"],
+                                 *extras(kind, row, describe: false)])
+              array_literal(name, row, "[#{element}]")
+            end
+
+            def composite(attr, row, name, rows)
+              subs = attr.parts.map { |part| sub_field(attr, part, rows) }
+              array_literal(name, row, "[#{subs.join(", ")}]")
+            end
+
+            def sub_field(attr, part, rows)
+              part_row = Fields.row_for(rows, attr.name, part.name)
+              literal(base(part, part_row.merge(required: part_row.fetch(:required, true)), part.ts, true))
+            end
+
+            # An array field named `name`, with the labels and description its row gives.
+            def array_literal(name, row, fields)
+              pairs = [["name", name.to_json], ["type", '"array"']]
+              pairs << ["labels", labels(row[:label])] if row[:label]
+              pairs << ["admin", "{ description: #{row[:description].to_json} }"] if row[:description]
+              pairs << ["fields", fields]
+              literal(pairs)
+            end
+
+            def labels(text)
+              singular, plural = text.split("|", 2)
+              "{ singular: #{singular.to_json}, plural: #{(plural || "#{singular}s").to_json} }"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/payload/fields/readers.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        module Fields
+          # The TypeScript expressions that read one saved document field back into the aggregate's
+          # input: a scalar, a list, a related document, a date or a composite's rows.
+          module Readers
+            module_function
+
+            def input(attr, row, rows)
+              return composite_input(attr, rows) if attr.shape == :composite
+
+              name = row[:field] || attr.ts
+              kind = Fields.kind_of(attr, row)
+              return list_input(name, kind) if attr.list
+
+              scalar_input(attr, row, name, kind)
+            end
+
+            def list_input(name, kind) = "valuesOf(doc.#{name}, #{kind == "date" ? "isoOrNull" : "nonBlank"})"
+
+            def scalar_input(attr, row, name, kind)
+              case kind
+              when "upload", "relationship" then related_input(row, name, kind)
+              when "date", "day" then date_input(attr, name, kind)
+              when "number" then number_input(attr, name)
+              else attr.optional ? "nonBlank(doc.#{name})" : "String(doc.#{name})"
+              end
+            end
+
+            def related_input(row, name, kind)
+              via = row[:via] || (kind == "upload" ? "url" : "slug")
+              "await related(req, #{row[:relation].to_json}, doc.#{name}, #{via.to_json})"
+            end
+
+            def number_input(attr, name)
+              attr.optional ? "doc.#{name} == null ? null : Number(doc.#{name})" : "Number(doc.#{name})"
+            end
+
+            def date_input(attr, name, kind)
+              return "isoOrNull(doc.#{name})#{' ?? ""' unless attr.optional}" unless attr.shape == :integer || kind == "day"
+
+              stamp = "doc.#{name} ? new Date(doc.#{name} as string).getTime() : Date.now()"
+              "Math.floor((#{stamp}) / 1000)"
+            end
+
+            def composite_input(attr, rows)
+              parts = attr.parts.map do |part|
+                "#{part.ts}: #{part_input(part, Fields.row_for(rows, attr.name, part.name))}"
+              end.join(", ")
+              "(Array.isArray(doc.#{attr.ts}) ? doc.#{attr.ts} : []).map((raw) => { const s = raw as Doc; return { #{parts} }; })"
+            end
+
+            def part_input(part, row)
+              return "isoOrNull(s.#{part.ts}) ?? \"\"" if KINDS[row[:kind]] == "date"
+
+              "nonBlank(s.#{part.ts}) ?? \"\""
+            end
+          end
+        end
+      end
+    end
+  end
+end