zero_ruby 0.1.0.alpha1 → 0.1.0.alpha4

data/lib/zero_ruby/push_processor.rb

@@ -15,15 +15,13 @@ module ZeroRuby
   # @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
+    attr_reader :schema, :lmid_store
 
     # @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)
+    def initialize(schema:, lmid_store:)
       @schema = schema
       @lmid_store = lmid_store
-      @max_retries = max_retries
     end
 
     # Process a Zero push request
@@ -36,12 +34,33 @@ module ZeroRuby
       mutations = push_data["mutations"] || []
       results = []
 
-      mutations.each do |mutation_data|
+      mutations.each_with_index do |mutation_data, index|
         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"
+      rescue MutationNotFoundError => e
+        # Unknown mutation - return error response and continue batch
+        mutation_id_obj = {id: mutation_data["id"], clientID: mutation_data["clientID"]}
+        results << {id: mutation_id_obj, result: format_error_response(e)}
+      rescue OutOfOrderMutationError => e
+        # Return top-level PushFailedBody with all unprocessed mutation IDs
+        unprocessed_ids = mutations[index..].map { |m| {id: m["id"], clientID: m["clientID"]} }
+        return {
+          kind: "PushFailed",
+          origin: "server",
+          reason: "oooMutation",
+          message: e.message,
+          mutationIDs: unprocessed_ids
+        }
+      rescue DatabaseTransactionError => e
+        # Database errors trigger top-level PushFailed per Zero protocol
+        unprocessed_ids = mutations[index..].map { |m| {id: m["id"], clientID: m["clientID"]} }
+        return {
+          kind: "PushFailed",
+          origin: "server",
+          reason: "database",
+          message: e.message,
+          mutationIDs: unprocessed_ids
+        }
       end
 
       {mutations: results}
@@ -49,28 +68,117 @@ module ZeroRuby
 
     private
 
-    # Process a single mutation with LMID validation and transaction support.
-    # Uses atomic increment-then-validate pattern matching Zero's TypeScript implementation.
+    # Process a single mutation with LMID validation, transaction support, and phase tracking.
+    #
+    # Supports two execution modes:
+    #
+    # **Default (auto-transaction)**
+    # - Entire execute method is wrapped in a transaction with LMID tracking
+    # - User does NOT need to call transact {} - it's automatic
+    # - Simple mutations benefit from less boilerplate
+    #
+    # **skip_auto_transaction**
+    # - Uses three-phase model matching Zero's TypeScript implementation:
+    #   1. Pre-transaction: User code runs before calling transact (auth, validation)
+    #   2. Transaction: User code inside transact { } block (database operations, LMID tracking)
+    #   3. Post-commit: User code after transact returns (side effects)
+    # - User MUST call transact {} or TransactNotCalledError is raised
+    #
+    # LMID semantics by phase:
+    # - Pre-transaction error: LMID advanced in separate transaction
+    # - Transaction error: LMID advanced in separate transaction (original tx rolled back)
+    # - Post-commit error: LMID already committed with transaction
     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}
+      mutation_name = mutation_data["name"]
 
-      mutation_id_obj = {
-        id: mutation_id,
-        clientID: client_id
-      }
+      handler_class = schema.handler_for(mutation_name)
+      raise MutationNotFoundError.new(mutation_name) unless handler_class
 
-      lmid_store.transaction do
-        # Atomically increment LMID first, then validate.
-        # This matches the TypeScript implementation's approach for minimal lock duration.
+      if handler_class.skip_auto_transaction?
+        process_manual_transact(mutation_data, client_group_id, client_id, mutation_id, mutation_id_obj, context)
+      else
+        process_auto_transact(mutation_data, client_group_id, client_id, mutation_id, mutation_id_obj, context)
+      end
+    end
+
+    # Process mutation with auto-transact (entire execute wrapped in transaction)
+    def process_auto_transact(mutation_data, client_group_id, client_id, mutation_id, mutation_id_obj, context)
+      result = lmid_store.transaction do
         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}
+        schema.execute_mutation(mutation_data, context)
       end
-    rescue ZeroRuby::Error => e
+      {id: mutation_id_obj, result: result}
+    rescue MutationAlreadyProcessedError => e
       {id: mutation_id_obj, result: format_error_response(e)}
