zero_ruby 0.1.0.alpha1 → 0.1.0.alpha2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba93bb14b442ea97c4ac597b0c97e7b9e0ec00a334e5f2fd6bb3ee7639d47302
-  data.tar.gz: 741f8f22deb20a49cf7ffd75a03657faf28d561ad32a03debb74f4f5b4e41de8
+  metadata.gz: 9d8baa0973deb010422a2e5d6679af4580b9c37666b2649f383c0bf6525a77c9
+  data.tar.gz: 27e0a5593d3344c6260d96838e94ce94a8af36225b861318091ed57532a92dda
 SHA512:
-  metadata.gz: bab7af54647503b8322eef911336dd9abfe952eaa574baa7f61da57e72e234754a03287354f24af6022b15731097c43a51b5ba67ecb441d0dcc148de834b7b2d
-  data.tar.gz: 9a4015f062da3df3cdfbc32fc00f747046dee0a30d03228995b59049b9ce2a44c0df10836db173f906ceb8aebd76d935a116576d74848187c88470b7aeb3c4bd
+  metadata.gz: 83b6256cf6db475ad7f6c5de6d958f6ed72627dd2d2ae5211183d2ed2fe2c346338fbda6cb52ca79aa7aaf7c343e342e017b4015004cba3c97d351da80b679de
+  data.tar.gz: 694ac953e5df97e3a747054846612923928d24eb3a184d5f53c999895419f2ba3885fb128034c8bd54b934c976e832d8cf58fb5a7469c8ace7e75f91185266c4

data/README.md

@@ -22,41 +22,8 @@ gem 'zero_ruby'
 
 ## Usage
 
-### 1. Base classes (optional)
 
-Create base classes to share behavior across mutations and input types:
-
-```ruby
-# app/zero/types/base_input_object.rb
-module Types
-  class BaseInputObject < ZeroRuby::InputObject
-    # Add shared behavior across all input objects here
-  end
-end
-
-# app/zero/mutations/application_mutation.rb
-class ApplicationMutation < ZeroRuby::Mutation
-  def current_user
-    ctx[:current_user]
-  end
-end
-```
-
-### 2. Define custom input types (optional)
-
-```ruby
-# app/zero/types/post_input.rb
-module Types
-  class PostInput < Types::BaseInputObject
-    argument :title, String, required: true,
-      validates: { length: { minimum: 1, maximum: 200 } }
-    argument :body, String, required: false
-    argument :published, Boolean, required: false, default: false
-  end
-end
-```
-
-### 3. Define mutations
+### 1. Define mutations
 
 ```ruby
 # app/zero/mutations/post_update.rb
@@ -73,7 +40,7 @@ module Mutations
 end
 ```
 
-### 4. Register mutations in schema
+### 2. Register mutations in schema
 
 ```ruby
 # app/zero/app_schema.rb
@@ -85,7 +52,7 @@ class ZeroSchema < ZeroRuby::Schema
 end
 ```
 
-### 5. Add controller
+### 3. Add zero_controller and route
 
 ```ruby
 # app/controllers/zero_controller.rb
@@ -112,23 +79,55 @@ class ZeroController < ApplicationController
     end
   rescue JSON::ParserError => e
     render json: {
-      error: {
-        kind: "PushFailed",
-        reason: "Parse",
-        message: "Invalid JSON: #{e.message}"
-      }
+      kind: "PushFailed",
+      origin: "server",
+      reason: "parse",
+      message: "Invalid JSON: #{e.message}",
+      mutationIDs: []
     }, status: :bad_request
   end
 end
 ```
 
-### 6. Add route
-
 ```ruby
 # config/routes.rb
 match '/zero/push', to: 'zero#push', via: [:get, :post]
 ```
 
