hecks 2.6.0 → 2.8.0

data/lib/hecks/projections/deploy/lambda.rb

@@ -148,7 +148,7 @@ module Hecks
           # `stack_name` at all. They diverge on purpose for a domain whose
           # declared identity (`Hecks.bluebook`, hence `world.domain`, hence
           # `.world`'s own filename — `domain_name` above, needed just to find
-          # that file) no longer matches its live AWS stack's own name: a
+          # that file) does not match its live AWS stack's own name: a
           # CloudFormation stack cannot be renamed in place, and this domain's
           # logical ids are already load-bearing on a real RDS instance other
           # domains borrow from in Shared mode (see `owner_stack_name` below) —
@@ -1039,10 +1039,10 @@ module Hecks
                     # matching this stack's own name), a question `infra_name`
                     # answers and a domain's own business identity does not.
                     # Real, live, and confirmed the hard way: this was still
-                    # wired to `declared_domain_name` when EmbryonautFoundersApp
+                    # wired to `declared_domain_name` when a client app
                     # first deployed, and WebFunction immediately threw
                     # `ResourceNotFoundException: Function not found:
-                    # hecks-embryonautfoundersapp` on every read AND on the
+                    # hecks-<domain>` on every read AND on the
                     # Google OAuth callback itself — a real signed-in user hit
                     # this within minutes of the deploy that introduced it.
                     DOMAIN_NAME: #{infra_name}
@@ -1246,7 +1246,7 @@ module Hecks
             template_yaml = template_yaml.sub(
               /^        - LambdaInvokePolicy:\n            FunctionName: !Ref #{Regexp.escape(logical_id)}\n/, ""
             )
-            # Outputs — no `#{logical_id}Url` exists any more for `FunctionUrl` to
+            # Outputs — no `#{logical_id}Url` exists for `FunctionUrl` to
             # `!GetAtt`; WebFunction's own URL becomes the stack's one and only
             # "FunctionUrl" (never "WebFunctionUrl" — that name is reserved for
             # the two-URL case, a domain that also has a #{logical_id} of its
@@ -1317,7 +1317,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
               # aggregates with no snapshot table at all -- it only provisions the
               # ONE bluebook it's called with (era_resolver.rb's own `bluebook.
               # aggregates.each`), never the whole registry. Found live minting
-              # lifeadelics' own era: `Payments::Payment.Initiate` refused with
+              # a client site's own era: `Payments::Payment.Initiate` refused with
               # "relation \\"payment_head_snapshot_1\\" does not exist" the first
               # time this domain's own checkout route ran for real. The automated
               # (non-Shared) recipe below now does this correctly for every OTHER
@@ -1490,7 +1490,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
           # `Hecks::Bluebook::Behaviour::World#for_binding` nor
           # `PostgresEra.connect_for` ever reads `ENV["DATABASE_URL"]` or
           # `ENV["HECKS_SCHEMA"]` — both scripts call
-          # `registry.world(bluebook.name)&.for_binding(...)`, a pure hash lookup
+          # `registry.binding_settings(...)`, a pure hash lookup
           # against whatever literal `database "..."` string #{domain}'s own
           # `.world` file declares. Without `db_env_blind:` below, this whole
           # recipe would stand up a real bastion, punch a live 5432 ingress rule
@@ -1722,7 +1722,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
           # `shared` are collected together here rather than spelled as an
           # if/elsif/else, the same shape `Parameters:` above holds to: the
           # two are independent facts about a domain, not alternatives, and
-          # lifeadelics is both — an elsif shape would silently drop the
+          # a client site can be both — an elsif shape would silently drop the
           # Owning* overrides whenever OAuth is also present. Caught live
           # the first time a Shared-mode domain with real Google OAuth
           # actually ran `make deploy`: `sam deploy` refused
@@ -2287,7 +2287,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
           reindent = ->(text) { text.each_line.map { |line| line.strip.empty? ? line : "  #{line}" }.join }
 
           # Not pre-reindented (unlike the return value as a whole, below) — each
-          # is spliced back into the still-being-dedented RESOURCES heredoc via
+          # is spliced back into the still-being-dedented `RESOURCES` heredoc via
           # `#{...}`, which the outer `reindent.call` already shifts by 2
           # spaces once; reindenting here too would double it.
           origin_access_control = use_oac ? <<~OAC : ""

data/lib/hecks/projections/deploy/preview/access_yaml.rb

