sourced-component 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require 'monitor'
4
+ require 'set'
4
5
  require 'tsort'
5
6
  require 'plumb'
6
7
  require_relative 'component/version'
@@ -14,6 +15,9 @@ require_relative 'component/graph'
14
15
  require_relative 'component/events'
15
16
  require_relative 'component/notifier'
16
17
  require_relative 'component/tree'
18
+ require_relative 'component/reconfiguration'
19
+ require_relative 'component/dir_source'
20
+ require_relative 'component/installable'
17
21
 
18
22
  module Sourced
19
23
  # A tree of components. Every node is a Component: it can declare a type, be implemented with
@@ -31,12 +35,16 @@ module Sourced
31
35
 
32
36
  # Lifecycle statuses, in order. Shared by the root (boot status) and every node.
33
37
  # Only nodes are ever :stopped: a started node stopped by key (see #stop_component!),
34
- # which can be started again.
35
- STATUSES = %i[open prepared built started stopped torn_down].freeze
38
+ # which can be started again. Only nodes are ever :removed either: a component a
39
+ # reconfiguration dropped from the tree (see #reconfigure), which is terminal.
40
+ STATUSES = %i[open prepared built started stopped torn_down removed].freeze
36
41
 
37
42
  # What #mount takes: anything that returns a Component from #to_component
38
43
  MountableInterface = Plumb::Types::Interface[:to_component]
39
44
 
45
+ # What #from_dir needs from a code loader, ex. a Zeitwerk::Loader (2.6.13+)
46
+ LoaderInterface = Plumb::Types::Interface[:cpath_expected_at, :on_setup]
47
+
40
48
  # key: local segment, ex. 'db'. nil for a root that isn't mounted anywhere
41
49
  # owner: the component that declared this node. Standalone components own themselves
42
50
  # type: the declared type. Any for implicit nodes created as intermediate segments (namespaces)
@@ -45,8 +53,9 @@ module Sourced
45
53
 
46
54
  # notifier: receives lifecycle events. See Component::Notifier and Component::Events.
47
55
  # The root's notifier receives the events of the whole tree, so a mounted component uses its root's.
48
- def initialize(owner: nil, type: Plumb::Undefined, notifier: Notifier.new)
56
+ def initialize(owner: nil, type: Plumb::Undefined, notifier: Notifier.new, loader: nil)
49
57
  @notifier = NotifierInterface.parse(notifier)
58
+ @loader = loader && LoaderInterface.parse(loader)
50
59
  @key = nil
51
60
  @parent = nil
52
61
  @owner = owner || self
@@ -57,6 +66,8 @@ module Sourced
57
66
  @value = nil
58
67
  @deferred = false # skipped by the root's #start!, see #defer
59
68
  @held = false # not started with the tree or its dependencies: deferred, or stopped by key
69
+ @recycle_to = nil # the status to come back to while recycling, see #recycle_component!
70
+ @reconfiguration = nil # the reconfiguration in progress, on the root only. See #reconfigure
60
71
  @deps = [].freeze # resolved deps: a node, or { segment => node } for a wildcard
61
72
  @dep_nodes = [].freeze # every node in @deps, for sorting
62
73
  @children = {}
@@ -67,6 +78,8 @@ module Sourced
67
78
  @starting = false
68
79
  @order = nil
69
80
  @lock = Monitor.new
81
+ @dir_sources = [] # see #from_dir
82
+ @deferred_injections = nil # see #deferring_injections, on the root only
70
83
  end
71
84
 
72
85
  def root = parent ? parent.root : self
@@ -75,6 +88,21 @@ module Sourced
75
88
  # The notifier lifecycle events are published to: the root's, for every component in the tree
76
89
  def notifier = root? ? @notifier : root.notifier
77
90
 
91
+ # The code loader for #from_dir, ex. a Zeitwerk::Loader. Set on the root, for the whole tree
92
+ def loader = root? ? @loader : root.loader
93
+
94
+ def loader=(loader)
95
+ synchronize do
96
+ raise SubcomponentError, "#{path} is mounted in another component: set the loader on the root" unless root?
97
+ raise LockedComponentError, "can't set the loader of a locked component" if locked?
98
+ if all_dir_sources.any?
99
+ raise ArgumentError, "can't replace the loader: #from_dir already registered with #{@loader.inspect}"
100
+ end
101
+
102
+ @loader = LoaderInterface.parse(loader)
103
+ end
104
+ end
105
+
78
106
  # Full key from the root, ex. 'sourced.db'. nil for the root
79
107
  def path
80
108
  return nil unless parent
@@ -87,8 +115,32 @@ module Sourced
87
115
 
88
116
  # Whether the root's #start! skips it (see #defer)
89
117
  def deferred? = @deferred
118
+ # Whether the tree is past :open. #mount asks this of the component being mounted
90
119
  def locked? = root.boot_status != :open
91
120
 
