foobara-aws 0.1.0

data/lib/foobara/aws/handler.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+# Serving a Foobara command from AWS Lambda.
+#
+# RUNTIME, not synth. Require this file and nothing else from the gem: it loads
+# no planning code and no CDK, because cold start is on the critical path of
+# every request and a deployment tool has no business being there.
+#
+#   require "foobara/aws/handler"
+#   require_relative "config/boot"
+#
+#   HANDLER = Foobara::AWS::Handler.new { |connector| Posts.foobara_all_command... }
+#
+#   def handle(event:, context:) = HANDLER.call(event, context)
+#
+# The connector is built by the caller, because which commands a unit registers
+# — and how it authenticates them — is the application's business. What this
+# owns is the translation either side of it.
+
+require_relative "error"
+require_relative "version"
+
+module Foobara
+  module AWS
+    class << self
+      # WHO IS CALLING, for the duration of one invocation.
+      #
+      # Foobara authenticates only commands declaring `requires_authentication`,
+      # which answers "may this caller in?" but not "who is this?". A command
+      # that is public AND viewer-aware — one that marks your own posts editable
+      # — needs the second without the first, and Foobara has nowhere to put it.
+      #
+      # So the handler puts it here, and an application reads it from its
+      # connector's authenticator and from any command that needs the viewer as
+      # data. A thread-local is not elegant; it is the smallest thing that works
+      # until Foobara grows a notion of optional identity.
+      def current_caller = Thread.current[:foobara_aws_caller]
+
+      # Not an endless def: Ruby does not allow a setter to be one.
+      def current_caller=(value)
+        Thread.current[:foobara_aws_caller] = value
+      end
+
+      # Turns the authorizer's verified claims into whatever the application
+      # wants as its caller. Set once, in the app's boot file, so the generated
+      # handler needs no application-specific code in it.
+      #
+      #   Foobara::AWS.caller_builder = ->(claims) { Viewer.new(claims["sub"], claims["name"]) }
+      attr_accessor :caller_builder
+    end
+
+    # Adapts an API Gateway v2 payload to what a Rack connector wants, and the
+    # authorizer's verified claims to the caller.
+    class Handler
+      # The claims a REQUEST authorizer returned, in SIMPLE format. API Gateway
+      # forwards only strings, so everything here is a string.
+      CLAIMS_PATH = %w[requestContext authorizer lambda].freeze
+
+      # +viewer+ receives the claims hash (empty for an anonymous caller on a
+      # public command) and returns whatever the application wants as its
+      # caller — a Struct, a model, anything. Return nil for "nobody".
+      #
+      # +dev_identity+ enables the X-Dev-Sub / X-Dev-Name escape hatch for local
+      # work. It defaults to OFF and must stay off in a deployed unit: those
+      # headers are unauthenticated, so honouring them would let any caller name
+      # themselves — including on the commands the authorizer just gated, and on
+      # the public-but-viewer-aware ones it lets through anonymously.
+      def initialize(connector, viewer: nil, dev_identity: false)
+        @connector = connector
+        @viewer = viewer
+        @dev_identity = dev_identity
+      end
+
+      # Identity is established BEFORE the connector runs and cleared after,
+      # whatever happens — a leaked caller would be served to whoever reuses this
+      # execution environment next, which is the worst possible bug to have.
+      def call(event, _context = nil)
+        env = rack_env(event)
+        AWS.current_caller = identify(event, env)
+
+        respond(@connector.call(env))
+      ensure
+        AWS.current_caller = nil
+      end
+
+      # What the authorizer verified, or the dev headers when explicitly allowed.
+      # Public so an application can reuse it for its own middleware.
+      def identify(event, env = nil)
+        claims = event.dig(*CLAIMS_PATH) || {}
+        claims = dev_identity(env || rack_env(event)) || {} if claims.empty? && @dev_identity
+        return nil if claims.empty?
+
+        builder = @viewer || AWS.caller_builder
+        builder ? builder.call(claims) : claims
+      end
+
+      private
+
+      def respond(rack_response)
+        status, headers, body = rack_response
+        { "statusCode" => status, "headers" => headers, "body" => Array(body).join }
+      end
+
+      def rack_env(event)
+        request = event["requestContext"] || {}
+        http = request["http"] || {}
+
+        env = {
+          "REQUEST_METHOD" => http["method"] || "POST",
+          # Passed through unchanged. The route IS the connector's own path, so
+          # stripping a prefix here would break dispatch.
+          "PATH_INFO" => event["rawPath"] || http["path"] || "",
+          "QUERY_STRING" => event["rawQueryString"].to_s,
+          "rack.input" => StringIO.new(decoded_body(event)),
+          "rack.errors" => $stderr
+        }
+        (event["headers"] || {}).each { |k, v| env["HTTP_#{k.upcase.tr("-", "_")}"] = v }
+        env
+      end
+
+      # API Gateway base64-encodes a binary body and says so. Ignoring the flag
+      # turns an uploaded byte into mojibake far from where it happened.
+      def decoded_body(event)
+        body = event["body"].to_s
+        event["isBase64Encoded"] ? body.unpack1("m") : body
+      end
+
+      def dev_identity(env)
+        sub = env["HTTP_X_DEV_SUB"]
+        name = env["HTTP_X_DEV_NAME"]
+        return nil unless sub
+
+        { "sub" => sub, "name" => name || sub }
+      end
+    end
+  end
+end
+
+require "stringio"