@@ -0,0 +1,145 @@
+require_relative "yaml_text"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Preview
+        # The secrets and IAM roles of a preview stack.
+        #
+        # The task role reads the shared database secret and this preview's own
+        # secrets and nothing owned by the main stack. The execution role also reads
+        # the database secret, only so the one-shot task can receive the credentials
+        # as container secrets.
+        module AccessYaml
+          extend YamlText
+
+          module_function
+
+          # Renders the secrets a preview generates: its session secret and the ones
+          # containers declare.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [Array<String>] one YAML resource block per secret
+          def secrets(settings)
+            [session_secret, *settings.containers.flat_map { |c| container_secrets(c) }]
+          end
+
+          # Renders the per-branch session secret the host reads at start.
+          #
+          # @return [String] the secret's resource block
+          def session_secret
+            <<~YAML.chomp
+              # No explicit Name: Secrets Manager keeps a deleted secret through its recovery window,
+              # and a fixed name would make destroy followed by deploy on one branch fail.
+              SessionSecret:
+                Type: AWS::SecretsManager::Secret
+                Properties:
+                  Description: !Sub "Session secret of the ${EnvName} preview."
+                  GenerateSecretString:
+                    SecretStringTemplate: '{}'
+                    GenerateStringKey: session_secret
+                    PasswordLength: 64
+                    ExcludePunctuation: true
+            YAML
+          end
+
+          # Renders one generated secret per name a container declares.
+          #
+          # @param container [Containers::Entry] the container
+          # @return [Array<String>] one resource block per declared secret name
+          def container_secrets(container)
+            container.secrets.map do |name|
+              <<~YAML.chomp
+                #{secret_id(container, name)}:
+                  Type: AWS::SecretsManager::Secret
+                  Properties:
+                    Description: !Sub "#{name} of the ${EnvName} preview's #{container.name} container."
+                    GenerateSecretString:
+                      SecretStringTemplate: '{}'
+                      GenerateStringKey: secret
+                      PasswordLength: 64
+                      ExcludePunctuation: true
+              YAML
+            end
+          end
+
+          # Renders the task execution role and the task role.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [Array<String>] the two role resource blocks
+          def roles(settings)
+            assume = <<~YAML.chomp
+              AssumeRolePolicyDocument:
+                Version: '2012-10-17'
+                Statement:
+                  - Effect: Allow
+                    Principal: { Service: ecs-tasks.amazonaws.com }
+                    Action: sts:AssumeRole
+            YAML
+            [execution_role(assume), task_role(assume, settings)]
+          end
+
+          # Renders the execution role, which pulls images and hands the one-shot task
+          # its credentials.
+          #
+          # @param assume [String] the shared trust policy block
+          # @return [String] the role's resource block
+          def execution_role(assume)
+            <<~YAML.chomp
+              # The execution role reads the database secret only so the one-shot task can be given
+              # its credentials as container secrets.
+              ExecutionRole:
+                Type: AWS::IAM::Role
+                Properties:
+              #{indent(assume, 4)}
+                  ManagedPolicyArns:
+                    - arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
+                  Policies:
+                    - PolicyName: SharedDatabaseSecretRead
+                      PolicyDocument:
+                        Version: '2012-10-17'
+                        Statement:
+                          - Effect: Allow
+                            Action: secretsmanager:GetSecretValue
+                            Resource: !Ref OwningDatabaseSecretArn
+            YAML
+          end
+
+          # Renders the task role: read access to the shared database secret and this
+          # preview's own secrets.
+          #
+          # @param assume [String] the shared trust policy block
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the role's resource block
+          def task_role(assume, settings)
+            readable = ["SessionSecret", *settings.containers.flat_map { |c| c.secrets.map { |n| secret_id(c, n) } }]
+            <<~YAML.chomp
+              # Reads the shared database secret (it connects with it and creates its database) and
+              # this preview's own secrets; nothing owned by the main stack.
+              TaskRole:
+                Type: AWS::IAM::Role
+                Properties:
+              #{indent(assume, 4)}
+                  Policies:
+                    - PolicyName: SharedDatabaseSecretRead
+                      PolicyDocument:
+                        Version: '2012-10-17'
+                        Statement:
+                          - Effect: Allow
+                            Action: secretsmanager:GetSecretValue
+                            Resource: !Ref OwningDatabaseSecretArn
+                    - PolicyName: PreviewSecretRead
+                      PolicyDocument:
+                        Version: '2012-10-17'
+                        Statement:
+                          - Effect: Allow
+                            Action: secretsmanager:GetSecretValue
+                            Resource:
+              #{indent(readable.map { |id| "- !Ref #{id}" }.join("\n"), 16)}
+            YAML
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/deploy/preview/containers.rb

