asgard 0.5.1 → 0.6.1

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.
Files changed (106) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +272 -99
  3. data/README.md +147 -46
  4. data/bin/asgard +10 -0
  5. data/lib/asgard/base/dependency_graph.rb +19 -11
  6. data/lib/asgard/base/dispatch.rb +272 -32
  7. data/lib/asgard/base/registry.rb +7 -3
  8. data/lib/asgard/base/task_dsl.rb +6 -0
  9. data/lib/asgard/base.rb +147 -9
  10. data/lib/asgard/declarations.rb +21 -0
  11. data/lib/asgard/doctor/report.rb +5 -1
  12. data/lib/asgard/doctor/task_sections.rb +11 -3
  13. data/lib/asgard/doctor.rb +41 -31
  14. data/lib/asgard/jobs/commands.rb +183 -0
  15. data/lib/asgard/jobs/declaration.rb +149 -0
  16. data/lib/asgard/jobs/launcher.rb +109 -0
  17. data/lib/asgard/jobs/state.rb +195 -0
  18. data/lib/asgard/jobs/stopper.rb +141 -0
  19. data/lib/asgard/jobs.rb +25 -0
  20. data/lib/asgard/kernel_methods.rb +25 -30
  21. data/lib/asgard/leading_flag.rb +26 -0
  22. data/lib/asgard/log.rb +90 -0
  23. data/lib/asgard/pid.rb +113 -0
  24. data/lib/asgard/schedule/commands.rb +68 -18
  25. data/lib/asgard/schedule/declaration.rb +158 -26
  26. data/lib/asgard/schedule/job_files.rb +24 -0
  27. data/lib/asgard/schedule/launchd.rb +57 -21
  28. data/lib/asgard/schedule/systemd.rb +72 -28
  29. data/lib/asgard/schedule/table.rb +48 -26
  30. data/lib/asgard/schedule.rb +49 -9
  31. data/lib/asgard/shell.rb +366 -44
  32. data/lib/asgard/state_dir.rb +90 -0
  33. data/lib/asgard/tasks.rb +8 -0
  34. data/lib/asgard/version.rb +1 -1
  35. data/lib/asgard/watch/changes.rb +26 -1
  36. data/lib/asgard/watch/commands.rb +63 -13
  37. data/lib/asgard/watch/daemon.rb +347 -52
  38. data/lib/asgard/watch/declaration.rb +135 -40
  39. data/lib/asgard/watch/dispatcher.rb +61 -10
  40. data/lib/asgard/watch/mailbox.rb +50 -0
  41. data/lib/asgard/watch/reporter.rb +54 -32
  42. data/lib/asgard/watch/spawn.rb +43 -18
  43. data/lib/asgard/watch/state.rb +93 -27
  44. data/lib/asgard/watch/worker.rb +44 -9
  45. data/lib/asgard/watch.rb +4 -11
  46. data/lib/asgard.rb +100 -16
  47. metadata +170 -186
  48. data/.envrc +0 -6
  49. data/.github/workflows/deploy-github-pages.yml +0 -52
  50. data/.loki +0 -39
  51. data/.reek.yml +0 -166
  52. data/.rubocop.yml +0 -163
  53. data/Archspec.rb +0 -24
  54. data/CLAUDE.md +0 -139
  55. data/COMMITS.md +0 -196
  56. data/bin/console +0 -11
  57. data/bin/setup +0 -8
  58. data/doc_tasks.loki +0 -21
  59. data/docs/api.md +0 -368
  60. data/docs/assets/css/custom.css +0 -93
  61. data/docs/assets/images/asgard.jpg +0 -0
  62. data/docs/changelog.md +0 -1
  63. data/docs/dependencies.md +0 -313
  64. data/docs/environment.md +0 -129
  65. data/docs/examples.md +0 -194
  66. data/docs/getting-started.md +0 -181
  67. data/docs/helpers.md +0 -262
  68. data/docs/index.md +0 -87
  69. data/docs/options.md +0 -224
  70. data/docs/schedule.md +0 -106
  71. data/docs/shell.md +0 -237
  72. data/docs/subcommands.md +0 -181
  73. data/docs/task-files.md +0 -407
  74. data/docs/tasks.md +0 -326
  75. data/docs/variables.md +0 -338
  76. data/docs/watch.md +0 -123
  77. data/examples/.env +0 -4
  78. data/examples/.envrc +0 -3
  79. data/examples/.loki +0 -24
  80. data/examples/bad.loki +0 -63
  81. data/examples/concurrent.loki +0 -58
  82. data/examples/confirm.loki +0 -48
  83. data/examples/db_subcommands.loki +0 -74
  84. data/examples/depends_on_block/bad/.loki +0 -51
  85. data/examples/depends_on_block/good/.loki +0 -83
  86. data/examples/do.loki +0 -45
  87. data/examples/env_usage.loki +0 -27
  88. data/examples/kitchen_sink.loki +0 -210
  89. data/examples/server_subcommands.loki +0 -65
  90. data/examples/subdir/.loki +0 -12
  91. data/examples/subdir/import_demo.loki +0 -14
  92. data/examples/subdir/import_up_demo.loki +0 -18
  93. data/examples/watcher_examples/.envrc +0 -3
  94. data/examples/watcher_examples/.loki +0 -54
  95. data/examples/watcher_examples/README.md +0 -112
  96. data/examples/watcher_examples/bin/hello +0 -3
  97. data/examples/watcher_examples/data/records.json +0 -1
  98. data/examples/watcher_examples/docs/drafts/ideas.md +0 -5
  99. data/examples/watcher_examples/docs/index.md +0 -4
  100. data/examples/watcher_examples/lib/greeter.rb +0 -7
  101. data/gem_tasks.loki +0 -51
  102. data/git.loki +0 -13
  103. data/mkdocs.yml +0 -166
  104. data/quality.loki +0 -266
  105. data/quality_rails.loki +0 -47
  106. data/xyzzy.loki +0 -12
