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/pid.rb
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "open3"
|
|
4
|
+
|
|
5
|
+
module Asgard
|
|
6
|
+
# Questions about a pid that outlived the process that recorded it: is
|
|
7
|
+
# it alive, what is it running, and is it still the process we started?
|
|
8
|
+
# The watcher and background jobs both keep pids on disk across asgard
|
|
9
|
+
# runs, and a pid left by a crash or a reboot can belong to an unrelated
|
|
10
|
+
# process by the time it is read back. (Not Asgard::Process: that would
|
|
11
|
+
# shadow ::Process inside the namespace.)
|
|
12
|
+
module Pid
|
|
13
|
+
# ps by absolute path: a scheduled or watched task's PATH may not
|
|
14
|
+
# hold it.
|
|
15
|
+
PS = %w[/bin/ps /usr/bin/ps].find { |path| File.executable?(path) } || "ps"
|
|
16
|
+
|
|
17
|
+
# The system's ps cannot answer what these questions ask of it.
|
|
18
|
+
class Unusable < Asgard::Error; end
|
|
19
|
+
|
|
20
|
+
# One process of a group: its pid, when it started (to ps's one-second
|
|
21
|
+
# resolution) and its command line.
|
|
22
|
+
Member = Data.define(:pid, :started, :command)
|
|
23
|
+
|
|
24
|
+
module_function
|
|
25
|
+
|
|
26
|
+
# Whether a process exists; one we may not signal still exists.
|
|
27
|
+
def alive?(pid)
|
|
28
|
+
Process.kill(0, pid)
|
|
29
|
+
true
|
|
30
|
+
rescue Errno::ESRCH
|
|
31
|
+
false
|
|
32
|
+
rescue Errno::EPERM
|
|
33
|
+
true
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
# The ps argv for one pid's full command line. -ww: procps cuts the
|
|
37
|
+
# line to the terminal width (COLUMNS) without it, and a job's script
|
|
38
|
+
# path sits at the very end of a long one. macOS accepts it too.
|
|
39
|
+
def ps_argv(pid) = [PS, "-ww", "-o", "command=", "-p", pid.to_s]
|
|
40
|
+
|
|
41
|
+
# The command line of a live process as `ps` prints it, or nil when
|
|
42
|
+
# there is no such process. ps is the one way that works unchanged
|
|
43
|
+
# on macOS and Linux.
|
|
44
|
+
def command_line(pid)
|
|
45
|
+
out, status = Open3.capture2(*ps_argv(pid))
|
|
46
|
+
status.success? ? out.strip : nil
|
|
47
|
+
rescue SystemCallError
|
|
48
|
+
nil
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
# Every process in group +pgid+ as Members, each with its age, so a
|
|
52
|
+
# caller can tell a group that has kept its members from a later
|
|
53
|
+
# group that reused the id. ps by group id is not portable, so this
|
|
54
|
+
# lists every process with its group and keeps the matching ones.
|
|
55
|
+
def group_processes(pgid, now: Time.now)
|
|
56
|
+
out, status = Open3.capture2(PS, "-ww", "-A", "-o", "pid=,pgid=,etime=,command=")
|
|
57
|
+
status.success? ? parse_group(out, pgid, now:) : []
|
|
58
|
+
rescue SystemCallError
|
|
59
|
+
[]
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
# The Members of +pgid+ in `ps -o pid=,pgid=,etime=,command=` output.
|
|
63
|
+
def parse_group(ps_output, pgid, now:)
|
|
64
|
+
ps_output.each_line.filter_map do |line|
|
|
65
|
+
pid, group, etime, command = line.strip.split(/\s+/, 4)
|
|
66
|
+
Member.new(pid: pid.to_i, started: now - elapsed_seconds(etime), command: command.to_s) if group.to_i == pgid
|
|
67
|
+
end
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
# Seconds in a ps etime, "[[dd-]hh:]mm:ss" (or bare seconds).
|
|
71
|
+
def elapsed_seconds(etime)
|
|
72
|
+
days, clock = etime.include?("-") ? etime.split("-", 2) : [0, etime]
|
|
73
|
+
clock.split(":").map(&:to_i).reduce(0) { |total, part| (total * 60) + part } + (days.to_i * 86_400)
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
# Why +ps+ cannot answer for jobs, or nil when it can: it must accept
|
|
77
|
+
# the flags command_line uses and name the current process. BusyBox
|
|
78
|
+
# ps (Alpine) rejects -ww and -p; without this every job would look
|
|
79
|
+
# gone and a second start would run a duplicate.
|
|
80
|
+
def ps_problem(ps: PS)
|
|
81
|
+
out, err, status = Open3.capture3(ps, "-ww", "-o", "pid=,command=", "-p", Process.pid.to_s)
|
|
82
|
+
return err.lines.first.to_s.strip.then { it.empty? ? "exit status #{status.exitstatus}" : it } unless status.success?
|
|
83
|
+
|
|
84
|
+
out.include?(Process.pid.to_s) ? nil : "it printed nothing for pid #{Process.pid}"
|
|
85
|
+
rescue SystemCallError => e
|
|
86
|
+
e.message
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
# Raises Unusable unless +ps+ works (see ps_problem); asks once per
|
|
90
|
+
# process and ps.
|
|
91
|
+
def require_ps!(ps: PS)
|
|
92
|
+
@usable ||= {}
|
|
93
|
+
problem = @usable.fetch(ps) { @usable[ps] = ps_problem(ps:) }
|
|
94
|
+
return unless problem
|
|
95
|
+
|
|
96
|
+
raise Unusable, "#{ps} cannot list processes: #{problem}. Background jobs need a ps that accepts " \
|
|
97
|
+
"-ww, -o and -p (procps on Linux, the system ps on macOS and BSD); on Alpine, `apk add procps`"
|
|
98
|
+
end
|
|
99
|
+
|
|
100
|
+
# Whether pid is alive and its command line carries every word. The
|
|
101
|
+
# current process counts unless +self_ok+ is false: the watcher asks
|
|
102
|
+
# about itself, but a job record naming our own pid is a reused pid.
|
|
103
|
+
# An empty word matches nothing, since every command line holds "".
|
|
104
|
+
# +command:+ supplies the command line in place of asking ps (tests,
|
|
105
|
+
# or a caller that already has it).
|
|
106
|
+
def matches?(pid, *words, command: nil, self_ok: true)
|
|
107
|
+
return true if self_ok && pid == Process.pid
|
|
108
|
+
|
|
109
|
+
command ||= command_line(pid)
|
|
110
|
+
!command.nil? && words.all? { |word| !word.to_s.empty? && command.include?(word.to_s) }
|
|
111
|
+
end
|
|
112
|
+
end
|
|
113
|
+
end
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
-
require "pathname"
|
|
4
3
|
require "shellwords"
|
|
4
|
+
require_relative "../log"
|
|
5
5
|
|
|
6
6
|
# warn is silent when $VERBOSE is nil and bypasses $stderr in Ruby 4.0 (see
|
|
7
7
|
# base/task_dsl.rb); these messages are for the user, so they always print.
|
|
@@ -23,9 +23,9 @@ module Asgard
|
|
|
23
23
|
no_commands do
|
|
24
24
|
def schedules = Schedule.declarations
|
|
25
25
|
|
|
26
|
-
def schedule_root =
|
|
26
|
+
def schedule_root = @schedule_root ||= Asgard.project_root
|
|
27
27
|
|
|
28
|
-
def schedule_project =
|
|
28
|
+
def schedule_project = @schedule_project ||= Schedule.project_slug(schedule_root)
|
|
29
29
|
|
|
30
30
|
def scheduler
|
|
31
31
|
@scheduler ||= Schedule.backend_class.new(project: schedule_project, root: schedule_root)
|
|
@@ -102,7 +102,9 @@ module Asgard
|
|
|
102
102
|
return [scheduler, name] if scheduler.installed_names.include?(name)
|
|
103
103
|
|
|
104
104
|
project, entry = name.include?("/") ? name.split("/", 2) : [nil, name]
|
|
105
|
-
matches = scheduler.installed_entries.select
|
|
105
|
+
matches = scheduler.installed_entries.select do |slug, found|
|
|
106
|
+
found == entry && (project.nil? || Schedule.project_match?(slug, project))
|
|
107
|
+
end
|
|
106
108
|
abort "#{name} is in several projects (#{matches.map(&:first).join(', ')}); name one as project/#{entry}." if matches.size > 1
|
|
107
109
|
|
|
108
110
|
matches.first&.then { |slug, found| [backend_for(slug), found] }
|
|
@@ -117,6 +119,17 @@ module Asgard
|
|
|
117
119
|
find_installed(name) || abort("#{name} is neither declared nor installed (see `asgard schedule list --all`).")
|
|
118
120
|
end
|
|
119
121
|
|
|
122
|
+
# Whether +path+ is NAME's log to truncate. A declared entry that has
|
|
123
|
+
# not run yet says so and is skipped; any other name aborts.
|
|
124
|
+
def log_to_truncate?(name, path)
|
|
125
|
+
found = File.file?(path)
|
|
126
|
+
abort "schedule: no such schedule log: #{name}" if name.include?("/") || !(found || schedules.key?(name))
|
|
127
|
+
return true if found
|
|
128
|
+
|
|
129
|
+
$stderr.puts "#{name} has no log yet (#{path}); nothing to truncate"
|
|
130
|
+
false
|
|
131
|
+
end
|
|
132
|
+
|
|
120
133
|
# True when list should cover every project: asked for with --all, or
|
|
121
134
|
# there is no .loki here, so no single project to scope to.
|
|
122
135
|
def list_all? = options[:all] || Asgard.find_task_file.nil?
|
|
@@ -144,28 +157,26 @@ module Asgard
|
|
|
144
157
|
by_project.to_h { |slug, entries| [project_title(slug, entries.first.last), entry_rows(entries)] }
|
|
145
158
|
end
|
|
146
159
|
|
|
147
|
-
# "Project: slug (/full/path)", the path read from one of the project's
|
|
160
|
+
# "Project: slug (/full/path)", the path read from one of the project's
|
|
161
|
+
# job files, flagged when the directory is gone (the project moved or
|
|
162
|
+
# was deleted, and its jobs with it should be).
|
|
148
163
|
def project_title(slug, name)
|
|
149
164
|
dir = slug == current_slug ? schedule_root : backend_for(slug).installed_directory(name)
|
|
150
|
-
["Project: #{slug}", ("(#{dir})" if dir)].compact.join(" ")
|
|
165
|
+
["Project: #{slug}", ("(#{dir})" if dir), ("[root missing]" if dir && !File.directory?(dir))].compact.join(" ")
|
|
151
166
|
end
|
|
152
167
|
|
|
153
|
-
def current_slug = Asgard.find_task_file &&
|
|
168
|
+
def current_slug = Asgard.find_task_file && schedule_project
|
|
154
169
|
|
|
155
170
|
def backend_for(slug) = Schedule.backend_class.new(project: slug, root: schedule_root)
|
|
156
171
|
|
|
157
172
|
def entry_rows(entries) = entries.map { |slug, name| entry_row(slug, name) }
|
|
158
173
|
|
|
159
|
-
# This project's entries keep their declaration columns
|
|
174
|
+
# This project's entries keep their declaration columns. Another
|
|
175
|
+
# project's .loki isn't loaded, so its command and schedule are read
|
|
176
|
+
# back from the installed job files.
|
|
160
177
|
def entry_row(slug, name)
|
|
161
178
|
return schedule_row(name) if slug == current_slug
|
|
162
179
|
|
|
163
|
-
other_project_row(slug, name)
|
|
164
|
-
end
|
|
165
|
-
|
|
166
|
-
# A row for an entry of another project: its .loki isn't loaded, so the
|
|
167
|
-
# command and schedule are read back from the installed job files.
|
|
168
|
-
def other_project_row(slug, name)
|
|
169
180
|
backend = backend_for(slug)
|
|
170
181
|
shown = backend.installed_columns(name) || Schedule.declared_columns(nil, "(unreadable)")
|
|
171
182
|
{ name:, **shown, **Schedule.live_columns(backend, name) }
|
|
@@ -222,17 +233,56 @@ module Asgard
|
|
|
222
233
|
|
|
223
234
|
path = backend.log_path(entry)
|
|
224
235
|
return $stderr.puts "#{name} has no log yet (#{path}); it is created on the first run." unless File.exist?(path)
|
|
225
|
-
return sh("tail -n +1 -f #{path.shellescape}", silent: true
|
|
236
|
+
return sh("tail -n +1 -f #{path.shellescape}", silent: true) if options[:follow]
|
|
226
237
|
|
|
227
238
|
IO.copy_stream(path, $stdout)
|
|
228
239
|
end
|
|
229
240
|
|
|
230
|
-
desc "
|
|
231
|
-
|
|
241
|
+
desc "truncate_log [NAME]", "Keep the last M lines of an entry's log; no NAME truncates every schedule log of this project"
|
|
242
|
+
method_option :lines, type: :string, default: "1000", banner: "M", desc: "Lines to keep per log; 0 empties it"
|
|
243
|
+
method_option :dry_run, aliases: "-n", type: :boolean, desc: "Report what would be removed without changing logs"
|
|
244
|
+
def truncate_log(name = nil)
|
|
245
|
+
Log.line_count(options[:lines]) # reject a bad --lines even when there is no log to truncate
|
|
246
|
+
pattern = scheduler.log_path("*")
|
|
247
|
+
paths = name ? [scheduler.log_path(name)] : Dir.glob(File.join(Asgard.glob_escape(File.dirname(pattern)), File.basename(pattern)))
|
|
248
|
+
return if name && !log_to_truncate?(name, paths.first)
|
|
249
|
+
|
|
250
|
+
Log.truncate_logs(paths, lines: options[:lines], dry_run: options[:dry_run])
|
|
251
|
+
rescue ArgumentError, SystemCallError, IOError => e
|
|
252
|
+
abort "schedule: #{e.message}"
|
|
253
|
+
end
|
|
254
|
+
|
|
255
|
+
desc "remove [NAME]", "Remove one installed entry (NAME or project/NAME), or all of this project's"
|
|
256
|
+
def remove(name = nil)
|
|
257
|
+
return remove_one(name) if name
|
|
258
|
+
|
|
232
259
|
names = scheduler.installed_names
|
|
233
260
|
return puts "No scheduled tasks installed for #{schedule_project}." if names.empty?
|
|
234
261
|
|
|
235
|
-
names.each { |
|
|
262
|
+
names.each { |entry| schedule_uninstall(entry) }
|
|
263
|
+
end
|
|
264
|
+
|
|
265
|
+
desc "prune", "Remove every project's entries whose project directory no longer exists"
|
|
266
|
+
method_option :dry_run, aliases: "-n", type: :boolean, desc: "Only list what would be removed"
|
|
267
|
+
def prune
|
|
268
|
+
orphans = Schedule.orphaned_entries(scheduler.installed_entries,
|
|
269
|
+
directory_of: ->(slug, name) { backend_for(slug).installed_directory(name) })
|
|
270
|
+
return puts "Nothing to prune: every installed entry's project directory exists." if orphans.empty?
|
|
271
|
+
|
|
272
|
+
orphans.each do |slug, name|
|
|
273
|
+
next puts "would remove #{slug}/#{name}" if options[:dry_run]
|
|
274
|
+
|
|
275
|
+
backend_for(slug).uninstall(name)
|
|
276
|
+
puts "removed #{slug}/#{name}"
|
|
277
|
+
end
|
|
278
|
+
end
|
|
279
|
+
|
|
280
|
+
no_commands do
|
|
281
|
+
def remove_one(name)
|
|
282
|
+
backend, entry = resolve_installed(name)
|
|
283
|
+
backend.uninstall(entry)
|
|
284
|
+
puts "removed #{name}"
|
|
285
|
+
end
|
|
236
286
|
end
|
|
237
287
|
end
|
|
238
288
|
end
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
+
require "digest"
|
|
3
4
|
require "open3"
|
|
4
5
|
require "shellwords"
|
|
6
|
+
require "zlib"
|
|
5
7
|
|
|
6
8
|
module Asgard
|
|
7
9
|
# Scheduled asgard tasks, run by the platform's own scheduler: launchd on
|
|
@@ -27,7 +29,8 @@ module Asgard
|
|
|
27
29
|
# #installed_entries # => [[project_slug, "demo"], ...] for every project
|
|
28
30
|
# #installed_columns(name) # => { command:, schedule: } read back from the job files, or nil
|
|
29
31
|
# #installed_directory(name) # => the project root the job runs in, or nil
|
|
30
|
-
# #status(name) # => { state: :active|:stopped|:not_loaded, last_exit: String|nil }
|
|
32
|
+
# #status(name) # => { state: :active|:running|:stopped|:not_loaded, last_exit: String|nil }
|
|
33
|
+
# # last_exit: an exit code ("1") or a signal ("signal 15 (Terminated)")
|
|
31
34
|
# #log_path(name) # => path the job's output is appended to
|
|
32
35
|
# #notes # => [String] platform hints to show after install
|
|
33
36
|
module Schedule
|
|
@@ -37,6 +40,15 @@ module Asgard
|
|
|
37
40
|
# Weekday numbers follow launchd and cron: 0 (Sunday) through 6 (Saturday).
|
|
38
41
|
DAYS = %i[sunday monday tuesday wednesday thursday friday saturday].freeze
|
|
39
42
|
|
|
43
|
+
# Longest derived entry name, hash suffix included, so a job's file
|
|
44
|
+
# names stay well inside the 255-byte limit.
|
|
45
|
+
NAME_MAX = 64
|
|
46
|
+
|
|
47
|
+
# Options a slug spells out: lowercase words and flags. Any other option
|
|
48
|
+
# (--period=week, 'Week End') adds a hash suffix, so spellings that slug
|
|
49
|
+
# alike still name different entries.
|
|
50
|
+
PLAIN_ARG = /\A-{0,2}[a-z0-9]+(?:-[a-z0-9]+)*\z/
|
|
51
|
+
|
|
40
52
|
DAY_GROUPS = {
|
|
41
53
|
weekdays: %i[monday tuesday wednesday thursday friday],
|
|
42
54
|
weekends: %i[saturday sunday]
|
|
@@ -51,12 +63,13 @@ module Asgard
|
|
|
51
63
|
end
|
|
52
64
|
|
|
53
65
|
class << self
|
|
54
|
-
# The runner new backends get
|
|
55
|
-
# instead of running them; nil restores RUNNER.
|
|
56
|
-
attr_writer :runner
|
|
57
|
-
|
|
66
|
+
# The runner new backends get: RUNNER, unless use_runner swapped it.
|
|
58
67
|
def runner = @runner || RUNNER
|
|
59
68
|
|
|
69
|
+
# Tests swap in a runner that records commands instead of running
|
|
70
|
+
# them; nil restores RUNNER.
|
|
71
|
+
def use_runner(runner) = @runner = runner
|
|
72
|
+
|
|
60
73
|
# The backend class for +platform+ (a RUBY_PLATFORM string).
|
|
61
74
|
def backend_class(platform = RUBY_PLATFORM)
|
|
62
75
|
case platform
|
|
@@ -73,27 +86,67 @@ module Asgard
|
|
|
73
86
|
# task's command-line options as a String, split shell-style with quotes
|
|
74
87
|
# respected ("--period week --title 'Week End'"), or an Array of words.
|
|
75
88
|
# Exactly one of at: ("HH:MM" or an Array of them, with on:) or every:
|
|
76
|
-
# (seconds or a Duration) is required
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
raise ArgumentError,
|
|
81
|
-
"schedule: task name #{task.inspect} must be a single word; put its flags in options:"
|
|
82
|
-
end
|
|
89
|
+
# (seconds or a Duration) is required; on: goes only with at:. as: names
|
|
90
|
+
# the entry.
|
|
91
|
+
def normalize(task, options: nil, at: nil, on: nil, every: nil, env: {}, as: nil)
|
|
92
|
+
task = task_name(task)
|
|
83
93
|
raise ArgumentError, "schedule :#{task} needs either at: or every:, not both" unless at.nil? ^ every.nil?
|
|
84
94
|
|
|
85
95
|
if every
|
|
96
|
+
raise ArgumentError, "schedule :#{task} on: only applies to at: times; every: runs on every day" if on
|
|
97
|
+
|
|
86
98
|
every = seconds(every)
|
|
87
99
|
unless every&.positive?
|
|
88
100
|
raise ArgumentError,
|
|
89
101
|
"schedule :#{task} every: must be a positive number of seconds or a Duration (3.minutes)"
|
|
90
102
|
end
|
|
91
103
|
else
|
|
104
|
+
on ||= :daily
|
|
92
105
|
calendar(at:, on:) # raises on a bad time or day
|
|
93
106
|
end
|
|
94
107
|
|
|
95
108
|
args = options.is_a?(Array) ? options.map(&:to_s) : Shellwords.split(options.to_s)
|
|
96
|
-
|
|
109
|
+
args.each { |arg| reject_control_characters!(task, "options:", arg) }
|
|
110
|
+
{ name: entry_name(task, args, as), task:, args:, at:, on:, every:, env: environment_variables(task, env) }
|
|
111
|
+
end
|
|
112
|
+
|
|
113
|
+
# The command a declaration names, as Thor dispatches it: a dash is the
|
|
114
|
+
# underscore of the method name (`asgard daily-summary` runs
|
|
115
|
+
# daily_summary). A colon would name a subcommand, which is its own
|
|
116
|
+
# command word plus arguments.
|
|
117
|
+
def task_name(task)
|
|
118
|
+
name = task.to_s
|
|
119
|
+
if name.include?(":")
|
|
120
|
+
raise ArgumentError,
|
|
121
|
+
"schedule: #{name.inspect} names a subcommand; schedule its command and pass the rest in options: " \
|
|
122
|
+
"(schedule :#{name.split(':').first}, options: #{name.split(':', 2).last.inspect}, ...)"
|
|
123
|
+
end
|
|
124
|
+
unless name.match?(/\A[\w-]+\z/)
|
|
125
|
+
raise ArgumentError, "schedule: task name #{name.inspect} must be a single word; put its flags in options:"
|
|
126
|
+
end
|
|
127
|
+
|
|
128
|
+
name.tr("-", "_")
|
|
129
|
+
end
|
|
130
|
+
|
|
131
|
+
# env: as String pairs. Names must be shell-style identifiers, and no
|
|
132
|
+
# name, value or option may hold a control character other than tab: a
|
|
133
|
+
# newline would end the line it is written on in a unit file and start
|
|
134
|
+
# another directive, and plists cannot hold most of them at all.
|
|
135
|
+
def environment_variables(task, env)
|
|
136
|
+
env.to_h do |key, value|
|
|
137
|
+
key = key.to_s
|
|
138
|
+
raise ArgumentError, "schedule :#{task} env: #{key.inspect} is not a variable name" unless key.match?(/\A[A-Za-z_]\w*\z/)
|
|
139
|
+
|
|
140
|
+
value = value.to_s
|
|
141
|
+
reject_control_characters!(task, "env: #{key}", value)
|
|
142
|
+
[key, value]
|
|
143
|
+
end
|
|
144
|
+
end
|
|
145
|
+
|
|
146
|
+
def reject_control_characters!(task, what, text)
|
|
147
|
+
return unless text.match?(/[\x00-\x08\x0a-\x1f\x7f]/)
|
|
148
|
+
|
|
149
|
+
raise ArgumentError, "schedule :#{task} #{what} holds a control character (#{text.inspect})"
|
|
97
150
|
end
|
|
98
151
|
|
|
99
152
|
# Integer seconds from an Integer or anything Duration-like (ActiveSupport's
|
|
@@ -107,33 +160,73 @@ module Asgard
|
|
|
107
160
|
# The task alone, or a slug of the whole command when it has arguments,
|
|
108
161
|
# so one task can be scheduled more than once with different flags.
|
|
109
162
|
def entry_name(task, args, as = nil)
|
|
110
|
-
name = (as || (args.empty? ? task :
|
|
163
|
+
name = (as || (args.empty? ? task : command_slug([task, *args]))).to_s
|
|
111
164
|
raise ArgumentError, "schedule as: #{name.inspect} may only contain letters, digits, _ . -" unless name.match?(/\A[\w.-]+\z/)
|
|
112
165
|
|
|
113
166
|
name
|
|
114
167
|
end
|
|
115
168
|
|
|
169
|
+
# "report-period-week". A short hash of the exact words is appended when
|
|
170
|
+
# the slug would lose something (an option that isn't PLAIN_ARG, or more
|
|
171
|
+
# than NAME_MAX characters). Plain slugs can still meet: `--period week`
|
|
172
|
+
# and `period week` both give report-period-week, so do `report` with
|
|
173
|
+
# `period week` and `report_period` with `week`. Schedule.declare
|
|
174
|
+
# gives each of two such rivals its hashed_slug, so different commands
|
|
175
|
+
# never share a name.
|
|
176
|
+
def command_slug(words)
|
|
177
|
+
words = words.map(&:to_s)
|
|
178
|
+
name = slug(words.join(" "))
|
|
179
|
+
return name if name.length <= NAME_MAX && words.drop(1).all? { |arg| arg.match?(PLAIN_ARG) }
|
|
180
|
+
|
|
181
|
+
hashed_slug(words)
|
|
182
|
+
end
|
|
183
|
+
|
|
184
|
+
# The slug of a command's +words+ (the task, then its arguments) with a
|
|
185
|
+
# short hash of the exact words appended, capped at NAME_MAX:
|
|
186
|
+
# "report-period-week-1a2b3c4d".
|
|
187
|
+
def hashed_slug(words)
|
|
188
|
+
words = words.map(&:to_s)
|
|
189
|
+
digest = Digest::SHA256.hexdigest(words.join("\0"))[0, 8]
|
|
190
|
+
"#{slug(words.join(' '))[0, NAME_MAX - 9].delete_suffix('-')}-#{digest}"
|
|
191
|
+
end
|
|
192
|
+
|
|
116
193
|
def slug(name) = name.to_s.downcase.gsub(/[^a-z0-9]+/, "-").delete_prefix("-").delete_suffix("-")
|
|
117
194
|
|
|
195
|
+
# The slug a project's jobs and watcher state are filed under: the
|
|
196
|
+
# basename of its root plus the CRC32 of the real path in hex
|
|
197
|
+
# ("api-9f3a1c2b"), so two projects in directories of the same name
|
|
198
|
+
# never share labels, units or state. Symlinked paths to one project
|
|
199
|
+
# agree, since the real path is hashed.
|
|
200
|
+
def project_slug(root)
|
|
201
|
+
real = File.realpath(root.to_s)
|
|
202
|
+
"#{slug(File.basename(real))}-#{format('%08x', Zlib.crc32(real))}"
|
|
203
|
+
end
|
|
204
|
+
|
|
205
|
+
# Whether +slug+ is the project the user named: the whole slug, or its
|
|
206
|
+
# basename alone when that is enough to pick it out.
|
|
207
|
+
def project_match?(slug, name) = slug == name || slug.sub(/-\h{8}\z/, "") == name
|
|
208
|
+
|
|
118
209
|
# For display: the command line the job runs.
|
|
119
210
|
def command_line(task, args = []) = Shellwords.join(["asgard", task.to_s, *args])
|
|
120
211
|
|
|
121
|
-
|
|
122
|
-
|
|
212
|
+
# A declaration's schedule in words: "every 60s", or its times and days
|
|
213
|
+
# ("17:30 weekdays"; daily when +spec+ has no :on).
|
|
214
|
+
def describe(spec)
|
|
215
|
+
return "every #{spec[:every]}s" if spec[:every]
|
|
123
216
|
|
|
124
|
-
"#{Array(at).join(', ')} #{Array(on).join(', ')}"
|
|
217
|
+
"#{Array(spec[:at]).join(', ')} #{Array(spec[:on] || :daily).join(', ')}"
|
|
125
218
|
end
|
|
126
219
|
|
|
127
220
|
# For the `list` table: like describe, but a run of hourly times
|
|
128
221
|
# collapses ("10:00, 11:00 ... 17:00" => "10:00-17:00 hourly").
|
|
129
|
-
def describe_compact(
|
|
130
|
-
return "every #{every}s" if every
|
|
222
|
+
def describe_compact(spec)
|
|
223
|
+
return "every #{spec[:every]}s" if spec[:every]
|
|
131
224
|
|
|
132
|
-
"#{compact_times(Array(at))} #{Array(on).join(', ')}"
|
|
225
|
+
"#{compact_times(Array(spec[:at]))} #{Array(spec[:on] || :daily).join(', ')}"
|
|
133
226
|
end
|
|
134
227
|
|
|
135
228
|
# The command and schedule columns of a `list` row for a declared entry.
|
|
136
|
-
def list_columns(spec) = { command: command_line(spec[:task], spec[:args]), schedule: describe_compact(
|
|
229
|
+
def list_columns(spec) = { command: command_line(spec[:task], spec[:args]), schedule: describe_compact(spec) }
|
|
137
230
|
|
|
138
231
|
# The command and schedule columns of a `list` row: the declaration's, or
|
|
139
232
|
# `missing` in the schedule column when there is none.
|
|
@@ -142,7 +235,18 @@ module Asgard
|
|
|
142
235
|
# The state and last-exit columns of a `list` row, from a backend's live status.
|
|
143
236
|
def live_columns(backend, name)
|
|
144
237
|
state, last_exit = backend.status(name).values_at(:state, :last_exit)
|
|
145
|
-
{ state: state.to_s.tr("_", " "), last_exit:
|
|
238
|
+
{ state: state.to_s.tr("_", " "), last_exit: %i[active running].include?(state) ? (last_exit || "never run") : "-" }
|
|
239
|
+
end
|
|
240
|
+
|
|
241
|
+
# The [slug, name] entries whose job files name a project directory
|
|
242
|
+
# that no longer exists: the project moved or was deleted, and its jobs
|
|
243
|
+
# fire in a directory that is not there. An entry whose directory
|
|
244
|
+
# cannot be read is left alone.
|
|
245
|
+
def orphaned_entries(entries, directory_of:, exists: File.method(:directory?))
|
|
246
|
+
entries.select do |slug, name|
|
|
247
|
+
dir = directory_of.call(slug, name)
|
|
248
|
+
dir && !exists.call(dir)
|
|
249
|
+
end
|
|
146
250
|
end
|
|
147
251
|
|
|
148
252
|
# The command a job runs, from its program arguments: everything from
|
|
@@ -172,7 +276,7 @@ module Asgard
|
|
|
172
276
|
return :daily unless days
|
|
173
277
|
|
|
174
278
|
names = days.map { |day| DAYS.fetch(day) }
|
|
175
|
-
DAY_GROUPS.
|
|
279
|
+
DAY_GROUPS.find { |_group, members| members.sort == names.sort }&.first || names
|
|
176
280
|
end
|
|
177
281
|
|
|
178
282
|
def compact_times(times)
|
|
@@ -200,6 +304,8 @@ module Asgard
|
|
|
200
304
|
return nil if on.to_s == "daily"
|
|
201
305
|
|
|
202
306
|
names = DAY_GROUPS.fetch(on.is_a?(Array) ? nil : on.to_sym) { Array(on) }
|
|
307
|
+
raise ArgumentError, "on: needs at least one day" if names.empty?
|
|
308
|
+
|
|
203
309
|
names.map do |day|
|
|
204
310
|
DAYS.index(day.to_sym) or raise ArgumentError, "on: unknown day #{day.inspect}"
|
|
205
311
|
end
|
|
@@ -208,6 +314,8 @@ module Asgard
|
|
|
208
314
|
# One entry per time: [{ hour: 17, minute: 30, days: [1, 2, 3, 4, 5] }];
|
|
209
315
|
# days is nil for every day.
|
|
210
316
|
def calendar(at:, on: :daily)
|
|
317
|
+
raise ArgumentError, "at: needs at least one time" if Array(at).empty?
|
|
318
|
+
|
|
211
319
|
days = weekdays(on)
|
|
212
320
|
Array(at).map do |time|
|
|
213
321
|
hour, minute = parse_time(time)
|
|
@@ -215,6 +323,29 @@ module Asgard
|
|
|
215
323
|
end
|
|
216
324
|
end
|
|
217
325
|
|
|
326
|
+
# A job's last exit when a signal ended it: "signal 15 (Terminated)".
|
|
327
|
+
def signal_exit(number, name) = "signal #{number} (#{name})"
|
|
328
|
+
|
|
329
|
+
# Raises when a job file's name passes the 255-byte filename limit.
|
|
330
|
+
def check_lengths!(paths)
|
|
331
|
+
long = paths.map { |path| File.basename(path) }.find { |base| base.bytesize > 255 }
|
|
332
|
+
raise Error, "schedule: job file name is too long (#{long.bytesize} bytes, limit 255): #{long}; use a shorter as: name" if long
|
|
333
|
+
end
|
|
334
|
+
|
|
335
|
+
# Runs the block that writes job files; a failure there (the system
|
|
336
|
+
# message names the path) is a Schedule::Error, not a backtrace.
|
|
337
|
+
def writing
|
|
338
|
+
yield
|
|
339
|
+
rescue SystemCallError => e
|
|
340
|
+
raise Error, "schedule: could not write job files: #{e.message}"
|
|
341
|
+
end
|
|
342
|
+
|
|
343
|
+
# Writes a job file only its owner can read: it holds the env: values.
|
|
344
|
+
def write_private(path, content)
|
|
345
|
+
File.write(path, content, perm: 0o600)
|
|
346
|
+
File.chmod(0o600, path) # perm: applies only when the file is created
|
|
347
|
+
end
|
|
348
|
+
|
|
218
349
|
# PATH captured at install time, plus the declaration's env:.
|
|
219
350
|
def environment(spec, path = ENV.fetch("PATH", nil)) = { "PATH" => path.to_s }.merge(spec[:env])
|
|
220
351
|
|
|
@@ -228,9 +359,10 @@ module Asgard
|
|
|
228
359
|
# The job's argv. Schedulers need an absolute program. With direnv, the
|
|
229
360
|
# repo's .envrc (API keys, ...) is loaded at run time instead of being
|
|
230
361
|
# copied into the job definition, and direnv finds asgard on the job's
|
|
231
|
-
# PATH.
|
|
232
|
-
|
|
233
|
-
|
|
362
|
+
# PATH. +words+ is the task, then its arguments; each is its own
|
|
363
|
+
# element, so no shell re-splits them.
|
|
364
|
+
def program_arguments(words, root:, asgard:, direnv: nil)
|
|
365
|
+
argv = words.map(&:to_s)
|
|
234
366
|
direnv ? [direnv, "exec", root, "asgard", *argv] : [asgard, *argv]
|
|
235
367
|
end
|
|
236
368
|
end
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Asgard
|
|
4
|
+
module Schedule
|
|
5
|
+
# Reading back the job files a backend writes, the same way for
|
|
6
|
+
# launchd plists and systemd units. Pure apart from reading the files.
|
|
7
|
+
module JobFiles
|
|
8
|
+
module_function
|
|
9
|
+
|
|
10
|
+
# [[project_slug, name], ...], sorted, for each job file in +dir+.
|
|
11
|
+
def entries_in(dir, prefix:, ext:) = entries(Dir.glob(File.join(dir, "#{prefix}.*#{ext}")), prefix:, ext:)
|
|
12
|
+
|
|
13
|
+
# [[project_slug, name], ...], sorted, for each of +paths+ named
|
|
14
|
+
# <prefix>.<project_slug>.<name><ext>; any other file name is skipped.
|
|
15
|
+
def entries(paths, prefix:, ext:)
|
|
16
|
+
paths.map { File.basename(it, ext).delete_prefix("#{prefix}.").split(".", 2) }.select { it.size == 2 }.sort
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
# The project root +parser+ reads from the job file at +path+, or nil
|
|
20
|
+
# when there is no such file.
|
|
21
|
+
def directory(path, parser) = File.exist?(path) ? parser.call(File.read(path)) : nil
|
|
22
|
+
end
|
|
23
|
+
end
|
|
24
|
+
end
|