zero_ruby 0.1.0.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba93bb14b442ea97c4ac597b0c97e7b9e0ec00a334e5f2fd6bb3ee7639d47302
+  data.tar.gz: 741f8f22deb20a49cf7ffd75a03657faf28d561ad32a03debb74f4f5b4e41de8
+SHA512:
+  metadata.gz: bab7af54647503b8322eef911336dd9abfe952eaa574baa7f61da57e72e234754a03287354f24af6022b15731097c43a51b5ba67ecb441d0dcc148de834b7b2d
+  data.tar.gz: 9a4015f062da3df3cdfbc32fc00f747046dee0a30d03228995b59049b9ce2a44c0df10836db173f906ceb8aebd76d935a116576d74848187c88470b7aeb3c4bd

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alex Serban
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,245 @@
+# zero_ruby
+
+A Ruby gem for handling [Zero](https://zero.rocicorp.dev/) mutations with type safety, validation, and full protocol support.
+
+0.1.0.alpha1
+
+## Features
+
+- **Type coercion & checking** - String, Integer, Float, Boolean, ID, BigInt, ISO8601Date, ISO8601DateTime with automatic conversion and runtime type validation
+- **Type generation** - Generates typescript types you can use for your frontend mutators
+- **Argument validation** - length, numericality, format, inclusion, exclusion, etc.
+- **LMID tracking** - Duplicate and out-of-order mutation detection using Zero's `zero_0.clients` table
+- **Push protocol** - Version validation, transaction wrapping, retry logic
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+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
+
+```ruby
+# app/zero/mutations/post_update.rb
+module Mutations
+  class PostUpdate < ApplicationMutation
+    argument :id, ID, required: true
+    argument :post_input, Types::PostInput, required: true
+
+    def execute(id:, post_input:)
+      post = current_user.posts.find(id)
+      post.update!(**post_input)
+    end
+  end
+end
+```
+
+### 4. Register mutations in schema
+
+```ruby
+# app/zero/app_schema.rb
+# The mutation names should match the names used in your Zero client:
+#   mutators.posts.update({ id: "...", post_input: { title: "..." } })
+#   -> maps to "posts.update"
+class ZeroSchema < ZeroRuby::Schema
+  mutation "posts.update", handler: Mutations::PostUpdate
+end
+```
+
+### 5. Add controller
+
+```ruby
+# app/controllers/zero_controller.rb
+class ZeroController < ApplicationController
+  # Skip CSRF for API endpoint
+  # skip_before_action :verify_authenticity_token
+
+  def push
+    if request.get?
+      # GET requests return TypeScript type definitions
+      render plain: ZeroSchema.to_typescript, content_type: "text/plain; charset=utf-8"
+    else
+      # POST requests process mutations
+      body = JSON.parse(request.body.read)
+
+      # Build context hash with whatever your mutations need.
+      # Access in mutations via ctx[:current_user]
+      context = {
+        current_user: current_user,
+      }
+
+      result = ZeroSchema.execute(body, context: context)
+      render json: result
+    end
+  rescue JSON::ParserError => e
+    render json: {
+      error: {
+        kind: "PushFailed",
+        reason: "Parse",
+        message: "Invalid JSON: #{e.message}"
+      }
+    }, status: :bad_request
+  end
+end
+```
+
+### 6. Add route
+
+```ruby
+# config/routes.rb
+match '/zero/push', to: 'zero#push', via: [:get, :post]
+```
+
+## Configuration
+
+Create an initializer to customize settings (all options have sensible defaults):
+
+```ruby
+# config/initializers/zero_ruby.rb
+ZeroRuby.configure do |config|
+  # Storage backend (:active_record is the only built-in option)
+  config.lmid_store = :active_record
+
+  # Retry attempts for transient errors
+  config.max_retry_attempts = 3
+
+  # Push protocol version (reject requests with different version)
+  config.supported_push_version = 1
+end
+```
+
+## TypeScript type generation
+
+ZeroRuby generates TypeScript type definitions from your Ruby mutations. GET requests to `/zero/push` return the types.
+
+### Setup
+
+- Set `ZERO_TYPES_URL` env var to your host `http://example.com/zero/push`
+- `npm install ts-to-zod --save-dev`
+- Add the following script to generate types and zod schemas
+
+```json
+{
+  "scripts": {
+    "zero:types": "mkdir -p lib/zero/__generated__ && curl -s $ZERO_TYPES_URL/zero/push > lib/zero/__generated__/zero-types.ts && npx ts-to-zod lib/zero/__generated__/zero-types.ts lib/zero/__generated__/zero-schemas.ts"
+  }
+}
+```
+
+### Using with Zero Mutators
+
+```typescript
+import { defineMutator, defineMutators } from '@rocicorp/zero'
+import {
+  postsCreateArgsSchema,
+  postsUpdateArgsSchema,
+} from './zero/__generated__/zero-schemas'
+
+export const mutators = defineMutators({
+  posts: {
+    update: defineMutator(postsUpdateArgsSchema, async ({ tx, args }) => {
+      await tx.mutate.posts.update({
+        id: args.id,
+        ...(args.postInput.title !== undefined && { title: args.postInput.title }),
+        updatedAt: Date.now(),
+      })
+    }),
+  },
+})
+
+export type Mutators = typeof mutators
+```
+
+## Validation
+
+Built-in validators:
+
+```ruby
+argument :name, String, required: true,
+  validates: {
+    length: { minimum: 1, maximum: 100 },
+    format: { with: /\A[a-z]+\z/i, message: "only letters allowed" },
+    allow_blank: false
+  }
+
+argument :age, Integer, required: true,
+  validates: {
+    numericality: { greater_than: 0, less_than: 150 }
+  }
+
+argument :status, String, required: true,
+  validates: {
+    inclusion: { in: %w[draft published archived] }
+  }
+
+argument :username, String, required: true,
+  validates: {
+    exclusion: { in: %w[admin root system], message: "is reserved" }
+  }
+
+argument :email, String, required: true,
+  validates: {
+    allow_null: false,
+    allow_blank: false
+  }
+```
+
+## Type coercion & checking
+
+Types automatically coerce compatible values and raise `CoercionError` for invalid input:
+
+| Type | Accepts | Rejects |
+|------|---------|---------|
+| `String` | Any value (via `.to_s`) | - |
+| `Integer` | `42`, `"42"`, `3.7` → `3` | `"abc"`, `""`, arrays, hashes |
+| `Float` | `3.14`, `"3.14"`, `42` → `42.0` | `"abc"`, `""`, arrays, hashes |
+| `Boolean` | `true`, `false`, `"true"`, `"false"`, `0`, `1` | `"yes"`, `"maybe"`, other values |
+| `ID` | `"abc"`, `123` → `"123"`, `:sym` → `"sym"` | `""`, arrays, hashes |
+| `BigInt` | `123`, `"9007199254740993"` | `"abc"`, `""`, floats |
+| `ISO8601Date` | `"2025-01-15"`, `Date`, `Time` → `Date` | `"invalid"`, `""`, integers |
+| `ISO8601DateTime` | `"2025-01-15T10:30:00Z"`, `Time`, `DateTime` | `"invalid"`, `""`, integers |
+
+## References
+
+- [Zero Documentation](https://zero.rocicorp.dev/docs/mutators)
+- [Zero Server Implementation](https://github.com/rocicorp/mono/blob/main/packages/zero-server/src/process-mutations.ts)
+- Inspired by [graphql-ruby](https://github.com/rmosolgo/graphql-ruby)

data/lib/zero_ruby/argument.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module ZeroRuby
+  # Represents a declared argument for a mutation.
+  # Holds type, required status, and validation configuration.
+  class Argument
+    # Sentinel value to distinguish "no default provided" from "default is nil"
+    NOT_PROVIDED = Object.new.freeze
+
+    # Maps Ruby built-in classes to ZeroRuby types.
+    # This allows using String, Integer, Float directly in argument declarations.
+    RUBY_TYPE_MAP = {
+      ::String => -> { ZeroRuby::Types::String },
+      ::Integer => -> { ZeroRuby::Types::Integer },
+      ::Float => -> { ZeroRuby::Types::Float }
+    }.freeze
+
+    attr_reader :name, :type, :required, :validators, :default, :description
+
+    def initialize(name:, type:, required: true, validates: nil, default: NOT_PROVIDED, description: nil, **options)
+      @name = name.to_sym
+      @type = resolve_type(type)
+      @required = required
+      @validators = validates || {}
+      @has_default = default != NOT_PROVIDED
+      @default = @has_default ? default : nil
+      @description = description
+      @options = options
+    end
+
+    def required?
+      @required
+    end
+
+    def optional?
+      !@required
+    end
+
+    def has_default?
+      @has_default
+    end
+
+    # Coerce and validate a raw input value
+    # @param raw_value [Object] The raw input value
+    # @param ctx [Hash] The context hash
+    # @return [Object] The coerced value
+    def coerce(raw_value, ctx = nil)
+      value = (raw_value.nil? && has_default?) ? @default : raw_value
+
+      # Handle InputObject types (they use .coerce instead of .coerce_input)
+      if input_object_type?
+        @type.coerce(value, ctx)
+      else
+        @type.coerce_input(value, ctx)
+      end
+    end
+
+    private
+
+    # Resolve a type reference to a ZeroRuby type.
+    # Handles Ruby built-in classes (String, Integer, Float) by mapping them
+    # to the corresponding ZeroRuby::Types class.
+    def resolve_type(type)
+      if RUBY_TYPE_MAP.key?(type)
+        RUBY_TYPE_MAP[type].call
+      else
+        type
+      end
+    end
+
+    def input_object_type?
+      defined?(ZeroRuby::InputObject) && @type.is_a?(Class) && @type < ZeroRuby::InputObject
+    end
+  end
+end

data/lib/zero_ruby/configuration.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ZeroRuby
+  # Configuration class for ZeroRuby.
+  #
+  # @example
+  #   ZeroRuby.configure do |config|
+  #     config.lmid_store = :active_record
+  #     config.max_retry_attempts = 3
+  #   end
+  class Configuration
+    # LMID (Last Mutation ID) tracking settings
+    # The LMID store backend: :active_record or a custom LmidStore instance
+    attr_accessor :lmid_store
+
+    # Maximum retry attempts for ApplicationError during mutation processing
+    attr_accessor :max_retry_attempts
+
+    # The push version supported by this configuration
+    attr_accessor :supported_push_version
+
+    def initialize
+      @lmid_store = :active_record
+      @max_retry_attempts = 3
+      @supported_push_version = 1
+    end
+
+    # Get the configured LMID store instance
+    # @return [LmidStore] The LMID store instance
+    def lmid_store_instance
+      case @lmid_store
+      when :active_record
+        LmidStores::ActiveRecordStore.new
+      when LmidStore
+        @lmid_store
+      else
+        raise ArgumentError, "Unknown LMID store: #{@lmid_store.inspect}. Use :active_record or pass a custom LmidStore instance."
+      end
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/zero_ruby/errors.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ZeroRuby
+  class Error < StandardError
+    attr_reader :details
+
+    def initialize(message = nil, details: nil)
+      @details = details
+      super(message)
+    end
+
+    # Returns the Zero protocol error type string
+    def error_type
+      "app"
+    end
+  end
+
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = Array(errors)
+      super(@errors.join(", "))
+    end
+  end
+
+  # Raised when a value cannot be coerced to the expected type
+  class CoercionError < Error
+    attr_reader :value, :expected_type
+
+    def initialize(message, value: nil, expected_type: nil)
+      @value = value
+      @expected_type = expected_type
+      super(message)
+    end
+  end
+
+  # Raised when a mutation is not found in the schema
+  class MutationNotFoundError < Error
+    attr_reader :mutation_name
+
+    def initialize(mutation_name)
+      @mutation_name = mutation_name
+      super("Unknown mutation: #{mutation_name}")
+    end
+  end
+
+  # Raised when pushVersion is not supported
+  class UnsupportedPushVersionError < Error
+    attr_reader :received_version, :supported_version
+
+    def initialize(received_version, supported_version: 1)
+      @received_version = received_version
+      @supported_version = supported_version
+      super("Unsupported push version: #{received_version}. Expected: #{supported_version}")
+    end
+  end
+
+  # Raised when a mutation has already been processed (duplicate)
+  class MutationAlreadyProcessedError < Error
+    attr_reader :client_id, :received_id, :last_mutation_id
+
+    def initialize(client_id:, received_id:, last_mutation_id:)
+      @client_id = client_id
+      @received_id = received_id
+      @last_mutation_id = last_mutation_id
+      super("Mutation #{received_id} already processed for client #{client_id}. Last mutation ID: #{last_mutation_id}")
+    end
+
+    def error_type
+      "alreadyProcessed"
+    end
+  end
+
+  # Raised when mutations arrive out of order
+  class OutOfOrderMutationError < Error
+    attr_reader :client_id, :received_id, :expected_id
+
+    def initialize(client_id:, received_id:, expected_id:)
+      @client_id = client_id
+      @received_id = received_id
+      @expected_id = expected_id
+      super("Client #{client_id} sent mutation ID #{received_id} but expected #{expected_id}")
+    end
+
+    def error_type
+      "ooo"
+    end
+  end
+end

data/lib/zero_ruby/input_object.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "argument"
+require_relative "errors"
+require_relative "validator"
+
+module ZeroRuby
+  # Base class for input objects (nested argument types).
+  # Similar to GraphQL-Ruby's InputObject pattern.
+  #
+  # @example
+  #   class Types::PostInput < ZeroRuby::InputObject
+  #     argument :id, ID, required: true
+  #     argument :title, String, required: true
+  #     argument :body, String, required: false
+  #   end
+  #
+  #   class PostCreate < ZeroRuby::Mutation
+  #     argument :post_input, Types::PostInput, required: true
+  #     argument :notify, Boolean, required: false
+  #
+  #     def execute(post_input:, notify: nil)
+  #       Post.create!(**post_input)
+  #     end
+  #   end
+  class InputObject
+    include TypeNames
+
+    class << self
+      # Declare an argument for this input object
+      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 (including inherited)
+      def arguments
+        @arguments ||= if superclass.respond_to?(:arguments)
+          superclass.arguments.dup
+        else
+          {}
+        end
+      end
+
+      # Coerce and validate raw input
+      # @param raw_args [Hash] Raw input
+      # @param ctx [Hash] The context hash
+      # @return [Hash] Validated and coerced hash (only includes keys present in input or with defaults)
+      # @raise [ZeroRuby::ValidationError] If validation fails
+      def coerce(value, ctx)
+        return nil if value.nil?
+        return nil unless value.is_a?(Hash)
+
+        validated = {}
+        errors = []
+
+        arguments.each do |name, arg|
+          key_present = value.key?(name) || value.key?(name.to_s)
+          val = if key_present
+            value[name].nil? ? value[name.to_s] : value[name]
+          end
+
+          # Check required
+          if arg.required? && !key_present && !arg.has_default?
+            errors << "#{name} is required"
+            next
+          end
+
+          # Apply default if key not present
+          if !key_present && arg.has_default?
+            validated[name] = arg.default
+            next
+          end
+
+          # Skip if key not present (don't add to validated hash)
+          next unless key_present
+
+          # Handle nil values - include in hash but skip coercion
+          if val.nil?
+            validated[name] = nil
+            next
+          end
+
+          # Type coercion (handles nested InputObjects)
+          begin
+            coerced = arg.coerce(val, ctx)
+          rescue CoercionError => e
+            errors << "#{name}: #{e.message}"
+            next
+          rescue ValidationError => e
+            # Nested InputObject validation errors - prefix with field name
+            e.errors.each do |err|
+              errors << "#{name}.#{err}"
+            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
+          end
+
+          validated[name] = coerced
+        end
+
+        raise ValidationError.new(errors) if errors.any?
+        validated
+      end
+    end
+  end
+end

data/lib/zero_ruby/lmid_store.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ZeroRuby
+  # Abstract base class for LMID (Last Mutation ID) storage backends.
+  # Implementations must provide thread-safe access to client mutation IDs.
+  #
+  # This follows 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 Custom store implementation
+  #   class RedisLmidStore < ZeroRuby::LmidStore
+  #     def fetch_and_increment(client_group_id, client_id)
+  #       # Atomically increment and return the new last mutation ID
+  #     end
+  #
+  #     def transaction
+  #       # Redis MULTI/EXEC
+  #     end
+  #   end
+  class LmidStore
+    # Atomically increment and return the last mutation ID for a client.
+    # Creates the record with ID 1 if it doesn't exist.
+    #
+    # This must be atomic to prevent race conditions - the increment and
+    # return should happen in a single operation.
+    #
+    # @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)
+      raise NotImplementedError, "#{self.class}#fetch_and_increment must be implemented"
+    end
+
+    # Execute a block within a transaction.
+    # The transaction should support rollback on error.
+    #
+    # @yield The block to execute within the transaction
+    # @return The result of the block
+    def transaction(&block)
+      raise NotImplementedError, "#{self.class}#transaction must be implemented"
+    end
+  end
+end