zero_ruby 0.1.0.alpha1

data/lib/zero_ruby/lmid_stores/active_record_store.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "../lmid_store"
+
+module ZeroRuby
+  module LmidStores
+    # ActiveRecord-based LMID store using Zero's zero_0.clients table.
+    # This store provides proper transaction support with atomic LMID updates
+    # for concurrent access in production environments.
+    #
+    # Uses the same atomic increment pattern as Zero's TypeScript implementation.
+    # @see https://github.com/rocicorp/mono/blob/main/packages/zero-server/src/zql-database.ts
+    #
+    # @example Usage
+    #   ZeroRuby.configure do |config|
+    #     config.lmid_store = :active_record
+    #   end
+    class ActiveRecordStore < LmidStore
+      # The model class to use for client records.
+      # Defaults to ZeroRuby::ZeroClient.
+      attr_reader :model_class
+
+      def initialize(model_class: nil)
+        @model_class = model_class || default_model_class
+      end
+
+      # Atomically increment and return the last mutation ID for a client.
+      # Uses INSERT ... ON CONFLICT to handle both new and existing clients
+      # in a single atomic operation, minimizing lock duration.
+      #
+      # @param client_group_id [String] The client group ID
+      # @param client_id [String] The client ID
+      # @return [Integer] The new last mutation ID (post-increment)
+      def fetch_and_increment(client_group_id, client_id)
+        table = model_class.quoted_table_name
+        sql = model_class.sanitize_sql_array([<<~SQL.squish, {client_group_id:, client_id:}])
+          INSERT INTO #{table} ("clientGroupID", "clientID", "lastMutationID")
+          VALUES (:client_group_id, :client_id, 1)
+          ON CONFLICT ("clientGroupID", "clientID")
+          DO UPDATE SET "lastMutationID" = #{table}."lastMutationID" + 1
+          RETURNING "lastMutationID"
+        SQL
+
+        model_class.connection.select_value(sql)
+      end
+
+      # Execute a block within an ActiveRecord transaction.
+      #
+      # @yield The block to execute within the transaction
+      # @return The result of the block
+      def transaction(&block)
+        model_class.transaction(&block)
+      end
+
+      private
+
+      def default_model_class
+        require_relative "../zero_client"
+        ZeroRuby::ZeroClient
+      end
+    end
+  end
+end