121
+ # Whether a reconfiguration's block is running. Only ever true on the root
122
+ def reconfiguring? = !@reconfiguration.nil?
123
+
124
+ # Whether the tree refuses declarations: locked, unless a #reconfigure block is open
125
+ private def declarations_locked? = locked? && !root.reconfiguring?
126
+
127
+ # The Reconfiguration in progress, which records what its block declares
128
+ protected def reconfiguration = @reconfiguration
129
+ protected def dir_sources = @dir_sources
130
+ protected def deferred_injections = @deferred_injections
131
+ protected def all_dir_sources = [self, *index.values].flat_map { |n| n.dir_sources }
132
+
133
+ # Load the files of each #from_dir. The branch is created even if no file declares anything,
134
+ # and outlives its files, so a reload can always reconfigure it
135
+ protected def install_dir_sources!
136
+ @dir_sources.each do |source|
137
+ next if source.installed?
138
+
139
+ walk("#{source.branch}._") unless source.branch.empty? # a directory per branch otherwise, see DirSource
140
+ source.install!
141
+ end
142
+ end
143
+
92
144
  def inspect
93
145
  details = namespace? ? '(namespace)' : "#{type_name} (#{[implementation&.mode || 'not implemented', status, ('deferred' if deferred?)].compact.join(', ')})"
94
146
  "#<#{self.class} #{path || '(root)'} #{details}>"
@@ -99,20 +151,28 @@ module Sourced
99
151
  # comp.declare('sourced.db.logger', Logger) { Logger.new(STDOUT) }
100
152
  def declare(ckey, type = T::Any, &default)
101
153
  synchronize do
102
- raise LockedComponentError, "can't declare #{ckey} in a locked component" if locked?
154
+ raise LockedComponentError, "can't declare #{ckey} in a locked component" if declarations_locked?
103
155
 
156
+ reconf = root.reconfiguration
104
157
  branch, leaf = walk(ckey)
105
158
  node = branch.children[leaf]
106
159
  if node.nil?
107
160
  node = branch.attach(leaf, Component.new(owner: self, type:))
108
161
  elsif !node.owner.equal?(self)
109
162
  raise OwnershipError, ownership_message(node)
110
- elsif !node.implicit?
163
+ elsif !node.implicit? && reconf.nil?
111
164
  raise DeclarationOverrideError, "#{node.path} is already declared"
112
165
  else
166
+ # Idempotent while reconfiguring: an unchanged component keeps its value and status,
167
+ # and a changed type marks it to be recycled
168
+ was = node.implicit? ? nil : node.type_name
113
169
  node.declare_type!(type) # an implicit namespace this component created, now with a type
170
+ reconf&.changed!(node) if was && was != node.type_name
114
171
  end
115
- emit(Events::ComponentDeclared, key: node.path, type_name: node.type_name)
172
+ new_to_the_tree = reconf.nil? || reconf.new?(node)
173
+ reconf&.declared!(node)
174
+ # While reconfiguring, only new components are announced: re-declaring the rest is noise
175
+ emit(Events::ComponentDeclared, key: node.path, type_name: node.type_name) if new_to_the_tree
116
176
 
117
177
  implement_node(node, Implementation.from_block([], implementer: self, mode: :singleton) { build(&default) }) if default
118
178
  self
@@ -180,7 +240,7 @@ module Sourced
180
240
  # and the alias follows it like any other dependent.
181
241
  def alias(ckey, target)
182
242
  synchronize do
183
- raise LockedComponentError, "can't implement #{ckey} in a locked component" if locked?
243
+ raise LockedComponentError, "can't implement #{ckey} in a locked component" if declarations_locked?
184
244
 
185
245
  implement_node(node(ckey), Implementation.alias(target, implementer: self))
186
246
  self
@@ -203,7 +263,7 @@ module Sourced
203
263
  end
204
264
 
205
265
  synchronize do
206
- raise LockedComponentError, "can't implement ENV components in a locked component" if locked?
266
+ raise LockedComponentError, "can't implement ENV components in a locked component" if declarations_locked?
207
267
 
208
268
  builders = mapping.map do |source, ckey|
209
269
  target = node(ckey)
@@ -217,6 +277,22 @@ module Sourced
217
277
  end
218
278
  end
219
279
 
280
+ # Implement a declared component by building +constructor+ on each read, from the components it
281
+ # injects: #__component_deps maps each one's key to the keyword argument it's injected as, so the
282
+ # component's dependencies and the constructor's arguments come from the same place.
283
+ # A constructor that injects nothing is built with no arguments.
284
+ # class Dispatcher
285
+ # include App.inject('logger', 'repos.users' => 'customers')
286
+ # end
287
+ # app.declare('dispatcher', Dispatcher)
288
+ # app.factory('dispatcher', Dispatcher) # Dispatcher.new(logger:, customers:)
289
+ # Keys are paths from the root of the injector's tree, so call this on that root.
290
+ def factory(ckey, constructor)
291
+ deps = constructor.respond_to?(:__component_deps) ? constructor.__component_deps : {}
292
+ config(ckey, deps.keys) { |*values| constructor.new(**deps.values.zip(values).to_h) }
293
+ self
294
+ end
295
+
220
296
  # Defer a node under this component: the root's #start! skips it, and every component that
