asgard 0.6.0 → 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.
@@ -21,6 +21,18 @@ module Asgard
21
21
  def initialize(pending: nil, **) = super
22
22
  end
23
23
 
24
+ # What a daemon is given to work with, so a test can stand in for any
25
+ # of it (see Daemon#initialize).
26
+ Tools = Data.define(:listen, :exec, :out, :dispatcher, :validate, :grace)
27
+
28
+ # What has been asked of a running daemon: to stop, to end its tasks
29
+ # by force (and when that began), or to reload the task files.
30
+ Requests = Struct.new(:stopping, :force, :forced_at, :reload)
31
+
32
+ # What a run holds while it is up: the project lock, the report queue,
33
+ # and the reporter and dispatcher with their threads.
34
+ Pipeline = Struct.new(:lock, :reports, :reporter, :dispatcher, :reporter_thread, :dispatcher_thread)
35
+
24
36
  LOKI_DEBOUNCE = 0.5
25
37
 
26
38
  # Seconds between the TERM a second stop sends running tasks and the
@@ -36,21 +48,12 @@ module Asgard
36
48
  # root); grace: is FORCE_GRACE.
37
49
  def initialize(config, listen: Daemon.listen_module, exec: Kernel.method(:exec), out: $stdout, dispatcher: Dispatcher,
38
50
  validate: Daemon.method(:loki_valid?), grace: FORCE_GRACE)
39
- @config = config
40
- @listen = listen
41
- @exec = exec
42
- @out = out
43
- @inbox = Queue.new
44
- @listeners = []
45
- @stopping = false
46
- @force = false
47
- @forced_at = nil
48
- @reload = false
49
- @reporter = nil
50
- @dispatcher = nil
51
- @dispatcher_class = dispatcher
52
- @validate = validate
53
- @grace = grace
51
+ @config = config
52
+ @tools = Tools.new(listen:, exec:, out:, dispatcher:, validate:, grace:)
53
+ @inbox = Queue.new
54
+ @listeners = []
55
+ @requests = Requests.new(false, false, nil, false)
56
+ @pipeline = Pipeline.new
54
57
  end
55
58
 
56
59
  class << self
@@ -94,7 +97,7 @@ module Asgard
94
97
 
95
98
  # Waits for a worker to end; one that died has nothing to wait for.
96
99
  def join_worker(ractor)
97
- ractor.respond_to?(:join) ? ractor.join : ractor.take
100
+ ractor.join
98
101
  rescue Ractor::Error
99
102
  nil
100
103
  end
@@ -199,7 +202,7 @@ module Asgard
199
202
  check_tasks!
200
203
  Dir.chdir(@config.root)
201
204
  state = @config.state.prepare
202
- @lock = state.lock or raise Error, "another watcher is already running for this project (#{state.lock_path} is held)"
205
+ @pipeline.lock = state.lock or raise Error, "another watcher is already running for this project (#{state.lock_path} is held)"
203
206
  state.write_declarations(@config.declarations.values)
204
207
  trap_signals
205
208
  begin
@@ -215,17 +218,17 @@ module Asgard
215
218
  # Asks run to stop; the trap handler calls this. A second call, while
216
219
  # running tasks are still awaited, asks for them to be ended too.
217
220
  def stop
218
- @force = true if @stopping
219
- @stopping = true
221
+ @requests.force = true if @requests.stopping
222
+ @requests.stopping = true
220
223
  end
221
224
 
222
225
  # Asks run to replace the process with a fresh `watcher run` so new
223
226
  # declarations take effect, once running tasks have exited. The
224
227
  # .loki listener calls this from its own thread, so it only sets a
225
228
  # flag.
226
- def reload = @reload = true
229
+ def reload = @requests.reload = true
227
230
 
228
- def next_action = Daemon.next_action(stopping: @stopping, reload: @reload)
231
+ def next_action = Daemon.next_action(stopping: @requests.stopping, reload: @requests.reload)
229
232
 
230
233
  # Waits for a stop, or for a reload into a project that would run. A
