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 --matrix ends 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

Instance Method Summary collapse

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.

Parameters:

  • io (IO) —

    the pipe's write end, with sync on.

  • owner (Integer) —

    the pid of the mutant's child.



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.

Returns:

  • (Boolean)


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.

Parameters:

  • error (Exception)

Returns:

  • (String)


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.message).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.

Parameters:

  • io (IO) —

    the pipe's read end.

Returns:

  • (String, nil)


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.

Parameters:

  • io (IO) —

    the pipe's write end, with sync on (the child ends with exit!).

  • error (Exception)
  • owner (Integer) —

    the pid of the mutant's child.



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).

Parameters:

  • error (Exception)


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.

Parameters:

  • text (String)


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.

Parameters:

  • io (IO)
  • text (String)


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.

Parameters:

  • io (IO) —

    the pipe's write end, with sync on.

  • owner (Integer) —

    the pid of the mutant's child.



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.

Returns:

  • (Boolean)


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.

Parameters:

  • error (Exception)

Returns:

  • (String)


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.message).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.

Parameters:

  • io (IO) —

    the pipe's read end.

Returns:

  • (String, nil)


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.

Parameters:

  • io (IO) —

    the pipe's write end, with sync on (the child ends with exit!).

  • error (Exception)
  • owner (Integer) —

    the pid of the mutant's child.



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).

Parameters:

  • error (Exception)


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.

Parameters:

  • text (String)


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.

Parameters:

  • io (IO)
  • text (String)


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