trane 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fabf8d80352adbe88869422f34a1b246b78b32518fc2af532520ca6c9b42de6
-  data.tar.gz: 2c72a84965aacb8bff923af520882d8683a6e33f286760935da57296e8556395
+  metadata.gz: 15dba6b06367507e244932e3e2951fc09dbe0a43219edd7ad9d2b110b23b6599
+  data.tar.gz: 8ef665c037cde9c0be79336ad749a23055cf6973f9a73f92ca37bc0c05b2a933
 SHA512:
-  metadata.gz: b5a40834b40f735228410ae3a4f65d464cc305a291306dd5fecb28f55c54f4aca7c6d576899aed158bdc60b55ed0e51a7686c39aa5c6fdd375defde1ab2e4d8e
-  data.tar.gz: e8de68a5e64d089111e37ef49f7949a960ff4fe748fcd01b12fc1fda6ef5a094f7a394a328429ddf9d83e24e6b5dadc483d99a867a16eeebc58014efa05e097b
+  metadata.gz: 41df9927bece8008f621a03c3f1f9210cfc8a30413ef5a661472a3f33bd49af97135b0a1628d4828129866bee9820c96b9287a33659a9d7ea14fccb7546328ee
+  data.tar.gz: 46762216d0b9f83fae26a92f36d4c3628db58cc9c8ce6b8009f34feeb5392d89d9cf80673e94d18d02a89654b0b3a979d8a4d778f91e9a21875ad938276e96f8

data/CHANGELOG.md

@@ -5,6 +5,51 @@ 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.2.1] - 2026-09-01
+
+### Fixed
+
+- The gem now packages `config/routes.rb`. `spec.files` listed only `lib/` and
+  the three top-level documents, so the Engine's routes never shipped:
+  `mount Trane::Engine` gave an Engine with no routes and the documentation
+  endpoints answered **404** for anyone installing from rubygems.org. 0.1.0 and
+  0.2.0 are both affected — the bug is invisible to a host pinning the gem by
+  `git:`, which fetches the whole checkout, so it went unnoticed until a host
+  consumed the published gem. `spec/trane/packaging_spec.rb` now asserts the
+  packaged file list directly, since the rest of the suite runs against the
+  checkout and cannot see what the gemspec omits.
+
+## [0.2.0] - 2026-08-27
+
+### Added
+
+- `success_envelope` (set via `Trane.configure`): a callable applied to the
+  serialized response hash before encoding, so hosts can wrap every success
+  payload in their own envelope. Defaults to identity.
+- `error_envelope` (set via `Trane.configure`): a callable receiving
+  `(exception, definition)` — `definition` is `nil` when no error is
+  registered — that builds the error response body. The status code stays
+  derived from the definition. The default reproduces the previous
+  `{"errors":[{"key","message"}]}` shape, verbosity gating included.
+- `rescue_rails_reserved` (set via `Trane.configure`): when `true`,
+  Rails-reserved exceptions with no registered error are served through the
+  envelope instead of being re-raised, as a plain 500 — the reserved
+  exception's native status mapping (e.g. `ActiveRecord::RecordNotFound`'s
+  404) is discarded, not preserved. It also moves their reporting: Rails'
+  exception middleware no longer sees them, so Trane reports them instead, as
+  `handled: true` / `severity: :warning` rather than Rails' `handled: false` /
+  `severity: :error`, and with a longer log line. Same event count, more log
+  volume. Defaults to `false`.
+
+Both envelope callables must return a Hash, and Trane checks rather than
+encoding whatever comes back. A `success_envelope` that returns something else
+raises `Trane::Error`; an `error_envelope` that returns something else, or that
+raises, degrades to the built-in shape and logs a warning — it cannot raise,
+because it runs inside a `rescue_from` and would escape to Rails' static error
+page.
+
+No breaking changes: every default reproduces 0.1.0 behaviour exactly.
+
 ## [0.1.0] - 2026-08-14
 
 First public release.
@@ -33,4 +78,6 @@ First public release.
   metadata raises by default (`on_missing_operation` opt-out), and
   configuration setters reject unknown modes.
 
+[0.2.1]: https://github.com/thisisqubika/trane/releases/tag/v0.2.1
+[0.2.0]: https://github.com/thisisqubika/trane/releases/tag/v0.2.0
 [0.1.0]: https://github.com/thisisqubika/trane/releases/tag/v0.1.0

data/config/routes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Routes for the Trane::Engine. The host mounts this engine at a path
+# of its choice; everything under that mount goes to the docs Rack app,
+# which dispatches HTML vs JSON by inspecting the request path.
+Trane::Engine.routes.draw do
+  mount Trane::Docs::App.new => "/"
+end

data/lib/trane/configuration.rb

@@ -14,6 +14,32 @@ module Trane
     # the route did not declare `contract: { operation: ... }`).
     ON_MISSING_OPERATION_MODES = %i[raise log fallback].freeze
 
