archipelago-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a271d60fbd7122dfe75a111e3182fc34662dd3afe9b6d4183e834d08be828e2b
+  data.tar.gz: '0357780015635cb62d1255e257064d6b5a3674a41f18465f5ce6f0e59ec54759'
+SHA512:
+  metadata.gz: a40da1f08277ed421fa36b9d29e03223036259625689eb17489455158d0f056cb4600e633f19994bcb2ba6bb7e06773a1db40b5033740f99027baaecd5aa0e66
+  data.tar.gz: b0827ebf94625a2a5c7f21cdf1c870794609a01d20e8a8dc028ef108cf1f1decde1f5d6284bba7930a267b85e9770430e19e63e45059312c6fd8b911e305add1

data/Appraisals

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+appraise "rails-7-1" do
+  gem "rails", "~> 7.1.0"
+  gem "sqlite3", ">= 1.6"
+end
+
+appraise "rails-7-2" do
+  gem "rails", "~> 7.2.0"
+  gem "sqlite3", ">= 1.6"
+end
+
+appraise "rails-8-1" do
+  gem "rails", "~> 8.1.0"
+  gem "sqlite3", ">= 1.6"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Archipelago
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,79 @@
+# archipelago-rails
+
+Rails engine for Archipelago server-driven React islands.
+
+## Supported Rails versions
+
+- Rails `>= 7.1`
+
+## Development setup
+
+```bash
+bundle install
+```
+
+## Run tests
+
+```bash
+# full suite (core + rails integration tests)
+bin/test
+
+# split tasks
+bundle exec rake test:core
+bundle exec rake test:rails
+```
+
+## Rails version matrix (Appraisal)
+
+```bash
+bundle exec appraisal install
+bin/test-appraisal rails-7-1
+bin/test-appraisal rails-7-2
+bin/test-appraisal rails-8-1
+```
+
+## Notes
+
+- Controller/generator tests run against an in-test Rails application harness.
+- JS packages are tested from repository root via `yarn test`.
+
+## Host app setup (React + esbuild)
+
+After `rails g archipelago:install`, you can scaffold frontend bootstrap wiring:
+
+```bash
+rails g archipelago:install:react
+```
+
+By default this runs an interactive wizard with auto-detected defaults
+(bundler, TypeScript, package manager, and local monorepo path).
+
+For esbuild apps, the wizard also enables auto-registry by default:
+- scans `app/javascript/islands/**/*.{js,jsx,ts,tsx}`
+- writes `app/javascript/archipelago/registry.generated.(js|ts)`
+- wires `package.json` esbuild scripts to run generator first
+
+Useful options:
+
+```bash
+# disable prompts and use flags only
+rails g archipelago:install:react --interactive=false --bundler=esbuild --typescript=true
+
+# force TSX output
+rails g archipelago:install:react --typescript=true
+
+# disable auto-registry and keep manual registry map in entry file
+rails g archipelago:install:react --auto_registry=false
+
+# install npm packages immediately
+rails g archipelago:install:react --install
+
+# install Archipelago packages from a local monorepo path
+rails g archipelago:install:react --install --local-monorepo-path=/absolute/path/to/cdx
+```
+
+Manual refresh command (if needed while a long-running watch is already running):
+
+```bash
+yarn archipelago:registry
+```

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new("test:core") do |t|
+  t.libs << "test"
+  t.pattern = "test/archipelago/**/*_test.rb"
+end
+
+Rake::TestTask.new("test:rails") do |t|
+  t.libs << "test"
+  t.pattern = ["test/controllers/**/*_test.rb", "test/generators/**/*_test.rb"]
+end
+
+task test: ["test:core", "test:rails"]
+
+task default: :test

data/app/controllers/archipelago/application_controller.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "action_controller/base"
+
+module Archipelago
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+    skip_forgery_protection if defined?(Rails) && Rails.env.test?
+  end
+end

