archipelago-rails 0.1.0

data/test/archipelago/action_test.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+require "active_model"
+begin
+  require "active_record"
+rescue LoadError
+  module ActiveRecord
+    class RecordInvalid < StandardError
+      attr_reader :record
+
+      def initialize(record)
+        @record = record
+        super("Record invalid")
+      end
+    end
+  end
+end
+
+class ActionTest < ArchipelagoTestCase
+  DummyContext = Struct.new(:user, :request, :params, :session)
+
+  class ForbiddenAction < Archipelago::Action
+    authorize { false }
+
+    def perform
+      props ok: true
+    end
+  end
+
+  class MissingAuthorizationAction < Archipelago::Action
+    def perform
+      props ok: true
+    end
+  end
+
+  class RedirectAction < Archipelago::Action
+    authorize { true }
+
+    def perform
+      redirect_to "https://evil.test/redirect"
+    end
+  end
+
+  class BroadcastAction < Archipelago::Action
+    authorize { true }
+
+    def perform
+      props members: [1, 2]
+    end
+  end
+
+  class ValidRedirectAction < Archipelago::Action
+    authorize { true }
+
+    def perform
+      redirect_to "/teams/1"
+    end
+  end
+
+  class RecordModel
+    include ActiveModel::Model
+
+    attr_accessor :email
+
+    validates :email, presence: true
+  end
+
+  class RecordInvalidAction < Archipelago::Action
+    authorize { true }
+
+    def perform
+      model = RecordModel.new(email: nil)
+      model.valid?
+      raise ActiveRecord::RecordInvalid.new(model)
+    end
+  end
+
+  def test_authorization_failure_returns_forbidden
+    payload = ForbiddenAction.new(ctx: DummyContext.new(nil, nil, nil, nil), raw_params: {}).call
+
+    assert_equal({ status: "forbidden" }, payload)
+  end
+
+  def test_missing_authorization_raises_when_required
+    Archipelago.configure { |config| config.authorize_by_default = true }
+
+    assert_raises(Archipelago::MissingAuthorization) do
+      MissingAuthorizationAction.new(ctx: DummyContext.new(nil, nil, nil, nil), raw_params: {}).call
+    end
+  end
+
+  def test_invalid_redirect_raises
+    assert_raises(Archipelago::InvalidRedirect) do
+      RedirectAction.new(ctx: DummyContext.new(nil, nil, nil, nil), raw_params: {}).call
+    end
+  end
+
+  def test_relative_redirect_is_allowed
+    payload = ValidRedirectAction.new(ctx: DummyContext.new(nil, nil, nil, nil), raw_params: {}).call
+
+    assert_equal "redirect", payload[:status]
+    assert_equal "/teams/1", payload[:location]
+  end
+
+  def test_broadcasts_when_stream_param_present
+    captured = nil
+    original_broadcast = Archipelago.method(:broadcast)
+    previous_verbose, $VERBOSE = $VERBOSE, nil
+
+    Archipelago.singleton_class.define_method(:broadcast) do |stream_name, props:, version:|
+      captured = [stream_name, props, version]
+    end
+
+    begin
+      BroadcastAction.new(
+        ctx: DummyContext.new(nil, nil, nil, nil),
+        raw_params: { __stream: "TeamMembers:1" }
+      ).call
+    ensure
+      Archipelago.singleton_class.define_method(:broadcast, original_broadcast)
+      $VERBOSE = previous_verbose
+    end
+
+    assert_equal "TeamMembers:1", captured[0]
+    assert_equal({ members: [1, 2] }, captured[1])
+    assert_kind_of Integer, captured[2]
+  end
+
+  def test_maps_record_invalid_errors
+    payload = RecordInvalidAction.new(ctx: DummyContext.new(nil, nil, nil, nil), raw_params: {}).call
+
+    assert_equal "error", payload[:status]
+    assert_equal ["Email can't be blank"], payload[:errors]["email"]
+  end
+end

