asgard 0.5.1 → 0.6.0

data/lib/asgard/watch/state.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require "json"
-require "tempfile"
+require_relative "../state_dir"
 
 module Asgard
   module Watch
@@ -13,41 +12,61 @@ module Asgard
     # default ~/.local/state), with a file naming the project root so
     # `watcher list --all` can find every project without loading it.
     class State
-      ROOT_FILE = "root"
+      ROOT_FILE = StateDir::ROOT_FILE
+
+      # Names the inherited descriptor of the held watcher.lock, from
+      # `start` to the daemon it spawns and across a reload's exec.
+      LOCK_ENV = "ASGARD_WATCH_LOCK_FD"
+
+      # Names the file of changes a reloading daemon saw but did not run,
+      # for the daemon its exec starts to run instead.
+      PENDING_ENV = "ASGARD_WATCH_PENDING"
 
       attr_reader :dir, :root
 
       class << self
-        def base_dir(home: Dir.home, env: ENV)
-          File.join(env["XDG_STATE_HOME"] || File.join(home, ".local", "state"), "asgard", "watch")
-        end
+        def base_dir(home: Dir.home, env: ENV) = StateDir.base_dir("watch", home:, env:)
 
         # Every project with a state directory under base, as [slug, root] pairs.
-        def all(base: base_dir)
-          Dir.glob(File.join(base, "*", ROOT_FILE)).map do |file|
-            [File.basename(File.dirname(file)), File.read(file).strip]
-          end
-        end
+        def all(base: base_dir) = StateDir.all(base:)
 
         # What `list` needs of a declaration, with the events Set as an Array.
         def declaration_record(spec) = spec.slice(:name, :task, :paths).merge(events: spec[:events].to_a)
 
         # Written whole then renamed, so a reader never sees a partial file.
-        def write_json(path, value)
-          dir = File.dirname(path)
-          FileUtils.mkdir_p(dir)
-          Tempfile.create(["asgard", ".json"], dir) do |file|
-            file.write(JSON.pretty_generate(value))
-            file.flush
-            File.rename(file.path, path)
-          end
+        def write_json(path, value) = StateDir.write_json(path, value)
+
+        def read_json(path) = StateDir.read_json(path)
+
+        # The pending triggers a reload left at +path+ ([{ entry:, changes: }]),
+        # removing the file so they run once; [] for no path or no file.
+        def take_pending(path)
+          return [] unless path
+
+          pending = read_json(path) || []
+          FileUtils.rm_f(path)
+          pending
         end
 
-        def read_json(path) = File.exist?(path) ? JSON.parse(File.read(path), symbolize_names: true) : nil
+        # Whether pid is a watcher daemon, not merely a live process.
+        def daemon?(pid) = Reporter.asgard_process?(pid, "watcher", "run")
 
         # Whether an entry record describes a task still running: no exit
-        # recorded and its pid alive.
-        def running?(entry) = !entry.key?(:finished) && Reporter.alive?(entry[:pid])
+        # recorded and its pid still that task's asgard process. The
+        # current process always counts, as for asgard_process?.
+        def running?(entry)
+          return false if entry.key?(:finished)
+
+          pid = entry[:pid]
+          pid == Process.pid || task_process?(entry[:task].to_s, command: Pid.command_line(pid))
+        end
+
+        # Whether +command+ (a command line, or nil for no process) runs
+        # asgard with +task+ as a whole word: "t" is not "test_check".
+        def task_process?(task, command:)
+          words = command.to_s.split
+          words.any? { |word| File.basename(word) == "asgard" } && words.include?(task)
+        end
       end
 
       # base: is the directory every project's state lives under.
@@ -57,33 +76,74 @@ module Asgard
       end
 
       def pid_path          = File.join(dir, "watcher.pid")
+      def lock_path         = File.join(dir, "watcher.lock")
       def log_path          = File.join(dir, "watcher.log")
       def root_path         = File.join(dir, ROOT_FILE)
       def declarations_path = File.join(dir, "declarations.json")
+      def pending_path      = File.join(dir, "pending.json")
       def entries_dir       = File.join(dir, "entries")
       def entry_path(name)  = File.join(entries_dir, "#{name}.json")
 
       # Creates the directories and records the root.
       def prepare
+        StateDir.record_root(dir, root)
         FileUtils.mkdir_p(entries_dir)
-        File.write(root_path, "#{root}\n")
         self
       end
 