data/app/controllers/archipelago/islands_controller.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Archipelago
+  class IslandsController < ApplicationController
+    rescue_from Archipelago::ResolutionError, with: :render_not_found
+    rescue_from Archipelago::MissingAuthorization, with: :render_forbidden
+    rescue_from Archipelago::Forbidden, with: :render_forbidden
+    rescue_from Archipelago::InvalidOrigin, with: :render_forbidden
+    rescue_from Archipelago::InvalidRedirect, with: :render_invalid_redirect
+
+    def create
+      validate_origin!
+
+      action_class = resolver.resolve(component: params[:component], operation: params[:operation])
+      action = action_class.new(ctx: request_context, raw_params: island_params)
+      payload = action.call
+
+      render json: payload, status: rack_status_for(payload)
+    end
+
+    def debug
+      return head :not_found unless Rails.env.development? || Rails.env.test?
+
+      render json: debug_payload
+    end
+
+    private
+
+    def resolver
+      @resolver ||= Archipelago::Resolver.new
+    end
+
+    def request_context
+      Archipelago::Context.new(
+        request: request,
+        params: params,
+        session: session,
+        user: current_archipelago_user
+      )
+    end
+
+    def current_archipelago_user
+      resolver_proc = Archipelago.configuration.current_user_resolver
+      return instance_exec(&resolver_proc) if resolver_proc
+
+      method_name = Archipelago.configuration.current_user_method
+      return send(method_name) if respond_to?(method_name, true)
+
+      nil
+    end
+
+    def validate_origin!
+      Archipelago::Security::OriginValidator.new(request).validate!
+    end
+
+    def island_params
+      params.to_unsafe_h.except(:component, :operation, :controller, :action)
+    end
+
+    def rack_status_for(payload)
+      case payload[:status]
+      when "ok", "redirect", "error"
+        :ok
+      when "forbidden"
+        :forbidden
+      else
+        :ok
+      end
+    end
+
+    def render_not_found
+      head :not_found
+    end
+
+    def render_forbidden
+      render json: Archipelago::Response.forbidden, status: :forbidden
+    end
+
+    def render_invalid_redirect(exception)
+      render json: Archipelago::Response.error(errors: { base: [exception.message] }), status: :unprocessable_entity
+    end
+
+    def debug_payload
+      {
+        root_namespace: Archipelago.configuration.root_namespace,
+        registry: Archipelago.registry.to_h.transform_values(&:name),
+        actions: debug_actions_from_files,
+        registry_actions: debug_actions_from_registry
+      }
+    end
+
+    def debug_actions_from_files
+      files = Dir.glob(Rails.root.join("app/islands/**/*.rb")).sort
+
+      files.map do |file_path|
+        relative = file_path.delete_prefix("#{Rails.root}/app/islands/").delete_suffix(".rb")
+        *component_parts, operation = relative.split("/")
+        component = component_parts.map(&:camelize).join("__")
+        handler_name = [
+          Archipelago.configuration.root_namespace,
+          *component_parts.map(&:camelize),
+          operation.camelize
+        ].join("::")
+        handler_class = handler_name.safe_constantize
+
+        {
+          source: "filesystem",
+          component: component,
+          operation: operation,
+          file: file_path.delete_prefix("#{Rails.root}/"),
+          handler: handler_name,
+          params: debug_param_schema_for(handler_class)
+        }
+      end
+    end
+
+    def debug_actions_from_registry
+      Archipelago.registry.to_h.map do |key, handler|
+        component, operation = key.split("#", 2)
+        {
+          source: "registry",
+          component: component,
+          operation: operation,
+          handler: handler.name,
+          params: debug_param_schema_for(handler)
+        }
+      end.sort_by { |entry| [entry[:component].to_s, entry[:operation].to_s] }
+    end
+
+    def debug_param_schema_for(handler_class)
+      return [] unless handler_class.respond_to?(:param_definitions)
+
+      handler_class.param_definitions.values.map do |definition|
+        {
+          name: definition.name.to_s,
+          type: definition.type.to_s,
+          required: definition.required,
+          default: debug_param_default(definition.default),
+          transforms: {
+            strip: definition.strip,
+            downcase: definition.downcase,
+            upcase: definition.upcase
+          }
+        }
+      end
+    end
+
+    def debug_param_default(value)
+      if value == Archipelago::ParamsDSL::MISSING
+        { provided: false }
+      elsif value.respond_to?(:call)
+        { provided: true, kind: "callable" }
+      else
+        { provided: true, value: value }
+      end
+    end
+  end
+end

data/config/database.yml

@@ -0,0 +1,5 @@
+test:
+  adapter: sqlite3
+  database: ":memory:"
+  pool: 5
+  timeout: 5000

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Archipelago::Engine.routes.draw do
+  post "/:component/:operation", to: "islands#create"
+  get "/__debug", to: "islands#debug"
+end

