archipelago-rails 0.1.0

data/lib/archipelago/params_dsl.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Archipelago
+  module ParamsDSL
+    MISSING = Object.new.freeze
+
+    ParamDefinition = Struct.new(
+      :name,
+      :type,
+      :required,
+      :default,
+      :strip,
+      :downcase,
+      :upcase,
+      keyword_init: true
+    )
+
+    module ClassMethods
+      def param_definitions
+        @param_definitions ||= {}
+      end
+
+      def param(name, type, required: false, default: MISSING, strip: false, downcase: false, upcase: false)
+        symbol_name = name.to_sym
+
+        param_definitions[symbol_name] = ParamDefinition.new(
+          name: symbol_name,
+          type: type,
+          required: required,
+          default: default,
+          strip: strip,
+          downcase: downcase,
+          upcase: upcase
+        )
+
+        define_method(symbol_name) do
+          @coerced_params[symbol_name]
+        end
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def coerce_declared_params(raw_params)
+      coerced = {}
+      errors = Hash.new { |hash, key| hash[key] = [] }
+
+      self.class.param_definitions.each_value do |definition|
+        raw_value = fetch_param(raw_params, definition.name)
+
+        if blank_value?(raw_value)
+          if definition.default != MISSING
+            coerced[definition.name] = definition.default.respond_to?(:call) ? definition.default.call : definition.default
+          elsif definition.required
+            errors[definition.name.to_s] << "is required"
+          end
+
+          next
+        end
+
+        begin
+          coerced_value = coerce_value(raw_value, definition)
+          coerced[definition.name] = coerced_value
+        rescue ArgumentError, TypeError, JSON::ParserError
+          errors[definition.name.to_s] << "is invalid"
+        end
+      end
+
+      [coerced, errors]
+    end
+
+    private
+
+    def fetch_param(raw_params, key)
+      raw_params[key] || raw_params[key.to_s]
+    end
+
+    def blank_value?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def coerce_value(raw_value, definition)
+      value = cast(raw_value, definition.type)
+
+      return value unless value.is_a?(String)
+
+      value = value.strip if definition.strip
+      value = value.downcase if definition.downcase
+      value = value.upcase if definition.upcase
+      value
+    end
+
+    def cast(value, type)
+      case type
+      when :string
+        String(value)
+      when :integer
+        Integer(value)
+      when :boolean
+        cast_boolean(value)
+      when :float
+        Float(value)
+      when :date
+        Date.parse(String(value))
+      when :datetime
+        Time.parse(String(value))
+      when :array
+        cast_array(value)
+      when :json
+        cast_json(value)
+      else
+        raise ArgumentError, "Unsupported param type: #{type}"
+      end
+    end
+
+    def cast_boolean(value)
+      return true if [true, 1, "1", "true", "on", "yes"].include?(value)
+      return false if [false, 0, "0", "false", "off", "no"].include?(value)
+
+      raise TypeError, "Invalid boolean value"
+    end
+
+    def cast_array(value)
+      return value if value.is_a?(Array)
+
+      parsed = JSON.parse(String(value))
+      raise TypeError, "Array expected" unless parsed.is_a?(Array)
+
+      parsed
+    end
+
+    def cast_json(value)
+      return value if value.is_a?(Hash) || value.is_a?(Array)
+
+      JSON.parse(String(value))
+    end
+  end
+end

data/lib/archipelago/registry.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Archipelago
+  class Registry
+    def initialize
+      @map = {}
+    end
+
+    def map(key, handler)
+      @map[key] = handler
+    end
+
+    def resolve(key)
+      @map[key]
+    end
+
+    def to_h
+      @map.dup
+    end
+
+    def clear!
+      @map.clear
+    end
+  end
+end