221
297
  # depends on it, directly or not, since they can't start before it. Start it by key instead,
222
298
  # ex. when its process is elected to run it (see #start_component!).
@@ -227,7 +303,7 @@ module Sourced
227
303
  # implemented again. Any component can defer a node below it, like implementing one.
228
304
  def defer(ckey)
229
305
  synchronize do
230
- raise LockedComponentError, "can't defer #{ckey} in a locked component" if locked?
306
+ raise LockedComponentError, "can't defer #{ckey} in a locked component" if declarations_locked?
231
307
 
232
308
  target = node(ckey)
233
309
  target.defer!
@@ -254,7 +330,29 @@ module Sourced
254
330
  duplicates = names.values.tally.select { |_, count| count > 1 }.keys
255
331
  raise ArgumentError, "duplicate injected names: #{duplicates.join(', ')}" if duplicates.any?
256
332
 
257
- Injector.new(names.to_h { |key, _| [key, node(key)] }, names)
333
+ Injector.new(names.to_h { |key, _| [key, injected_node(key)] }, names)
334
+ end
335
+
336
+ # Run the block with injections of undeclared keys deferred, instead of raising, and return the
337
+ # deferred nodes, to resolve once their declarations have run. For #from_dir, whose files can
338
+ # inject each other's components in any order. Only on the root
339
+ def deferring_injections
340
+ synchronize do
341
+ raise LockedComponentError, "already deferring injections" if @deferred_injections
342
+
343
+ @deferred_injections = []
344
+ yield
345
+ @deferred_injections
346
+ ensure
347
+ @deferred_injections = nil
348
+ end
349
+ end
350
+
351
+ private def injected_node(key)
352
+ deferred = root.deferred_injections
353
+ return node(key) if deferred.nil? || declared?(key)
354
+
355
+ Injector::DeferredNode.new(self, key).tap { |n| deferred << n }
258
356
  end
259
357
 
260
358
  # Attach an existing standalone component as a branch. It keeps owning its declarations,
@@ -271,10 +369,13 @@ module Sourced
271
369
  raise ArgumentError, "#{mountable.inspect}.to_component must return a Component, got #{sub.inspect}" unless sub.is_a?(Component)
272
370
 
273
371
  synchronize do
274
- raise LockedComponentError, "can't mount #{ckey} in a locked component" if locked?
372
+ raise LockedComponentError, "can't mount #{ckey} in a locked component" if declarations_locked?
275
373
  raise SubcomponentError, "#{sub.inspect} is already mounted in another component" unless sub.root?
276
374
  raise SubcomponentError, "can't mount a component into its own tree" if sub.equal?(root)
277
375
  raise LockedComponentError, "can't mount a #{sub.boot_status} component: it must be open" if sub.locked?
376
+ if sub.loader
377
+ raise SubcomponentError, "can't mount #{ckey}: it has its own loader. Set the loader on the root of the tree instead"
378
+ end
278
379
 
279
380
  branch, leaf = walk(ckey)
280
381
  if (existing = branch.children[leaf])
@@ -289,6 +390,38 @@ module Sourced
289
390
  # The mountable interface (see #mount)
290
391
  def to_component = self
291
392
 
393
+ # Declare components from the Ruby files matching +glob+, autoloaded by the root's #loader.
394
+ # Each file's key is its path relative to +root+, prefixed with +namespace+, and the constant
395
+ # Zeitwerk expects in it declares its components with .__install_component(declarer).
396
+ # See DirSource::Declarer.
397
+ # app.loader = loader # once, on the root: see #loader=
398
+ # app.from_dir('lib/**/*.rb') # lib/queries/users/search.rb => 'lib.queries.users.search'
399
+ # app.from_dir('app/queries/**/*.rb', root: 'app/queries', namespace: 'queries')
400
+ # Files are loaded on the root's #prepare!, so the components they inject are declared by then.
401
+ # When the loader reloads, the branch above the glob's first wildcard is reconfigured from the new
402
+ # constants (see #reconfigure). A failed reload leaves the tree as it was and calls +on_error+.
403
+ def from_dir(glob, root: Dir.pwd, namespace: nil, on_error: DirSource::DEFAULT_ON_ERROR)
404
+ source = synchronize do
405
+ # Not even while reconfiguring: sources are only installed on #prepare!
406
+ raise LockedComponentError, "can't add #{glob} to a locked component" if locked?
407
+
408
+ loader = self.loader
409
+ unless loader
410
+ raise MissingLoaderError,
411
+ "from_dir #{glob}: the tree has no code loader. Set one on the root, " \
412
+ "ex. Sourced::Component.new(loader: Zeitwerk::Loader.new) or root.loader = loader"
413
+ end
414
+
415
+ source = DirSource.new(self, glob, loader:, root:, namespace:, on_error:)
416
+ DirSource.check_overlaps!([*self.root.all_dir_sources, source]) # self.root: root is the keyword here
417
+ @dir_sources << source
418
+ source
419
+ end
420
+ # Outside the tree's lock: Zeitwerk calls back under its own lock, and the callback takes the tree's
421
+ loader.on_setup { source.reload! }
422
+ self
423
+ end
424
+
292
425
  # A node under this component, by relative key
