trane 0.1.0

data/lib/trane/field_builder.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Trane
+  class FieldBuilder
+    attr_reader :fields
+
+    def initialize
+      @fields = []
+    end
+
+    # Define a field in the current context.
+    #
+    # @param name [Symbol] field name
+    # @param type [Symbol, nil] field type keyword — mandatory unless `of:` or a block is provided
+    # @param extra [Boolean] whether this is an optional extra field
+    # @param format [Symbol, nil] format hint (e.g., :iso8601)
+    # @param of [Symbol, nil] element type for arrays (infers type: :array)
+    # @param enum [Array, nil] set of allowed values; only valid for scalar primitive types
+    # @yield optional block for inline nested fields (infers type: :object)
+    def field(name, type: nil, extra: false, format: nil, of: nil, enum: nil, &block)
+      @fields << _build_field_node(
+        name: name, type: type, extra: extra, format: format,
+        of: of, enum: enum, child_builder_class: FieldBuilder,
+        required: nil, &block
+      )
+    end
+
+    private
+
+    # Shared field construction logic used by both FieldBuilder and BodyBuilder.
+    # Validates presence of at least one type specifier, resolves the type, validates
+    # enum constraints, recursively builds children, and returns a FieldNode.
+    #
+    # @param child_builder_class [Class] builder class to use for nested fields
+    # @param required [Boolean, nil] whether the field is required (only meaningful for body fields)
+    def _build_field_node(name:, type:, extra:, format:, of:, enum:, child_builder_class:, required:, &block)
+      if name.nil? || name.to_s.empty?
+        raise ArgumentError, "field name cannot be nil or empty"
+      end
+
+      if type.nil? && of.nil? && !block_given?
+        raise ArgumentError,
+              "field #{name.inspect} must specify type:, of:, or provide a block"
+      end
+
+      resolved_type = _resolve_type(type, of, block_given?)
+      Trane::Types.validate_enum!(name: name, type: resolved_type, enum: enum) if enum
+
+      children = if block_given?
+        child_builder = child_builder_class.new
+        child_builder.instance_eval(&block)
+        child_builder.fields
+      else
+        []
+      end
+
+      FieldNode.new(
+        name: name,
+        type: resolved_type,
+        extra: extra,
+        format: format,
+        array_of: of,
+        required: required,
+        enum: enum,
+        children: children
+      )
+    end
+
+    # Resolve the effective field type from the three type-specifier inputs.
+    # Contract: always returns a non-nil Symbol; raises if the precondition in
+    # `_build_field_node` is bypassed (i.e. all three inputs falsy).
+    def _resolve_type(type, of, has_block)
+      return :array if of
+      return type if type
+      return :object if has_block
+
+      raise ArgumentError,
+            "_resolve_type called without type, of, or block — precondition bypassed"
+    end
+  end
+end

data/lib/trane/field_node.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Trane
+  FieldNode = Data.define(:name, :type, :extra, :format, :array_of, :required, :enum, :children) do
+    def initialize(name:, type: nil, extra: false, format: nil, array_of: nil, required: nil, enum: nil, children: [])
+      super(
+        name: name.to_sym,
+        type: type&.to_sym,
+        extra: extra,
+        format: format&.to_sym,
+        array_of: array_of&.to_sym,
+        required: required,
+        enum: enum&.freeze,
+        children: children.freeze
+      )
+    end
+  end
+end

