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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +272 -99
- data/README.md +147 -46
- data/bin/asgard +10 -0
- data/lib/asgard/base/dependency_graph.rb +19 -11
- data/lib/asgard/base/dispatch.rb +272 -32
- data/lib/asgard/base/registry.rb +7 -3
- data/lib/asgard/base/task_dsl.rb +6 -0
- data/lib/asgard/base.rb +147 -9
- data/lib/asgard/declarations.rb +21 -0
- data/lib/asgard/doctor/report.rb +5 -1
- data/lib/asgard/doctor/task_sections.rb +11 -3
- data/lib/asgard/doctor.rb +41 -31
- data/lib/asgard/jobs/commands.rb +183 -0
- data/lib/asgard/jobs/declaration.rb +149 -0
- data/lib/asgard/jobs/launcher.rb +109 -0
- data/lib/asgard/jobs/state.rb +195 -0
- data/lib/asgard/jobs/stopper.rb +141 -0
- data/lib/asgard/jobs.rb +25 -0
- data/lib/asgard/kernel_methods.rb +25 -30
- data/lib/asgard/leading_flag.rb +26 -0
- data/lib/asgard/log.rb +90 -0
- data/lib/asgard/pid.rb +113 -0
- data/lib/asgard/schedule/commands.rb +68 -18
- data/lib/asgard/schedule/declaration.rb +158 -26
- data/lib/asgard/schedule/job_files.rb +24 -0
- data/lib/asgard/schedule/launchd.rb +57 -21
- data/lib/asgard/schedule/systemd.rb +72 -28
- data/lib/asgard/schedule/table.rb +48 -26
- data/lib/asgard/schedule.rb +49 -9
- data/lib/asgard/shell.rb +366 -44
- data/lib/asgard/state_dir.rb +90 -0
- data/lib/asgard/tasks.rb +8 -0
- data/lib/asgard/version.rb +1 -1
- data/lib/asgard/watch/changes.rb +26 -1
- data/lib/asgard/watch/commands.rb +63 -13
- data/lib/asgard/watch/daemon.rb +347 -52
- data/lib/asgard/watch/declaration.rb +135 -40
- data/lib/asgard/watch/dispatcher.rb +61 -10
- data/lib/asgard/watch/mailbox.rb +50 -0
- data/lib/asgard/watch/reporter.rb +54 -32
- data/lib/asgard/watch/spawn.rb +43 -18
- data/lib/asgard/watch/state.rb +93 -27
- data/lib/asgard/watch/worker.rb +44 -9
- data/lib/asgard/watch.rb +4 -11
- data/lib/asgard.rb +100 -16
- metadata +170 -186
- data/.envrc +0 -6
- data/.github/workflows/deploy-github-pages.yml +0 -52
- data/.loki +0 -39
- data/.reek.yml +0 -166
- data/.rubocop.yml +0 -163
- data/Archspec.rb +0 -24
- data/CLAUDE.md +0 -139
- data/COMMITS.md +0 -196
- data/bin/console +0 -11
- data/bin/setup +0 -8
- data/doc_tasks.loki +0 -21
- data/docs/api.md +0 -368
- data/docs/assets/css/custom.css +0 -93
- data/docs/assets/images/asgard.jpg +0 -0
- data/docs/changelog.md +0 -1
- data/docs/dependencies.md +0 -313
- data/docs/environment.md +0 -129
- data/docs/examples.md +0 -194
- data/docs/getting-started.md +0 -181
- data/docs/helpers.md +0 -262
- data/docs/index.md +0 -87
- data/docs/options.md +0 -224
- data/docs/schedule.md +0 -106
- data/docs/shell.md +0 -237
- data/docs/subcommands.md +0 -181
- data/docs/task-files.md +0 -407
- data/docs/tasks.md +0 -326
- data/docs/variables.md +0 -338
- data/docs/watch.md +0 -123
- data/examples/.env +0 -4
- data/examples/.envrc +0 -3
- data/examples/.loki +0 -24
- data/examples/bad.loki +0 -63
- data/examples/concurrent.loki +0 -58
- data/examples/confirm.loki +0 -48
- data/examples/db_subcommands.loki +0 -74
- data/examples/depends_on_block/bad/.loki +0 -51
- data/examples/depends_on_block/good/.loki +0 -83
- data/examples/do.loki +0 -45
- data/examples/env_usage.loki +0 -27
- data/examples/kitchen_sink.loki +0 -210
- data/examples/server_subcommands.loki +0 -65
- data/examples/subdir/.loki +0 -12
- data/examples/subdir/import_demo.loki +0 -14
- data/examples/subdir/import_up_demo.loki +0 -18
- data/examples/watcher_examples/.envrc +0 -3
- data/examples/watcher_examples/.loki +0 -54
- data/examples/watcher_examples/README.md +0 -112
- data/examples/watcher_examples/bin/hello +0 -3
- data/examples/watcher_examples/data/records.json +0 -1
- data/examples/watcher_examples/docs/drafts/ideas.md +0 -5
- data/examples/watcher_examples/docs/index.md +0 -4
- data/examples/watcher_examples/lib/greeter.rb +0 -7
- data/gem_tasks.loki +0 -51
- data/git.loki +0 -13
- data/mkdocs.yml +0 -166
- data/quality.loki +0 -266
- data/quality_rails.loki +0 -47
- 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
|
-
#
|
|
34
|
-
|
|
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 ||=
|
|
61
|
+
def watch_root = @watch_root ||= Asgard.project_root
|
|
51
62
|
|
|
52
|
-
def watch_project =
|
|
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
|
-
|
|
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
|
-
|
|
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})",
|
|
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 -
|
|
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(
|
|
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
|
data/lib/asgard/watch/daemon.rb
CHANGED
|
@@ -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
|
|
7
|
-
# the dispatcher routes them to worker Ractors;
|
|
8
|
-
# log and the entry records. A change to any
|
|
9
|
-
# process so declarations are never stale
|
|
10
|
-
#
|
|
11
|
-
#
|
|
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,
|
|
15
|
-
# tasks the project defines
|
|
16
|
-
|
|
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
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
@
|
|
30
|
-
@
|
|
31
|
-
@
|
|
32
|
-
@
|
|
33
|
-
@
|
|
34
|
-
@
|
|
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
|
-
#
|
|
45
|
-
|
|
46
|
-
|
|
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
|
-
#
|
|
67
|
-
|
|
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
|
-
#
|
|
70
|
-
#
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
@
|
|
74
|
-
@
|
|
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
|
-
|
|
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
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
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.
|
|
339
|
+
def build_listeners = @config.declarations.values.flat_map { |spec| spec[:dirs].map { |dir| listener_for(spec, dir) } }
|
|
93
340
|
|
|
94
|
-
# One Listen listener
|
|
95
|
-
|
|
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(
|
|
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
|
-
|
|
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
|
-
@
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
@
|
|
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
|
-
|
|
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
|