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
@@ -0,0 +1,195 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "fileutils"
4
+ require_relative "../pid"
5
+ require_relative "../state_dir"
6
+
7
+ module Asgard
8
+ module Jobs
9
+ # Where one project's jobs keep what outlives the asgard run that
10
+ # started them, under $XDG_STATE_HOME/asgard/jobs/<project-slug>/:
11
+ # per job name a JSON record, the script as handed to the shell, the
12
+ # log, and the exit status the trampoline writes when the job ends.
13
+ # Everything stays until the next start of that name or `jobs clean`,
14
+ # so the log of a crashed job can still be read.
15
+ class State
16
+ # A job's record: a chosen name (\w+) or a sequenced "<task>-<N>".
17
+ # Dotfiles never match, which is how a half-written tempfile stays out.
18
+ RECORD = /\A[\w-]+\.json\z/
19
+
20
+ attr_reader :dir, :root
21
+
22
+ class << self
23
+ def base_dir(home: Dir.home, env: ENV) = StateDir.base_dir("jobs", home:, env:)
24
+
25
+ # Every project with job state under base, as [slug, root] pairs.
26
+ def all(base: base_dir) = StateDir.all(base:)
27
+
28
+ # Whether a record's job is still the process we started: its pid
29
+ # is alive and runs the trampoline whose command line carries the
30
+ # script path. A reused pid after a reboot fails this, and so does
31
+ # one that is now asgard itself, and so does a record that is not
32
+ # a job's (Jobs.valid_record?). Once the trampoline has written the
33
+ # status (not just opened the file) its pid no longer counts, though
34
+ # its shell may not have exited yet; ps asks first, so a status
35
+ # written in between is still seen. A ps that cannot tell raises
36
+ # Pid::Unusable rather than calling every job gone.
37
+ def verified?(record)
38
+ return false unless Jobs.valid_record?(record)
39
+
40
+ Pid.require_ps!
41
+ trampoline = Pid.matches?(record[:pid], record[:script], self_ok: false) && !File.size?(status_file(record))
42
+ trampoline || survives?(record)
43
+ end
44
+
45
+ # Whether the script still runs apart from the trampoline: some
46
+ # other process in its group carries the script path (the script's
47
+ # shell, or a subshell it backgrounded). A group id is never reused
48
+ # while the group has members, so a match is still the job we started.
49
+ def survives?(record, ps: Pid.method(:group_processes))
50
+ pgid = record[:pgid]
51
+ script = record[:script].to_s
52
+ return false unless job_group?(pgid) && !script.empty?
53
+
54
+ ps.call(pgid).any? { |member| member.pid != record[:pid] && member.command.include?(script) }
55
+ end
56
+
57
+ # Whether +pgid+ could be a job's group at all: a group id above 1
58
+ # that is not asgard's own. Nothing else is ever looked up or
59
+ # signalled.
60
+ def job_group?(pgid) = Jobs.process_id?(pgid) && pgid != Process.getpgrp
61
+
62
+ # Whether the job still owns processes: it is running, or its
63
+ # script exited and left processes in its group (`sleep 60 &`).
64
+ # Those are what `stop` signals and why `clean` keeps the record.
65
+ def active?(record) = verified?(record) || (Jobs.valid_record?(record) && leftovers?(record, exited_at: exited_at(record)))
66
+
67
+ # Whether group +pgid+ still holds a process that started before
68
+ # the trampoline exited at +exited_at+. The id cannot be reused
69
+ # while the group has members, but once they are gone a later
70
+ # group may take it, and every member of such a group is younger
71
+ # than our exit; one second of slack covers ps's resolution.
72
+ def leftovers?(record, exited_at:, ps: Pid.method(:group_processes))
73
+ pgid = record[:pgid]
74
+ return false unless exited_at && job_group?(pgid)
75
+
76
+ ps.call(pgid).any? { |member| member.started <= exited_at + 1 }
77
+ end
78
+
79
+ # The status file of a record's job, beside its script.
80
+ def status_file(record) = File.join(File.dirname(record[:script]), "#{record[:name]}.status")
81
+
82
+ # When the trampoline wrote the job's status, or nil.
83
+ def exited_at(record) = mtime_of(status_file(record))
84
+
85
+ # When +path+ was last written, or nil when it does not exist.
86
+ def mtime_of(path) = File.exist?(path) ? File.mtime(path) : nil
87
+
88
+ # Writes 137 (128 + KILL) as the job's status unless one is
89
+ # written: a group KILL takes the trampoline with it, so nothing
90
+ # else records how the job ended. A record that is not a job's
91
+ # writes nothing.
92
+ def record_kill(record)
93
+ return unless Jobs.valid_record?(record)
94
+
95
+ File.open(status_file(record), "wx", 0o600) { |file| file.puts(128 + 9) }
96
+ rescue Errno::EEXIST, Errno::ENOENT
97
+ nil
98
+ end
99
+ end
100
+
101
+ def initialize(project:, root:, base: State.base_dir)
102
+ @root = root
103
+ @dir = File.join(base, Schedule.slug(project))
104
+ end
105
+
106
+ def record_path(name) = File.join(dir, "#{name}.json")
107
+ def script_path(name, ext) = File.join(dir, "#{name}#{ext}")
108
+ def log_path(name) = File.join(dir, "#{name}.log")
109
+ def status_path(name) = File.join(dir, "#{name}.status")
110
+ def lock_path(name) = File.join(dir, ".#{name}.lock")
111
+
112
+ # Runs the block holding an exclusive flock for +name+, so two starts
113
+ # of one name (two terminals, two parallel dependencies) take turns:
114
+ # the second sees the first's record and finds the job running. The
115
+ # lock file is a dotfile, so RECORD and `remove` never see it.
116
+ def with_lock(name)
117
+ FileUtils.mkdir_p(dir)
118
+ File.open(lock_path(name), File::RDWR | File::CREAT, 0o600) do |file|
119
+ file.flock(File::LOCK_EX)
120
+ yield
121
+ end
122
+ end
123
+
124
+ # Creates the directory and records the root.
125
+ def prepare
126
+ StateDir.record_root(dir, root)
127
+ self
128
+ end
129
+
130
+ def write_record(record) = StateDir.write_json(record_path(record[:name]), record)
131
+
132
+ # The record for +name+, or nil when there is none or it is not a
133
+ # job's record (Jobs.valid_record?).
134
+ def read_record(name) = StateDir.read_json(record_path(name)).then { Jobs.valid_record?(it) ? it : nil }
135
+
136
+ # Every job's record, oldest start first. Only "<name>.json" counts,
137
+ # never the dot-prefixed tempfile write_json is still filling, and a
138
+ # file that is not a job's record is left out (see invalid_records).
139
+ def records
140
+ record_files.filter_map { |path| StateDir.read_json(path) }.select { |record| Jobs.valid_record?(record) }
141
+ .sort_by { |record| [record[:started], record[:name]] }
142
+ end
143
+
144
+ # The record files that are not a job's record: unparsable JSON, a
145
+ # hand edit, another tool's file.
146
+ def invalid_records = record_files.reject { |path| Jobs.valid_record?(StateDir.read_json(path)) }
147
+
148
+ def record_files
149
+ Dir.children(dir).grep(RECORD).sort.map { |file| File.join(dir, file) }
150
+ rescue Errno::ENOENT
151
+ []
152
+ end
153
+
154
+ def verified?(record) = State.verified?(record)
155
+
156
+ def active?(record) = State.active?(record)
157
+
158
+ # Forgets +name+ (record, script, status and log) unless its job
159
+ # still owns processes; true when it did. Holds the start lock and
160
+ # reads the record again inside it, so a start that ran meanwhile
161
+ # keeps the fresh record it wrote. A record that is not a job's is
162
+ # forgotten too: it cannot be running.
163
+ def forget_unless_active(name)
164
+ with_lock(name) do
165
+ next false unless File.exist?(record_path(name))
166
+
167
+ record = read_record(name)
168
+ next false if record && active?(record)
169
+
170
+ remove(name, keep_log: false)
171
+ true
172
+ end
173
+ end
174
+
175
+ # The exit code the trampoline wrote, or nil while none is written.
176
+ def exit_code(name)
177
+ path = status_path(name)
178
+ Integer(File.read(path).strip, exception: false) if File.exist?(path)
179
+ end
180
+
181
+ # When the status was written, or nil.
182
+ def exit_time(name) = State.mtime_of(status_path(name))
183
+
184
+ # Forgets a job: its record, script and status go; the log is kept
185
+ # but emptied, so a restart appends to a fresh file, unless
186
+ # keep_log: false deletes it too (`jobs clean`).
187
+ def remove(name, keep_log: true)
188
+ log = log_path(name)
189
+ files = Dir.exist?(dir) ? Dir.children(dir).select { |file| file.start_with?("#{name}.") }.map { |file| File.join(dir, file) } : []
190
+ FileUtils.rm_f(keep_log ? files - [log] : files)
191
+ File.truncate(log, 0) if keep_log && File.exist?(log)
192
+ end
193
+ end
194
+ end
195
+ end
@@ -0,0 +1,141 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Asgard
4
+ module Jobs
5
+ # Ends one job: TERM to its process group, a poll every 0.2s for up to
6
+ # the grace period, then KILL and a wait until the group holds none of
7
+ # the job's processes. The signal sender, the liveness check and
8
+ # sleep are injectable so the timing branches test without waiting.
9
+ class Stopper
10
+ POLL = 0.2
11
+ TIMEOUT = 10
12
+ WARN_AFTER = 1.0
13
+ RESEND_EVERY = 1.0
14
+
15
+ # A negative pid addresses a group, and kill(2) gives -1 and 0 their
16
+ # own meanings: every process the user owns, and the caller's own
17
+ # group. A record that is corrupt or hand-written must never turn
18
+ # into either, so only a real group id (above 1) is ever signalled.
19
+ #
20
+ # A valid id is still refused (false) when it is our own group, or
21
+ # when no process leads it any more: a job's pgid is its trampoline's
22
+ # pid, so a group whose leader is gone or moved is not the job. So is
23
+ # a group we may not signal (EPERM): its id now belongs to another
24
+ # user's processes. +kill+ is Process.kill, injectable for tests.
25
+ def self.signal_group(signal, pgid, own_pgrp: Process.getpgrp, pgid_of: Process.method(:getpgid),
26
+ kill: Process.method(:kill))
27
+ unless pgid.is_a?(Integer) && pgid > 1
28
+ raise ArgumentError,
29
+ "refusing to signal process group #{pgid.inspect}: not a group id above 1"
30
+ end
31
+ return false unless led_or_orphaned?(pgid, own_pgrp:, pgid_of:, kill:)
32
+
33
+ kill.call(signal, -pgid)
34
+ rescue Errno::ESRCH
35
+ nil
36
+ rescue Errno::EPERM
37
+ false
38
+ end
39
+
40
+ # A group may be signalled when its leader (the trampoline) still
41
+ # leads it, or when the leader is gone but members remain: then the
42
+ # id cannot have been reused. Never our own group, and never one we
43
+ # may not signal (EPERM). ESRCH from the group check means nobody is
44
+ # left: nil from signal_group.
45
+ def self.led_or_orphaned?(pgid, own_pgrp:, pgid_of:, kill: Process.method(:kill))
46
+ return false if pgid == own_pgrp
47
+
48
+ leader_group = begin
49
+ pgid_of.call(pgid)
50
+ rescue Errno::ESRCH
51
+ kill.call(0, -pgid) # members without their leader, or ESRCH
52
+ pgid
53
+ end
54
+ safe_group?(pgid, pid: pgid, own_pgrp:, pgid_of: ->(_) { leader_group })
55
+ rescue Errno::EPERM
56
+ false
57
+ end
58
+
59
+ # Whether +pgid+ may be signalled as the group +pid+ leads: a group id
60
+ # above 1, not our own, and still the group +pid+ belongs to.
61
+ def self.safe_group?(pgid, pid:, own_pgrp:, pgid_of:)
62
+ return false unless pgid.is_a?(Integer) && pgid > 1 && pgid != own_pgrp
63
+
64
+ pgid_of.call(pid) == pgid
65
+ rescue Errno::ESRCH, Errno::EPERM
66
+ false
67
+ end
68
+
69
+ # +alive+ is State.active?: a job whose script exited still counts
70
+ # while processes it left run in its group, and ps has confirmed
71
+ # they are there before any signal goes out.
72
+ def initialize(timeout: TIMEOUT, poll: POLL, out: $stdout,
73
+ alive: State.method(:active?), signal: Stopper.method(:signal_group), sleeper: Kernel.method(:sleep))
74
+ @timeout = timeout
75
+ @poll = poll
76
+ @out = out
77
+ @alive = alive
78
+ @signal = signal
79
+ @sleeper = sleeper
80
+ end
81
+
82
+ # :stopped when TERM ended the job within the grace period, :killed
83
+ # when KILL had to, :not_running when there was nothing to stop. A
84
+ # KILL takes the trampoline too, so the 137 is recorded here (a
85
+ # record that is not a job's, as the timing tests use, writes none).
86
+ def stop(record)
87
+ return :not_running unless @alive.call(record)
88
+
89
+ @signal.call("TERM", record[:pgid])
90
+ return :stopped if exited?(record, resend: "TERM")
91
+
92
+ @signal.call("KILL", record[:pgid])
93
+ State.record_kill(record) if exited?(record)
94
+ :killed
95
+ end
96
+
97
+ # Whether poll number +tick+ (from 0) re-sends TERM: once every
98
+ # RESEND_EVERY seconds. A TERM that reached the trampoline's child
99
+ # between its fork and its exec met the inherited trap and was lost;
100
+ # by the next one the child runs the job with the default handler.
101
+ def self.resend_tick?(tick, poll:)
102
+ every = (RESEND_EVERY / poll).round
103
+ tick.positive? && (tick % every).zero?
104
+ end
105
+
106
+ # Stops and reports one job; the outcome as above.
107
+ def stop_and_report(record)
108
+ outcome = stop(record)
109
+ @out.puts report_line(outcome, record)
110
+ outcome
111
+ end
112
+
113
+ def report_line(outcome, record)
114
+ name, pid = record.values_at(:name, :pid)
115
+ case outcome
116
+ when :stopped then "stopped #{name} (pid #{pid})"
117
+ when :killed then "killed #{name} (pid #{pid}) after #{@timeout}s"
118
+ else "#{name} is not running"
119
+ end
120
+ end
121
+
122
+ private
123
+
124
+ # True once the job is gone, false when the grace period ran out.
125
+ # Says what it is waiting for once, when the wait reaches a second
126
+ # (or its last poll, for a shorter grace period).
127
+ def exited?(record, resend: nil)
128
+ ticks = (@timeout / @poll).ceil
129
+ warn_tick = [(WARN_AFTER / @poll).round, ticks].min - 1
130
+ ticks.times do |tick|
131
+ return true unless @alive.call(record)
132
+
133
+ @signal.call(resend, record[:pgid]) if resend && Stopper.resend_tick?(tick, poll: @poll)
134
+ @sleeper.call(@poll)
135
+ @out.puts "waiting for #{record[:name]} (pid #{record[:pid]})" if tick == warn_tick
136
+ end
137
+ !@alive.call(record)
138
+ end
139
+ end
140
+ end
141
+ end
@@ -0,0 +1,25 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "jobs/declaration"
4
+ require_relative "jobs/state"
5
+ require_relative "jobs/launcher"
6
+ require_relative "jobs/stopper"
7
+ require_relative "jobs/commands"
8
+
9
+ module Asgard
10
+ # Background jobs started from a task body:
11
+ #
12
+ # class Tasks
13
+ # def doc_server = sh "mkdocs serve", background: true # doc_server-1
14
+ # def servers
15
+ # sh "docker compose up postgres", background: true # servers-1
16
+ # sh "bin/rails server", background: :api # api
17
+ # end
18
+ # end
19
+ #
20
+ # then manage them with `asgard jobs list|stop|log|restart|clean`.
21
+ module Jobs
22
+ # A job could not be managed: an unknown name, no owning task.
23
+ class Error < Asgard::Error; end
24
+ end
25
+ end
@@ -1,7 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require "pathname"
4
-
3
+ # Every helper defined here is also in Asgard::Base::KERNEL_HELPERS, so a
4
+ # task or helper by its name is refused rather than hiding it.
5
5
  module Kernel
