zero_ruby 0.1.0.alpha2 → 0.1.0.alpha5

data/lib/zero_ruby/lmid_stores/active_record_store.rb

@@ -55,7 +55,6 @@ module ZeroRuby
       private
 
       def default_model_class
-        require_relative "../zero_client"
         ZeroRuby::ZeroClient
       end
     end

data/lib/zero_ruby/mutation.rb

@@ -1,38 +1,88 @@
 # frozen_string_literal: true
 
-require_relative "argument"
+require_relative "types"
+require_relative "type_names"
 require_relative "errors"
-require_relative "validator"
+require_relative "error_formatter"
 
 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
+  # Base class for Zero mutations.
+  # Provides argument DSL with dry-types validation.
+  #
+  # Includes ZeroRuby::TypeNames for convenient type access via the Types module
+  # (e.g., Types::String, Types::ID, Types::Boolean).
+  #
+  # By default (auto_transact: true), the entire execute method runs inside
+  # a transaction with LMID tracking. For 3-phase control, set auto_transact false.
+  #
+  # @example Simple mutation (auto_transact: true, default)
+  #   class WorkCreate < ZeroRuby::Mutation
+  #     argument :id, Types::ID
+  #     argument :title, Types::String.constrained(max_size: 200)
+  #
+  #     def execute(id:, title:)
+  #       authorize! Work, to: :create?
+  #       Work.create!(id: id, title: title)  # Runs inside auto-wrapped transaction
+  #     end
+  #   end
+  #
+  # @example 3-phase mutation (skip_auto_transaction)
+  #   class WorkUpdate < ZeroRuby::Mutation
+  #     skip_auto_transaction
+  #
+  #     argument :id, Types::ID
+  #     argument :title, Types::String
+  #
+  #     def execute(id:, title:)
+  #       work = Work.find(id)
+  #       authorize! work, to: :update?  # Pre-transaction
+  #
+  #       transact do
+  #         work.update!(title: title)   # Transaction
+  #       end
+  #
+  #       notify_update(work)            # Post-commit
+  #     end
+  #   end
+  class Mutation
+    include ZeroRuby::TypeNames
+
+    # The context hash containing current_user, etc.
+    attr_reader :ctx
+
+    # The validated arguments hash
+    attr_reader :args
+
+    class << self
+      # Opt-out of auto-transaction wrapping.
+      # By default, execute is wrapped in a transaction with LMID tracking.
+      # Call this to use explicit 3-phase model where you must call transact { }.
+      #
+      # @return [void]
+      def skip_auto_transaction
+        @skip_auto_transaction = true
+      end
+
+      # Check if auto-transaction is skipped for this mutation
+      # @return [Boolean] true if skip_auto_transaction was called
+      def skip_auto_transaction?
+        @skip_auto_transaction == true
+      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,
+      # @param type [Dry::Types::Type] The type (from ZeroRuby::Types or dry-types)
+      # @param description [String, nil] Optional description for documentation
+      def argument(name, type, description: nil)
+        arguments[name.to_sym] = {
           type: type,
-          required: required,
-          validates: validates,
-          default: default,
           description: description,
-          **options
-        )
+          name: name.to_sym
+        }
       end
 
       # Get all declared arguments for this mutation (including inherited)
+      # @return [Hash<Symbol, Hash>] Map of argument name to config
       def arguments
         @arguments ||= if superclass.respond_to?(:arguments)
           superclass.arguments.dup
@@ -41,89 +91,141 @@ module ZeroRuby
         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)
+      # Coerce and validate raw arguments.
+      # Collects ALL validation errors (missing fields, type coercion, constraints)
+      # and raises a single ValidationError with all issues.
+      #
+      # Uses type.try(value) which returns a Result instead of raising, allowing
+      # us to collect all errors in one pass rather than failing on the first one.
+      # Works for both Dry::Types (scalars) and Dry::Struct (InputObjects).
+      #
+      # @param raw_args [Hash] Raw input arguments (string keys from JSON)
+      # @return [Hash] Validated and coerced arguments (symbol keys, may contain InputObject instances)
+      # @raise [ZeroRuby::ValidationError] If any validation fails
+      def coerce_and_validate!(raw_args)
+        # Result hash: symbol keys → coerced values (strings, integers, InputObject instances, etc.)
+        # eg:
+        # raw_args:  {"name" => "test", "count" => "5"}  # string keys, raw values
+        # validated: {name: "test", count: 5}            # symbol keys, coerced values
         validated = {}
         errors = []
 