293
426
  def node(ckey)
294
427
  index.fetch(ckey.to_s) { raise UndeclaredComponentError, "#{ckey} is not declared in #{path || 'this component'}" }
@@ -300,6 +433,7 @@ module Sourced
300
433
  def [](ckey) = node(ckey).read
301
434
 
302
435
  def read
436
+ raise RemovedComponentError, "#{path} was removed from the tree" if removed?
303
437
  raise NotBuiltError, 'component is not built yet' unless root.readable?
304
438
  raise UndeclaredComponentError, "#{path} is a namespace, not a component" unless implementation
305
439
 
@@ -316,7 +450,11 @@ module Sourced
316
450
  return self if past?(:prepared)
317
451
 
318
452
  instrument_root(:prepare) do
453
+ [self, *index.values].each { |n| n.install_dir_sources! }
319
454
  @order = resolve_order
455
+ # Holds start from the declarations, on a first boot only: #reresolve! must leave the ones
456
+ # #stop_component! set alone, or a reconfiguration would start a stopped component again
457
+ @order.each { |n| n.release!; n.hold! if n.deferred? }
320
458
  @order.each { |n| instrument_component(n, :prepare) { n.prepare_node! } }
321
459
  @boot_status = :prepared
322
460
  end
@@ -463,6 +601,98 @@ module Sourced
463
601
  end
464
602
  end
465
603
 
604
+ # ---- Recycling components -------------------------------------------------------
605
+
606
+ # Run a component's whole lifecycle again, by key relative to this component: stop it if it's
607
+ # running, tear it down, drop its value, then prepare and build it from scratch.
608
+ # Every component depending on it, directly or not, is recycled too: their values were built
609
+ # from its old one. Its own dependencies are left alone.
610
+ # Each one is left in the status it had before, so a started component is started again with
611
+ # +context+, and one that was only built stops at built. A component that was stopped by key
612
+ # (or deferred) comes back built and still held: the fresh value has never run, so it waits to
613
+ # be started by key, as it was.
614
+ # If a stop or teardown hook raises, every component is still torn down and its value dropped,
615
+ # and the first error is re-raised before anything is prepared again. A prepare, build or start
616
+ # hook leaves the component where it got to. Either way, recycling again recovers: each one
617
+ # remembers the status to restore until a recycle completes, so a retry puts it back even when
618
+ # its own status no longer says it was running.
619
+ # The root must be built, or started, and not booting.
620
+ # app.recycle_component!('sourced.store')
621
+ def recycle_component!(ckey, context = Thread.current)
622
+ recycle_components!(ckey, context:)
623
+ end
624
+
625
+ # #recycle_component! for several keys at once: a component depending on more than one of them
626
+ # is recycled once, not once per key.
627
+ # app.recycle_components!('sourced.store', 'repos.users')
628
+ def recycle_components!(*ckeys, context: Thread.current)
629
+ synchronize do
630
+ nodes = ckeys.flatten.map { |ckey| recyclable_node(ckey) }
631
+ # Recycling nothing resolves no nodes, so it checks the tree itself, and does nothing
632
+ if nodes.empty?
633
+ check_recyclable!('components')
634
+ return self
635
+ end
636
+
637
+ recycle_nodes!(nodes, context)
638
+ end
639
+ end
640
+
641
+ # #recycle_component! for every component in the tree, in dependency order. Only the root
642
+ # can recycle the whole tree.
643
+ # app.recycle!
644
+ def recycle!(context = Thread.current)
645
+ raise_mounted!
646
+ synchronize do
647
+ check_recyclable!('the tree')
648
+ recycle_nodes!(order, context)
649
+ end
650
+ end
651
+
652
+ # ---- Re-configuring a booted tree ----------------------------------------------
653
+
654
+ # Re-declare one branch of a booted tree, by key relative to this component. The block declares
655
+ # the branch's new contents, and whatever it doesn't declare is removed.
656
+ # Re-declaring a key is idempotent, so a component that didn't change keeps its value and status.
657
+ # Re-implementing it, re-typing it, or declaring a new key recycles it (see #recycle_component!),
658
+ # along with its dependents and anything whose resolved deps changed, ex. a wildcard over the branch.
659
+ # Nothing runs any hooks until the new set is validated, so a block that raises, or a set with a
660
+ # missing dep or a cycle, leaves the tree as it was. Holds survive: stopped stays stopped.
661
+ # app.reconfigure('reactors') do |reactors|
662
+ # files.each { |f| reactors.declare(f.key) }
663
+ # changed.each { |f| reactors.component!(f.key, f.deps, &f.implementation) }
664
+ # end
665
+ # Several branches are re-declared at once, and validated together, given an Array of keys.
666
+ # The block gets a handle per branch:
667
+ # app.reconfigure(%w[users accounts]) { |users, accounts| }
668
+ def reconfigure(ckey, context = Thread.current, &block)
669
+ raise ArgumentError, "reconfigure #{ckey}: a block must declare the branch's contents" unless block
670
+
671
+ synchronize do
672
+ check_reconfigurable!
673
+ branches = Array(ckey).map { |k| reconfigurable_branch(k) }
674
+ reconf = Reconfiguration.new(branches, self)
675
+ root.reconfiguring!(reconf)
676
+
677
+ begin
678
+ instrument_root(:reconfigure) do
679
+ reconf.snapshot!
680
+ plan = begin
681
+ block.call(*reconf.branch_handles)
682
+ validate_reconfiguration!(reconf)
683
+ rescue Exception # rubocop:disable Lint/RescueException -- nothing has run yet: put the tree back, whatever it was. Always re-raised
684
+ reconf.rollback!
685
+ raise
686
+ end
687
+ commit_reconfiguration!(reconf, plan, context)
688
+ end
689
+ ensure
690
+ root.reconfiguring!(nil)
691
+ end
692
+ self
693
+ end
694
+ end
695
+
466
696
  # A Component::Graph describing the components under this component, by full path from the root.