@@ -0,0 +1,218 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Preview
+        # The containers one preview task runs, in one normalized shape.
+        #
+        # A preview task runs the same containers as the stack it previews.
+        # This module is the single place that decides which containers those
+        # are, so the rest of `Preview` never asks where the list came from.
+        #
+        # ## One adapter to the shared setting
+        #
+        # The main Fargate stack is growing a multi-container setting.
+        # `shared_setting` is the only method that reads it; every other
+        # method here works on the normalized entries described below. When
+        # that setting lands with a different shape, translate it inside
+        # `shared_setting` and nothing else changes.
+        #
+        # ## Entry keys
+        #
+        # Each entry is a Hash with Symbol keys:
+        #
+        # - `name` (required): lowercase letters, digits and hyphens; also the
+        #   container name and the suffix of its ECR repository.
+        # - `port` (required): the port the container listens on. Unique
+        #   across the task, since all containers share one network namespace.
+        # - `health_check_path`: target group health check path, default `"/"`.
+        # - `paths`: load balancer path patterns forwarded to this container.
+        # - `default`: `true` sends every unmatched request here. When no
+        #   entry says so, the `host` entry is the default, else the first.
+        # - `host`: `true` marks the Hecks host container. It gets the domain,
+        #   session and database environment, and the signup path.
+        # - `database`: `true` gives a non-host container the database
+        #   environment as well. The host always has it.
+        # - `environment`: extra environment, name to value. `{{preview_url}}`
+        #   inside a value becomes the preview's public https URL.
+        # - `secrets`: environment variable names. Each becomes a per-branch
+        #   generated secret whose ARN is that variable's value.
+        # - `image`: the local docker image `preview.sh` pushes for this
+        #   container, default `"<name>:latest"`.
+        module Containers
+          # One normalized container of the preview task.
+          Entry = Data.define(:name, :port, :health_check_path, :paths, :default, :host, :database,
+                              :environment, :secrets, :image) do
+            # Answers the CloudFormation logical-id fragment for this container.
+            #
+            # @return [String] `name` in CamelCase, such as `"MySite"` for `"my-site"`
+            def logical = name.split("-").map(&:capitalize).join
+
+            # Answers whether the container is reachable through the load balancer.
+            #
+            # @return [Boolean] true when it is the default or owns any path
+            def routed? = default || !paths.empty?
+          end
+
+          NAME_PATTERN = /\A[a-z][a-z0-9-]{0,29}\z/
+          PATH_PATTERN = %r{\A/[A-Za-z0-9._~/*?%-]*\z}
+          IMAGE_PATTERN = %r{\A[A-Za-z0-9._/:@-]+\z}
+          ENV_NAME_PATTERN = /\A[A-Z_][A-Z0-9_]*\z/
+
+          module_function
+
+          # Answers the preview task's containers, normalized and validated.
+          #
+          # @param preview [Hash{Symbol => Object}] the preview settings; `:containers` wins
+          # @param deploy_settings [Hash{Symbol => Object}] the `deployed_to` settings, read
+          #   by `shared_setting`
+          # @param main [Hash{Symbol => Object}] the main stack's own facts; `:name`, `:port`,
+          #   `:image` describe the single container used when neither list is given
+          # @param signup_path [String, nil] path forwarded to the host container, or nil
+          # @return [Array<Entry>] at least one entry, exactly one of them the default
+          # @raise [ArgumentError] if an entry is malformed, a name or port repeats, or two
+          #   entries claim to be the default or the host
+          def resolve(preview:, deploy_settings:, main:, signup_path: nil)
+            raw = preview[:containers] || shared_setting(deploy_settings) || [single(main)]
+            entries = Array(raw).map { |item| normalize(item) }
+            check!(entries)
+            with_default(with_signup(entries, signup_path))
+          end
+
+          # Reads the main stack's own container list, when it declares one.
+          #
+          # This is the one hook to the multi-container setting shared with the
+          # main template; it answers entries in the shape documented above.
+          #
+          # @param deploy_settings [Hash{Symbol => Object}] the `deployed_to` settings
+          # @return [Array<Hash>, nil] the list, or nil when the stack runs one container
+          def shared_setting(deploy_settings)
+            deploy_settings[:containers]
+          end
+
+          # Builds the single-container entry a one-container stack previews as.
+          #
+          # @param main [Hash{Symbol => Object}] the main stack's facts, see `resolve`
+          # @return [Hash{Symbol => Object}] the entry, always the host and the default
+          def single(main)
+            name = main.fetch(:name).to_s.downcase.gsub(/[^a-z0-9]+/, "-").sub(/\A[^a-z]+/, "")[0, 30].sub(/-+\z/, "")
+            { name: name, port: main.fetch(:port), host: true, default: true, image: main[:image] }
+          end
+
+          # Turns one raw entry into an `Entry`, filling every default.
+          #
+          # @param item [Hash{Symbol => Object}] the raw entry, string keys accepted
+          # @return [Entry] the normalized entry
+          # @raise [ArgumentError] if the entry is not a Hash or lacks a valid `name` or `port`
+          def normalize(item)
+            raise ArgumentError, "preview container #{item.inspect} must be a Hash" unless item.is_a?(Hash)
+
+            item = item.transform_keys(&:to_sym)
+            name = matching(item[:name], NAME_PATTERN, "preview container name")
+            Entry.new(
+              name: name, port: port_of(item, name), health_check_path: path_of(item[:health_check_path] || "/"),
+              paths: Array(item[:paths]).map { |path| path_of(path) }, default: item[:default] == true,
+              host: item[:host] == true, database: item[:database] == true,
+              environment: environment_of(item[:environment]), secrets: Array(item[:secrets]).map(&:to_s),
+              image: matching(item[:image] || "#{name}:latest", IMAGE_PATTERN, "preview container #{name} image")
+            )
+          end
+
+          # Answers a value as a String, refusing one that does not match a pattern.
+          #
+          # @param value [Object] the raw value
+          # @param pattern [Regexp] what the string must match
+          # @param label [String] what the value is, for the message
+          # @return [String] the value as a String
+          # @raise [ArgumentError] if the string does not match
+          def matching(value, pattern, label)
+            text = value.to_s
+            raise ArgumentError, "#{label} #{text.inspect} must match #{pattern.inspect}" unless text.match?(pattern)
+
+            text
+          end
+
+          # Answers one path pattern, refusing one the template could not quote safely.
+          #
+          # @param path [Object] the raw path
+          # @return [String] the path
+          # @raise [ArgumentError] if it does not start with `/` or holds an unexpected character
+          def path_of(path) = matching(path, PATH_PATTERN, "preview container path")
+
+          # Reads and range-checks one entry's port.
+          #
+          # @param item [Hash{Symbol => Object}] the raw entry
+          # @param name [String] the entry's name, for the message
+          # @return [Integer] the port
+          # @raise [ArgumentError] if the port is missing or outside 1..65535
+          def port_of(item, name)
+            port = Integer(item[:port], exception: false)
+            raise ArgumentError, "preview container #{name} needs a port between 1 and 65535" unless port&.between?(1, 65_535)
+
+            port
+          end
+
+          # Stringifies an entry's environment, keeping declaration order.
+          #
+          # @param environment [Hash{Symbol, String => Object}, nil] the raw environment
+          # @return [Hash{String => String}] name to value
+          def environment_of(environment)
+            (environment || {}).to_h { |name, value| [name.to_s, value.to_s] }
+          end
+
+          # Refuses a list that cannot be one task.
+          #
+          # @param entries [Array<Entry>] the normalized entries
+          # @return [void]
+          # @raise [ArgumentError] on an empty list, a repeated name or port, more than one
+          #   default or host, or a secret name that is not an environment variable name
+          def check!(entries)
+            raise ArgumentError, "preview containers must not be empty" if entries.empty?
+
+            %i[name port].each do |field|
+              dup = entries.map(&field).tally.find { |_value, count| count > 1 }
+              raise ArgumentError, "preview containers repeat the #{field} #{dup.first.inspect}" if dup
+            end
+            check_roles!(entries)
+          end
+
+          # Refuses a second default or host, and a secret that is not an environment variable name.
+          #
+          # @param entries [Array<Entry>] the normalized entries
+          # @return [void]
+          # @raise [ArgumentError] on a second default or host, or a malformed secret name
+          def check_roles!(entries)
+            raise ArgumentError, "at most one preview container may be the default" if entries.count(&:default) > 1
+            raise ArgumentError, "at most one preview container may be the host" if entries.count(&:host) > 1
+
+            bad = entries.flat_map(&:secrets).find { |secret| !secret.match?(ENV_NAME_PATTERN) }
+            raise ArgumentError, "preview secret name #{bad.inspect} must be an environment variable name" if bad
+          end
+
+          # Adds the signup path to the host container's own paths.
+          #
+          # @param entries [Array<Entry>] the normalized entries
+          # @param signup_path [String, nil] the path, or nil for none
+          # @return [Array<Entry>] the entries, the host's paths extended when it needs a rule
+          def with_signup(entries, signup_path)
+            return entries unless signup_path
+
+            entries.map do |entry|
+              entry.host && !entry.default ? entry.with(paths: (entry.paths + [signup_path]).uniq) : entry
+            end
+          end
+
+          # Marks the default container when no entry does.
+          #
+          # @param entries [Array<Entry>] the normalized entries
+          # @return [Array<Entry>] the entries with exactly one default
+          def with_default(entries)
+            return entries if entries.any?(&:default)
+
+            chosen = entries.find(&:host) || entries.first
+            entries.map { |entry| entry.equal?(chosen) ? entry.with(default: true) : entry }
+          end
+        end
+      end
+    end
+  end
+end