-        arguments.each do |name, arg|
-          value = raw_args[name]
+        arguments.each do |name, config|
+          type = config[:type]
+          str_key = name.to_s
+          key_present = raw_args.key?(str_key)
+          value = raw_args[str_key]
+          is_input_object = input_object_type?(type)
 
-          # Check required
-          if arg.required? && value.nil? && !arg.has_default?
-            errors << "#{name} is required"
+          # Missing key: use default if available, otherwise error if required
+          unless key_present
+            if has_default?(type)
+              validated[name] = get_default(type)
+            elsif required_type?(type)
+              errors << "#{name} is required"
+            end
+            # Optional fields without defaults are simply omitted from result
             next
           end
 
-          # Apply default if needed, or nil for optional args without defaults
+          # Explicit null: InputObjects always allow nil (they handle optionality internally),
+          # scalars only allow nil if the type is optional
           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}"
+            if is_input_object || !required_type?(type)
+              validated[name] = nil
+            else
+              errors << "#{name} is required"
+            end
             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
+          # Coerce value: type.try returns Result instead of raising, so we can
+          # collect all errors. Works for both Dry::Types and Dry::Struct.
+          result = type.try(value)
+          if result.failure?
+            errors << format_type_error(name, result.error, is_input_object)
+          else
+            validated[name] = result.input
           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
+      private
 
-    # The context hash containing current_user, etc.
-    attr_reader :ctx
+      # Check if a type is an InputObject class
+      def input_object_type?(type)
+        type.is_a?(Class) && type < InputObject
+      end
+
+      # Check if a type has a default value
+      def has_default?(type)
+        type.respond_to?(:default?) && type.default?
+      end
+
+      # Get the default value for a type
+      def get_default(type)
+        return nil unless has_default?(type)
+        type[]
+      end
+
+      # Check if a type is required (not optional and not with default)
+      def required_type?(type)
+        return true unless type.respond_to?(:optional?)
+        !type.optional? && !has_default?(type)
+      end
+
+      # Format a type error (coercion or constraint failure)
+      # @param name [Symbol] The field name
+      # @param error [Exception] The error from try.failure
+      # @param is_input_object [Boolean] Whether this is an InputObject type
+      # @return [String] Formatted error message
+      def format_type_error(name, error, is_input_object = false)
+        if is_input_object && error.is_a?(Dry::Struct::Error)
+          # InputObject errors get prefixed with field name
+          ErrorFormatter.format_struct_error(error).map { |m| "#{name}.#{m}" }.first
+        else
+          message = case error
+          when Dry::Types::CoercionError
+            ErrorFormatter.format_coercion_error(error)
+          when Dry::Types::ConstraintError
+            ErrorFormatter.format_constraint_error(error)
+          else
+            error.message
+          end
+          "#{name}: #{message}"
+        end
+      end
+    end
 
     # 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)
+      @args = self.class.coerce_and_validate!(raw_args)
     end
 
     # Execute the mutation
+    # @param transact_proc [Proc] Block that wraps transactional work (internal use)
     # @return [Hash] Empty hash on success, or {data: ...} if execute returns a Hash
     # @raise [ZeroRuby::Error] On failure (formatted at boundary)
-    def call
-      data = execute(**@args)
+    # @raise [ZeroRuby::TransactNotCalledError] If skip_auto_transaction and transact not called
+    def call(&transact_proc)
+      @transact_proc = transact_proc
+      @transact_called = false
+
+      if self.class.skip_auto_transaction?
+        # Manual mode: Use defined mutation calls transact {}
+        data = execute(**@args)
+        raise TransactNotCalledError.new unless @transact_called
+      else
+        # Auto mode: wrap entire execute in transaction
+        data = transact_proc.call { execute(**@args) }
+      end
+
       result = {}
       result[:data] = data if data.is_a?(Hash) && !data.empty?
       result
@@ -131,12 +233,65 @@ module ZeroRuby
 
     private
 
+    # Wrap database operations in a transaction with LMID tracking.
+    # Used by user defined mutation.
+    #
+    # Behavior depends on skip_auto_transaction:
+    # - Default (no skip) - Just executes the block (already in transaction)
+    # - skip_auto_transaction - Wraps block in transaction via transact_proc
+    #
+    # For skip_auto_transaction mutations, you MUST call this method.
+    # For default mutations, calling this is optional (no-op, just runs block).
+    #
+    # @yield Block containing database operations
+    # @return [Object] Result of the block
+    def transact(&block)
+      raise "transact requires a block" unless block_given?
+      @transact_called = true
+
+      if self.class.skip_auto_transaction?
+        # Manual mode - actually call the transact_proc to start transaction
+        @transact_proc.call(&block)
+      else
+        # Auto mode - already in transaction, just execute the block
+        block.call
+      end
+    end
+
+    # Convenience method to access current_user from context.
+    # Override in your ApplicationMutation if you need different behavior.
+    def current_user
+      ctx[:current_user]
+    end
+
     # 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(**)