467
697
  # Components are listed in dependency order once the tree is prepared, and in declaration order before that.
468
698
  # Namespaces without an implementation are left out.
@@ -519,7 +749,7 @@ module Sourced
519
749
  type:,
520
750
  type_name:,
521
751
  namespace: namespace?,
522
- mounted: !root? && owner.equal?(self),
752
+ mounted: mounted?,
523
753
  implemented: !implementation.nil?,
524
754
  mode: implementation&.mode,
525
755
  status:,
@@ -540,11 +770,18 @@ module Sourced
540
770
 
541
771
  # ---- Node internals -------------------------------------------------------------
542
772
 
773
+ # The nodes this one depends on, resolved on #prepare!, wildcards included. See #graph for keys
774
+ def dep_nodes = @dep_nodes
775
+
776
+ # Every node in dependency order, or nil before #prepare!. #ordered_nodes is the checked version
777
+ def order = @order
778
+
779
+ # Whether a #reconfigure dropped this node. Terminal: reading it raises RemovedComponentError
780
+ def removed? = status == :removed
781
+
543
782
  protected def readable? = @readable
544
783
  protected def starting? = @starting
545
784
  protected def lock = @lock
546
- protected def dep_nodes = @dep_nodes
547
- protected def order = @order
548
785
 
549
786
  private def synchronize(&) = root.lock.synchronize(&)
550
787
 
@@ -553,6 +790,29 @@ module Sourced
553
790
  @type = Plumb::Composable.wrap(type)
554
791
  end
555
792
 
793
+ # Back to an implicit namespace: a dropped component that still has children (see #reconfigure).
794
+ # Returns the implementation it had, to tear it down with, and keeps its value until then.
795
+ # Clearing it before the order is resolved leaves it out, and fails validation for its dependents
796
+ protected def undeclare_type!
797
+ @implicit = true
798
+ @type = Plumb::Types::Any
799
+ @deps = [].freeze
800
+ @dep_nodes = [].freeze
801
+ @implementation.tap { @implementation = nil }
802
+ end
803
+
804
+ # Run a reverted component's hooks with the implementation it had, then leave it a bare namespace
805
+ protected def teardown_reverted!(implementation)
806
+ return self unless pending?(:teardown)
807
+
808
+ begin
809
+ implementation.stop(value) if started?
810
+ ensure
811
+ implementation.teardown(value)
812
+ end
813
+ recycle_node!
814
+ end
815
+
556
816
  protected def implement!(implementation)
557
817
  @implementation = implementation
558
818
  end
@@ -563,6 +823,48 @@ module Sourced
563
823
  protected def release! = @held = false
564
824
  protected def started? = status == :started
565
825
 
