foobara-aws 0.1.0

data/lib/foobara/aws/plan.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Foobara
+  module AWS
+    # One deployment unit: a Lambda, and the route that reaches it.
+    #
+    # +name+ is a stable identifier ("posts"), +route+ the API Gateway route key
+    # path, and +public_commands+ the ones callable without authentication —
+    # derived from the manifest, never handed in.
+    # +sizing+ is whatever the unit's commands declared with
+    # {Foobara::AWS::Lambda}, reduced to one value per key — empty when none
+    # of them said anything.
+    Unit = Data.define(:name, :group, :commands, :route, :public_commands, :sizing)
+
+    # The whole topology, read out of a Foobara manifest.
+    #
+    # Deliberately plain data. It is built where the manifest is (a running
+    # connector, or a file), travels as JSON, and is consumed where the
+    # infrastructure is — which may be a different process with none of the
+    # application's gems. Same split as the {Service} construct's, and the same
+    # reason: synthesis should depend on what was built, not on whether the app
+    # happens to load.
+    Plan = Data.define(:mount, :granularity, :units) do
+      # Every command callable without authentication, across all units. This is
+      # what an optional-auth authorizer needs, and it is derived rather than
+      # maintained — a command moves in or out of it by declaring
+      # `requires_authentication`, nowhere else.
+      def anonymous = units.flat_map(&:public_commands).sort
+
+      def unit(name) = units.find { |u| u.name == name.to_s }
+
+      def to_h
+        {
+          "mount" => mount,
+          "granularity" => granularity.to_s,
+          "units" => units.map do |u|
+            { "name" => u.name, "group" => u.group, "commands" => u.commands,
+              "route" => u.route, "public_commands" => u.public_commands,
+              "sizing" => u.sizing }
+          end
+        }
+      end
+
+      def to_json(*args) = to_h.to_json(*args)
+
+      # The inverse of {#to_h}, for a plan that has been through JSON.
+      def self.load(data)
+        data = data.transform_keys(&:to_s)
+
+        new(
+          mount: data.fetch("mount"),
+          granularity: data.fetch("granularity").to_sym,
+          units: data.fetch("units").map do |u|
+            u = u.transform_keys(&:to_s)
+            Unit.new(name: u.fetch("name"), group: u["group"], commands: u.fetch("commands"),
+                     route: u["route"], public_commands: u.fetch("public_commands", []),
+                     sizing: (u["sizing"] || {}).to_h { |k, v| [k.to_sym, v] })
+          end
+        )
+      end
+    end
+
+    class << self
+      # Build a {Plan} from a Foobara manifest.
+      #
+      #   manifest    the parsed manifest, as served at /manifest by a connector
+      #   mount       the connector's path prefix ("/run" for the Rack connector)
+      #   granularity :domain (default), :organization or :command
+      #
+      # A connector's manifest, not Foobara.manifest: `requires_authentication`
+      # only exists once commands are connected, and it is the field the public
+      # list comes from.
+      def plan(manifest, mount: "/run", granularity: :domain, exclude: DEFAULT_EXCLUDE)
+        commands = app_commands(manifest, exclude)
+        units =
+          case granularity
+          when :domain then group_units(commands, "domain", mount)
+          when :organization then group_units(commands, "organization", mount)
+          when :command then command_units(commands, mount)
+          else raise ArgumentError, "unknown granularity #{granularity.inspect}"
+          end
+
+        Plan.new(mount: mount, granularity: granularity, units: units.sort_by(&:name))
+      end
+
+      # Foobara's own commands — its auth domain and anything else it registers —
+      # are infrastructure, not the application, and deploying them is never what
+      # anyone means. Matched on the command's full name, which is where that
+      # namespace actually shows up.
+      #
+      # NOT matched on the organization: an app that declares none is filed under
+      # "global_organization", which is most apps, and excluding it would exclude
+      # everything.
+      DEFAULT_EXCLUDE = ["Foobara::"].freeze
+
+      private
+
+      def app_commands(manifest, exclude)
+        manifest.fetch("command").reject do |name, _command|
+          exclude.any? { |prefix| name.to_s.start_with?(prefix) }
+        end
+      end
+
+      def group_units(commands, key, mount)
+        commands.group_by { |_name, c| c[key].to_s }.map do |group, members|
+          names = members.map(&:first)
+          Unit.new(
+            name: slug(group),
+            group: group,
+            commands: names.sort,
+            # Derived from the commands' own paths, not from the group's name.
+            # Those are not the same thing: an app that declares no organization
+            # is filed under "global_organization", which appears nowhere in any
+            # URL, so grouping by organization and routing by its name would
+            # produce a prefix that matches nothing.
+            #
+            # Greedy: one route per unit rather than per command. That is only
+            # safe with a REQUEST authorizer, which sees the path and can decide
+            # per command; a JWT authorizer attaches per route, so a unit mixing
+            # public and authenticated commands would have to be split.
+            route: greedy_route(members, mount),
+            public_commands: public_of(members),
+            sizing: sizing_of(members)
+          )
+        end
+      end
+
+      def command_units(commands, mount)
+        commands.map do |name, command|
+          path = Array(command["scoped_full_path"])
+          Unit.new(
+            name: slug(name),
+            group: command["domain"].to_s,
+            # Closed over `depends_on`, transitively. A command that invokes
+            # another must be able to reach it, so a per-command artifact has to
+            # contain the commands it calls even though only one of them is
+            # routed to.
+            #
+            # This is the slicing problem that defeats per-command deployment in
+            # most frameworks: you cannot soundly infer it from Ruby's require
+            # graph. Foobara does not infer it — commands DECLARE it — which is
+            # what makes this granularity usable rather than theoretical.
+            commands: closure(name, commands),
+            # Exact, not greedy: one command per Lambda needs no wildcard, and an
+            # exact route is what lets API Gateway 404 an unknown command itself.
+            route: "#{mount}/#{path.join("/")}",
+            # Only the ROUTED command decides this. A dependency is invoked in
+            # process, never over HTTP, so whether it requires authentication
+            # says nothing about whether this route may be called anonymously.
+            public_commands: public_of([[name, command]]),
+            sizing: sizing_of([[name, command]])
+          )
+        end
+      end
+
+      # The longest path prefix every command in the unit shares, with the
+      # command segment dropped. For a domain that is the domain's own path; for
+      # an organization spanning several domains it is whatever they have in
+      # common, which may be nothing — and "nothing" is right: one function
+      # serving everything under the mount.
+      def greedy_route(members, mount)
+        prefixes = members.map { |_name, c| Array(c["scoped_full_path"])[0..-2] }
+        common = common_prefix(prefixes)
+
+        "#{mount}/#{(common + ["{proxy+}"]).join("/")}"
+      end
+
+      def common_prefix(paths)
+        first = paths.first || []
+        first.each_with_index.take_while { |segment, i| paths.all? { |p| p[i] == segment } }.map(&:first)
+      end
+
+      # Everything +name+ can reach through depends_on, including itself.
+      # Iterative rather than recursive because a cycle is legal (two commands
+      # that call each other) and would otherwise not terminate.
+      def closure(name, commands)
+        seen = []
+        queue = [name]
+
+        until queue.empty?
+          current = queue.shift
+          next if seen.include?(current)
+
+          seen << current
+          queue.concat(Array(commands[current]&.[]("depends_on")))
+        end
+
+        seen.sort
+      end
+
+      # `requires_authentication`, NOT `authenticator`. The latter says which
+      # authenticator applies, which is a different question, and is absent
+      # entirely when identity arrives some other way.
+      def public_of(members)
+        members.reject { |_name, c| c["requires_authentication"] }.map(&:first).sort
+      end
+
+      # The LARGEST value each command asked for. A unit runs all of its
+      # commands in one function, so it must be sized for the hungriest —
+      # undersizing is a runtime failure, oversizing is a rounding error on the
+      # bill. Declared per command (see {AWSLambda}) because that is where the
+      # knowledge is; reduced per unit because that is what a Lambda is.
+      def sizing_of(members)
+        declared = members.filter_map { |_name, c| c["aws_lambda"] }
+        return {} if declared.empty?
+
+        %w[memory_size timeout_seconds].each_with_object({}) do |key, out|
+          values = declared.filter_map { |d| d[key] || d[key.to_sym] }
+          out[key.to_sym] = values.max unless values.empty?
+        end
+      end
+
+      def symbolize(hash) = hash.to_h { |k, v| [k.to_sym, v] }
+
+      # A CloudFormation-friendly, filesystem-friendly identifier: "Posts" and
+      # "Acme::Posts" both become something usable as a directory name and a
+      # logical id fragment.
+      def slug(name) = name.split("::").map { |part| part.gsub(/([a-z])([A-Z])/, '\1-\2').downcase }.join("-")
+    end
+  end
+end

