Class: Vagrant::Action::Builder
- Inherits:
-
Object
- Object
- Vagrant::Action::Builder
- Defined in:
- lib/vagrant/action/builder.rb
Overview
Action builder which provides a nice DSL for building up
a middleware sequence for Vagrant actions. This code is based
heavily off of Rack::Builder
and ActionDispatch::MiddlewareStack
in Rack and Rails, respectively.
Usage
Building an action sequence is very easy:
app = Vagrant::Action::Builder.new.tap do |b|
b.use MiddlewareA
b.use MiddlewareB
end
Vagrant::Action.run(app)
Defined Under Namespace
Classes: MiddlewareArguments, StackItem
Instance Attribute Summary collapse
-
#stack ⇒ Array
readonly
This is the stack of middlewares added.
Class Method Summary collapse
-
.build(middleware, *args, **keywords, &block) ⇒ Builder
This is a shortcut for a middleware sequence with only one item in it.
Instance Method Summary collapse
-
#apply_action_name(env) ⇒ Builder
If action hooks have not already been set, this method will perform three tasks: 1.
-
#apply_dynamic_updates(env) ⇒ Builder
Find any action hooks or triggers which have been defined for items within the stack.
-
#call(env) ⇒ Object
Runs the builder stack with the given environment.
-
#delete(index) ⇒ Object
Deletes the given middleware object or index.
-
#flatten ⇒ Object
Returns a mergeable version of the builder.
-
#index(object) ⇒ Integer
Returns the numeric index for the given middleware object.
-
#initialize ⇒ Builder
constructor
A new instance of Builder.
-
#initialize_copy(original) ⇒ Object
Implement a custom copy that copies the stack variable over so that we don't clobber that.
-
#insert(idx_or_item, middleware, *args, **keywords, &block) ⇒ Object
(also: #insert_before)
Inserts a middleware at the given index or directly before the given middleware object.
-
#insert_after(idx_or_item, middleware, *args, **keywords, &block) ⇒ Object
Inserts a middleware after the given index or middleware object.
-
#replace(index, middleware, *args, **keywords, &block) ⇒ Object
Replaces the given middlware object or index with the new middleware.
-
#to_app(env) ⇒ Warden
Converts the builder stack to a runnable action sequence.
-
#use(middleware, *args, **keywords, &block) ⇒ Object
Adds a middleware class to the middleware stack.
Constructor Details
#initialize ⇒ Builder
Returns a new instance of Builder.
40 41 42 |
# File 'lib/vagrant/action/builder.rb', line 40 def initialize @stack = [] end |
Instance Attribute Details
#stack ⇒ Array (readonly)
This is the stack of middlewares added. This should NOT be used directly.
29 30 31 |
# File 'lib/vagrant/action/builder.rb', line 29 def stack @stack end |
Class Method Details
.build(middleware, *args, **keywords, &block) ⇒ Builder
This is a shortcut for a middleware sequence with only one item in it. For a description of the arguments and the documentation, please see #use instead.
36 37 38 |
# File 'lib/vagrant/action/builder.rb', line 36 def self.build(middleware, *args, **keywords, &block) new.use(middleware, *args, **keywords, &block) end |
Instance Method Details
#apply_action_name(env) ⇒ Builder
If action hooks have not already been set, this method will perform three tasks:
- Load any hook triggers defined for the action_name
- Load any action_hooks defined from plugins
- Load any action triggers based on machine action called (not action classes)
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 |
# File 'lib/vagrant/action/builder.rb', line 260 def apply_action_name(env) return self if !env[:action_name] hook = Hook.new machine_name = env[:machine].name if env[:machine] # Start with loading any hook triggers if applicable if Vagrant::Util::Experimental.feature_enabled?("typed_triggers") && env[:triggers] if !env[:triggers].find(env[:action_name], :before, machine_name, :hook).empty? hook.prepend(Vagrant::Action::Builtin::Trigger, env[:action_name], env[:triggers], :before, :hook) end if !env[:triggers].find(env[:action_name], :after, machine_name, :hook).empty? hook.append(Vagrant::Action::Builtin::Trigger, env[:action_name], env[:triggers], :after, :hook) end end # Next we load up all the action hooks that plugins may # have defined action_hooks = Vagrant.plugin("2").manager.action_hooks(env[:action_name]) action_hooks.each do |hook_proc| hook_proc.call(hook) end # Finally load any action triggers defined. The action triggers # are the originally implemented trigger style. They run before # and after specific provider actions (like :up, :halt, etc) and # are different from true action triggers if env[:triggers] if !env[:triggers].find(env[:raw_action_name], :before, machine_name, :action, all: true).empty? hook.prepend(Vagrant::Action::Builtin::Trigger, env[:raw_action_name], env[:triggers], :before, :action, all: true) end if !env[:triggers].find(env[:raw_action_name], :after, machine_name, :action, all: true).empty? # NOTE: These after triggers need to be delayed before running to # allow the rest of the call stack to complete before being # run. The delayed action is prepended to the stack (not appended) # to ensure it is called first, which results in it properly # waiting for everything to finish before itself completing. builder = self.class.build(Vagrant::Action::Builtin::Trigger, env[:raw_action_name], env[:triggers], :after, :action, all: true) hook.prepend(Vagrant::Action::Builtin::Delayed, builder) end end # If the hooks are empty, then there was nothing to apply and # we can just send ourself back return self if hook.empty? # These are the options to pass into hook application. = {} # If we already ran through once and did append/prepends, # then don't do it again. if env[:action_hooks_already_ran] [:no_prepend_or_append] = true end # Specify that we already ran, so in the future we don't repeat # the prepend/append hooks. env[:action_hooks_already_ran] = true # Apply all the hooks to the new builder instance hook.apply(self, ) self end |
#apply_dynamic_updates(env) ⇒ Builder
Find any action hooks or triggers which have been defined for items within the stack. Update the stack with any hooks or triggers found.
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 |
# File 'lib/vagrant/action/builder.rb', line 198 def apply_dynamic_updates(env) if Vagrant::Util::Experimental.feature_enabled?("typed_triggers") triggers = env[:triggers] end # Use a Hook as a convenient interface for injecting # any applicable trigger actions within the stack machine_name = env[:machine].name if env[:machine] # Iterate over all items in the stack and apply new items # into the hook as they are found. Must be sure to dup the # stack here since we are modifying the stack in the loop. stack.dup.each do |item| hook = Hook.new action = item.first next if action.is_a?(Proc) # Start with adding any action triggers that may be defined if triggers && !triggers.find(action, :before, machine_name, :action).empty? hook.prepend(Vagrant::Action::Builtin::Trigger, action.name, triggers, :before, :action) end if triggers && !triggers.find(action, :after, machine_name, :action).empty? hook.append(Vagrant::Action::Builtin::Trigger, action.name, triggers, :after, :action) end # Next look for any hook triggers that may be defined against # the dynamically generated action class hooks if triggers && !triggers.find(action, :before, machine_name, :hook).empty? hook.prepend(Vagrant::Action::Builtin::Trigger, action.name, triggers, :before, :hook) end if triggers && !triggers.find(action, :after, machine_name, :hook).empty? hook.append(Vagrant::Action::Builtin::Trigger, action.name, triggers, :after, :hook) end # Finally load any registered hooks for dynamically generated # action class based hooks Vagrant.plugin("2").manager.find_action_hooks(action).each do |hook_proc| hook_proc.call(hook) end hook.apply(self, root: item) end # Apply the hook to ourself to update the stack self end |
#call(env) ⇒ Object
Runs the builder stack with the given environment.
148 149 150 |
# File 'lib/vagrant/action/builder.rb', line 148 def call(env) to_app(env).call(env) end |
#delete(index) ⇒ Object
Deletes the given middleware object or index
142 143 144 145 |
# File 'lib/vagrant/action/builder.rb', line 142 def delete(index) index = self.index(index) unless index.is_a?(Integer) stack.delete_at(index) end |
#flatten ⇒ Object
Returns a mergeable version of the builder. If use
is called with
the return value of this method, then the stack will merge, instead
of being treated as a separate single middleware.
55 56 57 58 59 |
# File 'lib/vagrant/action/builder.rb', line 55 def flatten lambda do |env| self.call(env) end end |
#index(object) ⇒ Integer
Returns the numeric index for the given middleware object.
156 157 158 159 160 161 162 163 164 165 |
# File 'lib/vagrant/action/builder.rb', line 156 def index(object) stack.each_with_index do |item, i| return i if item == object return i if item.middleware == object return i if item.middleware.respond_to?(:name) && item.middleware.name == object end nil end |
#initialize_copy(original) ⇒ Object
Implement a custom copy that copies the stack variable over so that we don't clobber that.
46 47 48 49 50 |
# File 'lib/vagrant/action/builder.rb', line 46 def initialize_copy(original) super @stack = original.stack.dup end |
#insert(idx_or_item, middleware, *args, **keywords, &block) ⇒ Object Also known as: insert_before
Inserts a middleware at the given index or directly before the given middleware object.
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 |
# File 'lib/vagrant/action/builder.rb', line 88 def insert(idx_or_item, middleware, *args, **keywords, &block) item = StackItem.new( middleware: middleware, arguments: MiddlewareArguments.new( parameters: args, keywords: keywords, block: block ) ) if idx_or_item.is_a?(Integer) index = idx_or_item else index = self.index(idx_or_item) end raise "no such middleware to insert before: #{index.inspect}" unless index if middleware.kind_of?(Builder) middleware.stack.reverse.each do |stack_item| stack.insert(index, stack_item) end else stack.insert(index, item) end end |
#insert_after(idx_or_item, middleware, *args, **keywords, &block) ⇒ Object
Inserts a middleware after the given index or middleware object.
118 119 120 121 122 123 124 125 126 127 |
# File 'lib/vagrant/action/builder.rb', line 118 def insert_after(idx_or_item, middleware, *args, **keywords, &block) if idx_or_item.is_a?(Integer) index = idx_or_item else index = self.index(idx_or_item) end raise "no such middleware to insert after: #{index.inspect}" unless index insert(index + 1, middleware, *args, &block) end |
#replace(index, middleware, *args, **keywords, &block) ⇒ Object
Replaces the given middlware object or index with the new middleware.
131 132 133 134 135 136 137 138 139 |
# File 'lib/vagrant/action/builder.rb', line 131 def replace(index, middleware, *args, **keywords, &block) if index.is_a?(Integer) delete(index) insert(index, middleware, *args, **keywords, &block) else insert_before(index, middleware, *args, **keywords, &block) delete(index) end end |
#to_app(env) ⇒ Warden
Converts the builder stack to a runnable action sequence.
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 |
# File 'lib/vagrant/action/builder.rb', line 171 def to_app(env) # Start with a duplicate of ourself which can # be modified builder = self.dup # Apply all dynamic modifications of the stack. This # will generate dynamic hooks for all actions within # the stack, load any triggers for action classes, and # apply them to the builder's stack builder.apply_dynamic_updates(env) # Now that the stack is fully expanded, apply any # action hooks that may be defined so they are on # the outermost locations of the stack builder.apply_action_name(env) # Wrap the middleware stack with the Warden to provide a consistent # and predictable behavior upon exceptions. Warden.new(builder.stack.dup, env) end |
#use(middleware, *args, **keywords, &block) ⇒ Object
Adds a middleware class to the middleware stack. Any additional args and a block, if given, are saved and passed to the initializer of the middleware.
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 |
# File 'lib/vagrant/action/builder.rb', line 66 def use(middleware, *args, **keywords, &block) item = StackItem.new( middleware: middleware, arguments: MiddlewareArguments.new( parameters: args, keywords: keywords, block: block ) ) if middleware.kind_of?(Builder) # Merge in the other builder's stack into our own self.stack.concat(middleware.stack) else self.stack << item end self end |