gubbins-shell 0.1.0

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 (49) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +19 -0
  3. data/LICENSE +289 -0
  4. data/README.md +186 -0
  5. data/lib/gubbins/shell.rb +4 -0
  6. data/lib/shell/all.rb +34 -0
  7. data/lib/shell/base_64.rb +40 -0
  8. data/lib/shell/clam_av.rb +68 -0
  9. data/lib/shell/command.rb +1400 -0
  10. data/lib/shell/convert.rb +312 -0
  11. data/lib/shell/errors.rb +89 -0
  12. data/lib/shell/exiftool.rb +15 -0
  13. data/lib/shell/file.rb +84 -0
  14. data/lib/shell/ghostscript.rb +239 -0
  15. data/lib/shell/identify.rb +111 -0
  16. data/lib/shell/img2_pdf.rb +47 -0
  17. data/lib/shell/magick.rb +111 -0
  18. data/lib/shell/open_ssl.rb +26 -0
  19. data/lib/shell/optional_dependencies.rb +36 -0
  20. data/lib/shell/path.rb +40 -0
  21. data/lib/shell/pdf_detach.rb +86 -0
  22. data/lib/shell/pdffonts.rb +73 -0
  23. data/lib/shell/pdfimages.rb +48 -0
  24. data/lib/shell/pdfinfo.rb +79 -0
  25. data/lib/shell/pdftocairo.rb +24 -0
  26. data/lib/shell/pdftotext.rb +32 -0
  27. data/lib/shell/ping.rb +50 -0
  28. data/lib/shell/power_array.rb +42 -0
  29. data/lib/shell/seven_zip.rb +142 -0
  30. data/lib/shell/tesseract.rb +120 -0
  31. data/lib/shell/testing/mock/shell/clam_av.rb +12 -0
  32. data/lib/shell/testing/mock/shell/command.rb +241 -0
  33. data/lib/shell/testing/mock/shell/configurator.rb +223 -0
  34. data/lib/shell/testing/mock/shell/convert.rb +12 -0
  35. data/lib/shell/testing/mock/shell/file.rb +12 -0
  36. data/lib/shell/testing/mock/shell/ghostscript.rb +13 -0
  37. data/lib/shell/testing/mock/shell/identify.rb +11 -0
  38. data/lib/shell/testing/mock/shell/open_ssl.rb +11 -0
  39. data/lib/shell/testing/mock/shell/tesseract.rb +12 -0
  40. data/lib/shell/testing/mock/shell/unzip.rb +20 -0
  41. data/lib/shell/testing/mock/shell/zip.rb +11 -0
  42. data/lib/shell/testing.rb +15 -0
  43. data/lib/shell/tiff_2_pdf.rb +19 -0
  44. data/lib/shell/unzip.rb +137 -0
  45. data/lib/shell/version.rb +5 -0
  46. data/lib/shell/zbar.rb +123 -0
  47. data/lib/shell/zip.rb +52 -0
  48. data/lib/shell.rb +16 -0
  49. metadata +116 -0