data/lib/zero_ruby/mutation.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "argument"
+require_relative "errors"
+require_relative "validator"
+
+module ZeroRuby
+  # Mixin that provides the argument DSL for mutations.
+  # Inspired by graphql-ruby's HasArguments pattern.
+  module HasArguments
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Declare an argument for this mutation
+      # @param name [Symbol] The argument name
+      # @param type [Class] The type class (e.g., ZeroRuby::Types::String)
+      # @param required [Boolean] Whether the argument is required
+      # @param validates [Hash] Validation configuration
+      # @param default [Object] Default value if not provided
+      # @param description [String] Description of the argument
+      def argument(name, type, required: true, validates: nil, default: Argument::NOT_PROVIDED, description: nil, **options)
+        arguments[name.to_sym] = Argument.new(
+          name: name,
+          type: type,
+          required: required,
+          validates: validates,
+          default: default,
+          description: description,
+          **options
+        )
+      end
+
+      # Get all declared arguments for this mutation (including inherited)
+      def arguments
+        @arguments ||= if superclass.respond_to?(:arguments)
+          superclass.arguments.dup
+        else
+          {}
+        end
+      end
+
+      # Coerce and validate raw arguments
+      # @param raw_args [Hash] Raw input arguments
+      # @param ctx [Hash] The context hash
+      # @return [Hash] Validated and coerced arguments
+      # @raise [ZeroRuby::ValidationError] If validation fails
+      def coerce_and_validate!(raw_args, ctx)
+        validated = {}
+        errors = []
+
+        arguments.each do |name, arg|
+          value = raw_args[name]
+
+          # Check required
+          if arg.required? && value.nil? && !arg.has_default?
+            errors << "#{name} is required"
+            next
+          end
+
+          # Apply default if needed, or nil for optional args without defaults
+          if value.nil?
+            validated[name] = arg.has_default? ? arg.default : nil
+            next
+          end
+
+          # Type coercion
+          begin
+            coerced = arg.coerce(value, ctx)
+          rescue CoercionError => e
+            errors << "#{name}: #{e.message}"
+            next
+          end
+
+          # Run validators
+          if arg.validators.any?
+            validation_errors = Validator.validate!(arg.validators, nil, ctx, coerced)
+            validation_errors.each do |err|
+              errors << "#{name} #{err}"
+            end
+          end
+
+          validated[name] = coerced
+        end
+
+        raise ValidationError.new(errors) if errors.any?
+        validated
+      end
+    end
+  end
+
+  # Base class for Zero mutations.
+  # Provides argument DSL, validation, and error handling.
+  #
+  # @example
+  #   class WorkCreate < ZeroRuby::Mutation
+  #     argument :id, ID, required: true
+  #     argument :title, String, required: true,
+  #       validates: { length: { maximum: 200 } }
+  #
+  #     def execute(id:, title:)
+  #       authorize! Work, to: :create?
+  #       Work.create!(id: id, title: title)
+  #     end
+  #   end
+  class Mutation
+    include HasArguments
+    include TypeNames
+
+    # The context hash containing current_user, etc.
+    attr_reader :ctx
+
+    # Initialize a mutation with raw arguments and context
+    # @param raw_args [Hash] Raw input arguments (will be coerced and validated)
+    # @param ctx [Hash] The context hash
+    def initialize(raw_args, ctx)
+      @ctx = ctx
+      @args = self.class.coerce_and_validate!(raw_args, ctx)
+    end
+
+    # Execute the mutation
+    # @return [Hash] Empty hash on success
+    # @raise [ZeroRuby::Error] On failure (formatted at boundary)
+    def call
+      execute(**@args)
+      {}
+    end
+
+    private
+
+    # Implement this method in subclasses to define mutation logic.
+    # Arguments declared with `argument` are passed as keyword arguments.
+    # Access context via ctx[:key] (e.g., ctx[:current_user]).
+    # No return value needed - just perform the mutation.
+    # Raise an exception to signal failure.
+    def execute(**)
+      raise NotImplementedError, "Subclasses must implement #execute"
+    end
+  end
+end

