trane 0.1.0

data/lib/trane/controller/error_handler.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Trane
+  module Controller
+    # Mixin that captures StandardError subclasses and maps them to
+    # registered Trane errors. Resolves the exception class via the
+    # precomputed errors_by_name index on the Registry snapshot —
+    # single lookup on FQDN match, with a short-name fallback (via
+    # String#rpartition) for hosts that registered errors by short
+    # name. Include in your API base controller. Does NOT add
+    # `render contract:` support — combine with Trane::Controller::Renderer
+    # or use the composer Trane::Controller.
+    #
+    # WARNING: this installs rescue_from StandardError at the class
+    # level. Including in a base controller that also serves HTML
+    # would catch errors Devise / Pundit / etc. expect to bubble up.
+    # Recommended: include only in API base controllers.
+    #
+    # Rails-reserved exceptions (those in
+    # ActionDispatch::ExceptionWrapper.rescue_responses, e.g.
+    # ActiveRecord::RecordNotFound → 404, ActionController::ParameterMissing → 400)
+    # are re-raised when no Trane error is registered for them, so Rails'
+    # exception middleware applies its default status mapping. Hosts that
+    # want to swallow these into the Trane envelope can register them
+    # explicitly via `Trane.errors { error "ActiveRecord::RecordNotFound", ... }`;
+    # the Trane lookup wins over the re-raise path.
+    #
+    # SECURITY NOTE: a registered error's envelope carries the exception's
+    # runtime #message, in EVERY environment including production. Framework
+    # and library exception messages are written for logs and may reveal
+    # internals (model names, query conditions). Prefer the recommended
+    # pattern (docs/wiki/Error-Handling.md) — rescue the framework exception
+    # and raise a domain error with a curated message — and register framework
+    # exceptions directly only when their messages are acceptable to expose.
+    #
+    # PRODUCTION NOTE: re-raised exceptions surface via Rails' default
+    # middleware. Keep `config.consider_all_requests_local = false` in
+    # production so `ActionDispatch::ShowExceptions` serves the static
+    # `public/404.html` / `500.html` pages. With `consider_all_requests_local`
+    # enabled in production, `ActionDispatch::DebugExceptions` would expose
+    # the exception class + message + backtrace.
+    module ErrorHandler
+      extend ActiveSupport::Concern
+
+      included do
+        rescue_from StandardError, with: :_trane_handle_error
+      end
+
+      # Returns the frozen Set of Rails-reserved exception class NAMES
+      # (Strings) derived from ActionDispatch::ExceptionWrapper.rescue_responses.
+      # Memoized on first call (after Rails boot completes). Returns an empty
+      # Set when Rails is not loaded.
+      #
+      # Names, not Class objects, on purpose: memoizing classes would pin
+      # host-registered (Zeitwerk-reloadable) exception constants in the gem
+      # forever, and after a development reload the stale Class would no
+      # longer match its reloaded replacement. Names survive reloads.
+      #
+      # NOTE: callers MUST invoke this post-boot. The Rails Engine initializers
+      # merge AR/AC entries into `rescue_responses` during boot; calling this
+      # earlier would memoize an incomplete list. In practice the first error
+      # arrives in a request thread, which is always post-boot — but tests or
+      # explicit pre-boot invocations would have to reset @rails_reserved_names
+      # afterwards.
+      def self.rails_reserved_names
+        @rails_reserved_names ||= begin
+          if defined?(ActionDispatch::ExceptionWrapper)
+            Set.new(ActionDispatch::ExceptionWrapper.rescue_responses.keys.grep(String)).freeze
+          else
+            Set.new.freeze
+          end
+        end
+      end
+
+      private
+
+      def _trane_handle_error(exception)
+        klass = exception.class
+        return _trane_unhandled_error(exception) unless klass.name
+
+        index     = Trane.registry.errors_by_name
+        error_def = index[klass.name] || _trane_short_name_match(index, klass)
+
+        if error_def
+          render(
+            json: { errors: [ { key: error_def.key.to_s, message: exception.message } ] },
+            status: error_def.status_code
+          )
+        elsif _trane_rails_reserved?(klass)
+          raise exception
+        else
+          _trane_unhandled_error(exception)
+        end
+      end
+
+      # rescue_from handles the exception BEFORE Rails' exception-reporting
+      # middleware can see it, so without this hook a 500 in production
+      # would leave no trace at all: no log line, no stacktrace, and no
+      # event in middleware-based error trackers. Report through
+      # Rails.error (the ErrorReporter interface trackers subscribe to)
+      # and write the class + message + backtrace to the log.
+      def _trane_report_unhandled(exception)
+        return unless defined?(Rails)
+
+        if Rails.respond_to?(:error) && Rails.error
+          Rails.error.report(exception, handled: true, source: "trane")
+        end
+
+        if Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.error(
+            "[Trane] unhandled #{exception.class}: #{exception.message}\n" \
+            "#{Array(exception.backtrace).first(20).join("\n")}"
+          )
+        end
+      end
+
+      # Short-name fallback, restricted to errors REGISTERED by short name.
+      # The errors_by_name index also aliases FQDN registrations under their
+      # demodulized name (BootValidator resolves operation error_keys through
+      # those aliases), but matching here through an alias would let an
+      # unrelated exception (SomeGem::UserNotFound) hijack a registered
+      # Errors::UserNotFound and send a foreign library's message to the
+      # client — FQDN registrations must match exactly.
+      def _trane_short_name_match(index, klass)
+        short     = klass.name.rpartition("::").last
+        candidate = index[short]
+        candidate if candidate && candidate.key == short
+      end
+
+      def _trane_rails_reserved?(klass)
+        names = ErrorHandler.rails_reserved_names
+        return false if names.empty?
+
+        klass.ancestors.any? { |ancestor| names.include?(ancestor.name) }
+      end
+
+      # Verbose output is allow-listed to LOCAL environments (development
+      # and test, via Rails.env.local?) rather than deny-listed against
+      # production: a custom environment (staging, uat, preprod) must get
+      # the generic message by default. Exception messages are written by
+      # libraries that assume a log audience — they can carry SQL, record
+      # values, or internal hostnames — and this rescue_from renders before
+      # Rails' exception middleware, so the host's
+      # consider_all_requests_local setting cannot protect these responses.
+      def _trane_unhandled_error(exception)
+        _trane_report_unhandled(exception)
+
+        if defined?(Rails) && Rails.env.local?
+          render(
+            json: {
+              errors: [ {
+                key: "InternalServerError",
+                message: "#{exception.class}: #{exception.message}"
+              } ]
+            },
+            status: :internal_server_error
+          )
+        else
+          render(
+            json: { errors: [ { key: "InternalServerError", message: "An unexpected error occurred" } ] },
+            status: :internal_server_error
+          )
+        end
+      end
+    end
+  end
+end

