Class: Trane::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/trane/configuration.rb

Constant Summary collapse

DEFAULT_CONTRACTS_PATHS =

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.

[ "app/api_contract" ].freeze
STRICT_MODES =

Valid strict_mode values (nil is also accepted: auto-detect by env).

%i[raise log ignore].freeze
ON_MISSING_OPERATION_MODES =

Valid modes for on_missing_operation (what render contract: does when the route did not declare contract: { operation: ... }).

%i[raise log fallback].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



25
26
27
 
# File 'lib/trane/configuration.rb', line 25

def initialize
  reset!
end

Instance Attribute Details

#strict_mode ⇒ Object

Returns the value of attribute strict_mode.



17
18
19
 
# File 'lib/trane/configuration.rb', line 17

def strict_mode
  @strict_mode
end

Class Method Details

.instance ⇒ Object

Returns the process-level Configuration instance via the Trane shim. Existing call sites (Trane::Configuration.instance.X) continue to work.



21
22
23
 
# File 'lib/trane/configuration.rb', line 21

def self.instance
  Trane.configuration
end

Instance Method Details

#_dump_state ⇒ Object

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).



130
131
132
133
134
135
136
137
 
# File 'lib/trane/configuration.rb', line 130

def _dump_state
  {
    strict_mode:          @strict_mode,
    contracts_paths:      @contracts_paths,
    on_missing_operation: @on_missing_operation,
    frozen:               @frozen
  }
end

#_restore_state!(state) ⇒ Object 



139
140
141
142
143
144
 
# File 'lib/trane/configuration.rb', line 139

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

#_set_contracts_paths!(value) ⇒ Object

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.

Raises:

  • (FrozenError) 


106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/trane/configuration.rb', line 106

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

#contracts_paths ⇒ Object

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.



99
100
101
 
# File 'lib/trane/configuration.rb', line 99

def contracts_paths
  @contracts_paths || DEFAULT_CONTRACTS_PATHS
end

#effective_strict_mode ⇒ Symbol

Returns the effective strict mode for the current environment.

Returns:

  • (Symbol) —

    :raise, :log, or :ignore



79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/trane/configuration.rb', line 79

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

#freeze! ⇒ Object

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.



33
34
35
 
# File 'lib/trane/configuration.rb', line 33

def freeze!
  @frozen = true
end

#frozen_config? ⇒ Boolean

Returns:

  • (Boolean) 


37
38
39
 
# File 'lib/trane/configuration.rb', line 37

def frozen_config?
  @frozen
end

#on_missing_operation ⇒ Object

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.


62
63
64
 
# File 'lib/trane/configuration.rb', line 62

def on_missing_operation
  @on_missing_operation || :raise
end

#on_missing_operation=(value) ⇒ Object

Raises:

  • (FrozenError) 


66
67
68
69
70
71
72
73
74
 
# File 'lib/trane/configuration.rb', line 66

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

#reset! ⇒ Object 



119
120
121
122
123
124
 
# File 'lib/trane/configuration.rb', line 119

def reset!
  @strict_mode          = nil
  @contracts_paths      = nil
  @on_missing_operation = nil
  @frozen               = false
end