data/lib/zero_ruby/push_processor.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module ZeroRuby
+  # Processes Zero push requests with LMID tracking, version validation,
+  # and transaction support. This implements the same protocol as
+  # Zero's TypeScript implementation.
+  #
+  # @example Basic usage
+  #   processor = PushProcessor.new(
+  #     schema: ZeroSchema,
+  #     lmid_store: ZeroRuby.configuration.lmid_store_instance
+  #   )
+  #   result = processor.process(push_data, context)
+  #
+  # @see https://github.com/rocicorp/mono/blob/main/packages/zero-server/src/process-mutations.ts
+  # @see https://github.com/rocicorp/mono/blob/main/packages/zero-server/src/zql-database.ts
+  class PushProcessor
+    attr_reader :schema, :lmid_store, :max_retries
+
+    # @param schema [Class] The schema class for mutation processing
+    # @param lmid_store [LmidStore] The LMID store instance
+    # @param max_retries [Integer] Maximum retry attempts for retryable errors
+    def initialize(schema:, lmid_store:, max_retries: 3)
+      @schema = schema
+      @lmid_store = lmid_store
+      @max_retries = max_retries
+    end
+
+    # Process a Zero push request
+    #
+    # @param push_data [Hash] The parsed push request body
+    # @param context [Hash] Context to pass to mutations
+    # @return [Hash] The response hash
+    def process(push_data, context)
+      client_group_id = push_data["clientGroupID"]
+      mutations = push_data["mutations"] || []
+      results = []
+
+      mutations.each do |mutation_data|
+        result = process_mutation_with_lmid(mutation_data, client_group_id, context)
+        results << result
+
+        # If we hit an out-of-order error, stop processing the batch
+        break if result[:result][:error] == "ooo"
+      end
+
+      {mutations: results}
+    end
+
+    private
+
+    # Process a single mutation with LMID validation and transaction support.
+    # Uses atomic increment-then-validate pattern matching Zero's TypeScript implementation.
+    def process_mutation_with_lmid(mutation_data, client_group_id, context)
+      mutation_id = mutation_data["id"]
+      client_id = mutation_data["clientID"]
+
+      mutation_id_obj = {
+        id: mutation_id,
+        clientID: client_id
+      }
+
+      lmid_store.transaction do
+        # Atomically increment LMID first, then validate.
+        # This matches the TypeScript implementation's approach for minimal lock duration.
+        last_mutation_id = lmid_store.fetch_and_increment(client_group_id, client_id)
+        check_lmid!(client_id, mutation_id, last_mutation_id)
+
+        result = execute_with_retry(mutation_data, context)
+        {id: mutation_id_obj, result: result}
+      end
+    rescue ZeroRuby::Error => e
+      {id: mutation_id_obj, result: format_error_response(e)}
+    end
+
+    # Validate LMID against the post-increment value.
+    # The received mutation ID should equal the new last mutation ID.
+    #
+    # @raise [MutationAlreadyProcessedError] If mutation was already processed
+    # @raise [OutOfOrderMutationError] If mutation arrived out of order
+    def check_lmid!(client_id, received_id, last_mutation_id)
+      if received_id < last_mutation_id
+        raise MutationAlreadyProcessedError.new(
+          client_id: client_id,
+          received_id: received_id,
+          last_mutation_id: last_mutation_id - 1
+        )
+      elsif received_id > last_mutation_id
+        raise OutOfOrderMutationError.new(
+          client_id: client_id,
+          received_id: received_id,
+          expected_id: last_mutation_id
+        )
+      end
+    end
+
+    # Execute mutation with retry logic for app errors
+    def execute_with_retry(mutation_data, context)
+      attempts = 0
+
+      loop do
+        attempts += 1
+
+        begin
+          return schema.execute_mutation(mutation_data, context)
+        rescue ZeroRuby::Error => e
+          raise e unless attempts < max_retries
+        end
+      end
+    end
+
+    # Format an error into Zero protocol response
+    def format_error_response(error)
+      result = {error: error.error_type, message: error.message}
+
+      case error
+      when ValidationError
+        result[:details] = {messages: error.errors}
+      else
+        result[:details] = error.details if error.details
+      end
+
+      result
+    end
+  end
+end