+## Base classes (optional)
+
+Create base classes to share behavior across mutations and input types:
+
+```ruby
+# app/zero/types/base_input_object.rb
+module Types
+  class BaseInputObject < ZeroRuby::InputObject
+    # Add shared behavior across all input objects here
+  end
+end
+
+# app/zero/mutations/application_mutation.rb
+class ApplicationMutation < ZeroRuby::Mutation
+  def current_user
+    ctx[:current_user]
+  end
+end
+```
+
+## Define custom input types (optional)
+
+```ruby
+# app/zero/types/post_input.rb
+module Types
+  class PostInput < Types::BaseInputObject
+    argument :title, String, required: true,
+      validates: { length: { minimum: 1, maximum: 200 } }
+    argument :body, String, required: false
+    argument :published, Boolean, required: false, default: false
+  end
+end
+```
+
 ## Configuration
 
 Create an initializer to customize settings (all options have sensible defaults):
@@ -179,7 +178,7 @@ export const mutators = defineMutators({
     update: defineMutator(postsUpdateArgsSchema, async ({ tx, args }) => {
       await tx.mutate.posts.update({
         id: args.id,
-        ...(args.postInput.title !== undefined && { title: args.postInput.title }),
+        title: args.postInput.title,
         updatedAt: Date.now(),
       })
     }),
@@ -191,8 +190,6 @@ export type Mutators = typeof mutators
 
 ## Validation
 
-Built-in validators:
-
 ```ruby
 argument :name, String, required: true,
   validates: {

data/lib/zero_ruby/errors.rb

@@ -87,4 +87,19 @@ module ZeroRuby
       "ooo"
     end
   end
+
+  # Raised for database transaction errors.
+  # Triggers top-level PushFailed with reason: "database"
+  class DatabaseError < Error
+  end
+
+  # Raised when push data is malformed or missing required fields.
+  # Triggers top-level PushFailed with reason: "parse"
+  class ParseError < Error
+  end
+
+  # Raised for unexpected internal server errors.
+  # Wrapped as app error per Zero protocol (no "internal" error type at mutation level)
+  class InternalError < Error
+  end
 end

data/lib/zero_ruby/mutation.rb

@@ -120,11 +120,13 @@ module ZeroRuby
     end
 
     # Execute the mutation
-    # @return [Hash] Empty hash on success
+    # @return [Hash] Empty hash on success, or {data: ...} if execute returns a Hash
     # @raise [ZeroRuby::Error] On failure (formatted at boundary)
     def call
-      execute(**@args)
-      {}
+      data = execute(**@args)
+      result = {}
+      result[:data] = data if data.is_a?(Hash) && !data.empty?
+      result
     end
 
     private

data/lib/zero_ruby/push_processor.rb

@@ -36,12 +36,29 @@ 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 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 DatabaseError => 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}
@@ -69,6 +86,8 @@ module ZeroRuby
         result = execute_with_retry(mutation_data, context)
         {id: mutation_id_obj, result: result}
       end
+    rescue OutOfOrderMutationError, DatabaseError
+      raise
     rescue ZeroRuby::Error => e
       {id: mutation_id_obj, result: format_error_response(e)}
     end
@@ -111,12 +130,16 @@ module ZeroRuby
 
     # 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

@@ -46,16 +46,21 @@ 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
 
@@ -66,6 +71,14 @@ module ZeroRuby
           max_retries: ZeroRuby.configuration.max_retry_attempts
         )
         processor.process(push_data, context)
+      rescue ParseError => e
+        {
+          kind: "PushFailed",
+          origin: "server",
+          reason: "parse",
+          message: e.message,
+          mutationIDs: []
+        }
       end
 
       # Execute a single mutation.
@@ -90,6 +103,17 @@ module ZeroRuby
 
       private
 
+      # Validate push data structure
+      # @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")
+        end
+      end
+
       # Normalize mutation name (convert | to . for Zero's format)
       def normalize_mutation_name(name)
         return "" if name.nil?

data/lib/zero_ruby/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: zero_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha1
+  version: 0.1.0.alpha2
 platform: ruby
 authors:
 - Alex Serban
 bindir: bin
 cert_chain: []
-date: 2025-12-20 00:00:00.000000000 Z
+date: 2025-12-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -79,7 +79,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.51'
-description: Handle Zero mutations with runtime type safety
+description: Handle Zero mutations
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -141,5 +141,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: Ruby gem for handling Zero mutations with type safety
+summary: Ruby gem for handling Zero mutations
 test_files: []