data/lib/trane/controller/renderer.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "json"
+require "rack/utils"
+
+module Trane
+  module Controller
+    # Mixin that adds `render contract: data` support to a controller.
+    # Include in your API base controller (e.g. Api::BaseController <
+    # ActionController::API). Does NOT install any rescue_from handlers —
+    # combine with Trane::Controller::ErrorHandler or use the composer
+    # Trane::Controller for both.
+    #
+    # Caveat: if the including class also `prepend`s a custom `#render`,
+    # the prepended one runs first; chain via `super` to reach this one.
+    module Renderer
+      extend ActiveSupport::Concern
+
+      def render(options = nil, extra_options = {}, &block)
+        if options.is_a?(Hash) && options.key?(:contract)
+          if extra_options.is_a?(Hash) && extra_options.key?(:callback)
+            raise ArgumentError,
+                  "Trane: render contract: does not support :callback (JSONP). " \
+                  "Use render json: directly if JSONP is required."
+          end
+
+          contract_data = options[:contract]
+          status        = options[:status] || :ok
+          status_int    = ::Rack::Utils.status_code(status)
+
+          op_name = _trane_operation_name
+          unless op_name
+            # The route did not inject _trane_operation, so no contract can
+            # be resolved and the field filtering cannot run. Serving the
+            # data unserialized would expose every attribute of the object
+            # (fail-open on the gem's only field filter), so the default is
+            # to fail loud, consistent with the unknown-operation and
+            # missing-response paths below. Hosts opt into the old behavior
+            # via config.on_missing_operation = :log / :fallback.
+            case Trane.configuration.on_missing_operation
+            when :fallback
+              return super(json: contract_data, status: status, **extra_options, &block)
+            when :log
+              _trane_log_missing_operation
+              return super(json: contract_data, status: status, **extra_options, &block)
+            else
+              raise Trane::Error,
+                    "Trane: render contract: was called but the route did not declare a contract, " \
+                    "so the response cannot be serialized or filtered. " \
+                    "Add `contract: { operation: :<operation_name> }` to this route in routes.rb, " \
+                    "or set `config.on_missing_operation` to :log or :fallback to serve the data unserialized."
+            end
+          end
+
+          registry = Trane.registry
+
+          op = registry.operations[op_name]
+          unless op
+            raise Trane::Error,
+                  "Trane: no operation registered for '#{op_name}'. " \
+                  "Define it with Trane.operation(:#{op_name}) { ... }"
+          end
+
+          response_def = op.responses[status_int]
+          unless response_def
+            raise Trane::Error,
+                  "Trane: operation '#{op_name}' has no response defined for status #{status_int}."
+          end
+
+          extra_attrs = ExtraAttributesFilter.parse(params)
+          strict      = Trane.configuration.effective_strict_mode
+          serializer  = registry.compiled_serializer_for(response_def, strict)
+          hash        = serializer.serialize(contract_data, extra_attributes: extra_attrs)
+
+          body = ::JSON.generate(hash)
+          super(
+            plain: body,
+            status: status,
+            content_type: extra_options.fetch(:content_type, "application/json; charset=utf-8"),
+            **extra_options.except(:content_type),
+            &block
+          )
+        else
+          super
+        end
+      end
+
+      private
+
+      def _trane_operation_name
+        op = request.path_parameters[:_trane_operation]
+        op&.to_sym
+      end
+
+      def _trane_log_missing_operation
+        Trane.log_warning(
+          "[Trane] render contract: called on a route without contract metadata; " \
+          "serving unserialized JSON. Add `contract: { operation: ... }` to the route in routes.rb."
+        )
+      end
+    end
+  end
+end

