Class: Seahorse::Client::HandlerList

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/seahorse/client/handler_list.rb

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ HandlerList

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of HandlerList.



11
12
13
14
15
16
17
 
# File 'lib/seahorse/client/handler_list.rb', line 11

def initialize(options = {})
  @index = options[:index] || 0
  @entries = {}
  @mutex = Mutex.new
  entries = options[:entries] || []
  add_entries(entries) unless entries.empty?
end

Instance Method Details

#add(handler_class, options = {}) ⇒ Class<Handler>

Note:

There can be only one ‘:send` handler. Adding an additional send handler replaces the previous.

Registers a handler. Handlers are used to build a handler stack. Handlers default to the ‘:build` step with default priority of 50. The step and priority determine where in the stack a handler will be.

## Handler Stack Ordering

A handler stack is built from the inside-out. The stack is seeded with the send handler. Handlers are constructed recursively in reverse step and priority order so that the highest priority handler is on the outside.

By constructing the stack from the inside-out, this ensures that the validate handlers will be called first and the sign handlers will be called just before the final and only send handler is called.

## Steps

Handlers are ordered first by step. These steps represent the life-cycle of a request. Valid steps are:

  • ‘:initialize`

  • ‘:validate`

  • ‘:build`

  • ‘:sign`

  • ‘:send`

Many handlers can be added to the same step, except for ‘:send`. There can be only one `:send` handler. Adding an additional `:send` handler replaces the previous one.

## Priorities

Handlers within a single step are executed in priority order. The higher the priority, the earlier in the stack the handler will be called.

  • Handler priority is an integer between 0 and 99, inclusively.

  • Handler priority defaults to 50.

  • When multiple handlers are added to the same step with the same priority, the last one added will have the highest priority and the first one added will have the lowest priority.

Parameters:

Options Hash (options):

  • :step (Symbol) — default: :build —

    The request life-cycle step the handler should run in. Defaults to ‘:build`. The list of possible steps, in high-to-low priority order are:

    • ‘:initialize`

    • ‘:validate`

    • ‘:build`

    • ‘:sign`

    • ‘:send`

    There can only be one send handler. Registering an additional ‘:send` handler replaces the previous one.

  • :priority (Integer) — default: 50 —

    The priority of this handler within a step. The priority must be between 0 and 99 inclusively. It defaults to 50. When two handlers have the same ‘:step` and `:priority`, the handler registered last has the highest priority.

  • :operations (Array<Symbol,String>) —

    A list of operations names the handler should be applied to. When ‘:operations` is omitted, the handler is applied to all operations for the client.

Returns:

  • (Class<Handler>) —

    Returns the handler class that was added.

Raises:

  • (InvalidStepError)
  • (InvalidPriorityError) 


103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/seahorse/client/handler_list.rb', line 103

def add(handler_class, options = {})
  @mutex.synchronize do
    add_entry(
      HandlerListEntry.new(options.merge(
        handler_class: handler_class,
        inserted: next_index
      ))
    )
  end
  handler_class
end

#copy_from(source_list, &block) ⇒ void

This method returns an undefined value.

Copies handlers from the ‘source_list` onto the current handler list. If a block is given, only the entries that return a `true` value from the block will be copied.

Parameters:



127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/seahorse/client/handler_list.rb', line 127

def copy_from(source_list, &block)
  entries = []
  source_list.entries.each do |entry|
    if block_given?
      entries << entry.copy(inserted: next_index) if yield(entry)
    else
      entries << entry.copy(inserted: next_index)
    end
  end
  add_entries(entries)
end

#each(&block) ⇒ Object

Yields the handlers in stack order, which is reverse priority.



149
150
151
152
153
 
# File 'lib/seahorse/client/handler_list.rb', line 149

def each(&block)
  entries.sort.each do |entry|
    yield(entry.handler_class) if entry.operations.nil?
  end
end

#entries ⇒ Array<HandlerListEntry>

Returns:



20
21
22
23
24
 
# File 'lib/seahorse/client/handler_list.rb', line 20

def entries
  @mutex.synchronize do
    @entries.values
  end
end

#for(operation) ⇒ HandlerList

Returns a handler list for the given operation. The returned will have the operation specific handlers merged with the common handlers.

Parameters:

  • operation (String) —

    The name of an operation.

Returns:



144
145
146
 
# File 'lib/seahorse/client/handler_list.rb', line 144

def for(operation)
  HandlerList.new(index: @index, entries: filter(operation.to_s))
end

#remove(handler_class) ⇒ Object

Parameters:



116
117
118
119
120
 
# File 'lib/seahorse/client/handler_list.rb', line 116

def remove(handler_class)
  @entries.each do |key, entry|
    @entries.delete(key) if entry.handler_class == handler_class
  end
end

#to_stack ⇒ Handler

Constructs the handlers recursively, building a handler stack. The ‘:send` handler will be at the top of the stack and the `:validate` handlers will be at the bottom.

Returns:



159
160
161
 
# File 'lib/seahorse/client/handler_list.rb', line 159

def to_stack
  inject(nil) { |stack, handler| handler.new(stack) }
end