zero_ruby 0.1.0.alpha5 → 0.1.0.alpha6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68451ec0c319aab33578ee4ac8aa28f61426ade64f4185047528387c5c95f3e5
-  data.tar.gz: fc5b90718c5c0aa5ee11020b02e01d422cee0108bb1095c9aac8eb184dd6c050
+  metadata.gz: d3eab5f6867bccc496d6bb976fd8d6494c05888f085b53c7c92a62ff6cfcf1a8
+  data.tar.gz: dc879e22f7adf86659842f72763ef5ce4fea593a446116f185d4e5c9a72636c8
 SHA512:
-  metadata.gz: b60c2a285735db948bf33ebd52f78fc09329ed3c0a012cc000dab2eda668bf37920058dd4444317ff8bde80fcf70713014ed24186037fdf6b9acf35f32f3dc6b
-  data.tar.gz: bb7c53048a48d3c65c0303be1d67bf59368e3a2eec7ae8ce482c50e94304a8295be05ffb062e4591162a5d2cfb53f66d322b807e9c9c26c0039ec5ac3967e5d9
+  metadata.gz: e3c49d57a02dafcd912302ac4205a1a168a52711c6cf33f0ec078867b244ce1f0afca16887bf2da6a65a911efdd3ecbd11ccef526e614dc03062a209ded8e847
+  data.tar.gz: 44cfd5b1bc95f58f12de4b24803bdb7f1cf4dc38d85470553c86d5e6f79c4c3271072b83a774ace776282a16982ba068554211c18fb21d68e24c8415ba2166fa

data/README.md

@@ -1,6 +1,6 @@
 # zero_ruby
 