data/lib/trane/controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "controller/renderer"
+require_relative "controller/error_handler"
+
+module Trane
+  # Convenience composer that includes both Trane::Controller::Renderer
+  # and Trane::Controller::ErrorHandler. Use this when you want both
+  # behaviors. For finer control (e.g., render override without the
+  # rescue_from), include the submodules directly.
+  #
+  # WARNING: include this only in API-specific base controllers (e.g.
+  # Api::BaseController < ActionController::API). The ErrorHandler
+  # piece captures StandardError subclasses globally — including in
+  # ApplicationController of an app that mixes HTML/JSON would
+  # intercept exceptions Devise / Pundit / etc. expect to bubble up.
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      include Renderer
+      include ErrorHandler
+    end
+  end
+end

data/lib/trane/docs/app.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Trane
+  module Docs
+    # Rack middleware-style app that serves documentation endpoints.
+    # Mounted by the Trane::Engine at the path chosen by the host application.
+    class App
+      def call(env)
+        request = Rack::Request.new(env)
+        if request.path_info.end_with?(".json")
+          serve_json
+        else
+          serve_html
+        end
+      end
+
+      private
+
+      def serve_json
+        [ 200, response_headers("application/json; charset=utf-8"), [ Cache.json ] ]
+      end
+
+      def serve_html
+        [ 200, response_headers("text/html; charset=utf-8"), [ Cache.html ] ]
+      end
+
+      # nosniff keeps browsers from second-guessing the declared MIME type.
+      def response_headers(content_type)
+        {
+          "content-type"           => content_type,
+          "x-content-type-options" => "nosniff"
+        }
+      end
+    end
+  end
+end

data/lib/trane/docs/cache.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Trane
+  module Docs
+    # Memoized JSON + HTML output of the ServiceDefinition. The pair lives
+    # inside a single frozen Snapshot ivar built atomically by
+    # `precompute!`: every Snapshot instance carries a `(json, html)`
+    # pair derived from one ServiceDefinition.generate call, so no
+    # caller can observe a torn pair WITHIN a single snapshot
+    # generation. The previous design wrote `@json` and `@html` in
+    # sequence, leaving a window where a reader saw new JSON paired
+    # with old HTML across a Rails reload.
+    #
+    # Consistency is per-snapshot-instance, not per-call-pair: a thread
+    # that reads `Cache.json` then `Cache.html` may observe two
+    # different snapshots if `precompute!` runs between the two calls.
+    # In production this is unobservable (each Rack request hits ONE of
+    # `/docs.json` or `/docs`, never both), and cross-request
+    # ordering across reloads is out of scope for this module.
+    #
+    # `precompute!` is ALWAYS lazy — triggered by the first `json`/`html`
+    # read via `ensure_snapshot`. Trane::Engine's `to_prepare` block calls
+    # `invalidate!` (not `precompute!`): during `to_prepare` the host routes
+    # are not drawn yet (it runs before the Finisher's
+    # set_routes_reloader_hook, in every environment), so precomputing there
+    # would build a snapshot from an empty route set and every operation would
+    # fall back to method "GET" with an empty path. Deferring to the first
+    # post-boot read — inside a request, with the routes drawn — is what makes
+    # the docs report each operation's real HTTP verb and path. Concurrent
+    # cold readers may both build a snapshot; one assignment wins, the other is
+    # GC'd — wasted work, never inconsistent state.
+    module Cache
+      Snapshot = Data.define(:json, :html)
+
+      class << self
+        def json
+          ensure_snapshot
+          @snapshot&.json
+        end
+
+        def html
+          ensure_snapshot
+          @snapshot&.html
+        end
+
+        # Build a fresh (json, html) Snapshot from the current
+        # ServiceDefinition and swap it in atomically.
+        #
+        # @return [void]
+        def precompute!
+          # The only Rails read in the docs layer: the service name is
+          # Rails.application.name, never Trane configuration.
+          app = Rails.application
+          definition = ServiceDefinition.generate(app.routes.routes, service_name: app.name)
+          @snapshot = Snapshot.new(
+            json: JSON.generate(definition),
+            html: HtmlRenderer.render(definition)
+          )
+          nil
+        end
+
+        def invalidate!
+          @snapshot = nil
+        end
+
+        private
+
+        def ensure_snapshot
+          precompute! if @snapshot.nil?
+        end
+      end
+    end
+  end
+end