data/test/archipelago/broadcasts_test.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+class BroadcastsTest < ArchipelagoTestCase
+  ServerStub = Struct.new(:broadcasts) do
+    def broadcast(stream_name, payload)
+      broadcasts << [stream_name, payload]
+    end
+  end
+
+  def test_broadcasts_ok_payload_with_version
+    server = ServerStub.new([])
+    original_server_method = ActionCable.method(:server)
+    previous_verbose, $VERBOSE = $VERBOSE, nil
+
+    ActionCable.singleton_class.define_method(:server) { server }
+
+    begin
+      payload = Archipelago::Broadcasts.broadcast("TeamMembers:1", props: { members: [1] }, version: 10)
+
+      assert_equal "ok", payload[:status]
+      assert_equal ["TeamMembers:1", payload], server.broadcasts.first
+    ensure
+      ActionCable.singleton_class.define_method(:server, original_server_method)
+      $VERBOSE = previous_verbose
+    end
+  end
+end

data/test/archipelago/channel_test.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+class ChannelTest < ArchipelagoTestCase
+  def test_stream_pattern_accepts_safe_names
+    assert_match Archipelago::IslandChannel::STREAM_PATTERN, "TeamMembers:1"
+    assert_match Archipelago::IslandChannel::STREAM_PATTERN, "teams:abc_123"
+  end
+
+  def test_stream_pattern_rejects_unsafe_names
+    refute_match Archipelago::IslandChannel::STREAM_PATTERN, "../etc/passwd"
+    refute_match Archipelago::IslandChannel::STREAM_PATTERN, "team members"
+  end
+end

data/test/archipelago/notifications_test.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+module Islands
+  module NotificationDemo
+    class Run < Archipelago::Action
+      authorize { true }
+
+      def perform
+        props message: "ok"
+      end
+    end
+
+    class InvalidRun < Archipelago::Action
+      param :email, :string, required: true
+      authorize { true }
+
+      def perform
+        props message: "nope"
+      end
+    end
+  end
+end
+
+class NotificationsTest < ArchipelagoTestCase
+  DummyContext = Struct.new(:user, :request, :params, :session)
+
+  def test_emits_resolve_notification
+    payloads = []
+
+    callback = lambda do |_name, _start, _finish, _id, payload|
+      payloads << payload
+    end
+
+    ActiveSupport::Notifications.subscribed(callback, "archipelago.action.resolve") do
+      Archipelago::Resolver.new.resolve(component: "NotificationDemo", operation: "run")
+    end
+
+    assert_equal "NotificationDemo", payloads.first[:component]
+    assert_equal "run", payloads.first[:operation]
+  end
+
+  def test_emits_error_notification_for_validation_failure
+    payloads = []
+
+    callback = lambda do |_name, _start, _finish, _id, payload|
+      payloads << payload
+    end
+
+    ActiveSupport::Notifications.subscribed(callback, "archipelago.action.error") do
+      Islands::NotificationDemo::InvalidRun.new(
+        ctx: DummyContext.new(nil, nil, nil, nil),
+        raw_params: {}
+      ).call
+    end
+
+    assert_equal "validation", payloads.first[:reason]
+  end
+end

data/test/archipelago/origin_validator_test.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+class OriginValidatorTest < ArchipelagoTestCase
+  RequestStub = Struct.new(:headers, :protocol, :host, :port)
+
+  def test_skips_when_strict_mode_disabled
+    config = Archipelago::Configuration.new
+    config.strict_origin_check = false
+
+    request = RequestStub.new({ "Origin" => "https://example.com" }, "https://", "example.com", 443)
+
+    assert Archipelago::Security::OriginValidator.new(request, configuration: config).validate!
+  end
+
+  def test_allows_matching_origin
+    config = Archipelago::Configuration.new
+    config.strict_origin_check = true
+
+    request = RequestStub.new({ "Origin" => "https://example.com" }, "https://", "example.com", 443)
+
+    assert Archipelago::Security::OriginValidator.new(request, configuration: config).validate!
+  end
+
+  def test_rejects_mismatched_origin
+    config = Archipelago::Configuration.new
+    config.strict_origin_check = true
+
+    request = RequestStub.new({ "Origin" => "https://attacker.test" }, "https://", "example.com", 443)
+
+    assert_raises(Archipelago::InvalidOrigin) do
+      Archipelago::Security::OriginValidator.new(request, configuration: config).validate!
+    end
+  end
+end