231
234
  # .loki saved with an error, or one that renames a watched task or
@@ -234,10 +237,10 @@ module Asgard
234
237
  def wait_for_stop_or_good_reload
235
238
  loop do
236
239
  sleep 0.2 while next_action == :wait
237
- return if next_action == :stop || @validate.call(@config.context.asgard, @config.root)
240
+ return if next_action == :stop || @tools.validate.call(@config.context.asgard, @config.root)
238
241
 
239
242
  say "watcher: the task files do not load or declare no runnable watch; keeping the running declarations"
240
- @reload = false
243
+ @requests.reload = false
241
244
  end
242
245
  end
243
246
 
@@ -253,7 +256,7 @@ module Asgard
253
256
  stop_listening
254
257
  unless next_action == :reload
255
258
  say "watcher: stopped"
256
- return @lock.close
259
+ return @pipeline.lock.close
257
260
  end
258
261
 
259
262
  say "watcher: reloading"
@@ -287,18 +290,18 @@ module Asgard
287
290
  def abandon(state)
288
291
  @listeners.each { |listener| Daemon.quietly { listener.stop } }
289
292
  @inbox.push(nil)
290
- @dispatcher&.workers&.each_value { |worker| Daemon.close_queue(worker[:mailbox]) }
291
- @reports&.push(nil)
293
+ @pipeline.dispatcher&.workers&.each_value { |worker| Daemon.close_queue(worker[:mailbox]) }
294
+ @pipeline.reports&.push(nil)
292
295
  state.clear
293
- @lock.close
296
+ @pipeline.lock.close
294
297
  end
295
298
 
296
299
  # The new process inherits the held lock, so no other start can slip
297
300
  # in between this daemon and its replacement, and is told where the
298
301
  # pending changes are (nil unsets the variable).
299
302
  def exec_with_lock(pending)
300
- fd = @lock.fileno
301
- @exec.call({ State::LOCK_ENV => fd.to_s, State::PENDING_ENV => pending }, @config.context.asgard, "watcher", "run", fd => fd)
303
+ fd = @pipeline.lock.fileno
304
+ @tools.exec.call({ State::LOCK_ENV => fd.to_s, State::PENDING_ENV => pending }, @config.context.asgard, "watcher", "run", fd => fd)
302
305
  end
303
306
 
304
307
  # Writes the pending list for the next daemon; its path, or nil when
@@ -320,16 +323,17 @@ module Asgard
320
323
  # follows the log through rotation (and is unbuffered), so the
321
324
  # daemon's own messages never land in a rotated-away file.
322
325
  def start_pipeline(state)
323
- log = state.log_path
324
- @log_outputs = [@out, $stderr].uniq.select { |io| Daemon.writes_to?(io, log) }
325
- Daemon.reopen_log(@log_outputs, log)
326
+ log = state.log_path
327
+ outputs = [@tools.out, $stderr].uniq.select { |io| Daemon.writes_to?(io, log) }
328
+ Daemon.reopen_log(outputs, log)
326
329
  # Workers push from their Ractors; the reporter thread pops here, in
327
330
  # the main Ractor, which the Mailbox wakes on every push.
328
- @reports = Ractor.make_shareable(Mailbox.new(RactorQueue.new(capacity: 1024), Ractor.current))
329
- @reporter = Reporter.new(@reports, log:, state:, on_rotate: -> { Daemon.reopen_log(@log_outputs, log) })
330
- @dispatcher = @dispatcher_class.new(@config.declarations, @config.context, reports: @reports)
331
- @reporter_thread = @reporter.start
332
- @dispatcher_thread = @dispatcher.start(@inbox)
331
+ reports = Ractor.make_shareable(Mailbox.new(RactorQueue.new(capacity: 1024), Ractor.current))
332
+ @pipeline.reports = reports
333
+ @pipeline.reporter = Reporter.new(reports, log:, state:, on_rotate: -> { Daemon.reopen_log(outputs, log) })
334
+ @pipeline.dispatcher = @tools.dispatcher.new(@config.declarations, @config.context, reports:)
335
+ @pipeline.reporter_thread = @pipeline.reporter.start
336
+ @pipeline.dispatcher_thread = @pipeline.dispatcher.start(@inbox)
333
337
  end
