sourced-component 0.1.1 → 0.1.3

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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2896fb5ddac45462754f578010d435045bdaef50926865591b21bc49f68f8127
4
- data.tar.gz: 86e67b664260f455dd0c0d47d5ad7492d5164e408d4f580b00e17f4b46a2873e
3
+ metadata.gz: 1a892eb22b720a4e29fcf85ef1412a8c396912a0568288ae72509f2e0c3490ec
4
+ data.tar.gz: 4841c6f448f7fe1b23643cc838729ac590b347a401d7e47dbdbf546bc19b4120
5
5
  SHA512:
6
- metadata.gz: 6fd436c2496d183ee205625cffdd0f8714835083d5e081713dbf012f20412e7d04d454fbdb0cf689154158425d0ef4f268c5a4c0c0d741870a20ef6b11671850
7
- data.tar.gz: a2925c94cdc0fcfd6aafb5152ac051e9ed43680551e1e7891fb801c9e6b49e7d44597f7d269bda1950ac695a49c42f5e0dcca7e6cdac27874a25d95460957718
6
+ metadata.gz: '09758a5ee69e20c50803398b948df6907ced997dd1263e1a2d7aa435ce8c811fb75b6a65f7affc367ac39b62347f88b82a5265fc793f84d0b36b31a058fad3df'
7
+ data.tar.gz: cdcdaa73c163546c71474c83f1dbd9b3985adb19a2111904970fefba587b0388f2a1ff93845aef1afd409550ae44fa21110852750d9dc1be5098c928f9afe81b
data/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  ## [Unreleased]
2
2
 