@@ -1,8 +1,8 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require "pathname"
4
3
  require "shellwords"
5
4
  require "time"
5
+ require_relative "../log"
6
6
 
7
7
  # warn is silent when $VERBOSE is nil and bypasses $stderr in Ruby 4.0 (see
8
8
  # base/task_dsl.rb); these messages are for the user, so they always print.
@@ -30,14 +30,25 @@ module Asgard
30
30
  end
31
31
 
32
32
  # The LAST RUN column from an entry's record: never, still running,
33
- # or its exit status with duration and finish time.
34
- def last_run(entry)
33
+ # did not finish (no exit was recorded and its process is gone: a
34
+ # crash, a kill -9), or its exit status with duration and finish
35
+ # time. +running+ says whether an unfinished entry's task still runs.
36
+ def last_run(entry, running: State.method(:running?))
35
37
  return "never" unless entry
36
- return "running (pid #{entry[:pid]})" unless entry.key?(:finished)
38
+ return "#{running.call(entry) ? 'running' : 'did not finish'} (pid #{entry[:pid]})" unless entry.key?(:finished)
37
39
 
38
40
  finished = Time.iso8601(entry[:finished]).strftime("%Y-%m-%d %H:%M:%S")
39
41
  "#{entry[:status]} (#{format('%.1fs', entry[:seconds])}, #{finished})"
40
42
  end
43
+
44
+ # How `start` launches `watcher run`: in the project root, its own
45
+ # process group, output to the log, and no stdin, which it would
46
+ # otherwise share with the terminal that ran `start`.
47
+ def daemon_spawn_options(root, log) = { chdir: root, pgroup: true, in: File::NULL, out: [log, "a"], err: %i[child out] }
48
+
49
+ # The shell command `log -f` runs. -F, not -f: it keeps following
50
+ # watcher.log when rotation renames it and a new one starts.
51
+ def follow_command(path) = "tail -n +1 -F #{path.shellescape}"
41
52
  end
42
53
 
43
54
  desc "tree", "Print a tree of the watcher subcommands", hide: true
@@ -47,9 +58,9 @@ module Asgard
47
58
  no_commands do
48
59
  def watches = Watch.declarations
49
60
 
50
- def watch_root = @watch_root ||= File.realpath((Asgard.find_task_file&.dirname || Pathname.pwd).to_s)
61
+ def watch_root = @watch_root ||= Asgard.project_root
51
62
 
52
- def watch_project = File.basename(watch_root)
63
+ def watch_project = @watch_project ||= Schedule.project_slug(watch_root)
53
64
 
54
65
  def state = @state ||= State.new(project: watch_project, root: watch_root)
55
66
 
@@ -95,35 +106,64 @@ module Asgard
95
106
  def daemon
96
107
  specs = declared_watches
97
108
  refuse_if_another_running
98
- config = Daemon::Config.new(declarations: specs, root: watch_root, state:, context: spawn_context, tasks: Tasks.all_commands.keys)
109
+ config = Daemon::Config.new(declarations: specs, root: watch_root, state:, context: spawn_context, tasks: Tasks.all_commands.keys,
110
+ pending: ENV.delete(State::PENDING_ENV))
99
111
  Daemon.new(config).run
100
112
  end
101
113
 
