zero-rails-adapter 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15ffa084c77f3af139ecfc0e284d2b2d41265357ec3b3edafda78d5c7378c8b8
-  data.tar.gz: a6aaafe3bb4cca20cfd6544ad6fd63f49bca923ebd225edb0811069a31c3c778
+  metadata.gz: 87460dcc3c79305e4ca81c9bd30800866a2a9c97709298955cdf16334723d442
+  data.tar.gz: 9c76ea660812fb14a1fa52fc148e00e973da5b670635dcd85242d781b93f0958
 SHA512:
-  metadata.gz: cdb046e65aa33933cdb5e33ede0f484275e7734ad637cbe87d298846a5636d79c4a1b5188d390551224c9d660c7dc8ab3bd4a48dfd54571f61c54520a895a1f0
-  data.tar.gz: b3b4149d75a0519b307d7464fe48da60c77eca56a71283791f858151d518f164245e3027310347c342d57d18f03729afb9d2fc66a5a0e20d947ea2807d1d5195
+  metadata.gz: 13941576c897585d1253128412c7a3b062c273e407b1430e51cbae1f0dd9fc4a89d24b5fba7b8f5398ff610d72b64a38b286293af8146f6270bc5db27394a12c
+  data.tar.gz: e4785424bc04062e227084591faf341260d67177bf73c588494778b4037e25b9642fc6e444718554c90bdf371928ab71f7c01952c1dc4d3627d73c14f5b83ad5

data/README.md

@@ -25,7 +25,7 @@ mass-assignment policies are all configurable callable interfaces.
 - Ruby 4.0 or newer
 - Rails 8.0 or newer
 - PostgreSQL, the upstream database supported by Zero
-- Current `@rocicorp/zero` and `zero-cache` releases
+- `@rocicorp/zero` and `zero-cache` from the same supported release
 
 The Zero-managed `schema.clients` and `schema.mutations` tables and the
 application tables must use the same database connection. In a Rails
@@ -73,8 +73,64 @@ 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.
 
+## Explicit Publication Schema
+
+The adapter fails closed. No Active Record model or column is published, added
+to generated TypeScript, or exposed to generic CRUD by default.
+
+Declare both the tables and columns that may be replicated:
+
+```ruby
+ZeroRailsAdapter.configure do |config|
+  config.published_schema = lambda do
+    {
+      Article => %w[id title body author_id created_at updated_at],
+      Comment => %w[id article_id body author_id created_at updated_at]
+    }
+  end
+end
+```
+
+The callable is evaluated when code is generated, so it remains safe across
+Rails development reloads. Primary key columns must be present. Unknown
+columns, known credential columns such as `password_hash` and `token_digest`,
+Active Storage and Action Mailbox internal tables, and PostgreSQL types that
+Zero cannot replicate are rejected.
+
+By default, a model's Zero key is its Active Record primary key. Applications
+may use a separate stable synchronization key:
+
+```ruby
+config.zero_key = lambda do |model|
+  model == Article ? "sync_id" : model.primary_key
+end
+```
+
+A separate Zero key must be included in `published_schema` and backed by an
+exact unique, non-null database index. Composite Zero keys may be returned as
+an array. The database primary key must still be published because PostgreSQL
+uses it as the table's replica identity; it is not silently replaced by the
+Zero key.
+
+Generate a reviewable, column-limited PostgreSQL publication:
+
+```sh
+bin/rails generate zero_rails_adapter:publication zero_data
+```
+
+This writes `db/zero_publication.sql`; it does not execute DDL automatically.
+Apply the SQL through the application's normal migration or operations process,
+then configure:
+
+```sh
+ZERO_APP_PUBLICATIONS=zero_data
+```
+
 ## Generic Active Record CRUD
 
+Generic CRUD is a separate, opt-in capability. Publishing a model never makes
+it writable.
+
 This client-side mutation:
 
 ```ts
@@ -92,8 +148,9 @@ 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,
+configured Zero key, including composite keys, and then calls `update!` or
+`destroy!`. Neither the Zero key nor the Active Record primary key can be
+changed by generic update. 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.
 
@@ -101,14 +158,16 @@ Configure the models exposed to generic CRUD explicitly:
 
 ```ruby
 ZeroRailsAdapter.configure do |config|
-  config.model_provider = -> { [Article, Comment, Project] }
+  config.crud_model_provider = -> { [Article, Comment] }
 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.
+Models absent from `crud_model_provider` cannot be resolved by generic CRUD.
+The default provider returns an empty list, and the default `crud_authorizer`
+also rejects every operation. Applications must opt into both model resolution
+and authorization. Applications with aggregate operations, tenant-scoped
+commands, soft deletion, or other domain behavior should leave the provider
+empty and use custom mutators.
 
 If a table cannot be resolved through Rails naming conventions, replace the
 resolver:
@@ -128,14 +187,13 @@ hand:
 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:
+The generator reflects on `published_schema` in the Rails runtime and writes:
 
-- `schema.ts`, containing tables, columns, nullability, primary keys, and
+- `schema.ts`, containing tables, columns, nullability, Zero 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.
+- `mutators.ts`, containing `create`, `update`, and `destroy` only for models
+  returned by `crud_model_provider`, 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
@@ -145,6 +203,48 @@ an adjacent Next.js application:
 bin/rails generate zero_rails_adapter:typescript ../web/src/zero
 ```
 
+Rails cannot safely infer every Zero relationship. Add delegated-type,
+polymorphic, custom, or through relationships explicitly:
+
+```ruby
+config.relationship_provider = lambda do
+  [
+    {
+      source: Recording,
+      name: :task,
+      kind: :one,
+      source_fields: %w[recordable_id],
+      destination: Task,
+      destination_fields: %w[id]
+    },
+    {
+      source: Article,
+      name: :labels,
+      kind: :many,
+      through: [
+        {
+          source_fields: %w[id],
+          destination: ArticleLabel,
+          destination_fields: %w[article_id]
+        },
+        {
+          source_fields: %w[label_id],
+          destination: Label,
+          destination_fields: %w[id]
+        }
+      ]
+    }
+  ]
+end
+```
+
+Every model and field in a manual relationship must be published. Zero
+supports at most two relationship hops. A polymorphic or delegated-type
+relationship also needs an application invariant or a published discriminator
+or safe mirror column that prevents IDs belonging to another type from
+matching; the adapter does not guess that predicate. A manual definition with
+the same source and name replaces an inferred relationship.
+
 The default mappings follow Zero's PostgreSQL type conventions:
 
 - string/text/uuid → `string()`
@@ -152,10 +252,13 @@ The default mappings follow Zero's PostgreSQL type conventions:
 - boolean → `boolean()`
 - date/time/datetime/timestamp → `number()`
 - json/jsonb → `json()`
-- Active Record enum → `enumeration<...>()`
+- integer-backed Active Record enum → `number()`
+- string-backed Active Record enum → `string()`
+- PostgreSQL native 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.
+optimistic client write and are Unix epoch milliseconds in Zero. They 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.
 
@@ -333,6 +436,21 @@ Run the complete contract suite against a dedicated PostgreSQL test database:
 DATABASE_URL=postgres://localhost/zero_rails_adapter_test bundle exec rake test
 ```
 
+The repository also locks `@rocicorp/zero` and the `zero-cache` CLI to the
+exact same `1.8.0` package in `test/contract/package-lock.json`. Run the full
+wire and replication contract with Node 24+ and Docker:
+
+```sh
+bundle exec rake contract
+```
+
+That task compiles the generated TypeScript, starts PostgreSQL with logical
+replication, starts the real zero-cache and Rails mutation endpoint, then uses
+a Zero client to mutate and query replicated rows. The generated fixture
+includes a separate Zero key and a two-hop relationship. The task also verifies
+LMID advancement, duplicate-mutation handling, failure skipping, and
+`_zero_cleanupResults`. The contract runs as its own CI job.
+
 See [`examples/nextjs`](examples/nextjs) for a Next.js integration fixture.
 
 ## References