334
338
 
335
339
  def build_listeners = @config.declarations.values.flat_map { |spec| spec[:dirs].map { |dir| listener_for(spec, dir) } }
@@ -338,14 +342,14 @@ module Asgard
338
342
  # callback pushes [entry name, batch] onto the inbox.
339
343
  def listener_for(spec, dir)
340
344
  name = spec[:name]
341
- @listen.to(dir, **Daemon.listen_options(spec, dir)) do |modified, added, removed|
345
+ @tools.listen.to(dir, **Daemon.listen_options(spec, dir)) do |modified, added, removed|
342
346
  @inbox.push([name, { modified:, added:, removed: }])
343
347
  end
344
348
  end
345
349
 
346
350
  def loki_listener
347
351
  only = Daemon.loki_pattern(@config.root, $LOADED_FEATURES)
348
- @listen.to(@config.root, only:, ignore: Watch.ignores_for(".", []), wait_for_delay: LOKI_DEBOUNCE, relative: true) { reload }
352
+ @tools.listen.to(@config.root, only:, ignore: Watch.ignores_for(".", []), wait_for_delay: LOKI_DEBOUNCE, relative: true) { reload }
349
353
  end
350
354
 
351
355
  def trap_signals
@@ -355,8 +359,8 @@ module Asgard
355
359
  # One line of the daemon's own output, written out at once: an exec
356
360
  # would otherwise drop what is still buffered.
357
361
  def say(line)
358
- @out.puts line
359
- @out.flush
362
+ @tools.out.puts line
363
+ @tools.out.flush
360
364
  end
361
365
 
362
366
  # Upstream first, so nothing is in flight when it returns: the
@@ -366,12 +370,12 @@ module Asgard
366
370
  # every report is written. The dropped triggers as [entry, lists].
367
371
  def shutdown(state)
368
372
  @inbox.push(nil)
369
- @dispatcher_thread.join
370
- workers = @dispatcher.workers.values
373
+ @pipeline.dispatcher_thread.join
374
+ workers = @pipeline.dispatcher.workers.values
371
375
  dropped = workers.flat_map { |worker| Daemon.close_queue(worker[:mailbox]) }
372
376
  wait_for_workers(workers.map { |worker| worker[:ractor] })
373
- @reports.push(nil)
374
- @reporter_thread.join
377
+ @pipeline.reports.push(nil)
378
+ @pipeline.reporter_thread.join
375
379
  state.clear
376
380
  dropped.filter_map { |item| [item[:entry], item[:changes]] if item.is_a?(Hash) }
377
381
  end
@@ -387,9 +391,9 @@ module Asgard
387
391
  # worker has ended, ending the tasks after a second stop (escalate).
388
392
  def wait_for_workers(ractors, interval: 1.0)
389
393
  waiters = ractors.map { |ractor| Thread.new { Daemon.join_worker(ractor) } }
390
- say "watcher: INT or TERM again ends the running tasks" if @stopping && !@reporter.running.empty?
394
+ say "watcher: INT or TERM again ends the running tasks" if @requests.stopping && !@pipeline.reporter.running.empty?
391
395
  loop do
392
- pids = @reporter.running
396
+ pids = @pipeline.reporter.running
393
397
  say "watcher: waiting for pid #{pids.join(', ')}" unless pids.empty?
394
398
  break if waiters.all? { |waiter| waiter.join(interval) }
395
399
 
@@ -401,13 +405,13 @@ module Asgard
401
405
  # then KILL to any still running once the grace period has passed.
402
406
  # Each group is signalled only through Daemon.signal_task.
403
407
  def escalate
404
- return unless @force
408
+ return unless @requests.force
405
409
 
406
410
  now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
407
- signal = Daemon.escalation(@forced_at, now, @grace) or return
408
- @forced_at ||= now
411
+ signal = Daemon.escalation(@requests.forced_at, now, @tools.grace) or return
412
+ @requests.forced_at ||= now
409
413
  say "watcher: killing running tasks (#{signal})"