114
+ # What a reload runs before it re-execs: the checks `run` makes,
115
+ # without running anything. Exits non-zero, saying why on stderr,
116
+ # when the task files do not load, nothing is watched, or a watch
117
+ # names a task the project does not define.
118
+ desc "check", "Exit 0 when the watches would run (what a reload checks first)", hide: true
119
+ def check
120
+ declared_watches
121
+ nil
122
+ end
123
+
102
124
  desc "start", "Start the watcher for this project in the background"
103
125
  def start
104
126
  specs = declared_watches
105
127
  refuse_if_running
106
128
  log = state.log_path
107
129
  state.prepare.write_declarations(specs.values)
108
- pid = Process.spawn(watch_asgard, "watcher", "run", chdir: watch_root, pgroup: true, out: [log, "a"], err: %i[child out])
130
+ lock = state.acquire_lock or abort("watcher is already running for #{watch_project}; `asgard watcher stop` first.")
131
+ pid = Process.spawn({ State::LOCK_ENV => lock.fileno.to_s }, watch_asgard, "watcher", "run",
132
+ **Commands.daemon_spawn_options(watch_root, log), lock.fileno => lock.fileno)
133
+ lock.close # the daemon holds it now
109
134
  Process.detach(pid)
110
135
  state.write_pid(pid)
111
136
  puts "started watcher for #{watch_project} (pid #{pid}); log: #{log}"
112
137
  end
113
138
 
114
- desc "stop", "Stop the watcher; a task already running finishes first"
139
+ desc "stop", "Stop the watcher; a task already running finishes first (--force: end running tasks)"
140
+ method_option :force, aliases: "-f", type: :boolean, desc: "End running tasks (TERM, then KILL) instead of waiting for them"
115
141
  def stop
116
142
  pid = state.running_pid or abort("watcher is not running for #{watch_project}.")
117
143
  Process.kill("TERM", pid)
118
- while Reporter.alive?(pid)
144
+ waited = 0
145
+ while State.daemon?(pid)
119
146
  running = state.running_entries.map { |entry| "#{entry[:entry]} (pid #{entry[:pid]})" }
120
147
  puts "watcher: waiting for #{running.join(', ')}" unless running.empty?
121
148
  sleep STOP_WAIT
149
+ force_stop(pid) if options[:force] && (waited += 1) == 1
122
150
  end
123
151
  state.clear
124
152
  puts "stopped watcher for #{watch_project}"
125
153
  end
126
154
 
155
+ no_commands do
156
+ # The second TERM, a moment after the first so the two are not
157
+ # merged into one pending signal: the daemon takes it as "end the
158
+ # running tasks", which it does only for groups it can prove are
159
+ # its own tasks.
160
+ def force_stop(pid)
161
+ Process.kill("TERM", pid) if State.daemon?(pid)
162
+ rescue Errno::ESRCH
163
+ nil
164
+ end
165
+ end
166
+
127
167
  no_commands do
128
168
  # True when list should cover every project: asked for with --all, or
129
169
  # there is no .loki here, so no single project to scope to.
@@ -151,7 +191,8 @@ module Asgard
151
191
  State.all.to_h do |slug, root|
152
192
  other = State.new(project: slug, root:)
153
193
  own = Asgard.find_task_file && root == watch_root
154
- ["Project: #{slug} (#{root})", Commands.project_rows(other, own ? declared_records : other.read_declarations)]
194
+ title = ["Project: #{slug} (#{root})", ("[root missing]" unless File.directory?(root))].compact.join(" ")
195
+ [title, Commands.project_rows(other, own ? declared_records : other.read_declarations)]
155
196
  end
156
197
  end
157
198
  end
@@ -197,14 +238,23 @@ module Asgard
197
238
  end
198
239
 
199
240
  desc "log", "Print this project's watcher log to STDOUT"
200
- method_option :follow, aliases: "-f", type: :boolean, desc: "Keep printing new output as it arrives (tail -f)"
241
+ method_option :follow, aliases: "-f", type: :boolean, desc: "Keep printing new output as it arrives, across rotation (tail -F)"
201
242
  def log
202
243
  path = state.log_path
203
244
  return $stderr.puts "#{watch_project} has no watcher log yet (#{path}); it is created on the first start." unless File.exist?(path)
204
- return sh("tail -n +1 -f #{path.shellescape}", silent: true, exec: true) if options[:follow]
245
+ return sh(Commands.follow_command(path), silent: true) if options[:follow]
205
246
 
206
247
  IO.copy_stream(path, $stdout)
207
248
  end