+    # Applied to the serialized response hash immediately before it is encoded,
+    # so a host can wrap every success payload in its own envelope. Identity by
+    # default: the response is exactly what the contract declares.
+    DEFAULT_SUCCESS_ENVELOPE = ->(body) { body }
+
+    # Builds the response body for a rescued exception. Receives the exception
+    # and the resolved ErrorDefinition, or nil when no error is registered for
+    # it. The status code is NOT the hook's concern: the handler derives it from
+    # the definition (or 500), so a host cannot accidentally decouple body and
+    # status.
+    #
+    # The default reproduces the built-in shape, verbosity gating included:
+    # exception messages are written for a log audience and can carry SQL,
+    # record values or internal hostnames, so only local environments see them.
+    DEFAULT_ERROR_ENVELOPE = lambda do |exception, definition|
+      if definition
+        { errors: [ { key: definition.key.to_s, message: exception.message } ] }
+      elsif defined?(Rails) && Rails.env.local?
+        { errors: [ { key: "InternalServerError",
+                      message: "#{exception.class}: #{exception.message}" } ] }
+      else
+        { errors: [ { key: "InternalServerError",
+                      message: "An unexpected error occurred" } ] }
+      end
+    end
+
     attr_reader :strict_mode
 
     # Returns the process-level Configuration instance via the Trane shim.
@@ -73,6 +99,47 @@ module Trane
       @on_missing_operation = value
     end
 
+    def success_envelope
+      @success_envelope || DEFAULT_SUCCESS_ENVELOPE
+    end
+
+    def success_envelope=(value)
+      raise FrozenError, "Trane::Configuration is frozen; cannot modify success_envelope after boot" if @frozen
+      unless value.respond_to?(:call)
+        raise Trane::Error, "success_envelope must respond to #call (got #{value.inspect})"
+      end
+      @success_envelope = value
+    end
+
+    def error_envelope
+      @error_envelope || DEFAULT_ERROR_ENVELOPE
+    end
+
+    def error_envelope=(value)
+      raise FrozenError, "Trane::Configuration is frozen; cannot modify error_envelope after boot" if @frozen
+      unless value.respond_to?(:call)
+        raise Trane::Error, "error_envelope must respond to #call (got #{value.inspect})"
+      end
+      @error_envelope = value
+    end
+
+    # Whether a Rails-reserved exception (one in
+    # ActionDispatch::ExceptionWrapper.rescue_responses) without a registered
+    # Trane error is re-raised (false, the default — Rails' own middleware
+    # applies its status mapping) or served through the configured error
+    # envelope as an unhandled error (true).
+    def rescue_rails_reserved
+      @rescue_rails_reserved.nil? ? false : @rescue_rails_reserved
+    end
+
+    def rescue_rails_reserved=(value)
+      raise FrozenError, "Trane::Configuration is frozen; cannot modify rescue_rails_reserved after boot" if @frozen
+      unless value == true || value == false
+        raise Trane::Error, "rescue_rails_reserved must be true or false (got #{value.inspect})"
+      end
+      @rescue_rails_reserved = value
+    end
+
     # Returns the effective strict mode for the current environment.
     #
     # @return [Symbol] :raise, :log, or :ignore
@@ -117,10 +184,13 @@ module Trane
     end
 
     def reset!
-      @strict_mode          = nil
-      @contracts_paths      = nil
-      @on_missing_operation = nil
-      @frozen               = false
+      @strict_mode           = nil
+      @contracts_paths       = nil
+      @on_missing_operation  = nil
+      @success_envelope      = nil
+      @error_envelope        = nil
+      @rescue_rails_reserved = nil
+      @frozen                = false
     end
 
     # Internal — full state snapshot/restore for Trane::Testing.
@@ -129,18 +199,24 @@ module Trane
     # (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
+        strict_mode:           @strict_mode,
+        contracts_paths:       @contracts_paths,
+        on_missing_operation:  @on_missing_operation,
+        success_envelope:      @success_envelope,
+        error_envelope:        @error_envelope,
+        rescue_rails_reserved: @rescue_rails_reserved,
+        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]
+      @strict_mode           = state[:strict_mode]
+      @contracts_paths       = state[:contracts_paths]
+      @on_missing_operation  = state[:on_missing_operation]
+      @success_envelope      = state[:success_envelope]
+      @error_envelope        = state[:error_envelope]
+      @rescue_rails_reserved = state[:rescue_rails_reserved]
+      @frozen                = state[:frozen]
     end
   end
 end

data/lib/trane/controller/error_handler.rb

@@ -25,7 +25,10 @@ module Trane
     # 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.
+    # the Trane lookup wins over the re-raise path. Alternatively, setting
+    # `Trane.configuration.rescue_rails_reserved = true` swallows every
+    # reserved exception without registering each one by hand — useful for an
+    # API that must answer JSON on every path (default: false).
     #
     # SECURITY NOTE: a registered error's envelope carries the exception's
     # runtime #message, in EVERY environment including production. Framework
@@ -85,10 +88,10 @@ module Trane
 
         if error_def
           render(
-            json: { errors: [ { key: error_def.key.to_s, message: exception.message } ] },
+            json: _trane_error_body(exception, error_def),
             status: error_def.status_code
           )
