foobara-aws 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4de7e0012dfa7d11c92054cd25827b8b7f2e0864bf779027fe8c35a754c423e
-  data.tar.gz: b5009b5e2c62ba0db20ba010ad3580afec5c0524733fd8a8aa09f9a0afa8e475
+  metadata.gz: 16a858ce4e2944711259dacbf844fd258a1715018aaa7df98364e45739ec33de
+  data.tar.gz: 995b9e3af507e6cb53e3fd581945d27b9251f9559f0151c9151e5fa5bb277191
 SHA512:
-  metadata.gz: cb24ae7b484641d23c71c27ff59743ff1a2ac60eb0eea8c672da9c7177d05083cecfc535b47e722c09f995ca70fd9c8b32ea74ca1c5b6e2f2b0767ee9d58eedd
-  data.tar.gz: 87c12595977a88553fc092c6aa050dd22dcb25d433e5593d5b0594958b0e16cd42e47ae6553fcec8957089a8aeab68e620b251974a8e2da4bd38a65115793a29
+  metadata.gz: a328cae1d9959faa1efc89dc399f007005673493704ae20dbe9e02904b85949f7eb76debefeff09830f2a367315efac9bde77981c660690299aced88f5871464
+  data.tar.gz: a0cb8f25daa37b5ea097d5bf13e145c0a7df3a27b2d6faa801e426dafb3f8f00def81a55093d7c95818cd2caf32b2d7bbe7c6f3864248993b099f749d1218d52

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-04
+
+- `Foobara::AWS.plan_from_connector(connector)` — build a plan by inspecting a live connector instead of a
+  manifest. No HTTP, no running server, and no snapshot on disk to go stale.
+- It takes a CONNECTOR rather than a set of command classes, because `requires_authentication` is decided at
+  `connect` time and lives on the transformed command. The command classes alone cannot say which commands are
+  public, which is the one thing a deployment most needs to know.
+- It adapts each command into the shape `plan` already reads, so there is a single derivation and the two routes
+  cannot drift — asserted by a spec comparing the plans they produce.
+
+## [0.2.0] - 2026-08-04
+
+- `Foobara::AWS::Check` — checks a DEPLOYED API against the plan it was deployed from. It asserts the few things
+  that are true of every Foobara deployment and that an application's own tests structurally cannot see, because
+  they live at the edge: a public command is reachable without credentials, a gated one is refused without them
+  and with an invalid token, and a refusal is JSON rather than an HTML page with a 200 on it.
+- Gated commands are only ever called WITHOUT credentials, so they are refused before executing and nothing is
+  written. Public commands are executed with empty inputs; `skip:` is there for when that is not wanted. A 422 is
+  treated as success — the question is whether the request reached the command, not whether it liked the inputs.
+
 ## [0.1.0] - 2026-08-04
 
 - Initial release. Renamed from foobara-cdk before publishing: half of it is runtime code that loads inside a

data/README.md

