trane 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0fabf8d80352adbe88869422f34a1b246b78b32518fc2af532520ca6c9b42de6
+  data.tar.gz: 2c72a84965aacb8bff923af520882d8683a6e33f286760935da57296e8556395
+SHA512:
+  metadata.gz: b5a40834b40f735228410ae3a4f65d464cc305a291306dd5fecb28f55c54f4aca7c6d576899aed158bdc60b55ed0e51a7686c39aa5c6fdd375defde1ab2e4d8e
+  data.tar.gz: e8de68a5e64d089111e37ef49f7949a960ff4fe748fcd01b12fc1fda6ef5a094f7a394a328429ddf9d83e24e6b5dadc483d99a867a16eeebc58014efa05e097b

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-14
+
+First public release.
+
+### Added
+
+- Contract DSL: `Trane.operation`, `Trane.representation`, and `Trane.errors`
+  for declaring API contracts as code, auto-loaded from `app/api_contract/`
+  (configurable via `config.trane.contracts_paths`).
+- `render contract:` controller integration with deterministic serialization:
+  responses contain exactly the declared fields (extra `extra: true` fields
+  are client-opt-in via `extra_attributes[]`).
+- Structured error handling: raised exceptions map to a registered error
+  catalog and render a consistent JSON error envelope; unhandled exceptions
+  are reported through `Rails.error` and logged before rendering a generic
+  500 (verbose details only in local environments).
+- Strict contract validation (`:raise` / `:log` / `:ignore`, auto-detected by
+  environment): missing keys, undeclared keys, and composite values in scalar
+  leaf fields.
+- Boot-time validation of contract referential integrity, route `contract:`
+  metadata validation with "did you mean" hints, and a `trane:check` rake
+  task.
+- Auto-generated documentation (HTML + Service Definition JSON) served by a
+  mountable engine, cached per boot/reload.
+- Fail-closed defaults: `render contract:` on a route without contract
+  metadata raises by default (`on_missing_operation` opt-out), and
+  configuration setters reject unknown modes.
+
+[0.1.0]: https://github.com/thisisqubika/trane/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Qubika
+
+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,151 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/thisisqubika/trane/main/docs/trane-logo.png" width="380" alt="Trane logo">
+</p>
+
+# Trane
+
+[![CI](https://github.com/thisisqubika/trane/actions/workflows/ci.yml/badge.svg)](https://github.com/thisisqubika/trane/actions/workflows/ci.yml)
+
+Contract enforcement and documentation layer for Rails APIs.
+
+Declare your API's contract — operations, representations, errors — as code,
+and Trane takes it from there:
+
+- **Deterministic serialization**: responses contain exactly the fields the
+  contract declares, nothing more. No accidental `password_digest` in a JSON.
+- **Contract validation**: drift between what you declared and what you serve
+  fails loud in development and gets logged in production.
+- **Structured error handling**: raise your domain exceptions; clients get a
+  consistent JSON error envelope with the right status code.
+- **Auto-generated documentation**: polished HTML + machine-readable JSON,
+  always in sync with the contract, served from a mountable engine.
+
+## Installation
+
+Add Trane to your Gemfile:
+
+```ruby
+gem "trane"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Supported versions
+
+| Component | Versions |
+|---|---|
+| Ruby | >= 3.2 |
+| Rails | 7.2, 8.0, 8.1 |
+
+## Quick Start
+
+**1. Define your error catalog** — `app/api_contract/errors.rb`:
+
+```ruby
+Trane.errors do
+  error :UserNotFound, status_code: 404, description: "User not found"
+end
+```
+
+**2. Define a representation** — `app/api_contract/representations/user.rb`:
+
+```ruby
+Trane.representation :user do
+  field :id,    type: :integer
+  field :name,  type: :string
+  field :email, type: :string
+end
+```
+
+**3. Define an operation** — `app/api_contract/operations/users.rb`:
+
+```ruby
+Trane.operation :get_user do
+  summary "Get a user by id"
+
+  request do
+    path :id, type: :integer
+  end
+
+  response 200 do
+    field :user, type: :user
+  end
+
+  errors do
+    key :UserNotFound
+  end
+end
+```
+
+**4. Include the controller concern** (in your API base controller):
+
+```ruby
+class ApplicationController < ActionController::API
+  include Trane::Controller
+end
+```
+
+**5. Render through the contract**:
+
+```ruby
+class UsersController < ApplicationController
+  def show
+    @user = User.find(params[:id])
+    render contract: { user: @user }
+  rescue ActiveRecord::RecordNotFound
+    raise UserNotFound
+  end
+end
+```
+
+**6. Wire the route to the operation** — `config/routes.rb`:
+
+```ruby
+get "/users/:id", to: "users#show", contract: { operation: :get_user }
+```
+
+That's it. `GET /users/1` now serves exactly the declared fields, and a
+missing user renders `{"errors":[{"key":"UserNotFound","message":"User not
+found"}]}` with a 404.
+
+**Optional — mount the documentation endpoints**:
+
+```ruby
+# config/routes.rb
+unless Rails.env.production?
+  mount Trane::Engine, at: "/my-api/docs"
+end
+```
+
+`GET /my-api/docs` serves the HTML documentation and `/my-api/docs.json` the
+machine-readable service definition. The docs expose your full API surface —
+see [securing the docs endpoint](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Documentation-Endpoints.md#securing-the-docs-endpoint)
+before mounting in production.
+
+## Documentation
+
+The full guides live in the wiki:
+
+| Guide | What it covers |
+|---|---|
+| [Configuration](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Configuration.md) | Options, contract file locations and loading order, lifecycle, testing helper |
+| [Representations](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Representations.md) | Fields, formats, arrays, references, passthrough |
+| [Operations](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Operations.md) | Request DSL (path/query/body), response DSL, error keys |
+| [Error Handling](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Error-Handling.md) | Error catalog, exception matching, response envelope, unhandled errors |
+| [Controller Integration](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Controller-Integration.md) | The mixins, `render contract:`, status mapping, raising errors |
+| [Routes](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Routes.md) | The `contract:` route keyword |
+| [Serialization](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Serialization.md) | Value extraction, nil handling, nesting |
+| [Extra Attributes](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Extra-Attributes.md) | Optional fields clients opt into per request |
+| [Validation](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Validation.md) | Strict response validation, boot-time checks, `trane:check` |
+| [Documentation Endpoints](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Documentation-Endpoints.md) | Mounting, securing, the Service Definition JSON |
+| [Field Types Reference](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Field-Types-Reference.md) | Every type, option, and declaration variant |
+| [Architecture](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Architecture.md) | Process-level state, concurrency model, legacy API |
+| [Complete Example](https://github.com/thisisqubika/trane/blob/main/docs/wiki/Complete-Example.md) | A full CRUD example, end to end |
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/tasks/trane.rake

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+namespace :trane do
+  desc "Validate Trane contract registry (load files + cross-reference check)"
+  task check: :environment do
+    Trane::Registry.validate!
+
+    Rails.application.reload_routes_unless_loaded
+    Trane::RouteValidator.validate!(Rails.application.routes.routes, Trane.registry)
+
+    ops = Trane::Registry.operations.size
+    reps = Trane::Registry.representations.size
+    errs = Trane::Registry.errors.size
+    puts "OK - Trane registry validates clean (#{ops} operations, #{reps} representations, #{errs} errors); " \
+         "route/registry cross-check passed."
+  end
+end

data/lib/trane/boot_validator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Trane
+  class BootValidator
+    # Validate referential integrity of the registry.
+    # Ensures that all representation references in operations exist,
+    # and all error keys referenced by operations are registered.
+    # Consumes the precomputed errors_by_name index from the snapshot.
+    #
+    # @param registry [Module] Trane::Registry
+    # @raise [Trane::Error] if any references are invalid
+    def self.validate!(registry)
+      errors         = []
+      errors_by_name = registry.errors_by_name
+
+      registry.operations.each do |op_name, op|
+        op.responses.each do |status, resp|
+          resp.fields.each do |field|
+            errors.concat(validate_field_references(field, registry, context: "operation :#{op_name} response #{status}"))
+          end
+        end
+
+        op.error_keys.each do |key|
+          key_str = key.to_s
+          next if errors_by_name.key?(key_str)
+
+          errors << "operation :#{op_name} references error :#{key}, but no such error is registered"
+        end
+      end
+
+      return if errors.empty?
+
+      raise Trane::Error, "Trane boot validation failed:\n  #{errors.join("\n  ")}"
+    end
+
+    class << self
+      private
+
+      def validate_field_references(field, registry, context:, path: [])
+        errors = []
+        joined_path = (path + [ field.name ]).join(".")
+
+        if field.type && Types.representation_reference?(field.type)
+          unless registry.representations.key?(field.type)
+            errors << "#{context}: field :#{joined_path} references representation :#{field.type}, which does not exist"
+          end
+        end
+
+        if field.array_of && Types.representation_reference?(field.array_of)
+          unless registry.representations.key?(field.array_of)
+            errors << "#{context}: field :#{joined_path} has array of :#{field.array_of}, which does not exist as a representation"
+          end
+        end
+
+        child_path = path + [ field.name ]
+        field.children.each do |child|
+          errors.concat(validate_field_references(child, registry, context: context, path: child_path))
+        end
+
+        errors
+      end
+    end
+  end
+end

data/lib/trane/configuration.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Trane
+  class Configuration
+    # Default contracts paths resolved relative to the Rails application root.
+    # Hosts that need a different location should set
+    # `config.trane.contracts_paths` in `config/application.rb`.
+    DEFAULT_CONTRACTS_PATHS = [ "app/api_contract" ].freeze
+
+    # Valid strict_mode values (nil is also accepted: auto-detect by env).
+    STRICT_MODES = %i[raise log ignore].freeze
+
+    # Valid modes for on_missing_operation (what `render contract:` does when
+    # the route did not declare `contract: { operation: ... }`).
+    ON_MISSING_OPERATION_MODES = %i[raise log fallback].freeze
+
+    attr_reader :strict_mode
+
+    # Returns the process-level Configuration instance via the Trane shim.
+    # Existing call sites (Trane::Configuration.instance.X) continue to work.
+    def self.instance
+      Trane.configuration
+    end
+
+    def initialize
+      reset!
+    end
+
+    # Marks the configuration as frozen. Subsequent setter calls raise
+    # FrozenError. Called by the Engine after :load_config_initializers
+    # so that runtime code cannot mutate config from another thread or
+    # request.
+    def freeze!
+      @frozen = true
+    end
+
+    def frozen_config?
+      @frozen
+    end
+
+    # Rejects unknown modes at assignment time: an unrecognized value would
+    # otherwise fall outside every consumer's case statement and silently
+    # disable contract validation (fail-open by typo).
+    def strict_mode=(value)
+      raise FrozenError, "Trane::Configuration is frozen; cannot modify strict_mode after boot" if @frozen
+      unless value.nil? || STRICT_MODES.include?(value)
+        raise Trane::Error,
+              "strict_mode must be nil (auto-detect) or one of " \
+              "#{STRICT_MODES.map(&:inspect).join(', ')} (got #{value.inspect})"
+      end
+      @strict_mode = value
+    end
+
+    # What `render contract:` does when the route did not declare
+    # `contract: { operation: ... }` (so no contract can be resolved):
+    #
+    #   :raise    — fail loud with Trane::Error (default). Without a contract
+    #               the field filtering cannot run, and serving the data
+    #               unserialized would expose every attribute of the object.
+    #   :log      — serve the data unserialized, logging a warning per request.
+    #   :fallback — serve the data unserialized, silently.
+    def on_missing_operation
+      @on_missing_operation || :raise
+    end
+
+    def on_missing_operation=(value)
+      raise FrozenError, "Trane::Configuration is frozen; cannot modify on_missing_operation after boot" if @frozen
+      unless ON_MISSING_OPERATION_MODES.include?(value)
+        raise Trane::Error,
+              "on_missing_operation must be one of #{ON_MISSING_OPERATION_MODES.map(&:inspect).join(', ')} " \
+              "(got #{value.inspect})"
+      end
+      @on_missing_operation = value
+    end
+
+    # Returns the effective strict mode for the current environment.
+    #
+    # @return [Symbol] :raise, :log, or :ignore
+    def effective_strict_mode
+      return @strict_mode if @strict_mode
+
+      if defined?(Rails)
+        case Rails.env.to_s
+        when "development", "test" then :raise
+        when "production" then :log
+        else :log
+        end
+      else
+        :raise
+      end
+    end
+
+    # Returns the configured contracts paths, falling back to DEFAULT_CONTRACTS_PATHS
+    # when none have been explicitly set.
+    #
+    # To override, set `config.trane.contracts_paths = [...]` in
+    # `config/application.rb` — NOT in `config/initializers/trane.rb`, which
+    # runs too late for the Engine's `trane.ignore_autoload_paths` initializer.
+    def contracts_paths
+      @contracts_paths || DEFAULT_CONTRACTS_PATHS
+    end
+
+    # Internal — populated by the Engine from app.config.trane.contracts_paths.
+    # Host code should use `config.trane.contracts_paths = [...]` in
+    # config/application.rb, NOT call this method directly.
+    def _set_contracts_paths!(value)
+      raise FrozenError, "Trane::Configuration is frozen; cannot modify contracts_paths after boot" if @frozen
+      raise Trane::Error, "contracts_paths must be an Array" unless value.is_a?(Array)
+      raise Trane::Error, "contracts_paths must not be empty" if value.empty?
+      value.each_with_index do |entry, i|
+        raise Trane::Error, "contracts_paths[#{i}] must be a String or Pathname" unless entry.is_a?(String) || entry.is_a?(Pathname)
+        str = entry.to_s
+        raise Trane::Error, "contracts_paths[#{i}] must not be blank" if str.strip.empty?
+        raise Trane::Error, "contracts_paths[#{i}]: glob patterns are not supported" if str.match?(/[*?]/)
+      end
+      @contracts_paths = value.map(&:to_s)
+    end
+
+    def reset!
+      @strict_mode          = nil
+      @contracts_paths      = nil
+      @on_missing_operation = nil
+      @frozen               = false
+    end
+
+    # Internal — full state snapshot/restore for Trane::Testing.
+    # Lives here, next to the ivars it enumerates, so adding a new
+    # configuration attribute forces updating this list in the same file
+    # (instead of silently losing it across a with_configuration block).
+    def _dump_state
+      {
+        strict_mode:          @strict_mode,
+        contracts_paths:      @contracts_paths,
+        on_missing_operation: @on_missing_operation,
+        frozen:               @frozen
+      }
+    end
+
+    def _restore_state!(state)
+      @strict_mode          = state[:strict_mode]
+      @contracts_paths      = state[:contracts_paths]
+      @on_missing_operation = state[:on_missing_operation]
+      @frozen               = state[:frozen]
+    end
+  end
+end

data/lib/trane/contract_loader.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Trane
+  # Single source of truth for the contract-file load order, used by both
+  # the Engine's to_prepare block and any test harness that replays the
+  # boot-time load (spec/integration/integration_helper.rb) — keeping the
+  # two from silently diverging.
+  #
+  # Order:
+  #   Phase 1 — every errors.rb from every base path (in declaration order).
+  #   Phase 2 — all other .rb files from every base path (sorted within each).
+  module ContractLoader
+    # Yields the absolute path (String) of each contract file in load order.
+    #
+    # @param root [Pathname] the application root (e.g. Rails.root)
+    # @param contracts_paths [Array<String>] base paths relative to root
+    def self.each_file(root, contracts_paths)
+      errors_files = contracts_paths.map { |path| root.join(path, "errors.rb") }
+      errors_files.each { |file| yield file.to_s if file.exist? }
+
+      contracts_paths.each_with_index do |path, i|
+        errors_file = errors_files[i].to_s
+        Dir[root.join(path, "**/*.rb")].sort.each do |file|
+          yield file unless file == errors_file
+        end
+      end
+    end
+  end
+end

data/lib/trane/contract_validator.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Trane
+  class ContractViolation < Trane::Error; end
+
+  class ContractValidator
+    # Validate that a serialized result conforms to the response definition.
+    #
+    # @param response_def [ResponseDefinition]
+    # @param result [Hash] the serialized output
+    # @param registry [Module] Trane::Registry
+    # @param mode [Symbol] :raise or :log
+    def self.validate_response!(response_def, result, registry, mode:)
+      violations = collect_violations(response_def.fields, result, registry, prefix: "")
+      return if violations.empty?
+
+      message = "Trane contract violations (status #{response_def.status}):\n  #{violations.join("\n  ")}"
+      case mode
+      when :raise
+        raise ContractViolation, message
+      when :log
+        Trane.log_warning(message)
+      end
+    end
+
+    class << self
+      private
+
+      def collect_violations(fields, result, registry, prefix:)
+        violations = []
+
+        declared_keys = registry.validator_declared_field_names_for(fields)
+
+        # Check for missing declared (non-extra) keys
+        declared_keys.each do |key|
+          unless result.key?(key)
+            violations << "#{format_path(prefix, key)}: missing from response"
+          end
+        end
+
+        # Check for undeclared keys
+        allowed_keys = registry.validator_field_names_for(fields)
+        result.each_key do |key|
+          unless allowed_keys.include?(key)
+            violations << "#{format_path(prefix, key)}: undeclared field in response"
+          end
+        end
+
+        # Recurse into representation fields; flag composite values that
+        # landed in scalar leaves
+        fields.each do |field|
+          value = result[field.name]
+          next if value.nil?
+
+          rep = registry.representations[field.type] if field.type
+          if rep && value.is_a?(Hash)
+            child_prefix = format_path(prefix, field.name)
+            violations.concat(collect_violations(rep.fields, value, registry, prefix: child_prefix))
+          elsif composite_scalar_violation?(field, value)
+            violations << "#{format_path(prefix, field.name)}: composite #{value.class} value " \
+                          "in scalar field (declared type :#{field.type})"
+          end
+        end
+
+        violations
+      end
+
+      # A Hash or Array in a field declared as a scalar leaf means the
+      # caller passed a composite object where a value was expected — the
+      # serializer emits leaf values verbatim, so the whole object (every
+      # attribute, e.g. a full model as_json) would reach the client.
+      # Only scalar leaf types are checked: :object is free-form by
+      # declaration, :array carries Arrays, representation-typed fields
+      # recurse above, and fields with children are structurally filtered
+      # by the serializer.
+      def composite_scalar_violation?(field, value)
+        return false unless Types::ENUMERABLE_TYPES.include?(field.type)
+        return false unless field.children.nil? || field.children.empty?
+
+        value.is_a?(Hash) || value.is_a?(Array)
+      end
+
+      def format_path(prefix, key)
+        prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+      end
+    end
+  end
+end