Class: Treaty::Action::Versions::Factory

Inherits:
Object
  • Object
show all
Defined in:
lib/treaty/action/versions/factory.rb

Overview

Factory for version configuration and DSL.

Purpose

Provides the DSL interface within version blocks. Captures all version configuration: summary, deprecation, request schema, response schema, and executor delegation.

Usage

Created by:

  • Versions::DSL (when version is called)

Consumed by:

  • Versions::Resolver (to find matching version)
  • Versions::Execution::Request (to execute the service)
  • Request::Validator / Response::Validator (to get schemas)
  • Info::Builder (to build version information)

DSL Methods

Method Purpose
summary Set version description text
deprecated Mark version as deprecated (bool or proc)
request Define request schema (block or entity class)
response Define response schema with status code
delegate_to Set service class/proc to execute

Example

version 1, default: true do
summary "Initial API version"

deprecated { ENV["V1_DEPRECATED"] == "true" }

request do
  object :post do
    string :title, :required
  end
end

response 201 do
  object :post do
    string :id
  end
end

delegate_to Posts::CreateService
end

Validation

  • default must be boolean or Proc
  • Cannot be both default and deprecated

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(version:, default:) ⇒ Factory

Creates a new version factory

Parameters:

  • version (Integer, String, Array) —

    Version identifier

  • default (Boolean, Proc) —

    Whether this is the default version



87
88
89
90
91
92
93
94
95
 
# File 'lib/treaty/action/versions/factory.rb', line 87

def initialize(version:, default:)
  @version = Semantic.new(version)
  @default_result = default.is_a?(Proc) ? default.call : default
  @summary_text = nil
  @deprecated_result = false
  @executor = nil

  validate!
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, &_block) ⇒ Object (private)

Catches unknown DSL methods with helpful error

Raises:



239
240
241
242
 
# File 'lib/treaty/action/versions/factory.rb', line 239

def method_missing(name, *, &_block)
  raise Treaty::Exceptions::MethodName,
        I18n.t("treaty.versioning.factory.unknown_method", method: name)
end

Instance Attribute Details

#default_result ⇒ Boolean (readonly)

Returns Whether this is the default version.

Returns:

  • (Boolean) —

    Whether this is the default version



66
67
68
 
# File 'lib/treaty/action/versions/factory.rb', line 66

def default_result
  @default_result
end

#deprecated_result ⇒ Boolean (readonly)

Returns Whether version is deprecated.

Returns:

  • (Boolean) —

    Whether version is deprecated



72
73
74
 
# File 'lib/treaty/action/versions/factory.rb', line 72

def deprecated_result
  @deprecated_result
end

#executor ⇒ Treaty::Action::Versions::Executor? (readonly)

Returns Executor configuration.

Returns:



75
76
77
 
# File 'lib/treaty/action/versions/factory.rb', line 75

def executor
  @executor
end

#request_factory ⇒ Treaty::Action::Request::Factory? (readonly)

Returns Request schema factory.

Returns:



78
79
80
 
# File 'lib/treaty/action/versions/factory.rb', line 78

def request_factory
  @request_factory
end

#response_factory ⇒ Treaty::Action::Response::Factory? (readonly)

Returns Response schema factory.

Returns:



81
82
83
 
# File 'lib/treaty/action/versions/factory.rb', line 81

def response_factory
  @response_factory
end

#summary_text ⇒ String? (readonly)

Returns Version summary/description.

Returns:

  • (String, nil) —

    Version summary/description



69
70
71
 
# File 'lib/treaty/action/versions/factory.rb', line 69

def summary_text
  @summary_text
end

#version ⇒ Treaty::Action::Versions::Semantic (readonly)

Returns Semantic version wrapper.

Returns:



63
64
65
 
# File 'lib/treaty/action/versions/factory.rb', line 63

def version
  @version
end

Instance Method Details

#delegate_to(executor, method = :call) ⇒ void

This method returns an undefined value.

Configures service delegation

Sets the executor (class, string, or proc) and method to call.

Examples:

Class reference

delegate_to Posts::CreateService

With custom method

delegate_to Posts::CreateService => :call!

String path

delegate_to "posts/create_service"

Lambda

delegate_to ->(params:) { { id: SecureRandom.uuid } }

Parameters:

  • executor (Class, String, Proc, Hash) —

    Service reference

  • method (Symbol) (defaults to: :call) —

    Method to call (default: :call)



195
196
197
 
# File 'lib/treaty/action/versions/factory.rb', line 195

def delegate_to(executor, method = :call)
  @executor = Executor.new(executor, method)
end

#deprecated(condition = nil) { ... } ⇒ void

This method returns an undefined value.

Marks version as deprecated

Accepts boolean, Proc, or block that evaluates to boolean. Deprecated versions raise error when accessed.

Parameters:

  • condition (Boolean, Proc, nil) (defaults to: nil) —

    Deprecation condition

Yields:

  • Block that returns boolean



128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/treaty/action/versions/factory.rb', line 128

def deprecated(condition = nil)
  result =
    if condition.is_a?(Proc)
      condition.call
    elsif condition.is_a?(TrueClass) || condition.is_a?(FalseClass)
      condition
    else
      yield
    end

  @deprecated_result = result
end

#request(entity_class = nil) { ... } ⇒ void

This method returns an undefined value.

Defines request schema

Accepts either an Entity class or a block with attribute definitions.

Parameters:

  • entity_class (Class, nil) (defaults to: nil) —

    Entity class for request schema

Yields:

  • Block with request attribute definitions



148
149
150
151
152
153
154
155
156
 
# File 'lib/treaty/action/versions/factory.rb', line 148

def request(entity_class = nil, &block)
  @request_factory ||= Request::Factory.new

  if entity_class.present?
    @request_factory.use_entity(entity_class)
  elsif block_given?
    @request_factory.instance_eval(&block)
  end
end

#response(status, entity_class = nil) { ... } ⇒ void

This method returns an undefined value.

Defines response schema with HTTP status

Accepts status code and either Entity class or block.

Parameters:

  • status (Integer) —

    HTTP status code (200, 201, 404, etc.)

  • entity_class (Class, nil) (defaults to: nil) —

    Entity class for response schema

Yields:

  • Block with response attribute definitions



166
167
168
169
170
171
172
173
174
 
# File 'lib/treaty/action/versions/factory.rb', line 166

def response(status, entity_class = nil, &block)
  @response_factory ||= Response::Factory.new(status)

  if entity_class.present?
    @response_factory.use_entity(entity_class)
  elsif block_given?
    @response_factory.instance_eval(&block)
  end
end

#summary(text) ⇒ void

This method returns an undefined value.

Sets version summary text

Parameters:

  • text (String) —

    Version description



116
117
118
 
# File 'lib/treaty/action/versions/factory.rb', line 116

def summary(text)
  @summary_text = text
end

#validate! ⇒ void

This method returns an undefined value.

Validates configuration on creation



100
101
102
 
# File 'lib/treaty/action/versions/factory.rb', line 100

def validate!
  validate_default_option!
end

#validate_after_block! ⇒ void

This method returns an undefined value.

Validates configuration after block evaluation

Raises:



108
109
110
 
# File 'lib/treaty/action/versions/factory.rb', line 108

def validate_after_block!
  validate_default_deprecated_conflict!
end