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.
@@ -0,0 +1,187 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sourced
4
+ class Component
5
+ # Components declared by the Ruby files matching a glob, through a Zeitwerk loader. See Component#from_dir.
6
+ # Each file's key is its path relative to +root+, prefixed with +namespace+:
7
+ # lib/queries/users/search.rb => 'lib.queries.users.search'
8
+ # The file's constant (as Zeitwerk expects it) declares its components with
9
+ # .__install_component(declarer), where the declarer is scoped to that key. Constants that
10
+ # don't respond to it are skipped.
11
+ # Reloads re-declare the branch above the glob's first wildcard. With no such branch (root: is
12
+ # the directory scanned, and no namespace:), each top-level directory is a branch of its own:
13
+ # system/users/create.rb, system/queries/search.rb, root: 'system' => 'users.create', 'queries.search'
14
+ class DirSource
15
+ INSTALL = :__install_component
16
+ GLOB_CHARS = /[*?\[{]/
17
+ DEFAULT_ON_ERROR = lambda do |error|
18
+ Kernel.warn("[Sourced::Component] reloading components failed: #{error.class}: #{error.message}")
19
+ end
20
+
21
+ # branch: the key every file is declared under, relative to the owner. Reconfigured on reload.
22
+ # Empty when each top-level directory is a branch
23
+ # error: the last reload's error, nil once a reload succeeds
24
+ attr_reader :branch, :error
25
+
26
+ def initialize(owner, glob, loader:, root:, namespace:, on_error:)
27
+ @owner = owner
28
+ @loader = loader
29
+ @root = File.expand_path(root.to_s)
30
+ @namespace = namespace&.to_s
31
+ @on_error = on_error
32
+ @glob, static_dir = expand(glob.to_s)
33
+ @branch = key_for(static_dir)
34
+ @installed = false
35
+ @error = nil
36
+ @claimed = [] # with an empty branch: the top-level keys the last install declared under
37
+ end
38
+
39
+ def installed? = @installed
40
+
41
+ # Raise if two sources would declare in the same branch: one reloading would drop the other's components
42
+ def self.check_overlaps!(sources)
43
+ sources.combination(2) do |a, b|
44
+ raise ArgumentError, "#{a.inspect} overlaps #{b.inspect}: each reconfigures its whole branch" if a.overlaps?(b)
45
+ end
46
+ end
47
+
48
+ # The branch's full path from the root
49
+ def full_branch = [@owner.path, branch].compact.join('.')
50
+
51
+ def overlaps?(other)
52
+ return true if full_branch.empty? || other.full_branch.empty? # claims every top-level directory
53
+
54
+ mine = "#{full_branch}."
55
+ theirs = "#{other.full_branch}."
56
+ mine.start_with?(theirs) || theirs.start_with?(mine)
57
+ end
58
+
59
+ # The first time, on the root's #prepare!. Through #reconfigure, which on an open tree is plain
60
+ # declaration, but rolls back if a file raises: a retried #prepare! starts from a clean branch
61
+ def install!
62
+ reconfigure!
63
+ @installed = true
64
+ self
65
+ end
66
+
67
+ # After Zeitwerk sets up again (a reload): re-declare the branch from the new constants.
68
+ # Every file re-implements its components, so they're recycled, and the ones whose file or
69
+ # method is gone are removed. Runs inside Zeitwerk's on_setup, where raising would leave the
70
+ # loader half set up, so errors go to +on_error+ instead, which mustn't raise either. The tree is
71
+ # left as it was (see Component#reconfigure), and the error is also published as root.failed.
72
+ def reload!
73
+ return self unless @installed
74
+ return self if @owner.root.boot_status == :torn_down
75
+
76
+ reconfigure!
77
+ @error = nil
78
+ self
79
+ rescue StandardError, ScriptError => e
80
+ @error = e
81
+ @on_error.call(e)
82
+ self
83
+ end
84
+
85
+ def inspect = "#<#{self.class} #{@glob} => #{full_branch}>"
86
+
87
+ # Load every file first, so a file that doesn't load raises before anything is reconfigured, and
88
+ # the branches are known. With an empty branch, they're the top-level keys of the files that
89
+ # install, and those of the last install, so a directory that's gone is emptied. New ones are
90
+ # created by declaring into them.
91
+ # Files can inject components that other files declare, whichever loads first: those are
92
+ # resolved once every file is installed, and a missing one rolls the reconfiguration back.
93
+ private def reconfigure!
94
+ installs = nil
95
+ deferred = @owner.root.deferring_injections { installs = installables }
96
+ keys = if branch.empty?
97
+ claimed = installs.map { |key, _| key.split('.').first }.uniq
98
+ (@claimed | claimed).select { |k| @owner.declared?(k) }
99
+ else
100
+ [branch]
101
+ end
102
+
103
+ @owner.reconfigure(keys) do
104
+ installs.each { |key, mod| mod.public_send(INSTALL, Declarer.new(@owner, key)) }
105
+ deferred.each(&:resolve!)
106
+ end
107
+ @claimed = claimed if branch.empty?
108
+ end
109
+
110
+ # [[key, constant]] for each file whose constant responds to .__install_component
111
+ private def installables
112
+ files.filter_map do |path|
113
+ cpath = @loader.cpath_expected_at(path)
114
+ next unless cpath
115
+
116
+ mod = Object.const_get(cpath)
117
+ next unless mod.respond_to?(INSTALL)
118
+
119
+ key = key_for(path.delete_suffix('.rb'))
120
+ if branch.empty? && !key.include?('.')
121
+ raise ArgumentError, "#{path} can't install components at the top level, where reloading can't " \
122
+ "re-declare them: move it into a directory, or pass namespace: to #from_dir"
123
+ end
124
+
125
+ [key, mod]
126
+ end
127
+ end
128
+
129
+ private def files
130
+ Dir.glob(@glob).select { |path| path.end_with?('.rb') && File.file?(path) }.sort
131
+ end
132
+
133
+ # [absolute glob, the directory above its first wildcard]. A plain directory means its own .rb files
134
+ private def expand(glob)
135
+ abs = File.expand_path(glob)
136
+ segments = abs.split('/')
137
+ static = segments.take_while { |s| !GLOB_CHARS.match?(s) }
138
+ return [abs, static.join('/')] if static.size < segments.size
139
+ raise ArgumentError, "from_dir: #{abs} is not a directory" unless File.directory?(abs)
140
+
141
+ [File.join(abs, '*.rb'), abs]
142
+ end
143
+
144
+ private def key_for(path)
145
+ relative = if path == @root
146
+ ''
147
+ elsif path.start_with?("#{@root}/")
148
+ path.delete_prefix("#{@root}/")
149
+ else
150
+ raise ArgumentError, "from_dir: #{path} is not under root #{@root}"
151
+ end
152
+ [@namespace, *relative.split('/')].compact.reject(&:empty?).join('.')
153
+ end
154
+
155
+ # What .__install_component gets: the component's DSL, scoped to the file's key.
156
+ # Deps are relative to the component #from_dir was called on, like the keys of #inject.
157
+ # def self.__install_component(c) = c.declare(self).factory(self)
158
+ # def self.__install_component(c) # several, under the file's key
159
+ # c['logger'].declare(Logger) { Logger.new($stdout) }
160
+ # c['store'].declare(Store).config!([c['logger'].key]) { |logger| Store.new(logger) }
161
+ # end
162
+ class Declarer
163
+ # The key, relative to the component #from_dir was called on, ex. 'lib.queries.users.search'
164
+ attr_reader :key
165
+
166
+ def initialize(owner, key)
167
+ @owner = owner
168
+ @key = key
169
+ end
170
+
171
+ # A declarer for a key under this one
172
+ def [](ckey) = Declarer.new(@owner, "#{key}.#{ckey}")
173
+
174
+ def declare(type = T::Any, &default) = tap { @owner.declare(key, type, &default) }
175
+ def component!(...) = tap { @owner.component!(key, ...) }
176
+ def component(...) = tap { @owner.component(key, ...) }
177
+ def config!(...) = tap { @owner.config!(key, ...) }
178
+ def config(...) = tap { @owner.config(key, ...) }
179
+ def alias(target) = tap { @owner.alias(key, target) }
180
+ def factory(constructor) = tap { @owner.factory(key, constructor) }
181
+ def defer = tap { @owner.defer(key) }
182
+
183
+ def inspect = "#<#{self.class} #{key}>"
184
+ end
185
+ end
186
+ end
187
+ end
@@ -14,6 +14,8 @@ module Sourced
14
14
  NotBuiltError = Class.new(ComponentError)
15
15
  TornDownError = Class.new(ComponentError)
16
16
  NotStartedError = Class.new(ComponentError)
17
+ RemovedComponentError = Class.new(ComponentError)
17
18
  InjectionError = Class.new(ComponentError)
19
+ MissingLoaderError = Class.new(ComponentError)
18
20
  end
19
21
  end
@@ -49,7 +49,7 @@ module Sourced
49
49
 
50
50
  Completed = proc { attribute :duration, Float }
51
51
  Failed = proc do
52
- attribute :stage, Symbol # :prepare, :build, :start, :stop or :teardown
52
+ attribute :stage, Symbol # :prepare, :build, :start, :stop, :teardown, :recycle or :reconfigure
53
53
  attribute :error_class, String
54
54
  attribute :error_message, String
55
55
  attribute :backtrace, Plumb::Types::Array[String]
@@ -61,6 +61,10 @@ module Sourced
61
61
  RootBuilt = RootEvent.define('root.built', &Completed)
62
62
  RootStarting = RootEvent.define('root.starting')
63
63
  RootStarted = RootEvent.define('root.started', &Completed)
64
+ RootReconfiguring = RootEvent.define('root.reconfiguring')
65
+ RootReconfigured = RootEvent.define('root.reconfigured', &Completed)
66
+ RootRecycling = RootEvent.define('root.recycling')
67
+ RootRecycled = RootEvent.define('root.recycled', &Completed)
64
68
  RootTearingDown = RootEvent.define('root.tearing_down')
65
69
  RootTornDown = RootEvent.define('root.torn_down', &Completed)
66
70
  RootFailed = RootEvent.define('root.failed', &Failed)
@@ -77,6 +81,9 @@ module Sourced
77
81
  ComponentDeferred = ComponentEvent.define('components.deferred') do
78
82
  attribute :deferrer, Plumb::Types::String.nullable # the full path of the component that deferred it. nil for the root
79
83
  end
84
+ ComponentRemoved = ComponentEvent.define('components.removed') do
85
+ attribute :remover, Plumb::Types::String.nullable # the full path of the component that removed it. nil for the root
86
+ end
80
87
  ComponentPreparing = ComponentEvent.define('components.preparing')
81
88
  ComponentPrepared = ComponentEvent.define('components.prepared', &Completed)
82
89
  ComponentBuilding = ComponentEvent.define('components.building')
@@ -97,6 +104,8 @@ module Sourced
97
104
  prepare: [Events::RootPreparing, Events::RootPrepared],
98
105
  build: [Events::RootBuilding, Events::RootBuilt],
99
106
  start: [Events::RootStarting, Events::RootStarted],
107
+ reconfigure: [Events::RootReconfiguring, Events::RootReconfigured],
108
+ recycle: [Events::RootRecycling, Events::RootRecycled],
100
109
  teardown: [Events::RootTearingDown, Events::RootTornDown]
101
110
  }.freeze
102
111
 
@@ -11,16 +11,48 @@ module Sourced
11
11
  # Values are read from the nodes themselves, so a class injecting from a library's component
12
12
  # gets the overrides of the application that mounts it.
13
13
  class Injector < Module
14
- attr_reader :names
14
+ # A component injected before it was declared, while #from_dir loads files: the file declaring
15
+ # it may load later. Looked up on first use, and checked once every file is installed (#resolve!)
16
+ class DeferredNode
17
+ def initialize(component, key)
18
+ @component = component
19
+ @key = key
20
+ @node = nil
21
+ end
22
+
23
+ def resolve! = @node ||= @component.node(@key)
24
+ def read = resolve!.read
25
+ # Known before it's declared, so #factory can depend on it
26
+ def path = [@component.path, @key].compact.join('.')
27
+ end
15
28
 
16
- # nodes: { 'component.key' => <Component node> }
29
+ # Extended into whatever includes an Injector, see #included
30
+ module ComponentDeps
31
+ # Every component injected into this class, including inherited ones, by key.
32
+ # See Injector.deps_for
33
+ def __component_deps = Injector.deps_for(self)
34
+ end
35
+
36
+ # Every component injected into mod, as the key it's registered under (a path from the root of
37
+ # its tree) mapped to the name it's injected as, in injection order, with the ones injected
38
+ # into mod's ancestors first. Injecting a key again under another name replaces the name, so
39
+ # the one closest to mod wins.
40
+ # { 'logger' => :logger, 'repos.users' => :customers }
41
+ def self.deps_for(mod)
42
+ mod.ancestors.grep(Injector).reverse.reduce({}) { |deps, injector| deps.merge(injector.mapping) }
43
+ end
44
+
45
+ attr_reader :names, :nodes
46
+
47
+ # nodes: { 'component.key' => <Component node, or DeferredNode> }
17
48
  # names: { 'component.key' => :kwarg_name }
18
49
  def initialize(nodes, names)
19
50
  super()
20
51
  @names = names.freeze
52
+ @nodes = names.keys.map { |key| nodes.fetch(key) }.freeze
21
53
 
22
54
  # Instance variable names are computed once, not on every #new
23
- entries = names.map { |key, name| [nodes.fetch(key), name, :"@#{name}"] }.freeze
55
+ entries = @nodes.zip(names.values).map { |node, name| [node, name, :"@#{name}"] }.freeze
24
56
 
25
57
  initializer = Module.new do
26
58
  define_method(:initialize) do |*args, **kwargs, &block|
@@ -50,9 +82,20 @@ module Sourced
50
82
  define_singleton_method(:included) do |base|
51
83
  base.prepend(initializer)
52
84
  base.attr_reader(*names.values)
85
+ base.extend(ComponentDeps)
53
86
  end
54
87
  end
55
88
 
89
+ # The keys as passed to Component#inject, relative to the component they were injected from
90
+ def keys = names.keys
91
+
92
+ # The keys the injected components are registered under, as paths from the root of their tree.
93
+ # Computed on each call: a node's path changes when its root is mounted into another component.
94
+ def paths = nodes.map(&:path)
95
+
96
+ # Those keys, mapped to the names the components are injected as
97
+ def mapping = paths.zip(names.values).to_h
98
+
56
99
  def inspect = "#<#{self.class} #{names.map { |key, name| "#{key} => #{name}" }.join(', ')}>"
57
100
  end
58
101
  end
@@ -0,0 +1,32 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sourced
4
+ class Component
5
+ # The default .__install_component for a class in a #from_dir directory: declared as its own
6
+ # type and implemented with #factory, so the components it injects are its deps.
7
+ # class Queries::Users::Search
8
+ # include Sourced::Component::Installable
9
+ # include App.inject('db', 'logger')
10
+ # end
11
+ # A class defining its own .__install_component keeps it. Subclasses install as themselves, and
12
+ # a base class only there to be subclassed opts out, without opting out its subclasses:
13
+ # class Queries::Base
14
+ # include Sourced::Component::Installable
15
+ # __abstract_component!
16
+ # end
17
+ module Installable
18
+ def self.included(base) = base.extend(ClassMethods)
19
+
20
+ module ClassMethods
21
+ # Set on this class only: an instance variable of the class, which subclasses don't share
22
+ def __abstract_component! = @__abstract_component = true
23
+
24
+ def __install_component(c)
25
+ return if @__abstract_component
26
+
27
+ c.declare(self).factory(self)
28
+ end
29
+ end
30
+ end
31
+ end
32
+ end
@@ -0,0 +1,135 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Sourced
4
+ class Component
5
+ # A re-declaration of one or more branches of a booted tree, driven by Component#reconfigure: it records
6
+ # what the block declares, and snapshots what's needed to roll back if anything raises.
7
+ # Branch what the block declares through, see below
8
+ # #snapshot! everything the block or the validation can touch
9
+ # #declared! one per key the block declares, from Component#declare
10
+ # #implemented! one per key it re-implements, from Component#implement_node
11
+ # #retyped! one per surviving node whose type changed, from Component#declare
12
+ class Reconfiguration
13
+ # What a reconfiguration can change about one node: captured before its block runs, restored
14
+ # if anything raises. The members drive both the capture and the restore, so a new one can't
15
+ # be captured and then forgotten on the way back
16
+ NodeState = Data.define(
17
+ :implementation, :type, :implicit, :deps, :dep_nodes, :deferred, :held, :status, :value,
18
+ :recycle_to, :children, :index
19
+ )
20
+
21
+ # The tree as it was before the block: every node's state, and the root's order
22
+ Snapshot = Data.define(:order, :nodes)
23
+
24
+ # Declares into +branch+ on behalf of +owner+, the component #reconfigure was called on: keys
25
+ # are prefixed and passed on, so the owner declares them as it would itself. That's what makes
26
+ # nested keys work, since a branch node can't declare under namespaces the root created.
27
+ class Branch
28
+ def initialize(owner, prefix)
29
+ @owner = owner
30
+ @prefix = prefix
31
+ end
32
+
33
+ def declare(ckey, ...) = @owner.declare(key(ckey), ...)
34
+ def component!(ckey, ...) = @owner.component!(key(ckey), ...)
35
+ def component(ckey, ...) = @owner.component(key(ckey), ...)
36
+ def config!(ckey, ...) = @owner.config!(key(ckey), ...)
37
+ def config(ckey, ...) = @owner.config(key(ckey), ...)
38
+ def alias(ckey, ...) = @owner.alias(key(ckey), ...)
39
+ def defer(ckey) = @owner.defer(key(ckey))
40
+ def node(ckey) = @owner.node(key(ckey))
41
+ def declared?(ckey) = @owner.declared?(key(ckey))
42
+
43
+ def inspect = "#<#{self.class} #{@prefix}>"
44
+
45
+ private def key(ckey) = "#{@prefix}.#{ckey}"
46
+ end
47
+
48
+ # branches: the namespace nodes being re-declared. owner: the component #reconfigure was called on
49
+ def initialize(branches, owner)
50
+ @branches = branches
51
+ @owner = owner
52
+ @declared = Set.new # nodes the block declared, new and surviving
53
+ @changed = Set.new # nodes it re-implemented, or declared with another type
54
+ @before = Set.new # the nodes under the branches before the block
55
+ @snapshot = nil
56
+ end
57
+
58
+ def branch_handles = @branches.map { |b| Branch.new(@owner, b.path) }
59
+
60
+ def snapshot!
61
+ root = @owner.root
62
+ @before = @branches.flat_map { |b| b.index.values }.to_set
63
+ nodes = [root, *root.index.values]
64
+ @snapshot = Snapshot.new(order: root.order&.dup, nodes: nodes.to_h { |n| [n, n.capture_state] })
65
+ self
66
+ end
67
+
68
+ # Put it all back. Nothing has run any hooks yet, so this is all it takes
69
+ def rollback!
70
+ @snapshot.nodes.each { |n, state| n.restore_state!(state) }
71
+ @owner.root.restore_order!(@snapshot.order)
72
+ self
73
+ end
74
+
75
+ def declared!(node) = @declared << node
76
+ def changed!(node) = @changed << node
77
+
78
+ # Whether the tree didn't have this component before the block. Component#declare asks, to
79
+ # announce only those
80
+ def new?(node) = !@before.include?(node)
81
+
82
+ # The order before the block ran, to tear removed components down in reverse
83
+ def order_before = @snapshot.order || []
84
+
85
+ # What the block changed, plus every node whose resolved deps are no longer the same nodes
86
+ def affected
87
+ redeps = @snapshot.nodes.filter_map { |n, state| n unless state.dep_nodes == n.dep_nodes }
88
+ (@changed | created | redeps).reject { |n| n.removed? || n.namespace? }
89
+ end
90
+
91
+ # Components the tree didn't have: new nodes, and namespaces the block implemented
92
+ def newly_components
93
+ was_namespace = @snapshot.nodes.filter_map do |n, state|
94
+ n if state.implementation.nil? && !n.implementation.nil?
95
+ end
96
+ (created | was_namespace).reject(&:namespace?)
97
+ end
98
+
99
+ # Components the block declared that the tree didn't have before
100
+ def created = @declared - @before
101
+
102
+ # Dropped components that still have declared descendants, ex. one at 'billing' whose file
103
+ # became a 'billing/' directory. They revert to namespaces: removing them would orphan those
104
+ def reverting = dropped.fetch(:reverting)
105
+
106
+ # Everything to take out of the tree: dropped components with no declared descendants left,
107
+ # plus the namespaces that leaves empty, pruned bottom-up until stable (dropping
108
+ # 'billing.deep.x' can empty 'deep', which can empty 'billing')
109
+ def removing
110
+ gone = dropped.fetch(:removing).dup
111
+ loop do
112
+ empty = @before.select do |n|
113
+ n.namespace? && !gone.include?(n) && n.children.any? && (n.children.values - gone).empty?
114
+ end
115
+ break gone if empty.empty?
116
+
117
+ gone.concat(empty)
118
+ end
119
+ end
120
+
121
+ # The nodes the block didn't declare, split into the ones to take out of the tree and the ones
122
+ # that revert to namespaces. Computed once: the block has finished by the time anything asks
123
+ private def dropped
124
+ @dropped ||= begin
125
+ kept, gone = (@before - @declared).partition { |n| keeps_children?(n) }
126
+ { removing: gone, reverting: kept.reject(&:namespace?) }
127
+ end
128
+ end
129
+
130
+ private def keeps_children?(node)
131
+ node.index.values.any? { |d| @declared.include?(d) }
132
+ end
133
+ end
134
+ end
135
+ end
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Sourced
4
4
  class Component
5
- VERSION = "0.1.0"
5
+ VERSION = "0.1.2"
6
6
  end
7
7
  end