410
- @reporter.running_tasks.each { |pid, task| Daemon.signal_task(signal, pid, task) }
414
+ @pipeline.reporter.running_tasks.each { |pid, task| Daemon.signal_task(signal, pid, task) }
411
415
  end
412
416
  end
413
417
  end
@@ -65,16 +65,23 @@ module Asgard
65
65
  def asgard_process?(pid, *words, command: nil) = Pid.matches?(pid, "asgard", *words, command:)
66
66
  end
67
67
 
68
+ # The watcher's log file: appends a line, rotating first (StateDir.rotate)
69
+ # when the file has passed limit bytes, and telling on_rotate when it did.
70
+ Log = Struct.new(:path, :limit, :on_rotate) do
71
+ def append(line)
72
+ on_rotate&.call if StateDir.rotate(path, max_bytes: limit)
73
+ File.open(path, "a") { |file| file.puts(line) }
74
+ end
75
+ end
76
+
68
77
  # state: responds to write_entry(name, record). max_log: is the size
69
78
  # past which the log is rotated (StateDir.rotate); on_rotate: is
70
79
  # called after each rotation, so the daemon can move its own output
71
80
  # to the new log.
72
81
  def initialize(reports, log:, state:, max_log: StateDir.log_limit, on_rotate: nil)
73
- @reports = reports
74
- @log = log
75
- @max_log = max_log
76
- @on_rotate = on_rotate
77
- @state = state
82
+ @reports = reports
83
+ @log = Log.new(log, max_log, on_rotate)
84
+ @state = state
78
85
  @records = {}
79
86
  @running = {} # pid => task
80
87
  @mutex = Mutex.new
@@ -97,8 +104,7 @@ module Asgard
97
104
  trigger = kind == :trigger
98
105
  line = Reporter.log_line(report, behind: trigger ? running_for(report[:task]) : nil)
99
106
  track(report) if %i[spawn exit].include?(kind)
100
- @on_rotate&.call if StateDir.rotate(@log, max_bytes: @max_log)
101
- File.open(@log, "a") { |file| file.puts(line) }
107
+ @log.append(line)
102
108
  rescue SystemCallError, IOError => e
103
109
  $stderr.puts "watcher: could not write #{kind} report for #{report[:entry]}: #{e.message}" # rubocop:disable Style/StderrPuts
104
110
  end
@@ -66,10 +66,10 @@ module Asgard
66
66
  # a trigger runs the very asgard that started the watcher whatever PATH
67
67
  # says, wrapped in direnv exec when available so .envrc loads in the
68
68
  # task's process.
69
- def argv(spec, context)
69
+ def argv(task, context)
70
70
  direnv = context.direnv
71
71
  wrapper = direnv ? [direnv, "exec", context.root] : []
72
- [*wrapper, context.asgard, spec[:task]]
72
+ [*wrapper, context.asgard, task]
73
73
  end
74
74
 
75
75
  # The asgard executable to run: the one running now when it is an
@@ -90,7 +90,7 @@ module Asgard
90
90
  # it as :changes_file only when they did.
91
91
  def description(spec, changes, context, changes_file: nil)
92
92
  env = environment(spec, changes, context, changes_file:)