data/lib/zero_ruby/schema.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module ZeroRuby
+  # Schema class for registering and processing Zero mutations.
+  #
+  # @example
+  #   class ZeroSchema < ZeroRuby::Schema
+  #     mutation "works.create", handler: Mutations::WorkCreate
+  #     mutation "works.update", handler: Mutations::WorkUpdate
+  #   end
+  class Schema
+    class << self
+      # Register a mutation handler
+      # @param name [String] The mutation name (e.g., "works.create")
+      # @param handler [Class] The mutation class to handle this mutation
+      def mutation(name, handler:)
+        mutations[name.to_s] = handler
+      end
+
+      # Get all registered mutations
+      def mutations
+        @mutations ||= if superclass.respond_to?(:mutations)
+          superclass.mutations.dup
+        else
+          {}
+        end
+      end
+
+      # Generate TypeScript type definitions from registered mutations
+      # @return [String] TypeScript type definitions
+      def to_typescript
+        TypeScriptGenerator.new(self).generate
+      end
+
+      # Execute a Zero push request. This is the main entry point for processing mutations.
+      #
+      # @param push_data [Hash] The parsed push request body
+      # @param context [Hash] Context hash to pass to mutations (e.g., current_user:)
+      # @param lmid_store [LmidStore, nil] Optional LMID store override
+      # @return [Hash] Result hash: {mutations: [...]} on success, {error: {...}} on failure
+      #
+      # @example Basic usage
+      #   body = JSON.parse(request.body.read)
+      #   result = ZeroSchema.execute(body, context: {current_user: user})
+      #   render json: result
+      def execute(push_data, context:, lmid_store: nil)
+        push_version = push_data["pushVersion"]
+        supported_version = ZeroRuby.configuration.supported_push_version
+
+        unless push_version == supported_version
+          return {
+            error: {
+              kind: "PushFailed",
+              reason: "UnsupportedPushVersion",
+              message: "Unsupported push version: #{push_version}. Expected: #{supported_version}"
+            }
+          }
+        end
+
+        store = lmid_store || ZeroRuby.configuration.lmid_store_instance
+        processor = PushProcessor.new(
+          schema: self,
+          lmid_store: store,
+          max_retries: ZeroRuby.configuration.max_retry_attempts
+        )
+        processor.process(push_data, context)
+      end
+
+      # Execute a single mutation.
+      # Used by PushProcessor for LMID-tracked mutations.
+      # @param mutation_data [Hash] The mutation data from Zero
+      # @param context [Hash] Context hash to pass to mutations
+      # @return [Hash] Empty hash on success
+      # @raise [MutationNotFoundError] If the mutation is not registered
+      # @raise [ZeroRuby::Error] If the mutation fails
+      def execute_mutation(mutation_data, context)
+        name = normalize_mutation_name(mutation_data["name"])
+        raw_args = extract_args(mutation_data)
+        params = transform_keys(raw_args)
+
+        ctx = context.freeze
+        handler = mutations[name]
+
+        raise MutationNotFoundError.new(name) unless handler
+
+        handler.new(params, ctx).call
+      end
+
+      private
+
+      # Normalize mutation name (convert | to . for Zero's format)
+      def normalize_mutation_name(name)
+        return "" if name.nil?
+        name.tr("|", ".")
+      end
+
+      # Extract args from mutation data
+      def extract_args(mutation_data)
+        args = mutation_data["args"]
+        return {} if args.nil?
+
+        # Zero sends args as an array with a single object
+        args.is_a?(Array) ? (args.first || {}) : args
+      end
+
+      # Transform camelCase string keys to snake_case symbols (deep)
+      def transform_keys(object)
+        case object
+        when Hash
+          object.each_with_object({}) do |(key, value), result|
+            new_key = key.to_s.gsub(/([A-Z])/, '_\1').downcase.delete_prefix("_").to_sym
+            result[new_key] = transform_keys(value)
+          end
+        when Array
+          object.map { |e| transform_keys(e) }
+        else
+          object
+        end
+      end
+    end
+  end
+end

data/lib/zero_ruby/type_names.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ZeroRuby
+  # Provides shorthand constants for ZeroRuby types.
+  # Include this module to use ID, Boolean, etc. without the ZeroRuby::Types:: prefix.
+  #
+  # This is automatically included in Mutation and InputObject, so you can write:
+  #
+  #   class PostCreate < ZeroRuby::Mutation
+  #     argument :id, ID, required: true
+  #     argument :title, String, required: true
+  #     argument :active, Boolean, required: true
+  #   end
+  #
+  # Note: String, Integer, and Float work automatically because Ruby's built-in
+  # classes are resolved to ZeroRuby types by the argument system.
+  module TypeNames
+    ID = ZeroRuby::Types::ID
+    Boolean = ZeroRuby::Types::Boolean
+    BigInt = ZeroRuby::Types::BigInt
+    ISO8601Date = ZeroRuby::Types::ISO8601Date
+    ISO8601DateTime = ZeroRuby::Types::ISO8601DateTime
+  end
+end