data/lib/trane/operation_definition.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Trane
+  RequestDefinition = Data.define(:params, :body_fields) do
+    def initialize(params: [], body_fields: [])
+      super(params: params.freeze, body_fields: body_fields.freeze)
+    end
+  end
+
+  ResponseDefinition = Data.define(:status, :fields) do
+    def initialize(status:, fields: [])
+      status_int = status.to_i
+      unless Trane::Types::HTTP_STATUS_RANGE.cover?(status_int)
+        raise ArgumentError,
+              "ResponseDefinition status #{status.inspect} is not a valid HTTP status code " \
+              "(must be in #{Trane::Types::HTTP_STATUS_RANGE})"
+      end
+      super(status: status_int, fields: fields.freeze)
+    end
+  end
+
+  OperationDefinition = Data.define(:name, :summary, :request, :responses, :error_keys) do
+    def initialize(name:, summary: nil, request: nil, responses: {}, error_keys: [])
+      if name.nil? || name.to_s.empty?
+        raise ArgumentError, "OperationDefinition name cannot be nil or empty"
+      end
+      super(
+        name: name.to_sym,
+        summary: summary,
+        request: request,
+        responses: responses.freeze,
+        error_keys: error_keys.freeze
+      )
+    end
+  end
+
+  # Builder for the `body do ... end` block inside a request.
+  # Extends FieldBuilder to accept the `required:` kwarg on body fields.
+  class BodyBuilder < FieldBuilder
+    def field(name, type: nil, extra: false, format: nil, of: nil, required: false, enum: nil, &block)
+      @fields << _build_field_node(
+        name: name, type: type, extra: extra, format: format,
+        of: of, enum: enum, child_builder_class: BodyBuilder,
+        required: required, &block
+      )
+    end
+  end
+
+  # Builder for the `request do ... end` block
+  class RequestBuilder
+    def initialize
+      @params = []
+      @body_fields = []
+    end
+
+    def path(name, type:)
+      raise ArgumentError, "path #{name.inspect} type: cannot be nil" if type.nil?
+
+      @params << ParamDefinition.new(name: name, type: type, required: true, location: :path)
+    end
+
+    def query(name, type:, required: false, enum: nil)
+      raise ArgumentError, "query #{name.inspect} type: cannot be nil" if type.nil?
+
+      Trane::Types.validate_enum!(name: name, type: type, enum: enum) if enum
+      @params << ParamDefinition.new(name: name, type: type, required: required, location: :query, enum: enum)
+    end
+
+    def body(&block)
+      builder = BodyBuilder.new
+      builder.instance_eval(&block)
+      @body_fields = builder.fields
+    end
+
+    def build
+      RequestDefinition.new(params: @params, body_fields: @body_fields)
+    end
+  end
+
+  # Builder for the `response STATUS do ... end` block
+  class ResponseBuilder < FieldBuilder
+    def initialize(status)
+      super()
+      @status = status.to_i
+    end
+
+    def build
+      ResponseDefinition.new(status: @status, fields: @fields)
+    end
+  end
+
+  # Builder for the `errors do ... end` block inside an operation
+  class ErrorKeysBuilder
+    attr_reader :keys
+
+    def initialize
+      @keys = []
+    end
+
+    def key(error_key)
+      @keys << error_key.to_sym
+    end
+  end
+
+  # Builder for `Trane.operation :name do ... end`
+  class OperationBuilder
+    def initialize(name)
+      @name = name.to_sym
+      @summary = nil
+      @request_builder = nil
+      @responses = {}
+      @error_keys = []
+    end
+
+    def summary(text)
+      @summary = text
+    end
+
+    def request(&block)
+      @request_builder = RequestBuilder.new
+      @request_builder.instance_eval(&block)
+    end
+
+    def response(status, &block)
+      builder = ResponseBuilder.new(status)
+      builder.instance_eval(&block)
+      @responses[status.to_i] = builder.build
+    end
+
+    def errors(&block)
+      builder = ErrorKeysBuilder.new
+      builder.instance_eval(&block)
+      @error_keys = builder.keys
+    end
+
+    def build
+      OperationDefinition.new(
+        name: @name,
+        summary: @summary,
+        request: @request_builder&.build,
+        responses: @responses,
+        error_keys: @error_keys
+      )
+    end
+  end
+end

data/lib/trane/param_definition.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Trane
+  ParamDefinition = Data.define(:name, :type, :required, :location, :enum) do
+    # Build a frozen param definition for an operation request schema.
+    #
+    # @param name [Symbol, String] coerced to Symbol
+    # @param type [Symbol, String] coerced to Symbol
+    # @param location [Symbol, String] one of +:path+, +:query+; coerced to Symbol
+    # @param required [Boolean] whether the param must be present in the request.
+    #   Defaults to +false+. DSL callers override per location: +path+ always
+    #   passes +true+; +query+ honours the caller's +required:+ keyword (also
+    #   defaulting to +false+).
+    # @param enum [Array, nil] frozen on assignment
+    def initialize(name:, type:, location:, required: false, enum: nil)
+      super(
+        name: name.to_sym,
+        type: type.to_sym,
+        required: required,
+        location: location.to_sym,
+        enum: enum&.freeze
+      )
+    end
+  end
+end