data/lib/foobara/aws/lambda.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Foobara
+  module AWS
+    # Declares how a command should be RUN, next to the command that says what it
+    # does:
+    #
+    #   class DestroyPost < Foobara::Command
+    #     extend Foobara::AWS::Lambda
+    #     aws_lambda vcpu: 1, timeout: 60
+    #     ...
+    #   end
+    #
+    # This is the one thing a manifest cannot otherwise supply. Foobara describes
+    # what a command IS, not how it should be run — a defensible line, but
+    # something has to carry it, and the person who knows a command fans out
+    # across a whole comment tree is the person writing the command.
+    #
+    # No change to Foobara is needed: a command's manifest is `super.merge(...)`,
+    # so this adds a key and the connector serves it. {Foobara::AWS.plan} reads it
+    # back, and {Service} sizes each function from it.
+    #
+    # ON vcpu. Lambda has no CPU setting — CPU is allocated in proportion to
+    # memory, and 1769 MB is the point at which a function gets one full vCPU.
+    # So `vcpu:` is a more honest way to ask for compute than picking a memory
+    # number, but it RESOLVES to memory; it is not a second dial. Give both and
+    # the larger memory wins, because undersizing is a runtime failure while
+    # oversizing is a rounding error on the bill.
+    module Lambda
+      # AWS's own figure: one vCPU is allocated at 1,769 MB.
+      MEMORY_PER_VCPU = 1769
+
+      # Lambda's floor and ceiling. Asking outside them fails at deploy time,
+      # which is a slow way to learn about a typo.
+      MEMORY_RANGE = (128..10_240)
+      TIMEOUT_RANGE = (1..900)
+
+      def aws_lambda(memory: nil, vcpu: nil, timeout: nil)
+        memory = resolve_memory(memory, vcpu)
+
+        if memory && !MEMORY_RANGE.cover?(memory)
+          raise ArgumentError, "aws_lambda memory #{memory} outside Lambda's #{MEMORY_RANGE}"
+        end
+        if timeout && !TIMEOUT_RANGE.cover?(timeout)
+          raise ArgumentError, "aws_lambda timeout #{timeout} outside Lambda's #{TIMEOUT_RANGE} seconds"
+        end
+
+        @aws_lambda = { "memory_size" => memory, "timeout_seconds" => timeout }.compact
+      end
+
+      def aws_lambda_manifest = @aws_lambda
+
+      def foobara_manifest
+        manifest = super
+        @aws_lambda ? manifest.merge(aws_lambda: @aws_lambda) : manifest
+      end
+
+      private
+
+      def resolve_memory(memory, vcpu)
+        return memory unless vcpu
+
+        [memory, (vcpu * MEMORY_PER_VCPU).ceil].compact.max
+      end
+    end
+  end
+end

