archipelago-rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a271d60fbd7122dfe75a111e3182fc34662dd3afe9b6d4183e834d08be828e2b
-  data.tar.gz: '0357780015635cb62d1255e257064d6b5a3674a41f18465f5ce6f0e59ec54759'
+  metadata.gz: 958584d368aaf5860d872cd58c01639c7efda2a412b96b8d112bd941fc455d31
+  data.tar.gz: e1a648f35bdd36fee3c0c798989a613663a1bfd7c336757bd73005c60417f10a
 SHA512:
-  metadata.gz: a40da1f08277ed421fa36b9d29e03223036259625689eb17489455158d0f056cb4600e633f19994bcb2ba6bb7e06773a1db40b5033740f99027baaecd5aa0e66
-  data.tar.gz: b0827ebf94625a2a5c7f21cdf1c870794609a01d20e8a8dc028ef108cf1f1decde1f5d6284bba7930a267b85e9770430e19e63e45059312c6fd8b911e305add1
+  metadata.gz: acd4fc0e23a2897fd483a0a18340a93c9a24bf705da3de9441b3f895103a2bcace726192be557ba4dd6ccc7fbb75b8df38b9575b59367b175a82ddae440617bc
+  data.tar.gz: 846fdc9686466a6ad5ca9a98b74ae5ca3ba9286878f5cedbc9b0410a739988558be826d10b2d49282835e6a675e010757263d4051fb35970924937db47689e5a

data/README.md