data/lib/archipelago/action.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Archipelago
+  class Action
+    include Archipelago::ParamsDSL
+
+    class << self
+      attr_reader :authorization_block
+
+      def authorize(&block)
+        @authorization_block = block
+      end
+    end
+
+    attr_reader :ctx, :raw_params, :errors
+
+    def initialize(ctx:, raw_params:)
+      @ctx = ctx
+      @raw_params = raw_params.with_indifferent_access
+      @errors = Hash.new { |hash, key| hash[key] = [] }
+      @coerced_params = {}
+      @response_props = {}
+      @redirect_location = nil
+    end
+
+    def call
+      Archipelago.instrument("archipelago.action.perform", action: self.class.name) do
+        @coerced_params, coercion_errors = coerce_declared_params(raw_params)
+        merge_errors!(coercion_errors)
+        if errors.any?
+          Archipelago.instrument("archipelago.action.error", action: self.class.name, reason: "validation")
+          return Archipelago::Response.error(errors: errors)
+        end
+
+        run_authorization!
+        perform
+
+        if errors.any?
+          Archipelago.instrument("archipelago.action.error", action: self.class.name, reason: "validation")
+          return Archipelago::Response.error(errors: errors)
+        end
+
+        if @redirect_location
+          validator = Archipelago::Security::RedirectValidator.new
+          location = validator.validate!(@redirect_location)
+          return Archipelago::Response.redirect(location: location)
+        end
+
+        payload = Archipelago::Response.ok(props: @response_props, version: Archipelago.next_version)
+        maybe_broadcast(payload)
+        payload
+      end
+    rescue Archipelago::Forbidden
+      Archipelago.instrument("archipelago.action.error", action: self.class.name, reason: "forbidden")
+      Archipelago::Response.forbidden
+    rescue StandardError => e
+      if record_invalid_error?(e)
+        map_record_invalid!(e)
+        Archipelago.instrument("archipelago.action.error", action: self.class.name, reason: "record_invalid")
+        Archipelago::Response.error(errors: errors)
+      else
+        raise
+      end
+    end
+
+    def add_error(field, message)
+      errors[field.to_s] << message
+    end
+
+    def props(payload)
+      @response_props = payload
+    end
+
+    def redirect_to(location)
+      @redirect_location = location
+    end
+
+    private
+
+    def run_authorization!
+      block = self.class.authorization_block
+
+      if block.nil?
+        raise Archipelago::MissingAuthorization if Archipelago.configuration.authorize_by_default
+
+        return true
+      end
+
+      authorized = instance_exec(&block)
+      raise Archipelago::Forbidden unless authorized
+
+      true
+    end
+
+    def merge_errors!(incoming)
+      incoming.each do |field, messages|
+        messages.each { |message| add_error(field, message) }
+      end
+    end
+
+    def map_record_invalid!(error)
+      return unless error.record.respond_to?(:errors)
+
+      error.record.errors.to_hash(true).each do |field, messages|
+        Array(messages).each { |message| add_error(field, message) }
+      end
+    end
+
+    def record_invalid_error?(error)
+      defined?(ActiveRecord::RecordInvalid) && error.is_a?(ActiveRecord::RecordInvalid)
+    end
+
+    def maybe_broadcast(payload)
+      stream_name = raw_params[:__stream]
+      return if stream_name.blank?
+      return unless payload[:status] == "ok"
+
+      Archipelago.broadcast(stream_name, props: payload[:props], version: payload[:version])
+    end
+  end
+end

data/lib/archipelago/broadcasts.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Archipelago
+  module Broadcasts
+    module_function
+
+    def broadcast(stream_name, props:, version: Archipelago.next_version)
+      payload = Archipelago::Response.ok(props: props, version: version)
+      unless defined?(ActionCable) && ActionCable.respond_to?(:server)
+        raise LoadError, "ActionCable is required for streaming broadcasts"
+      end
+
+      ActionCable.server.broadcast(stream_name, payload)
+      payload
+    end
+  end
+end

data/lib/archipelago/channel.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+base_channel = if defined?(::ApplicationCable::Channel)
+  ::ApplicationCable::Channel
+elsif defined?(ActionCable::Channel::Base)
+  ActionCable::Channel::Base
+else
+  Class.new do
+    def stream_from(*); end
+    def reject; end
+    def params = {}
+  end
+end
+
+channel_class = Class.new(base_channel) do
+  def subscribed
+    stream_name = verified_stream_name
+    reject unless stream_name
+
+    stream_from(stream_name)
+  end
+
+  private
+
+  def verified_stream_name
+    stream_name = params[:stream_name].to_s
+    return nil unless stream_name.match?(self.class::STREAM_PATTERN)
+
+    stream_name
+  end
+end
+
+channel_class.const_set(:STREAM_PATTERN, /\A[A-Za-z0-9:_-]+\z/)
+
+Archipelago.send(:remove_const, :IslandChannel) if Archipelago.const_defined?(:IslandChannel, false)
+Archipelago.const_set(:IslandChannel, channel_class)

data/lib/archipelago/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Archipelago
+  class Configuration
+    attr_accessor :root_namespace,
+                  :current_user_method,
+                  :current_user_resolver,
+                  :authorize_by_default,
+                  :strict_origin_check,
+                  :allowed_redirect_hosts,
+                  :version_source
+
+    def initialize
+      @root_namespace = "Islands"
+      @current_user_method = :current_user
+      @current_user_resolver = nil
+      @authorize_by_default = true
+      @strict_origin_check = false
+      @allowed_redirect_hosts = []
+      @version_source = -> { (Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)).to_i }
+    end
+  end
+end

data/lib/archipelago/context.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Archipelago
+  class Context
+    attr_reader :request, :params, :session, :user
+
+    def initialize(request:, params:, session:, user: nil)
+      @request = request
+      @params = params
+      @session = session
+      @user = user
+    end
+  end
+end

data/lib/archipelago/engine.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Archipelago
+  class Engine < ::Rails::Engine
+    isolate_namespace Archipelago
+
+    initializer "archipelago.view_helper" do
+      ActiveSupport.on_load(:action_view) do
+        include Archipelago::ViewHelper
+      end
+    end
+
+    initializer "archipelago.test_helpers" do
+      ActiveSupport.on_load(:action_dispatch_integration_test) do
+        include Archipelago::TestHelpers
+      end
+    end
+  end
+end