data/lib/foobara/aws/packager.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require "digest"
+require "erb"
+require "fileutils"
+require "json"
+
+require_relative "error"
+require_relative "plan"
+
+module Foobara
+  module AWS
+    # Builds one deployable artifact per unit in a {Plan}.
+    #
+    # BUILD time — neither runtime nor synth. It shells out to Docker, so it is
+    # required explicitly and never from a Lambda or a CDK app.
+    #
+    #   Foobara::AWS::Packager.new(plan:, root: ".", out: "build").build
+    #
+    # Each artifact contains the application's sources, a generated `handler.rb`,
+    # and a standalone gem bundle holding only that unit's dependencies. Units
+    # whose gemfiles resolve identically share one bundle build.
+    #
+    # It also writes the plan next to them. That is the contract with synthesis:
+    # the CDK app reads what was BUILT, so it cannot route to an artifact that
+    # does not exist, and it needs neither a running connector nor the app.
+    class Packager
+      # A Lambda-like container, so native extensions are built against the
+      # runtime's own libraries rather than the host's.
+      DEFAULT_IMAGE = "public.ecr.aws/sam/build-ruby4.0"
+
+      # Bundler's standalone mode, NOT `bundle exec`: Bundler's runtime costs
+      # several hundred milliseconds at Lambda's smaller memory sizes, on every
+      # cold start, for nothing a deployed artifact needs.
+      BUNDLE_COMMAND = "bundle install --standalone"
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(plan:, root: Dir.pwd, out: "build", sources: %w[app config],
+                     gemfiles: "units", image: DEFAULT_IMAGE, env: {}, mounts: [],
+                     handler_template: nil, authorizer: nil, docker: nil)
+        @plan = plan
+        @root = File.expand_path(root)
+        @out = File.expand_path(out, @root)
+        @sources = sources
+        @gemfiles = gemfiles
+        @image = image
+        @env = env
+        # Extra host paths to mount. A gemfile referencing a gem by path outside
+        # the application root would otherwise fail inside the container, which
+        # sees only the root.
+        @mounts = mounts
+        @handler_template = handler_template
+        @authorizer = authorizer
+        # Injectable so the layout can be tested without Docker, and so an
+        # environment with a different container runtime can substitute one.
+        @docker = docker || method(:run_docker)
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def build
+        FileUtils.mkdir_p(@out)
+
+        built = @plan.units.map { |unit| build_unit(unit) }
+        built << build_authorizer if @authorizer
+
+        File.write(plan_path, JSON.pretty_generate(@plan.to_h))
+        built
+      end
+
+      def plan_path = File.join(@out, "plan.json")
+
+      private
+
+      def build_unit(unit)
+        dir = prepare(unit.name)
+        @sources.each { |s| FileUtils.cp_r(File.join(@root, s), dir) }
+        File.write(File.join(dir, "handler.rb"), handler_source(unit))
+        vendor(unit.name, dir)
+
+        { name: unit.name, dir: dir, commands: unit.commands.length }
+      end
+
+      # The authorizer is a deployment unit but not a plan unit: it serves no
+      # commands and needs none of the application — only this gem and jwt.
+      # Giving it the app's sources would put the whole domain model on the cold
+      # start of every authenticated request.
+      def build_authorizer
+        name = @authorizer.fetch(:name, "authorizer")
+        dir = prepare(name)
+        File.write(File.join(dir, "handler.rb"), authorizer_source)
+        vendor(name, dir)
+
+        { name: name, dir: dir, commands: 0 }
+      end
+
+      def prepare(name)
+        dir = File.join(@out, name)
+        FileUtils.rm_rf(dir)
+        FileUtils.mkdir_p(dir)
+        dir
+      end
+
+      def handler_source(unit)
+        template = @handler_template ? File.read(@handler_template) : DEFAULT_HANDLER
+        render(template, unit)
+      end
+
+      def authorizer_source
+        template = @authorizer[:template] ? File.read(@authorizer[:template]) : DEFAULT_AUTHORIZER
+        render(template, nil)
+      end
+
+      def render(template, unit)
+        ERB.new(template, trim_mode: "-").result(binding)
+      end
+
+      # One bundle per distinct gemfile, keyed by its contents. Units that
+      # resolve identically then share a build rather than repeating it — the
+      # difference between one docker run and one per unit.
+      def vendor(name, dir)
+        gemfile = File.join(@root, @gemfiles, "#{name}.gemfile")
+        raise Error, "no gemfile for unit #{name.inspect} at #{gemfile}" unless File.exist?(gemfile)
+
+        cache = File.join(@out, ".bundles", Digest::SHA256.hexdigest(File.read(gemfile))[0, 16])
+        unless File.directory?(File.join(cache, "bundler"))
+          build_bundle(gemfile, cache)
+          vendor_path_gems!(cache, gemfile)
+        end
+
+        FileUtils.mkdir_p(File.join(dir, "vendor"))
+        FileUtils.cp_r(cache, File.join(dir, "vendor/bundle"))
+      end
+
+      def build_bundle(gemfile, cache)
+        FileUtils.mkdir_p(cache)
+        ok = @docker.call(gemfile, cache)
+        raise Error, "bundle install failed for #{gemfile}" unless ok
+      end
+
+      # A gem declared by `path:` is NOT copied into a standalone bundle —
+      # bundler adds its location to the load path instead. That location is
+      # written RELATIVE to the bundle directory, so once the bundle is copied
+      # into an artifact it resolves somewhere else entirely, and the unit boots
+      # on the build machine and dies in Lambda with a LoadError.
+      #
+      # Copy each such gem in and rewrite the load path to point at the copy.
+      # Only lib and exe: an artifact needs neither specs nor .git.
+      #
+      # The lockfile is the source of truth for WHICH gems those are. Detecting
+      # them by inspecting the generated paths is guesswork that has already
+      # changed once between bundler versions.
+      def vendor_path_gems!(cache, gemfile)
+        setup = File.join(cache, "bundler", "setup.rb")
+        return unless File.exist?(setup)
+
+        roots = path_gem_roots(gemfile)
+        return if roots.empty?
+
+        source = File.read(setup)
+        roots.each { |root| source = vendor_one(cache, root, source) }
+        File.write(setup, source)
+      end
+
+      # PATH sections of the unit's lockfile, resolved against the gemfile that
+      # declared them.
+      def path_gem_roots(gemfile)
+        lock = "#{gemfile}.lock"
+        return [] unless File.exist?(lock)
+
+        File.read(lock).scan(/^PATH\n  remote: (.+)$/).flatten.map do |remote|
+          File.expand_path(remote.strip, File.dirname(gemfile))
+        end
+      end
+
+      def vendor_one(cache, root, source)
+        name = File.basename(root)
+        dest = File.join(cache, "path-gems", name)
+
+        FileUtils.rm_rf(dest)
+        FileUtils.mkdir_p(dest)
+        %w[lib exe].each do |sub|
+          from = File.join(root, sub)
+          FileUtils.cp_r(from, dest) if File.exist?(from)
+        end
+
+        source.gsub(%r{^\$:\.unshift File\.expand_path\("[^"]*/#{Regexp.escape(name)}/([^"]+)"\)$}) do
+          %($:.unshift File.expand_path("\#{__dir__}/../path-gems/#{name}/#{Regexp.last_match(1)}"))
+        end
+      end
+
+      def run_docker(gemfile, cache)
+        env_args = @env.flat_map { |k, v| ["-e", "#{k}=#{v}"] }
+        # Mounted at the same path they have on the host, so the absolute paths
+        # bundler writes resolve identically in both places.
+        mount_args = @mounts.flat_map { |path| ["-v", "#{File.expand_path(path)}:#{File.expand_path(path)}"] }
+
+        system(
+          "docker", "run", "--rm", "--platform", "linux/amd64",
+          # As the invoking user, or the build output is root-owned and the next
+          # step cannot read it. HOME because bundler writes there and the
+          # container has none for this uid.
+          "--user", "#{Process.uid}:#{Process.gid}", "-e", "HOME=/tmp",
+          *env_args, *mount_args,
+          "-v", "#{@root}:#{@root}", "-v", "#{cache}:/vendor", "-w", @root,
+          "--entrypoint", "bash", @image, "-c",
+          "set -e; export BUNDLE_GEMFILE=#{gemfile} BUNDLE_PATH=/vendor; #{BUNDLE_COMMAND}",
+          out: File::NULL
+        )
+      end
+
+      # Generic because everything unit-specific comes from the plan and
+      # everything app-specific comes from the boot file: an application sets
+      # Foobara::AWS.caller_builder there, and nothing else is needed here.
+      DEFAULT_HANDLER = <<~ERB
+        # Generated by foobara-aws for unit <%= unit.name.inspect %>. Do not edit.
+        #
+        # Serves: <%= unit.commands.join(", ") %>
+        #
+        # NOTE the standalone require rather than `bundle exec`: Bundler's runtime
+        # is a large fraction of a Ruby cold start and buys a deployed artifact
+        # nothing.
+        require_relative "vendor/bundle/bundler/setup"
+        require "foobara/aws/handler"
+        require_relative "config/boot"
+        require "foobara/rack_connector"
+
+        # This unit registers exactly its own commands. It does not have to
+        # REFUSE the others — they were never connected, so there is nothing to
+        # refuse, and an unknown path 404s by construction.
+        PUBLIC_COMMANDS = <%= unit.public_commands.inspect %>.freeze
+
+        CONNECTOR = Foobara::CommandConnectors::Http::Rack.new(
+          # instance_exec'd against the request, so it takes no argument.
+          # It reads what the handler already resolved from verified claims.
+          authenticator: -> { Foobara::AWS.current_caller }
+        )
+
+        <%= unit.commands.inspect %>.each do |name|
+          CONNECTOR.connect(
+            Object.const_get(name),
+            requires_authentication: !PUBLIC_COMMANDS.include?(name)
+          )
+        end
+
+        HANDLER = Foobara::AWS::Handler.new(
+          CONNECTOR,
+          dev_identity: ENV["FOOBARA_DEV_IDENTITY"] == "1"
+        )
+
+        def handle(event:, context:)
+          HANDLER.call(event, context)
+        end
+      ERB
+
+      DEFAULT_AUTHORIZER = <<~ERB
+        # Generated by foobara-aws. Do not edit.
+        #
+        # The optional-auth authorizer. Its public list and mount come from the
+        # environment, which the CDK Service sets from the plan — so which
+        # commands are reachable anonymously is derived from
+        # requires_authentication and never maintained by hand.
+        require_relative "vendor/bundle/bundler/setup"
+        require "foobara/aws/authorizer"
+
+        HANDLER = Foobara::AWS::Authorizer.from_env(
+          issuer: ENV.fetch("FOOBARA_ISSUER"),
+          audience: ENV.fetch("FOOBARA_AUDIENCE", "").split(",")
+        )
+
+        def handle(event:, context:)
+          HANDLER.call(event, context)
+        end
+      ERB
+    end
+  end
+end