@@ -45,6 +45,14 @@ After `rails g archipelago:install`, you can scaffold frontend bootstrap wiring:
 rails g archipelago:install:react
 ```
 
+The generator writes `.npmrc` with:
+
+```text
+@archipelago-js:registry=https://registry.npmjs.org
+```
+
+This keeps installs reliable across npm, Yarn classic, pnpm, and bun.
+
 By default this runs an interactive wizard with auto-detected defaults
 (bundler, TypeScript, package manager, and local monorepo path).
 

data/app/controllers/archipelago/islands_controller.rb

@@ -35,10 +35,26 @@ module Archipelago
         request: request,
         params: params,
         session: session,
-        user: current_archipelago_user
+        user: current_archipelago_user,
+        stream: extract_stream_name
       )
     end
 
+    def extract_stream_name
+      from_header = request.headers["X-Archipelago-Stream"].presence
+      return from_header if from_header
+
+      # Backwards compat: fall back to __stream in params with deprecation warning.
+      from_params = island_params[:__stream].presence
+      if from_params
+        ActiveSupport::Deprecation.warn(
+          "Passing __stream in the request payload is deprecated. " \
+          "Use the X-Archipelago-Stream header instead."
+        )
+      end
+      from_params
+    end
+
     def current_archipelago_user
       resolver_proc = Archipelago.configuration.current_user_resolver
       return instance_exec(&resolver_proc) if resolver_proc
@@ -131,7 +147,7 @@ module Archipelago
       return [] unless handler_class.respond_to?(:param_definitions)
 
       handler_class.param_definitions.values.map do |definition|
-        {
+        entry = {
           name: definition.name.to_s,
           type: definition.type.to_s,
           required: definition.required,
@@ -142,6 +158,14 @@ module Archipelago
             upcase: definition.upcase
           }
         }
+        entry[:in] = definition.in.to_a if definition.in
+        entry[:format] = definition.format.inspect if definition.format
+        entry[:min] = definition.min if definition.min
+        entry[:max] = definition.max if definition.max
+        entry[:empty_as_nil] = true if definition.empty_as_nil
+        entry[:of] = definition.of.to_s if definition.of
+        entry[:validate] = true if definition.validate
+        entry
       end
     end
 

data/lib/archipelago/action.rb

@@ -110,8 +110,12 @@ module Archipelago
       defined?(ActiveRecord::RecordInvalid) && error.is_a?(ActiveRecord::RecordInvalid)
     end
 
+    def current_user
+      ctx.user
+    end
+
     def maybe_broadcast(payload)
-      stream_name = raw_params[:__stream]
+      stream_name = ctx.stream || raw_params[:__stream]
       return if stream_name.blank?
       return unless payload[:status] == "ok"
 

data/lib/archipelago/cancan_adapter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Archipelago
+  module CanCanAdapter
+    def authorize!(action, record)
+      ability = current_ability
+      unless ability.can?(action, record)
+        raise Archipelago::Forbidden, "not allowed to #{action} this #{record.class}"
+      end
+
+      record
+    end
+
+    def current_ability
+      ability_builder = Archipelago.configuration.current_ability
+      if ability_builder
+        ability_builder.call(current_user)
+      elsif defined?(::Ability)
+        ::Ability.new(current_user)
+      else
+        raise Archipelago::Error, "No ability class configured. Set Archipelago.configuration.current_ability or define an Ability class."
+      end
+    end
+  end
+end

data/lib/archipelago/channel.rb

@@ -9,13 +9,26 @@ else
     def stream_from(*); end
     def reject; end
     def params = {}
+    def connection; end
   end
 end
 
 channel_class = Class.new(base_channel) do
   def subscribed
     stream_name = verified_stream_name
-    reject unless stream_name
+    unless stream_name
+      reject
+      return
+    end
+
+    unless Archipelago.authorize_stream?(
+      connection: connection,
+      stream_name: stream_name,
+      params: params.except(:channel, :stream_name)
+    )
+      reject
+      return
+    end
 
     stream_from(stream_name)
   end

data/lib/archipelago/configuration.rb

@@ -8,7 +8,10 @@ module Archipelago
                   :authorize_by_default,
                   :strict_origin_check,
                   :allowed_redirect_hosts,
-                  :version_source
+                  :version_source,
+                  :stream_authorizer,
+                  :require_stream_authorization,
+                  :current_ability
 
     def initialize
       @root_namespace = "Islands"
@@ -18,6 +21,9 @@ module Archipelago
       @strict_origin_check = false
       @allowed_redirect_hosts = []
       @version_source = -> { (Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)).to_i }
+      @stream_authorizer = nil
+      @require_stream_authorization = false
+      @current_ability = nil
     end
   end
 end

data/lib/archipelago/context.rb

@@ -3,12 +3,14 @@
 module Archipelago
   class Context
     attr_reader :request, :params, :session, :user
+    attr_accessor :stream
 
-    def initialize(request:, params:, session:, user: nil)
+    def initialize(request:, params:, session:, user: nil, stream: nil)
       @request = request
       @params = params
       @session = session
       @user = user
+      @stream = stream
     end
   end
 end

data/lib/archipelago/params_dsl.rb

@@ -15,6 +15,13 @@ module Archipelago
       :strip,
       :downcase,
       :upcase,
+      :in,
+      :format,
+      :min,
+      :max,
+      :empty_as_nil,
+      :of,
+      :validate,
       keyword_init: true
     )
 
@@ -23,7 +30,8 @@ module Archipelago
         @param_definitions ||= {}
       end
 
-      def param(name, type, required: false, default: MISSING, strip: false, downcase: false, upcase: false)
+      def param(name, type, required: false, default: MISSING, strip: false, downcase: false, upcase: false,
+                in: nil, format: nil, min: nil, max: nil, empty_as_nil: false, of: nil, validate: nil)
         symbol_name = name.to_sym
 
         param_definitions[symbol_name] = ParamDefinition.new(
@@ -33,7 +41,14 @@ module Archipelago
           default: default,
           strip: strip,
           downcase: downcase,
-          upcase: upcase
+          upcase: upcase,
+          in: binding.local_variable_get(:in),
+          format: format,
+          min: min,
+          max: max,
+          empty_as_nil: empty_as_nil,
+          of: of,
+          validate: validate
         )
 
         define_method(symbol_name) do
@@ -53,6 +68,10 @@ module Archipelago
       self.class.param_definitions.each_value do |definition|
         raw_value = fetch_param(raw_params, definition.name)
 
+        if definition.empty_as_nil && empty_string?(raw_value)
+          raw_value = nil
+        end
+
         if blank_value?(raw_value)
           if definition.default != MISSING
             coerced[definition.name] = definition.default.respond_to?(:call) ? definition.default.call : definition.default
@@ -65,7 +84,12 @@ module Archipelago
 
         begin
           coerced_value = coerce_value(raw_value, definition)
-          coerced[definition.name] = coerced_value
+          validation_error = run_validations(coerced_value, definition)
+          if validation_error
+            errors[definition.name.to_s] << validation_error
+          else
+            coerced[definition.name] = coerced_value
+          end
         rescue ArgumentError, TypeError, JSON::ParserError
           errors[definition.name.to_s] << "is invalid"
         end
@@ -84,9 +108,17 @@ module Archipelago
       value.nil? || (value.respond_to?(:empty?) && value.empty?)
     end
 
+    def empty_string?(value)
+      value.is_a?(String) && value.strip.empty?
+    end
+
     def coerce_value(raw_value, definition)
       value = cast(raw_value, definition.type)
 
+      if definition.type == :array && definition.of
+        value = value.map { |element| cast(element, definition.of) }
+      end
+
       return value unless value.is_a?(String)
 
       value = value.strip if definition.strip
@@ -95,6 +127,33 @@ module Archipelago
       value
     end
 
+    def run_validations(value, definition)
+      if definition.in && !definition.in.include?(value)
+        return "is not included in the list"
+      end
+
+      if definition.format && value.is_a?(String) && !value.match?(definition.format)
+        return "is invalid"
+      end
+
+      if definition.min
+        comparable = value.respond_to?(:length) ? value.length : value
+        return "is too small" if comparable < definition.min
+      end
+
+      if definition.max
+        comparable = value.respond_to?(:length) ? value.length : value
+        return "is too large" if comparable > definition.max
+      end
+
+      if definition.validate
+        custom_error = definition.validate.call(value)
+        return custom_error if custom_error.is_a?(String)
+      end
+
+      nil
+    end
+
     def cast(value, type)
       case type
       when :string

data/lib/archipelago/pundit_adapter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Archipelago
+  module PunditAdapter
+    def authorize(record, query = nil)
+      query ||= infer_pundit_query
+      policy = policy(record)
+
+      unless policy.public_send(query)
+        raise Archipelago::Forbidden, "not allowed to #{query} this #{record.class}"
+      end
+
+      record
+    end
+
+    def policy(record)
+      klass = "#{record.class}Policy".safe_constantize
+      raise Archipelago::Forbidden, "no policy found for #{record.class}" unless klass
+
+      klass.new(current_user, record)
+    end
+
+    private
+
+    def infer_pundit_query
+      action_name = self.class.name.to_s.demodulize.sub(/Action\z/, "").underscore
+      "#{action_name}?"
+    end
+  end
+end

data/lib/archipelago.rb

@@ -45,6 +45,15 @@ module Archipelago
       Broadcasts.broadcast(stream_name, props: props, version: version)
     end
 
+    def authorize_stream?(connection:, stream_name:, params: {})
+      authorizer = configuration.stream_authorizer
+      return true unless configuration.require_stream_authorization || authorizer
+
+      return false if configuration.require_stream_authorization && authorizer.nil?
+
+      authorizer.call(connection: connection, stream_name: stream_name, params: params)
+    end
+
     def instrument(event, payload = {}, &block)
       ActiveSupport::Notifications.instrument(event, payload, &block)
     end
@@ -59,6 +68,8 @@ require "archipelago/context"
 require "archipelago/security/origin_validator"
 require "archipelago/security/redirect_validator"
 require "archipelago/action"
+require "archipelago/pundit_adapter"
+require "archipelago/cancan_adapter"
 require "archipelago/resolver"
 require "archipelago/broadcasts"
 require "archipelago/channel"

data/lib/generators/archipelago/install/install_generator.rb

@@ -33,6 +33,8 @@ module Archipelago
       end
 
       def print_next_steps
+        say "If package install fails on Yarn mirror, add to .npmrc:"
+        say "  @archipelago-js:registry=https://registry.npmjs.org"
         say "Install JS packages: yarn add @archipelago-js/client @archipelago-js/react"
         say "Optional React bootstrap wizard: rails g archipelago:install:react"
         say "Non-interactive mode: rails g archipelago:install:react --interactive=false"

data/lib/generators/archipelago/install/react/react_generator.rb

@@ -48,6 +48,11 @@ module Archipelago
                      default: true,
                      desc: "For esbuild, auto-generate component registry from app/javascript/islands"
 
+        class_option :lazy_registry,
+                     type: :boolean,
+                     default: false,
+                     desc: "Generate lazy (dynamic import) registry instead of eager imports"
+
         desc "Sets up React + Archipelago frontend bootstrapping for a Rails app."
 
         def detect_stack
@@ -69,6 +74,7 @@ module Archipelago
           @package_manager = options[:package_manager] == "auto" ? @detected_package_manager : options[:package_manager]
           @local_monorepo_path = options[:local_monorepo_path] || @detected_local_monorepo_path
           @auto_registry = options[:auto_registry]
+          @lazy_registry = options[:lazy_registry]
         end
 
         def interactive_preferences
@@ -122,6 +128,10 @@ module Archipelago
           template "entry.js.tt", @entry_relative_path
         end
 
+        def configure_scope_registry
+          ensure_scope_registry_in_npmrc
+        end
+
         def setup_esbuild_auto_registry
           return unless @bundler == :esbuild
           return unless @auto_registry
@@ -131,6 +141,13 @@ module Archipelago
           wire_esbuild_package_scripts
         end
 
+        def setup_lazy_registry
+          return unless @lazy_registry
+          return if @bundler == :esbuild && @auto_registry
+
+          create_file registry_relative_path, lazy_registry_source
+        end
+
         def wire_esbuild_entry
           return unless @bundler == :esbuild
 
@@ -166,6 +183,7 @@ module Archipelago
             say "Install packages:"
             say "  #{resolved_package_manager} add #{packages_for_install.join(' ')}"
           end
+          say "Scoped registry configured in .npmrc for @archipelago-js -> npmjs.org."
           say ""
           if @bundler == :esbuild && @auto_registry
             say "Islands in app/javascript/islands/**/* are auto-registered before esbuild runs."
@@ -268,6 +286,32 @@ module Archipelago
           end
         end
 
+        def lazy_registry_source
+          if @use_typescript
+            <<~TS
+              import { defineIslandLoader, type IslandRegistry } from "@archipelago-js/react"
+
+              // Lazy registry: islands are loaded on demand via dynamic import.
+              // Add entries like:
+              //   MyIsland: defineIslandLoader(() => import("../islands/MyIsland"))
+              const registry: IslandRegistry = {}
+
+              export default registry
+            TS
+          else
+            <<~JS
+              import { defineIslandLoader } from "@archipelago-js/react"
+
+              // Lazy registry: islands are loaded on demand via dynamic import.
+              // Add entries like:
+              //   MyIsland: defineIslandLoader(() => import("../islands/MyIsland"))
+              const registry = {}
+
+              export default registry
+            JS
+          end
+        end
+
         def wire_esbuild_package_scripts
           return unless path_exists?("package.json")
 
@@ -374,6 +418,22 @@ module Archipelago
           root = Pathname.new(@local_monorepo_path).expand_path
           "@archipelago-js/react@file:#{root.join('packages/react')}"
         end
+
+        def ensure_scope_registry_in_npmrc
+          scope_key = "@archipelago-js:registry"
+          registry_line = "#{scope_key}=https://registry.npmjs.org"
+          npmrc_path = path_for(".npmrc")
+
+          unless File.exist?(npmrc_path)
+            create_file ".npmrc", "#{registry_line}\n"
+            return
+          end
+
+          content = File.read(npmrc_path)
+          return if content.include?(scope_key)
+
+          append_to_file ".npmrc", "\n#{registry_line}\n"
+        end
       end
     end
   end

data/lib/generators/archipelago/install/react/templates/generate_registry.mjs.tt

@@ -10,6 +10,7 @@ const outputFile = path.resolve(
   archipelagoDir,
   "registry.generated.<%= @use_typescript ? "ts" : "js" %>"
 )
+const lazy = <%= @lazy_registry ? "true" : "false" %>
 
 function walk(dir) {
   if (!fs.existsSync(dir)) {
@@ -62,16 +63,33 @@ const islandFiles = walk(islandsRoot).sort()
 const imports = []
 const registryRows = []
 
-islandFiles.forEach((absolutePath, index) => {
-  const relativeFromIslands = path.relative(islandsRoot, absolutePath)
-  const relativeWithoutExt = relativeFromIslands.replace(/\.[^.]+$/, "")
-  const importPath = `../islands/${relativeWithoutExt.split(path.sep).join("/")}`
-  const componentName = componentNameFromRelative(relativeWithoutExt)
-  const importName = `Island${index + 1}`
+if (lazy) {
+<% if @use_typescript %>
+  imports.push("import { defineIslandLoader, type IslandRegistry } from \"@archipelago-js/react\"")
+<% else %>
+  imports.push("import { defineIslandLoader } from \"@archipelago-js/react\"")
+<% end %>
 
-  imports.push(`import ${importName} from "${importPath}"`)
-  registryRows.push(`  "${componentName}": ${importName}`)
-})
+  islandFiles.forEach((absolutePath) => {
+    const relativeFromIslands = path.relative(islandsRoot, absolutePath)
+    const relativeWithoutExt = relativeFromIslands.replace(/\.[^.]+$/, "")
+    const importPath = `../islands/${relativeWithoutExt.split(path.sep).join("/")}`
+    const componentName = componentNameFromRelative(relativeWithoutExt)
+
+    registryRows.push(`  "${componentName}": defineIslandLoader(() => import("${importPath}"))`)
+  })
+} else {
+  islandFiles.forEach((absolutePath, index) => {
+    const relativeFromIslands = path.relative(islandsRoot, absolutePath)
+    const relativeWithoutExt = relativeFromIslands.replace(/\.[^.]+$/, "")
+    const importPath = `../islands/${relativeWithoutExt.split(path.sep).join("/")}`
+    const componentName = componentNameFromRelative(relativeWithoutExt)
+    const importName = `Island${index + 1}`
+
+    imports.push(`import ${importName} from "${importPath}"`)
+    registryRows.push(`  "${componentName}": ${importName}`)
+  })
+}
 
 const source = [
   "// This file is auto-generated by app/javascript/archipelago/generate_registry.mjs.",
@@ -80,8 +98,7 @@ const source = [
   ...imports,
   imports.length > 0 ? "" : "",
 <% if @use_typescript %>
-  "import type { IslandRegistry } from \"@archipelago-js/react\"",
-  "",
+  ...(lazy ? [] : ["import type { IslandRegistry } from \"@archipelago-js/react\"", ""]),
   "const registry: IslandRegistry = {",
 <% else %>
   "const registry = {",

data/test/archipelago/action_test.rb

@@ -18,7 +18,7 @@ rescue LoadError
 end
 
 class ActionTest < ArchipelagoTestCase
-  DummyContext = Struct.new(:user, :request, :params, :session)
+  DummyContext = Struct.new(:user, :request, :params, :session, :stream)
 
   class ForbiddenAction < Archipelago::Action
     authorize { false }
@@ -133,4 +133,185 @@ class ActionTest < ArchipelagoTestCase
     assert_equal "error", payload[:status]
     assert_equal ["Email can't be blank"], payload[:errors]["email"]
   end
+
+  def test_current_user_delegates_to_ctx_user
+    user = Object.new
+    action = BroadcastAction.new(
+      ctx: DummyContext.new(user, nil, nil, nil),
+      raw_params: {}
+    )
+
+    assert_same user, action.send(:current_user)
+  end
+
+  def test_broadcasts_via_ctx_stream
+    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, "ctx-stream:42"),
+        raw_params: {}
+      ).call
+    ensure
+      Archipelago.singleton_class.define_method(:broadcast, original_broadcast)
+      $VERBOSE = previous_verbose
+    end
+
+    assert_equal "ctx-stream:42", captured[0]
+    assert_equal({ members: [1, 2] }, captured[1])
+  end
+
+  def test_ctx_stream_takes_precedence_over_raw_params_stream
+    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
+    end
+
+    begin
+      BroadcastAction.new(
+        ctx: DummyContext.new(nil, nil, nil, nil, "ctx-stream:1"),
+        raw_params: { __stream: "param-stream:1" }
+      ).call
+    ensure
+      Archipelago.singleton_class.define_method(:broadcast, original_broadcast)
+      $VERBOSE = previous_verbose
+    end
+
+    assert_equal "ctx-stream:1", captured
+  end
+end
+
+class PunditAdapterTest < ArchipelagoTestCase
+  DummyContext = Struct.new(:user, :request, :params, :session, :stream)
+
+  DummyUser = Struct.new(:id, :admin)
+
+  class TeamPolicy
+    attr_reader :user, :record
+
+    def initialize(user, record)
+      @user = user
+      @record = record
+    end
+
+    def update?
+      user.admin
+    end
+  end
+
+  Team = Struct.new(:name)
+
+  class UpdateAction < Archipelago::Action
+    include Archipelago::PunditAdapter
+
+    authorize { true }
+
+    def perform
+      authorize(Team.new("test"))
+      props ok: true
+    end
+  end
+
+  def test_pundit_authorize_allows_when_policy_returns_true
+    user = DummyUser.new(1, true)
+    # TeamPolicy is looked up as "PunditAdapterTest::Team" + "Policy",
+    # so we need the class in scope. We define it above.
+    stub_const_for_test("PunditAdapterTest::TeamPolicy", TeamPolicy) do
+      payload = UpdateAction.new(
+        ctx: DummyContext.new(user, nil, nil, nil),
+        raw_params: {}
+      ).call
+
+      assert_equal "ok", payload[:status]
+    end
+  end
+
+  def test_pundit_authorize_raises_forbidden_when_policy_returns_false
+    user = DummyUser.new(1, false)
+    stub_const_for_test("PunditAdapterTest::TeamPolicy", TeamPolicy) do
+      payload = UpdateAction.new(
+        ctx: DummyContext.new(user, nil, nil, nil),
+        raw_params: {}
+      ).call
+
+      assert_equal "forbidden", payload[:status]
+    end
+  end
+
+  private
+
+  def stub_const_for_test(_name, _klass, &block)
+    yield
+  end
+end
+
+class CanCanAdapterTest < ArchipelagoTestCase
+  DummyContext = Struct.new(:user, :request, :params, :session, :stream)
+
+  class DummyAbility
+    def initialize(user)
+      @user = user
+    end
+
+    def can?(action, record)
+      action == :read
+    end
+  end
+
+  class ReadAction < Archipelago::Action
+    include Archipelago::CanCanAdapter
+
+    authorize { true }
+
+    def perform
+      authorize!(:read, Object.new)
+      props ok: true
+    end
+  end
+
+  class WriteAction < Archipelago::Action
+    include Archipelago::CanCanAdapter
+
+    authorize { true }
+
+    def perform
+      authorize!(:write, Object.new)
+      props ok: true
+    end
+  end
+
+  def test_cancan_authorize_allows_permitted_action
+    Archipelago.configure do |config|
+      config.current_ability = ->(user) { DummyAbility.new(user) }
+    end
+
+    payload = ReadAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: {}
+    ).call
+
+    assert_equal "ok", payload[:status]
+  end
+
+  def test_cancan_authorize_raises_forbidden_on_denied_action
+    Archipelago.configure do |config|
+      config.current_ability = ->(user) { DummyAbility.new(user) }
+    end
+
+    payload = WriteAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: {}
+    ).call
+
+    assert_equal "forbidden", payload[:status]
+  end
 end

data/test/archipelago/channel_test.rb

@@ -12,4 +12,39 @@ class ChannelTest < ArchipelagoTestCase
     refute_match Archipelago::IslandChannel::STREAM_PATTERN, "../etc/passwd"
     refute_match Archipelago::IslandChannel::STREAM_PATTERN, "team members"
   end
+
+  def test_authorize_stream_returns_true_when_no_authorizer_and_not_required
+    Archipelago.configure do |config|
+      config.stream_authorizer = nil
+      config.require_stream_authorization = false
+    end
+
+    assert Archipelago.authorize_stream?(connection: nil, stream_name: "test:1")
+  end
+
+  def test_authorize_stream_rejects_all_when_required_but_no_authorizer
+    Archipelago.configure do |config|
+      config.stream_authorizer = nil
+      config.require_stream_authorization = true
+    end
+
+    refute Archipelago.authorize_stream?(connection: nil, stream_name: "test:1")
+  end
+
+  def test_authorize_stream_calls_authorizer_lambda
+    called_with = nil
+    Archipelago.configure do |config|
+      config.stream_authorizer = ->(connection:, stream_name:, params:) {
+        called_with = { connection: connection, stream_name: stream_name, params: params }
+        stream_name.start_with?("allowed:")
+      }
+    end
+
+    assert Archipelago.authorize_stream?(connection: :conn, stream_name: "allowed:1", params: { a: 1 })
+    assert_equal :conn, called_with[:connection]
+    assert_equal "allowed:1", called_with[:stream_name]
+    assert_equal({ a: 1 }, called_with[:params])
+
+    refute Archipelago.authorize_stream?(connection: :conn, stream_name: "denied:1")
+  end
 end

data/test/archipelago/notifications_test.rb

@@ -24,7 +24,7 @@ module Islands
 end
 
 class NotificationsTest < ArchipelagoTestCase
-  DummyContext = Struct.new(:user, :request, :params, :session)
+  DummyContext = Struct.new(:user, :request, :params, :session, :stream)
 
   def test_emits_resolve_notification
     payloads = []

data/test/archipelago/params_dsl_test.rb

@@ -15,7 +15,70 @@ class ParamsDSLTest < ArchipelagoTestCase
     end
   end
 
-  DummyContext = Struct.new(:user, :request, :params, :session)
+  class InValidatorAction < Archipelago::Action
+    param :role, :string, required: true, in: %w[admin member viewer]
+
+    authorize { true }
+
+    def perform
+      props role: role
+    end
+  end
+
+  class FormatValidatorAction < Archipelago::Action
+    param :slug, :string, required: true, format: /\A[a-z0-9-]+\z/
+
+    authorize { true }
+
+    def perform
+      props slug: slug
+    end
+  end
+
+  class MinMaxValidatorAction < Archipelago::Action
+    param :age, :integer, required: true, min: 0, max: 150
+    param :name, :string, required: true, min: 2, max: 50
+
+    authorize { true }
+
+    def perform
+      props age: age, name: name
+    end
+  end
+
+  class EmptyAsNilAction < Archipelago::Action
+    param :nickname, :string, empty_as_nil: true
+
+    authorize { true }
+
+    def perform
+      props nickname: nickname
+    end
+  end
+
+  class TypedArrayAction < Archipelago::Action
+    param :tag_ids, :array, required: true, of: :integer
+
+    authorize { true }
+
+    def perform
+      props tag_ids: tag_ids
+    end
+  end
+
+  class CustomValidateAction < Archipelago::Action
+    param :code, :string, required: true, validate: ->(value) {
+      value.length == 6 ? nil : "must be exactly 6 characters"
+    }
+
+    authorize { true }
+
+    def perform
+      props code: code
+    end
+  end
+
+  DummyContext = Struct.new(:user, :request, :params, :session, :stream)
 
   def test_coerces_and_transforms_params
     payload = ParamAction.new(
@@ -48,4 +111,144 @@ class ParamsDSLTest < ArchipelagoTestCase
     assert_equal "error", payload[:status]
     assert_equal ["is invalid"], payload[:errors]["team_id"]
   end
+
+  def test_in_validator_accepts_valid_value
+    payload = InValidatorAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "role" => "admin" }
+    ).call
+
+    assert_equal "ok", payload[:status]
+    assert_equal "admin", payload[:props][:role]
+  end
+
+  def test_in_validator_rejects_invalid_value
+    payload = InValidatorAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "role" => "superuser" }
+    ).call
+
+    assert_equal "error", payload[:status]
+    assert_equal ["is not included in the list"], payload[:errors]["role"]
+  end
+
+  def test_format_validator_accepts_matching_value
+    payload = FormatValidatorAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "slug" => "my-slug-123" }
+    ).call
+
+    assert_equal "ok", payload[:status]
+    assert_equal "my-slug-123", payload[:props][:slug]
+  end
+
+  def test_format_validator_rejects_non_matching_value
+    payload = FormatValidatorAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "slug" => "INVALID SLUG!" }
+    ).call
+
+    assert_equal "error", payload[:status]
+    assert_equal ["is invalid"], payload[:errors]["slug"]
+  end
+
+  def test_min_max_validator_accepts_in_range
+    payload = MinMaxValidatorAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "age" => "25", "name" => "Alice" }
+    ).call
+
+    assert_equal "ok", payload[:status]
+    assert_equal 25, payload[:props][:age]
+  end
+
+  def test_min_validator_rejects_below_minimum
+    payload = MinMaxValidatorAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "age" => "-1", "name" => "Alice" }
+    ).call
+
+    assert_equal "error", payload[:status]
+    assert_equal ["is too small"], payload[:errors]["age"]
+  end
+
+  def test_max_validator_rejects_above_maximum
+    payload = MinMaxValidatorAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "age" => "200", "name" => "Alice" }
+    ).call
+
+    assert_equal "error", payload[:status]
+    assert_equal ["is too large"], payload[:errors]["age"]
+  end
+
+  def test_min_max_on_string_validates_length
+    payload = MinMaxValidatorAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "age" => "25", "name" => "A" }
+    ).call
+
+    assert_equal "error", payload[:status]
+    assert_equal ["is too small"], payload[:errors]["name"]
+  end
+
+  def test_empty_as_nil_treats_blank_string_as_nil
+    payload = EmptyAsNilAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "nickname" => "   " }
+    ).call
+
+    assert_equal "ok", payload[:status]
+    assert_nil payload[:props][:nickname]
+  end
+
+  def test_empty_as_nil_preserves_non_empty_string
+    payload = EmptyAsNilAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "nickname" => "Bob" }
+    ).call
+
+    assert_equal "ok", payload[:status]
+    assert_equal "Bob", payload[:props][:nickname]
+  end
+
+  def test_typed_array_coerces_elements
+    payload = TypedArrayAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "tag_ids" => ["1", "2", "3"] }
+    ).call
+
+    assert_equal "ok", payload[:status]
+    assert_equal [1, 2, 3], payload[:props][:tag_ids]
+  end
+
+  def test_typed_array_rejects_invalid_elements
+    payload = TypedArrayAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "tag_ids" => ["1", "abc", "3"] }
+    ).call
+
+    assert_equal "error", payload[:status]
+    assert_equal ["is invalid"], payload[:errors]["tag_ids"]
+  end
+
+  def test_custom_validate_accepts_valid_value
+    payload = CustomValidateAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "code" => "ABC123" }
+    ).call
+
+    assert_equal "ok", payload[:status]
+    assert_equal "ABC123", payload[:props][:code]
+  end
+
+  def test_custom_validate_rejects_invalid_value
+    payload = CustomValidateAction.new(
+      ctx: DummyContext.new(nil, nil, nil, nil),
+      raw_params: { "code" => "SHORT" }
+    ).call
+
+    assert_equal "error", payload[:status]
+    assert_equal ["must be exactly 6 characters"], payload[:errors]["code"]
+  end
 end

data/test/generators/react_install_generator_test.rb

@@ -41,6 +41,7 @@ class ReactInstallGeneratorTest < Rails::Generators::TestCase
     package_json = JSON.parse(File.read(File.join(destination_root, "package.json")))
     assert_equal "node app/javascript/archipelago/generate_registry.mjs", package_json.dig("scripts", "archipelago:registry")
     assert_match(/^node app\/javascript\/archipelago\/generate_registry\.mjs && /, package_json.dig("scripts", "build"))
+    assert_file ".npmrc", /@archipelago-js:registry=https:\/\/registry\.npmjs\.org/
   end
 
   def test_generates_typescript_entry_when_requested
@@ -64,4 +65,13 @@ class ReactInstallGeneratorTest < Rails::Generators::TestCase
     assert_file "app/javascript/archipelago/entry.jsx", /const registry = \{/
     refute File.exist?(File.join(destination_root, "app/javascript/archipelago/generate_registry.mjs"))
   end
+
+  def test_does_not_duplicate_scope_registry_when_already_present
+    File.write(File.join(destination_root, ".npmrc"), "@archipelago-js:registry=https://registry.npmjs.org\n")
+
+    run_generator %w[--interactive=false]
+
+    npmrc = File.read(File.join(destination_root, ".npmrc"))
+    assert_equal 1, npmrc.scan("@archipelago-js:registry=").length
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: archipelago-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Archipelago
@@ -116,11 +116,13 @@ files:
 - lib/archipelago.rb
 - lib/archipelago/action.rb
 - lib/archipelago/broadcasts.rb
+- lib/archipelago/cancan_adapter.rb
 - lib/archipelago/channel.rb
 - lib/archipelago/configuration.rb
 - lib/archipelago/context.rb
 - lib/archipelago/engine.rb
 - lib/archipelago/params_dsl.rb
+- lib/archipelago/pundit_adapter.rb
 - lib/archipelago/registry.rb
 - lib/archipelago/resolver.rb
 - lib/archipelago/response.rb