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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +14 -0
- data/README.md +245 -6
- data/examples/from_dir/app.rb +86 -0
- data/examples/from_dir/lib/integrations/mailer.rb +16 -0
- data/examples/from_dir/lib/queries/users/find.rb +9 -0
- data/examples/from_dir/lib/queries/users/search.rb +13 -0
- data/examples/from_dir/lib/support/formatter.rb +6 -0
- data/lib/sourced/component/dir_source.rb +187 -0
- data/lib/sourced/component/errors.rb +2 -0
- data/lib/sourced/component/events.rb +10 -1
- data/lib/sourced/component/injector.rb +46 -3
- data/lib/sourced/component/installable.rb +32 -0
- data/lib/sourced/component/reconfiguration.rb +135 -0
- data/lib/sourced/component/version.rb +1 -1
- data/lib/sourced/component.rb +503 -25
- metadata +10 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: db15a3e8df75b3fd1e30d607d77d4a5812463f673c4530472ca32ad1b7bc66fc
|
|
4
|
+
data.tar.gz: bde0065b4858b3a91898c2016068c1a1bec1d0d7cebc420f851cd51acce5269d
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 2268205f4ba2c92d53554e2b5a2b0d526d6c81df75cd193121a72bcf5ad921a7f4033baba1e5e5ba3bce8c2db133614a4e79742df4d35394974f1ba29bc7c69b
|
|
7
|
+
data.tar.gz: bcd9972a3addfde922ad082991771357f96c6ac044f280c79c31255cbda1b0cea38ac2392454f91f39311edb697b49d292761d34401b9802da9690d5323e8484
|
data/CHANGELOG.md
CHANGED
|
@@ -1,10 +1,24 @@
|
|
|
1
1
|
## [Unreleased]
|
|
2
2
|
|
|
3
|
+
- `#from_dir(glob)`: declare components from the files in a directory, with `.__install_component`, and reconfigure them when the tree's Zeitwerk loader reloads
|
|
4
|
+
- `Sourced::Component::Installable`: the default `.__install_component`, `c.declare(self).factory(self)`, and `.__abstract_component!` for base classes
|
|
5
|
+
- `#from_dir(glob, root: dir)`, rooted at the directory it scans: each top-level directory is a branch, reloaded together
|
|
6
|
+
- Files loaded by `#from_dir` can inject each other's components, in any order
|
|
7
|
+
- `#reconfigure([keys])` re-declares several branches at once, validated together
|
|
8
|
+
- `Sourced::Component.new(loader:)` and `#loader=`: the tree's code loader, for `#from_dir`. `MissingLoaderError` without one
|
|
3
9
|
- `stop` lifecycle hook: runs when a started component is stopped, and before `teardown` when the root is torn down
|
|
4
10
|
- `#defer(key)`: the root's `#start!` skips the component, and everything depending on it
|
|
5
11
|
- `#start_component!`, `#stop_component!` and `#restart_component!` start and stop components by key, following the dependency graph
|
|
6
12
|
- `components.deferred`, `components.stopping` and `components.stopped` events, and `NotStartedError`
|
|
7
13
|
- `#tree` and `#graph` show deferred and stopped components
|
|
14
|
+
- `.__component_deps` on classes including an injector: every component injected into them, including inherited ones, as the key it's registered under mapped to the name it's injected as
|
|
15
|
+
- `#factory(key, constructor)` implements a declared component from a class that injects, taking its dependencies and its constructor's keyword arguments from `.__component_deps`
|
|
16
|
+
- `#recycle_component!`, `#recycle_components!` and `#recycle!` run a component's whole lifecycle again, leaving every affected component in the status it was in. A recycle that raises can be retried: components remember the status to restore until one completes
|
|
17
|
+
- `root.recycling` and `root.recycled` events
|
|
18
|
+
- `#reconfigure(key) { |branch| ... }` re-declares one branch of a booted tree from scratch: what the block doesn't declare is removed, unchanged components keep running, and the new declaration set is validated before anything is torn down, so a failure leaves the tree as it was
|
|
19
|
+
- `root.reconfiguring`, `root.reconfigured` and `components.removed` events, and `RemovedComponentError`
|
|
20
|
+
- Document forking after `#prepare!`, with `#build!` and `#start!` in each child
|
|
21
|
+
- Fix: `#teardown!` left the rest of the tree running, and the root `:started`, when a hook raised something that wasn't a `StandardError` (ex. the `Interrupt` a signal handler raises). Every component is now torn down exactly once, and a component whose hooks already ran is never torn down again
|
|
8
22
|
|
|
9
23
|
## [0.1.0] - 2026-10-04
|
|
10
24
|
|
data/README.md
CHANGED
|
@@ -141,6 +141,8 @@ App.component!('with.deps', ['sourced.db']) { build { |db| Foo.new(db) } }
|
|
|
141
141
|
App.component('now') { build { Time.now } }
|
|
142
142
|
```
|
|
143
143
|
|
|
144
|
+
A class that injects its own dependencies can be implemented from them, without repeating the list: see [`#factory`](#factory).
|
|
145
|
+
|
|
144
146
|
### Aliases
|
|
145
147
|
|
|
146
148
|
`#alias(key, target)` implements a declared node as an alias of another component: reading it reads the target. It's useful to wire one library's component to another's:
|
|
@@ -382,9 +384,172 @@ App.start_component!('dispatcher') # starts dispatcher, then monitor
|
|
|
382
384
|
- **If `stop` hooks raise,** every component is still stopped, and the first error is re-raised.
|
|
383
385
|
- **`#teardown!`** runs `stop` on the started components and `teardown` on all of them, deferred or stopped ones included.
|
|
384
386
|
|
|
387
|
+
### Recycling components
|
|
388
|
+
|
|
389
|
+
`#recycle_component!(key, context = Thread.current)` runs a component's whole lifecycle again, from the top: it stops the component if it's running, tears it down, drops its value, then prepares and builds it from scratch. This is for class reloaders and the like — a file changes, and the components built from it are recycled.
|
|
390
|
+
|
|
391
|
+
```ruby
|
|
392
|
+
App.recycle_component!('sourced.store', task)
|
|
393
|
+
App.recycle_components!('sourced.store', 'repos.users', context: task) # several at once
|
|
394
|
+
App.recycle!(task) # the whole tree
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
- **Every component is left in the status it was in before.** A started one is started again with `context`, and one that was only built stops at built. Nothing changes the root's own status.
|
|
398
|
+
- **The components depending on it are recycled too**, directly or not: their values were built from its old value, so they're stale. Its own dependencies are left alone, running.
|
|
399
|
+
- **A component that was stopped by key, or deferred, comes back `:built` and still held.** Its fresh value has never run, so it waits to be started by `#start_component!`, exactly as it was waiting before.
|
|
400
|
+
- **Order:** down in reverse dependency order, dependents first, then up in dependency order, one stage at a time — every affected component is prepared before any is built, as when the root boots.
|
|
401
|
+
- **Keys are relative to the component** the method is called on, like `#component!`. Only the root can `#recycle!` the whole tree.
|
|
402
|
+
- **Hooks:** a started component runs `stop` then `teardown` on the way down, and `prepare`, `build` and `start` on the way back up. A component that wasn't running only runs `teardown`.
|
|
403
|
+
- **Events:** `root.recycling` and `root.recycled` wrap the operation, and each component publishes its usual stage events, so a reloader can follow along. As with `#teardown!`, the `stop` hooks of a started component run under its `components.tearing_down` event.
|
|
404
|
+
|
|
405
|
+
```
|
|
406
|
+
db <- store <- dispatcher
|
|
407
|
+
|
|
408
|
+
App.recycle_component!('store') # tears down dispatcher, then store
|
|
409
|
+
# then builds store, dispatcher, and starts both again
|
|
410
|
+
# db keeps running, with the same value
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
- **If a `stop` or `teardown` hook raises,** every affected component is still torn down and its value dropped, and the first error is re-raised before anything is prepared again. They're left `:open`, with no value: reading one raises `NotBuiltError`.
|
|
414
|
+
- **If a `prepare`, `build` or `start` hook raises,** the component is left where it got to and the error is re-raised, along with the components the recycle hadn't reached: `:open` or `:prepared` with no value, where reading one raises `NotBuiltError`, or `:built` with the value it just built for them.
|
|
415
|
+
- **Recycling again recovers, however it failed.** Each component remembers the status the first recycle meant to restore, until one completes, so a retry puts it back even when its own status no longer says it was running: a component a failed `start` left `:built` is started again, not left behind. A reloader can just retry on the next save.
|
|
416
|
+
- **The root must be built, or started.** Before that there's nothing to recycle, and it raises `NotBuiltError`; once the root is torn down, `TornDownError`. Recycling while the root is booting raises `LockedComponentError`: mid-`#start!` there's no settled status to go back to.
|
|
417
|
+
- **No code is reloaded.** Recycling re-runs the hooks a component was implemented with; it doesn't re-implement it. The tree is locked once prepared, so a class captured in a provider (`App.component!('store', Store)`) stays captured — only a block that resolves the constant when it builds (`build { Store.new }`) picks up a reloaded class.
|
|
418
|
+
|
|
419
|
+
### Re-configuring a booted tree
|
|
420
|
+
|
|
421
|
+
`#reconfigure(key, context = Thread.current)` re-declares one branch of the tree from scratch while it's running. The block declares the branch's new contents, and whatever it doesn't declare is removed. This is for file watchers: rescan a directory, re-register every file, and removal is a consequence of not declaring a key rather than an operation of its own.
|
|
422
|
+
|
|
423
|
+
```ruby
|
|
424
|
+
App.reconfigure('reactors') do |reactors|
|
|
425
|
+
files.each { |f| reactors.declare(f.key) } # idempotent: these are kept
|
|
426
|
+
changed.each { |f| reactors.component!(f.key, f.deps, &f.hooks) } # these recycle
|
|
427
|
+
end
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
| In the block | Before | Result |
|
|
431
|
+
| --- | --- | --- |
|
|
432
|
+
| declared, not re-implemented | existed | kept, untouched: same value and status |
|
|
433
|
+
| declared and re-implemented | existed | recycled |
|
|
434
|
+
| declared with another type | existed | recycled |
|
|
435
|
+
| declared | new | prepared, built, and started if the root is started |
|
|
436
|
+
| not declared | existed | torn down and removed |
|
|
437
|
+
|
|
438
|
+
- **Re-declaring is idempotent**, so a component whose declaration didn't change keeps its value and status, and runs no hooks. Only the ones the block re-implements, re-types or declares for the first time are recycled (see above), along with everything depending on them.
|
|
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
|
+
- **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
|
+
- **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
|
+
|
|
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.
|
|
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.
|
|
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.
|
|
454
|
+
- **A component that keeps declared children reverts to a namespace** instead of being removed. That's the `billing.rb` → `billing/` refactor: it's torn down and loses its implementation, but stays as the parent of its new children. Collapsing it back the other way re-implements it and removes the children.
|
|
455
|
+
- **An open tree** reconfigures as plain declaration: nothing is built yet, so nothing is torn down or recycled, and `#prepare!` validates the whole set when it boots.
|
|
456
|
+
- **Events:** `root.reconfiguring` and `root.reconfigured` wrap the operation, with `components.removed` for each removal and the usual stage and recycling events in between.
|
|
457
|
+
- **No code is reloaded**, as with recycling: the block supplies the new implementations, and a class captured in a provider is only re-captured if the block passes it again.
|
|
458
|
+
|
|
459
|
+
```ruby
|
|
460
|
+
App.reconfigure('reactors') do |reactors|
|
|
461
|
+
reactors.declare('audit') # kept, still running
|
|
462
|
+
reactors.declare('billing.invoices') # kept
|
|
463
|
+
reactors.component!('billing.invoices', [], NewImpl) # ... but re-implemented, so recycled
|
|
464
|
+
# 'billing.payments' isn't declared: torn down and removed
|
|
465
|
+
end
|
|
466
|
+
```
|
|
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
|
+
- **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.
|
|
533
|
+
- **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.
|
|
534
|
+
- **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:
|
|
535
|
+
|
|
536
|
+
```ruby
|
|
537
|
+
App.from_dir('system/**/*.rb', root: 'system')
|
|
538
|
+
# system/users/create.rb => 'users.create'
|
|
539
|
+
# system/queries/search.rb => 'queries.search'
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
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.
|
|
543
|
+
- **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.
|
|
544
|
+
- **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.
|
|
545
|
+
- **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.
|
|
546
|
+
- **`#from_dir` is for open trees**, and raises `LockedComponentError` once the tree is prepared, including inside a `#reconfigure` block.
|
|
547
|
+
- **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.
|
|
548
|
+
- **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).
|
|
549
|
+
|
|
385
550
|
### Signal handlers
|
|
386
551
|
|
|
387
|
-
The lifecycle methods, and anything else that takes the root's lock (declaring, implementing and mounting components, `#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.
|
|
552
|
+
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.
|
|
388
553
|
|
|
389
554
|
Instead, have the trap wake up the main thread, and tear down from there, as in the example above:
|
|
390
555
|
|
|
@@ -398,10 +563,31 @@ trap('TERM') { Thread.main.raise(Interrupt) }
|
|
|
398
563
|
|
|
399
564
|
Any other way out of trap context works too, ex. pushing to a `Queue` or writing to a self-pipe that a thread waits on.
|
|
400
565
|
|
|
566
|
+
### Forked processes
|
|
567
|
+
|
|
568
|
+
`#prepare!` resolves dependencies, computes the boot order and runs the `prepare` hooks, but builds no values. That makes it the point to fork from: the parent holds no connections, sockets or threads, and each child builds and starts its own.
|
|
569
|
+
|
|
570
|
+
```ruby
|
|
571
|
+
App.prepare! # once, in the parent: requires, validation, dependency order
|
|
572
|
+
|
|
573
|
+
workers.times do
|
|
574
|
+
fork do
|
|
575
|
+
App.build!
|
|
576
|
+
App.start!(task) # this process' own values, from here on
|
|
577
|
+
...
|
|
578
|
+
end
|
|
579
|
+
end
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
- **Don't fork a built or started tree.** Threads don't survive `fork`, so a long-running component would report `:started` in the child with nothing running, and file descriptors *do* survive, shared: the child and the parent would write to the same connection. Tearing down or recycling in the child would then run `stop` and `teardown` hooks on resources the parent still owns.
|
|
583
|
+
- **Fork from the main thread**, with no lifecycle call in flight. The root's `Monitor` is copied as-is, so forking while another thread holds it leaves the child's copy locked forever.
|
|
584
|
+
- **A reconfigured branch comes up to where the tree already is**, and no further: on a prepared tree its new components are prepared but not built, so children forked afterwards build them for themselves. Deferring lowers that ceiling to `:built`, it never raises it.
|
|
585
|
+
- **Everything else is per-process.** `#recycle_component!` and `#reconfigure` act on one process' tree, in memory, with no coordination between them: a file watcher has to run in each process that should react to it, as `ActiveSupport::FileUpdateChecker` and Zeitwerk do. Driving one from a signal has the `trap` restriction above, since it takes the root's lock.
|
|
586
|
+
|
|
401
587
|
### Errors while starting and tearing down
|
|
402
588
|
|
|
403
589
|
- If a `start` hook raises, the components already started are torn down in reverse order, the component is left `:torn_down`, and the error is re-raised.
|
|
404
|
-
- If `teardown` hooks raise, every component is still torn down, and the first error is re-raised.
|
|
590
|
+
- If `stop` or `teardown` hooks raise, every component is still torn down, exactly once, and the first error is re-raised. This holds for anything they raise, `Interrupt` included: a signal handler interrupting the shutdown can't leave part of the tree running, and the root still ends `:torn_down`. A component whose hooks already ran is never torn down again, so `#teardown!` is safe to call once more after one failed.
|
|
405
591
|
|
|
406
592
|
## Mounting components
|
|
407
593
|
|
|
@@ -553,6 +739,53 @@ App.start!
|
|
|
553
739
|
MyLib::Dispatcher.new.store # => #<DBStore ...>, the app's override
|
|
554
740
|
```
|
|
555
741
|
|
|
742
|
+
### `.__component_deps`
|
|
743
|
+
|
|
744
|
+
Including an injector also defines `.__component_deps` on the class: every component injected into it, including the ones injected into its ancestors, as the key it's registered under mapped to the name it's injected as.
|
|
745
|
+
|
|
746
|
+
```ruby
|
|
747
|
+
class Foo
|
|
748
|
+
include App.inject('logger', 'repos.users' => 'customers')
|
|
749
|
+
end
|
|
750
|
+
|
|
751
|
+
Foo.__component_deps # => { "logger" => :logger, "repos.users" => :customers }
|
|
752
|
+
```
|
|
753
|
+
|
|
754
|
+
- **Keys** are the ones components are **registered** under, never the names they're injected as. **Values** are those names, as symbols, so they can go straight into keyword arguments.
|
|
755
|
+
- Inherited dependencies are included, the superclass' first, each class' own in the order they were injected. A component injected twice is listed once, under the name closest to the class: a subclass injecting `'logger' => 'app_logger'` over its parent's `'logger'` reports `:app_logger`.
|
|
756
|
+
- Keys are paths from the root of the component's tree, so they follow mounting. `MyLib::Dispatcher` above reports `{ "store" => :store }` while the library is standalone, and `{ "my_lib.store" => :store }` once the app mounts it at `my_lib`: the key the app would use to read it.
|
|
757
|
+
- An alias (see `#alias`) is listed under its own key, not its target's.
|
|
758
|
+
- A class defining its own `def self.__component_deps` keeps it: unlike the injected readers, this one is never overwritten.
|
|
759
|
+
- `Sourced::Component::Injector.deps_for(klass)` returns the same hash for any class or module, which is useful when an injector is included into a module rather than directly into a class: the module gets `.__component_deps`, but classes including it don't.
|
|
760
|
+
|
|
761
|
+
### `#factory`
|
|
762
|
+
|
|
763
|
+
Keys and values line up with a component's dependencies and its constructor's keyword arguments, so `#factory(key, constructor)` implements a declared component from a class that injects:
|
|
764
|
+
|
|
765
|
+
```ruby
|
|
766
|
+
class Dispatcher
|
|
767
|
+
include App.inject('logger', 'repos.users' => 'customers')
|
|
768
|
+
end
|
|
769
|
+
|
|
770
|
+
App.declare('dispatcher', Dispatcher)
|
|
771
|
+
App.factory('dispatcher', Dispatcher) # Dispatcher.new(logger:, customers:)
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
which is the same as writing out what the class already declares:
|
|
775
|
+
|
|
776
|
+
```ruby
|
|
777
|
+
deps = Dispatcher.__component_deps # { "logger" => :logger, "repos.users" => :customers }
|
|
778
|
+
App.config('dispatcher', deps.keys) { |*values| Dispatcher.new(**deps.values.zip(values).to_h) }
|
|
779
|
+
```
|
|
780
|
+
|
|
781
|
+
- **The injected components become the component's dependencies**, so it's built after them and [`#graph`](#graph) shows the edges.
|
|
782
|
+
- **Values are passed to the constructor**, so each dependency is read once per build. The injector takes the keyword arguments it's given instead of reading the components itself, which matters for a dynamic dependency: the instance and the build see the same value.
|
|
783
|
+
- **It's dynamic**, like `#config`: a new instance on every read. For one instance, built once, use `App.config!('dispatcher', deps.keys) { ... }` with the block above.
|
|
784
|
+
- **Any class works.** One that injects nothing is built with `new` and no arguments, and so has no dependencies. One that needs positional arguments doesn't fit: `#factory` only passes keywords.
|
|
785
|
+
- **Inherited injections are included**, since `.__component_deps` includes them.
|
|
786
|
+
- **Declare the key first.** `#factory` implements an existing declaration, and the built instance is parsed through its declared type like any other value.
|
|
787
|
+
- **Keys are paths from the root of the injector's tree** (see above), so call `#factory` on that root. Calling it on a component mounted inside that tree resolves them relative to itself instead, and `#prepare!` then raises `MissingDependencyError`.
|
|
788
|
+
|
|
556
789
|
## Inspecting the tree
|
|
557
790
|
|
|
558
791
|
```ruby
|
|
@@ -570,8 +803,10 @@ node.root # => App
|
|
|
570
803
|
node.owner # => the component that declared it
|
|
571
804
|
node.type # => the declared type
|
|
572
805
|
node.implementation # => deps, mode (:singleton, :dynamic or :alias) and the implementing component
|
|
806
|
+
node.dep_nodes # => the components it depends on, wildcards included. See #graph for keys
|
|
573
807
|
node.children # => { segment => Component }
|
|
574
808
|
node.namespace? # => no type and no implementation
|
|
809
|
+
node.removed? # => whether a #reconfigure dropped it from the tree
|
|
575
810
|
```
|
|
576
811
|
|
|
577
812
|
### `#tree`
|
|
@@ -733,10 +968,13 @@ end
|
|
|
733
968
|
| `components.stopping` / `components.stopped` | around a component's `stop` hooks, when stopped by key (on `#teardown!`, they're part of tearing down) | `key`, and `duration` when finished |
|
|
734
969
|
| `components.tearing_down` / `components.torn_down` | around a component's `teardown` hooks | `key`, and `duration` when finished |
|
|
735
970
|
| `components.deferred` | `#defer` | `key`, `deferrer` (the full path of the component that deferred it, `nil` for the root) |
|
|
971
|
+
| `components.removed` | a component `#reconfigure` dropped from the tree | `key`, `remover` (the full path of the component that reconfigured, `nil` for the root) |
|
|
736
972
|
| `components.failed` | a component's hook (or type check) raised | `key`, `stage`, `error_class`, `error_message`, `backtrace` |
|
|
737
973
|
| `root.preparing` / `root.prepared` | around `#prepare!` | `duration` when finished |
|
|
738
974
|
| `root.building` / `root.built` | around `#build!` | `duration` when finished |
|
|
739
975
|
| `root.starting` / `root.started` | around `#start!` | `duration` when finished |
|
|
976
|
+
| `root.recycling` / `root.recycled` | around `#recycle_component!`, `#recycle_components!` and `#recycle!` | `duration` when finished |
|
|
977
|
+
| `root.reconfiguring` / `root.reconfigured` | around `#reconfigure` | `duration` when finished |
|
|
740
978
|
| `root.tearing_down` / `root.torn_down` | around `#teardown!` | `duration` when finished |
|
|
741
979
|
| `root.failed` | a lifecycle step raised | `stage`, `error_class`, `error_message`, `backtrace` |
|
|
742
980
|
|
|
@@ -744,7 +982,7 @@ end
|
|
|
744
982
|
- **`key`** is the component's full path from the root, ex. `sourced.db`.
|
|
745
983
|
- **`deps`** are relative to the `implementer`, the full path of the component that implemented the component (`nil` for the root).
|
|
746
984
|
- **`duration`** is in seconds, measured with a monotonic clock.
|
|
747
|
-
- **`stage`** is one of `:prepare`, `:build`, `:start`, `:stop` or `:
|
|
985
|
+
- **`stage`** is one of `:prepare`, `:build`, `:start`, `:stop`, `:teardown`, `:recycle` or `:reconfigure`.
|
|
748
986
|
- **Errors are described, not attached:** `error_class`, `error_message` and `backtrace` are strings, so events stay serializable (see below). The error itself is re-raised to the caller of the lifecycle method.
|
|
749
987
|
|
|
750
988
|
A few rules:
|
|
@@ -834,15 +1072,16 @@ Plumb::ParseError: user: {age: "Must be a Integer"}
|
|
|
834
1072
|
| --- | --- |
|
|
835
1073
|
| `DeclarationOverrideError` | declaring or mounting on a key that's already declared |
|
|
836
1074
|
| `OwnershipError` | declaring or mounting under nodes owned by another component |
|
|
837
|
-
| `LockedComponentError` | changing the tree after it's prepared,
|
|
1075
|
+
| `LockedComponentError` | changing the tree after it's prepared, mounting a component that isn't open, recycling or reconfiguring while the root is booting, or a nested `#reconfigure` |
|
|
838
1076
|
| `SubcomponentError` | booting a mounted component, or mounting a component that's already mounted |
|
|
839
1077
|
| `UndeclaredComponentError` | implementing or reading an undeclared key, or reading a namespace |
|
|
840
1078
|
| `UnimplementedComponentError` | preparing with declared (or deferred) components that have no implementation |
|
|
841
1079
|
| `MissingDependencyError` | preparing with dependencies that aren't declared or implemented |
|
|
842
1080
|
| `CircularDependencyError` | preparing with dependency cycles |
|
|
843
|
-
| `NotBuiltError` | reading values before the component is built |
|
|
844
|
-
| `TornDownError` | starting a component that's torn down, or starting or
|
|
1081
|
+
| `NotBuiltError` | reading values before the component is built, reading one that was recycled away, or recycling before the root is built |
|
|
1082
|
+
| `TornDownError` | starting a component that's torn down, or starting, stopping or recycling a component by key once its root is torn down |
|
|
845
1083
|
| `NotStartedError` | starting or stopping a component by key before its root is started |
|
|
1084
|
+
| `RemovedComponentError` | reading a component that `#reconfigure` removed from the tree |
|
|
846
1085
|
| `InjectionError` | including an injector in a class that already has a method with an injected name, or already injects it |
|
|
847
1086
|
|
|
848
1087
|
## Thread safety
|
|
@@ -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,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
|