826
+ # A component mounted into another tree: it owns itself, and isn't the root of its own
827
+ protected def mounted? = !root? && owner.equal?(self)
828
+
829
+ # ---- Reconfiguration internals (see #reconfigure) -------------------------------
830
+
831
+ # Public because Component::Reconfiguration is a collaborator, not another Component
832
+
833
+ def reconfiguring!(reconf) = @reconfiguration = reconf
834
+ def restore_order!(order) = @order = order
835
+
836
+ # Re-resolve every node's deps and the order, leaving holds alone. Raises if the new set is invalid
837
+ def reresolve! = resolve_order
838
+
839
+ # Everything a reconfiguration can change about this node, as a frozen
840
+ # Reconfiguration::NodeState. #children and #index are the node's own mutable hashes, so they're
841
+ # copied; everything else is frozen, or a reference it has to keep as it is — its value above all
842
+ def capture_state
843
+ Reconfiguration::NodeState.new(
844
+ implementation:, type:, implicit: implicit?, deps:, dep_nodes:, deferred: deferred?,
845
+ held: held?, status:, value:, recycle_to:, children: children.dup, index: index.dup
846
+ )
847
+ end
848
+
849
+ # Every member, so a new one can't be captured and then forgotten on the way back
850
+ def restore_state!(state)
851
+ state.to_h.each { |member, value| send(:"#{member}=", value) }
852
+ self
853
+ end
854
+
855
+ # Only #capture_state and #restore_state! use these: a reconfiguration rolling back is the one
856
+ # thing that writes a node's state wholesale
857
+ private attr_reader :deps
858
+ private attr_writer :implementation, :type, :implicit, :deps, :dep_nodes, :deferred, :held,
859
+ :status, :value, :recycle_to, :children, :index
860
+
861
+ # The status a recycle is bringing this node back to, remembered before anything is torn down.
862
+ # A recycle that raises leaves it set, so a retry restores what the first one meant to: the
863
+ # node's own status is no use by then, ex. :built for one a failed start never reached
864
+ protected def recycle_to = @recycle_to
865
+ protected def recycle_to!(status) = @recycle_to = status
866
+ protected def recycled! = @recycle_to = nil
867
+
566
868
  # Every node this one depends on, directly or not
567
869
  protected def transitive_dependencies
568
870
  dep_nodes.each_with_object([]) do |dep, all|
@@ -602,6 +904,22 @@ module Sourced
602
904
  parent&.index!("#{key}.#{ckey}", node)
603
905
  end
604
906
 
907
+ # The inverse of #index!: drop a descendant here and in every ancestor
908
+ protected def unindex!(ckey)
909
+ @index.delete(ckey)
910
+ parent&.unindex!("#{key}.#{ckey}")
911
+ end
912
+
913
+ # Drop a child and its descendants from this node's children, and from every index
914
+ protected def detach!(segment)
915
+ child = @children.delete(segment)
916
+ return nil unless child
917
+
918
+ child.index.each_key { |sub_key| unindex!("#{segment}.#{sub_key}") }
919
+ unindex!(segment)
920
+ child
921
+ end
922
+
605
923
  # Resolve deps through the implementer's index. Called on #prepare!, so declaration order doesn't matter.
606
924
  # A wildcard dep ('reactors.*') resolves to a hash of the components directly under its key, by segment,
607
925
  # and to an empty hash if there are none.
@@ -651,6 +969,7 @@ module Sourced
651
969
 
652
970
  implementation.start(value, context)
653
971
  @status = :started
972
+ recycled! # whatever a recycle meant to restore, this is the node's status now
654
973
  self
655
974
  end
656
975
 
@@ -662,25 +981,55 @@ module Sourced
662
981
  implementation.stop(value)
663
982
  ensure
664
983
  @status = :stopped
984
+ recycled! # ... and the same when a component is stopped by key
665
985
  end
666
986
  self
667
987
  end
668
988
 
669
- # A started node runs its stop hooks first. Teardown hooks run even if those raise
989
+ # A started node runs its stop hooks first. Teardown hooks run even if those raise, and the node
990
+ # is torn down whatever they raise (incl. Interrupt): its hooks have had their turn either way,
991
+ # and running them again would tear the same value down twice
670
992
  protected def teardown_node!
671
993
  return self unless pending?(:teardown)
672
994
 
995
+ was_started = started?
996
+ @status = :torn_down
673
997
  begin
674
- implementation.stop(value) if started?
998
+ implementation.stop(value) if was_started
675
999
  ensure
676
1000
  implementation.teardown(value)
677
1001
  end
678
- @status = :torn_down
1002
+ self
1003
+ end
1004
+
1005
+ # Back to :open, so every hook runs again from the top (see #recycle_component!).
1006
+ # Keeps the node's hold, its deps and its place in the root's order: the tree is locked,
1007
+ # so nothing about the graph can have changed
1008
+ protected def recycle_node!
1009
+ @status = :open
1010
+ @value = nil
1011
+ self
1012
+ end
1013
+
1014
+ # Whether the node has been built. A torn down node keeps its value, which stays readable;
1015
+ # recycling drops it, back to :open, and removing it drops it for good
1016
+ protected def built? = !%i[open prepared removed].include?(status)
1017
+
1018
+ # Drop the value and mark the node removed, once torn down: anything still holding it (an
1019
+ # Injector, say) then fails loudly instead of reading a dead value. Terminal
1020
+ protected def remove_node!
1021
+ @value = nil
1022
+ @status = :removed
679
1023
  self