data/test/archipelago/params_dsl_test.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+class ParamsDSLTest < ArchipelagoTestCase
+  class ParamAction < Archipelago::Action
+    param :team_id, :integer, required: true
+    param :email, :string, required: true, strip: true, downcase: true
+    param :notify, :boolean, default: false
+
+    authorize { true }
+
+    def perform
+      props team_id: team_id, email: email, notify: notify
+    end
+  end
+
+  DummyContext = Struct.new(:user, :request, :params, :session)
+
+  def test_coerces_and_transforms_params
+    payload = ParamAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "team_id" => "10", "email" => "  USER@EXAMPLE.COM " }
+    ).call
+
+    assert_equal "ok", payload[:status]
+    assert_equal 10, payload[:props][:team_id]
+    assert_equal "user@example.com", payload[:props][:email]
+    assert_equal false, payload[:props][:notify]
+  end
+
+  def test_reports_required_errors
+    payload = ParamAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "team_id" => "10" }
+    ).call
+
+    assert_equal "error", payload[:status]
+    assert_equal ["is required"], payload[:errors]["email"]
+  end
+
+  def test_reports_coercion_errors
+    payload = ParamAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "team_id" => "x", "email" => "a@b.c" }
+    ).call
+
+    assert_equal "error", payload[:status]
+    assert_equal ["is invalid"], payload[:errors]["team_id"]
+  end
+end

data/test/archipelago/redirect_validator_test.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+class RedirectValidatorTest < ArchipelagoTestCase
+  def test_accepts_relative_path
+    validator = Archipelago::Security::RedirectValidator.new
+
+    assert_equal "/teams/1", validator.validate!("/teams/1")
+  end
+
+  def test_rejects_unlisted_absolute_host
+    validator = Archipelago::Security::RedirectValidator.new
+
+    assert_raises(Archipelago::InvalidRedirect) do
+      validator.validate!("https://example.com/path")
+    end
+  end
+
+  def test_allows_allowlisted_absolute_host
+    config = Archipelago::Configuration.new
+    config.allowed_redirect_hosts = ["app.example.com"]
+
+    validator = Archipelago::Security::RedirectValidator.new(configuration: config)
+
+    assert_equal "https://app.example.com/path", validator.validate!("https://app.example.com/path")
+  end
+end

data/test/archipelago/resolver_test.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+module Islands
+  module TeamMembers
+    class AddMember < Archipelago::Action
+      authorize { true }
+
+      def perform
+        props members: []
+      end
+    end
+  end
+
+  module Admin
+    module Users
+      class Create < Archipelago::Action
+        authorize { true }
+
+        def perform
+          props users: []
+        end
+      end
+    end
+  end
+end
+
+class ResolverTest < ArchipelagoTestCase
+  class CustomHandler < Archipelago::Action
+    authorize { true }
+
+    def perform
+      props override: true
+    end
+  end
+
+  def setup
+    super
+    Archipelago.configure { |config| config.root_namespace = "Islands" }
+  end
+
+  def test_resolves_by_convention
+    resolved = Archipelago::Resolver.new.resolve(component: "TeamMembers", operation: "add_member")
+
+    assert_equal Islands::TeamMembers::AddMember, resolved
+  end
+
+  def test_resolves_namespaced_component
+    resolved = Archipelago::Resolver.new.resolve(component: "Admin__Users", operation: "create")
+
+    assert_equal Islands::Admin::Users::Create, resolved
+  end
+
+  def test_registry_override_takes_precedence
+    Archipelago.map "TeamMembers#add_member" => CustomHandler
+
+    resolved = Archipelago::Resolver.new.resolve(component: "TeamMembers", operation: "add_member")
+
+    assert_equal CustomHandler, resolved
+  end
+
+  def test_rejects_invalid_component_name
+    assert_raises(Archipelago::ResolutionError) do
+      Archipelago::Resolver.new.resolve(component: "team_members", operation: "add_member")
+    end
+  end
+
+  def test_rejects_invalid_operation_name
+    assert_raises(Archipelago::ResolutionError) do
+      Archipelago::Resolver.new.resolve(component: "TeamMembers", operation: "AddMember")
+    end
+  end
+
+  def test_raises_for_missing_handler
+    assert_raises(Archipelago::ResolutionError) do
+      Archipelago::Resolver.new.resolve(component: "UnknownIsland", operation: "add_member")
+    end
+  end
+end

