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
data/lib/asgard/shell.rb
CHANGED
|
@@ -1,59 +1,381 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
-
require
|
|
3
|
+
require "English"
|
|
4
|
+
require "shellwords"
|
|
5
|
+
require_relative "pid"
|
|
4
6
|
require "tempfile"
|
|
7
|
+
require_relative "schedule/declaration"
|
|
5
8
|
|
|
6
9
|
module Asgard
|
|
10
|
+
# `shebang` is the one way a task runs something that isn't Ruby. The script
|
|
11
|
+
# is written to a tempfile and the file is handed to an interpreter from the
|
|
12
|
+
# `shells` registry, so one line and fifty lines take the same path:
|
|
13
|
+
#
|
|
14
|
+
# shebang :bash, "rake build"
|
|
15
|
+
# shebang :python3, <<~PY
|
|
16
|
+
# print("hi")
|
|
17
|
+
# PY
|
|
18
|
+
#
|
|
19
|
+
# The name may be left out, and `sh script` is the same call: both run the
|
|
20
|
+
# `default_shell`, which starts as :bash. The registry maps a name to the
|
|
21
|
+
# executable, the arguments placed before the script, and the tempfile
|
|
22
|
+
# extension:
|
|
23
|
+
#
|
|
24
|
+
# Tasks.shells[:bash] # => { path: "bash", args: [], ext: ".sh" }
|
|
25
|
+
#
|
|
26
|
+
# `shell` at class level adds or replaces an entry. A name that isn't
|
|
27
|
+
# registered runs as itself, found on PATH, with a `.tmp` extension.
|
|
7
28
|
module Shell
|
|
8
|
-
#
|
|
9
|
-
#
|
|
10
|
-
|
|
29
|
+
# The extension a declaration gets when `ext:` is omitted, keyed by the
|
|
30
|
+
# basename of its executable. Node needs `.js` to load ES modules.
|
|
31
|
+
DEFAULT_EXTENSIONS = {
|
|
32
|
+
"bash" => ".sh", "sh" => ".sh", "zsh" => ".sh", "fish" => ".fish", "csh" => ".csh", "tcsh" => ".csh",
|
|
33
|
+
"python3" => ".py", "python" => ".py",
|
|
34
|
+
"node" => ".js", "ruby" => ".rb", "perl" => ".pl"
|
|
35
|
+
}.freeze
|
|
36
|
+
|
|
37
|
+
SEEDED_SHELLS = %w[bash sh python3 python node ruby perl].freeze
|
|
38
|
+
|
|
39
|
+
class << self
|
|
40
|
+
# The registry: name => { path:, args:, ext: }. One table for every
|
|
41
|
+
# Tasks subclass, seeded with the interpreters above.
|
|
42
|
+
def shells
|
|
43
|
+
@shells ||= SEEDED_SHELLS.to_h { |name| [name.to_sym, entry(name)] }
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
# The shell `sh` and a nameless `shebang` run; :bash until a .loki says
|
|
47
|
+
# otherwise.
|
|
48
|
+
def default_shell(name = nil)
|
|
49
|
+
@default_shell = name.to_sym if name
|
|
50
|
+
@default_shell ||= :bash
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
# Restore the seeded registry and default (tests).
|
|
54
|
+
def reset_shells!
|
|
55
|
+
@shells = nil
|
|
56
|
+
@default_shell = nil
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
# Build a normalized entry. A String +path+ is split with Shellwords:
|
|
60
|
+
# the first word is the executable, the rest are arguments and come
|
|
61
|
+
# before +args+, which may be a String (also Shellwords-split) or an
|
|
62
|
+
# Array. A Pathname +path+ is the executable as is, spaces and all.
|
|
63
|
+
# +ext+ is derived from the executable's basename when omitted.
|
|
64
|
+
def entry(path, args: nil, ext: nil)
|
|
65
|
+
words = path_words(path)
|
|
66
|
+
raise ArgumentError, "shell path is empty" if words.empty?
|
|
67
|
+
|
|
68
|
+
executable = words.shift
|
|
69
|
+
{
|
|
70
|
+
path: executable,
|
|
71
|
+
args: (words + split_args(args)).freeze,
|
|
72
|
+
ext: ext || DEFAULT_EXTENSIONS.fetch(File.basename(executable), ".tmp")
|
|
73
|
+
}.freeze
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
def split_args(args)
|
|
77
|
+
case args
|
|
78
|
+
when nil then []
|
|
79
|
+
when String then Shellwords.split(args)
|
|
80
|
+
else Array(args).map(&:to_s)
|
|
81
|
+
end
|
|
82
|
+
end
|
|
83
|
+
|
|
84
|
+
# The executable and any leading arguments a path gives: a Pathname
|
|
85
|
+
# names one file and is never split; anything else is a String with
|
|
86
|
+
# shell quoting.
|
|
87
|
+
def path_words(path)
|
|
88
|
+
return path.to_s.empty? ? [] : [path.to_s] if path.is_a?(Pathname)
|
|
89
|
+
|
|
90
|
+
Shellwords.split(path.to_s)
|
|
91
|
+
end
|
|
92
|
+
|
|
93
|
+
# The name a bare path registers under: the executable's basename.
|
|
94
|
+
# "/usr/local/bin/bash -c -w" is :bash, "uv run --script" is :uv.
|
|
95
|
+
def name_for(entry) = File.basename(entry[:path]).to_sym
|
|
96
|
+
|
|
97
|
+
# The file an entry's executable names, or nil: a path with a
|
|
98
|
+
# directory part must be an executable file as given (no ~ or PATH
|
|
99
|
+
# expansion, since none happens when it runs); a bare name must be
|
|
100
|
+
# found on +env_path+.
|
|
101
|
+
def resolve(executable, env_path = ENV.fetch("PATH", nil))
|
|
102
|
+
return Schedule.which(executable, env_path) unless executable.include?(File::SEPARATOR)
|
|
103
|
+
|
|
104
|
+
executable if File.file?(executable) && File.executable?(executable)
|
|
105
|
+
end
|
|
106
|
+
|
|
107
|
+
# +entry+ when its executable resolves; ArgumentError naming the
|
|
108
|
+
# shell otherwise, so a .loki fails as it loads rather than with an
|
|
109
|
+
# exit 127 the first time a task runs.
|
|
110
|
+
def validate!(name, entry, env_path = ENV.fetch("PATH", nil))
|
|
111
|
+
return entry if resolve(entry[:path], env_path)
|
|
112
|
+
|
|
113
|
+
problem = entry[:path].include?(File::SEPARATOR) ? "is not an executable file" : "is not an executable on PATH"
|
|
114
|
+
raise ArgumentError, "shell #{name.inspect}: #{entry[:path]} #{problem}"
|
|
115
|
+
end
|
|
116
|
+
|
|
117
|
+
# The entry for +name+, or a bare fallback that runs +name+ itself as
|
|
118
|
+
# found on PATH.
|
|
119
|
+
def shell_for(name)
|
|
120
|
+
shells.fetch(name.to_sym) { { path: name.to_s, args: [].freeze, ext: DEFAULT_EXTENSIONS.fetch(name.to_s, ".tmp") }.freeze }
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
# The argv that runs +file+ with +shell+.
|
|
124
|
+
def argv(shell, file)
|
|
125
|
+
[shell[:path], *shell[:args], file]
|
|
126
|
+
end
|
|
127
|
+
|
|
128
|
+
# A process's exit code as a shell reports it: its status, or 128
|
|
129
|
+
# plus the signal number when a signal ended it.
|
|
130
|
+
def exit_code(status) = status.exitstatus || (128 + status.termsig)
|
|
131
|
+
end
|
|
132
|
+
|
|
133
|
+
module ClassMethods
|
|
134
|
+
def shells = Shell.shells
|
|
135
|
+
|
|
136
|
+
# `default_shell :zsh` selects the shell `sh` runs, leaving the
|
|
137
|
+
# registry alone; with no argument it returns the current name. Any
|
|
138
|
+
# other form registers first, through `shell`, then selects:
|
|
139
|
+
#
|
|
140
|
+
# default_shell "/usr/local/bin/bash -c -w" # :bash
|
|
141
|
+
# default_shell :strict, "bash", args: "-eu -o pipefail"
|
|
142
|
+
# default_shell :zsh, args: "-f" # path is the name
|
|
143
|
+
def default_shell(name_or_path = nil, path = nil, args: nil, ext: nil)
|
|
144
|
+
return Shell.default_shell unless name_or_path
|
|
145
|
+
|
|
146
|
+
selecting = name_or_path.is_a?(Symbol) && !(path || args || ext)
|
|
147
|
+
Shell.default_shell(selecting ? selectable!(name_or_path) : shell(name_or_path, path, args:, ext:))
|
|
148
|
+
end
|
|
149
|
+
|
|
150
|
+
# Register a shell and return its name. With a Symbol first:
|
|
151
|
+
#
|
|
152
|
+
# shell :strict, "bash -eu -o pipefail"
|
|
153
|
+
# shell :uv, "uv run --script", ext: ".py"
|
|
154
|
+
# shell :fish # fish from PATH, defaults
|
|
155
|
+
#
|
|
156
|
+
# With a bare path (String or Pathname) the name is the executable's
|
|
157
|
+
# basename, and any options in the string are parsed into args:
|
|
158
|
+
#
|
|
159
|
+
# shell "/usr/local/bin/bash -c -w" # :bash, args ["-c", "-w"]
|
|
160
|
+
#
|
|
161
|
+
# The executable must exist: an executable file at that path, or a
|
|
162
|
+
# bare name found on PATH. Otherwise ArgumentError, as the .loki loads.
|
|
163
|
+
def shell(name_or_path, path = nil, args: nil, ext: nil)
|
|
164
|
+
# A Symbol first is the name, and its path defaults to the name
|
|
165
|
+
# itself; a String or Pathname first is the path, and the name
|
|
166
|
+
# comes from the entry.
|
|
167
|
+
name = name_or_path if name_or_path.is_a?(Symbol)
|
|
168
|
+
entry = Shell.entry(name ? path || name.to_s : name_or_path, args:, ext:)
|
|
169
|
+
name ||= Shell.name_for(entry)
|
|
170
|
+
Shell.shells[name] = Shell.validate!(name, entry)
|
|
171
|
+
name
|
|
172
|
+
end
|
|
173
|
+
|
|
174
|
+
private
|
|
175
|
+
|
|
176
|
+
# +name+ when it is registered or runs as itself from PATH; otherwise
|
|
177
|
+
# ArgumentError as the .loki loads, as `shell` does for a bad path.
|
|
178
|
+
def selectable!(name)
|
|
179
|
+
return name if Shell.shells.key?(name)
|
|
180
|
+
|
|
181
|
+
Shell.validate!(name, Shell.shell_for(name))
|
|
182
|
+
name
|
|
183
|
+
end
|
|
184
|
+
end
|
|
185
|
+
|
|
186
|
+
def self.included(base) = base.extend(ClassMethods)
|
|
187
|
+
|
|
188
|
+
# The scripts `sh` is running right now, so that INT or TERM sent to
|
|
189
|
+
# asgard alone (`kill <pid>`, a process manager) reaches them too:
|
|
190
|
+
# asgard passes the signal on, waits for them, then exits with 128
|
|
191
|
+
# plus the signal's number. Only the child's own pid is signalled,
|
|
192
|
+
# never a process group, since the children share asgard's group.
|
|
11
193
|
#
|
|
12
|
-
#
|
|
13
|
-
#
|
|
14
|
-
#
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
194
|
+
# Ctrl-C at a terminal already reaches every process in the foreground
|
|
195
|
+
# group, children included, so the signal is passed on only to a child
|
|
196
|
+
# still running GRACE seconds later: a script that stops on its own
|
|
197
|
+
# Ctrl-C is not signalled a second time.
|
|
198
|
+
module Children
|
|
199
|
+
SIGNALS = %w[INT TERM].freeze
|
|
200
|
+
GRACE = 0.3
|
|
201
|
+
|
|
202
|
+
@pids = [].freeze # swapped whole, never changed: the trap reads it without a lock
|
|
203
|
+
@active = 0
|
|
204
|
+
@previous = {}
|
|
205
|
+
@received = nil
|
|
206
|
+
@mutex = Mutex.new
|
|
207
|
+
|
|
208
|
+
class << self
|
|
209
|
+
# The signal that arrived while a script ran, or nil.
|
|
210
|
+
attr_reader :received
|
|
211
|
+
|
|
212
|
+
# Runs +argv+ as a child and returns its Process::Status, or nil
|
|
213
|
+
# when it could not be started.
|
|
214
|
+
def run(argv)
|
|
215
|
+
enter
|
|
216
|
+
pid = Process.spawn(*argv)
|
|
217
|
+
add(pid)
|
|
218
|
+
Process.wait2(pid).last
|
|
219
|
+
rescue SystemCallError
|
|
220
|
+
nil
|
|
221
|
+
ensure
|
|
222
|
+
remove(pid) if pid
|
|
223
|
+
leave
|
|
224
|
+
end
|
|
225
|
+
|
|
226
|
+
# A pid asgard may signal: an Integer above 1 that is not its own.
|
|
227
|
+
def signalable?(pid) = pid.is_a?(Integer) && pid > 1 && pid != Process.pid
|
|
228
|
+
|
|
229
|
+
def alive?(pid) = signalable?(pid) && Pid.alive?(pid)
|
|
230
|
+
|
|
231
|
+
# 128 plus +signal+'s number, as a shell reports it; nil for nil.
|
|
232
|
+
def exit_status_for(signal) = signal && (128 + Signal.list.fetch(signal))
|
|
233
|
+
|
|
234
|
+
# The status asgard exits with after a signal, or nil.
|
|
235
|
+
def exit_status = exit_status_for(received)
|
|
236
|
+
|
|
237
|
+
# Sends +signal+ to every child still running, then to everything
|
|
238
|
+
# each child started. A shell killed while it waits does not pass
|
|
239
|
+
# the signal on, so the command it was running would be left
|
|
240
|
+
# behind. The tree is read before any signal, since a child that
|
|
241
|
+
# dies hands its own children to init.
|
|
242
|
+
def forward(signal, table = process_table)
|
|
243
|
+
@pids.each do |pid|
|
|
244
|
+
[pid, *descendants_of(pid, table)].each { |target| signal(signal, target) }
|
|
245
|
+
end
|
|
246
|
+
end
|
|
247
|
+
|
|
248
|
+
# Every process below +pid+ in +table+ ([pid, parent pid] pairs),
|
|
249
|
+
# nearest first.
|
|
250
|
+
def descendants_of(pid, table)
|
|
251
|
+
children = table.filter_map { |child, parent| child if parent == pid }
|
|
252
|
+
children + children.flat_map { |child| descendants_of(child, table) }
|
|
253
|
+
end
|
|
254
|
+
|
|
255
|
+
# [pid, parent pid] for every process in +ps_output+ (one pair per
|
|
256
|
+
# line); lines that are not two numbers are dropped.
|
|
257
|
+
def process_table(ps_output = ps_listing)
|
|
258
|
+
ps_output.to_s.lines.filter_map do |line|
|
|
259
|
+
pair = line.split.map { Integer(it, exception: false) }
|
|
260
|
+
pair if pair.size == 2 && pair.all?
|
|
261
|
+
end
|
|
262
|
+
end
|
|
263
|
+
|
|
264
|
+
# Every process's pid and parent pid as +ps+ prints them, or "" when
|
|
265
|
+
# ps cannot run (a slim image without procps). It rescues on its own:
|
|
266
|
+
# a default argument is evaluated outside the method's rescue, so a
|
|
267
|
+
# missing ps would otherwise escape forward before any signal went out.
|
|
268
|
+
def ps_listing(ps = Pid::PS)
|
|
269
|
+
IO.popen([ps, "-A", "-o", "pid=,ppid="], err: File::NULL, &:read)
|
|
270
|
+
rescue SystemCallError
|
|
271
|
+
""
|
|
272
|
+
end
|
|
273
|
+
|
|
274
|
+
def signal(signal, pid)
|
|
275
|
+
Process.kill(signal, pid) if alive?(pid)
|
|
276
|
+
rescue Errno::ESRCH
|
|
277
|
+
nil
|
|
278
|
+
end
|
|
279
|
+
|
|
280
|
+
private
|
|
281
|
+
|
|
282
|
+
def add(pid) = @mutex.synchronize { @pids = [*@pids, pid].freeze }
|
|
283
|
+
def remove(pid) = @mutex.synchronize { @pids = (@pids - [pid]).freeze }
|
|
284
|
+
|
|
285
|
+
# The first script to start installs the traps; the last to finish
|
|
286
|
+
# puts the previous handlers back.
|
|
287
|
+
def enter = @mutex.synchronize { install_traps if (@active += 1) == 1 }
|
|
288
|
+
def leave = @mutex.synchronize { restore_traps if (@active -= 1).zero? }
|
|
289
|
+
|
|
290
|
+
# A signal asgard was started ignoring (INT under `cmd &`) stays
|
|
291
|
+
# ignored.
|
|
292
|
+
def install_traps
|
|
293
|
+
@received = nil
|
|
294
|
+
SIGNALS.each do |signal|
|
|
295
|
+
previous = Signal.trap(signal) { on_signal(signal) }
|
|
296
|
+
previous == "IGNORE" ? Signal.trap(signal, previous) : @previous[signal] = previous || "DEFAULT"
|
|
297
|
+
end
|
|
298
|
+
end
|
|
299
|
+
|
|
300
|
+
def restore_traps
|
|
301
|
+
@previous.each { |signal, handler| Signal.trap(signal, handler) }
|
|
302
|
+
@previous = {}
|
|
303
|
+
end
|
|
304
|
+
|
|
305
|
+
# Runs in trap context, where a Mutex cannot be taken: the thread
|
|
306
|
+
# does the waiting and the signalling.
|
|
307
|
+
def on_signal(signal)
|
|
308
|
+
@received ||= signal
|
|
309
|
+
Thread.new do
|
|
310
|
+
sleep GRACE
|
|
311
|
+
forward(signal)
|
|
312
|
+
end
|
|
313
|
+
end
|
|
47
314
|
end
|
|
48
315
|
end
|
|
49
316
|
|
|
317
|
+
# One shebang call: the shell name the task gave, its registry entry and
|
|
318
|
+
# the stripped script.
|
|
319
|
+
Run = Data.define(:name, :shell, :script) do
|
|
320
|
+
def ext = shell[:ext]
|
|
321
|
+
def argv(file) = Shell.argv(shell, file)
|
|
322
|
+
def missing_message = "asgard: shell #{name.inspect} not found: #{argv('...').shelljoin}"
|
|
323
|
+
|
|
324
|
+
# Says the shell is missing and exits 127. $stderr.puts, not warn:
|
|
325
|
+
# warn is silent under -W0 and this must show.
|
|
326
|
+
def missing!
|
|
327
|
+
$stderr.puts missing_message # rubocop:disable Style/StderrPuts
|
|
328
|
+
exit 127
|
|
329
|
+
end
|
|
330
|
+
end
|
|
331
|
+
|
|
332
|
+
# Write +script+ to a tempfile and run it with the shell registered as
|
|
333
|
+
# +name+, or with the default shell when only the script is given.
|
|
334
|
+
# Returns true; exits with the command's status code on failure. `sh`
|
|
335
|
+
# is the same method under a shorter name (see the alias below).
|
|
336
|
+
#
|
|
337
|
+
# background: true starts the script as a job named after the calling
|
|
338
|
+
# task (`doc_server-1`); a Symbol or String names the job itself. The
|
|
339
|
+
# call returns a Jobs::Job at once and the job outlives asgard; see
|
|
340
|
+
# `asgard jobs`.
|
|
341
|
+
def shebang(name_or_script, script = nil, silent: false, background: nil)
|
|
342
|
+
name, script = script ? [name_or_script, script] : [Shell.default_shell, name_or_script]
|
|
343
|
+
run = Run.new(name:, shell: Shell.shell_for(name), script: script.strip)
|
|
344
|
+
job = _background_job_name(background)
|
|
345
|
+
$stdout.puts run.script unless silent
|
|
346
|
+
job ? _start_job(run, job, silent:) : _run_script(run)
|
|
347
|
+
end
|
|
348
|
+
alias_method :sh, :shebang # rubocop:disable Style/Alias -- the method form reads as the API statement it is
|
|
349
|
+
|
|
50
350
|
private
|
|
51
351
|
|
|
52
|
-
# The
|
|
53
|
-
#
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
352
|
+
# The job name a background: value asks for; only `true` consumes a
|
|
353
|
+
# sequence number, and only inside a task body.
|
|
354
|
+
def _background_job_name(background)
|
|
355
|
+
return nil unless background
|
|
356
|
+
|
|
357
|
+
task = current_task
|
|
358
|
+
sequence = _next_job_sequence if background == true && task
|
|
359
|
+
Jobs.job_name(background, task:, sequence:)
|
|
360
|
+
end
|
|
361
|
+
|
|
362
|
+
def _start_job(run, name, silent:)
|
|
363
|
+
root = Asgard.project_root
|
|
364
|
+
state = Jobs::State.new(project: Schedule.project_slug(root), root:)
|
|
365
|
+
Jobs::Launcher.start(run, name:, task: current_task, state:, silent:)
|
|
366
|
+
end
|
|
367
|
+
|
|
368
|
+
def _run_script(run)
|
|
369
|
+
Tempfile.create(["asgard_", run.ext]) do |f|
|
|
370
|
+
f.write(run.script)
|
|
371
|
+
f.flush
|
|
372
|
+
status = Children.run(run.argv(f.path))
|
|
373
|
+
run.missing! unless status
|
|
374
|
+
signalled = Children.exit_status
|
|
375
|
+
exit(signalled) if signalled
|
|
376
|
+
exit(Shell.exit_code(status)) unless status.success?
|
|
377
|
+
true
|
|
378
|
+
end
|
|
57
379
|
end
|
|
58
380
|
end
|
|
59
381
|
end
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "fileutils"
|
|
4
|
+
require "json"
|
|
5
|
+
require "tempfile"
|
|
6
|
+
|
|
7
|
+
module Asgard
|
|
8
|
+
# The layout every kind of per-project state shares: a directory per
|
|
9
|
+
# project under $XDG_STATE_HOME/asgard/<kind>/<project-slug>/ (by default
|
|
10
|
+
# ~/.local/state), a file in it naming the project root so a machine-wide
|
|
11
|
+
# listing can find every project without loading its .loki, and JSON
|
|
12
|
+
# records written whole then renamed. The watcher files its state under
|
|
13
|
+
# "watch" and background jobs under "jobs".
|
|
14
|
+
module StateDir
|
|
15
|
+
ROOT_FILE = "root"
|
|
16
|
+
|
|
17
|
+
# The size a log may reach before it is rotated, unless ASGARD_LOG_MAX
|
|
18
|
+
# (bytes) says otherwise.
|
|
19
|
+
LOG_MAX = 10 * 1024 * 1024
|
|
20
|
+
|
|
21
|
+
module_function
|
|
22
|
+
|
|
23
|
+
def base_dir(kind, home: Dir.home, env: ENV)
|
|
24
|
+
File.join(env["XDG_STATE_HOME"] || File.join(home, ".local", "state"), "asgard", kind.to_s)
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
# Every project with a state directory under base, as [slug, root] pairs.
|
|
28
|
+
def all(kind = nil, base: base_dir(kind))
|
|
29
|
+
Dir.glob(File.join(base, "*", ROOT_FILE)).map do |file|
|
|
30
|
+
[File.basename(File.dirname(file)), File.read(file).strip]
|
|
31
|
+
end
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
# Written whole then renamed, so a reader never sees a partial file.
|
|
35
|
+
# The tempfile is a dotfile: a "*.json" glob or a name pattern that
|
|
36
|
+
# lists records never picks up one that is still being written.
|
|
37
|
+
def write_json(path, value)
|
|
38
|
+
dir = File.dirname(path)
|
|
39
|
+
FileUtils.mkdir_p(dir)
|
|
40
|
+
Tempfile.create([".asgard", ".json"], dir) do |file|
|
|
41
|
+
file.write(JSON.pretty_generate(value))
|
|
42
|
+
file.flush
|
|
43
|
+
File.rename(file.path, path)
|
|
44
|
+
end
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
# The parsed record, or nil when there is none or it is not JSON (a
|
|
48
|
+
# disk that filled up, a hand edit): one bad file must not take down
|
|
49
|
+
# every listing that reads it.
|
|
50
|
+
def read_json(path)
|
|
51
|
+
return nil unless File.exist?(path)
|
|
52
|
+
|
|
53
|
+
JSON.parse(File.read(path), symbolize_names: true)
|
|
54
|
+
rescue JSON::ParserError
|
|
55
|
+
nil
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
# The log size limit: ASGARD_LOG_MAX when it is a positive number of
|
|
59
|
+
# bytes, else LOG_MAX.
|
|
60
|
+
def log_limit(env = ENV)
|
|
61
|
+
bytes = Integer(env["ASGARD_LOG_MAX"].to_s, exception: false)
|
|
62
|
+
bytes&.positive? ? bytes : LOG_MAX
|
|
63
|
+
end
|
|
64
|
+
|
|
65
|
+
# Moves +path+ to +path+.1 (replacing an older one) once it is larger
|
|
66
|
+
# than +max_bytes+; the new name when it did, else nil. A task still
|
|
67
|
+
# writing to the old file carries on into path.1, and the next line
|
|
68
|
+
# starts a fresh file.
|
|
69
|
+
def rotate(path, max_bytes:)
|
|
70
|
+
return nil unless File.exist?(path) && File.size(path) > max_bytes
|
|
71
|
+
|
|
72
|
+
File.rename(path, "#{path}.1")
|
|
73
|
+
"#{path}.1"
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
# Creates +dir+, readable by its owner only (logs and job scripts can
|
|
77
|
+
# hold secrets), and records the project root in it.
|
|
78
|
+
def record_root(dir, root)
|
|
79
|
+
private_dir(dir)
|
|
80
|
+
File.write(File.join(dir, ROOT_FILE), "#{root}\n")
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
# Creates +dir+ (and any missing parents) readable by its owner only,
|
|
84
|
+
# tightening an existing one: mkdir_p's mode: applies only to what it creates.
|
|
85
|
+
def private_dir(dir)
|
|
86
|
+
FileUtils.mkdir_p(dir, mode: 0o700)
|
|
87
|
+
File.chmod(0o700, dir)
|
|
88
|
+
end
|
|
89
|
+
end
|
|
90
|
+
end
|
data/lib/asgard/tasks.rb
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
require_relative "schedule"
|
|
4
4
|
require_relative "watch"
|
|
5
|
+
require_relative "jobs"
|
|
5
6
|
|
|
6
7
|
# Tasks is the single conventional entry point for all .loki files.
|
|
7
8
|
# It is pre-defined by the gem so .loki files never need to declare a class.
|
|
@@ -18,11 +19,13 @@ class Tasks < Asgard::Base
|
|
|
18
19
|
type: :boolean,
|
|
19
20
|
default: false,
|
|
20
21
|
desc: "Enable debug mode ($DEBUG = true)"
|
|
22
|
+
no_negate :debug
|
|
21
23
|
|
|
22
24
|
class_option :verbose,
|
|
23
25
|
type: :boolean,
|
|
24
26
|
default: false,
|
|
25
27
|
desc: "Enable verbose output ($VERBOSE = true)"
|
|
28
|
+
no_negate :verbose
|
|
26
29
|
|
|
27
30
|
class_option :version,
|
|
28
31
|
type: :boolean,
|
|
@@ -53,4 +56,9 @@ class Tasks < Asgard::Base
|
|
|
53
56
|
subcommand "_watcher", Asgard::Watch::Commands
|
|
54
57
|
map "watcher" => :_watcher
|
|
55
58
|
Asgard::Watch::Commands.commands.each_value { |command| command.ancestor_name = "watcher" }
|
|
59
|
+
|
|
60
|
+
desc "jobs SUBCOMMAND", "List, stop and restart the background jobs started with `sh ..., background: true`"
|
|
61
|
+
subcommand "_jobs", Asgard::Jobs::Commands
|
|
62
|
+
map "jobs" => :_jobs
|
|
63
|
+
Asgard::Jobs::Commands.commands.each_value { |command| command.ancestor_name = "jobs" }
|
|
56
64
|
end
|
data/lib/asgard/version.rb
CHANGED
data/lib/asgard/watch/changes.rb
CHANGED
|
@@ -1,13 +1,18 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
+
require "json"
|
|
4
|
+
|
|
3
5
|
module Asgard
|
|
4
6
|
# The files a watcher trigger saw change, as three lists of paths relative
|
|
5
7
|
# to the project root. The watcher hands them to the task through three
|
|
6
8
|
# environment variables (newline-separated, since paths may hold spaces
|
|
7
9
|
# or colons); the `changes` Kernel method reads them back. Every list is
|
|
8
10
|
# empty when the task is run by hand, so one task body serves both.
|
|
11
|
+
# Lists too big for the environment come in a JSON file named by
|
|
12
|
+
# ASGARD_CHANGES_FILE instead.
|
|
9
13
|
class Changes < Data.define(:modified, :added, :removed)
|
|
10
14
|
VARIABLES = { modified: "ASGARD_MODIFIED", added: "ASGARD_ADDED", removed: "ASGARD_REMOVED" }.freeze
|
|
15
|
+
FILE_VARIABLE = "ASGARD_CHANGES_FILE"
|
|
11
16
|
|
|
12
17
|
class << self
|
|
13
18
|
# The changes behind this process, read once from ENV. Tests and a
|
|
@@ -17,7 +22,20 @@ module Asgard
|
|
|
17
22
|
def forget = @current = nil
|
|
18
23
|
|
|
19
24
|
# Parses the trigger variables; a missing one is an empty list.
|
|
20
|
-
def from_env(env = ENV)
|
|
25
|
+
def from_env(env = ENV)
|
|
26
|
+
file = env[FILE_VARIABLE].to_s
|
|
27
|
+
return from_file(file) unless file.empty?
|
|
28
|
+
|
|
29
|
+
new(**VARIABLES.to_h { |member, variable| [member, env[variable].to_s.split("\n")] })
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
# The lists a spilled trigger wrote; empty once the file is gone.
|
|
33
|
+
def from_file(path)
|
|
34
|
+
lists = JSON.parse(File.read(path), symbolize_names: true)
|
|
35
|
+
new(**VARIABLES.keys.to_h { |member| [member, Array(lists[member])] })
|
|
36
|
+
rescue Errno::ENOENT
|
|
37
|
+
new
|
|
38
|
+
end
|
|
21
39
|
end
|
|
22
40
|
|
|
23
41
|
def initialize(modified: [], added: [], removed: [])
|
|
@@ -40,6 +58,13 @@ module Asgard
|
|
|
40
58
|
|
|
41
59
|
module_function
|
|
42
60
|
|
|
61
|
+
# One Changes holding every path of +list+, each kind in first-seen
|
|
62
|
+
# order without repeats: what several triggers that waited for the same
|
|
63
|
+
# busy task hand its next run.
|
|
64
|
+
def merge_changes(list)
|
|
65
|
+
Changes.new(**Changes.members.to_h { |member| [member, list.flat_map(&member).uniq] })
|
|
66
|
+
end
|
|
67
|
+
|
|
43
68
|
# A listener batch ({ modified:, added:, removed: }) narrowed to the
|
|
44
69
|
# kinds in events (a Set from normalize_events), as a Changes; nil
|
|
45
70
|
# when nothing is left, so the dispatcher skips the trigger.
|