680
1024
  end
681
1025
 
682
1026
  # Without the readable check: deps are read while the component is building, in dependency order
683
- protected def current_value = memoized? ? value : build_value
1027
+ protected def current_value
1028
+ raise RemovedComponentError, "#{path} was removed from the tree" if removed?
1029
+ raise NotBuiltError, "#{path} is not built: it was torn down or recycled" if memoized? && !built?
1030
+
1031
+ memoized? ? value : build_value
1032
+ end
684
1033
 
685
1034
  # Whether the value is built once, on #build!: singletons, and aliases of memoized components.
686
1035
  # Only known once deps are resolved, on #prepare!
@@ -735,11 +1084,7 @@ module Sourced
735
1084
  raise UnimplementedComponentError, "components are deferred but not implemented: #{deferred_namespaces.map(&:path).join(', ')}"
736
1085
  end
737
1086
 
738
- nodes.each do |n|
739
- n.resolve_deps!
740
- n.release!
741
- n.hold! if n.deferred?
742
- end
1087
+ nodes.each { |n| n.resolve_deps! }
743
1088
 
744
1089
  each_node = ->(&b) { nodes.each(&b) }
745
1090
  each_child = ->(n, &b) { n.dep_nodes.each(&b) }
@@ -758,7 +1103,7 @@ module Sourced
758
1103
  next if !include_built && n.status == :built
759
1104
 
760
1105
  instrument_component(n, :teardown) { n.teardown_node! }
761
- rescue StandardError => e
1106
+ rescue Exception => e # rubocop:disable Lint/RescueException -- any error (incl. Interrupt) must still tear the rest down. The first is re-raised
762
1107
  errors << e
763
1108
  end
764
1109
  end
@@ -784,6 +1129,138 @@ module Sourced
784
1129
  target
785
1130
  end
786
1131
 