6
6
  def debug? = $DEBUG
7
7
  def verbose? = $VERBOSE
@@ -22,16 +22,10 @@ module Kernel
22
22
  def changes = Asgard::Changes.current
23
23
  module_function :changes
24
24
 
25
+ # The nearest +name+ in the current directory or an ancestor, as a
26
+ # Pathname, or nil. A directory by that name is not it.
25
27
  def loki_up(name = ".loki")
26
- dir = Pathname.new(Dir.pwd)
27
- loop do
28
- candidate = dir + name
29
- return candidate if candidate.exist?
30
- parent = dir.parent
31
- break if parent == dir
32
- dir = parent
33
- end
34
- nil
28
+ Pathname.new(Dir.pwd).ascend.map { it + name }.find(&:file?)
35
29
  end
36
30
  module_function :loki_up
37
31
 
@@ -39,40 +33,41 @@ module Kernel
39
33
  # defaults to the immediate caller, but is exposed as a keyword so a
40
34
  # wrapper (e.g. Asgard::Doctor's import tracer, prepended via `super`)
41
35
  # can thread through the *real* caller instead of its own frame.
36
+ #
37
+ # Only +path+ as written decides whether it is a glob. The caller's
38
+ # directory is the glob's base, never part of the pattern, so a project
39
+ # directory named like a glob ("glob[1]") does not change what matches.
42
40
  def import(path, from: caller_locations(1, 1).first)