+      # One watcher per project: whoever holds an exclusive flock on
+      # watcher.lock. The open File while held, nil when another process
+      # holds it. The lock ends when the last descriptor of this open
+      # closes, so a daemon that inherits it keeps it for its lifetime.
+      # The descriptor is close-on-exec: only `start` and a reload hand it
+      # on, by name (see LOCK_ENV); a task the daemon spawns, and anything
+      # that task leaves running, never holds it.
+      def acquire_lock
+        FileUtils.mkdir_p(dir)
+        file = File.open(lock_path, File::RDWR | File::CREAT, 0o600) # rubocop:disable Style/FileOpen -- held, not read
+        file.close_on_exec = true
+        return file if file.flock(File::LOCK_EX | File::LOCK_NB)
+
+        file.close
+        nil
+      end
+
+      # The lock a parent handed down (see LOCK_ENV), or nil when none was
+      # or the descriptor is not this project's lock file. Handing it down
+      # cleared close-on-exec, so it is set again here: otherwise every
+      # task spawned would inherit the lock and could outlive the daemon
+      # holding it.
+      def adopt_lock(env = ENV)
+        fd = Integer(env[LOCK_ENV].to_s, exception: false) or return nil
+        io = File.for_fd(fd, autoclose: false)
+        return nil unless File.exist?(lock_path) && File.identical?(io, lock_path) && io.flock(File::LOCK_EX | File::LOCK_NB)
+
+        io.autoclose     = true
+        io.close_on_exec = true
+        io
+      rescue Errno::EBADF, ArgumentError
+        nil
+      end
+
+      # The inherited lock, else a fresh one; nil when another holds it.
+      def lock(env = ENV) = adopt_lock(env) || acquire_lock
+
       def write_pid(pid) = File.write(pid_path, "#{pid}\n")
 
       def read_pid = File.exist?(pid_path) ? File.read(pid_path).to_i : nil
 
       # The daemon's pid when one is running, else nil. A pidfile left by a
-      # crash counts as not running.
+      # crash counts as not running, even when another process has since
+      # been given its pid.
       def running_pid
         pid = read_pid
-        pid if pid&.positive? && Reporter.alive?(pid)
+        pid if pid&.positive? && State.daemon?(pid)
       end
 
       def clear = FileUtils.rm_f(pid_path)
 
-      # The declarations at start time, trimmed to what `list` shows.
+      # The declarations of the running daemon (written by every `watcher
+      # run`, a reload included), trimmed to what `list` shows.
       def write_declarations(specs)
         State.write_json(declarations_path, specs.map { |spec| State.declaration_record(spec) })
       end
@@ -95,7 +155,13 @@ module Asgard
       def read_entry(name) = State.read_json(entry_path(name))
 
       # Every entry's latest record, keyed by entry name.
-      def entries = Dir.glob(File.join(entries_dir, "*.json")).to_h { |file| [File.basename(file, ".json"), State.read_json(file)] }
+      # A corrupt record is left out (see StateDir.read_json).
+      def entries
+        Dir.glob(File.join(entries_dir, "*.json")).filter_map do |file|
+          record = State.read_json(file)
+          [File.basename(file, ".json"), record] if record
+        end.to_h
+      end
 
       # The records of tasks still running.
       def running_entries = entries.values.select { |entry| State.running?(entry) }

data/lib/asgard/watch/worker.rb

@@ -17,10 +17,14 @@ module Asgard
         # The child's pid. The task runs in the project root with exactly
         # the description's environment, in its own process group, with
         # its output appended to the log.
-        def spawn(description)
-          Process.spawn(description[:env], *description[:argv],
-                        chdir: description[:root], pgroup: true, unsetenv_others: true,
-                        out: [description[:log], "a"], err: %i[child out])
+        def spawn(description) = Process.spawn(description[:env], *description[:argv], **spawn_options(description))
+
+        # stdin is /dev/null: the task's group is a background group on any
+        # terminal the daemon has, where a read would stop it with SIGTTIN
+        # and leave its worker waiting forever.
+        def spawn_options(description)
+          { chdir: description[:root], pgroup: true, unsetenv_others: true, in: File::NULL,
+            out: [description[:log], "a"], err: %i[child out] }
         end
 
         # Blocks until the child exits; its exit code.
@@ -30,13 +34,17 @@ module Asgard
         end
 
         # A signalled child reports 128 + the signal number, as shells do.
-        def exit_code(status) = status.exitstatus || (128 + status.termsig)
+        def exit_code(status) = Shell.exit_code(status)
       end
 