data/lib/zero_ruby/types/base_type.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ZeroRuby
+  module Types
+    # Base class for all types. Provides the interface for type coercion.
+    class BaseType
+      class << self
+        def name
+          raise NotImplementedError, "Subclasses must implement .name"
+        end
+
+        def coerce_input(value, _ctx = nil)
+          raise NotImplementedError, "Subclasses must implement .coerce_input"
+        end
+
+        def valid?(value)
+          coerce_input(value)
+          true
+        rescue CoercionError
+          false
+        end
+
+        protected
+
+        # Helper to raise CoercionError with consistent formatting
+        # @param value [Object] The invalid value
+        # @param message [String, nil] Custom message (optional)
+        def coercion_error!(value, message = nil)
+          displayed_value = format_value_for_error(value)
+          msg = message || "#{displayed_value} is not a valid #{name}"
+          raise CoercionError.new(msg, value: value, expected_type: name)
+        end
+
+        private
+
+        # Format a value for display in error messages
+        # Truncates long strings and handles various types
+        def format_value_for_error(value)
+          case value
+          when ::String
+            truncated = (value.length > 50) ? "#{value[0, 50]}..." : value
+            "'#{truncated}'"
+          when ::Symbol
+            ":#{value}"
+          when ::NilClass
+            "nil"
+          else
+            value.inspect.then { |s| (s.length > 50) ? "#{s[0, 50]}..." : s }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zero_ruby/types/big_int.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "base_type"
+
+module ZeroRuby
+  module Types
+    # BigInt type for large integers beyond 32-bit range.
+    # Ruby's Integer handles arbitrary precision natively.
+    # Accepts integers and numeric strings, coerces to Integer.
+    class BigInt < BaseType
+      class << self
+        def name
+          "BigInt"
+        end
+
+        def coerce_input(value, _ctx = nil)
+          return nil if value.nil?
+          return value if value.is_a?(::Integer)
+
+          if value.is_a?(::String)
+            coercion_error!(value, "empty string is not a valid #{name}") if value.empty?
+            result = Kernel.Integer(value, exception: false)
+            coercion_error!(value) if result.nil?
+            result
+          else
+            coercion_error!(value, "#{format_value_for_error(value)} (#{value.class}) cannot be coerced to #{name}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zero_ruby/types/boolean.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "base_type"
+
+module ZeroRuby
+  module Types
+    class Boolean < BaseType
+      TRUTHY_VALUES = [true, "true", "1", 1].freeze
+      FALSY_VALUES = [false, "false", "0", 0].freeze
+
+      class << self
+        def name
+          "Boolean"
+        end
+
+        def coerce_input(value, _ctx = nil)
+          return nil if value.nil?
+
+          if TRUTHY_VALUES.include?(value)
+            true
+          elsif FALSY_VALUES.include?(value)
+            false
+          else
+            coercion_error!(value, "#{format_value_for_error(value)} is not a valid #{name}; expected true, false, \"true\", \"false\", 0, or 1")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zero_ruby/types/float.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "base_type"
+
+module ZeroRuby
+  module Types
+    class Float < BaseType
+      class << self
+        def name
+          "Float"
+        end
+
+        def coerce_input(value, _ctx = nil)
+          return nil if value.nil?
+          return value if value.is_a?(::Float)
+
+          if value.is_a?(::Integer)
+            value.to_f
+          elsif value.is_a?(::String)
+            coercion_error!(value, "empty string is not a valid #{name}") if value.empty?
+            result = Kernel.Float(value, exception: false)
+            coercion_error!(value) if result.nil?
+            result
+          else
+            coercion_error!(value, "#{format_value_for_error(value)} (#{value.class}) cannot be coerced to #{name}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zero_ruby/types/id.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "base_type"
+
+module ZeroRuby
+  module Types
+    # ID type for unique identifiers (database PKs, FKs, etc.)
+    # Accepts strings and integers, always coerces to String.
+    class ID < BaseType
+      class << self
+        def name
+          "ID"
+        end
+
+        def coerce_input(value, _ctx = nil)
+          return nil if value.nil?
+
+          case value
+          when ::String
+            coercion_error!(value, "empty string is not a valid #{name}") if value.empty?
+            value
+          when ::Integer
+            value.to_s
+          when ::Symbol
+            value.to_s
+          else
+            coercion_error!(value, "#{format_value_for_error(value)} (#{value.class}) cannot be coerced to #{name}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zero_ruby/types/integer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "base_type"
+
+module ZeroRuby
+  module Types
+    class Integer < BaseType
+      class << self
+        def name
+          "Integer"
+        end
+
+        def coerce_input(value, _ctx = nil)
+          return nil if value.nil?
+          return value if value.is_a?(::Integer)
+
+          if value.is_a?(::String)
+            coercion_error!(value, "empty string is not a valid #{name}") if value.empty?
+            result = Kernel.Integer(value, exception: false)
+            coercion_error!(value) if result.nil?
+            result
+          elsif value.is_a?(::Float)
+            value.to_i
+          else
+            coercion_error!(value, "#{format_value_for_error(value)} (#{value.class}) cannot be coerced to #{name}")
+          end
+        end
+      end
+    end
+  end
+end