43
41
  path = path.to_s
44
42
  raise ArgumentError, "import: path must end with .loki (got #{path.inspect})" unless path.end_with?(".loki")
45
- unless File.absolute_path?(path)
46
- caller_dir = File.dirname(from.absolute_path)
47
- path = File.expand_path(path, caller_dir)
48
- end
49
- paths = path =~ /[*?\[{]/ ? Dir.glob(path) : [path]
50
- loaded = paths.map do |p|
43
+ base = File.dirname(from.absolute_path) unless File.absolute_path?(path)
44
+ paths = Asgard.glob?(path) ? Dir.glob(path, base:) : [path]
45
+ loaded = paths.map { File.expand_path(it, base) }.map do |p|
51
46
  if $LOADED_FEATURES.include?(p)
52
47
  warn "import: skip #{p} (already loaded)" if debug?
53
48
  next false
54
49
  end
55
50
  warn "import: #{p}" if verbose? || debug?
56
- load p
51
+ # Recorded before it loads, as Asgard.load_root does, so two files
52
+ # that import each other each load once instead of without end.
57
53
  $LOADED_FEATURES << p
54
+ load p
58
55
  true
59
56
  end
60
57
  loaded.any?
61
58
  end
62
59
  module_function :import
63
60
 
61
+ # The paths found are handed to import escaped: the directory they sit
62
+ # in is part of a path, not a pattern.
64
63
  def import_up(name = ".loki")
65
- if name =~ /[*?\[{]/
66
- dir = Dir.pwd
67
- loop do
68
- matches = Dir.glob(File.join(dir, name))
69
- unless matches.empty?
70
- warn "import_up: #{name} → #{dir}" if verbose? || debug?
71
- return matches.map { |p| import(p) }.any?
72
- end
73
- parent = File.dirname(dir)
74
- break if parent == dir
75
- dir = parent
64
+ if Asgard.glob?(name)
65
+ Pathname.new(Dir.pwd).ascend do |dir|
66
+ matches = Dir.glob(name, base: dir)
67
+ next if matches.empty?
68
+
69
+ warn "import_up: #{name} → #{dir}" if verbose? || debug?
70
+ return matches.map { |p| import(Asgard.glob_escape(File.join(dir, p))) }.any?
76
71
  end
77
72
  warn "import_up: #{name} not found" if debug?
78
73
  return false
@@ -83,7 +78,7 @@ module Kernel
83
78
  return false
84
79
  end
85
80
  warn "import_up: #{name} → #{path}" if verbose? || debug?
86
- import path
81
+ import Asgard.glob_escape(path)
87
82
  end
88
83
  module_function :import_up
89
84
  end
@@ -0,0 +1,26 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Loaded alone by bin/asgard to answer --version before Thor loads, so it
4
+ # requires nothing.
5
+ module Asgard
6
+ # Whether +flag+ is one of asgard's own options: among the options
7
+ # before the first word that is not one (the task name). After it, the
8
+ # word belongs to the task, which may take --version as an argument.
9
+ def self.leading_flag?(argv, flag) = argv.take_while { |word| word.start_with?("-") }.include?(flag)
10
+
11
+ # The options that set a global for whatever task runs, so they read the
12
+ # same on either side of the task name.
13
+ GLOBAL_FLAGS = %w[--debug --verbose].freeze
14
+
15
+ # +argv+ with the task name first: leading GLOBAL_FLAGS move behind the
16
+ # word they precede when the block says that word names a task. Thor
17
+ # hands a command line that starts with an option to the default task,
18
+ # so without this `asgard --verbose build` never reaches `build`.
19
+ def self.task_first(argv)
20
+ flags = argv.take_while { |word| GLOBAL_FLAGS.include?(word) }
21
+ word = argv[flags.size]
22
+ return argv if flags.empty? || word.nil? || !yield(word)
23
+
24
+ [word, *flags, *argv.drop(flags.size + 1)]
25
+ end
26
+ end
data/lib/asgard/log.rb ADDED
@@ -0,0 +1,90 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Asgard
4
+ # Keeps the last M lines of a log, rewriting it in place. Every writer
5
+ # (launchd, systemd's append:, jobs, the watcher) opens its log with
6
+ # O_APPEND, so it keeps writing to the same file at the new end. As with
7
+ # logrotate's copytruncate, a write landing between the last read and the
8
+ # truncate can be lost.
9
+ module Log
10
+ CHUNK = 64 * 1024
11
+
12
+ module_function
13
+
14
+ def line_count(value)
15
+ raise ArgumentError, "--lines must be a nonnegative integer" unless value.to_s.match?(/\A[0-9]+\z/)
16
+
17
+ Integer(value.to_s, 10)
18
+ end
19
+
20
+ # The byte offset where the last +lines+ lines of +io+ begin. Scans
21
+ # backwards in bounded chunks; a final newline ends the last line
22
+ # rather than starting an empty one.
23
+ def tail_offset(io, lines)
24
+ position = io.size
25
+ return position if lines.zero? || position.zero?
26
+
27
+ io.seek(-1, IO::SEEK_END)
28
+ remaining = lines + (io.read(1) == "\n" ? 1 : 0)
29
+ while position.positive?
30
+ length = [position, CHUNK].min
31
+ position -= length
32
+ io.seek(position)
33
+ chunk = io.read(length)
34
+ index = chunk.bytesize
35
+ while index.positive? && (index = chunk.rindex("\n", index - 1))
36
+ remaining -= 1
37
+ return position + index + 1 if remaining.zero?
38
+ end
39
+ end
40
+ 0
41
+ end
42
+
43
+ # Bytes removed (or that would be, with +dry_run+).
44
+ def truncate(path, lines:, dry_run: false)
45
+ File.open(path, dry_run ? "rb" : "r+b") do |file|
46
+ offset = tail_offset(file, lines)
47
+ rewrite(file, offset) unless dry_run || offset.zero?
48
+ offset
49
+ end
50
+ end
51
+
52
+ # Slides the bytes from +offset+ on to the start of +file+, a chunk at a
53
+ # time, then cuts the file after them. Each write lands behind the next
54
+ # read, so no copy is needed, and lines appended meanwhile move too.
55
+ # Signals and Thread#raise wait until the file is cut. A failed read or
56
+ # write still cuts the file after the bytes already moved, so it never
57
+ # holds the tail written over its own head.
58
+ def rewrite(file, offset)
59
+ moved = 0
60
+ Thread.handle_interrupt(Object => :never) do
61
+ while (chunk = read_at(file, offset + moved))
62
+ file.seek(moved)
63
+ file.write(chunk)
64
+ moved += chunk.bytesize
65
+ end
66
+ file.truncate(moved)
67
+ rescue StandardError
68
+ file.truncate(moved) if moved.positive?
69
+ raise
70
+ end
71
+ end
72
+
73
+ # Up to CHUNK bytes of +file+ from +position+, or nil at the end.
74
+ def read_at(file, position)
75
+ file.seek(position)
76
+ file.read(CHUNK)
77
+ end
78
+
79
+ def truncate_logs(paths, lines:, dry_run: false, out: $stdout)
80
+ count = line_count(lines)
81
+ found = paths.select { |path| File.file?(path) }.uniq.sort
82
+ return out.puts("No logs found for this project.") if found.empty?
83
+
84
+ found.each do |path|
85
+ bytes = truncate(path, lines: count, dry_run:)
86
+ out.puts "#{dry_run ? 'would truncate' : 'truncated'} #{path}: #{bytes} bytes #{dry_run ? 'would be removed' : 'removed'}"
87
+ end
88
+ end
89
+ end
90
+ end