-      # The worker loop in its own Ractor. The Ractor is handed the two
-      # queues and the spawner (all shareable) and nothing else.
+      # The worker loop in its own Ractor. The Ractor is handed its queue,
+      # the reports and the spawner (all shareable) and nothing else, and
+      # pops through a Mailbox so it sleeps while idle: whoever pushes onto
+      # +queue+ must wake it, through Mailbox.new(queue, the_ractor).
       def self.start(queue, reports, spawner: Spawner)
-        Ractor.new(queue, reports, spawner) { |inbox, outbox, runner| Asgard::Watch::Worker.new(inbox, outbox, spawner: runner).run }
+        Ractor.new(queue, reports, spawner) do |inbox, outbox, runner|
+          Asgard::Watch::Worker.new(Asgard::Watch::Mailbox.new(inbox, Ractor.current), outbox, spawner: runner).run
+        end
       end
 
       def initialize(queue, reports, spawner: Spawner, clock: Process)
@@ -54,18 +62,45 @@ module Asgard
         end
       end
 
+      # One trigger. A spawn that fails (the root or the executable gone,
+      # an environment too large or malformed) is reported as an exit with
+      # no pid, so the worker carries on with the next trigger instead of
+      # ending.
       def run_one(description)
         entry, task = description.values_at(:entry, :task)
-        pid = @spawner.spawn(description)
+        pid = spawn_or_report(description) or return
         started_at, started = stamp
         report(kind: :spawn, entry:, task:, pid:, at: started_at, changes: description[:changes])
         status = @spawner.wait(pid)
         finished_at, finished = stamp
         report(kind: :exit, entry:, task:, pid:, at: finished_at, status:, seconds: finished - started)
+      ensure
+        Worker.remove_changes_file(description[:changes_file])
+      end
+
+      # The exit code a spawn failure reports, as a shell would: 126 when
+      # the system could not run it, 127 when something was not found or
+      # spawn refused its arguments (an ArgumentError: a bad env: name).
+      def self.spawn_failure_status(error) = error.is_a?(SystemCallError) && !error.is_a?(Errno::ENOENT) ? 126 : 127
+
+      # The task has exited, so the change lists spilled for it are done.
+      def self.remove_changes_file(path)
+        File.delete(path) if path
+      rescue Errno::ENOENT
+        nil
       end
 
       private
 
+      def spawn_or_report(description)
+        @spawner.spawn(description)
+      rescue StandardError => e
+        at, = stamp
+        report(kind: :exit, entry: description[:entry], task: description[:task], pid: nil, at:,
+               status: Worker.spawn_failure_status(e), seconds: 0.0, error: e.message)
+        nil
+      end
+
       # [wall-clock seconds since the epoch, monotonic seconds]
       def stamp = [@clock.clock_gettime(Process::CLOCK_REALTIME), @clock.clock_gettime(Process::CLOCK_MONOTONIC)]
 

data/lib/asgard/watch.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "declarations"
 require_relative "watch/declaration"
 require_relative "watch/changes"
 require_relative "watch/spawn"
+require_relative "watch/mailbox"
 require_relative "watch/worker"
 require_relative "watch/reporter"
 require_relative "watch/dispatcher"
@@ -30,17 +32,8 @@ module Asgard
         @declarations ||= {}
       end
 
-      # Records one declaration. Redeclaring an identical entry is a no-op
-      # (a .loki file loaded twice); a different entry under the same name
-      # is an error.
-      def declare(task, **settings)
-        spec  = normalize(task, **settings)
-        name  = spec[:name]
-        taken = declarations[name]
-        raise ArgumentError, "watch: #{name.inspect} is already declared; give one a distinct as: name" if taken && taken != spec
-
-        declarations[name] = spec
-      end
+      # Records one declaration (see Declarations.record).
+      def declare(task, **) = Declarations.record(declarations, normalize(task, **), "watch")
     end
 
     # The class-level `watch` declaration helper for Tasks.

data/lib/asgard.rb

@@ -2,6 +2,7 @@
 
 require_relative "asgard/errors"
 require_relative "asgard/version"
+require_relative "asgard/leading_flag"
 require_relative "asgard/kernel_methods"
 require_relative "asgard/shell"
 require_relative "asgard/base"
@@ -15,29 +16,92 @@ module Asgard
     loki_up
   end
 
-  # `asgard schedule list` and `asgard watcher list` report every project's
-  # entries, so they work from a directory with no .loki above it.
-  def self.machine_wide?(argv) = [%w[schedule list], %w[watcher list]].include?(argv.first(2))
+  # The directory of the nearest .loki, or the current directory without
+  # one: where the watcher and background jobs file their state. Fixed
+  # for the length of a run! (see pin_project_root), so a task that
+  # changes directory first still files its jobs under this project.
+  def self.project_root = @project_root || File.realpath((find_task_file&.dirname || Dir.pwd).to_s)
 