249
+
250
+ desc "truncate_log", "Keep the last M lines of this project's watcher logs; --lines 0 empties them"
251
+ method_option :lines, type: :string, default: "1000", banner: "M", desc: "Lines to keep per log; 0 empties it"
252
+ method_option :dry_run, aliases: "-n", type: :boolean, desc: "Report what would be removed without changing logs"
253
+ def truncate_log
254
+ Log.truncate_logs([state.log_path, "#{state.log_path}.1"], lines: options[:lines], dry_run: options[:dry_run])
255
+ rescue ArgumentError, SystemCallError, IOError => e
256
+ abort "watcher: #{e.message}"
257
+ end
208
258
  end
209
259
  end
210
260
  end
@@ -3,35 +3,57 @@
3
3
  module Asgard
4
4
  module Watch
5
5
  # `asgard watcher run`: the whole watcher in one foreground process.
6
- # One Listen listener per declaration pushes batches onto the inbox;
7
- # the dispatcher routes them to worker Ractors; the reporter writes the
8
- # log and the entry records. A change to any .loki file re-execs the
9
- # process so declarations are never stale. INT or TERM stops listening,
10
- # drops triggers that have not started, waits for running tasks to
11
- # exit, removes the pidfile and returns.
6
+ # One Listen listener per watched directory of each declaration pushes
7
+ # batches onto the inbox; the dispatcher routes them to worker Ractors;
8
+ # the reporter writes the log and the entry records. A change to any
9
+ # .loki file re-execs the process so declarations are never stale: the
10
+ # listener only raises a flag, and the main thread shuts down and
11
+ # execs, since a listener cannot stop itself from its own callback
12
+ # thread. INT or TERM stops listening, drops triggers that have not
13
+ # started, waits for running tasks to exit, removes the pidfile and
14
+ # returns; a second INT or TERM ends the running tasks.
12
15
  class Daemon
13
16
  # What a run is made of: the normalized declarations, the real
14
- # project root, the State, the Spawn::Context, and the names of the
15
- # tasks the project defines.
16
- Config = Data.define(:declarations, :root, :state, :context, :tasks)
17
+ # project root, the State, the Spawn::Context, the names of the
18
+ # tasks the project defines, and the pending-changes file a reload
19
+ # handed this run (State::PENDING_ENV), if any.
20
+ Config = Data.define(:declarations, :root, :state, :context, :tasks, :pending) do
21
+ def initialize(pending: nil, **) = super
22
+ end
23
+
24
+ # What a daemon is given to work with, so a test can stand in for any
25
+ # of it (see Daemon#initialize).
26
+ Tools = Data.define(:listen, :exec, :out, :dispatcher, :validate, :grace)
27
+
28
+ # What has been asked of a running daemon: to stop, to end its tasks
29
+ # by force (and when that began), or to reload the task files.
30
+ Requests = Struct.new(:stopping, :force, :forced_at, :reload)
31
+
32
+ # What a run holds while it is up: the project lock, the report queue,
33
+ # and the reporter and dispatcher with their threads.
34
+ Pipeline = Struct.new(:lock, :reports, :reporter, :dispatcher, :reporter_thread, :dispatcher_thread)
17
35
 
18
36
  LOKI_DEBOUNCE = 0.5
19
37
 
38
+ # Seconds between the TERM a second stop sends running tasks and the
39
+ # KILL for any still running.
40
+ FORCE_GRACE = 5.0
41
+
20
42
  attr_reader :inbox, :listeners
21
43
 
22
44
  # listen: is the Listen module (loaded only when nothing else is
23
45
  # given) or a stand-in; exec: replaces the process on reload; out:
24
- # is where shutdown progress goes.
25
- def initialize(config, listen: Daemon.listen_module, exec: Kernel.method(:exec), out: $stdout)
26
- @config = config
27
- @listen = listen
28
- @exec = exec
29
- @out = out
30
- @inbox = Queue.new
31
- @listeners = []
32
- @stopping = false
33
- @reporter = nil
34
- @dispatcher = nil
46
+ # is where shutdown progress goes; dispatcher: is the Dispatcher class;
47
+ # validate: answers whether the edited project would run (asgard,
48
+ # root); grace: is FORCE_GRACE.
49
+ def initialize(config, listen: Daemon.listen_module, exec: Kernel.method(:exec), out: $stdout, dispatcher: Dispatcher,
50
+ validate: Daemon.method(:loki_valid?), grace: FORCE_GRACE)
51
+ @config = config
52
+ @tools = Tools.new(listen:, exec:, out:, dispatcher:, validate:, grace:)
53
+ @inbox = Queue.new
54
+ @listeners = []
55
+ @requests = Requests.new(false, false, nil, false)
56
+ @pipeline = Pipeline.new
35
57
  end
36
58
 
37
59
  class << self
@@ -41,82 +63,355 @@ module Asgard
41
63
  Listen
42
64
  end
