asgard 0.5.1 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +272 -99
  3. data/README.md +147 -46
  4. data/bin/asgard +10 -0
  5. data/lib/asgard/base/dependency_graph.rb +19 -11
  6. data/lib/asgard/base/dispatch.rb +272 -32
  7. data/lib/asgard/base/registry.rb +7 -3
  8. data/lib/asgard/base/task_dsl.rb +6 -0
  9. data/lib/asgard/base.rb +147 -9
  10. data/lib/asgard/declarations.rb +21 -0
  11. data/lib/asgard/doctor/report.rb +5 -1
  12. data/lib/asgard/doctor/task_sections.rb +11 -3
  13. data/lib/asgard/doctor.rb +41 -31
  14. data/lib/asgard/jobs/commands.rb +183 -0
  15. data/lib/asgard/jobs/declaration.rb +149 -0
  16. data/lib/asgard/jobs/launcher.rb +109 -0
  17. data/lib/asgard/jobs/state.rb +195 -0
  18. data/lib/asgard/jobs/stopper.rb +141 -0
  19. data/lib/asgard/jobs.rb +25 -0
  20. data/lib/asgard/kernel_methods.rb +25 -30
  21. data/lib/asgard/leading_flag.rb +26 -0
  22. data/lib/asgard/log.rb +90 -0
  23. data/lib/asgard/pid.rb +113 -0
  24. data/lib/asgard/schedule/commands.rb +68 -18
  25. data/lib/asgard/schedule/declaration.rb +158 -26
  26. data/lib/asgard/schedule/job_files.rb +24 -0
  27. data/lib/asgard/schedule/launchd.rb +57 -21
  28. data/lib/asgard/schedule/systemd.rb +72 -28
  29. data/lib/asgard/schedule/table.rb +48 -26
  30. data/lib/asgard/schedule.rb +49 -9
  31. data/lib/asgard/shell.rb +366 -44
  32. data/lib/asgard/state_dir.rb +90 -0
  33. data/lib/asgard/tasks.rb +8 -0
  34. data/lib/asgard/version.rb +1 -1
  35. data/lib/asgard/watch/changes.rb +26 -1
  36. data/lib/asgard/watch/commands.rb +63 -13
  37. data/lib/asgard/watch/daemon.rb +347 -52
  38. data/lib/asgard/watch/declaration.rb +135 -40
  39. data/lib/asgard/watch/dispatcher.rb +61 -10
  40. data/lib/asgard/watch/mailbox.rb +50 -0
  41. data/lib/asgard/watch/reporter.rb +54 -32
  42. data/lib/asgard/watch/spawn.rb +43 -18
  43. data/lib/asgard/watch/state.rb +93 -27
  44. data/lib/asgard/watch/worker.rb +44 -9
  45. data/lib/asgard/watch.rb +4 -11
  46. data/lib/asgard.rb +100 -16
  47. metadata +170 -186
  48. data/.envrc +0 -6
  49. data/.github/workflows/deploy-github-pages.yml +0 -52
  50. data/.loki +0 -39
  51. data/.reek.yml +0 -166
  52. data/.rubocop.yml +0 -163
  53. data/Archspec.rb +0 -24
  54. data/CLAUDE.md +0 -139
  55. data/COMMITS.md +0 -196
  56. data/bin/console +0 -11
  57. data/bin/setup +0 -8
  58. data/doc_tasks.loki +0 -21
  59. data/docs/api.md +0 -368
  60. data/docs/assets/css/custom.css +0 -93
  61. data/docs/assets/images/asgard.jpg +0 -0
  62. data/docs/changelog.md +0 -1
  63. data/docs/dependencies.md +0 -313
  64. data/docs/environment.md +0 -129
  65. data/docs/examples.md +0 -194
  66. data/docs/getting-started.md +0 -181
  67. data/docs/helpers.md +0 -262
  68. data/docs/index.md +0 -87
  69. data/docs/options.md +0 -224
  70. data/docs/schedule.md +0 -106
  71. data/docs/shell.md +0 -237
  72. data/docs/subcommands.md +0 -181
  73. data/docs/task-files.md +0 -407
  74. data/docs/tasks.md +0 -326
  75. data/docs/variables.md +0 -338
  76. data/docs/watch.md +0 -123
  77. data/examples/.env +0 -4
  78. data/examples/.envrc +0 -3
  79. data/examples/.loki +0 -24
  80. data/examples/bad.loki +0 -63
  81. data/examples/concurrent.loki +0 -58
  82. data/examples/confirm.loki +0 -48
  83. data/examples/db_subcommands.loki +0 -74
  84. data/examples/depends_on_block/bad/.loki +0 -51
  85. data/examples/depends_on_block/good/.loki +0 -83
  86. data/examples/do.loki +0 -45
  87. data/examples/env_usage.loki +0 -27
  88. data/examples/kitchen_sink.loki +0 -210
  89. data/examples/server_subcommands.loki +0 -65
  90. data/examples/subdir/.loki +0 -12
  91. data/examples/subdir/import_demo.loki +0 -14
  92. data/examples/subdir/import_up_demo.loki +0 -18
  93. data/examples/watcher_examples/.envrc +0 -3
  94. data/examples/watcher_examples/.loki +0 -54
  95. data/examples/watcher_examples/README.md +0 -112
  96. data/examples/watcher_examples/bin/hello +0 -3
  97. data/examples/watcher_examples/data/records.json +0 -1
  98. data/examples/watcher_examples/docs/drafts/ideas.md +0 -5
  99. data/examples/watcher_examples/docs/index.md +0 -4
  100. data/examples/watcher_examples/lib/greeter.rb +0 -7
  101. data/gem_tasks.loki +0 -51
  102. data/git.loki +0 -13
  103. data/mkdocs.yml +0 -166
  104. data/quality.loki +0 -266
  105. data/quality_rails.loki +0 -47
  106. data/xyzzy.loki +0 -12
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 = (Asgard.find_task_file&.dirname || Pathname.pwd).to_s
26
+ def schedule_root = @schedule_root ||= Asgard.project_root
27
27
 
28
- def schedule_project = File.basename(schedule_root)
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 { |slug, found| found == entry && (project.nil? || slug == project) }
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 job files.
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 && Schedule.slug(schedule_project)
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; see other_project_row.
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, exec: true) if options[:follow]
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 "remove", "Remove all of this project's installed entries"
231
- def remove
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 { |name| schedule_uninstall(name) }
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. Tests assign one that records commands
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. as: names the entry.
77
- def normalize(task, options: nil, at: nil, on: :daily, every: nil, env: {}, as: nil)
78
- task = task.to_s
79
- unless task.match?(/\A[\w:-]+\z/)
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
- { name: entry_name(task, args, as), task:, args:, at:, on:, every:, env: env.to_h { |key, value| [key.to_s, value.to_s] } }
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 : slug([task, *args].join(" ")))).to_s
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
- def describe(at: nil, on: :daily, every: nil, **)
122
- return "every #{every}s" if every
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(at: nil, on: :daily, every: nil, **)
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(**spec) }
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: state == :active ? (last_exit || "never run") : "-" }
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.key(names) || names
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. Each argument is its own element, so no shell re-splits them.
232
- def program_arguments(task, args = [], root:, asgard:, direnv: nil)
233
- argv = [task.to_s, *args.map(&:to_s)]
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