-        elsif _trane_rails_reserved?(klass)
+        elsif _trane_rails_reserved?(klass) && !Trane.configuration.rescue_rails_reserved
           raise exception
         else
           _trane_unhandled_error(exception)
@@ -136,33 +139,52 @@ module Trane
         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.
+      # The report is NOT the envelope's concern and stays unconditional: this
+      # rescue_from runs before Rails' exception-reporting middleware, so
+      # without it a 500 in production leaves no log line and no tracker event.
+      #
+      # That applies to the rescue_rails_reserved path too, and it is why the
+      # report is not skipped there: serving a reserved exception through the
+      # envelope means Rails' middleware never sees it either, so skipping here
+      # would leave no trace at all — strictly less than the re-raising default,
+      # under which ActionDispatch reports it as handled: false / :error. Trane
+      # reports it as handled: true / :warning instead. The event count is the
+      # same; the log line is longer. See docs/wiki/Configuration.md.
       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
+        render(
+          json: _trane_error_body(exception, nil),
+          status: :internal_server_error
+        )
+      end
+
+      # Applies error_envelope, degrading to the built-in shape when the host's
+      # callable misbehaves.
+      #
+      # It does NOT raise, unlike the success path. We are already inside a
+      # rescue_from handler, and an exception raised in one is not re-dispatched
+      # to another: it propagates to Rails' exception middleware, so the client
+      # gets the static error page — HTML, or an empty body where the host has
+      # no public/500.html. That is precisely the outcome a host configuring an
+      # envelope is trying to avoid, so a broken envelope must not cause it.
+      # Falling back keeps the response JSON and puts the misconfiguration in
+      # the log, where it is actionable.
+      def _trane_error_body(exception, definition)
+        body = Trane.configuration.error_envelope.call(exception, definition)
+        return body if body.is_a?(::Hash)
+
+        Trane.log_warning(
+          "[Trane] error_envelope returned #{body.class}, expected Hash; " \
+          "serving the built-in error shape instead."
+        )
+        Trane::Configuration::DEFAULT_ERROR_ENVELOPE.call(exception, definition)
+      rescue StandardError => e
+        Trane.log_warning(
+          "[Trane] error_envelope raised #{e.class}: #{e.message}; " \
+          "serving the built-in error shape instead."
+        )
+        Trane::Configuration::DEFAULT_ERROR_ENVELOPE.call(exception, definition)
       end
     end
   end

data/lib/trane/controller/renderer.rb

@@ -72,6 +72,7 @@ module Trane
           strict      = Trane.configuration.effective_strict_mode
           serializer  = registry.compiled_serializer_for(response_def, strict)
           hash        = serializer.serialize(contract_data, extra_attributes: extra_attrs)
+          hash        = _trane_enveloped(hash)
 
           body = ::JSON.generate(hash)
           super(
@@ -93,6 +94,22 @@ module Trane
         op&.to_sym
       end
 
+      # Applies success_envelope and insists the result is still a Hash.
+      # `JSON.generate` happily encodes a nil, a String or an Array, so an
+      # envelope with a wrong return type would serve `null` — or a bare
+      # string — with a 200 and no signal at all. Raising instead is the
+      # fail-loud default the rest of the gem holds to, and it is safe here:
+      # Trane::Error is a StandardError, so the host's own rescue_from turns
+      # it into a reported 500 rather than letting it escape.
+      def _trane_enveloped(hash)
+        result = Trane.configuration.success_envelope.call(hash)
+        return result if result.is_a?(::Hash)
+
+        raise Trane::Error,
+              "Trane: success_envelope must return a Hash, got #{result.class}. " \
+              "It receives the serialized response hash and returns the hash to encode."
+      end
+
       def _trane_log_missing_operation
         Trane.log_warning(
           "[Trane] render contract: called on a route without contract metadata; " \

data/lib/trane/testing.rb

@@ -10,10 +10,12 @@ module Trane
     # restores the original state. Guarantees restore even when the block
     # raises.
     #
-    # This helper does not touch the route set: `strict_mode` — the only
-    # attribute settable via `Trane.configure` — is read when a response is
-    # rendered (Trane::Controller::Renderer), never when routes are drawn. The
-    # API name is not configurable at all; it is Rails.application.name.
+    # This helper does not touch the route set: none of the attributes
+    # settable via `Trane.configure` (`strict_mode`, `on_missing_operation`,
+    # `success_envelope`, `error_envelope`, `rescue_rails_reserved`) are read
+    # at route-draw time — `strict_mode`, for instance, is read when a
+    # response is rendered (Trane::Controller::Renderer). The API name is not
+    # configurable at all; it is Rails.application.name.
     #
     # `contracts_paths` is also configuration state (set from
     # `config/application.rb` via the internal `_set_contracts_paths!`, not

data/lib/trane/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Trane
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trane
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Ignacio Jorge
@@ -109,6 +109,7 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- config/routes.rb
 - lib/tasks/trane.rake
 - lib/trane.rb
 - lib/trane/boot_validator.rb