3
+ - `#install_dirs!`: load the files of every `#from_dir` and declare their components on an open tree, before `#prepare!`, so classes loaded earlier (ex. by Zeitwerk's `#eager_load`) can inject them
4
+ - `#from_dir(glob)`: declare components from the files in a directory, with `.__install_component`, and reconfigure them when the tree's Zeitwerk loader reloads
5
+ - `Sourced::Component::Installable`: the default `.__install_component`, `c.declare(self).factory(self)`, and `.__abstract_component!` for base classes
6
+ - `#from_dir(glob, root: dir)`, rooted at the directory it scans: each top-level directory is a branch, reloaded together
7
+ - Files loaded by `#from_dir` can inject each other's components, in any order
8
+ - `#reconfigure([keys])` re-declares several branches at once, validated together
9
+ - `Sourced::Component.new(loader:)` and `#loader=`: the tree's code loader, for `#from_dir`. `MissingLoaderError` without one
3
10
  - `stop` lifecycle hook: runs when a started component is stopped, and before `teardown` when the root is torn down
4
11
  - `#defer(key)`: the root's `#start!` skips the component, and everything depending on it
5
12
  - `#start_component!`, `#stop_component!` and `#restart_component!` start and stop components by key, following the dependency graph
data/README.md CHANGED
@@ -439,6 +439,15 @@ end
439
439
  - **Components elsewhere in the tree are recycled if their dependencies changed**, which is how a `config('runner', ['reactors.*'])` picks up an added or removed reactor: its memoized value listed the old ones.
440
440
  - **Nothing runs any hooks until the whole new declaration set has been validated.** A block that raises, a missing dependency, a cycle, a declaration with no implementation, or dropping a component something still depends on: each leaves the tree exactly as it was, still running. A broken file save is the normal case in a dev loop, so recovering from it is the point.
441
441
  - **Components stopped by key stay stopped**, and deferred ones stay deferred. Re-declaring doesn't start anything that wasn't running.
442
+ - **Several branches at once:** given an Array of keys, `#reconfigure` re-declares them together, and the block gets a handle per branch. They're validated as one set, so a component can move from one branch to another, along with whatever depends on it, which one branch at a time couldn't do without dropping a component that's still depended on.
443
+
444
+ ```ruby
445
+ App.reconfigure(%w[users accounts]) do |users, accounts|
446
+ users.declare('register')
447
+ accounts.declare('open')
448
+ end
449
+ ```
450
+
442
451
  - **Keys are relative to the branch**, and the block declares through the component `#reconfigure` was called on, so ownership comes out exactly as plain declaration would. The branch must be a namespace, and the tree is locked for anything outside the block as usual.
443
452
  - **Removed components are `:removed`**, which is terminal. They're gone from `#index`, `#tree` and `#graph`, so reading them by key raises `UndeclaredComponentError` — and anything still holding the node itself, ex. a class that injected it, raises `RemovedComponentError` rather than reading a dead value.
444
453
  - **Nested keys work the same**, since dotted keys build the tree. A namespace left with nothing under it is removed too, pruned bottom-up: dropping `billing.deep.x` leaves neither `deep` nor `billing` behind.
@@ -456,6 +465,96 @@ App.reconfigure('reactors') do |reactors|
456
465
  end
457
466
  ```
458
467
 
468
+ ### Components from a directory
469
+
470
+ `#from_dir(glob, root: Dir.pwd, namespace: nil, on_error:)` declares components from the Ruby files matching a glob, autoloaded by a [Zeitwerk](https://github.com/fxn/zeitwerk) loader, and re-declares them when the loader reloads.
471
+
472
+ The loader is configuration for the whole tree, set on the root, either when it's created or later, while it's open:
473
+
474
+ ```ruby
475
+ App = Sourced::Component.new(loader:) # or App.loader = loader
476
+
477
+ App.from_dir('lib/**/*.rb')
478
+ ```
479
+
480
+ - **It's optional**, and only `#from_dir` needs it: calling it on a tree without a loader raises `MissingLoaderError`. Zeitwerk isn't a dependency of this gem: bring your own loader (2.6.13+), or anything with `#cpath_expected_at(path)` and `#on_setup(&block)`.
481
+ - **Mounted components use their root's loader**, so a library's component can call `#from_dir` once it's mounted. Setting it on a mounted component, or mounting a component that has its own, raises `SubcomponentError`.
482
+ - **It can't be replaced** once `#from_dir` registered with it (`ArgumentError`), or once the tree is prepared (`LockedComponentError`).
483
+
484
+ Each file's key is its path relative to `root`, prefixed with `namespace`. The constant Zeitwerk expects in the file declares its components with `.__install_component`, which gets the component DSL scoped to that key:
485
+
486
+ ```ruby
487
+ # lib/queries/users/search.rb => 'lib.queries.users.search'
488
+ class Queries::Users::Search
489
+ include App.inject('db', 'logger')
490
+
491
+ def self.__install_component(c) = c.declare(self).factory(self)
492
+ end
493
+ ```
494
+
495
+ That's the usual case, a class declared as its own type and built with [`#factory`](#factory), so the components it injects are its dependencies. `Sourced::Component::Installable` defines it:
496
+
497
+ ```ruby
498
+ class Queries::Users::Search
499
+ include Sourced::Component::Installable
500
+ include App.inject('db', 'logger')
501
+ end
502
+ ```
503
+
504
+ A class defining its own `.__install_component` keeps it, and subclasses install as themselves. A base class that's only there to be subclassed opts out with `__abstract_component!`, which its subclasses don't inherit:
505
+
506
+ ```ruby
507
+ class Queries::Base
508
+ include Sourced::Component::Installable
509
+ include App.inject('db')
510
+ __abstract_component!
511
+ end
512
+
513
+ class Queries::Users::Search < Queries::Base; end # 'lib.queries.users.search'
514
+ ```
515
+
516
+ `c['name']` scopes it to a key under the file's, so a file can declare several components:
517
+
518
+ ```ruby
519
+ # lib/integrations/sourced.rb => 'lib.integrations.sourced.logger', 'lib.integrations.sourced.store'
520
+ module Integrations::Sourced
521
+ def self.__install_component(c)
522
+ c['logger'].declare(Logger) { Logger.new($stdout) }
523
+ c['store'].declare(Store).config!([c['logger'].key, 'db']) { |logger, db| Store.new(logger, db) }
524
+ end
525
+ end
526
+ ```
527
+
528
+ - **The declarer** has `declare(type = Any, &default)`, `component!`, `component`, `config!`, `config`, `alias`, `factory` and `defer`, which take the same arguments as the component's, without the key, and return the declarer. `#key` is its key.
529
+ - **Dependencies are relative to the component `#from_dir` was called on**, like the keys of `#inject`, so siblings are referenced by their full key (`c['logger'].key`).
530
+ - **Constants that don't respond to `.__install_component` are skipped**, and so are files the loader ignores.
531
+ - **Files are loaded on the root's `#prepare!`**, not by `#from_dir`, so the components they inject are declared by then. The loader must be set up before that. If a file raises, none of the directory's components are left declared, so booting again after fixing it works.
532
+ - **`#install_dirs!` loads them earlier**, on the open tree, for an app that loads classes injecting them before it prepares the tree, ex. with Zeitwerk's `#eager_load`. The tree stays open, and `#prepare!` skips the sources already installed. It's for the root, and raises `LockedComponentError` once the tree is prepared:
533
+
534
+ ```ruby
535
+ App.from_dir('system/**/*.rb', root: 'system')
536
+ loader.setup
537
+ App.install_dirs! # declares 'users.create', from system/users/create.rb
538
+ loader.eager_load # so a class elsewhere can inject 'users.create' as it loads
539
+ ```
540
+ - **Files can inject each other's components**, whichever loads first. While `#from_dir` loads files, injecting a key that isn't declared yet is resolved once every file has declared its components, and one that's still missing raises `UndeclaredComponentError` (on a reload, rolling it back). Everywhere else, injecting an undeclared key raises straight away.
541
+ - **Keys:** `App.from_dir('app/queries/**/*.rb', root: 'app/queries', namespace: 'queries')` keys `app/queries/users/search.rb` as `queries.users.search`. A glob without wildcards is a directory's own `.rb` files.
542
+ - **A whole directory, without its name:** with `root:` set to the directory scanned and no `namespace:`, each top-level directory is a branch of its own:
543
+
544
+ ```ruby
545
+ App.from_dir('system/**/*.rb', root: 'system')
546
+ # system/users/create.rb => 'users.create'
547
+ # system/queries/search.rb => 'queries.search'
548
+ ```
549
+
550
+ The branches are the top-level directories with files that install components, and reloads re-declare all of them at once, so directories can be added and removed. Top-level directories whose files install nothing are left alone, along with anything else declared under them. A file directly in `system/` that installs components raises `ArgumentError`: a component at the root of the tree can't be re-declared by a reload.
551
+ - **On reload**, the branch above the glob's first wildcard (`lib` above), or each top-level directory's, is [reconfigured](#re-configuring-a-booted-tree) from the reloaded constants: every component the files declare is recycled with its new class, along with its dependents, components whose file is gone are removed, and new ones are added. A wildcard dependency on the branch (`'lib.queries.users.*'`) picks the changes up.
552
+ - **A failed reload leaves the tree as it was**, still running, and is published as `root.failed`. It's not raised: it happens inside Zeitwerk's `on_setup`, and raising there would leave the loader unable to reload again. It's passed to `on_error` instead (by default, a warning), which mustn't raise either, and the next reload retries.
553
+ - **Branches can't overlap:** each `#from_dir` reconfigures its whole branch, so two whose branches nest raise `ArgumentError`, wherever in the tree they were registered. One rooted at the directory it scans overlaps any other. The branch must be a namespace with no mounted components, like any reconfigured branch.
554
+ - **`#from_dir` is for open trees**, and raises `LockedComponentError` once the tree is prepared, including inside a `#reconfigure` block.
555
+ - **The loader keeps each tree's reload hook**, since Zeitwerk can't remove `on_setup` callbacks. After teardown it does nothing, but a long-lived loader shared by many trees, ex. in tests, keeps them all in memory: give each tree its own loader.
556
+ - **Classes outside the directory aren't re-declared.** A component elsewhere that captured a reloaded class in a provider keeps the old one: see [recycling](#recycling-components).
557
+
459
558
  ### Signal handlers
460
559
 
461
560
  The lifecycle methods, and anything else that takes the root's lock (declaring, implementing and mounting components, `#recycle_component!` and friends, `#reconfigure`, `#graph`, `#tree`), can't be called from a `trap` block: Ruby doesn't allow locking a `Monitor` in trap context, so they raise `ThreadError: can't be called from trap context` and nothing is torn down. Reading values doesn't take the lock.
@@ -0,0 +1,86 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Run with: bundle exec ruby examples/from_dir/app.rb
4
+ # Or explore it in irb, booted, without the demo: bundle exec irb -r ./examples/from_dir/app.rb
5
+ #
6
+ # Declares components from the files in lib/, autoloaded by Zeitwerk, then edits a file and
7
+ # reloads, as a dev-mode file watcher would. The reload edits a copy of lib/ in a temp dir,
8
+ # so running the example leaves this one untouched.
9
+
10
+ require 'bundler/setup'
11
+ require 'sourced/component'
12
+ require 'zeitwerk'
13
+ require 'logger'
14
+ require 'tmpdir'
15
+ require 'fileutils'
16
+
17
+ T = Sourced::Component::T
18
+ $stdout.sync = true # keep output in order with the reload warning, on stderr
19
+
20
+ dir = Dir.mktmpdir
21
+ at_exit { FileUtils.rm_rf(dir) }
22
+ FileUtils.cp_r(File.join(__dir__, 'lib'), dir)
23
+ lib = File.join(dir, 'lib')
24
+
25
+ loader = Zeitwerk::Loader.new
26
+ loader.push_dir(lib)
27
+ loader.enable_reloading
28
+
29
+ # The loader is configuration for the whole tree
30
+ App = Sourced::Component.new(loader:)
31
+
32
+ App.declare('logger', Logger) { Logger.new($stdout, formatter: ->(_, _, _, msg) { " [log] #{msg}\n" }) }
33
+ App.declare('db', T::Array) { [{ id: 1, name: 'Joe' }, { id: 2, name: 'Joan' }, { id: 3, name: 'Ann' }] }
34
+
35
+ # Every file under lib/, keyed by its path relative to root:
36
+ # lib/queries/users/search.rb => 'lib.queries.users.search'
37
+ # Files are loaded on #prepare!, so 'db' and 'logger' only need to be declared before booting.
38
+ # On reload, the 'lib' branch is reconfigured from the reloaded constants.
39
+ App.from_dir(File.join(lib, '**/*.rb'), root: dir)
40
+ # Or root: lib, for 'queries.users.search': each top-level directory is then a branch of its own
41
+
42
+ # Collects every user query, whichever files declare them
43
+ App.declare('user_queries', T::Hash)
44
+ App.config!('user_queries', ['lib.queries.users.*']) { |queries| queries }
45
+
46
+ LOADER = loader
47
+ LIB = lib # the temp copy of lib/: edit files here, then LOADER.reload
48
+
49
+ loader.setup
50
+ App.start!
51
+
52
+ return unless __FILE__ == $PROGRAM_NAME
53
+
54
+ puts App.tree
55
+ puts
56
+
57
+ puts 'Search "Jo":'
58
+ App['lib.queries.users.search'].call('Jo').each { |user| puts " #{Support::Formatter.user(user)}" }
59
+ puts 'Find 3:'
60
+ puts " #{Support::Formatter.user(App['lib.queries.users.find'].call(3))}"
61
+ App['lib.integrations.mailer.client'].deliver('joe@example.com', :welcome)
62
+ puts "User queries: #{App['user_queries'].keys}"
63
+ puts
64
+
65
+ puts 'Adding lib/queries/users/count.rb, removing find.rb, and reloading...'
66
+ File.write(File.join(lib, 'queries/users/count.rb'), <<~RUBY)
67
+ class Queries::Users::Count
68
+ include Sourced::Component::Installable
69
+ include App.inject('db')
70
+ def call = db.size
71
+ end
72
+ RUBY
73
+ File.delete(File.join(lib, 'queries/users/find.rb'))
74
+ loader.reload
75
+
76
+ puts "User queries: #{App['user_queries'].keys}"
77
+ puts "Count: #{App['lib.queries.users.count'].call}"
78
+ puts "Find declared? #{App.declared?('lib.queries.users.find')}"
79
+ puts
80
+
81
+ puts 'Breaking search.rb and reloading: the tree keeps running as it was'
82
+ File.write(File.join(lib, 'queries/users/search.rb'), "class Queries::Users::Search\n def oops(\nend\n")
83
+ loader.reload
84
+ puts "Search still works: #{App['lib.queries.users.search'].call('Ann').size} result"
85
+
86
+ App.teardown!
@@ -0,0 +1,16 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Several components under 'lib.integrations.mailer': '.templates' and '.client'.
4
+ # Deps are relative to App, so the client refers to its sibling by its full key.
5
+ module Integrations::Mailer
6
+ Client = Data.define(:templates, :logger) do
7
+ def deliver(to, template) = logger.info("mail #{to}: #{templates.fetch(template)}")
8
+ end
9
+
10
+ def self.__install_component(c)
11
+ c['templates'].declare(Sourced::Component::T::Hash) { { welcome: 'Welcome aboard!' } }
12
+ c['client'].declare(Client).config!([c['templates'].key, 'logger']) do |templates, logger|
13
+ Client.new(templates:, logger:)
14
+ end
15
+ end
16
+ end
@@ -0,0 +1,9 @@
1
+ # frozen_string_literal: true
2
+
3
+ # One component, at 'lib.queries.users.find'
4
+ class Queries::Users::Find
5
+ include Sourced::Component::Installable
6
+ include App.inject('db')
7
+
8
+ def call(id) = db.find { |user| user[:id] == id }
9
+ end
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ # One component, at 'lib.queries.users.search': a new Search on every read, with its injected deps.
4
+ # Installable declares it as c.declare(self).factory(self)
5
+ class Queries::Users::Search
6
+ include Sourced::Component::Installable
7
+ include App.inject('db', 'logger')
8
+
9
+ def call(term)
10
+ logger.info("search #{term.inspect}")
11
+ db.select { |user| user[:name].include?(term) }
12
+ end
13
+ end
@@ -0,0 +1,6 @@
1
+ # frozen_string_literal: true
2
+
3
+ # No .__install_component: autoloaded as usual, but not a component
4
+ module Support::Formatter
5
+ def self.user(user) = "##{user[:id]} #{user[:name]}"
6
+ end
@@ -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
@@ -16,5 +16,6 @@ module Sourced
16
16
  NotStartedError = Class.new(ComponentError)
17
17
  RemovedComponentError = Class.new(ComponentError)
18
18
  InjectionError = Class.new(ComponentError)
19
+ MissingLoaderError = Class.new(ComponentError)
19
20
  end
20
21
  end
@@ -11,6 +11,21 @@ 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
+ # 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
28
+
14
29
  # Extended into whatever includes an Injector, see #included
15
30
  module ComponentDeps
16
31
  # Every component injected into this class, including inherited ones, by key.
@@ -29,7 +44,7 @@ module Sourced
29
44
 
30
45
  attr_reader :names, :nodes
31
46
 
32
- # nodes: { 'component.key' => <Component node> }
47
+ # nodes: { 'component.key' => <Component node, or DeferredNode> }
33
48
  # names: { 'component.key' => :kwarg_name }
34
49
  def initialize(nodes, names)
35
50
  super()
@@ -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
@@ -2,7 +2,7 @@
2
2
 
3
3
  module Sourced
4
4
  class Component
5
- # A re-declaration of one branch of a booted tree, driven by Component#reconfigure: it records
5
+ # A re-declaration of one or more branches of a booted tree, driven by Component#reconfigure: it records
6
6
  # what the block declares, and snapshots what's needed to roll back if anything raises.
7
7
  # Branch what the block declares through, see below
8
8
  # #snapshot! everything the block or the validation can touch
@@ -45,21 +45,21 @@ module Sourced
45
45
  private def key(ckey) = "#{@prefix}.#{ckey}"
46
46
  end
47
47
 
48
- # branch: the namespace node being re-declared. owner: the component #reconfigure was called on
49
- def initialize(branch, owner)
50
- @branch = branch
48
+ # branches: the namespace nodes being re-declared. owner: the component #reconfigure was called on
49
+ def initialize(branches, owner)
50
+ @branches = branches
51
51
  @owner = owner
52
52
  @declared = Set.new # nodes the block declared, new and surviving
53
53
  @changed = Set.new # nodes it re-implemented, or declared with another type
54
- @before = Set.new # the nodes under the branch before the block
54
+ @before = Set.new # the nodes under the branches before the block
55
55
  @snapshot = nil
56
56
  end
57
57
 
58
- def branch_handle = Branch.new(@owner, @branch.path)
58
+ def branch_handles = @branches.map { |b| Branch.new(@owner, b.path) }
59
59
 
60
60
  def snapshot!
61
- root = @branch.root
62
- @before = @branch.index.values.to_set
61
+ root = @owner.root
62
+ @before = @branches.flat_map { |b| b.index.values }.to_set
63
63
  nodes = [root, *root.index.values]
64
64
  @snapshot = Snapshot.new(order: root.order&.dup, nodes: nodes.to_h { |n| [n, n.capture_state] })
65
65
  self
@@ -68,7 +68,7 @@ module Sourced
68
68
  # Put it all back. Nothing has run any hooks yet, so this is all it takes
69
69
  def rollback!
70
70
  @snapshot.nodes.each { |n, state| n.restore_state!(state) }
71
- @branch.root.restore_order!(@snapshot.order)
71
+ @owner.root.restore_order!(@snapshot.order)
72
72
  self
73
73
  end
74
74
 
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Sourced
4
4
  class Component
5
- VERSION = "0.1.1"
5
+ VERSION = "0.1.3"
6
6
  end
7
7
  end
@@ -16,6 +16,8 @@ require_relative 'component/events'
16
16
  require_relative 'component/notifier'
17
17
  require_relative 'component/tree'
18
18
  require_relative 'component/reconfiguration'
19
+ require_relative 'component/dir_source'
20
+ require_relative 'component/installable'
19
21
 
20
22
  module Sourced
21
23
  # A tree of components. Every node is a Component: it can declare a type, be implemented with
@@ -40,6 +42,9 @@ module Sourced
40
42
  # What #mount takes: anything that returns a Component from #to_component
41
43
  MountableInterface = Plumb::Types::Interface[:to_component]
42
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
+
43
48
  # key: local segment, ex. 'db'. nil for a root that isn't mounted anywhere
44
49
  # owner: the component that declared this node. Standalone components own themselves
45
50
  # type: the declared type. Any for implicit nodes created as intermediate segments (namespaces)
@@ -48,8 +53,9 @@ module Sourced
48
53
 
49
54
  # notifier: receives lifecycle events. See Component::Notifier and Component::Events.
50
55
  # The root's notifier receives the events of the whole tree, so a mounted component uses its root's.
51
- def initialize(owner: nil, type: Plumb::Undefined, notifier: Notifier.new)
56
+ def initialize(owner: nil, type: Plumb::Undefined, notifier: Notifier.new, loader: nil)
52
57
  @notifier = NotifierInterface.parse(notifier)
58
+ @loader = loader && LoaderInterface.parse(loader)
53
59
  @key = nil
54
60
  @parent = nil
55
61
  @owner = owner || self
@@ -72,6 +78,8 @@ module Sourced
72
78
  @starting = false
73
79
  @order = nil
74
80
  @lock = Monitor.new
81
+ @dir_sources = [] # see #from_dir
82
+ @deferred_injections = nil # see #deferring_injections, on the root only
75
83
  end
76
84
 
77
85
  def root = parent ? parent.root : self
@@ -80,6 +88,21 @@ module Sourced
80
88
  # The notifier lifecycle events are published to: the root's, for every component in the tree
81
89
  def notifier = root? ? @notifier : root.notifier
82
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
+
83
106
  # Full key from the root, ex. 'sourced.db'. nil for the root
84
107
  def path
85
108
  return nil unless parent
@@ -103,6 +126,20 @@ module Sourced
103
126
 
104
127
  # The Reconfiguration in progress, which records what its block declares
105
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
106
143
 
107
144
  def inspect
108
145
  details = namespace? ? '(namespace)' : "#{type_name} (#{[implementation&.mode || 'not implemented', status, ('deferred' if deferred?)].compact.join(', ')})"
@@ -293,7 +330,29 @@ module Sourced
293
330
  duplicates = names.values.tally.select { |_, count| count > 1 }.keys
294
331
  raise ArgumentError, "duplicate injected names: #{duplicates.join(', ')}" if duplicates.any?
295
332
 
296
- 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 }
297
356
  end
298
357
 
299
358
  # Attach an existing standalone component as a branch. It keeps owning its declarations,
@@ -314,6 +373,9 @@ module Sourced
314
373
  raise SubcomponentError, "#{sub.inspect} is already mounted in another component" unless sub.root?
315
374
  raise SubcomponentError, "can't mount a component into its own tree" if sub.equal?(root)
316
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
317
379
 
318
380
  branch, leaf = walk(ckey)
319
381
  if (existing = branch.children[leaf])
@@ -328,6 +390,59 @@ module Sourced
328
390
  # The mountable interface (see #mount)
329
391
  def to_component = self
330
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
+ # or earlier with #install_dirs!.
402
+ # When the loader reloads, the branch above the glob's first wildcard is reconfigured from the new
403
+ # constants (see #reconfigure). A failed reload leaves the tree as it was and calls +on_error+.
404
+ def from_dir(glob, root: Dir.pwd, namespace: nil, on_error: DirSource::DEFAULT_ON_ERROR)
405
+ source = synchronize do
406
+ # Not even while reconfiguring: sources are only installed on #prepare!
407
+ raise LockedComponentError, "can't add #{glob} to a locked component" if locked?
408
+
409
+ loader = self.loader
410
+ unless loader
411
+ raise MissingLoaderError,
412
+ "from_dir #{glob}: the tree has no code loader. Set one on the root, " \
413
+ "ex. Sourced::Component.new(loader: Zeitwerk::Loader.new) or root.loader = loader"
414
+ end
415
+
416
+ source = DirSource.new(self, glob, loader:, root:, namespace:, on_error:)
417
+ DirSource.check_overlaps!([*self.root.all_dir_sources, source]) # self.root: root is the keyword here
418
+ @dir_sources << source
419
+ source
420
+ end
421
+ # Outside the tree's lock: Zeitwerk calls back under its own lock, and the callback takes the tree's
422
+ loader.on_setup { source.reload! }
423
+ self
424
+ end
425
+
426
+ # Load the files of every #from_dir in the tree now, on an open tree, rather than on #prepare!,
427
+ # and declare their components. The tree stays open, so more can still be declared and
428
+ # implemented, and #prepare! skips the sources already installed. For an app that loads classes
429
+ # injecting those components before it prepares the tree, ex. with Zeitwerk's #eager_load:
430
+ # app.from_dir('system/**/*.rb', root: 'system')
431
+ # loader.setup
432
+ # app.install_dirs! # declares 'users.create', from system/users/create.rb
433
+ # loader.eager_load # so web/ classes can inject it
434
+ # The loader must be set up. If a file raises, none of the directory's components are left
435
+ # declared, and calling it again (or #prepare!) retries.
436
+ def install_dirs!
437
+ raise_mounted!
438
+ synchronize do
439
+ raise LockedComponentError, "can't install directories into a locked component" if locked?
440
+
441
+ [self, *index.values].each { |n| n.install_dir_sources! }
442
+ end
443
+ self
444
+ end
445
+
331
446
  # A node under this component, by relative key
332
447
  def node(ckey)
333
448
  index.fetch(ckey.to_s) { raise UndeclaredComponentError, "#{ckey} is not declared in #{path || 'this component'}" }
@@ -356,6 +471,7 @@ module Sourced
356
471
  return self if past?(:prepared)
357
472
 
358
473
  instrument_root(:prepare) do
474
+ [self, *index.values].each { |n| n.install_dir_sources! }
359
475
  @order = resolve_order
360
476
  # Holds start from the declarations, on a first boot only: #reresolve! must leave the ones
361
477
  # #stop_component! set alone, or a reconfiguration would start a stopped component again
@@ -567,19 +683,23 @@ module Sourced
567
683
  # files.each { |f| reactors.declare(f.key) }
568
684
  # changed.each { |f| reactors.component!(f.key, f.deps, &f.implementation) }
569
685
  # end
686
+ # Several branches are re-declared at once, and validated together, given an Array of keys.
687
+ # The block gets a handle per branch:
688
+ # app.reconfigure(%w[users accounts]) { |users, accounts| }
570
689
  def reconfigure(ckey, context = Thread.current, &block)
571
690
  raise ArgumentError, "reconfigure #{ckey}: a block must declare the branch's contents" unless block
572
691
 
573
692
  synchronize do
574
- branch = reconfigurable_branch(ckey)
575
- reconf = Reconfiguration.new(branch, self)
693
+ check_reconfigurable!
694
+ branches = Array(ckey).map { |k| reconfigurable_branch(k) }
695
+ reconf = Reconfiguration.new(branches, self)
576
696
  root.reconfiguring!(reconf)
577
697
 
578
698
  begin
579
699
  instrument_root(:reconfigure) do
580
700
  reconf.snapshot!
581
701
  plan = begin
582
- block.call(reconf.branch_handle)
702
+ block.call(*reconf.branch_handles)
583
703
  validate_reconfiguration!(reconf)
584
704
  rescue Exception # rubocop:disable Lint/RescueException -- nothing has run yet: put the tree back, whatever it was. Always re-raised
585
705
  reconf.rollback!
@@ -1040,13 +1160,14 @@ module Sourced
1040
1160
  end
1041
1161
 
1042
1162
  # A branch to reconfigure: a namespace, under a tree that isn't booting or torn down
1163
+ private def check_reconfigurable!
1164
+ raise LockedComponentError, "can't reconfigure: a reconfiguration is already running" if root.reconfiguring?
1165
+ raise TornDownError, "can't reconfigure: the component is torn down" if root.boot_status == :torn_down
1166
+ raise LockedComponentError, "can't reconfigure while the root is booting" if root.starting?
1167
+ end
1168
+
1043
1169
  private def reconfigurable_branch(ckey)
1044
1170
  branch = node(ckey)
1045
- raise LockedComponentError, "can't reconfigure #{branch.path}: a reconfiguration is already running" if root.reconfiguring?
1046
- raise TornDownError, "can't reconfigure #{branch.path}: the component is torn down" if root.boot_status == :torn_down
1047
- if root.starting?
1048
- raise LockedComponentError, "can't reconfigure #{branch.path} while the root is booting"
1049
- end
1050
1171
  unless branch.namespace?
1051
1172
  raise UndeclaredComponentError, "#{branch.path} is a component, not a namespace: reconfigure the branch above it"
1052
1173
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: sourced-component
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.1
4
+ version: 0.1.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Ismael Celis
@@ -64,8 +64,14 @@ files:
64
64
  - README.md
65
65
  - Rakefile
66
66
  - examples/env.rb
67
+ - examples/from_dir/app.rb
68
+ - examples/from_dir/lib/integrations/mailer.rb
69
+ - examples/from_dir/lib/queries/users/find.rb
70
+ - examples/from_dir/lib/queries/users/search.rb
71
+ - examples/from_dir/lib/support/formatter.rb
67
72
  - examples/tree.rb
68
73
  - lib/sourced/component.rb
74
+ - lib/sourced/component/dir_source.rb
69
75
  - lib/sourced/component/dsl.rb
70
76
  - lib/sourced/component/env_provider.rb
71
77
  - lib/sourced/component/errors.rb
@@ -73,6 +79,7 @@ files:
73
79
  - lib/sourced/component/graph.rb
74
80
  - lib/sourced/component/implementation.rb
75
81
  - lib/sourced/component/injector.rb
82
+ - lib/sourced/component/installable.rb
76
83
  - lib/sourced/component/mermaid.rb
77
84
  - lib/sourced/component/notifier.rb
78
85
  - lib/sourced/component/reconfiguration.rb
@@ -95,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
95
102
  - !ruby/object:Gem::Version
96
103
  version: '0'
97
104
  requirements: []
98
- rubygems_version: 4.0.21
105
+ rubygems_version: 4.0.10
99
106
  specification_version: 4
100
107
  summary: A tree of nested, typed components with dependencies and a managed lifecycle.
101
108
  test_files: []