data/lib/archipelago/resolver.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Archipelago
+  class Resolver
+    COMPONENT_PATTERN = /\A[A-Z][A-Za-z0-9_]*\z/
+    OPERATION_PATTERN = /\A[a-z][a-z0-9_]*\z/
+
+    def initialize(configuration: Archipelago.configuration, registry: Archipelago.registry)
+      @configuration = configuration
+      @registry = registry
+    end
+
+    def resolve(component:, operation:)
+      Archipelago.instrument(
+        "archipelago.action.resolve",
+        component: component,
+        operation: operation
+      ) do
+        validate!(component: component, operation: operation)
+
+        override = @registry.resolve("#{component}##{operation}")
+        return validate_handler!(override) if override
+
+        constant_name = convention_constant_name(component: component, operation: operation)
+        klass = constant_name.safe_constantize
+        raise Archipelago::ResolutionError, "Unknown island action" unless klass
+
+        validate_handler!(klass)
+      end
+    end
+
+    private
+
+    def validate!(component:, operation:)
+      raise Archipelago::ResolutionError, "Invalid component name" unless component.match?(COMPONENT_PATTERN)
+      raise Archipelago::ResolutionError, "Invalid operation name" unless operation.match?(OPERATION_PATTERN)
+    end
+
+    def validate_handler!(handler)
+      unless handler.is_a?(Class) && handler < Archipelago::Action
+        raise Archipelago::ResolutionError, "Resolved handler must inherit from Archipelago::Action"
+      end
+
+      handler
+    end
+
+    def convention_constant_name(component:, operation:)
+      component_parts = component.split("__").map { |part| part.underscore.camelize }
+      operation_class = operation.camelize
+
+      [@configuration.root_namespace, *component_parts, operation_class].join("::")
+    end
+  end
+end

data/lib/archipelago/response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Archipelago
+  module Response
+    module_function
+
+    def ok(props:, version:)
+      {
+        status: "ok",
+        props: props,
+        version: version
+      }
+    end
+
+    def redirect(location:)
+      {
+        status: "redirect",
+        location: location
+      }
+    end
+
+    def error(errors:)
+      {
+        status: "error",
+        errors: errors
+      }
+    end
+
+    def forbidden
+      {
+        status: "forbidden"
+      }
+    end
+  end
+end

data/lib/archipelago/security/origin_validator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Archipelago
+  module Security
+    class OriginValidator
+      def initialize(request, configuration: Archipelago.configuration)
+        @request = request
+        @configuration = configuration
+      end
+
+      def validate!
+        return true unless @configuration.strict_origin_check
+
+        origin = @request.headers["Origin"]
+        return true if origin.nil? || origin.empty?
+
+        uri = URI.parse(origin)
+        expected_scheme = @request.protocol.delete_suffix("://")
+
+        valid = uri.scheme == expected_scheme &&
+          uri.host == @request.host &&
+          uri.port == @request.port
+
+        raise Archipelago::InvalidOrigin, "Origin mismatch" unless valid
+
+        true
+      rescue URI::InvalidURIError
+        raise Archipelago::InvalidOrigin, "Invalid origin URI"
+      end
+    end
+  end
+end

data/lib/archipelago/security/redirect_validator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Archipelago
+  module Security
+    class RedirectValidator
+      def initialize(configuration: Archipelago.configuration)
+        @configuration = configuration
+      end
+
+      def validate!(location)
+        return location if relative_path?(location)
+
+        uri = URI.parse(location)
+        unless uri.is_a?(URI::HTTP) && @configuration.allowed_redirect_hosts.include?(uri.host)
+          raise Archipelago::InvalidRedirect, "Unsafe redirect host"
+        end
+
+        location
+      rescue URI::InvalidURIError
+        raise Archipelago::InvalidRedirect, "Invalid redirect URI"
+      end
+
+      private
+
+      def relative_path?(location)
+        location.start_with?("/") && !location.start_with?("//")
+      end
+    end
+  end
+end

data/lib/archipelago/test_helpers.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Archipelago
+  module TestHelpers
+    def island_post(component, operation, params = {})
+      post "/islands/#{component}/#{operation}", params: params, as: :json
+    end
+
+    def parsed_island_response
+      JSON.parse(response.body)
+    end
+
+    def assert_island_props(key, value)
+      body = parsed_island_response
+      assert_equal "ok", body["status"]
+      assert_equal value, body.fetch("props").fetch(key.to_s)
+    end
+
+    def assert_island_redirect(path)
+      body = parsed_island_response
+      assert_equal "redirect", body["status"]
+      assert_equal path, body["location"]
+    end
+
+    def assert_island_errors(field)
+      body = parsed_island_response
+      assert_equal "error", body["status"]
+      assert body.fetch("errors").key?(field.to_s)
+    end
+  end
+end

data/lib/archipelago/view_helper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Archipelago
+  module ViewHelper
+    def archipelago_island(component, props:, params: {}, instance: nil, stream: nil, **html_options)
+      stream_name = resolve_stream_name(component: component, instance: instance, stream: stream)
+
+      data_attributes = {
+        island: true,
+        component: component,
+        props: props.to_json,
+        params: params.to_json,
+        instance: instance,
+        stream: stream_name
+      }.compact
+
+      content_tag(:div, "", html_options.merge(data: data_attributes))
+    end
+
+    private
+
+    def resolve_stream_name(component:, instance:, stream:)
+      return nil if stream.nil?
+      return stream if stream.is_a?(String)
+
+      raise ArgumentError, "instance is required when stream: true" if instance.blank?
+
+      "#{component}:#{instance}"
+    end
+  end
+end

data/lib/archipelago-rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "archipelago"

data/lib/archipelago.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/string/inflections"
+require "active_support/notifications"
+require "json"
+require "uri"
+
+module Archipelago
+  class Error < StandardError; end
+  class Forbidden < Error; end
+  class ResolutionError < Error; end
+  class InvalidOrigin < Error; end
+  class InvalidRedirect < Error; end
+  class MissingAuthorization < Error; end
+
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def registry
+      @registry ||= Registry.new
+    end
+
+    def map(mapping)
+      mapping.each { |key, value| registry.map(key, value) }
+    end
+
+    def next_version
+      configuration.version_source.call
+    end
+
+    def broadcast(stream_name, props:, version: next_version)
+      Broadcasts.broadcast(stream_name, props: props, version: version)
+    end
+
+    def instrument(event, payload = {}, &block)
+      ActiveSupport::Notifications.instrument(event, payload, &block)
+    end
+  end
+end
+
+require "archipelago/configuration"
+require "archipelago/registry"
+require "archipelago/response"
+require "archipelago/params_dsl"
+require "archipelago/context"
+require "archipelago/security/origin_validator"
+require "archipelago/security/redirect_validator"
+require "archipelago/action"
+require "archipelago/resolver"
+require "archipelago/broadcasts"
+require "archipelago/channel"
+require "archipelago/view_helper"
+require "archipelago/test_helpers"
+begin
+  require "archipelago/engine"
+rescue LoadError, NameError
+  # Engine support requires railties and loads when running inside Rails.
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Archipelago
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Installs Archipelago into a Rails app"
+
+      def create_islands_directory
+        empty_directory "app/islands"
+      end
+
+      def create_initializer
+        create_file "config/initializers/archipelago.rb", <<~RUBY
+          Archipelago.configure do |config|
+            config.root_namespace = "Islands"
+            config.current_user_method = :current_user
+            config.authorize_by_default = true
+            config.strict_origin_check = false
+            config.allowed_redirect_hosts = []
+          end
+        RUBY
+      end
+
+      def mount_engine
+        route_line = "mount Archipelago::Engine => \"/islands\""
+        routes_path = "config/routes.rb"
+
+        if File.exist?(routes_path) && !File.read(routes_path).include?(route_line)
+          route(route_line)
+        end
+      end
+
+      def print_next_steps
+        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"
+        say "esbuild users get auto-registry wiring by default in install:react"
+      end
+    end
+  end
+end