@@ -340,5 +458,6 @@ See [`examples/nextjs`](examples/nextjs) for a Next.js integration fixture.
 - [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 1.8 release notes](https://zero.rocicorp.dev/docs/release-notes/1.8)
 - [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/examples/nextjs/README.md

@@ -25,5 +25,7 @@ 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`.
+key verifier, publish explicit `Book` columns through
+`config.published_schema`, and opt `Book` into
+`config.crud_model_provider`. No Ruby mutator class is needed for
+`books.create/update/destroy`.

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

@@ -26,10 +26,31 @@ ZeroRailsAdapter.configure do |config|
   # 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] }
+  # Fail-closed table and column allowlist used by schema.ts and publication
+  # SQL generation. No tables or columns are published by default.
+  # config.published_schema = lambda do
+  #   {
+  #     Article => %w[id title body author_id created_at updated_at],
+  #     Comment => %w[id article_id body author_id created_at updated_at]
+  #   }
+  # end
+
+  # Generic CRUD is independently opt-in. Publishing a model does not make it
+  # writable. The default crud_authorizer below also rejects every operation.
+  # Keep this empty when writes require domain-specific mutators.
+  # config.crud_model_provider = -> { [Article, Comment] }
+
+  # Zero uses this stable key in generated schemas and CRUD update/destroy
+  # lookups. A non-Active Record key must be published and backed by an exact
+  # unique, non-null database index. Composite keys may return an array.
+  # config.zero_key = lambda do |model|
+  #   model == Article ? "sync_id" : model.primary_key
+  # end
+
+  # Add relationships that Rails reflection cannot express safely, including
+  # polymorphic, delegated-type, and through relationships. Definitions may
+  # contain one direct hop or a maximum of two entries under `through`.
+  # config.relationship_provider = -> { [] }
 
   # Authorize generic CRUD independently of Devise/JWT/Pundit/etc. target is
   # the model class for create, and the loaded record for update/destroy.

data/lib/generators/zero_rails_adapter/publication/publication_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "zero_rails_adapter"
+
+module ZeroRailsAdapter
+  module Generators
+    class PublicationGenerator < Rails::Generators::Base
+      argument :publication_name,
+        type: :string,
+        default: ZeroRailsAdapter::PostgreSQL::PublicationGenerator::DEFAULT_NAME
+
+      def create_publication_sql
+        sql = ZeroRailsAdapter::PostgreSQL::PublicationGenerator.new(
+          name: publication_name
+        ).sql
+        create_file "db/zero_publication.sql", sql
+      end
+    end
+  end
+end

data/lib/zero_rails_adapter/configuration.rb

@@ -5,18 +5,22 @@ module ZeroRailsAdapter
     attr_accessor :authenticator, :request_verifier, :authorizer, :logger,
       :transaction_class, :storage_provider, :crud_authorizer,
       :writable_attributes, :generated_attributes, :model_resolver,
-      :model_provider
+      :published_schema, :crud_model_provider, :zero_key,
+      :relationship_provider
 
     def initialize
       @authenticator = ->(_request) { Identity.new }
       @request_verifier = ->(_request) { true }
       @authorizer = ->(_context, _mutation) { true }
-      @crud_authorizer = ->(_context, _action, _target, _attributes) { true }
+      @crud_authorizer = ->(_context, _action, _target, _attributes) { false }
       @logger = defined?(Rails) ? Rails.logger : nil
       @transaction_class = ActiveRecord::Base
-      @model_provider = -> { default_models }
+      @published_schema = -> { {} }
+      @crud_model_provider = -> { [] }
+      @zero_key = ->(model) { model.primary_key }
+      @relationship_provider = -> { [] }
       @model_resolver = lambda do |resource|
-        allowed_models = Array(model_provider.call).select do |model|
+        allowed_models = Array(crud_model_provider.call).select do |model|
           active_record_model?(model)
         end
         candidate = resource.to_s.classify.safe_constantize
@@ -32,16 +36,6 @@ module ZeroRailsAdapter
 
     private
 
-    def default_models
-      application = Rails.application if defined?(Rails) && Rails.respond_to?(:application)
-      application&.eager_load!
-      ActiveRecord::Base.descendants.select do |model|
-        active_record_model?(model) &&
-          model.name.present? &&
-          !model.name.start_with?("ZeroRailsAdapter::")
-      end
-    end
-
     def default_writable_attributes(model)
       model.column_names -
         model.readonly_attributes.to_a -

data/lib/zero_rails_adapter/crud/dispatcher.rb

@@ -68,7 +68,8 @@ module ZeroRailsAdapter
       def update(model, attributes)
         record = find_record!(model, attributes)
         authorize!(:update, record, attributes)
-        changes = writable(model, :update, attributes).except(*primary_keys(model))
+        immutable_keys = zero_keys(model) + Array(model.primary_key).compact.map(&:to_s)
+        changes = writable(model, :update, attributes).except(*immutable_keys)
         record.update!(changes)
         nil
       end
@@ -81,21 +82,26 @@ module ZeroRailsAdapter
       end
 
       def find_record!(model, attributes)
-        keys = primary_keys(model)
+        keys = zero_keys(model)
         values = attributes.slice(*keys)
         missing = keys - values.keys
         if missing.any?
           raise ValidationError.new(
-            "Missing primary key attributes: #{missing.join(', ')}",
-            details: {"primaryKey" => missing}
+            "Missing Zero key attributes: #{missing.join(', ')}",
+            details: {"zeroKey" => missing}
           )
         end
 
         model.find_by!(values)
       end
 
-      def primary_keys(model)
-        Array(model.primary_key).map(&:to_s)
+      def zero_keys(model)
+        keys = Array(
+          ZeroRailsAdapter.configuration.zero_key.call(model)
+        ).compact.map(&:to_s)
+        return keys if keys.any?
+
+        raise ValidationError, "#{model.name} must define at least one Zero key"
       end
 
       def authorize!(action, target, attributes)

data/lib/zero_rails_adapter/errors.rb

@@ -17,6 +17,8 @@ module ZeroRailsAdapter
   class UnauthorizedError < Error; end
   class UnknownMutatorError < ApplicationError; end
   class UnsupportedColumnTypeError < Error; end
+  class UnsafePublicationError < Error; end
+  class InvalidRelationshipError < Error; end
 
   class ProtocolError < Error
     attr_reader :mutation_ids

data/lib/zero_rails_adapter/postgresql/publication_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  module PostgreSQL
+    class PublicationGenerator
+      DEFAULT_NAME = "zero_data"
+
+      def initialize(name: DEFAULT_NAME, published_schema: nil)
+        @name = name.to_s
+        @published_schema = PublishedSchema.new(
+          published_schema || ZeroRailsAdapter.configuration.published_schema.call,
+          zero_key: ZeroRailsAdapter.configuration.zero_key
+        )
+      end
+
+      def sql
+        entries = @published_schema.models.map do |model|
+          connection = model.connection
+          quoted_columns = @published_schema.column_names_for(model).map do |column|
+            connection.quote_column_name(column)
+          end
+
+          "#{connection.quote_table_name(model.table_name)} (#{quoted_columns.join(', ')})"
+        end
+
+        raise UnsafePublicationError, "Published schema must include at least one table" if entries.empty?
+
+        connection = @published_schema.models.first.connection
+        <<~SQL
+          CREATE PUBLICATION #{connection.quote_column_name(@name)} FOR TABLE
+            #{entries.join(",\n  ")};
+        SQL
+      end
+    end
+  end
+end

data/lib/zero_rails_adapter/published_schema.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  class PublishedSchema
+    SUPPORTED_COLUMN_TYPES = %i[
+      bigint boolean date datetime decimal enum float integer json jsonb
+      string text time timestamp uuid
+    ].freeze
+    FORBIDDEN_COLUMN_NAMES = %w[
+      access_token api_key api_key_digest device_token key_digest
+      password password_digest password_hash refresh_token secret secret_key
+      token token_digest
+    ].freeze
+    FORBIDDEN_TABLE_PREFIXES = %w[
+      action_mailbox_ active_storage_
+    ].freeze
+    FORBIDDEN_TABLE_NAMES = %w[
+      user_login_change_keys user_lockouts user_password_reset_keys
+      user_previous_password_hashes user_recovery_codes user_remember_keys
+      user_verification_keys
+    ].freeze
+
+    attr_reader :models
+
+    def initialize(mapping, zero_key: ZeroRailsAdapter.configuration.zero_key)
+      value = mapping.respond_to?(:call) ? mapping.call : mapping
+      unless value.respond_to?(:to_h)
+        raise UnsafePublicationError,
+          "Published schema must be a model-to-columns mapping"
+      end
+
+      @zero_key = zero_key
+      @columns_by_model = value.to_h.each_with_object({}) do |(model, names), result|
+        validate_model!(model)
+        result[model] = validate_columns!(model, names)
+      end
+      @models = @columns_by_model.keys.freeze
+    end
+
+    def empty?
+      models.empty?
+    end
+
+    def column_names_for(model)
+      columns_for(model).map(&:name)
+    end
+
+    def columns_for(model)
+      @columns_by_model.fetch(model)
+    end
+
+    def zero_keys_for(model)
+      keys = Array(@zero_key.call(model)).compact.map(&:to_s)
+      return keys.freeze if keys.any?
+
+      label = model.name.presence || model.table_name
+      raise UnsafePublicationError, "#{label} must define at least one Zero key"
+    end
+
+    private
+
+    def validate_model!(model)
+      unless model.is_a?(Class) &&
+          model < ActiveRecord::Base &&
+          !model.abstract_class?
+        raise UnsafePublicationError,
+          "#{model.inspect} is not an Active Record model"
+      end
+
+      if FORBIDDEN_TABLE_PREFIXES.any? { |prefix| model.table_name.start_with?(prefix) }
+        raise UnsafePublicationError,
+          "#{model.table_name} is an internal framework table"
+      end
+
+      if FORBIDDEN_TABLE_NAMES.include?(model.table_name)
+        raise UnsafePublicationError,
+          "#{model.table_name} is an authentication table"
+      end
+    end
+
+    def validate_columns!(model, names)
+      names = Array(names).map(&:to_s).uniq
+      label = model.name.presence || model.table_name
+      raise UnsafePublicationError, "#{label} must publish at least one column" if names.empty?
+
+      unknown = names - model.column_names
+      if unknown.any?
+        raise UnsafePublicationError, "#{label}.#{unknown.first} does not exist"
+      end
+
+      forbidden = names.find { |name| FORBIDDEN_COLUMN_NAMES.include?(name) }
+      if forbidden
+        raise UnsafePublicationError, "#{label}.#{forbidden} is forbidden"
+      end
+
+      columns = names.map { |name| model.columns_hash.fetch(name) }
+      unsupported = columns.find do |column|
+        !SUPPORTED_COLUMN_TYPES.include?(column.type.to_sym)
+      end
+      if unsupported
+        raise UnsafePublicationError,
+          "#{label}.#{unsupported.name} uses unsupported PostgreSQL type " \
+          "#{unsupported.sql_type}"
+      end
+
+      missing_keys = Array(model.primary_key).compact.map(&:to_s) - names
+      if missing_keys.any?
+        key_label = missing_keys.one? ? "column" : "columns"
+        raise UnsafePublicationError,
+          "#{label} publication must include primary key #{key_label} " \
+          "#{missing_keys.join(', ')}"
+      end
+
+      validate_zero_key!(model, names, label)
+      columns.freeze
+    end
+
+    def validate_zero_key!(model, published_names, label)
+      keys = zero_keys_for(model)
+      missing_keys = keys - published_names
+      if missing_keys.any?
+        key_label = missing_keys.one? ? "column" : "columns"
+        raise UnsafePublicationError,
+          "#{label} publication must include Zero key #{key_label} " \
+          "#{missing_keys.join(', ')}"
+      end
+
+      active_record_keys = Array(model.primary_key).compact.map(&:to_s)
+      return if keys == active_record_keys
+
+      columns = keys.map { |key| model.columns_hash.fetch(key) }
+      unique_index = model.connection.indexes(model.table_name).any? do |index|
+        index.unique &&
+          index.where.blank? &&
+          Array(index.columns).map(&:to_s) == keys
+      end
+      return if columns.none?(&:null) && unique_index
+
+      raise UnsafePublicationError,
+        "#{label} Zero key #{keys.join(', ')} must be backed by a unique, non-null index"
+    end
+  end
+end

data/lib/zero_rails_adapter/relationship.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ZeroRailsAdapter
+  class Relationship
+    Hop = Struct.new(
+      :source_fields,
+      :destination,
+      :destination_fields,
+      keyword_init: true
+    )
+
+    attr_reader :source, :name, :kind, :hops
+
+    def self.from_definition(definition, published_schema:)
+      unless definition.respond_to?(:to_h)
+        raise InvalidRelationshipError, "Relationship definition must be an object"
+      end
+
+      attributes = definition.to_h.symbolize_keys
+      hop_definitions = if attributes.key?(:through)
+        Array(attributes[:through])
+      else
+        [{
+          source_fields: attributes[:source_fields],
+          destination: attributes[:destination],
+          destination_fields: attributes[:destination_fields]
+        }]
+      end
+
+      new(
+        source: attributes[:source],
+        name: attributes[:name],
+        kind: attributes[:kind],
+        hops: hop_definitions,
+        published_schema:
+      )
+    end
+
+    def initialize(source:, name:, kind:, hops:, published_schema:)
+      @source = source
+      @name = name.to_s
+      @kind = kind.to_s
+      @published_schema = published_schema
+
+      validate_header!
+      @hops = validate_hops!(hops).freeze
+    end
+
+    private
+
+    def validate_header!
+      unless @published_schema.models.include?(source)
+        raise InvalidRelationshipError,
+          "Relationship source #{model_label(source)} is not published"
+      end
+      if name.empty?
+        raise InvalidRelationshipError, "Relationship name must not be empty"
+      end
+      unless %w[one many].include?(kind)
+        raise InvalidRelationshipError,
+          "Relationship #{name} kind must be one or many"
+      end
+    end
+
+    def validate_hops!(definitions)
+      definitions = Array(definitions)
+      if definitions.empty?
+        raise InvalidRelationshipError,
+          "Relationship #{name} must define at least one hop"
+      end
+      if definitions.length > 2
+        raise InvalidRelationshipError,
+          "Relationship #{name} supports at most two hops"
+      end
+
+      current_source = source
+      definitions.map do |definition|
+        unless definition.respond_to?(:to_h)
+          raise InvalidRelationshipError,
+            "Relationship #{name} hop must be an object"
+        end
+
+        attributes = definition.to_h.symbolize_keys
+        source_fields = normalize_fields(attributes[:source_fields])
+        destination = attributes[:destination]
+        destination_fields = normalize_fields(attributes[:destination_fields])
+
+        validate_model!(destination)
+        validate_fields!(current_source, source_fields, "source")
+        validate_fields!(destination, destination_fields, "destination")
+        if source_fields.length != destination_fields.length
+          raise InvalidRelationshipError,
+            "Relationship #{name} hop fields must have matching arity"
+        end
+
+        current_source = destination
+        Hop.new(source_fields:, destination:, destination_fields:).freeze
+      end
+    end
+
+    def validate_model!(model)
+      return if @published_schema.models.include?(model)
+
+      raise InvalidRelationshipError,
+        "Relationship #{name} destination #{model_label(model)} is not published"
+    end
+
+    def validate_fields!(model, fields, side)
+      if fields.empty?
+        raise InvalidRelationshipError,
+          "Relationship #{name} #{side} fields must not be empty"
+      end
+
+      missing = fields - @published_schema.column_names_for(model)
+      return if missing.empty?
+
+      raise InvalidRelationshipError,
+        "Relationship #{name} #{side} field #{missing.first} is not published"
+    end
+
+    def normalize_fields(value)
+      Array(value).compact.map(&:to_s)
+    end
+
+    def model_label(model)
+      model.respond_to?(:name) && model.name.present? ? model.name : model.inspect
+    end
+  end
+end

data/lib/zero_rails_adapter/type_script/generator.rb

@@ -37,13 +37,31 @@ module ZeroRailsAdapter
         jsonb: "z.json()"
       }.freeze
 
-      attr_reader :models
+      attr_reader :models, :crud_models
+
+      def initialize(published_schema: nil, crud_models: nil, manual_relationships: nil)
+        schema = published_schema || ZeroRailsAdapter.configuration.published_schema.call
+        @published_schema = PublishedSchema.new(
+          schema,
+          zero_key: ZeroRailsAdapter.configuration.zero_key
+        )
+        @models = @published_schema.models.sort_by(&:table_name)
+        relationship_definitions = manual_relationships ||
+          ZeroRailsAdapter.configuration.relationship_provider.call
+        @manual_relationships = Array(relationship_definitions).map do |definition|
+          Relationship.from_definition(definition, published_schema: @published_schema)
+        end
+        requested_crud_models = Array(
+          crud_models || ZeroRailsAdapter.configuration.crud_model_provider.call
+        )
+        unpublished = requested_crud_models - models
+        if unpublished.any?
+          labels = unpublished.map { |model| model.respond_to?(:name) ? model.name : model.inspect }
+          raise UnsafePublicationError,
+            "CRUD models must also be published: #{labels.join(', ')}"
+        end
 
-      def initialize(models: nil)
-        @models = Array(models || ZeroRailsAdapter.configuration.model_provider.call)
-          .select { |model| active_record_model?(model) }
-          .uniq
-          .sort_by(&:table_name)
+        @crud_models = requested_crud_models.uniq.sort_by(&:table_name)
       end
 
       def schema
@@ -75,7 +93,7 @@ module ZeroRailsAdapter
 
       def table_definitions
         models.map do |model|
-          columns = model.columns.map do |column|
+          columns = columns_for(model).map do |column|
             "    #{property_name(column.name)}: #{zero_type(model, column)},"
           end.join("\n")
           keys = primary_keys(model).map { |key| quote(key) }.join(", ")
@@ -91,22 +109,20 @@ module ZeroRailsAdapter
       end
 
       def relationship_definitions
-        relationships.group_by(&:first).map do |model, definitions|
-          kinds = definitions.map do |_source, reflection, _destination|
-            reflection.collection? ? "many" : "one"
-          end.uniq.sort.join(", ")
-          entries = definitions.map do |_source, reflection, destination|
-            source_fields, destination_fields =
-              relationship_fields(model, reflection, destination)
-            kind = reflection.collection? ? "many" : "one"
-
-            [
-              "#{property_name(reflection.name)}: #{kind}({",
-              "  sourceField: [#{source_fields.map { |field| quote(field) }.join(', ')}],",
-              "  destSchema: #{variable_name(destination)},",
-              "  destField: [#{destination_fields.map { |field| quote(field) }.join(', ')}],",
-              "}),"
-            ].join("\n")
+        relationships.group_by(&:source).map do |model, definitions|
+          kinds = definitions.map(&:kind).uniq.sort.join(", ")
+          entries = definitions.map do |relationship|
+            hops = relationship.hops.map do |hop|
+              [
+                "{",
+                "  sourceField: [#{hop.source_fields.map { |field| quote(field) }.join(', ')}],",
+                "  destSchema: #{variable_name(hop.destination)},",
+                "  destField: [#{hop.destination_fields.map { |field| quote(field) }.join(', ')}],",
+                "}"
+              ].join("\n")
+            end.join(", ")
+
+            "#{property_name(relationship.name)}: #{relationship.kind}(#{hops}),"
           end.join("\n")
 
           [
@@ -119,7 +135,7 @@ module ZeroRailsAdapter
 
       def schema_export
         table_vars = models.map { |model| variable_name(model) }.join(", ")
-        relation_vars = relationships.map(&:first).uniq.map do |model|
+        relation_vars = relationships.map(&:source).uniq.map do |model|
           relationship_variable_name(model)
         end.join(", ")
 
@@ -140,7 +156,7 @@ module ZeroRailsAdapter
       end
 
       def argument_schemas
-        models.flat_map do |model|
+        crud_models.flat_map do |model|
           [
             zod_schema(model, :create),
             zod_schema(model, :update),
@@ -162,7 +178,7 @@ module ZeroRailsAdapter
       end
 
       def mutator_export
-        tables = models.map do |model|
+        tables = crud_models.map do |model|
           variable = variable_name(model)
           table = property_name(model.table_name)
           create_values = create_insert_values(model)
@@ -193,8 +209,8 @@ module ZeroRailsAdapter
 
       def create_insert_values(model)
         additions = []
-        additions << "created_at: now" if model.column_names.include?("created_at")
-        additions << "updated_at: now" if model.column_names.include?("updated_at")
+        additions << "created_at: now" if published_column?(model, "created_at")
+        additions << "updated_at: now" if published_column?(model, "updated_at")
         defaulted_columns(model).each do |column|
           value = if generated_attribute_names(model, :create).include?(column.name)
             "args.#{property_name(column.name)} ?? #{typescript_default(column)}"
@@ -208,7 +224,7 @@ module ZeroRailsAdapter
 
       def update_insert_values(model)
         additions = []
-        additions << "updated_at: Date.now()" if model.column_names.include?("updated_at")
+        additions << "updated_at: Date.now()" if published_column?(model, "updated_at")
         object_with_additions(additions)
       end
 
@@ -220,21 +236,24 @@ module ZeroRailsAdapter
 
       def mutation_columns(model, action)
         primary = primary_keys(model)
+        immutable = (primary + Array(model.primary_key).compact.map(&:to_s)).uniq
         case action
         when :create
           allowed = generated_attribute_names(model, action)
-          model.columns.select do |column|
+          columns_for(model).select do |column|
             !timestamp_column?(column) &&
               (primary.include?(column.name) || allowed.include?(column.name))
           end
         when :update
           allowed = generated_attribute_names(model, action)
-          model.columns.select do |column|
+          columns_for(model).select do |column|
             primary.include?(column.name) ||
-              (!timestamp_column?(column) && allowed.include?(column.name))
+              (!immutable.include?(column.name) &&
+                !timestamp_column?(column) &&
+                allowed.include?(column.name))
           end
         when :destroy
-          model.columns.select { |column| primary.include?(column.name) }
+          columns_for(model).select { |column| primary.include?(column.name) }
         end
       end
 
@@ -250,7 +269,7 @@ module ZeroRailsAdapter
 
       def defaulted_columns(model)
         primary = primary_keys(model)
-        model.columns.select do |column|
+        columns_for(model).select do |column|
           !primary.include?(column.name) &&
             !timestamp_column?(column) &&
             !column.null &&
@@ -264,7 +283,7 @@ module ZeroRailsAdapter
           return column.null ? "#{type}.optional()" : type
         end
 
-        type = enum_values(model, column)&.then do |values|
+        type = native_enum_values(model, column)&.then do |values|
           "enumeration<#{values.map { |value| quote(value) }.join(' | ')}>()"
         end
         type ||= mapped_type(SCHEMA_TYPES, model, column)
@@ -273,7 +292,7 @@ module ZeroRailsAdapter
       end
 
       def zod_type(model, column, action)
-        values = enum_values(model, column)
+        values = native_enum_values(model, column)
         type = if column.respond_to?(:array) && column.array
           "z.array(#{mapped_type(ZOD_TYPES, model, column)})"
         elsif values
@@ -300,18 +319,24 @@ module ZeroRailsAdapter
         end
       end
 
-      def enum_values(model, column)
+      def native_enum_values(model, column)
+        return unless column.type.to_sym == :enum
+
         definition = model.defined_enums[column.name]
-        definition&.keys
+        return definition.keys if definition
+
+        enum_types = model.connection.enum_types.to_h
+        enum_types[column.sql_type] ||
+          raise(UnsupportedColumnTypeError,
+            "Cannot read PostgreSQL enum values for #{model.name}.#{column.name}")
       end
 
       def schema_imports
         imports = %w[createSchema table]
         imports << "relationships" if relationships.any?
-        imports << "enumeration" if models.any? { |model| model.defined_enums.any? }
         models.each do |model|
-          model.columns.each do |column|
-            imports << if enum_values(model, column)
+          columns_for(model).each do |column|
+            imports << if native_enum_values(model, column)
               "enumeration"
             elsif column.respond_to?(:array) && column.array
               "json"
@@ -334,14 +359,42 @@ module ZeroRailsAdapter
       end
 
       def relationships
-        @relationships ||= models.flat_map do |model|
-          model.reflect_on_all_associations.filter_map do |reflection|
-            next if reflection.polymorphic? || reflection.options[:through]
-
-            destination = reflection.klass
-            [model, reflection, destination] if models.include?(destination)
-          rescue NameError
-            nil
+        @relationships ||= begin
+          automatic = models.flat_map do |model|
+            model.reflect_on_all_associations.filter_map do |reflection|
+              next if reflection.polymorphic? || reflection.options[:through]
+
+              destination = reflection.klass
+              next unless models.include?(destination)
+
+              source_fields, destination_fields =
+                relationship_fields(model, reflection, destination)
+              if source_fields.all? { |field| published_column?(model, field) } &&
+                  destination_fields.all? { |field| published_column?(destination, field) }
+                Relationship.new(
+                  source: model,
+                  name: reflection.name,
+                  kind: reflection.collection? ? :many : :one,
+                  hops: [{
+                    source_fields:,
+                    destination:,
+                    destination_fields:
+                  }],
+                  published_schema: @published_schema
+                )
+              end
+            rescue NameError
+              nil
+            end
+          end
+
+          manual_keys = @manual_relationships.map do |relationship|
+            [relationship.source, relationship.name]
+          end
+          (automatic.reject do |relationship|
+            manual_keys.include?([relationship.source, relationship.name])
+          end + @manual_relationships).sort_by do |relationship|
+            [relationship.source.table_name, relationship.name]
           end
         end
       end
@@ -366,10 +419,15 @@ module ZeroRailsAdapter
       end
 
       def primary_keys(model)
-        keys = Array(model.primary_key).compact.map(&:to_s)
-        return keys if keys.any?
+        @published_schema.zero_keys_for(model)
+      end
+
+      def columns_for(model)
+        @published_schema.columns_for(model)
+      end
 
-        raise UnsupportedColumnTypeError, "#{model.name} has no primary key"
+      def published_column?(model, name)
+        columns_for(model).any? { |column| column.name == name.to_s }
       end
 
       def relationship_variable_name(model)

data/lib/zero_rails_adapter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZeroRailsAdapter
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/zero_rails_adapter.rb

@@ -11,6 +11,8 @@ require_relative "zero_rails_adapter/errors"
 require_relative "zero_rails_adapter/identity"
 require_relative "zero_rails_adapter/context"
 require_relative "zero_rails_adapter/configuration"
+require_relative "zero_rails_adapter/published_schema"
+require_relative "zero_rails_adapter/relationship"
 require_relative "zero_rails_adapter/request_verifiers/api_key"
 require_relative "zero_rails_adapter/registry"
 require_relative "zero_rails_adapter/mutator"
@@ -18,6 +20,7 @@ require_relative "zero_rails_adapter/mutation"
 require_relative "zero_rails_adapter/request"
 require_relative "zero_rails_adapter/crud/dispatcher"
 require_relative "zero_rails_adapter/type_script/generator"
+require_relative "zero_rails_adapter/postgresql/publication_generator"
 require_relative "zero_rails_adapter/storage/zero_schema"
 require_relative "zero_rails_adapter/processor"
 require_relative "zero_rails_adapter/engine"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zero-rails-adapter
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Zero Rails Adapter contributors
@@ -46,6 +46,7 @@ files:
 - lib/generators/zero_rails_adapter/install/templates/initializer.rb
 - lib/generators/zero_rails_adapter/mutator/mutator_generator.rb
 - lib/generators/zero_rails_adapter/mutator/templates/mutator.rb
+- lib/generators/zero_rails_adapter/publication/publication_generator.rb
 - lib/generators/zero_rails_adapter/typescript/typescript_generator.rb
 - lib/zero_rails_adapter.rb
 - lib/zero_rails_adapter/configuration.rb
@@ -56,8 +57,11 @@ files:
 - lib/zero_rails_adapter/identity.rb
 - lib/zero_rails_adapter/mutation.rb
 - lib/zero_rails_adapter/mutator.rb
+- lib/zero_rails_adapter/postgresql/publication_generator.rb
 - lib/zero_rails_adapter/processor.rb
+- lib/zero_rails_adapter/published_schema.rb
 - lib/zero_rails_adapter/registry.rb
+- lib/zero_rails_adapter/relationship.rb
 - lib/zero_rails_adapter/request.rb
 - lib/zero_rails_adapter/request_verifiers/api_key.rb
 - lib/zero_rails_adapter/storage/zero_schema.rb