93
- desc = { entry: spec[:name], task: spec[:task], argv: argv(spec, context), env:,
93
+ desc = { entry: spec[:name], task: spec[:task], argv: argv(spec[:task], context), env:,
94
94
  root: context.root, log: context.log, changes: changes.to_h }
95
95
  desc[:changes_file] = changes_file if env.key?(Changes::FILE_VARIABLE)
96
96
  Ractor.make_shareable(desc)
data/lib/asgard.rb CHANGED
@@ -11,7 +11,7 @@ require_relative "asgard/doctor"
11
11
 
12
12
  module Asgard
13
13
  # Search the current directory and its ancestors for a .loki task file.
14
- # Returns the path string, or nil if not found.
14
+ # Returns its Pathname, or nil if not found.
15
15
  def self.find_task_file
16
16
  loki_up
17
17
  end
@@ -58,7 +58,19 @@ module Asgard
58
58
  return "#{first} (#{error.class})" if error.is_a?(SyntaxError) && first.match?(LOKI_FRAME)
59
59
 
60
60
  where = Array(error.backtrace).lazy.filter_map { |frame| frame[LOKI_FRAME, 1] }.first
61
- [where, "#{first} (#{error.class})"].compact.join(": ")
61
+ hint = "; asgard's DSL (desc, depends_on, schedule, ...) goes inside class Tasks ... end" if dsl_outside_tasks?(error)
62
+ [where, "#{first} (#{error.class})#{hint}"].compact.join(": ")
63
+ end
64
+
65
+ # Whether +error+ is a Tasks class method (desc, depends_on, ...) called
66
+ # at the top level of a task file, outside `class Tasks ... end`.
67
+ def self.dsl_outside_tasks?(error)
68
+ return false unless error.is_a?(NameError) && error.receiver.equal?(TOPLEVEL_BINDING.receiver)
69
+
70
+ name = error.name or return false
71
+ Tasks.respond_to?(name, true) && !Object.respond_to?(name, true)
72
+ rescue ArgumentError # a NameError built without a receiver
73
+ false
62
74
  end
63
75
 
64
76
  # Loads the task files; anything they raise ends asgard with one line
@@ -83,8 +95,7 @@ module Asgard
83
95
  end
84
96
  return unless leading_flag?(argv, "--doctor")
85
97
 
86
- Asgard::Doctor.new.run
87
- exit
98
+ exit(Asgard::Doctor.new.run)
88
99
  end
89
100
 
90
101
  # Finds and loads the task files and checks every class they defined.
@@ -96,13 +107,20 @@ module Asgard
96
107
  ((Asgard::Base._asgard_subclasses - before) + [Tasks]).uniq.each(&:validate_deps!)
97
108
  end
98
109
 
110
+ # Whether +word+ is what Thor would take as a task name: a task, a mapped
111
+ # name, or an abbreviation of either. Options and the gem's reserved
112
+ # `_` names are not.
113
+ def self.task_word?(word, tasks = Tasks)
114
+ !word.start_with?("-", "_") && tasks.send(:find_command_possibilities, word).any?
115
+ end
116
+
99
117
  # Main entry point invoked by the asgard executable.
100
118
  def self.run!(argv)
101
119
  answer_flags(argv)
102
120
  boot(argv)
103
121
  Tasks._reset_ran!
104
122
  pin_project_root(project_root)
105
- result = Tasks.start(argv)
123
+ result = Tasks.start(task_first(argv) { |word| task_word?(word) })
106
124
  # Quality-gate convention: a task signals failure by returning :fail
107
125
  # (see dev/quality.loki's *_check tasks). Surface that as a nonzero
108
126
  # exit so callers (CI, cross-repo runners) can rely on $?.
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: asgard
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.6.0
4
+ version: 0.6.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Dewayne VanHoozer
@@ -140,6 +140,7 @@ files:
140
140
  - lib/asgard/jobs/stopper.rb
141
141
  - lib/asgard/kernel_methods.rb
142
142
  - lib/asgard/leading_flag.rb
143
+ - lib/asgard/log.rb
143
144
  - lib/asgard/pid.rb
144
145
  - lib/asgard/schedule.rb
145
146
  - lib/asgard/schedule/commands.rb
@@ -171,6 +172,8 @@ metadata:
171
172
  homepage_uri: "https://github.com/madbomber/asgard"
172
173
  source_code_uri: "https://github.com/madbomber/asgard"
173
174
  changelog_uri: "https://github.com/madbomber/asgard/blob/main/CHANGELOG.md"
175
+ documentation_uri: "https://madbomber.github.io/asgard"
176
+ bug_tracker_uri: "https://github.com/madbomber/asgard/issues"
174
177
  rubygems_mfa_required: "true"
175
178
  rdoc_options: []
176
179
  require_paths: