zero-rails-adapter 0.2.0

data/lib/zero_rails_adapter/configuration.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  class Configuration
+    attr_accessor :authenticator, :request_verifier, :authorizer, :logger,
+      :transaction_class, :storage_provider, :crud_authorizer,
+      :writable_attributes, :generated_attributes, :model_resolver,
+      :model_provider
+
+    def initialize
+      @authenticator = ->(_request) { Identity.new }
+      @request_verifier = ->(_request) { true }
+      @authorizer = ->(_context, _mutation) { true }
+      @crud_authorizer = ->(_context, _action, _target, _attributes) { true }
+      @logger = defined?(Rails) ? Rails.logger : nil
+      @transaction_class = ActiveRecord::Base
+      @model_provider = -> { default_models }
+      @model_resolver = lambda do |resource|
+        allowed_models = Array(model_provider.call).select do |model|
+          active_record_model?(model)
+        end
+        candidate = resource.to_s.classify.safe_constantize
+        candidate = nil unless allowed_models.include?(candidate)
+        candidate ||= allowed_models.find { |model| model.table_name == resource.to_s }
+      end
+      @writable_attributes = ->(model, _action, _context) { default_writable_attributes(model) }
+      @generated_attributes = ->(model, _action) { default_writable_attributes(model) }
+      @storage_provider = lambda do |request|
+        Storage::ZeroSchema.new(request:, transaction_class:)
+      end
+    end
+
+    private
+
+    def default_models
+      application = Rails.application if defined?(Rails) && Rails.respond_to?(:application)
+      application&.eager_load!
+      ActiveRecord::Base.descendants.select do |model|
+        active_record_model?(model) &&
+          model.name.present? &&
+          !model.name.start_with?("ZeroRailsAdapter::")
+      end
+    end
+
+    def default_writable_attributes(model)
+      model.column_names -
+        model.readonly_attributes.to_a -
+        [model.inheritance_column, "created_at", "updated_at"]
+    end
+
+    def active_record_model?(candidate)
+      candidate.is_a?(Class) &&
+        candidate < ActiveRecord::Base &&
+        !candidate.abstract_class?
+    end
+  end
+end

data/lib/zero_rails_adapter/context.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  class Context
+    attr_reader :identity, :request, :rack_request
+
+    delegate :user_id, :current_user, :claims, to: :identity
+
+    def initialize(identity:, request: nil, rack_request: nil)
+      @identity = identity
+      @request = request
+      @rack_request = rack_request
+    end
+
+    def with(request: @request, rack_request: @rack_request)
+      self.class.new(identity:, request:, rack_request:)
+    end
+  end
+end

data/lib/zero_rails_adapter/crud/dispatcher.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  module Crud
+    class Dispatcher
+      ACTIONS = {
+        "create" => :create,
+        "insert" => :create,
+        "update" => :update,
+        "destroy" => :destroy,
+        "delete" => :destroy
+      }.freeze
+
+      attr_reader :context
+
+      def initialize(context:)
+        @context = context
+      end
+
+      def call(mutation)
+        resource, action = parse_name(mutation.name)
+        model = resolve_model(resource)
+        attributes = normalize_arguments(mutation.argument)
+
+        case action
+        when :create
+          create(model, attributes)
+        when :update
+          update(model, attributes)
+        when :destroy
+          destroy(model, attributes)
+        end
+      end
+
+      private
+
+      def parse_name(name)
+        resource, action_name = name.to_s.split(".", 2)
+        action = ACTIONS[action_name]
+        unless resource&.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*\z/) && action
+          raise UnknownMutatorError, "Could not find mutator #{name}"
+        end
+
+        [resource, action]
+      end
+
+      def resolve_model(resource)
+        model = ZeroRailsAdapter.configuration.model_resolver.call(resource)
+        return model if model.is_a?(Class) && model < ActiveRecord::Base
+
+        raise UnknownMutatorError, "Could not resolve Active Record model for #{resource}"
+      end
+
+      def normalize_arguments(arguments)
+        unless arguments.respond_to?(:to_h)
+          raise ValidationError, "CRUD mutation arguments must be an object"
+        end
+
+        arguments.to_h.stringify_keys
+      end
+
+      def create(model, attributes)
+        authorize!(:create, model, attributes)
+        model.create!(writable(model, :create, attributes))
+        nil
+      end
+
+      def update(model, attributes)
+        record = find_record!(model, attributes)
+        authorize!(:update, record, attributes)
+        changes = writable(model, :update, attributes).except(*primary_keys(model))
+        record.update!(changes)
+        nil
+      end
+
+      def destroy(model, attributes)
+        record = find_record!(model, attributes)
+        authorize!(:destroy, record, attributes)
+        record.destroy!
+        nil
+      end
+
+      def find_record!(model, attributes)
+        keys = primary_keys(model)
+        values = attributes.slice(*keys)
+        missing = keys - values.keys
+        if missing.any?
+          raise ValidationError.new(
+            "Missing primary key attributes: #{missing.join(', ')}",
+            details: {"primaryKey" => missing}
+          )
+        end
+
+        model.find_by!(values)
+      end
+
+      def primary_keys(model)
+        Array(model.primary_key).map(&:to_s)
+      end
+
+      def authorize!(action, target, attributes)
+        allowed = ZeroRailsAdapter.configuration.crud_authorizer.call(
+          context,
+          action,
+          target,
+          attributes
+        )
+        raise ForbiddenError, "Mutation is not authorized" unless allowed
+      end
+
+      def writable(model, action, attributes)
+        allowed = ZeroRailsAdapter.configuration.writable_attributes.call(
+          model,
+          action,
+          context
+        )
+        attributes.slice(*Array(allowed).map(&:to_s))
+      end
+    end
+  end
+end

data/lib/zero_rails_adapter/engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  class Engine < ::Rails::Engine
+    isolate_namespace ZeroRailsAdapter
+  end
+end

data/lib/zero_rails_adapter/errors.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  class Error < StandardError; end
+
+  class ApplicationError < Error
+    attr_reader :details
+
+    def initialize(message = nil, details: nil)
+      @details = details
+      super(message)
+    end
+  end
+
+  class ValidationError < ApplicationError; end
+  class ForbiddenError < ApplicationError; end
+  class UnauthorizedError < Error; end
+  class UnknownMutatorError < ApplicationError; end
+  class UnsupportedColumnTypeError < Error; end
+
+  class ProtocolError < Error
+    attr_reader :mutation_ids
+
+    def initialize(message, mutation_ids: [])
+      @mutation_ids = mutation_ids
+      super(message)
+    end
+  end
+
+  class ParseError < ProtocolError
+    attr_reader :source
+
+    def initialize(message, mutation_ids: [], source: :body)
+      @source = source
+      super(message, mutation_ids:)
+    end
+  end
+
+  class UnsupportedPushVersionError < ProtocolError
+    attr_reader :version
+
+    def initialize(version, mutation_ids: [])
+      @version = version
+      super("Unsupported push version: #{version}", mutation_ids:)
+    end
+  end
+
+  class OutOfOrderMutationError < ProtocolError; end
+  class AlreadyProcessedError < Error; end
+end

data/lib/zero_rails_adapter/identity.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  Identity = Data.define(:user_id, :current_user, :claims) do
+    def initialize(user_id: nil, current_user: nil, claims: {})
+      super(user_id: user_id&.to_s, current_user:, claims: claims || {})
+    end
+  end
+end

data/lib/zero_rails_adapter/mutation.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  class Mutation
+    REQUIRED_KEYS = %w[type id clientID name args timestamp].freeze
+
+    attr_reader :type, :id, :client_id, :name, :args, :timestamp
+
+    def self.parse(value)
+      unless value.is_a?(Hash)
+        raise ParseError, "Mutation must be an object"
+      end
+
+      missing = REQUIRED_KEYS.reject { |key| value.key?(key) }
+      raise ParseError, "Mutation is missing #{missing.join(', ')}" if missing.any?
+      raise ParseError, "Mutation type must be custom" unless value["type"] == "custom"
+      raise ParseError, "Mutation id must be a number" unless value["id"].is_a?(Numeric)
+      raise ParseError, "Mutation clientID must be a string" unless value["clientID"].is_a?(String)
+      raise ParseError, "Mutation name must be a string" unless value["name"].is_a?(String)
+      raise ParseError, "Mutation args must be an array" unless value["args"].is_a?(Array)
+      raise ParseError, "Mutation timestamp must be a number" unless value["timestamp"].is_a?(Numeric)
+
+      new(
+        type: value["type"],
+        id: value["id"],
+        client_id: value["clientID"],
+        name: value["name"],
+        args: value["args"],
+        timestamp: value["timestamp"]
+      )
+    end
+
+    def initialize(type:, id:, client_id:, name:, args:, timestamp:)
+      @type = type
+      @id = id
+      @client_id = client_id
+      @name = name
+      @args = args
+      @timestamp = timestamp
+    end
+
+    def argument
+      args.first
+    end
+
+    def identifier
+      {"clientID" => client_id, "id" => id}
+    end
+  end
+end

data/lib/zero_rails_adapter/mutator.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  class Mutator
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    class_attribute :configured_mutation_name, instance_writer: false
+    class_attribute :authorization_callback, instance_writer: false
+
+    attr_reader :arguments, :context
+
+    class << self
+      def mutation_name(name = nil)
+        return configured_mutation_name if name.nil?
+
+        self.configured_mutation_name = name.to_s
+        ZeroRailsAdapter.registry.register(self)
+      end
+
+      def authorize_with(callable = nil, &block)
+        self.authorization_callback = callable || block
+      end
+
+      def perform(&block)
+        define_method(:perform, &block)
+      end
+
+      def call(arguments = {}, context:)
+        new(arguments, context:).call
+      end
+    end
+
+    def initialize(arguments = {}, context:)
+      @arguments = arguments
+      @context = context
+      attributes = arguments.respond_to?(:to_h) ? arguments.to_h.symbolize_keys : {}
+      super(attributes)
+    end
+
+    def call
+      validate_arguments!
+      authorize!
+      perform
+    end
+
+    def perform
+      raise NotImplementedError, "#{self.class.name} must implement #perform"
+    end
+
+    private
+
+    def validate_arguments!
+      return if valid?
+
+      raise ValidationError.new(
+        "Mutation arguments are invalid",
+        details: errors.to_hash.stringify_keys
+      )
+    end
+
+    def authorize!
+      callback = self.class.authorization_callback
+      return true unless callback
+      return true if instance_exec(context, &callback)
+
+      raise ForbiddenError, "Mutation is not authorized"
+    end
+  end
+end

data/lib/zero_rails_adapter/processor.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  class Processor
+    CLEANUP_MUTATION_NAME = "_zero_cleanupResults"
+
+    attr_reader :request, :context, :storage
+
+    def initialize(request:, context:)
+      @request = request
+      @context = context.with(request:)
+      @storage = ZeroRailsAdapter.configuration.storage_provider.call(request)
+    end
+
+    def call
+      responses = []
+      processed_count = 0
+
+      request.mutations.each do |mutation|
+        if mutation.name == CLEANUP_MUTATION_NAME
+          cleanup_results(mutation)
+          processed_count += 1
+          next
+        end
+
+        responses << ActiveSupport::Notifications.instrument(
+          "mutation.zero_rails_adapter",
+          name: mutation.name,
+          client_id: mutation.client_id,
+          mutation_id: mutation.id,
+          client_group_id: request.client_group_id,
+          app_id: request.app_id,
+          schema: request.schema
+        ) { process_mutation(mutation) }
+        processed_count += 1
+      end
+
+      {
+        "kind" => "MutateResponse",
+        "mutations" => responses,
+        "userID" => context.user_id
+      }
+    rescue OutOfOrderMutationError => error
+      push_failed(
+        reason: "oooMutation",
+        message: error.message,
+        mutation_ids: request.mutation_ids.drop(processed_count)
+      )
+    rescue ActiveRecord::ActiveRecordError => error
+      push_failed(
+        reason: "database",
+        message: error.message,
+        mutation_ids: request.mutation_ids.drop(processed_count)
+      )
+    rescue StandardError => error
+      push_failed(
+        reason: "internal",
+        message: error.message,
+        mutation_ids: request.mutation_ids.drop(processed_count)
+      )
+    end
+
+    private
+
+    def process_mutation(mutation)
+      result = nil
+
+      storage.transaction do
+        expected = storage.increment_lmid!(mutation.client_id)
+        check_order!(expected, mutation)
+        authorized = ZeroRailsAdapter.configuration.authorizer.call(context, mutation)
+        raise ForbiddenError, "Mutation is not authorized" unless authorized
+        mutator = ZeroRailsAdapter.registry.find(mutation.name)
+        result =
+          if mutator
+            mutator.call(mutation.argument, context:)
+          else
+            Crud::Dispatcher.new(context:).call(mutation)
+          end
+      end
+
+      success_response(mutation, result)
+    rescue AlreadyProcessedError => error
+      already_processed_response(mutation, error)
+    rescue OutOfOrderMutationError
+      raise
+    rescue StandardError => error
+      application_error = normalize_application_error(error)
+      begin
+        persist_failure(mutation, application_error)
+      rescue AlreadyProcessedError => concurrent_error
+        return already_processed_response(mutation, concurrent_error)
+      end
+      mutation_response(mutation, application_result(application_error))
+    end
+
+    def persist_failure(mutation, error)
+      storage.transaction do
+        expected = storage.increment_lmid!(mutation.client_id)
+        check_order!(expected, mutation)
+        storage.write_result(
+          client_id: mutation.client_id,
+          mutation_id: mutation.id,
+          result: application_result(error)
+        )
+      end
+    end
+
+    def check_order!(expected, mutation)
+      if mutation.id < expected
+        raise AlreadyProcessedError,
+          "Ignoring mutation from #{mutation.client_id} with ID #{mutation.id} " \
+          "as it was already processed. Expected: #{expected}"
+      end
+      return if mutation.id == expected
+
+      raise OutOfOrderMutationError,
+        "Client #{mutation.client_id} sent mutation ID #{mutation.id} but expected #{expected}"
+    end
+
+    def success_response(mutation, result)
+      payload = {}
+      payload["data"] = serializable(result) unless result.nil?
+      mutation_response(mutation, payload)
+    end
+
+    def mutation_response(mutation, result)
+      {"id" => mutation.identifier, "result" => result}
+    end
+
+    def already_processed_response(mutation, error)
+      mutation_response(mutation, {
+        "error" => "alreadyProcessed",
+        "details" => error.message
+      })
+    end
+
+    def normalize_application_error(error)
+      return error if error.is_a?(ApplicationError)
+
+      if error.respond_to?(:record) && error.record.respond_to?(:errors)
+        return ApplicationError.new(error.message, details: error.record.errors.to_hash)
+      end
+
+      ApplicationError.new(error.message)
+    end
+
+    def application_result(error)
+      result = {"error" => "app", "message" => error.message}
+      result["details"] = serializable(error.details) unless error.details.nil?
+      result
+    end
+
+    def serializable(value)
+      value.as_json
+    end
+
+    def cleanup_results(mutation)
+      args = mutation.argument
+      return unless args.is_a?(Hash)
+      storage.transaction { storage.cleanup(args) }
+    rescue StandardError => error
+      ZeroRailsAdapter.configuration.logger&.warn(
+        "ZeroRailsAdapter cleanup failed: #{error.class}: #{error.message}"
+      )
+    end
+
+    def push_failed(reason:, message:, mutation_ids:)
+      {
+        "kind" => "PushFailed",
+        "origin" => "server",
+        "reason" => reason,
+        "message" => message,
+        "mutationIDs" => mutation_ids
+      }
+    end
+  end
+end

data/lib/zero_rails_adapter/registry.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  class Registry
+    SEPARATOR = /[|.]/
+
+    def initialize
+      @mutators = {}
+    end
+
+    def register(mutator_class, as: mutator_class.mutation_name)
+      raise ArgumentError, "mutation_name must be configured" if as.to_s.empty?
+
+      @mutators[canonical(as)] = mutator_class.name.to_s.empty? ? mutator_class : mutator_class.name
+      mutator_class
+    end
+
+    def fetch(name)
+      find(name) || raise(UnknownMutatorError, "Could not find mutator #{name}")
+    end
+
+    def find(name)
+      key = canonical(name)
+      mutator = resolve(@mutators[key])
+      return mutator if mutator
+
+      conventional_class_name(name).safe_constantize
+      mutator = resolve(@mutators[key])
+      return mutator if mutator
+    end
+
+    def registered_names
+      @mutators.keys.sort
+    end
+
+    private
+
+    def canonical(name)
+      name.to_s.split(SEPARATOR).join("|")
+    end
+
+    def conventional_class_name(name)
+      parts = name.to_s.split(SEPARATOR)
+      "#{parts.map(&:camelize).join('::')}Mutator"
+    end
+
+    def resolve(entry)
+      entry.is_a?(String) ? entry.safe_constantize : entry
+    end
+  end
+end