+    rescue OutOfOrderMutationError, DatabaseTransactionError
+      raise
+    rescue ActiveRecord::StatementInvalid => e
+      raise DatabaseTransactionError.new("Transaction failed: #{e.message}")
+    rescue ZeroRuby::Error, FloatDomainError => e
+      # No retry - matches TypeScript behavior (TS does NOT retry user code)
+      # Transaction rolled back - advance LMID separately to prevent replay
+      persist_lmid_on_application_error(client_group_id, client_id)
+      error = e.is_a?(FloatDomainError) ?
+        ValidationError.new(["Invalid numeric value: #{e.message}"]) : e
+      {id: mutation_id_obj, result: format_error_response(error)}
+    rescue => e
+      raise DatabaseTransactionError.new("Transaction failed: #{e.message}")
+    end
+
+    # Process mutation with manual transact (3-phase model)
+    # No retry - matches TypeScript behavior (TS does NOT retry user code)
+    def process_manual_transact(mutation_data, client_group_id, client_id, mutation_id, mutation_id_obj, context)
+      phase = :pre_transaction
+      transact_called = false
+
+      transact_proc = proc { |&user_block|
+        transact_called = true
+        phase = :transaction
+        result = lmid_store.transaction do
+          last_mutation_id = lmid_store.fetch_and_increment(client_group_id, client_id)
+          check_lmid!(client_id, mutation_id, last_mutation_id)
+          user_block.call
+        end
+        phase = :post_commit
+        result
+      }
+
+      result = schema.execute_mutation(mutation_data, context, &transact_proc)
+      raise TransactNotCalledError.new unless transact_called
+      {id: mutation_id_obj, result: result}
+    rescue MutationAlreadyProcessedError => e
+      {id: mutation_id_obj, result: format_error_response(e)}
+    rescue OutOfOrderMutationError, DatabaseTransactionError
+      raise
+    rescue ActiveRecord::StatementInvalid => e
+      raise DatabaseTransactionError.new("Transaction failed: #{e.message}")
+    rescue ZeroRuby::Error, FloatDomainError => e
+      # LMID semantics by phase (no retry - matches TS):
+      # - Pre-transaction: LMID advanced separately
+      # - Transaction (rolled back): LMID advanced separately
+      # - Post-commit: LMID already committed with transaction
+      if phase != :post_commit
+        persist_lmid_on_application_error(client_group_id, client_id)
+      end
+      error = e.is_a?(FloatDomainError) ?
+        ValidationError.new(["Invalid numeric value: #{e.message}"]) : e
+      {id: mutation_id_obj, result: format_error_response(error)}
+    rescue => e
+      raise DatabaseTransactionError.new("Transaction failed: #{e.message}")
+    end
+
+    # Persist LMID advancement after an application error.
+    # Called for pre-transaction and transaction errors to prevent replay attacks.
+    def persist_lmid_on_application_error(client_group_id, client_id)
+      lmid_store.transaction do
+        lmid_store.fetch_and_increment(client_group_id, client_id)
+      end
+    rescue => e
+      warn "Failed to persist LMID after application error: #{e.message}"
     end
 
     # Validate LMID against the post-increment value.
@@ -94,29 +202,18 @@ module ZeroRuby
       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}
+      result = {error: error.error_type}
 
       case error
       when ValidationError
+        result[:message] = error.message
         result[:details] = {messages: error.errors}
+      when MutationAlreadyProcessedError
+        result[:details] = error.message
       else
+        result[:message] = error.message
         result[:details] = error.details if error.details
       end
 

data/lib/zero_ruby/schema.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "error_formatter"
 
 module ZeroRuby
   # Schema class for registering and processing Zero mutations.
@@ -28,6 +29,13 @@ module ZeroRuby
         end
       end
 
+      # Get handler class for a mutation name
+      # @param name [String] The mutation name
+      # @return [Class, nil] The handler class or nil if not found
+      def handler_for(name)
+        mutations[normalize_mutation_name(name)]
+      end
+
       # Generate TypeScript type definitions from registered mutations
       # @return [String] TypeScript type definitions
       def to_typescript
@@ -46,50 +54,86 @@ module ZeroRuby
       #   result = ZeroSchema.execute(body, context: {current_user: user})
       #   render json: result
       def execute(push_data, context:, lmid_store: nil)
+        validate_push_structure!(push_data)
+
         push_version = push_data["pushVersion"]
         supported_version = ZeroRuby.configuration.supported_push_version
 
         unless push_version == supported_version
+          mutations = push_data["mutations"] || []
+          mutation_ids = mutations.map { |m| {id: m["id"], clientID: m["clientID"]} }
+
           return {
-            error: {
-              kind: "PushFailed",
-              reason: "UnsupportedPushVersion",
-              message: "Unsupported push version: #{push_version}. Expected: #{supported_version}"
-            }
+            kind: "PushFailed",
+            origin: "server",
+            reason: "unsupportedPushVersion",
+            message: "Unsupported push version: #{push_version}. Expected: #{supported_version}",
+            mutationIDs: mutation_ids
           }
         end
 
         store = lmid_store || ZeroRuby.configuration.lmid_store_instance
         processor = PushProcessor.new(
           schema: self,
-          lmid_store: store,
-          max_retries: ZeroRuby.configuration.max_retry_attempts
+          lmid_store: store
         )
         processor.process(push_data, context)
+      rescue ParseError => e
+        {
+          kind: "PushFailed",
+          origin: "server",
+          reason: "parse",
+          message: e.message,
+          mutationIDs: []
+        }
       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
+      # @param transact [Proc] Block that wraps transactional work
       # @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)
+      def execute_mutation(mutation_data, context, &transact)
         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
