Module: Mutineer::ChildCause
- Defined in:
- lib/mutineer/child_cause.rb
Overview
Carries one line from a mutant's child to its parent: why the child
raised. The parent puts it in the errored mutant's details, so the JSON
report names the cause, not only stderr (#388, #417).
The child writes the line to a pipe just before exit!; the parent reads
it after the reap, without blocking, so a grandchild that still holds the
write end cannot delay the result.
The fork boundary ChildCause.arm!s the write end as process-local state so Minitest and RSpec can write a cause without a new runner argument (plan KTD3).
Stdlib only: the app-side daemon loads this file without the rest of mutineer.
Constant Summary collapse
- LIMIT =
The longest line sent, in characters, including the
...of a cut line. 500- MATRIX_EARLY_END =
Fixed text when
--matrixends early after a serial database error (KTD5). "a test failed with a database error, then the child ended before the suite finished"- RSPEC_OUTSIDE_EXAMPLES =
Fixed text when RSpec reports an error outside examples (KTD5).
"RSpec reported an error outside its examples, for example a spec file that raised while it loaded"
Class Method Summary collapse
-
.arm!(io, owner) ⇒ void
Remembers the cause pipe for this process so suite code can write without holding the IO.
- .armed_here? ⇒ Boolean private
-
.disarm! ⇒ void
Clears ChildCause.arm!.
-
.line(error) ⇒ String
The error as
Class: first non-blank message line, or the class alone when the message is blank or is the class name. -
.read(io) ⇒ String?
The last complete line in the pipe now, as UTF-8, or nil.
-
.write(io, error, owner) ⇒ void
Write ChildCause.line for
errorto the pipe, but only from the mutant's child itself. -
.write_error(error) ⇒ void
Write ChildCause.line for
errorto the armed pipe (#417). -
.write_text(text) ⇒ void
Write a fixed or already-built cause text to the armed pipe (#417).
- .write_to(io, text) ⇒ void private private
Instance Method Summary collapse
-
#arm!(io, owner) ⇒ void
private
Remembers the cause pipe for this process so suite code can write without holding the IO.
- #armed_here? ⇒ Boolean private private
-
#disarm! ⇒ void
private
Clears ChildCause.arm!.
-
#line(error) ⇒ String
private
The error as
Class: first non-blank message line, or the class alone when the message is blank or is the class name. -
#read(io) ⇒ String?
private
The last complete line in the pipe now, as UTF-8, or nil.
-
#write(io, error, owner) ⇒ void
private
Write ChildCause.line for
errorto the pipe, but only from the mutant's child itself. -
#write_error(error) ⇒ void
private
Write ChildCause.line for
errorto the armed pipe (#417). -
#write_text(text) ⇒ void
private
Write a fixed or already-built cause text to the armed pipe (#417).
- #write_to(io, text) ⇒ void private private
Class Method Details
.arm!(io, owner) ⇒ void
This method returns an undefined value.
Remembers the cause pipe for this process so suite code can write without holding the IO. Only #write_error / #write_text from the same pid succeed.
39 40 41 42 |
# File 'lib/mutineer/child_cause.rb', line 39 def arm!(io, owner) @armed_io = io @armed_owner = owner end |
.armed_here? ⇒ Boolean
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
134 135 136 |
# File 'lib/mutineer/child_cause.rb', line 134 def armed_here? @armed_io && @armed_owner && Process.pid == @armed_owner end |
.disarm! ⇒ void
This method returns an undefined value.
Clears arm!. Safe when nothing was armed.
47 48 49 50 |
# File 'lib/mutineer/child_cause.rb', line 47 def disarm! @armed_io = nil @armed_owner = nil end |
.line(error) ⇒ String
The error as Class: first non-blank message line, or the class alone
when the message is blank or is the class name. Redacted before the cut,
so a cut cannot leave part of a password. Never raises.
58 59 60 61 62 63 64 65 66 67 68 69 70 |
# File 'lib/mutineer/child_cause.rb', line 58 def line(error) name = Redaction.text(error.class) first = nil Redaction.text(error.).each_line("\n") do |l| first = l.strip break unless first.empty? end first = nil if first&.empty? text = first.nil? || first == name ? name : "#{name}: #{first}" text.length > LIMIT ? "#{text[0, LIMIT - 3]}..." : text rescue StandardError Redaction::FAILED end |
.read(io) ⇒ String?
The last complete line in the pipe now, as UTF-8, or nil. Reads without blocking.
118 119 120 121 122 123 124 125 126 127 128 129 130 |
# File 'lib/mutineer/child_cause.rb', line 118 def read(io) buffer = +"" loop do chunk = io.read_nonblock(65_536, exception: false) break if chunk.nil? || chunk == :wait_readable buffer << chunk end last = buffer.lines("\n").reverse.find { |l| l.end_with?("\n") } last && Redaction.utf8(last.chomp("\n").force_encoding(Encoding::UTF_8)) rescue StandardError nil end |
.write(io, error, owner) ⇒ void
This method returns an undefined value.
Write line for error to the pipe, but only from the mutant's child
itself. A grandchild made with a bare fork (no block) runs the child's
code after the fork, so its error can reach the same rescue; it writes
nothing, so details never names another process's error. Never
raises: a failed write only loses the cause, never the verdict.
82 83 84 85 86 |
# File 'lib/mutineer/child_cause.rb', line 82 def write(io, error, owner) return unless Process.pid == owner write_to(io, line(error)) end |
.write_error(error) ⇒ void
This method returns an undefined value.
Write line for error to the armed pipe (#417).
92 93 94 95 96 |
# File 'lib/mutineer/child_cause.rb', line 92 def write_error(error) return unless armed_here? write_to(@armed_io, line(error)) end |
.write_text(text) ⇒ void
This method returns an undefined value.
Write a fixed or already-built cause text to the armed pipe (#417). Redacted and cut like line.
103 104 105 106 107 108 109 110 111 |
# File 'lib/mutineer/child_cause.rb', line 103 def write_text(text) return unless armed_here? body = Redaction.text(text.to_s) body = body.length > LIMIT ? "#{body[0, LIMIT - 3]}..." : body write_to(@armed_io, body) rescue StandardError nil end |
.write_to(io, text) ⇒ void (private)
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
This method returns an undefined value.
142 143 144 145 146 |
# File 'lib/mutineer/child_cause.rb', line 142 def write_to(io, text) io.write("#{text}\n") rescue StandardError nil end |
Instance Method Details
#arm!(io, owner) ⇒ void (private)
This method returns an undefined value.
Remembers the cause pipe for this process so suite code can write without holding the IO. Only #write_error / #write_text from the same pid succeed.
39 40 41 42 |
# File 'lib/mutineer/child_cause.rb', line 39 def arm!(io, owner) @armed_io = io @armed_owner = owner end |
#armed_here? ⇒ Boolean (private)
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
134 135 136 |
# File 'lib/mutineer/child_cause.rb', line 134 def armed_here? @armed_io && @armed_owner && Process.pid == @armed_owner end |
#disarm! ⇒ void (private)
This method returns an undefined value.
Clears arm!. Safe when nothing was armed.
47 48 49 50 |
# File 'lib/mutineer/child_cause.rb', line 47 def disarm! @armed_io = nil @armed_owner = nil end |
#line(error) ⇒ String (private)
The error as Class: first non-blank message line, or the class alone
when the message is blank or is the class name. Redacted before the cut,
so a cut cannot leave part of a password. Never raises.
58 59 60 61 62 63 64 65 66 67 68 69 70 |
# File 'lib/mutineer/child_cause.rb', line 58 def line(error) name = Redaction.text(error.class) first = nil Redaction.text(error.).each_line("\n") do |l| first = l.strip break unless first.empty? end first = nil if first&.empty? text = first.nil? || first == name ? name : "#{name}: #{first}" text.length > LIMIT ? "#{text[0, LIMIT - 3]}..." : text rescue StandardError Redaction::FAILED end |
#read(io) ⇒ String? (private)
The last complete line in the pipe now, as UTF-8, or nil. Reads without blocking.
118 119 120 121 122 123 124 125 126 127 128 129 130 |
# File 'lib/mutineer/child_cause.rb', line 118 def read(io) buffer = +"" loop do chunk = io.read_nonblock(65_536, exception: false) break if chunk.nil? || chunk == :wait_readable buffer << chunk end last = buffer.lines("\n").reverse.find { |l| l.end_with?("\n") } last && Redaction.utf8(last.chomp("\n").force_encoding(Encoding::UTF_8)) rescue StandardError nil end |
#write(io, error, owner) ⇒ void (private)
This method returns an undefined value.
Write line for error to the pipe, but only from the mutant's child
itself. A grandchild made with a bare fork (no block) runs the child's
code after the fork, so its error can reach the same rescue; it writes
nothing, so details never names another process's error. Never
raises: a failed write only loses the cause, never the verdict.
82 83 84 85 86 |
# File 'lib/mutineer/child_cause.rb', line 82 def write(io, error, owner) return unless Process.pid == owner write_to(io, line(error)) end |
#write_error(error) ⇒ void (private)
This method returns an undefined value.
Write line for error to the armed pipe (#417).
92 93 94 95 96 |
# File 'lib/mutineer/child_cause.rb', line 92 def write_error(error) return unless armed_here? write_to(@armed_io, line(error)) end |
#write_text(text) ⇒ void (private)
This method returns an undefined value.
Write a fixed or already-built cause text to the armed pipe (#417). Redacted and cut like line.
103 104 105 106 107 108 109 110 111 |
# File 'lib/mutineer/child_cause.rb', line 103 def write_text(text) return unless armed_here? body = Redaction.text(text.to_s) body = body.length > LIMIT ? "#{body[0, LIMIT - 3]}..." : body write_to(@armed_io, body) rescue StandardError nil end |
#write_to(io, text) ⇒ void (private)
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
This method returns an undefined value.
142 143 144 145 146 |
# File 'lib/mutineer/child_cause.rb', line 142 def write_to(io, text) io.write("#{text}\n") rescue StandardError nil end |