-  # Main entry point invoked by the asgard executable.
-  def self.run!(argv)
+  def self.pin_project_root(root) = @project_root = root
+
+  # Whether an import path, as written, is a glob pattern.
+  def self.glob?(path) = path.match?(/[*?\[{]/)
+
+  # +path+ with every glob metacharacter escaped, so Dir.glob matches it
+  # literally: a project in "glob[1]" still finds its own files.
+  def self.glob_escape(path) = path.to_s.gsub(/[\\*?\[\]{}]/) { "\\#{it}" }
+
+  # `asgard schedule list`, `asgard watcher list` and `asgard jobs list`
+  # report every project's entries, so they work from a directory with no
+  # .loki above it.
+  def self.machine_wide?(argv) = [%w[schedule list], %w[watcher list], %w[jobs list], %w[jobs]].include?(argv.first(2))
+
+  # The root .loki is loaded directly rather than through `import`, so
+  # record it the way import would. Otherwise an `import_up` in a child
+  # file finds the root, reloads it, and the two import each other without
+  # end.
+  def self.load_root(path)
+    path = File.expand_path(path.to_s)
+    $LOADED_FEATURES << path unless $LOADED_FEATURES.include?(path)
+    load path
+  end
+
+  # A frame of the backtrace inside a task file: "/proj/.loki:12" from
+  # "/proj/.loki:12:in '<class:Tasks>'".
+  LOKI_FRAME = /\A(.*?\.loki:\d+)/
+
+  # One line for an error raised while the task files load: the nearest
+  # .loki location, the message's first line and the class. A SyntaxError
+  # names its own location in its message, so that is used as is.
+  def self.load_error_message(error)
+    first = error.message.lines.first.to_s.strip
+    return "#{first} (#{error.class})" if error.is_a?(SyntaxError) && first.match?(LOKI_FRAME)
+
+    where = Array(error.backtrace).lazy.filter_map { |frame| frame[LOKI_FRAME, 1] }.first
+    [where, "#{first} (#{error.class})"].compact.join(": ")
+  end
+
+  # Loads the task files; anything they raise ends asgard with one line
+  # (see load_error_message), or the full backtrace with ASGARD_TRACE set.
+  def self.load_tasks(task_file)
+    load_root(task_file) if task_file
+  rescue Error
+    raise
+  rescue ScriptError, StandardError => e
+    raise if ENV["ASGARD_TRACE"]
+
+    abort "asgard: #{load_error_message(e)}"
+  end
+
+  # --version and --doctor answer and exit before any task file loads.
+  def self.answer_flags(argv)
     first = argv.first
     abort "asgard: unknown command '#{first}'" if first&.start_with?("_")
-    if argv.include?("--version")
+    if leading_flag?(argv, "--version")
       puts Asgard::VERSION
       exit
     end
-    if argv.include?("--doctor")
-      Asgard::Doctor.new.run
-      exit
-    end
+    return unless leading_flag?(argv, "--doctor")
+
+    Asgard::Doctor.new.run
+    exit
+  end
+
+  # Finds and loads the task files and checks every class they defined.
+  def self.boot(argv)
     task_file = find_task_file
     abort "asgard: no .loki file found in #{Dir.pwd}" unless task_file || machine_wide?(argv)
-    before = Asgard::Base.subclasses.dup
-    load task_file if task_file
-    newly_defined = Asgard::Base.subclasses - before
-    (newly_defined + [Tasks]).uniq.each(&:validate_deps!)
+    before = Asgard::Base._asgard_subclasses.dup
+    load_tasks(task_file)
+    ((Asgard::Base._asgard_subclasses - before) + [Tasks]).uniq.each(&:validate_deps!)
+  end
+
+  # Main entry point invoked by the asgard executable.
+  def self.run!(argv)
+    answer_flags(argv)
+    boot(argv)
     Tasks._reset_ran!
+    pin_project_root(project_root)
     result = Tasks.start(argv)
     # Quality-gate convention: a task signals failure by returning :fail
     # (see dev/quality.loki's *_check tasks). Surface that as a nonzero
@@ -50,5 +114,7 @@ module Asgard
     abort "asgard: #{e.message}"
   rescue Interrupt
     exit(130)
+  ensure
+    pin_project_root(nil)
   end
 end