zero-rails-adapter 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15ffa084c77f3af139ecfc0e284d2b2d41265357ec3b3edafda78d5c7378c8b8
+  data.tar.gz: a6aaafe3bb4cca20cfd6544ad6fd63f49bca923ebd225edb0811069a31c3c778
+SHA512:
+  metadata.gz: cdb046e65aa33933cdb5e33ede0f484275e7734ad637cbe87d298846a5636d79c4a1b5188d390551224c9d660c7dc8ab3bd4a48dfd54571f61c54520a895a1f0
+  data.tar.gz: b3b4149d75a0519b307d7464fe48da60c77eca56a71283791f858151d518f164245e3027310347c342d57d18f03729afb9d2fc66a5a0e20d947ea2807d1d5195

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zero Rails Adapter contributors
+
+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,344 @@
+# Zero Rails Adapter
+
+`zero-rails-adapter` is a mountable Rails Engine that maps Rocicorp Zero custom
+mutations directly to existing Active Record models.
+
+The default CRUD path does not require a Ruby Mutator class for every model:
+
+| Zero mutation | Rails call |
+| --- | --- |
+| `articles.create` / `articles.insert` | `Article.create!(attributes)` |
+| `articles.update` | `Article.find(...).update!(attributes)` |
+| `articles.destroy` / `articles.delete` | `Article.find(...).destroy!` |
+
+Existing Active Record validations, callbacks, associations, `after_commit`
+jobs, database constraints, and transaction behavior therefore work without
+adapter-specific wrappers. Explicit Mutators are reserved for non-CRUD domain
+commands, aggregate operations, and other custom behavior.
+
+The gem does not depend on Devise, a JWT implementation, Pundit, or another
+authorization framework. Authentication, authorization, model exposure, and
+mass-assignment policies are all configurable callable interfaces.
+
+## Requirements
+
+- Ruby 4.0 or newer
+- Rails 8.0 or newer
+- PostgreSQL, the upstream database supported by Zero
+- Current `@rocicorp/zero` and `zero-cache` releases
+
+The Zero-managed `schema.clients` and `schema.mutations` tables and the
+application tables must use the same database connection. In a Rails
+multi-database application, configure `transaction_class` with the abstract
+Active Record base class connected to that PostgreSQL database.
+
+## Installation
+
+Add the gem:
+
+```ruby
+# Gemfile
+gem "zero-rails-adapter"
+```
+
+Install the bundle and initializer:
+
+```sh
+bundle install
+bin/rails generate zero_rails_adapter:install
+```
+
+Mount the Engine:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount ZeroRailsAdapter::Engine => "/zero"
+end
+```
+
+Configure zero-cache:
+
+```sh
+ZERO_MUTATE_URL="https://api.example.com/zero/mutate"
+ZERO_MUTATE_API_KEY="replace-with-a-long-random-secret"
+```
+
+The Engine accepts `POST /mutate`, `POST /push`, and `POST /` beneath its mount
+point. `/mutate` is the recommended endpoint.
+
+The gem intentionally installs no tracking-table migration. zero-cache creates
+the `clients` and `mutations` tables in its shard schema, such as `zero_0`.
+The adapter uses Zero's validated `schema` parameter to build schema-qualified
+Active Record classes for those tables, then writes application data and the
+LMID in the same transaction.
+
+## Generic Active Record CRUD
+
+This client-side mutation:
+
+```ts
+await mutators.articles.create({
+  id: crypto.randomUUID(),
+  title: 'Rails and Zero',
+})
+```
+
+reaches the Engine as `articles.create`. The adapter resolves `Article` from
+the table name, applies the writable-attribute policy, and calls:
+
+```ruby
+Article.create!(id: "...", title: "Rails and Zero")
+```
+
+For `update` and `destroy`, the adapter first loads the record using the
+model's primary key, including composite primary keys, and then calls
+`update!` or `destroy!`. The bang methods are intentional: a validation,
+callback, or database-constraint failure rolls back the complete business
+transaction and produces a structured Zero application error.
+
+Configure the models exposed to generic CRUD explicitly:
+
+```ruby
+ZeroRailsAdapter.configure do |config|
+  config.model_provider = -> { [Article, Comment, Project] }
+end
+```
+
+`model_provider` is both the CRUD allowlist and the source used by the
+TypeScript generator. By default, the adapter eager-loads the Rails application
+and returns every named, non-abstract Active Record model outside the adapter
+itself. An explicit allowlist is recommended in production.
+
+If a table cannot be resolved through Rails naming conventions, replace the
+resolver:
+
+```ruby
+config.model_resolver = ->(table_name) { LegacyModels.fetch(table_name) }
+```
+
+The resolver must return a non-abstract Active Record class.
+
+## Generate Zero TypeScript from Rails Models
+
+The frontend schema and generic CRUD mutators do not need to be maintained by
+hand:
+
+```sh
+bin/rails generate zero_rails_adapter:typescript app/javascript/zero
+```
+
+The generator reflects on the models returned by `model_provider` in the Rails
+runtime and writes:
+
+- `schema.ts`, containing tables, columns, nullability, primary keys, and
+  safely inferred `belongs_to`, `has_one`, and `has_many` relationships.
+- `mutators.ts`, containing `create`, `update`, and `destroy` for every table,
+  using Zero's current `defineMutator` / `defineMutators` API and Zod argument
+  schemas.
+
+Run the generator again after changing Rails migrations or model associations.
+The output can live in Rails' JavaScript directory or be written directly into
+an adjacent Next.js application:
+
+```sh
+bin/rails generate zero_rails_adapter:typescript ../web/src/zero
+```
+
+The default mappings follow Zero's PostgreSQL type conventions:
+
+- string/text/uuid → `string()`
+- integer/bigint/float/decimal → `number()`
+- boolean → `boolean()`
+- date/time/datetime/timestamp → `number()`
+- json/jsonb → `json()`
+- Active Record enum → `enumeration<...>()`
+
+Nullable columns use `.optional()`. Rails timestamps use `Date.now()` for the
+optimistic client write and remain managed normally by Rails on the server.
+The generator raises a descriptive error for a column that cannot be mapped
+reliably instead of emitting an incorrect type.
+
+`generated_attributes` controls which fields appear in generated create and
+update argument schemas:
+
+```ruby
+config.generated_attributes = lambda do |model, action|
+  case model.name
+  when "User" then %w[id name avatar_url]
+  else model.column_names - %w[admin internal_state]
+  end
+end
+```
+
+This is a static code-generation policy and must not depend on the current
+user. Runtime permissions must still be enforced through the authorization
+and writable-attribute interfaces below.
+
+## Authentication, Authorization, and Attribute Policies
+
+The generated initializer supports `ZERO_MUTATE_API_KEY` and verifies
+zero-cache's `X-Api-Key` header using a constant-time comparison.
+
+The authentication interface receives the Rails request. It can integrate with
+Devise/Warden, any JWT library, a session, or an application-specific
+authentication system:
+
+```ruby
+ZeroRailsAdapter.configure do |config|
+  config.authenticator = lambda do |request|
+    user = request.env["warden"]&.user
+    raise ZeroRailsAdapter::UnauthorizedError, "Sign in required" unless user
+
+    ZeroRailsAdapter::Identity.new(
+      user_id: user.id.to_s,
+      current_user: user,
+      claims: {"role" => user.role}
+    )
+  end
+end
+```
+
+The global `authorizer` runs first inside every mutation transaction. The CRUD
+authorizer then receives the model class as `target` for create, or the loaded
+record for update and destroy:
+
+```ruby
+config.crud_authorizer = lambda do |context, action, target, attributes|
+  MutationPolicy.new(
+    context.current_user,
+    action,
+    target,
+    attributes
+  ).allowed?
+end
+```
+
+The server-side mass-assignment allowlist can vary by model, action, and
+authenticated identity:
+
+```ruby
+config.writable_attributes = lambda do |model, action, context|
+  MutationPolicy.new(context.current_user, action, model).permitted_attributes
+end
+```
+
+The default excludes readonly attributes, the STI inheritance column, and
+Rails timestamps. Attributes outside the allowlist are not assigned. Client
+mutation arguments must never be treated as identity or trusted authorization
+data.
+
+Return `false` or raise `ZeroRailsAdapter::ForbiddenError` to reject a
+mutation. Raise `UnauthorizedError` for an authentication failure. A request
+verifier that returns `false` also produces HTTP 401.
+
+## Custom Domain Mutators
+
+Use an explicit Mutator only when ordinary model CRUD cannot express the
+operation, such as publishing an article with an audit event, issuing a command
+across multiple aggregates, or invoking an external service:
+
+```sh
+bin/rails generate zero_rails_adapter:mutator articles.publish
+```
+
+```ruby
+class Articles::PublishMutator < ZeroRailsAdapter::Mutator
+  mutation_name "articles.publish"
+
+  attribute :id, :string
+  validates :id, presence: true
+
+  authorize_with do |context|
+    context.current_user.present?
+  end
+
+  def perform
+    ArticlePublishing.call(Article.find(id), actor: context.current_user)
+  end
+end
+```
+
+An explicitly registered Mutator takes precedence over generic CRUD, so an
+application may intentionally override `articles.create`. The Ruby DSL is also
+available:
+
+```ruby
+ZeroRailsAdapter.define_mutator "projects.archive" do
+  attribute :id, :string
+
+  perform do
+    Project.find(id).archive!(actor: context.current_user)
+  end
+end
+```
+
+Mutators use Active Model attributes and validations and share a transaction
+with application writes and LMID tracking.
+
+## Mutation Ordering and Transaction Semantics
+
+For each `(schema, clientGroupID, clientID)`, the adapter:
+
+1. Locks or creates the Zero client tracking row.
+2. Rejects a mutation ID above the next expected ID.
+3. Skips a mutation ID that has already been processed.
+4. Executes the authorized Active Record operation inside a transaction.
+5. Updates the LMID atomically.
+
+When a business validation or callback fails, the first transaction rolls
+back. A second transaction advances the LMID and stores a structured `app`
+result so that a bad mutation is not retried forever and later mutations can
+continue. If the second transaction also fails, the adapter returns a
+retry-safe `PushFailed` response.
+
+Each mutation owns an independent transaction. A later failure in the same
+HTTP batch does not roll back earlier committed mutations.
+`_zero_cleanupResults` removes acknowledged error results without advancing
+the LMID.
+
+## Observability
+
+Every non-internal mutation emits an Active Support notification:
+
+```ruby
+ActiveSupport::Notifications.subscribe("mutation.zero_rails_adapter") do |event|
+  Rails.logger.info(
+    name: event.payload[:name],
+    client_id: event.payload[:client_id],
+    duration_ms: event.duration
+  )
+end
+```
+
+The payload also contains `mutation_id`, `client_group_id`, `app_id`, and
+`schema`.
+
+## Development and Testing
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec gem build zero-rails-adapter.gemspec
+```
+
+The suite covers the mountable Engine endpoint, Zero protocol ordering and
+error semantics, dynamic CRUD dispatch, Active Record validations, callbacks,
+dependent destroy behavior, authorization hooks, TypeScript generation, and a
+PostgreSQL contract test using Zero's exact tracking-table structure.
+
+Run the complete contract suite against a dedicated PostgreSQL test database:
+
+```sh
+DATABASE_URL=postgres://localhost/zero_rails_adapter_test bundle exec rake test
+```
+
+See [`examples/nextjs`](examples/nextjs) for a Next.js integration fixture.
+
+## References
+
+- [Zero custom mutators](https://zero.rocicorp.dev/docs/mutators)
+- [Zero schema](https://zero.rocicorp.dev/docs/schema)
+- [Zero PostgreSQL support](https://zero.rocicorp.dev/docs/postgres-support)
+- [Zero `process-mutations.ts`](https://github.com/rocicorp/mono/blob/main/packages/zero-server/src/process-mutations.ts)
+- [Server implementation plan](https://jeremykreutzbender.com/blog/server-implementation-plan-rocicorp-zero-custom-mutators)

data/app/controllers/zero_rails_adapter/mutations_controller.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  class MutationsController < ActionController::API
+    def create
+      verify_request!
+      identity = authenticate!
+      zero_request = Request.parse(parsed_body, query: request.query_parameters)
+      context = Context.new(identity:, request: zero_request, rack_request: request)
+
+      render json: Processor.new(request: zero_request, context:).call, status: :ok
+    rescue JSON::ParserError => error
+      render json: push_failed("parse", "Failed to parse push body: #{error.message}", []),
+        status: :ok
+    rescue ParseError => error
+      subject = error.source == :query ? "push query parameters" : "push body"
+      render json: push_failed("parse", "Failed to parse #{subject}: #{error.message}", error.mutation_ids),
+        status: :ok
+    rescue UnsupportedPushVersionError => error
+      render json: push_failed("unsupportedPushVersion", error.message, error.mutation_ids),
+        status: :ok
+    rescue UnauthorizedError => error
+      render json: authentication_error(error), status: :unauthorized
+    rescue ForbiddenError => error
+      render json: authentication_error(error), status: :forbidden
+    rescue StandardError => error
+      ZeroRailsAdapter.configuration.logger&.error(
+        "ZeroRailsAdapter request failed: #{error.class}: #{error.message}"
+      )
+      render json: push_failed("internal", error.message, []), status: :internal_server_error
+    end
+
+    private
+
+    def parsed_body
+      JSON.parse(request.raw_post)
+    end
+
+    def verify_request!
+      verified = ZeroRailsAdapter.configuration.request_verifier.call(request)
+      raise UnauthorizedError, "Zero request verification failed" unless verified
+    end
+
+    def authenticate!
+      value = ZeroRailsAdapter.configuration.authenticator.call(request)
+      return value if value.is_a?(Identity)
+
+      attributes = value.respond_to?(:to_h) ? value.to_h.symbolize_keys : {}
+      Identity.new(
+        user_id: attributes[:user_id],
+        current_user: attributes[:current_user],
+        claims: attributes[:claims] || {}
+      )
+    end
+
+    def push_failed(reason, message, mutation_ids)
+      {
+        "kind" => "PushFailed",
+        "origin" => "server",
+        "reason" => reason,
+        "message" => message,
+        "mutationIDs" => mutation_ids
+      }
+    end
+
+    def authentication_error(error)
+      {
+        "kind" => "Unauthorized",
+        "origin" => "server",
+        "message" => error.message
+      }
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+ZeroRailsAdapter::Engine.routes.draw do
+  post "/", to: "mutations#create"
+  post "/mutate", to: "mutations#create"
+  post "/push", to: "mutations#create"
+end

data/examples/nextjs/README.md

@@ -0,0 +1,29 @@
+# Next.js integration fixture
+
+This fixture shows the generated client half of Rails-backed generic CRUD.
+Install the current `@rocicorp/zero` and `zod` releases in a Next.js app, or
+generate equivalent files directly from the Rails models:
+
+```sh
+bin/rails generate zero_rails_adapter:typescript ../web/src/zero
+```
+
+Register the exported `schema` and `mutators` with the app's Zero client.
+
+Configure:
+
+```env
+NEXT_PUBLIC_ZERO_CACHE_URL=http://localhost:4848
+NEXT_PUBLIC_ZERO_MUTATE_URL=http://localhost:3000/zero/mutate
+```
+
+Configure zero-cache with the same Rails URL:
+
+```sh
+ZERO_MUTATE_URL=http://localhost:3000/zero/mutate
+ZERO_MUTATE_API_KEY=development-secret
+```
+
+The Rails application must mount the Engine at `/zero`, use the generated API
+key verifier, and expose `Book` through `config.model_provider`. No Ruby
+mutator class is needed for `books.create/update/destroy`.

data/examples/nextjs/src/zero/mutators.ts

@@ -0,0 +1,37 @@
+import {defineMutator, defineMutators} from '@rocicorp/zero'
+import {z} from 'zod'
+
+export const mutators = defineMutators({
+  books: {
+    create: defineMutator(
+      z.object({
+        id: z.string(),
+        title: z.string().min(1).max(200),
+        owner_id: z.string(),
+      }),
+      async ({tx, args}) => {
+        const now = Date.now()
+        await tx.mutate.books.insert({
+          ...args,
+          created_at: now,
+          updated_at: now,
+        })
+      },
+    ),
+    update: defineMutator(
+      z.object({
+        id: z.string(),
+        title: z.string().min(1).max(200).optional(),
+      }),
+      async ({tx, args}) => {
+        await tx.mutate.books.update({...args, updated_at: Date.now()})
+      },
+    ),
+    destroy: defineMutator(
+      z.object({id: z.string()}),
+      async ({tx, args}) => {
+        await tx.mutate.books.delete(args)
+      },
+    ),
+  },
+})

data/examples/nextjs/src/zero/schema.ts

@@ -0,0 +1,20 @@
+import {createSchema, number, string, table} from '@rocicorp/zero'
+
+const books = table('books')
+  .columns({
+    id: string(),
+    title: string(),
+    owner_id: string(),
+    created_at: number(),
+    updated_at: number(),
+  })
+  .primaryKey('id')
+
+export const schema = createSchema({tables: [books]})
+export type Schema = typeof schema
+
+declare module '@rocicorp/zero' {
+  interface DefaultTypes {
+    schema: Schema
+  }
+}

data/lib/generators/zero_rails_adapter/install/install_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module ZeroRailsAdapter
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/zero_rails_adapter.rb"
+      end
+    end
+  end
+end

data/lib/generators/zero_rails_adapter/install/templates/initializer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+ZeroRailsAdapter.configure do |config|
+  # zero-cache owns the schema.clients and schema.mutations tracking tables,
+  # so this gem does not install a migration for them.
+
+  # Verify that calls came from your zero-cache instance.
+  # Configure zero-cache with ZERO_MUTATE_API_KEY using the same value.
+  if ENV["ZERO_MUTATE_API_KEY"].present?
+    config.request_verifier = ZeroRailsAdapter::RequestVerifiers::ApiKey.new(
+      key: ENV.fetch("ZERO_MUTATE_API_KEY")
+    )
+  end
+
+  # Return an Identity from any authentication system (Devise, JWT, cookies, etc.).
+  # config.authenticator = lambda do |request|
+  #   user = YourAuthentication.call(request)
+  #   ZeroRailsAdapter::Identity.new(
+  #     user_id: user&.id&.to_s,
+  #     current_user: user,
+  #     claims: {}
+  #   )
+  # end
+
+  # This runs once per mutation, inside its database transaction.
+  # Raise ZeroRailsAdapter::ForbiddenError to reject a mutation.
+  # config.authorizer = ->(context, mutation) { YourPolicy.authorize!(context, mutation) }
+
+  # Generic CRUD resolves "articles.create", "articles.update", and
+  # "articles.destroy" against this allowlist. The default is every named,
+  # non-abstract Active Record model; an explicit list is recommended.
+  # config.model_provider = -> { [Article, Comment] }
+
+  # Authorize generic CRUD independently of Devise/JWT/Pundit/etc. target is
+  # the model class for create, and the loaded record for update/destroy.
+  # config.crud_authorizer = lambda do |context, action, target, attributes|
+  #   ApplicationPolicy.new(context.current_user, target).public_send("#{action}?")
+  # end
+
+  # Server-side mass-assignment policy. It is always enforced after auth.
+  # config.writable_attributes = lambda do |model, action, context|
+  #   ModelMutationPolicy.new(context.current_user, model, action).attributes
+  # end
+
+  # Static field allowlist used by the TypeScript generator. Keep
+  # user-dependent decisions in writable_attributes/crud_authorizer.
+  # config.generated_attributes = ->(model, action) { model.column_names - %w[admin] }
+
+  # For Rails multi-database apps, use an abstract base class connected to the
+  # same PostgreSQL database as zero-cache's upstream schema.
+  # config.transaction_class = PrimaryApplicationRecord
+end

data/lib/generators/zero_rails_adapter/mutator/mutator_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module ZeroRailsAdapter
+  module Generators
+    class MutatorGenerator < Rails::Generators::Base
+      argument :name, type: :string, banner: "namespace.action"
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_mutator
+        template "mutator.rb", File.join("app/mutators", "#{file_path}_mutator.rb")
+      end
+
+      private
+
+      def name_parts
+        @name_parts ||= name.split(/[|.]/)
+      end
+
+      def class_name
+        "#{name_parts.map(&:camelize).join('::')}Mutator"
+      end
+
+      def file_path
+        name_parts.map(&:underscore).join("/")
+      end
+    end
+  end
+end

data/lib/generators/zero_rails_adapter/mutator/templates/mutator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < ZeroRailsAdapter::Mutator
+  mutation_name "<%= name %>"
+
+  # Arguments are Active Model attributes and support normal Rails validations.
+  # attribute :title, :string
+  # validates :title, presence: true
+
+  def perform
+    # Use context.current_user, context.user_id, and context.claims for authorization.
+    raise NotImplementedError
+  end
+end

data/lib/generators/zero_rails_adapter/typescript/typescript_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "zero_rails_adapter"
+
+module ZeroRailsAdapter
+  module Generators
+    class TypeScriptGenerator < Rails::Generators::Base
+      argument :destination, type: :string, default: "app/javascript/zero"
+
+      def generate_typescript
+        generator = ZeroRailsAdapter::TypeScript::Generator.new
+        create_file File.join(destination, "schema.ts"), generator.schema
+        create_file File.join(destination, "mutators.ts"), generator.mutators
+      end
+    end
+  end
+end