data/lib/foobara/aws/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Foobara
+  module AWS
+    VERSION = "0.1.0"
+  end
+end

data/lib/foobara/aws.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "aws/version"
+require_relative "aws/error"
+
+module Foobara
+  # Run Foobara commands on AWS Lambda, with the topology read out of the
+  # manifest rather than restated in infrastructure code.
+  #
+  # Three concerns, deliberately separable because they run in different places:
+  #
+  #   Foobara::AWS.plan(manifest)      WHAT to deploy. Plain data. Needs neither
+  #                                    aws-cdk-lib nor Foobara.
+  #   Foobara::AWS::CDK::Service       the AWS resources. Synth time; needs
+  #                                    aws-cdk-lib, and no application.
+  #   Foobara::AWS::Handler            serving a request. Runtime, inside the
+  #   Foobara::AWS::Authorizer         Lambda; needs neither of the above.
+  #
+  # A Lambda bundle requires only "foobara/aws/handler" (or ".../authorizer"),
+  # which loads no CDK and no planning code — cold start is on the critical path
+  # of every request, and a deployment tool has no business being there.
+  module AWS
+  end
+end
+
+require_relative "aws/lambda"
+require_relative "aws/plan"
+require_relative "aws/cdk/service"

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: foobara-aws
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Omar Qureshi
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Reads a Foobara manifest into a deployment plan — one unit per domain,
+  its route, and which of its commands are callable without authentication — and synthesises
+  the matching AWS CDK resources. The manifest is the single source of truth, so infrastructure
+  never restates what the application already declares.
+email:
+- omar@omarqureshi.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/foobara/aws.rb
+- lib/foobara/aws/authorizer.rb
+- lib/foobara/aws/cdk/service.rb
+- lib/foobara/aws/error.rb
+- lib/foobara/aws/handler.rb
+- lib/foobara/aws/lambda.rb
+- lib/foobara/aws/packager.rb
+- lib/foobara/aws/plan.rb
+- lib/foobara/aws/version.rb
+homepage: https://github.com/omarqureshi/foobara-aws
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/omarqureshi/foobara-aws
+  source_code_uri: https://github.com/omarqureshi/foobara-aws
+  changelog_uri: https://github.com/omarqureshi/foobara-aws/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Run Foobara commands on AWS Lambda, from the manifest.
+test_files: []