+    # Arguments are passed as keyword arguments matching your declared arguments.
+    # Access context via ctx[:key] or use the current_user helper.
+    #
+    # By default (auto_transact: true), the entire execute method runs inside
+    # a transaction with LMID tracking. Just write your database operations directly.
+    #
+    # For 3-phase control, use `skip_auto_transaction` and call transact { ... }:
+    # - Pre-transaction: code before transact (auth, validation)
+    # - Transaction: code inside transact { } (database operations)
+    # - Post-commit: code after transact returns (side effects)
+    #
+    # @example Simple mutation (default auto_transact: true)
+    #   def execute(id:, title:)
+    #     authorize! Post, to: :create?
+    #     Post.create!(id: id, title: title)
+    #   end
+    #
+    # @example 3-phase mutation (skip_auto_transaction)
+    #   def execute(id:, title:)
+    #     authorize! Post, to: :create?     # Pre-transaction
+    #     result = transact do
+    #       Post.create!(id: id, title: title)  # Transaction
+    #     end
+    #     NotificationService.notify(result.id)  # Post-commit
+    #     {id: result.id}
+    #   end
+    def execute(**args)
       raise NotImplementedError, "Subclasses must implement #execute"
     end
   end

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
@@ -49,7 +47,7 @@ module ZeroRuby
           message: e.message,
           mutationIDs: unprocessed_ids
         }
-      rescue DatabaseError => e
+      rescue TransactionError => e
         # Database errors trigger top-level PushFailed per Zero protocol
         unprocessed_ids = mutations[index..].map { |m| {id: m["id"], clientID: m["clientID"]} }
         return {
@@ -66,30 +64,66 @@ 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.
+    #
+    # The Mutation#call method decides whether to auto-wrap execute in a transaction
+    # (default behavior) or pass control to user code (skip_auto_transaction mode).
+    #
+    # Phase tracking enables correct LMID semantics:
+    # - 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.
-        last_mutation_id = lmid_store.fetch_and_increment(client_group_id, client_id)
-        check_lmid!(client_id, mutation_id, last_mutation_id)
+      phase = :pre_transaction
 
-        result = execute_with_retry(mutation_data, context)
-        {id: mutation_id_obj, result: result}
-      end
-    rescue OutOfOrderMutationError, DatabaseError
+      transact_proc = proc { |&user_block|
+        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)
+      {id: mutation_id_obj, result: result}
+    rescue MutationNotFoundError, MutationAlreadyProcessedError => e
+      # Known skip conditions - return error response, batch continues
+      {id: mutation_id_obj, result: format_error_response(e)}
+    rescue OutOfOrderMutationError, TransactionError
+      # Batch-terminating errors - bubble up to process() for PushFailed response
       raise
     rescue ZeroRuby::Error => e
+      # Application errors - advance LMID based on phase, return error response
+      # Pre-transaction/transaction: 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
       {id: mutation_id_obj, result: format_error_response(e)}
+    rescue => e
+      # Unexpected errors - wrap and bubble up as batch-terminating
+      raise TransactionError.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.
@@ -113,21 +147,6 @@ 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}

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
@@ -67,8 +75,7 @@ module ZeroRuby
         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
@@ -85,32 +92,45 @@ module ZeroRuby
       # 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
+      # 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
-        unless push_data.key?("clientGroupID")
-          raise ParseError.new("Missing required field: clientGroupID")
+
+        %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
 
@@ -129,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,16 @@
 # 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:
+  # Provides access to ZeroRuby::Types via the Types constant.
+  # Automatically included in Mutation and InputObject classes.
   #
+  # @example Usage in mutations
   #   class PostCreate < ZeroRuby::Mutation
-  #     argument :id, ID, required: true
-  #     argument :title, String, required: true
-  #     argument :active, Boolean, required: true
+  #     argument :id, Types::ID
+  #     argument :title, Types::String
+  #     argument :active, Types::Boolean
   #   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
+    Types = ZeroRuby::Types
   end
 end