@@ -0,0 +1,1400 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "open3"
4
+ require "pathname"
5
+ require "active_support"
6
+ require "active_support/core_ext/string/inflections"
7
+ require_relative "optional_dependencies"
8
+
9
+ module Shell
10
+ # `Shell::Command` allows you to create wrapper classes for executing shell commands
11
+ # with a simple DSL.
12
+ #
13
+ # This is what a minimal example looks like:
14
+ #
15
+ # ```ruby
16
+ # module Shell
17
+ # class Pgrep < Command
18
+ # command_path "/usr/bin/pgrep"
19
+ # end
20
+ # end
21
+ # ```
22
+ #
23
+ # This command can now be executed with `.exec`:
24
+ #
25
+ # ```ruby
26
+ # Shell::Pgrep.exec
27
+ # # => Command: /usr/bin/pgrep
28
+ # # PID: 38443
29
+ # # Status: 2 (failure)
30
+ # # Stdout: 0 Bytes
31
+ # # Sterr: 145 Bytes
32
+ # ```
33
+ #
34
+ # The return value of `.exec` is a `Shell::Command::Result`:
35
+ #
36
+ # ```ruby
37
+ # r = Shell::Pgrep.exec
38
+ # # => Command: /usr/bin/pgrep
39
+ # # PID: 38448
40
+ # # Status: 2 (failure)
41
+ # # Stdout: 0 Bytes
42
+ # # Sterr: 145 Bytes
43
+ # r.success?
44
+ # # => false
45
+ # r.failure?
46
+ # # => true
47
+ # r.status
48
+ # # => 2
49
+ # r.stdout
50
+ # # => ""
51
+ # r.stderr
52
+ # # => "usage: pgrep [-Lfilnoqvx] [-d delim] [-F pidfile] [-G gid]\n [...]"
53
+ # ```
54
+ #
55
+ # In addition to these methods, wrappers can use the `Result#value` attribute
56
+ # to return custom values:
57
+ #
58
+ # ```ruby
59
+ # r.value
60
+ # # => nil
61
+ # ```
62
+ #
63
+ # If desired, use `Result#raise_failures` to have your `Command` raise an exception
64
+ # on non-zero exit codes. `#raise_failures` returns `self` and is thus chainable:
65
+ #
66
+ # ```ruby
67
+ # value =
68
+ # Shell::Pgrep.exec
69
+ # .raise_failures
70
+ # .value
71
+ # ```
72
+ #
73
+ # ### Shell arguments, options and flags
74
+ #
75
+ # As a rule of thumb: arguments passed to `.exec` become positioned shell command arguments,
76
+ # keyword arguments become options or flags:
77
+ #
78
+ # ```ruby
79
+ # Shell::Pgrep.exec "rails", foo: 1, x: 2
80
+ # # => Command: /usr/bin/pgrep --foo 1 -x 2 rails
81
+ # ```
82
+ #
83
+ # To pass a flag, supply a keyword argumente with a `nil` value:
84
+ #
85
+ # ```ruby
86
+ # Shell::Pgrep.exec "rails", foo: nil, x: nil
87
+ # # => Command: /usr/bin/pgrep --foo -x rails
88
+ # ```
89
+ #
90
+ # For ease of use, `Symbol` arguments also become flags:
91
+ #
92
+ # ```ruby
93
+ # Shell::Pgrep.exec "rails", :foo, :x
94
+ # # => Command: /usr/bin/pgrep --foo -x rails
95
+ # ```
96
+ #
97
+ # ### Formatting options
98
+ #
99
+ # In the default setting `option_prefix :auto`:
100
+ #
101
+ # ```ruby
102
+ # module Shell
103
+ # class Pgrep < Command
104
+ # command_path "/usr/bin/pgrep"
105
+ # option_prefix :auto
106
+ # end
107
+ # end
108
+ # ```
109
+ #
110
+ # , short options are prefixed with "-", longer options with "--":
111
+ #
112
+ # ```ruby
113
+ # Shell::Pgrep.exec "rails", foo: 1, x: 2
114
+ # # => Command: /usr/bin/pgrep --foo 1 -x 2 rails
115
+ # ```
116
+ #
117
+ # If the command you are wrapping expects differently, set your prefix as a `String`:
118
+ #
119
+ # ```ruby
120
+ # module Shell
121
+ # class Pgrep < Command
122
+ # command_path "/usr/bin/pgrep"
123
+ # option_prefix "-"
124
+ # end
125
+ # end
126
+ #
127
+ # Shell::Pgrep.exec "rails", foo: 1, x: 2
128
+ # # => Command: /usr/bin/pgrep -foo 1 -x 2 rails
129
+ # ```
130
+ #
131
+ # The order of positional arguments and options can be swapped with
132
+ # `positional_parameters: :first`:
133
+ #
134
+ # ```ruby
135
+ # module Shell
136
+ # class Pgrep < Command
137
+ # command_path "/usr/bin/pgrep"
138
+ # positional_parameters :first
139
+ # end
140
+ # end
141
+ #
142
+ # Shell::Pgrep.exec "rails", foo: 1, x: 2
143
+ # # => Command: /usr/bin/pgrep rails --foo 1 -x 2
144
+ # ```
145
+ #
146
+ # ### Transforming options
147
+ #
148
+ # The translation from "`.exec` method argument" to "shell command argument" can
149
+ # be controlled through the `transform_options` macro:
150
+ #
151
+ # ```ruby
152
+ # module Shell
153
+ # class Pgrep < Command
154
+ # command_path "/usr/bin/pgrep"
155
+ #
156
+ # transform_options include_ancestors: :a
157
+ # end
158
+ # end
159
+ #
160
+ # Shell::Pgrep.exec "rails", :include_ancestors
161
+ # # => Command: /usr/bin/pgrep -a rails
162
+ # ```
163
+ #
164
+ # If the replacement value (here: `:a`) is a `Symbol`, it will be prefixed according to
165
+ # the `option_prefix` settings. `String` replacement values are passed through unformatted:
166
+ #
167
+ # ```ruby
168
+ # module Shell
169
+ # class Pgrep < Command
170
+ # command_path "/usr/bin/pgrep"
171
+ #
172
+ # transform_options include_ancestors: "!a"
173
+ # end
174
+ # end
175
+ #
176
+ # Shell::Pgrep.exec "rails", :include_ancestors
177
+ # # => Command: /usr/bin/pgrep !a rails
178
+ # ```
179
+ #
180
+ # If you need even more control - for example, because the command in question does not
181
+ # tolerate whitespace between option name and value - you can pass a string with a `#VALUE#`
182
+ # placeholder:
183
+ #
184
+ # ```ruby
185
+ # module Shell
186
+ # class Pgrep < Command
187
+ # command_path "/usr/bin/pgrep"
188
+ #
189
+ # transform_options some_option: "-x#VALUE#"
190
+ # end
191
+ # end
192
+ #
193
+ # Shell::Pgrep.exec "rails", some_option: "foo"
194
+ # # => Command: /usr/bin/pgrep -xfoo rails
195
+ # ```
196
+ #
197
+ # ### Result#value
198
+ #
199
+ # If STDOUT is not enough and you want to control the return value of your command, use
200
+ # `Result#value`. Take the output of `git --version` as an example:
201
+ #
202
+ # ```ruby
203
+ # module Shell
204
+ # class Git < Command
205
+ # command_path `which git`
206
+ # end
207
+ # end
208
+ #
209
+ # Shell::Git.exec(:version).stdout
210
+ # # => "git version 2.16.1"
211
+ # ```
212
+ #
213
+ # We now want to provide a convenience method on our wrapper that returns the plain version
214
+ # number only, and we will pass that parsed value back by setting it on `Result#value`:
215
+ #
216
+ # ```ruby
217
+ # module Shell
218
+ # class Git < Command
219
+ # command_path `which git`
220
+ #
221
+ # # `Shell::Command.version` is already taken, so we name the method `.get_version`
222
+ # def self.get_version
223
+ # result = exec(:version)
224
+ #
225
+ # return result if result.failure?
226
+ #
227
+ # result.value =
228
+ # result.stdout
229
+ # .split(" ")
230
+ # .last
231
+ #
232
+ # result
233
+ # end
234
+ # end
235
+ # end
236
+ #
237
+ # Shell::Git.get_version.value
238
+ # # => "2.16.1"
239
+ # ```
240
+ #
241
+ # A more compact way of dealing with command success or failure exists through two block
242
+ # handlers, `Result#on_success` and `Result#on_failure`. They both yield the `Result` object:
243
+ #
244
+ # ```ruby
245
+ # module Shell
246
+ # class Git < Command
247
+ # command_path `which git`
248
+ #
249
+ # def self.get_version
250
+ # exec(:version).on_success do |result|
251
+ # result.value =
252
+ # result.stdout
253
+ # .split(" ")
254
+ # .last
255
+ # end
256
+ # end
257
+ # end
258
+ # end
259
+ #
260
+ # Shell::Git.get_version.value
261
+ # # => "2.16.1"
262
+ # ```
263
+ #
264
+ # ### Supporting multiple versions of a command
265
+ #
266
+ # Every `Shell::Command` can support multiple versions of a shell command and help you
267
+ # abstract away the differences between them. This is useful for upgrade situations or
268
+ # to deal with differences between environments.
269
+ #
270
+ # One such example is `tesseract`, where the option format has changed between versions
271
+ # 3 and 4 - the older version expects long-form options to be prefixed with "-", while
272
+ # version 4 moved to the more common "--" prefix.
273
+ #
274
+ # To support multiple versions, use the `detect_version {}` and `version(:identifier) {}`
275
+ # DSL macros. For `tesseract`, our version 3 base class looks like this:
276
+ #
277
+ # ```ruby
278
+ # module Shell
279
+ # class Tesseract < Command
280
+ # command_path `which tesseract`
281
+ # option_prefix "-"
282
+ # positional_parameters :first
283
+ # end
284
+ # end
285
+ # ```
286
+ #
287
+ # We now add a detector block that returns an identifier for the installed version of
288
+ # `tesseract`:
289
+ #
290
+ # ```ruby
291
+ # module Shell
292
+ # class Tesseract < Command
293
+ # command_path `which tesseract`
294
+ # option_prefix "-"
295
+ # positional_parameters :first
296
+ #
297
+ # detect_version do
298
+ # exec_base("--version").on_success do |result|
299
+ # result.value =
300
+ # result.stdout
301
+ # .lines
302
+ # .first
303
+ # .split(" ")
304
+ # .last
305
+ # .first
306
+ # end
307
+ # end
308
+ # end
309
+ # end
310
+ # ```
311
+ #
312
+ # Your detector can return a `String`, a `Symbol` or `nil`. It can return them either
313
+ # directly or set on `Result#value`, which is what we are doing above.
314
+ #
315
+ # It's important to note that you cannot call `.exec` in your detector! `.exec` depends
316
+ # on the version being detected, so calling it from inside the detector leads to an
317
+ # infinite loop. Explicitely execute the command base class with `.exec_base` instead.
318
+ #
319
+ # Now we'll define a `version` which overrides the configuration of the `Shell::Tesseract`
320
+ # class when we have detected version 4 to be installed:
321
+ #
322
+ # ```ruby
323
+ # module Shell
324
+ # class Tesseract < Command
325
+ # command_path `which tesseract`
326
+ # option_prefix "-"
327
+ # positional_parameters :first
328
+ #
329
+ # detect_version do
330
+ # exec_base("--version").on_success do |result|
331
+ # result.value =
332
+ # result.stdout
333
+ # .lines
334
+ # .first
335
+ # .split(" ")
336
+ # .last
337
+ # .first
338
+ # end
339
+ # end
340
+ #
341
+ # version("4") do
342
+ # option_prefix :auto
343
+ # end
344
+ # end
345
+ # end
346
+ # ```
347
+ #
348
+ # Now whenever you call `.exec` for the first time, your version detector block is
349
+ # executed. If it returns "4", our alternate configuration is used; if it returns
350
+ # `nil` or a different version string, the base class is used instead.
351
+ #
352
+ # ### Timeouts
353
+ #
354
+ # Commands can be configured to abort execution after a specified time limit by passing
355
+ # a `timeout:` parameter to `.exec`. The timeout is specified in seconds and accepts both
356
+ # integers and floats.
357
+ #
358
+ # When a timeout occurs:
359
+ # 1. The process receives a SIGTERM signal (graceful termination)
360
+ # 2. After 0.5 seconds, a SIGKILL signal is sent if the process is still alive
361
+ # 3. A `Shell::Errors::CommandTimeout` exception is raised
362
+ #
363
+ # ```ruby
364
+ # module Shell
365
+ # class SlowCommand < Command
366
+ # command_path "/usr/bin/some_slow_command"
367
+ # end
368
+ # end
369
+ #
370
+ # # Execute with a 30 second timeout
371
+ # Shell::SlowCommand.exec("large_file.txt", timeout: 30)
372
+ # ```
373
+ #
374
+ # The timeout exception includes useful debugging information:
375
+ #
376
+ # ```ruby
377
+ # begin
378
+ # Shell::SlowCommand.exec("huge_file.txt", timeout: 10)
379
+ # rescue Shell::Errors::CommandTimeout => e
380
+ # puts "Command: #{e.command}" # Full command that was executed
381
+ # puts "Timeout: #{e.timeout_seconds}s" # Timeout limit in seconds
382
+ # puts "PID: #{e.pid}" # Process ID
383
+ # end
384
+ # ```
385
+ #
386
+ # Timeouts can be combined with other features like stdin/stdout redirection:
387
+ #
388
+ # ```ruby
389
+ # # Timeout with stdin data
390
+ # Shell::SomeCommand.exec(
391
+ # "input.txt",
392
+ # stdin: "data to process",
393
+ # timeout: 60
394
+ # )
395
+ #
396
+ # # Timeout with stdout redirection
397
+ # Shell::SomeCommand.exec(
398
+ # "input.txt",
399
+ # stdout: "/tmp/output.txt",
400
+ # timeout: 120
401
+ # )
402
+ # ```
403
+ #
404
+ # You can also wrap commands with custom timeout handling in your wrapper classes:
405
+ #
406
+ # ```ruby
407
+ # module Shell
408
+ # class ImageProcessor < Command
409
+ # command_path "/usr/bin/convert"
410
+ #
411
+ # def self.process_with_timeout(input_file, output_file, max_seconds: 300)
412
+ # exec(input_file, output_file, timeout: max_seconds)
413
+ # .raise_failures
414
+ # .on_success { |r| puts "Processing complete" }
415
+ # rescue Shell::Errors::CommandTimeout => e
416
+ # # Handle timeout gracefully
417
+ # Rails.logger.warn("Image processing timed out: #{e.message}")
418
+ # nil
419
+ # end
420
+ # end
421
+ # end
422
+ # ```
423
+ #
424
+ # For commands that should never hang, you can set a reasonable default timeout:
425
+ #
426
+ # ```ruby
427
+ # module Shell
428
+ # class NetworkCommand < Command
429
+ # command_path "/usr/bin/curl"
430
+ #
431
+ # def self.fetch_with_default_timeout(url, timeout: 30)
432
+ # exec(url, timeout: timeout)
433
+ # end
434
+ # end
435
+ # end
436
+ # ```
437
+ #
438
+ # ### Inheritance
439
+ #
440
+ # `Shell::Command` classes inherit their parents configuration:
441
+ #
442
+ # ```ruby
443
+ # module Shell
444
+ # class Pgrep < Command
445
+ # command_path "/usr/bin/pgrep"
446
+ # positional_parameters :first
447
+ # end
448
+ #
449
+ # class Pgrep2 < Pgrep
450
+ # end
451
+ # end
452
+ #
453
+ # Shell::Pgrep2.exec "rails", foo: 1, x: 2
454
+ # # => Command: /usr/bin/pgrep rails --foo=1 -x 2
455
+ # ```
456
+ class Command
457
+ extend OptionalDependencies
458
+
459
+ # How long a child process which is being terminated gets to exit after SIGTERM,
460
+ # before it is sent SIGKILL
461
+ #
462
+ # @return [Float] seconds
463
+ TERMINATION_GRACE_PERIOD = 0.5
464
+
465
+ # The `Result` class is the return value you receive from a successful or unsuccessful
466
+ # command execution. It provides you with `#stdout`, `#stderr` and the {Process::Status}
467
+ # at `#status`. Its `#value` attribute can be set with custom return data by the executed
468
+ # command.
469
+ #
470
+ # It also provides some chainable block helpers for convenience:
471
+ #
472
+ # ```ruby
473
+ # result = Shell::SomeCommand.exec
474
+ #
475
+ # result.on_success { |result| puts "Success: #{result.value}" }
476
+ # .on_failure { |result| puts "Failure: #{result.stderr}" }
477
+ # ```
478
+ #
479
+ # If you prefer unsuccessful commands to raise an exception, use `#raise_failures`:
480
+ #
481
+ # ```ruby
482
+ # Shell::SomeCommand.exec
483
+ # .raise_failures
484
+ # .on_success { |result| puts "Success: #{result.value}" }
485
+ # ```
486
+ class Result
487
+ attr_reader :command_path
488
+ attr_reader :command_options
489
+ attr_reader :stdout
490
+ attr_reader :stdout_path
491
+ attr_reader :stdout_size
492
+ attr_reader :stderr
493
+ attr_accessor :value
494
+
495
+ # The exception raised while turning the command's output into {#value}
496
+ #
497
+ # The command itself may have exited cleanly; if its output could not be
498
+ # processed, the result is a {#failure?} all the same.
499
+ #
500
+ # @return [Exception, nil]
501
+ attr_accessor :post_processing_failure
502
+
503
+ # @param path [String]
504
+ # @param args [Array<String>]
505
+ # @param stdout [String] the contents of STDOUT
506
+ # @param stdout_path [String] the path to the file STDOUT was redirected to; alternative to `:stdout`
507
+ # @param stderr [String]
508
+ # @param status [Process::Status]
509
+ def initialize(path:, args:, stderr:, status:, stdout: nil, stdout_path: nil)
510
+ @command_path = path
511
+ @command_options = args
512
+ @stdout = stdout
513
+ @stdout_path = stdout_path
514
+ @stderr = stderr
515
+ @status = status
516
+ @ignored_exit_codes = []
517
+
518
+ @stdout_size =
519
+ if stdout_path
520
+ ::File.readable?(stdout_path) ? ::File.size(stdout_path) : "?"
521
+ else
522
+ stdout ? stdout.size : 0
523
+ end
524
+ end
525
+
526
+ # The full command that was executed
527
+ #
528
+ # @return [String]
529
+ def command
530
+ ([command_path] + command_options).join(" ")
531
+ end
532
+
533
+ # The commands exit status code
534
+ #
535
+ # @return [Integer]
536
+ def status
537
+ @status.exitstatus
538
+ end
539
+
540
+ # Was the command executed successfully?
541
+ #
542
+ # @return [Boolean]
543
+ def success?
544
+ return false if post_processing_failure
545
+
546
+ @status.success? || @ignored_exit_codes.include?(status)
547
+ end
548
+
549
+ # Was the command executed unsuccessfully?
550
+ #
551
+ # @return [Boolean]
552
+ def failure?
553
+ !success?
554
+ end
555
+
556
+ # Mark one or more non-zero exit codes as "successful"
557
+ #
558
+ # These exit codes will not mark the result as {#failed?}
559
+ # or raise `Shell::Errors::CommandUnsuccessful`.
560
+ #
561
+ # @param code_or_codes [Integer, Array<Integer>]
562
+ # @return [self]
563
+ def consider_successful(code_or_codes)
564
+ @ignored_exit_codes.push(*code_or_codes)
565
+
566
+ self
567
+ end
568
+
569
+ # Execute the given block if the command was successful
570
+ #
571
+ # @yield [self]
572
+ # @return [self]
573
+ def on_success
574
+ yield self if success?
575
+
576
+ self
577
+ end
578
+
579
+ # Execute the given block on successful execution with exception handling
580
+ #
581
+ # Unlike {#on_success}, an exception raised by the block does not escape:
582
+ # it marks the result as a {#failure?} and becomes its `#value`.
583
+ #
584
+ # @yield [self]
585
+ # @return [self]
586
+ def post_process
587
+ yield self if success?
588
+
589
+ self
590
+ rescue StandardError => e
591
+ self.post_processing_failure = e
592
+ self.value = e
593
+
594
+ self
595
+ end
596
+
597
+ # Execute the given block if the command was unsuccessful
598
+ #
599
+ # @yield [self]
600
+ # @return [self]
601
+ def on_failure
602
+ yield self if failure?
603
+
604
+ self
605
+ end
606
+
607
+ # Information returned from the command about an error situation
608
+ #
609
+ # Usually, but not always STDERR. Can be overloaded by `Result`
610
+ # subclasses.
611
+ #
612
+ # @return [String]
613
+ def error_output
614
+ post_processing_failure ? post_processing_failure.message : stderr
615
+ end
616
+
617
+ # Raise a `Shell::Errors::CommandUnsuccessful` exception if the
618
+ # command was unsuccessful
619
+ #
620
+ # If the failure was in post-processing the command's output, the
621
+ # exception raised there is the error's `#cause`.
622
+ #
623
+ # @raise [Shell::Errors::CommandUnsuccessful]
624
+ # @return [self]
625
+ def raise_failures
626
+ if failure?
627
+ raise Shell::Errors::CommandUnsuccessful.new(inspect), cause: post_processing_failure
628
+ end
629
+
630
+ self
631
+ end
632
+
633
+ def inspect
634
+ stdout_formatted =
635
+ stdout_path ? "<file: #{stdout_path}> #{stdout_size} Bytes" : "#{stdout_size} Bytes"
636
+
637
+ <<~EOT
638
+ Command: #{command}
639
+ PID: #{@status.pid}
640
+ Status: #{status} (#{ success? ? 'successful' : 'failure' })
641
+ Stdout: #{stdout_formatted}
642
+ Stderr: #{ (stderr.lines[0]&.chomp || '') + "... (#{stderr.size} Bytes)" if failure?}
643
+ #{"Post-processing failed: #{post_processing_failure.class}: #{post_processing_failure.message}" if post_processing_failure}
644
+ EOT
645
+ end
646
+ end
647
+
648
+ class << self
649
+ # @return [Symbol] whether positional parameters `:first`
650
+ # (before the options) or `:last` (after the options)
651
+ attr_reader :positional_parameters_position
652
+
653
+ # Get or set the path to the commands binary
654
+ #
655
+ # @param value [String, Pathname]
656
+ # @return [Pathname]
657
+ def command_path(value = nil)
658
+ if value
659
+ @command_path = Pathname.new(value.chomp.strip).freeze
660
+ else
661
+ @command_path
662
+ end
663
+ end
664
+
665
+ # Get or set the prefix used by the command for
666
+ # command options ("--" or "-"). Set to `:auto` to use
667
+ # "-" for single-character flags and "--" for longer ones.
668
+ #
669
+ # Subclasses default to :auto.
670
+ #
671
+ # @param value [String]
672
+ # @return [Pathname]
673
+ def option_prefix(value = nil)
674
+ if value
675
+ @option_prefix = value.freeze
676
+ else
677
+ @option_prefix
678
+ end
679
+ end
680
+
681
+ # Get or set whether positional parameters come `:first`
682
+ # (before the options) or `:last` (after the options).
683
+ #
684
+ # Subclasses default to :last.
685
+ #
686
+ # @example
687
+ # ```
688
+ # # Positional parameters last
689
+ # some_command --foo -l example.txt
690
+ #
691
+ # # Positional parameters first
692
+ # some_command example.txt --foo -l
693
+ # ```
694
+ #
695
+ # @param value [Symbol, nil] `:first` or `:last`. `:last` if not set.
696
+ # @return [Symbol, nil]
697
+ def positional_parameters(value = nil)
698
+ if value
699
+ @positional_parameters_position = value.freeze
700
+ else
701
+ @positional_parameters_position
702
+ end
703
+ end
704
+
705
+ # Get or set a transformation table for option names
706
+ #
707
+ # Set the Hash in the format
708
+ # `<Ruby keyword argument name> => <Command line option name>`
709
+ #
710
+ # As a replacement, provide a `Symbol` for simple renamings; your
711
+ # classes prefixing and value separation settings will be
712
+ # automatically applied.
713
+ #
714
+ # Provide `String` replacements for more control; these must contain
715
+ # the prefix as well.
716
+ #
717
+ # @example
718
+ # ```ruby
719
+ # class SomeCommand < Command
720
+ # command_path `which some_command`
721
+ # # `option_prefix` is set to its default of :auto
722
+ #
723
+ # transform_options {
724
+ # foo: :dFoo,
725
+ # bar: "!bar"
726
+ # }
727
+ # end
728
+ #
729
+ # SomeCommand.exec(foo: "one", bar: "two")
730
+ # .command
731
+ # # => "some_command --dFoo=one !bar=two"
732
+ #
733
+ # @param value [String]
734
+ # @return [Pathname]
735
+ def transform_options(**kargs)
736
+ if kargs.any?
737
+ @transform_options = kargs.freeze
738
+ else
739
+ @transform_options
740
+ end
741
+ end
742
+
743
+ # Get or set the state for `dasherize_options`
744
+ #
745
+ # When `true`, underscores in option names will be
746
+ # converted into dashes, e.g. `:some_option` => `--some-option`.
747
+ #
748
+ # @param value [Boolean, nil]
749
+ # @return [Boolean, nil]
750
+ def dasherize_options(value = nil)
751
+ if value.nil?
752
+ @dasherize_options
753
+ else
754
+ @dasherize_options = value
755
+ end
756
+ end
757
+
758
+ # Dynamically generated subclasses configured with the
759
+ # `version("identifier") {}` macro, indexed by name
760
+ #
761
+ # @return [Hash{Symbol,String=>Class}]
762
+ def versions
763
+ @versions || {}
764
+ end
765
+
766
+ # Macro for providing a version detector block
767
+ #
768
+ # The return value of your block decides which version
769
+ # configuration is used. If your block returns `nil` or
770
+ # an unknown identifier, the base class is used instead.
771
+ #
772
+ # @example
773
+ # ```ruby
774
+ # class SomeCommand < Command
775
+ # detect_version do
776
+ # "4"
777
+ # end
778
+ #
779
+ # version("4") do
780
+ # end
781
+ # end
782
+ # ```
783
+ #
784
+ # One important note: do not call `.exec` inside your
785
+ # detector block, as that leads to an infinite loop. Execute
786
+ # the base class command with `.exec_base` instead.
787
+ #
788
+ # @yieldreturn [String,Symbol,nil] an identifier as defined by a
789
+ # `version(:identifier) {}` macro, or `nil` to use the base class
790
+ # @return [void]
791
+ def detect_version(&block)
792
+ if block_given?
793
+ @version_detector = block
794
+ else
795
+ instance_eval(&@version_detector) if @version_detector
796
+ end
797
+ end
798
+
799
+ # An identifier for the version of the command that is
800
+ # installed. Only available if the command supports versions.
801
+ #
802
+ # @return [String, nil]
803
+ def detected_version
804
+ @detected_version ||= begin
805
+ result = detect_version
806
+
807
+ result.is_a?(Result) ? result.value : result
808
+ end
809
+ end
810
+
811
+ # DSL macro for defining a version of this command
812
+ #
813
+ # This creates a subclass of the current command class; your
814
+ # block is executed in the scope of that subclass.
815
+ #
816
+ # The subclass inherits all settings from its parent. You can
817
+ # then override them as required.
818
+ #
819
+ # @example
820
+ # ```ruby
821
+ # class SomeCommand < Command
822
+ # command_path "/usr/bin/some_command"
823
+ #
824
+ # detect_version do
825
+ # exec_base("--version").stdout
826
+ # .split(".")
827
+ # .first
828
+ # end
829
+ #
830
+ # version("4") do
831
+ # command_path "/usr/bin/some_command4"
832
+ # end
833
+ # end
834
+ # ```
835
+ #
836
+ # @param identifier [String, Symbol]
837
+ # @yield
838
+ # @return [void]
839
+ def version(identifier, &block)
840
+ @versions[identifier] = Class.new(self, &block)
841
+ end
842
+
843
+ # We give our `Command` subclasses the default values of the parent class
844
+ def inherited(subclass)
845
+ super
846
+
847
+ subclass.instance_variable_set(:@command_path, command_path.dup)
848
+ subclass.instance_variable_set(:@option_prefix, option_prefix.dup)
849
+ subclass.instance_variable_set(:@dasherize_options, dasherize_options.dup)
850
+ subclass.instance_variable_set(:@transform_options, transform_options.dup)
851
+ subclass.instance_variable_set(:@positional_parameters_position, positional_parameters_position.dup)
852
+ subclass.instance_variable_set(:@version_detector, @version_detector.dup)
853
+ subclass.instance_variable_set(:@versions, versions.dup)
854
+ end
855
+ end
856
+
857
+ # Prefix single-character flags with a "-" and longer options with "--" by default,
858
+ # ie `some_command -f --option`
859
+ option_prefix :auto
860
+ # Convert underscores in options to dashes by default, e.g.
861
+ # `:some_option` => `--some-option`
862
+ dasherize_options true
863
+ # Positional parameters come as last arguments, after the options by default
864
+ positional_parameters :last
865
+
866
+ def self.versioned_new
867
+ (versions[detected_version] || self).new
868
+ end
869
+
870
+ # Execute the command
871
+ #
872
+ # If the subclass has support for multiple versions configured,
873
+ # the installed version will be detected first and the appropriate
874
+ # configuration initialised.
875
+ #
876
+ # @see {#exec}
877
+ def self.exec(*args, **kargs, &block)
878
+ versioned_new.exec(*args, **kargs, &block)
879
+ end
880
+
881
+ # Execute the command through the base configuration, without
882
+ # performing version detection
883
+ #
884
+ # @see {#exec}
885
+ def self.exec_base(*args, **kargs, &block)
886
+ new.exec(*args, **kargs, &block)
887
+ end
888
+
889
+ # Execute the command
890
+ #
891
+ # In general, give keyword arguments for command options or flags and
892
+ # arguments for positional arguments.
893
+ #
894
+ # @example
895
+ # ```ruby
896
+ # Shell::SomeCommand.exec("example.txt", "other_file.txt", foo: :bar)
897
+ # .command
898
+ # # => "some_command --foo bar example.txt other_file.txt"
899
+ # ```
900
+ #
901
+ # Option flags can be set through keyword arguments with `nil` values:
902
+ #
903
+ # @example
904
+ # ```ruby
905
+ # Shell::SomeCommand.exec("example.txt", foo: nil)
906
+ # .command
907
+ # # => "some_command --foo example.txt"
908
+ # ```
909
+ #
910
+ # For convenience, arguments passed as `Symbol` are treated as flags
911
+ # as well:
912
+ #
913
+ # @example
914
+ # ```ruby
915
+ # Shell::SomeCommand.exec("example.txt", :foo)
916
+ # .command
917
+ # # => "some_command --foo example.txt"
918
+ # ```
919
+ #
920
+ # `Fs::File` objects can also be passed directly as arguments:
921
+ #
922
+ # @example
923
+ # ```ruby
924
+ # upload = Fs::Files::UserUpload.new(path: "/some/file.pdf")
925
+ # Shell::SomeCommand.exec(upload, :foo)
926
+ # ```
927
+ #
928
+ # If you need to pass the same option multiple times and thus cannot
929
+ # use keyword arguments, pass a nested array instead:
930
+ #
931
+ # @example
932
+ # ```ruby
933
+ # Shell::SomeCommand.exec("example.txt", [[:foo, "first_value"], [:foo, "second_value"]])
934
+ # .command
935
+ # # => "some_command --foo first_value --foo second_value example.txt"
936
+ # ```
937
+ #
938
+ # @param stdin [String, IO, nil] if given, defines the STDIN input for the command
939
+ # @param stdout [String, #path, nil] if given, redirects STDOUT to this file path
940
+ # @param timeout [Numeric, nil] if given, the command will be terminated after this many seconds
941
+ # @param chdir [String, #to_path, nil] if given, the command runs in this working directory.
942
+ # Only the child process changes directory, unlike `Dir.chdir`, which is global to the
943
+ # process and raises when another thread is inside a `Dir.chdir` block.
944
+ # @return [Shell::Command::Result]
945
+ def exec(*args, stdin: nil, stdout: nil, timeout: nil, chdir: nil, **kargs)
946
+ execute(*args, stdin: stdin, stdout: stdout, timeout: timeout, chdir: chdir, **kargs)
947
+ end
948
+
949
+ private
950
+
951
+ # @see Command.command_path
952
+ # @return [Pathname]
953
+ def command_path
954
+ self.class.command_path.to_s
955
+ end
956
+
957
+ # @see Command.option_prefix
958
+ # @return [String]
959
+ def option_prefix
960
+ self.class.option_prefix
961
+ end
962
+
963
+ # @see Command.dasherize_options
964
+ # @return [Boolean]
965
+ def dasherize_options
966
+ self.class.dasherize_options
967
+ end
968
+
969
+ # @see Command.positional_parameters_position
970
+ # @return [Symbol]
971
+ def positional_parameters_position
972
+ self.class.positional_parameters_position
973
+ end
974
+
975
+ # @see Command.transform_options
976
+ # @return [Hash{Symbol=>Symbol,String}]
977
+ def transform_options
978
+ self.class.transform_options || {}
979
+ end
980
+
981
+ # @see #exec
982
+ def execute(*args, stdin: nil, stdout: nil, timeout: nil, chdir: nil, **kargs)
983
+ command_arguments = build_command_arguments(*args, **kargs)
984
+
985
+ # We always capture STDERR; the others we only create as needed.
986
+ stderr_pipe_read, stderr_pipe_write = IO.pipe
987
+ stdout_pipe_read = nil
988
+ stdout_pipe_write = nil
989
+ stdout_path = nil
990
+ stdin_pipe_read = nil
991
+ stdin_pipe_write = nil
992
+
993
+ spawn_options = {
994
+ err: stderr_pipe_write
995
+ }
996
+ spawn_options[:chdir] = chdir.respond_to?(:to_path) ? chdir.to_path : chdir.to_s if chdir
997
+
998
+ if stdout
999
+ # Redirect stdout to file
1000
+ stdout_path = stdout.respond_to?(:path) ? stdout.path.to_s : stdout.to_s
1001
+ spawn_options[:out] = stdout_path
1002
+
1003
+ else
1004
+ # Capture stdout content ourselves with a pipe
1005
+ stdout_pipe_read, stdout_pipe_write = IO.pipe
1006
+ spawn_options[:out] = stdout_pipe_write
1007
+ end
1008
+
1009
+ if stdin
1010
+ if stdin.respond_to?(:read)
1011
+ # IO objects can be passed directly
1012
+ spawn_options[:in] = stdin
1013
+
1014
+ else
1015
+ # Strings we pass through a pipe manually
1016
+ stdin_pipe_read, stdin_pipe_write = IO.pipe
1017
+ spawn_options[:in] = stdin_pipe_read
1018
+ end
1019
+ end
1020
+
1021
+ # At this point, we have up to three pipes: for STDIN, we supply the input
1022
+ # INTO the spawned command, so it gets the read end. For STDOUT and STDERR,
1023
+ # we receive the input FROM the spawned command, so it gets the write end.
1024
+
1025
+ # Spawn the process
1026
+ pid = spawn_child(command_arguments, spawn_options)
1027
+
1028
+ # From here on the child is ours to clean up: if we are being asked to terminate
1029
+ # while it still runs, the `ensure` below terminates it as well instead of leaving
1030
+ # it behind.
1031
+ reaped = false
1032
+ timed_out = false
1033
+ stdout_reader_thread = nil
1034
+ stderr_reader_thread = nil
1035
+
1036
+ begin
1037
+ # Immediately clean up our own pipe references to pipe ends we do not use ourselves;
1038
+ # the spawned child process which actually does use them now has its own references.
1039
+ stdin_pipe_read&.close
1040
+ stdout_pipe_write&.close
1041
+ stderr_pipe_write.close
1042
+
1043
+ if stdin_pipe_write
1044
+ stdin_pipe_write.write(stdin)
1045
+ stdin_pipe_write.close
1046
+ end
1047
+
1048
+ # Start reader threads BEFORE waiting for the process
1049
+ # ---------------------------------------------------
1050
+ #
1051
+ # Why do we need threads here?
1052
+ #
1053
+ # Pipes have a limited buffer size (typically 64KB on macOS/Linux). When a child
1054
+ # process writes to stdout/stderr and the buffer fills up, the child BLOCKS until
1055
+ # the parent reads from the pipe to make room.
1056
+ #
1057
+ # Our prior version worked like this:
1058
+ #
1059
+ # 1. spawn child process
1060
+ # 2. wait for child to exit (Process.wait)
1061
+ # 3. read from pipes
1062
+ #
1063
+ # This caused a deadlock when the child's output exceeded the pipe buffer -
1064
+ # child blocks on write (waiting for parent to read), parent blocks on wait
1065
+ # (waiting for child to exit).
1066
+ #
1067
+ # The solution is reading from pipes concurrently with waiting for the process.
1068
+ # We spawn threads that continuously read from the pipes, preventing the buffer
1069
+ # from filling up. The main thread can then safely wait for the process.
1070
+ #
1071
+ # Ruby's Global VM Lock (GVL) is released during I/O operations, so when a thread
1072
+ # calls `pipe.read` and blocks waiting for data, other threads (including the
1073
+ # main thread) can run. This makes threads suitable for concurrent I/O.
1074
+ #
1075
+ # Thread lifecycle:
1076
+ #
1077
+ # 1. thread starts and immediately calls `pipe.read`
1078
+ # 2. thread blocks until ALL data is available (child closes its pipe end)
1079
+ # 3. when child exits, it closes its pipe ends automatically
1080
+ # 4. `read` returns with all the data, thread finishes
1081
+ # 5. main thread calls `thread.value` to get the result
1082
+
1083
+ # Start a thread to read stdout (if we're capturing it, not redirecting to file)
1084
+ # The thread will block on `read` until the child process closes its stdout,
1085
+ # which happens automatically when the child exits.
1086
+ stdout_reader_thread =
1087
+ if stdout_pipe_read
1088
+ Thread.new { stdout_pipe_read.read }
1089
+ end
1090
+
1091
+ # Start a thread to read stderr (we always capture stderr)
1092
+ stderr_reader_thread = Thread.new { stderr_pipe_read.read }
1093
+
1094
+ # While we wait here, the reader threads are draining the pipes in the background,
1095
+ # preventing the pipe buffer deadlock.
1096
+
1097
+ timed_out = wait_for_child(pid, timeout)
1098
+ reaped = true
1099
+
1100
+ ensure
1101
+ # Reaching this point without having reaped the child means we are being asked to
1102
+ # terminate while it is still running: the calling thread was killed or had an exception
1103
+ # raised into it, or the process is exiting. Left alone, the child would carry
1104
+ # on as an orphan, with nobody to read its output or to wait for it.
1105
+ unless reaped
1106
+ terminate_child(pid)
1107
+ release_output_readers(stdout_reader_thread, stderr_reader_thread, stdout_pipe_read, stderr_pipe_read)
1108
+ end
1109
+ end
1110
+
1111
+ if timed_out
1112
+ # The child was terminated for exceeding its timeout, and reaped
1113
+ release_output_readers(stdout_reader_thread, stderr_reader_thread, stdout_pipe_read, stderr_pipe_read)
1114
+
1115
+ raise Shell::Errors::CommandTimeout.new(
1116
+ command: ([command_path] + command_arguments).join(" "),
1117
+ timeout: timeout,
1118
+ pid: pid
1119
+ )
1120
+ end
1121
+
1122
+ # Collect results from reader threads
1123
+ #
1124
+ # Thread#value does two things:
1125
+ #
1126
+ # 1. it waits for the thread to finish, like `join` would
1127
+ # 2. it returns the result of the thread block - here, the pipe contents
1128
+ #
1129
+ # If an exception occurred in a thread, `value` will re-raise it here in the
1130
+ # main thread, which is good.
1131
+ #
1132
+ # At this point, the child has exited, so the threads should complete immediately
1133
+ # (or already have completed while we were waiting for the process).
1134
+
1135
+ stdout_content = stdout_reader_thread&.value
1136
+ stderr_content = stderr_reader_thread.value
1137
+
1138
+ # Now that the threads are done reading, we close our pipe ends
1139
+ stdout_pipe_read&.close
1140
+ stderr_pipe_read.close
1141
+
1142
+ # We guide the constant lookup a little with `self.class::Result`, to allow
1143
+ # command subclasses to provide their own `Result` subclass.
1144
+ # See `Shell::File` for an example.
1145
+ self.class::Result.new(
1146
+ path: command_path,
1147
+ args: command_arguments,
1148
+ stderr: stderr_content,
1149
+ status: $?,
1150
+ stdout: stdout_content,
1151
+ stdout_path: stdout_path
1152
+ )
1153
+ rescue IOError, SystemCallError
1154
+ raise Shell::Errors::ExecutionError
1155
+ end
1156
+
1157
+ # Starts the command as a child process
1158
+ #
1159
+ # @param arguments [Array<String>]
1160
+ # @param options [Hash] options for `Kernel.spawn`
1161
+ # @raise [Shell::Errors::CommandNotFound] if the program itself is missing
1162
+ # @return [Integer] the PID of the child
1163
+ def spawn_child(arguments, options)
1164
+ Kernel.spawn(command_path, *arguments, options)
1165
+ rescue Errno::ENOENT
1166
+ # ENOENT is also raised for a missing file we redirect to, so only blame the program
1167
+ # if it really is missing; a bare name is left to the PATH lookup `spawn` did.
1168
+ raise unless command_path.empty? || (command_path.include?("/") && !::File.exist?(command_path))
1169
+
1170
+ raise Shell::Errors::CommandNotFound.new(command_class: self.class, path: command_path)
1171
+ end
1172
+
1173
+ # Transforms arguments and keyword arguments into a correctly ordered
1174
+ # sequence of options, flags and positional command arguments
1175
+ #
1176
+ # @param args [Array]
1177
+ # @param kargs [Hash]
1178
+ # @return [Array<String>]
1179
+ def build_command_arguments(*args, **kargs)
1180
+ positional_args, options =
1181
+ preprocess_arguments(args, kargs)
1182
+
1183
+ order_command_arguments(positional: positional_args, options: stringify_options(options))
1184
+ end
1185
+
1186
+ # Partitions arguments and keyword arguments given to `#exec` into command options and
1187
+ # positional parameters.
1188
+ #
1189
+ # Generally, method keyword arguments become command options, and method arguments become
1190
+ # command positional arguments ("some_command file.txt").
1191
+ #
1192
+ # There are two exceptions: Symbols are shorthands for Symbol => nil keyword arguments
1193
+ # (:foo => "--foo"), and nested arrays are used for repeating options.
1194
+ #
1195
+ # @example
1196
+ # ```ruby
1197
+ # preprocess_arguments(["file.txt", :quiet, [[:l, 1], [:l, 2]]], { foo: "bar" })
1198
+ # # => [
1199
+ # # ["file.txt"],
1200
+ # # [[:quiet, nil], [:l, 1], [:l, 2], [:foo, "bar"]]
1201
+ # # ]
1202
+ # ```
1203
+ #
1204
+ # @param args [Array]
1205
+ # @return [Array<(Array, Array)>] one array of positional parameters and another array
1206
+ # of arrays for options (`[[:option_name, value]]`)
1207
+ def preprocess_arguments(args, kargs)
1208
+ positional_args = []
1209
+ flags = []
1210
+ kargs = kargs.to_a
1211
+
1212
+ args.each do |arg|
1213
+ case arg
1214
+ when Array
1215
+ kargs.concat(arg)
1216
+ when Symbol
1217
+ flags << [arg, nil]
1218
+ else
1219
+ positional_args <<
1220
+ if arg.respond_to?(:path)
1221
+ arg.path.to_s
1222
+ else
1223
+ arg.to_s
1224
+ end
1225
+ end
1226
+ end
1227
+
1228
+ return positional_args, (flags + kargs)
1229
+ end
1230
+
1231
+ # Takes nested option arrays and turns them into
1232
+ # a flat array of strings, ready for consumption by
1233
+ # `Process.spawn`
1234
+ #
1235
+ # @param outer_array [Array<Array>] an array in the form
1236
+ # of [[:option_name, option_value], [:other_option_name, nil]...]
1237
+ # @return [Array<String>] an array in the form of
1238
+ # ["--option_name", "option value", "--other_option_name" ...]
1239
+ def stringify_options(outer_array)
1240
+ outer_array.map do |array|
1241
+ option_name, value = *array
1242
+
1243
+ option_name =
1244
+ format_option_name(option_name)
1245
+ value =
1246
+ value.path.to_s if value.respond_to?(:path)
1247
+
1248
+ if option_name.include?("#VALUE#")
1249
+ [option_name.gsub("#VALUE#", value.to_s)]
1250
+ elsif value
1251
+ [option_name, value.to_s]
1252
+ else
1253
+ [option_name]
1254
+ end
1255
+ end.flatten
1256
+ end
1257
+
1258
+ # Transforms option name symbols into transformed and
1259
+ # prefixed strings, according to class settings
1260
+ #
1261
+ # @param option_name [Symbol]
1262
+ # @return [String]
1263
+ def format_option_name(option_name)
1264
+ if transform_options.key?(option_name)
1265
+ option_name = transform_options[option_name]
1266
+ end
1267
+
1268
+ if option_name.is_a?(Symbol)
1269
+ option_name = option_name.to_s.dasherize if dasherize_options
1270
+
1271
+ option_prefix_for(option_name) + option_name
1272
+ else
1273
+ option_name
1274
+ end
1275
+ end
1276
+
1277
+ # Returns the appropriate prefix for an option,
1278
+ # eg. the "--" in "--option=value"
1279
+ #
1280
+ # @param option_name [Symbol]
1281
+ # @return [String]
1282
+ def option_prefix_for(option_name)
1283
+ if option_prefix == :auto
1284
+ option_name.size == 1 ? "-" : "--"
1285
+ else
1286
+ option_prefix
1287
+ end
1288
+ end
1289
+
1290
+ # Orders options and positional arguments according to
1291
+ # the class setting
1292
+ #
1293
+ # @param positional [Array<String>]
1294
+ # @param options [Array<String>]
1295
+ # @return [Array<String>]
1296
+ def order_command_arguments(positional:, options:)
1297
+ case positional_parameters_position
1298
+ when :first
1299
+ positional + options
1300
+ when :last
1301
+ options + positional
1302
+ else
1303
+ raise "unsupported value for positional_parameters_position: #{positional_parameters_position}"
1304
+ end
1305
+ end
1306
+
1307
+ # Check if a process is still alive
1308
+ #
1309
+ # Uses signal 0 which checks process existence without affecting it
1310
+ #
1311
+ # Waits for the child process to exit, and reaps it
1312
+ #
1313
+ # With a `timeout`, the child is terminated once it has been running for longer.
1314
+ #
1315
+ # @param pid [Integer] the process ID of the child
1316
+ # @param timeout [Numeric, nil] seconds the child may run for
1317
+ # @return [Boolean] true if the child had to be terminated for exceeding `timeout`
1318
+ def wait_for_child(pid, timeout)
1319
+ unless timeout
1320
+ Process.wait(pid)
1321
+ return false
1322
+ end
1323
+
1324
+ deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
1325
+
1326
+ # The documentation for Process::WNOHANG says "do not block if no child available",
1327
+ # but that is misleading — it actually makes .waitpid nonblocking and only returns
1328
+ # the PID after the process has exited, `nil` otherwise.
1329
+ until Process.waitpid(pid, Process::WNOHANG)
1330
+ if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
1331
+ terminate_child(pid)
1332
+ return true
1333
+ end
1334
+
1335
+ sleep(0.05)
1336
+ end
1337
+
1338
+ false
1339
+ end
1340
+
1341
+ # Terminates a child process and reaps it: SIGTERM first, SIGKILL if it is still
1342
+ # alive after {TERMINATION_GRACE_PERIOD}
1343
+ #
1344
+ # Safe to call for a child which has exited or been reaped already.
1345
+ #
1346
+ # @param pid [Integer] the process ID of the child
1347
+ # @return [void]
1348
+ def terminate_child(pid)
1349
+ # Also reaps the child if it has exited in the meantime. Checking before signalling
1350
+ # keeps us from signalling a process ID which has been reaped and reused.
1351
+ return if Process.waitpid(pid, Process::WNOHANG)
1352
+
1353
+ Process.kill("TERM", pid)
1354
+
1355
+ grace_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + TERMINATION_GRACE_PERIOD
1356
+
1357
+ until Process.waitpid(pid, Process::WNOHANG)
1358
+ if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= grace_deadline
1359
+ Process.kill("KILL", pid)
1360
+ Process.waitpid(pid)
1361
+ return
1362
+ end
1363
+
1364
+ sleep(0.01)
1365
+ end
1366
+ rescue Errno::ESRCH, Errno::ECHILD
1367
+ # Already gone, and reaped
1368
+ end
1369
+
1370
+ # Lets the threads reading the child's output finish, and closes our end of the pipes
1371
+ #
1372
+ # The child is dead by now, which closes its ends of the pipes and lets the readers
1373
+ # return with whatever they have buffered. The brief wait is a safety net: a reader
1374
+ # which has not finished by then is killed, so threads cannot leak.
1375
+ #
1376
+ # @param stdout_reader [Thread, nil]
1377
+ # @param stderr_reader [Thread, nil]
1378
+ # @param stdout_pipe [IO, nil]
1379
+ # @param stderr_pipe [IO, nil]
1380
+ # @return [void]
1381
+ def release_output_readers(stdout_reader, stderr_reader, stdout_pipe, stderr_pipe)
1382
+ [stdout_reader, stderr_reader].compact.each do |reader|
1383
+ reader.join(1)
1384
+ reader.kill if reader.alive?
1385
+ end
1386
+
1387
+ stdout_pipe&.close
1388
+ stderr_pipe&.close
1389
+ end
1390
+
1391
+ # @param pid [Integer] the process ID to check
1392
+ # @return [Boolean] true if the process is alive, false otherwise
1393
+ def process_alive?(pid)
1394
+ Process.kill(0, pid)
1395
+ true
1396
+ rescue Errno::ESRCH
1397
+ false
1398
+ end
1399
+ end
1400
+ end