data/lib/trane/docs/html_renderer.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Trane
+  module Docs
+    class HtmlRenderer
+      METHOD_COLORS = {
+        "GET" => "#61affe",
+        "POST" => "#49cc90",
+        "PUT" => "#fca130",
+        "PATCH" => "#fca130",
+        "DELETE" => "#f93e3e"
+      }.freeze
+
+      TEMPLATE_PATH = File.expand_path("templates/index.html.erb", __dir__)
+      TEMPLATE      = ERB.new(File.read(TEMPLATE_PATH), trim_mode: "-").freeze
+
+      def self.render(definition)
+        new(definition).to_html
+      end
+
+      def initialize(definition)
+        @definition = definition
+      end
+
+      def to_html
+        TEMPLATE.result(binding)
+      end
+
+      private
+
+      def service
+        @definition[:service]
+      end
+
+      def operations
+        @definition[:operations] || []
+      end
+
+      def representations
+        @definition[:representations] || []
+      end
+
+      def errors
+        @definition[:errors] || []
+      end
+
+      def method_color(method)
+        METHOD_COLORS[method.to_s.upcase] || "#999"
+      end
+
+      def h(text)
+        ERB::Util.html_escape(text.to_s)
+      end
+
+      def representation_link(type_name)
+        type_str = type_name.to_s
+        reps = representations.map { |r| r[:name] }
+        if reps.include?(type_str)
+          "<a href=\"#rep-#{h(type_str)}\" class=\"type-link\">#{h(type_str)}</a>"
+        else
+          "<span class=\"type\">#{h(type_str)}</span>"
+        end
+      end
+
+      def render_field_row(field, indent = 0, include_required: false, buffer: +"")
+        name         = h(field[:name])
+        type         = field[:type] || "object"
+        type_display = if field[:array_of]
+          "array of #{representation_link(field[:array_of])}"
+        else
+          representation_link(type)
+        end
+        extra_badge  = field[:extra] ? ' <span class="badge extra">extra</span>' : ""
+        format_badge = field[:format] ? " <span class=\"badge format\">#{h(field[:format])}</span>" : ""
+        enum_display = field[:enum] ? %(<div class="enum-values">enum: #{field[:enum].map { |v| h(v) }.join(", ")}</div>) : ""
+        padding      = indent * 20
+
+        buffer << %(<tr><td style="padding-left: #{padding + 12}px"><code>#{name}</code>#{extra_badge}</td>)
+        buffer << %(<td>#{type_display}#{format_badge}#{enum_display}</td>)
+
+        if include_required
+          required_badge = case field[:required]
+          when true  then '<span class="badge required">required</span>'
+          when false then '<span class="badge optional">optional</span>'
+          else "—"
+          end
+          buffer << %(<td>#{required_badge}</td>)
+        end
+
+        buffer << "</tr>\n"
+
+        if field[:children]
+          field[:children].each do |child|
+            render_field_row(child, indent + 1, include_required: include_required, buffer: buffer)
+          end
+        end
+
+        buffer
+      end
+    end
+  end
+end

data/lib/trane/docs/service_definition.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Trane
+  module Docs
+    class ServiceDefinition
+      # Generate a complete service definition hash from the registry and routes.
+      #
+      # @param routes [ActionDispatch::Routing::RouteSet::NamedRouteCollection, Array] Rails routes
+      # @param service_name [String] published as `service.name`. Trane does not
+      #   configure the API name: callers inside a Rails application pass
+      #   `Rails.application.name`. Required — there is no default.
+      # @return [Hash]
+      def self.generate(routes, service_name:)
+        new(routes, service_name: service_name).to_h
+      end
+
+      def initialize(routes, service_name:)
+        @routes       = routes
+        @service_name = service_name
+        @registry     = Trane.registry
+      end
+
+      def to_h
+        {
+          service: {
+            name: @service_name
+          },
+          operations: build_operations,
+          representations: build_representations,
+          errors: build_errors
+        }
+      end
+
+      private
+
+      def build_operations
+        route_map = extract_route_map
+
+        @registry.operations.map do |name, op|
+          route_info = route_map[name.to_s] || {}
+
+          entry = {
+            id: name.to_s,
+            summary: op.summary,
+            method: route_info[:method] || "GET",
+            path: route_info[:path] || ""
+          }
+
+          entry[:request] = build_request(op.request) if op.request
+          entry[:responses] = build_responses(op.responses)
+          entry[:errors] = op.error_keys.map(&:to_s) unless op.error_keys.empty?
+
+          entry
+        end
+      end
+
+      def build_request(request_def)
+        result = {}
+
+        unless request_def.params.empty?
+          result[:params] = request_def.params.map do |p|
+            entry = { name: p.name.to_s, type: p.type.to_s, location: p.location.to_s, required: p.required }
+            entry[:enum] = serialize_enum(p.enum) unless p.enum.nil?
+            entry
+          end
+        end
+
+        unless request_def.body_fields.empty?
+          result[:body] = build_field_list(request_def.body_fields)
+        end
+
+        result
+      end
+
+      def build_responses(responses)
+        responses.map do |status, resp|
+          { status: status, fields: build_field_list(resp.fields) }
+        end
+      end
+
+      def build_field_list(fields)
+        fields.map { |f| build_field_hash(f) }
+      end
+
+      def build_field_hash(field)
+        entry = { name: field.name.to_s }
+        entry[:type] = field.type.to_s if field.type
+        entry[:format] = field.format.to_s if field.format
+        entry[:extra] = true if field.extra
+        entry[:array_of] = field.array_of.to_s if field.array_of
+        entry[:required] = field.required unless field.required.nil?
+        entry[:enum] = serialize_enum(field.enum) unless field.enum.nil?
+
+        unless field.children.empty?
+          entry[:children] = build_field_list(field.children)
+        end
+
+        entry
+      end
+
+      def build_representations
+        @registry.representations.map do |name, rep|
+          {
+            name: name.to_s,
+            fields: build_field_list(rep.fields)
+          }
+        end
+      end
+
+      def build_errors
+        @registry.errors.map do |_key, err|
+          {
+            key: err.key.to_s,
+            status_code: err.status_code,
+            description: err.description
+          }
+        end
+      end
+
+      def serialize_enum(values)
+        values.map do |v|
+          case v
+          when Date, DateTime, Time then v.iso8601
+          else v
+          end
+        end
+      end
+
+      def extract_route_map
+        map = {}
+
+        @routes.each do |route|
+          defaults = route.defaults
+          op_name = defaults[:_trane_operation]
+          next unless op_name
+
+          path = route.path.spec.to_s.gsub("(.:format)", "")
+          method = extract_method(route)
+
+          # Store only the first route per operation: defensive against
+          # any host that explicitly declares the same _trane_operation on
+          # multiple `match` lines. Rails 8.1.2 collapses `via: [:patch,
+          # :put]` into a single route with verb "PATCH|PUT", so this
+          # `||=` is a no-op for that case (the verb is canonicalised by
+          # `extract_method` to "PATCH").
+          map[op_name] ||= { method: method, path: path }
+        end
+
+        map
+      end
+
+      # NOTE: Trane::RouteValidator guarantees that a route with a contract
+      # maps to exactly one HTTP verb, so the `"PATCH|PUT"` (String) and
+      # `/^PATCH|PUT$/` (Regexp) multi-verb branches below no longer occur at
+      # runtime for contract routes. They are kept as defensive fallbacks.
+      def extract_method(route)
+        verb = route.verb
+        case verb
+        when String then verb.split("|").first
+        when Regexp then verb.source.scan(/[A-Z]+/).first || verb.source
+        else
+          if verb.respond_to?(:verb)
+            verb.verb.to_s
+          else
+            verb.to_s
+          end
+        end
+      end
+    end
+  end
+end