+        raw_args = extract_args(mutation_data)
+        params = transform_keys(raw_args)
+
+        handler.new(params, context).call(&transact)
+      rescue Dry::Struct::Error => e
+        raise ValidationError.new(ErrorFormatter.format_struct_error(e))
+      rescue Dry::Types::CoercionError => e
+        raise ValidationError.new([ErrorFormatter.format_coercion_error(e)])
+      rescue Dry::Types::ConstraintError => e
+        raise ValidationError.new([ErrorFormatter.format_constraint_error(e)])
       end
 
       private
 
+      # Validate push data structure per Zero protocol
+      # Required fields: clientGroupID, mutations, pushVersion, timestamp, requestID
+      # @raise [ParseError] If push data is malformed
+      def validate_push_structure!(push_data)
+        unless push_data.is_a?(Hash)
+          raise ParseError.new("Push data must be a hash")
+        end
+
+        %w[clientGroupID mutations pushVersion timestamp requestID].each do |field|
+          unless push_data.key?(field)
+            raise ParseError.new("Missing required field: #{field}")
+          end
+        end
+
+        unless push_data["mutations"].is_a?(Array)
+          raise ParseError.new("Field 'mutations' must be an array")
+        end
+      end
+
       # Normalize mutation name (convert | to . for Zero's format)
       def normalize_mutation_name(name)
         return "" if name.nil?
@@ -105,12 +149,16 @@ module ZeroRuby
         args.is_a?(Array) ? (args.first || {}) : args
       end
 
-      # Transform camelCase string keys to snake_case symbols (deep)
+      # Transform camelCase string keys to snake_case strings (deep).
+      # Keys are kept as strings to prevent symbol table DoS attacks.
+      # Symbolization happens later in coerce_and_validate! using schema-defined keys.
+      # @param object [Object] The object to transform
+      # @return [Object] Transformed object with string keys
       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
+            new_key = key.to_s.gsub(/([A-Z])/, '_\1').downcase.delete_prefix("_")
             result[new_key] = transform_keys(value)
           end
         when Array

data/lib/zero_ruby/type_names.rb

@@ -1,24 +1,29 @@
 # frozen_string_literal: true
 
+require_relative "types"
+
 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:
-  #
+  # @example Including in your own classes
   #   class PostCreate < ZeroRuby::Mutation
-  #     argument :id, ID, required: true
-  #     argument :title, String, required: true
-  #     argument :active, Boolean, required: true
+  #     include ZeroRuby::TypeNames
+  #
+  #     argument :id, ID
+  #     argument :title, Types::String
+  #     argument :active, Boolean
   #   end
   #
-  # Note: String, Integer, and Float work automatically because Ruby's built-in
-  # classes are resolved to ZeroRuby types by the argument system.
+  # Note: Ruby's built-in String, Integer, and Float cannot be aliased since
+  # they are actual classes. Use ZeroRuby::Types::String, etc. instead.
   module TypeNames
     ID = ZeroRuby::Types::ID
     Boolean = ZeroRuby::Types::Boolean
-    BigInt = ZeroRuby::Types::BigInt
     ISO8601Date = ZeroRuby::Types::ISO8601Date
     ISO8601DateTime = ZeroRuby::Types::ISO8601DateTime
+
+    # Provide Types module access without prefix
+    Types = ZeroRuby::Types
   end
 end

data/lib/zero_ruby/types.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "dry-types"
+
+module ZeroRuby
+  # Type definitions using dry-types.
+  #
+  # When inheriting from ZeroRuby::Mutation or ZeroRuby::InputObject, types are
+  # available via ZeroRuby::TypeNames which is automatically included:
+  #   - Direct: ID, Boolean, ISO8601Date, ISO8601DateTime
+  #   - Via Types: Types::String, Types::Integer, Types::Float
+  #
+  # @example Basic usage
+  #   class MyMutation < ZeroRuby::Mutation
+  #     argument :id, ID
+  #     argument :name, Types::String
+  #     argument :count, Types::Integer.optional
+  #     argument :active, Boolean.default(false)
+  #   end
+  #
+  # @example With constraints
+  #   class MyMutation < ZeroRuby::Mutation
+  #     argument :title, Types::String.constrained(min_size: 1, max_size: 200)
+  #     argument :count, Types::Integer.constrained(gt: 0)
+  #     argument :status, Types::String.constrained(included_in: %w[draft published])
+  #   end
+  module Types
+    include Dry.Types()
+
+    # Params types for JSON input
+    # These handle string coercions common in form/JSON data
+
+    # String type (passes through strings, coerces nil)
+    String = Params::String
+
+    # Coerces string numbers to integers (e.g., "42" -> 42)
+    Integer = Params::Integer
+
+    # Coerces string numbers to floats (e.g., "3.14" -> 3.14)
+    Float = Params::Float
+
+    # Coerces string booleans (e.g., "true" -> true, "false" -> false)
+    Boolean = Params::Bool
+
+    # Non-empty string ID type
+    ID = Params::String.constrained(filled: true)
+
+    # ISO8601 date string -> Date object
+    ISO8601Date = Params::Date
+
+    # ISO8601 datetime string -> DateTime object
+    ISO8601DateTime = Params::DateTime
+  end
+end