1132
+ # A node to recycle by key: implemented, under a root that can be recycled
1133
+ private def recyclable_node(ckey)
1134
+ target = node(ckey)
1135
+ raise UndeclaredComponentError, "#{target.path} is a namespace, not a component" if target.namespace?
1136
+
1137
+ check_recyclable!(target.path)
1138
+ target
1139
+ end
1140
+
1141
+ # A branch to reconfigure: a namespace, under a tree that isn't booting or torn down
1142
+ private def check_reconfigurable!
1143
+ raise LockedComponentError, "can't reconfigure: a reconfiguration is already running" if root.reconfiguring?
1144
+ raise TornDownError, "can't reconfigure: the component is torn down" if root.boot_status == :torn_down
1145
+ raise LockedComponentError, "can't reconfigure while the root is booting" if root.starting?
1146
+ end
1147
+
1148
+ private def reconfigurable_branch(ckey)
1149
+ branch = node(ckey)
1150
+ unless branch.namespace?
1151
+ raise UndeclaredComponentError, "#{branch.path} is a component, not a namespace: reconfigure the branch above it"
1152
+ end
1153
+
1154
+ mounted = [branch, *branch.index.values].find { |n| n.mounted? }
1155
+ raise SubcomponentError, "can't reconfigure #{branch.path}: #{mounted.path} is a mounted component" if mounted
1156
+
1157
+ branch
1158
+ end
1159
+
1160
+ # Apply the new set structurally and re-resolve, before any hooks run: raises what a first boot
1161
+ # would if it's invalid, with nothing torn down yet
1162
+ private def validate_reconfiguration!(reconf)
1163
+ reverting = reconf.reverting
1164
+ removing = reconf.removing
1165
+
1166
+ # Each reverted component hands its implementation back, to tear down once validation passes
1167
+ reverted = reverting.to_h { |n| [n, n.undeclare_type!] }
1168
+ removing.each { |n| n.parent.detach!(n.key) }
1169
+
1170
+ # An open tree has nothing resolved or built: #prepare! validates the set when it boots
1171
+ { reverted:, removing:, order: root.boot_status == :open ? nil : root.reresolve! }
1172
+ end
1173
+
1174
+ # Past validation, so nothing here rolls back: tear down what's going, recycle what changed
1175
+ private def commit_reconfiguration!(reconf, plan, context)
1176
+ booted = !plan[:order].nil?
1177
+ was = reconf.order_before.each_with_index.to_h
1178
+ root.restore_order!(plan[:order]) if booted
1179
+
1180
+ # Dependents first. On an open tree every hook is pending?-skipped, so this only unindexes
1181
+ going = plan[:removing] + plan[:reverted].keys
1182
+ going.sort_by { |n| -(was[n] || -1) }.each do |n|
1183
+ if (implementation = plan[:reverted][n])
1184
+ instrument_component(n, :teardown) { n.teardown_reverted!(implementation) }
1185
+ next
1186
+ end
1187
+
1188
+ instrument_component(n, :teardown) { n.teardown_node! }
1189
+ n.remove_node!
1190
+ emit(Events::ComponentRemoved, key: n.path, remover: path)
1191
+ end
1192
+ return unless booted
1193
+
1194
+ # Nothing new has a status to go back to, so it comes up to where the root is: :prepared,
1195
+ # :built or :started. Deferring lowers that ceiling to :built, never raises it
1196
+ coming_up = root.boot_status
1197
+ reconf.newly_components.each do |n|
1198
+ n.hold! if n.deferred?
1199
+ n.recycle_to!(n.deferred? && coming_up == :started ? :built : coming_up)
1200
+ end
1201
+ affected = reconf.affected
1202
+ recycle_nodes!(affected, context) if affected.any?
1203
+ end
1204
+
1205
+ # Whether the tree can be recycled: built or started, and not booting. +what+ names what
1206
+ # the caller is recycling, for the error messages
1207
+ private def check_recyclable!(what)
1208
+ raise TornDownError, "can't recycle #{what}: the component is torn down" if root.boot_status == :torn_down
1209
+ if root.starting?
1210
+ raise LockedComponentError, "can't recycle #{what} while the root is booting: it has no status to go back to"
1211
+ end
1212
+ return if %i[built started].include?(root.boot_status)
1213
+
1214
+ raise NotBuiltError, "can't recycle #{what} before the root is built: build! it first"
1215
+ end
1216
+
1217
+ # Tear the targets and their dependents down, drop their values, and prepare and build them
1218
+ # again, leaving each one in the status it had before. See #recycle_component!
1219
+ private def recycle_nodes!(targets, context)
1220
+ # Nodes come after their dependencies in the order, so one forward pass seeded with every
1221
+ # target reaches the same nodes as a closure per target, without the walk-per-target
1222
+ reached = targets.to_set
1223
+ root.order.each { |n| reached << n if n.dep_nodes.any? { |dep| reached.include?(dep) } }
1224
+ ordered = root.order.select { |n| reached.include?(n) }
1225
+ # What each node comes back to, remembered before anything is torn down. A node a previous
1226
+ # recycle left part way through keeps the status that recycle meant to restore
1227
+ ordered.each { |n| n.recycle_to!(n.recycle_to || n.status) }
1228
+
1229
+ instrument_root(:recycle) do
1230
+ # Down, dependents first. Started nodes run their stop hooks, then their teardown hooks.
1231
+ # Their values are dropped whatever a hook raises (incl. Interrupt): they've been torn down
1232
+ errors = []
1233
+ begin
1234
+ ordered.reverse.each do |n|
1235
+ instrument_component(n, :teardown) { n.teardown_node! }
1236
+ rescue Exception => e # rubocop:disable Lint/RescueException -- as #teardown_nodes: the rest are still torn down
1237
+ errors << e
1238
+ end
1239
+ ensure
1240
+ ordered.each { |n| n.recycle_node! }
1241
+ end
1242
+ raise errors.first if errors.any?
1243
+
1244
+ # And up again, in dependency order, one stage at a time, as the root boots
1245
+ ordered.each { |n| instrument_component(n, :prepare) { n.prepare_node! } }
1246
+ ordered.each do |n|
1247
+ # A tree that's only prepared stops there: its values are built by #build!, which is what
1248
+ # a process forked after #prepare! runs for itself
1249
+ next if n.recycle_to == :prepared
1250
+
1251
+ instrument_component(n, :build) { n.build_node! }
1252
+ end
1253
+ ordered.each do |n|
1254
+ next unless n.recycle_to == :started && n.dep_nodes.all? { |dep| dep.started? }
1255
+
1256
+ instrument_component(n, :start) { n.start_node!(context) }
1257
+ end
1258
+ # Only once every node is back: a recycle that raises keeps the statuses for the retry
1259
+ ordered.each { |n| n.recycled! }
1260
+ end
1261
+ self
1262
+ end
1263
+
787
1264
  # ---- Telemetry ------------------------------------------------------------------
788
1265
 
789
1266
  # Publish root.<stage>ing, run the block, and publish root.<stage>ed with its duration,
@@ -864,7 +1341,7 @@ module Sourced
864
1341
  raise ArgumentError, "#{ckey}: pass either a provider or a block, not both" if provider && block
865
1342
 
866
1343
  synchronize do
867
- raise LockedComponentError, "can't implement #{ckey} in a locked component" if locked?
1344
+ raise LockedComponentError, "can't implement #{ckey} in a locked component" if declarations_locked?
868
1345
 
869
1346
  target = node(ckey)
870
1347
  implementation = if provider
@@ -880,6 +1357,7 @@ module Sourced
880
1357
  private def implement_node(target, implementation)
881
1358
  override = !target.implementation.nil?
882
1359
  target.implement!(implementation)
1360
+ root.reconfiguration&.changed!(target)
883
1361
  emit(
884
1362
  Events::ComponentImplemented,
885
1363
  key: target.path,