@@ -15,6 +15,22 @@ service = Foobara::AWS::CDK::Service.new(self, "Api", plan: plan, code_root: "bu
 posts_table.grant_read_write_data(service.function("posts"))
 ```
 
+## Where a plan comes from
+
+```ruby
+Foobara::AWS.plan(manifest)                  # a manifest, however you obtained it
+Foobara::AWS.plan_from_connector(connector)  # a live connector, no server needed
+Foobara::AWS::Plan.load(JSON.parse(json))    # one that has been through JSON
+```
+
+`plan_from_connector` is usually what a build step wants: it reads the objects
+directly, so there is no server to start and no snapshot to go stale. It takes a
+**connector**, not a set of command classes — `requires_authentication` is
+decided at `connect` time and lives on the transformed command, so the classes
+alone cannot say which commands are public.
+
+All three produce the same `Plan`, and a spec asserts the first two agree.
+
 ## Two halves, on purpose
 
 ```ruby
@@ -151,6 +167,36 @@ Two things it handles that are easy to get wrong:
   and the load path rewritten. (Use `mounts:` so the build container can see
   them in the first place.)
 
+## Checking a deployment
+
+```ruby
+result = Foobara::AWS::Check.new(url: "https://api.example.com", plan: plan).run
+puts result.report
+exit 1 unless result.ok?
+```
+
+Driven by the plan, so it knows which commands are public without being told. It
+asserts the few things true of every Foobara deployment that an application's own
+tests structurally cannot see, because they live at the edge:
+
+- a public command is reachable **without** credentials
+- a gated command is refused without them, and with an invalid token
+- a refusal is JSON, not an HTML page with a 200 on it
+
+Each has a specific failure behind it. A public command that 401s usually means
+the authorizer declared an identity source, so API Gateway answered before the
+authorizer ran — silent, because the function was never invoked and logged
+nothing. A refusal arriving as `200 text/html` usually means a SPA history
+fallback is rewriting the API's errors, which turns every client-side error check
+into a lie. Both are real, both shipped, and both passed a full green test suite.
+
+Every request carries `{}`, so a command with required inputs answers 422 — which
+counts as success, since the question is whether the request reached the command.
+Gated commands are therefore only ever called **without** credentials: they are
+refused before executing and nothing is written. Public commands are executed
+with empty inputs, which is safe for the usual case of a read; `skip:` is there
+for when it is not.
+
 ## What it does not do
 
 - **Create tables, buckets or queues.** Those are the application's, not the

data/lib/foobara/aws/check.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "error"
+require_relative "plan"
+
+module Foobara
+  module AWS
+    # Checks a DEPLOYED API against the plan it was deployed from.
+    #
+    #   result = Foobara::AWS::Check.new(url: "https://api.example.com", plan: plan).run
+    #   puts result.report
+    #   exit 1 unless result.ok?
+    #
+    # Not a substitute for the application's own tests. It asserts the handful of
+    # things that are true of every Foobara deployment and that unit tests
+    # structurally cannot see, because they live at the edge:
+    #
+    #   * a public command is reachable WITHOUT credentials
+    #   * a command requiring authentication is refused without them
+    #   * a refusal is a refusal, not an HTML page with a 200 on it
+    #
+    # Each of those has a specific failure behind it. A public command that 401s
+    # usually means the authorizer declared an identity source, so API Gateway
+    # answered before the authorizer ran — silent, because the function was never
+    # invoked and logged nothing. A refusal arriving as `200 text/html` usually
+    # means a SPA history fallback is rewriting the API's errors, which turns
+    # every client error check into a lie.
+    #
+    # WHAT IT SENDS. Every request carries `{}` as its body, so a command that
+    # requires inputs answers 422. That is treated as SUCCESS: the point is
+    # whether the request reached the command at all, not whether it liked the
+    # inputs. It also means gated commands are only ever called WITHOUT
+    # credentials, so they are refused before executing and nothing is written.
+    #
+    # Public commands ARE executed, with empty inputs. That is safe for the usual
+    # case — a command reachable anonymously is nearly always a read — but it is
+    # the caller's judgement, and `skip:` exists for when it is not.
+    class Check
+      # Anything at all, as long as it is not a refusal and not HTML.
+      REFUSALS = [401, 403].freeze
+
+      Finding = Data.define(:command, :description, :expected, :actual, :ok) do
+        def to_s
+          "#{ok ? "ok  " : "FAIL"} #{command.ljust(28)} #{description} (expected #{expected}, got #{actual})"
+        end
+      end
+
+      Result = Data.define(:findings) do
+        def ok? = findings.all?(&:ok)
+        def failures = findings.reject(&:ok)
+
+        def report
+          summary = "#{findings.count(&:ok)}/#{findings.length} checks passed"
+          ([summary] + findings.map(&:to_s)).join("\n")
+        end
+      end
+
+      # +http+ is injectable so this can be tested without a network, and so a
+      # caller can supply its own client (a proxy, a custom CA, an SSM-fetched
+      # token). It receives (url, body_hash, headers) and returns
+      # [status, content_type, body_string].
+      def initialize(url:, plan:, skip: [], invalid_token: "not.a.token", http: nil)
+        @url = url.to_s.chomp("/")
+        @plan = plan
+        @skip = Array(skip).map(&:to_s)
+        @invalid_token = invalid_token
+        @http = http || method(:request)
+      end
+
+      def run
+        Result.new(findings: @plan.units.flat_map { |unit| check_unit(unit) })
+      end
+
+      private
+
+      def check_unit(unit)
+        unit.commands.reject { |c| @skip.include?(c) }.flat_map do |command|
+          if unit.public_commands.include?(command)
+            check_public(command)
+          else
+            check_gated(command)
+          end
+        end
+      end
+
+      # Reachable without credentials, and answering as an API rather than as a
+      # web page.
+      def check_public(command)
+        status, content_type, = call(command)
+
+        [
+          finding(command, "reachable anonymously", "not #{REFUSALS.join("/")}", status,
+                  !REFUSALS.include?(status)),
+          finding(command, "answers as an API", "json", content_type, json?(content_type))
+        ]
+      end
+
+      # Refused without credentials, and refused with a token that does not
+      # verify — the second catches an authorizer that accepts anything, which
+      # the first cannot distinguish from one that is never invoked.
+      def check_gated(command)
+        anonymous, anonymous_type, = call(command)
+        forged, forged_type, = call(command, token: @invalid_token)
+
+        [
+          finding(command, "refused anonymously", REFUSALS.join("/"), anonymous,
+                  REFUSALS.include?(anonymous)),
+          finding(command, "refusal is not a web page", "json", anonymous_type, json?(anonymous_type)),
+          finding(command, "refused with an invalid token", REFUSALS.join("/"), forged,
+                  REFUSALS.include?(forged)),
+          finding(command, "invalid-token refusal is not a web page", "json", forged_type,
+                  json?(forged_type))
+        ]
+      end
+
+      def finding(command, description, expected, actual, passed)
+        Finding.new(command: command, description: description, expected: expected,
+                    actual: actual.to_s, ok: passed)
+      end
+
+      # A 200 serving text/html is the CloudFront-rewrite failure, and it is worth
+      # naming rather than reporting as an unexpected status.
+      def json?(content_type) = content_type.to_s.include?("json")
+
+      def call(command, token: nil)
+        path = command.split("::").join("/")
+        headers = { "Content-Type" => "application/json" }
+        headers["Authorization"] = "Bearer #{token}" if token
+
+        @http.call("#{@url}#{@plan.mount}/#{path}", {}, headers)
+      rescue StandardError => e
+        # A connection failure is a check failure, not a crash: reporting it
+        # alongside the others is more useful than aborting the run, and it
+        # applies to an injected client as much as to the default one.
+        [0, "error: #{e.class}", e.message]
+      end
+
+      def request(url, body, headers)
+        uri = URI(url)
+        request = Net::HTTP::Post.new(uri)
+        headers.each { |k, v| request[k] = v }
+        request.body = JSON.dump(body)
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+          http.request(request)
+        end
+
+        [response.code.to_i, response["content-type"], response.body]
+      end
+    end
+  end
+end

data/lib/foobara/aws/plan.rb

@@ -85,6 +85,28 @@ module Foobara
         Plan.new(mount: mount, granularity: granularity, units: units.sort_by(&:name))
       end
 
+      # Build a {Plan} by inspecting a live connector instead of a manifest.
+      #
+      # The same information by a shorter route: no HTTP, no running server, and
+      # no snapshot on disk to go stale. It needs the application loaded, so it
+      # belongs in a build step rather than in a CDK app — which is the whole
+      # reason a {Plan} can also travel as JSON.
+      #
+      # A CONNECTOR, not a set of command classes. `requires_authentication` is
+      # decided at `connect` time and lives on the transformed command, so the
+      # command classes alone cannot say which commands are public — which is the
+      # one thing a deployment most needs to know.
+      #
+      # It adapts each command into the shape {plan} already reads, so there is
+      # one implementation and the two routes cannot drift.
+      def plan_from_connector(connector, **)
+        commands = connector.command_registry.all_transformed_command_classes.to_h do |transformed|
+          [transformed.command_class.full_command_name, describe_command(transformed)]
+        end
+
+        plan({ "command" => commands }, **)
+      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
@@ -97,6 +119,35 @@ module Foobara
 
       private
 
+      # Manifest-shaped, so {plan} cannot tell the difference. Only the fields
+      # planning reads — a manifest carries much more, and none of the rest
+      # matters here.
+      def describe_command(transformed)
+        command_class = transformed.command_class
+
+        {
+          "domain" => domain_name(command_class),
+          "organization" => organization_name(command_class),
+          "scoped_full_path" => Array(command_class.scoped_full_path),
+          "requires_authentication" => transformed.requires_authentication,
+          "depends_on" => Array(command_class.depends_on).map(&:to_s),
+          # The AWSLambda DSL, when the command extends it.
+          "aws_lambda" => (command_class.aws_lambda_manifest if command_class.respond_to?(:aws_lambda_manifest))
+        }.compact
+      end
+
+      def domain_name(command_class)
+        command_class.domain.scoped_full_name
+      rescue StandardError
+        ""
+      end
+
+      def organization_name(command_class)
+        command_class.organization.scoped_full_name
+      rescue StandardError
+        ""
+      end
+
       def app_commands(manifest, exclude)
         manifest.fetch("command").reject do |name, _command|
           exclude.any? { |prefix| name.to_s.start_with?(prefix) }

data/lib/foobara/aws/version.rb

@@ -2,6 +2,6 @@
 
 module Foobara
   module AWS
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/foobara/aws.rb

@@ -27,4 +27,5 @@ end
 
 require_relative "aws/lambda"
 require_relative "aws/plan"
+require_relative "aws/check"
 require_relative "aws/cdk/service"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foobara-aws
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Omar Qureshi
@@ -26,6 +26,7 @@ files:
 - lib/foobara/aws.rb
 - lib/foobara/aws/authorizer.rb
 - lib/foobara/aws/cdk/service.rb
+- lib/foobara/aws/check.rb
 - lib/foobara/aws/error.rb
 - lib/foobara/aws/handler.rb
 - lib/foobara/aws/lambda.rb