-A Ruby gem for handling [Zero](https://zero.rocicorp.dev/) mutations with type safety, validation, and full protocol support.
+A Ruby gem for handling [Zero](https://zero.rocicorp.dev/) mutations with type safety, validation, and full protocol support. Compatible with Zero 0.25.12.
 
 ## Features
 

data/lib/zero_ruby/lmid_store.rb

@@ -39,5 +39,25 @@ module ZeroRuby
     def transaction(&block)
       raise NotImplementedError, "#{self.class}#transaction must be implemented"
     end
+
+    # Persist a mutation result so clients can read it via replication.
+    # Used to surface error results back to the client.
+    #
+    # @param client_group_id [String] The client group ID
+    # @param client_id [String] The client ID
+    # @param mutation_id [Integer] The mutation ID
+    # @param result [Hash, String] The mutation result to persist
+    def write_mutation_result(client_group_id, client_id, mutation_id, result)
+      raise NotImplementedError, "#{self.class}#write_mutation_result must be implemented"
+    end
+
+    # Delete mutation results, called by _zero_cleanupResults to remove acknowledged results.
+    #
+    # @param args [Hash] Cleanup arguments from the _zero_cleanupResults mutation.
+    #   For single/legacy format: { "clientGroupID" => String, "clientID" => String, "upToMutationID" => Integer }
+    #   For bulk format: { "type" => "bulk", "clientGroupID" => String, "clientIDs" => Array<String> }
+    def delete_mutation_results(args)
+      raise NotImplementedError, "#{self.class}#delete_mutation_results must be implemented"
+    end
   end
 end

data/lib/zero_ruby/lmid_stores/active_record_store.rb

@@ -52,6 +52,53 @@ module ZeroRuby
         model_class.transaction(&block)
       end
 
+      # Write a mutation result to the zero_0.mutations table.
+      #
+      # @param client_group_id [String] The client group ID
+      # @param client_id [String] The client ID
+      # @param mutation_id [Integer] The mutation ID
+      # @param result [Hash, String] The mutation result. Hashes are serialized to JSON for storage.
+      def write_mutation_result(client_group_id, client_id, mutation_id, result)
+        result_json = begin
+          result.is_a?(String) ? result : result.to_json
+        rescue JSON::GeneratorError, Encoding::UndefinedConversionError
+          {error: "app", message: "Error result could not be serialized"}.to_json
+        end
+        sql = model_class.sanitize_sql_array([<<~SQL.squish, {client_group_id:, client_id:, mutation_id:, result: result_json}])
+          INSERT INTO zero_0.mutations ("clientGroupID", "clientID", "mutationID", "result")
+          VALUES (:client_group_id, :client_id, :mutation_id, :result::text::json)
+        SQL
+
+        model_class.connection.execute(sql)
+      end
+
+      # Delete mutation results from the zero_0.mutations table.
+      #
+      # @param args [Hash] Cleanup arguments
+      def delete_mutation_results(args)
+        client_group_id = args["clientGroupID"]
+
+        sql = if args["type"] == "bulk"
+          client_ids = args["clientIDs"]
+          model_class.sanitize_sql_array([<<~SQL.squish, {client_group_id:}])
+            DELETE FROM zero_0.mutations
+            WHERE "clientGroupID" = :client_group_id
+            AND "clientID" = ANY(ARRAY[#{client_ids.map { |id| model_class.connection.quote(id) }.join(",")}])
+          SQL
+        else
+          client_id = args["clientID"]
+          up_to_mutation_id = args["upToMutationID"]
+          model_class.sanitize_sql_array([<<~SQL.squish, {client_group_id:, client_id:, up_to_mutation_id:}])
+            DELETE FROM zero_0.mutations
+            WHERE "clientGroupID" = :client_group_id
+            AND "clientID" = :client_id
+            AND "mutationID" <= :up_to_mutation_id
+          SQL
+        end
+
+        model_class.connection.execute(sql)
+      end
+
       private
 
       def default_model_class

data/lib/zero_ruby/push_processor.rb

@@ -35,6 +35,11 @@ module ZeroRuby
       results = []
 
       mutations.each_with_index do |mutation_data, index|
+        if mutation_data["name"] == "_zero_cleanupResults"
+          handle_cleanup_results(mutation_data)
+          next
+        end
+
         result = process_mutation_with_lmid(mutation_data, client_group_id, context)
         results << result
       rescue OutOfOrderMutationError => e
@@ -89,7 +94,13 @@ module ZeroRuby
         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
+          begin
+            user_block.call
+          rescue ZeroRuby::Error
+            raise
+          rescue => e
+            raise ZeroRuby::Error.new(e.message)
+          end
         end
         phase = :post_commit
         result
@@ -107,23 +118,55 @@ module ZeroRuby
       # Application errors - advance LMID based on phase, return error response
       # Pre-transaction/transaction: LMID advanced separately
       # Post-commit: LMID already committed with transaction
+      error_response = format_error_response(e)
       if phase != :post_commit
-        persist_lmid_on_application_error(client_group_id, client_id)
+        persist_mutation_failure(client_group_id, client_id, mutation_id, error_response)
       end
-      {id: mutation_id_obj, result: format_error_response(e)}
+      {id: mutation_id_obj, result: error_response}
     rescue => e
-      # Unexpected errors - wrap and bubble up as batch-terminating
-      raise TransactionError.new("Transaction failed: #{e.message}")
+      if phase == :transaction
+        # Infrastructure error (user code errors already wrapped by transact_proc)
+        raise TransactionError.new("Transaction failed: #{e.message}")
+      else
+        # User code error in pre-transaction or post-commit phase
+        error_response = {error: "app", message: e.message}
+        if phase != :post_commit
+          persist_mutation_failure(client_group_id, client_id, mutation_id, error_response)
+        end
+        {id: mutation_id_obj, result: error_response}
+      end
     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)
+    # Persist LMID advancement and mutation error result after a failure.
+    # Advances the LMID so the failed mutation is not re-executed on retry,
+    # and writes the error result so clients can read it via replication.
+    def persist_mutation_failure(client_group_id, client_id, mutation_id, error_result)
       lmid_store.transaction do
         lmid_store.fetch_and_increment(client_group_id, client_id)
+        lmid_store.write_mutation_result(client_group_id, client_id, mutation_id, error_result)
+      end
+    rescue => e
+      warn "[ZeroRuby] Failed to persist mutation failure for " \
+           "client_group=#{client_group_id} client=#{client_id} mutation=#{mutation_id}: " \
+           "#{e.class}: #{e.message}"
+    end
+
+    # Handle _zero_cleanupResults mutations by deleting acknowledged results.
+    # Errors are caught and logged as warnings without propagating, matching
+    # the Zero protocol behavior where cleanup failures must not abort the push batch.
+    def handle_cleanup_results(mutation_data)
+      args = mutation_data["args"]
+      args = args.first if args.is_a?(Array)
+      unless args.is_a?(Hash) && args["clientGroupID"]
+        warn "[ZeroRuby] _zero_cleanupResults: invalid args: #{args.inspect}"
+        return
+      end
+      lmid_store.transaction do
+        lmid_store.delete_mutation_results(args)
       end
     rescue => e
-      warn "Failed to persist LMID after application error: #{e.message}"
+      warn "[ZeroRuby] _zero_cleanupResults failed for " \
+           "clientGroupID=#{args&.dig("clientGroupID")}: #{e.class}: #{e.message}"
     end
 
     # Validate LMID against the post-increment value.

data/lib/zero_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZeroRuby
-  VERSION = "0.1.0.alpha5"
+  VERSION = "0.1.0.alpha6"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: zero_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha5
+  version: 0.1.0.alpha6
 platform: ruby
 authors:
 - Alex Serban
 bindir: bin
 cert_chain: []
-date: 2026-01-01 00:00:00.000000000 Z
+date: 2026-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-struct