43
65
 
44
- # The Listen options for one declaration.
45
- def listen_options(spec)
46
- { only: spec[:only], ignore: spec[:ignore], wait_for_delay: spec[:debounce], relative: true }.compact
66
+ # Listen's own list of editor and tool temp files (swap files,
67
+ # .DS_Store, ...), kept when its directory defaults are replaced.
68
+ def editor_ignores
69
+ require "listen/silencer"
70
+ Listen::Silencer::DEFAULT_IGNORED_EXTENSIONS
71
+ end
72
+
73
+ # The Listen options for one watched directory of a declaration.
74
+ # ignore! replaces Listen's defaults, which ignore log/ and tmp/
75
+ # under every watched directory, with the declaration's own list
76
+ # (Watch.ignores_for) plus +editor+ (editor_ignores).
77
+ def listen_options(spec, dir, editor: editor_ignores)
78
+ { only: spec[:only][dir], ignore!: [*spec[:ignore][dir], editor], wait_for_delay: spec[:debounce], relative: true }.compact
79
+ end
80
+
81
+ # What the main loop does next: a stop wins over a pending reload.
82
+ def next_action(stopping:, reload:)
83
+ return :stop if stopping
84
+
85
+ reload ? :reload : :wait
86
+ end
87
+
88
+ # Drops the triggers still waiting in a worker's +mailbox+, with
89
+ # any spilled change lists, and queues the nil that ends the worker
90
+ # once its running task exits. The dropped triggers, oldest first.
91
+ def close_queue(mailbox)
92
+ dropped = Dispatcher.take_waiting(mailbox.queue)
93
+ dropped.each { |item| Worker.remove_changes_file(item[:changes_file]) if item.is_a?(Hash) }
94
+ mailbox.push(nil)
95
+ dropped
96
+ end
97
+
98
+ # Waits for a worker to end; one that died has nothing to wait for.
99
+ def join_worker(ractor)
100
+ ractor.join
101
+ rescue Ractor::Error
102
+ nil
103
+ end
104
+
105
+ # [entry, { modified:, added:, removed: }] pairs as the pending
106
+ # list a reload hands on: one { entry:, changes: } per entry, its
107
+ # changes merged in order.
108
+ def pending(pairs)
109
+ pairs.group_by(&:first).map do |entry, batches|
110
+ { entry:, changes: Watch.merge_changes(batches.map { |_, lists| Changes.new(**lists.slice(*Changes.members)) }).to_h }
111
+ end
112
+ end
113
+
114
+ # The paths, relative to +root+, whose change reloads the daemon:
115
+ # every task file in +loaded+ (what $LOADED_FEATURES holds) inside
116
+ # the root, and any .loki directly in the root, where an
117
+ # `import "*.loki"` would find a new one.
118
+ def loki_pattern(root, loaded)
119
+ real = File.realpath(root.to_s)
120
+ files = loaded.select { |path| path.to_s.end_with?(".loki") }.filter_map { |path| relative_to(real, path) }
121
+ Regexp.union(%r{\A[^/]*\.loki\z}, *files.map { |file| /\A#{Regexp.escape(file)}\z/ })
122
+ end
123
+
124
+ # +path+ relative to +root+ (a real path), or nil outside it. Real
125
+ # paths on both sides where the file exists, since a symlinked
126
+ # temp dir (/var -> /private/var) would otherwise never match.
127
+ def relative_to(root, path)
128
+ full = File.exist?(path.to_s) ? File.realpath(path.to_s) : File.expand_path(path.to_s)
129
+ full.delete_prefix("#{root}/") if full.start_with?("#{root}/")
130
+ end
131
+
132
+ # Whether the edited project would run: `asgard watcher check`
133
+ # exits 0 in +root+, which loads the task files and checks the
134
+ # declarations exactly as `watcher run` does (some watch declared,
135
+ # every watched task defined). Its errors go to the daemon's log,
136
+ # so the reason shows.
137
+ def loki_valid?(asgard, root) = system(asgard, "watcher", "check", chdir: root, in: File::NULL, out: File::NULL) || false
138
+
139
+ # Runs a clean-up step whose failure must not hide the error that
140
+ # made it necessary.
141
+ def quietly
142
+ yield
143
+ rescue StandardError
144
+ nil
47
145
  end
48
146
 
49
147
  # The tasks declared by watch but not defined by the project.
50
148
  def unknown_tasks(declarations, tasks) = declarations.values.map { |spec| spec[:task] }.uniq - tasks
149
+
150
+ # Sends +signal+ to the process group of the task running as +pid+,
151
+ # only when task_group? proves it is one; whether it was sent. The
152
+ # keywords stand in for the system in tests.
153
+ def signal_task(signal, pid, task, own_pgrp: Process.getpgrp, pgid_of: Process.method(:getpgid),
154
+ command: Pid.method(:command_line), kill: Process.method(:kill))
155
+ return false unless task_group?(pid, task, own_pgrp:, pgid_of:, command:)
156
+
157
+ kill.call(signal, -pid)
158
+ true
159
+ rescue Errno::ESRCH, Errno::EPERM
160
+ false
161
+ end
162
+
163
+ # Whether -pid may be signalled as a watched task's group: pid is an
164
+ # Integer above 1 (kill(2) gives a group of 0 or 1, and -1, meanings
165
+ # far beyond one task), neither this daemon nor its group, still the
166
+ # leader of its own group as a task spawned with pgroup: is, and
167
+ # still running asgard +task+ (a pid reused since is not ours).
168
+ def task_group?(pid, task, own_pgrp:, pgid_of:, command:)
169
+ return false unless pid.is_a?(Integer) && pid > 1 && pid != own_pgrp && pid != Process.pid
170
+
171
+ pgid_of.call(pid) == pid && State.task_process?(task, command: command.call(pid))
172
+ rescue Errno::ESRCH, Errno::EPERM
173
+ false
174
+ end
175
+
176
+ # The signal a forced stop sends next: TERM first, KILL once
177
+ # +grace+ seconds have passed since (+forced_at+), else nil.
178
+ def escalation(forced_at, now, grace)
179
+ return "TERM" unless forced_at
180
+
181
+ "KILL" if now - forced_at >= grace
182
+ end
183
+
184
+ # Whether +io+ is an open File on +path+: how the daemon knows its
185
+ # output is the watcher log `start` pointed it at.
186
+ def writes_to?(io, path) = io.is_a?(File) && !io.closed? && File.exist?(path) && File.identical?(io, path)
187
+
188
+ # Points each of +ios+ at a fresh +path+ (after the log rotated
189
+ # away beneath them), unbuffered.
190
+ def reopen_log(ios, path)
191
+ ios.each do |io|
192
+ io.reopen(path, "a")
193
+ io.sync = true
194
+ end
195
+ end
51
196
  end
52
197
 
198
+ # Traps go in first: Listen can take seconds to start on a large
199
+ # tree, and a TERM meanwhile must stop the daemon cleanly, not kill
200
+ # it. A start that fails takes down what it started (abandon).
53
201
  def run
54
202
  check_tasks!
55
203
  Dir.chdir(@config.root)
56
204
  state = @config.state.prepare
205
+ @pipeline.lock = state.lock or raise Error, "another watcher is already running for this project (#{state.lock_path} is held)"
206
+ state.write_declarations(@config.declarations.values)
207
+ trap_signals
208
+ begin
209
+ start_watching(state)
210
+ rescue StandardError
211
+ abandon(state)
212
+ raise
213
+ end
214
+ wait_for_stop_or_good_reload
215
+ finish(state, next_action == :reload)
216
+ end
217
+
218
+ # Asks run to stop; the trap handler calls this. A second call, while
219
+ # running tasks are still awaited, asks for them to be ended too.
220
+ def stop
221
+ @requests.force = true if @requests.stopping
222
+ @requests.stopping = true
223
+ end
224
+
225
+ # Asks run to replace the process with a fresh `watcher run` so new
226
+ # declarations take effect, once running tasks have exited. The
227
+ # .loki listener calls this from its own thread, so it only sets a
228
+ # flag.
229
+ def reload = @requests.reload = true
230
+
231
+ def next_action = Daemon.next_action(stopping: @requests.stopping, reload: @requests.reload)
232
+
233
+ # Waits for a stop, or for a reload into a project that would run. A
234
+ # .loki saved with an error, or one that renames a watched task or
235
+ # drops the last watch, would make the new process abort, so the
236
+ # running declarations go on watching until the next save.
237
+ def wait_for_stop_or_good_reload
238
+ loop do
239
+ sleep 0.2 while next_action == :wait
240
+ return if next_action == :stop || @tools.validate.call(@config.context.asgard, @config.root)
241
+
242
+ say "watcher: the task files do not load or declare no runnable watch; keeping the running declarations"
243
+ @requests.reload = false
244
+ end
245
+ end
246
+
247
+ private
248
+
249
+ # Shuts down, then execs the new daemon or lets go of the lock. A
250
+ # reload keeps listening until its running tasks have exited, and
251
+ # hands what was dropped or heard meanwhile to the next daemon. A
252
+ # stop that arrives while a reload waits wins.
253
+ def finish(state, reloading)
254
+ stop_listening unless reloading
255
+ dropped = shutdown(state)
256
+ stop_listening
257
+ unless next_action == :reload
258
+ say "watcher: stopped"
259
+ return @pipeline.lock.close
260
+ end
261
+
262
+ say "watcher: reloading"
263
+ exec_with_lock(write_pending(state, dropped + heard))
264
+ end
265
+
266
+ def stop_listening
267
+ @listeners.each(&:stop)
268
+ @listeners = []
269
+ end
270
+
271
+ def start_watching(state)
57
272
  start_pipeline(state)
273
+ replay(State.take_pending(@config.pending))
58
274
  @listeners = build_listeners + [loki_listener]
59
275
  @listeners.each(&:start)
60
276
  state.write_pid(Process.pid)
61
- trap_signals
62
- sleep 0.2 until @stopping
63
- shutdown(state)
64
277
  end
65
278
 
66
- # Asks run to stop; the trap handler calls this.
67
- def stop = @stopping = true
279
+ # Routes what the reloading daemon before this one saw but did not
280
+ # run, for entries that are still declared.
281
+ def replay(pending)
282
+ pending.each do |item|
283
+ name = item[:entry]
284
+ @inbox.push([name, item[:changes]]) if @config.declarations.key?(name)
285
+ end
286
+ end
68
287
 
69
- # Stops listening and replaces the process with a fresh `watcher run`
70
- # so new declarations take effect. Running tasks, in their own
71
- # process groups, carry on; the new daemon does not know about them.
72
- def reload
73
- @listeners.each(&:stop)
74
- @exec.call(@config.context.asgard, "watcher", "run")
288
+ # After a failed start: stop whatever listens, end the pipeline
289
+ # without waiting on anything, drop the pidfile and the lock.
290
+ def abandon(state)
291
+ @listeners.each { |listener| Daemon.quietly { listener.stop } }
292
+ @inbox.push(nil)
293
+ @pipeline.dispatcher&.workers&.each_value { |worker| Daemon.close_queue(worker[:mailbox]) }
294
+ @pipeline.reports&.push(nil)
295
+ state.clear
296
+ @pipeline.lock.close
75
297
  end
76
298
 
77
- private
299
+ # The new process inherits the held lock, so no other start can slip
300
+ # in between this daemon and its replacement, and is told where the
301
+ # pending changes are (nil unsets the variable).
302
+ def exec_with_lock(pending)
303
+ fd = @pipeline.lock.fileno
304
+ @tools.exec.call({ State::LOCK_ENV => fd.to_s, State::PENDING_ENV => pending }, @config.context.asgard, "watcher", "run", fd => fd)
305
+ end
306
+
307
+ # Writes the pending list for the next daemon; its path, or nil when
308
+ # nothing is pending.
309
+ def write_pending(state, pairs)
310
+ pending = Daemon.pending(pairs)
311
+ return nil if pending.empty?
312
+
313
+ State.write_json(state.pending_path, pending)
314
+ state.pending_path
315
+ end
78
316
 
79
317
  def check_tasks!
80
318
  unknown = Daemon.unknown_tasks(@config.declarations, @config.tasks)
81
319
  raise Error, "watch declares tasks this project does not define: #{unknown.join(', ')}" unless unknown.empty?
82
320
  end
83
321
 
322
+ # When `start` pointed the daemon's output at the log, that output
323
+ # follows the log through rotation (and is unbuffered), so the
324
+ # daemon's own messages never land in a rotated-away file.
84
325
  def start_pipeline(state)
85
- reports = RactorQueue.new(capacity: 1024)
86
- @reporter = Reporter.new(reports, log: state.log_path, state:)
87
- @dispatcher = Dispatcher.new(@config.declarations, @config.context, reports:)
88
- @reporter.start
89
- @dispatcher.start(@inbox)
326
+ log = state.log_path
327
+ outputs = [@tools.out, $stderr].uniq.select { |io| Daemon.writes_to?(io, log) }
328
+ Daemon.reopen_log(outputs, log)
329
+ # Workers push from their Ractors; the reporter thread pops here, in
330
+ # the main Ractor, which the Mailbox wakes on every push.
331
+ reports = Ractor.make_shareable(Mailbox.new(RactorQueue.new(capacity: 1024), Ractor.current))
332
+ @pipeline.reports = reports
333
+ @pipeline.reporter = Reporter.new(reports, log:, state:, on_rotate: -> { Daemon.reopen_log(outputs, log) })
334
+ @pipeline.dispatcher = @tools.dispatcher.new(@config.declarations, @config.context, reports:)
335
+ @pipeline.reporter_thread = @pipeline.reporter.start
336
+ @pipeline.dispatcher_thread = @pipeline.dispatcher.start(@inbox)
90
337
  end
91
338
 
92
- def build_listeners = @config.declarations.values.map { |spec| listener_for(spec) }
339
+ def build_listeners = @config.declarations.values.flat_map { |spec| spec[:dirs].map { |dir| listener_for(spec, dir) } }
93
340
 
94
- # One Listen listener whose callback pushes [entry name, batch] onto the inbox.
95
- def listener_for(spec)
341
+ # One Listen listener for one directory of a declaration, whose
342
+ # callback pushes [entry name, batch] onto the inbox.
343
+ def listener_for(spec, dir)
96
344
  name = spec[:name]
97
- @listen.to(*spec[:dirs], **Daemon.listen_options(spec)) do |modified, added, removed|
345
+ @tools.listen.to(dir, **Daemon.listen_options(spec, dir)) do |modified, added, removed|
98
346
  @inbox.push([name, { modified:, added:, removed: }])
99
347
  end
100
348
  end
101
349
 
102
350
  def loki_listener
103
- @listen.to(@config.root, only: /\.loki\z/, ignore: DEFAULT_IGNORES, wait_for_delay: LOKI_DEBOUNCE, relative: true) { reload }
351
+ only = Daemon.loki_pattern(@config.root, $LOADED_FEATURES)
352
+ @tools.listen.to(@config.root, only:, ignore: Watch.ignores_for(".", []), wait_for_delay: LOKI_DEBOUNCE, relative: true) { reload }
104
353
  end
105
354
 
106
355
  def trap_signals
107
356
  %w[INT TERM].each { |signal| trap(signal) { stop } }
108
357
  end
109
358
 
359
+ # One line of the daemon's own output, written out at once: an exec
360
+ # would otherwise drop what is still buffered.
361
+ def say(line)
362
+ @tools.out.puts line
363
+ @tools.out.flush
364
+ end
365
+
366
+ # Upstream first, so nothing is in flight when it returns: the
367
+ # dispatcher done routing (anything heard later stays on the inbox),
368
+ # the triggers no worker has started dropped, each worker ended
369
+ # after its running task exits, and only then the reporter, once
370
+ # every report is written. The dropped triggers as [entry, lists].
110
371
  def shutdown(state)
111
- @listeners.each(&:stop)
112
372
  @inbox.push(nil)
113
- @dispatcher.workers.each_value do |worker|
114
- queue = worker[:queue]
115
- queue.try_pop until queue.empty?
116
- end
117
- @reporter.drain(out: @out)
373
+ @pipeline.dispatcher_thread.join
374
+ workers = @pipeline.dispatcher.workers.values
375
+ dropped = workers.flat_map { |worker| Daemon.close_queue(worker[:mailbox]) }
376
+ wait_for_workers(workers.map { |worker| worker[:ractor] })
377
+ @pipeline.reports.push(nil)
378
+ @pipeline.reporter_thread.join
118
379
  state.clear
119
- @out.puts "watcher: stopped"
380
+ dropped.filter_map { |item| [item[:entry], item[:changes]] if item.is_a?(Hash) }
381
+ end
382
+
383
+ # The batches pushed onto the inbox after the dispatcher stopped.
384
+ def heard
385
+ batches = []
386
+ batches << @inbox.pop until @inbox.empty?
387
+ batches
388
+ end
389
+
390
+ # Says which pids it waits for, once per interval, until every
391
+ # worker has ended, ending the tasks after a second stop (escalate).
392
+ def wait_for_workers(ractors, interval: 1.0)
393
+ waiters = ractors.map { |ractor| Thread.new { Daemon.join_worker(ractor) } }
394
+ say "watcher: INT or TERM again ends the running tasks" if @requests.stopping && !@pipeline.reporter.running.empty?
395
+ loop do
396
+ pids = @pipeline.reporter.running
397
+ say "watcher: waiting for pid #{pids.join(', ')}" unless pids.empty?
398
+ break if waiters.all? { |waiter| waiter.join(interval) }
399
+
400
+ escalate
401
+ end
402
+ end
403
+
404
+ # After a second stop: TERM to every running task's process group,
405
+ # then KILL to any still running once the grace period has passed.
406
+ # Each group is signalled only through Daemon.signal_task.
407
+ def escalate
408
+ return unless @requests.force
409
+
410
+ now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
411
+ signal = Daemon.escalation(@requests.forced_at, now, @tools.grace) or return
412
+ @requests.forced_at ||= now
413
+ say "watcher: killing running tasks (#{signal})"
414
+ @pipeline.reporter.running_tasks.each { |pid, task| Daemon.signal_task(signal, pid, task) }
120
415
  end
121
416
  end
122
417
  end