data/lib/trane/registry.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+module Trane
+  # Thread-safe registry of operations, representations, and errors.
+  #
+  # The registry maintains a single frozen snapshot containing all three
+  # categories. Reads (`Registry.operations`, etc.) are lock-free: one
+  # ivar read returning a frozen Hash. Writes happen atomically via
+  # `Registry.replace!`, which constructs a new snapshot in a builder
+  # and swaps it in a single assignment (atomic under MRI GVL).
+  #
+  # For ad-hoc registrations outside `replace!` (specs, REPL), the
+  # `register_*` methods do copy-on-write to a new snapshot — O(n) per
+  # write but bounded by spec sizes (typically < 100 entries).
+  #
+  # Class methods on this module delegate to the process-level
+  # `Registry::Instance` via `Trane.registry`. Existing call sites
+  # (`Trane::Registry.reset!` etc.) continue to work unchanged.
+  module Registry
+    EMPTY_ERRORS_BY_NAME = {}.freeze
+
+    EMPTY_SNAPSHOT = {
+      operations:      {}.freeze,
+      representations: {}.freeze,
+      errors:          {}.freeze,
+      errors_by_name:  EMPTY_ERRORS_BY_NAME
+    }.freeze
+
+    # Builder collected inside a `Registry::Instance#replace!` block.
+    class SnapshotBuilder
+      def initialize
+        @operations      = {}
+        @representations = {}
+        @errors          = {}
+      end
+
+      def register_operation(definition)
+        @operations[definition.name] = definition
+      end
+
+      def register_representation(definition)
+        @representations[definition.name] = definition
+      end
+
+      def register_error(definition)
+        @errors[definition.key] = definition
+      end
+
+      def freeze_and_build
+        errors_by_name = self.class.build_errors_by_name(@errors)
+        {
+          operations:      @operations.freeze,
+          representations: @representations.freeze,
+          errors:          @errors.freeze,
+          errors_by_name:  errors_by_name
+        }.freeze
+      end
+
+      # Build a frozen FQDN+short-name index over the given errors Hash.
+      # Raises Trane::Error on short-name collision between two distinct FQDNs.
+      # A pure function of its input — class-level so Instance#register_error
+      # can rebuild the index without allocating a builder.
+      def self.build_errors_by_name(errors)
+        return EMPTY_ERRORS_BY_NAME if errors.empty?
+
+        index   = {}
+        buckets = Hash.new { |h, k| h[k] = [] }
+
+        errors.each do |fqdn, defn|
+          index[fqdn] = defn
+          short = fqdn.rpartition("::").last
+          buckets[short] << defn unless short == fqdn
+        end
+
+        buckets.each do |short, defs|
+          if defs.size >= 2
+            fqdns   = defs.map(&:key).sort
+            message = "Trane boot: error short-name collision on \"#{short}\".\n" \
+                      "Conflicting registrations: #{fqdns.join(', ')}.\n" \
+                      "Fix by renaming one, or by referencing them by FQDN in operation `errors` blocks " \
+                      "(e.g. key :\"#{fqdns.first}\")."
+            raise Trane::Error, message
+          end
+          index[short] = defs.first unless index.key?(short)
+        end
+
+        index.freeze
+      end
+    end
+
+    # Trane registry. Owns its own snapshot ivar and replacement mutex;
+    # instances are independent of one another.
+    class Instance
+      # Single process-wide thread-local key holding a Hash of
+      # { instance object_id => active SnapshotBuilder } for the builders
+      # opened on the current thread. Keyed per instance so a builder is
+      # only visible to `register_*` calls on the same instance AND the
+      # same thread; entries are deleted in `replace!`'s ensure, so the
+      # table is empty between calls. One constant Symbol replaces the
+      # previous per-instance dynamic symbols, which pinned a symbol and a
+      # thread-local entry per discarded instance for the thread's lifetime
+      # (`thread_variable_set(key, nil)` does not delete the key).
+      ACTIVE_BUILDERS_KEY = :trane_active_builders
+
+      # Defensive bound for the three object_id-keyed caches below
+      # (@compiled_serializers, @validator_field_names,
+      # @validator_declared_field_names). Under their documented invariant —
+      # keys are objects owned by the current frozen snapshot — the caches
+      # are cleared on every snapshot change and stay small (one entry per
+      # response/fields object in the registry). The bound only matters if a
+      # caller violates the invariant by passing transient objects built per
+      # request: past it, results are built without caching (a perf
+      # degradation) instead of growing the caches without limit (a leak).
+      MAX_CACHE_ENTRIES = 10_000
+
+      def initialize
+        @snapshot                       = EMPTY_SNAPSHOT
+        @replace_mutex                  = Mutex.new
+        @compiled_serializers           = {}
+        @validator_field_names          = {}
+        @validator_declared_field_names = {}
+      end
+
+      def operations
+        @snapshot[:operations]
+      end
+
+      def representations
+        @snapshot[:representations]
+      end
+
+      def errors
+        @snapshot[:errors]
+      end
+
+      # Returns the frozen FQDN+short-name index built when the snapshot was last replaced.
+      # Keys are Strings; values are Trane::ErrorDefinition instances.
+      def errors_by_name
+        @snapshot[:errors_by_name]
+      end
+
+      # Atomic bulk replacement. Use this for reload paths (Railtie's
+      # `to_prepare`, integration test setup). The block receives a
+      # `SnapshotBuilder`; on successful completion of the block, the
+      # built snapshot replaces the current one in a single assignment.
+      # If the block raises, the prior snapshot is preserved.
+      #
+      # Concurrent writers are serialised by a per-instance mutex;
+      # readers remain lock-free.
+      #
+      # Nested calls (on the same thread) are not supported and raise.
+      def replace!
+        raise Trane::Error, "nested Registry.replace! is not supported" if active_builder
+
+        @replace_mutex.synchronize do
+          builder = SnapshotBuilder.new
+          active_builders[object_id] = builder
+          yield builder
+          @snapshot = builder.freeze_and_build
+          clear_derived_caches
+        ensure
+          active_builders.delete(object_id)
+        end
+      end
+
+      # Incremental registration paths. Used by specs and any caller
+      # outside a `replace!` block. Copy-on-write under @replace_mutex,
+      # so concurrent CoW writes are serialised with the same guarantee
+      # as `replace!`. The `active_builder` early-return skips the mutex
+      # acquisition when these methods are called from inside a
+      # `replace!` block — re-acquiring a non-reentrant Mutex from the
+      # same thread would deadlock. For bulk operations, prefer `replace!`.
+      def register_operation(definition)
+        b = active_builder
+        return b.register_operation(definition) if b
+
+        @replace_mutex.synchronize do
+          s = @snapshot
+          @snapshot = s.merge(operations: s[:operations].merge(definition.name => definition).freeze).freeze
+          clear_derived_caches
+        end
+      end
+
+      def register_representation(definition)
+        b = active_builder
+        return b.register_representation(definition) if b
+
+        @replace_mutex.synchronize do
+          s = @snapshot
+          @snapshot = s.merge(representations: s[:representations].merge(definition.name => definition).freeze).freeze
+          clear_derived_caches
+        end
+      end
+
+      def register_error(definition)
+        b = active_builder
+        return b.register_error(definition) if b
+
+        @replace_mutex.synchronize do
+          s = @snapshot
+          new_errors = s[:errors].merge(definition.key => definition).freeze
+          new_index  = SnapshotBuilder.build_errors_by_name(new_errors)
+          @snapshot = s.merge(errors: new_errors, errors_by_name: new_index).freeze
+          clear_derived_caches
+        end
+      end
+
+      def reset!
+        @snapshot = EMPTY_SNAPSHOT
+        clear_derived_caches
+      end
+
+      def validate!
+        Trane::BootValidator.validate!(self)
+      end
+
+      # Returns a memoized Trane::Serializer for the given ResponseDefinition
+      # and strict_mode pair. Instances are built lazily on first access and
+      # cached until the registry snapshot changes (via replace!, reset!, or
+      # any of the register_* copy-on-write paths).
+      #
+      # INVARIANT: response_def must be owned by the current snapshot (i.e.
+      # reachable from `operations`). The cache is keyed by object_id without
+      # holding the object, so it can never notice a dead key; passing
+      # transient objects built per call would grow it until
+      # MAX_CACHE_ENTRIES, after which results are built uncached.
+      #
+      # Thread-safety: concurrent first access on the same key may build two
+      # Serializers; last write wins. Subsequent reads share the cached
+      # instance. Serializer is frozen post-init and safe to share across
+      # threads.
+      #
+      # @param response_def [Trane::ResponseDefinition]
+      # @param strict_mode [Symbol] :raise, :log, or :ignore
+      # @return [Trane::Serializer]
+      def compiled_serializer_for(response_def, strict_mode)
+        key    = [ response_def.object_id, strict_mode ]
+        cached = @compiled_serializers[key]
+        return cached if cached
+
+        built = Trane::Serializer.new(response_def, self, strict_mode: strict_mode)
+        @compiled_serializers[key] = built if @compiled_serializers.size < MAX_CACHE_ENTRIES
+        built
+      end
+
+      # Cached frozen Set of all field names for a given fields collection.
+      # Used by ContractValidator to detect undeclared keys without per-request
+      # allocation. A Set (not an Array) because the consumer does one
+      # membership test per serialized key: with F fields that is O(F) total
+      # instead of the O(F^2) an Array scan would cost — measurable on every
+      # production response, where the validator runs in :log mode.
+      # Same lifecycle / invalidation / INVARIANT (snapshot-owned `fields`
+      # only) and MAX_CACHE_ENTRIES bound as @compiled_serializers.
+      #
+      # @param fields [Array<Trane::FieldNode>] frozen fields array
+      # @return [Set<Symbol>] frozen Set of field names
+      def validator_field_names_for(fields)
+        cached = @validator_field_names[fields.object_id]
+        return cached if cached
+
+        built = Set.new(fields.map(&:name)).freeze
+        @validator_field_names[fields.object_id] = built if @validator_field_names.size < MAX_CACHE_ENTRIES
+        built
+      end
+
+      # Cached frozen Array of non-`extra:` field names. Used by ContractValidator
+      # to detect missing declared keys. Same lifecycle / invalidation /
+      # INVARIANT (snapshot-owned `fields` only) and MAX_CACHE_ENTRIES bound
+      # as @compiled_serializers.
+      #
+      # @param fields [Array<Trane::FieldNode>] frozen fields array
+      # @return [Array<Symbol>] frozen Array of declared (non-extra) field names
+      def validator_declared_field_names_for(fields)
+        cached = @validator_declared_field_names[fields.object_id]
+        return cached if cached
+
+        built = fields.reject(&:extra).map(&:name).freeze
+        @validator_declared_field_names[fields.object_id] = built if @validator_declared_field_names.size < MAX_CACHE_ENTRIES
+        built
+      end
+
+      private
+
+      # Drop every snapshot-derived cache. MUST be called on every path
+      # that replaces @snapshot — a stale entry here would be served keyed
+      # by an object_id belonging to the dead snapshot.
+      def clear_derived_caches
+        @compiled_serializers           = {}
+        @validator_field_names          = {}
+        @validator_declared_field_names = {}
+      end
+
+      # The current thread's { instance object_id => builder } table,
+      # created lazily (one Hash per thread that has ever run replace!).
+      def active_builders
+        Thread.current.thread_variable_get(ACTIVE_BUILDERS_KEY) ||
+          {}.tap { |table| Thread.current.thread_variable_set(ACTIVE_BUILDERS_KEY, table) }
+      end
+
+      def active_builder
+        table = Thread.current.thread_variable_get(ACTIVE_BUILDERS_KEY)
+        table && table[object_id]
+      end
+    end
+
+    class << self
+      def operations;      Trane.registry.operations; end
+      def representations; Trane.registry.representations; end
+      def errors;          Trane.registry.errors; end
+
+      def errors_by_name;  Trane.registry.errors_by_name; end
+
+      def replace!(&block); Trane.registry.replace!(&block); end
+      def register_operation(d);      Trane.registry.register_operation(d); end
+      def register_representation(d); Trane.registry.register_representation(d); end
+      def register_error(d);          Trane.registry.register_error(d); end
+      def reset!;    Trane.registry.reset!; end
+      def validate!; Trane.registry.validate!; end
+
+      def validator_field_names_for(fields);          Trane.registry.validator_field_names_for(fields); end
+      def validator_declared_field_names_for(fields); Trane.registry.validator_declared_field_names_for(fields); end
+    end
+  end
+end

data/lib/trane/representation_definition.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Trane
+  RepresentationDefinition = Data.define(:name, :fields) do
+    def initialize(name:, fields: [])
+      if name.nil? || name.to_s.empty?
+        raise ArgumentError, "RepresentationDefinition name cannot be nil or empty"
+      end
+      super(name: name.to_sym, fields: fields.freeze)
+    end
+  end
+
+  # Builder for `Trane.representation :name do ... end`
+  class RepresentationBuilder < FieldBuilder
+    def initialize(name)
+      super()
+      @name = name.to_sym
+    end
+
+    def build
+      RepresentationDefinition.new(name: @name, fields: @fields)
+    end
+  end
+end