data/test/archipelago/response_test.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+class ResponseTest < ArchipelagoTestCase
+  def test_ok_payload
+    payload = Archipelago::Response.ok(props: { members: [] }, version: 7)
+
+    assert_equal "ok", payload[:status]
+    assert_equal({ members: [] }, payload[:props])
+    assert_equal 7, payload[:version]
+  end
+
+  def test_redirect_payload
+    payload = Archipelago::Response.redirect(location: "/teams/1")
+
+    assert_equal({ status: "redirect", location: "/teams/1" }, payload)
+  end
+
+  def test_error_payload
+    payload = Archipelago::Response.error(errors: { "email" => ["is invalid"] })
+
+    assert_equal "error", payload[:status]
+    assert_equal ["is invalid"], payload[:errors]["email"]
+  end
+
+  def test_forbidden_payload
+    assert_equal({ status: "forbidden" }, Archipelago::Response.forbidden)
+  end
+end

data/test/archipelago/view_helper_test.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+class ViewHelperTest < ArchipelagoTestCase
+  ViewContext = Class.new do
+    include ActionView::Helpers::TagHelper
+    include Archipelago::ViewHelper
+  end
+
+  def test_renders_island_div_with_data_attributes
+    html = ViewContext.new.archipelago_island(
+      "TeamMembers",
+      props: { members: [{ id: 1 }] },
+      params: { team_id: 9 },
+      instance: "team_9_members",
+      stream: true,
+      class: "island"
+    )
+
+    assert_includes html, "data-island=\"true\""
+    assert_includes html, "data-component=\"TeamMembers\""
+    assert_includes html, "data-stream=\"TeamMembers:team_9_members\""
+    assert_includes html, "class=\"island\""
+  end
+
+  def test_requires_instance_when_stream_true
+    assert_raises(ArgumentError) do
+      ViewContext.new.archipelago_island("TeamMembers", props: {}, params: {}, stream: true)
+    end
+  end
+end

data/test/controllers/islands_controller_test.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+require "rails/all"
+require "action_dispatch/testing/integration"
+
+unless defined?(ArchipelagoDummyApp)
+  class ArchipelagoDummyApp < Rails::Application
+    config.root = File.expand_path("../../", __dir__)
+    config.eager_load = false
+    config.secret_key_base = "test-key"
+    config.hosts << "www.example.com"
+
+    routes.append do
+      mount Archipelago::Engine => "/islands"
+    end
+  end
+
+  ArchipelagoDummyApp.initialize!
+end
+
+module Islands
+  module TeamMembers
+    class AddMember < Archipelago::Action
+      authorize { true }
+
+      def perform
+        props members: [{ id: 1, email: "person@example.com" }]
+      end
+    end
+
+    class Forbid < Archipelago::Action
+      authorize { false }
+
+      def perform
+        props blocked: false
+      end
+    end
+
+    class DebugMeta < Archipelago::Action
+      param :team_id, :integer, required: true
+      param :email, :string, strip: true, downcase: true, default: "fallback@example.com"
+      param :tags, :array, default: -> { [] }
+
+      authorize { true }
+
+      def perform
+        props ok: true
+      end
+    end
+  end
+end
+
+class IslandsControllerTest < ActionDispatch::IntegrationTest
+  def setup
+    super
+    Archipelago.reset_configuration!
+    Archipelago.registry.clear!
+  end
+
+  def test_success_response_contract
+    post "/islands/TeamMembers/add_member", params: { email: "person@example.com" }, as: :json
+
+    assert_response :ok
+    body = JSON.parse(response.body)
+    assert_equal "ok", body["status"]
+    assert_equal "person@example.com", body.fetch("props").fetch("members").first.fetch("email")
+  end
+
+  def test_forbidden_response_contract
+    post "/islands/TeamMembers/forbid", params: {}, as: :json
+
+    assert_response :forbidden
+    body = JSON.parse(response.body)
+    assert_equal "forbidden", body["status"]
+  end
+
+  def test_resolution_failure_is_404
+    post "/islands/Unknown/add_member", params: {}, as: :json
+
+    assert_response :not_found
+  end
+
+  def test_debug_payload_includes_param_metadata_for_registry_actions
+    Archipelago.map "TeamMembers#debug_meta" => Islands::TeamMembers::DebugMeta
+
+    get "/islands/__debug"
+
+    assert_response :ok
+    body = JSON.parse(response.body)
+
+    entry = body.fetch("registry_actions").find do |candidate|
+      candidate["component"] == "TeamMembers" && candidate["operation"] == "debug_meta"
+    end
+
+    refute_nil entry
+    assert_equal "Islands::TeamMembers::DebugMeta", entry["handler"]
+
+    team_id = entry.fetch("params").find { |param| param["name"] == "team_id" }
+    assert_equal "integer", team_id["type"]
+    assert_equal true, team_id["required"]
+    assert_equal({ "provided" => false }, team_id["default"])
+
+    email = entry.fetch("params").find { |param| param["name"] == "email" }
+    assert_equal "string", email["type"]
+    assert_equal({ "provided" => true, "value" => "fallback@example.com" }, email["default"])
+    assert_equal(
+      { "strip" => true, "downcase" => true, "upcase" => false },
+      email["transforms"]
+    )
+
+    tags = entry.fetch("params").find { |param| param["name"] == "tags" }
+    assert_equal({ "provided" => true, "kind" => "callable" }, tags["default"])
+  end
+end

data/test/generators/install_generator_test.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+require "rails/generators/test_case"
+require "generators/archipelago/install_generator"
+
+class InstallGeneratorTest < Rails::Generators::TestCase
+  tests Archipelago::Generators::InstallGenerator
+  destination File.expand_path("../../tmp", __dir__)
+
+  setup :prepare_destination
+
+  def setup
+    super
+    FileUtils.mkdir_p(File.join(destination_root, "config"))
+    File.write(File.join(destination_root, "config/routes.rb"), "Rails.application.routes.draw do\nend\n")
+  end
+
+  def test_generates_initializer_and_islands_dir
+    run_generator
+
+    assert_file "app/islands"
+    assert_file "config/initializers/archipelago.rb"
+    assert_file "config/routes.rb", /mount Archipelago::Engine => "\/islands"/
+  end
+end

data/test/generators/island_generator_test.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+require "rails/generators/test_case"
+require "generators/archipelago/island_generator"
+
+class IslandGeneratorTest < Rails::Generators::TestCase
+  tests Archipelago::Generators::IslandGenerator
+  destination File.expand_path("../../tmp", __dir__)
+
+  setup :prepare_destination
+
+  def test_generates_action_and_component_files
+    run_generator %w[TeamMembers add_member remove_member]
+
+    assert_file "app/islands/team_members/add_member.rb", /class AddMember < Archipelago::Action/
+    assert_file "app/islands/team_members/remove_member.rb", /class RemoveMember < Archipelago::Action/
+    assert_file "app/javascript/islands/TeamMembers.tsx", /useIslandProps/
+  end
+end