Class: Mutineer::Isolation
- Inherits:
-
Object
- Object
- Mutineer::Isolation
- Defined in:
- lib/mutineer/isolation.rb
Overview
Fork-based isolation for running one mutant. The block runs in a child process; the parent enforces a wall-clock timeout and decodes the child's exit status into a Result.
Exit-status contract (the block's return value, or an explicit exit, is the child's status): 0 => survived, 1 => killed, 2 => error. Timeout is detected by the parent's monitor flag, not by status.signaled? (which is true for ANY signal death, e.g. SIGSEGV — it cannot tell our SIGKILL apart from the OS's).
mutineer: the reload strategy this enables (whole-file load) re-executes
the entire file — any top-level code runs again. Acceptable for POROs;
document if users hit issues with initializers/callbacks. Alternative: the
redefine strategy (surgical single-method redefinition).
Defined Under Namespace
Classes: PathAnchor
Constant Summary collapse
- DEFAULT_TIMEOUT =
seconds
10- POLL_INTERVAL =
Seconds between the parent's checks on a running child.
0.005- ANCHOR_PATTERN =
Byte scan for a path anchor. A snippet without one skips the parse that anchor_paths would do (#339).
send(:__dir__)andsend(:require_relative)contain the same tokens. /__dir__|__FILE__|require_relative/
Class Method Summary collapse
-
.anchor_directory(file_path) ⇒ String
private
The directory
__dir__andrequire_relativeuse forfile_path:File.dirname(File.realpath(file_path)). -
.anchor_file(subject) ⇒ String
private
The path
__FILE__must return forsubject. -
.anchor_paths(code, subject) ⇒ String
private
Rewrites path anchors in a redefine snippet so they resolve against the original source file when
loadruns a different file (#339). -
.apply_surgical(mutation, subject, source, reach_path: nil, reach_key: nil) ⇒ Object
private
Redefine strategy: extract just the enclosing DefNode, apply the mutation to that snippet, wrap it in its real namespace, and
loadonly that one method back into the running process. -
.apply_whole_file(mutated, source_file, hook_def: nil) ⇒ Object
private
Strategy 7a (default): write the whole mutated file and
loadit, which reopens its classes and redefines every method in place. -
.bare_kernel_builtin?(subject) ⇒ Boolean
private
Whether a bare
Kernelinsubjectis::Kernel. -
.decode(status, cause = nil) ⇒ Mutineer::Result
private
Decodes a child status into a Result.
-
.defined_path(subject) ⇒ String?
private
The file the live method was defined in, when that method is
subject's own. -
.drain(rd, buffer) ⇒ Boolean
private
Reads what the channel holds now, without blocking.
-
.finish(result, rd, buffer, finished:) ⇒ Mutineer::Result
private
The Result to return.
-
.method_visibility(mod, name) ⇒ Symbol?
private
Returns the visibility for a method name.
-
.mutated_def(mutation, subject, source, reach_path: nil, reach_key: nil) ⇒ String
private
The enclosing def with the mutation applied, wrapped in
class << selffor a singleton def with no receiver (#20). -
.nesting_keywords(namespace) ⇒ Array<[String, String]>
private
Resolve each namespace ELEMENT to its live Module and pick the correct keyword (reopening a class with
module— or vice versa — raises TypeError), so the textual wrapper matches the real definitions. -
.run(timeout: DEFAULT_TIMEOUT, channel: false) {|channel| ... } ⇒ Mutineer::Result
Runs the block in a forked child.
-
.same_file?(left, right) ⇒ Boolean
private
Whether
leftandrightare the same file after resolving symlinks. -
.write_beside(code, source_file, fallback: false) {|path| ... } ⇒ Object
private
Writes
codeto a hidden.mutineer_mutantfile besidesource_file, yields its path, and removes it after the block.
Class Method Details
.anchor_directory(file_path) ⇒ String
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.
The directory __dir__ and require_relative use for file_path:
File.dirname(File.realpath(file_path)). A subject path that is not a
file yet (a unit probe) uses the real directory that contains it.
419 420 421 422 423 |
# File 'lib/mutineer/isolation.rb', line 419 def self.anchor_directory(file_path) File.dirname(File.realpath(file_path)) rescue SystemCallError File.realpath(File.dirname(File.(file_path))) end |
.anchor_file(subject) ⇒ String
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.
The path __FILE__ must return for subject. The live method's
source_location wins when it is the same file, because that string is
the one the unmutated method returns (a symlink path stays a symlink
path). Otherwise the expanded subject path.
405 406 407 408 409 410 |
# File 'lib/mutineer/isolation.rb', line 405 def self.anchor_file(subject) defined_in = defined_path(subject) return defined_in if defined_in && same_file?(defined_in, subject.file) File.(subject.file) end |
.anchor_paths(code, subject) ⇒ String
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.
Rewrites path anchors in a redefine snippet so they resolve against the
original source file when load runs a different file (#339).
The hidden snippet is never the source file. Beside the source, __dir__
still names that directory, but __FILE__ names the hidden file, and a
symlinked source makes __dir__ and require_relative follow the link's
directory. In the system temp directory every one of them follows the
temp directory, so each mutant raises and scores killed. The rewrite
uses the live method's source_location when that file is subject.file,
so a symlink keeps the path the program loaded. __dir__ and
require_relative use File.realpath, as Ruby does.
Calls with an implicit receiver, literal self, or Kernel / ::Kernel
are rewritten, including send and __send__ whose name is a literal.
A call on any other receiver is left alone: other.__dir__ is a private
call and raises.
365 366 367 368 369 370 371 |
# File 'lib/mutineer/isolation.rb', line 365 def self.anchor_paths(code, subject) return code unless code.match?(ANCHOR_PATTERN) file_path = anchor_file(subject) dir_literal = anchor_directory(file_path).dump PathAnchor.rewrite(code, file_path.dump, dir_literal, bare_kernel: (subject)) end |
.apply_surgical(mutation, subject, source, reach_path: nil, reach_key: nil) ⇒ Object
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.
Redefine strategy: extract just the enclosing DefNode, apply the mutation
to that snippet, wrap it in its real namespace, and load only that one
method back into the running process. No file-level side effects re-run.
Child-only.
The snippet keeps its own def self.x for singletons, so the namespace
wrapper redefines instance and singleton methods correctly without any
special-casing.
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 |
# File 'lib/mutineer/isolation.rb', line 286 def self.apply_surgical(mutation, subject, source, reach_path: nil, reach_key: nil) # Rebuild the FULL namespace nesting textually so unqualified enclosing- # namespace constants resolve exactly as the reload strategy would. A # bare redefinition on the owner would collapse Module.nesting to [owner] # and raise NameError on such constants (C2 scope-collapse). keywords = nesting_keywords(subject.lexical_namespace) prefix = keywords.map { |kw, name| "#{kw} #{name}" }.join("\n") prefix += "\n" unless prefix.empty? # #20: a singleton method whose def has NO `self.` receiver (the # `class << self` and `module_function` forms) would, as a bare `def foo` # inside `module Owner`, redefine the INSTANCE method — but the call # (`Owner.foo`) dispatches to the singleton, so the mutant never runs and # falsely survives. Re-open the singleton class so the redefinition lands on # the same method the test calls. `def self.foo` already carries its # receiver, so it is left as-is (wrapping it would mis-target). inner = mutated_def(mutation, subject, source, reach_path: reach_path, reach_key: reach_key) inner = "#{subject.block_owner}.class_eval do\n#{inner}\nend" if subject.block_owner wrapped = "#{prefix}#{inner}#{"\nend" * keywords.size}" # A snippet that fails to reparse must NOT silently fall through to # running the ORIGINAL method (C2 false-survived). Raise -> the fork # block aborts before any test runs -> Result.error, never a bogus # `survived`. raise "surgical snippet failed to reparse" if Parser.invalid?(wrapped) # Preserve original visibility — class/module bodies define methods # public, but 7a's `load` would re-apply the file's private/protected # (C2). owner = subject.namespace.empty? ? Object : Object.const_get(subject.namespace.join("::")) target = subject.singleton ? owner.singleton_class : owner vis = method_visibility(target, subject.name) # Write the wrapped snippet to a tempfile and `load` it: `load` runs it # at top level, so the textual class/module wrappers rebuild # Module.nesting identically, with no dynamic string execution for # scanners to flag. The input is the project's OWN source (the enclosing # method, textually mutated), loaded only in this forked child. # # The file sits beside the source, as in apply_whole_file (#279). A # read-only source directory keeps the 1.x system-temp location, so # redefine still runs there. Either file is a different path from the # source, so {anchor_paths} rewrites `__FILE__`, `__dir__`, and # `require_relative` to the original file before the load. Without that, # a temp-dir load raises ENOENT or LoadError and every mutant of the # method scores `killed` (#339). The hidden `.mutineer_mutant` name # keeps Zeitwerk away (#253) and lets the parent sweep an orphan after a # timeout kill. anchored = anchor_paths(wrapped, subject) # The anchored text is what `load` runs. A rewrite that does not reparse # must take the same error path as the unanchored snippet above. raise "surgical snippet failed to reparse" if anchored != wrapped && Parser.invalid?(anchored) write_beside(anchored, subject.file, fallback: true) { |path| load path } target.send(vis, subject.name) if vis && vis != :public end |
.apply_whole_file(mutated, source_file, hook_def: nil) ⇒ Object
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.
Strategy 7a (default): write the whole mutated file and load it, which
reopens its classes and redefines every method in place. Re-runs file-
level side effects. Child-only — mutates the loaded program.
The tempfile is created in the ORIGINAL file's directory, not the system
temp dir, so any require_relative in the mutated source resolves
against its real neighbours (e.g. a mutator's require_relative "base"). Writing it elsewhere makes those requires resolve to the temp
dir and raise LoadError.
Loading the file reopens its namespace. With lazy loading, that can be the first time Zeitwerk scans the namespace's directory. Zeitwerk skips hidden files, so the leading dot keeps it from rejecting the tempfile's name as a constant, in this child and in any other running at the same time (#253).
A concern's stored included and prepended blocks from the source file
are forgotten around the load, so ActiveSupport accepts the blocks the
temp file stores (#256). For a def in such a block, the caller passes the
text and hook_def from JobPlan.hook_mutant, and the load places the
mutated def (#297, #348).
ConcernBlocks.load_mutant turns Ruby's warnings off for the load, so the constants it assigns again do not warn (#364).
231 232 233 |
# File 'lib/mutineer/isolation.rb', line 231 def self.apply_whole_file(mutated, source_file, hook_def: nil) write_beside(mutated, source_file) { |path| ConcernBlocks.load_mutant(source_file, path, hook_def: hook_def) } end |
.bare_kernel_builtin?(subject) ⇒ 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.
Whether a bare Kernel in subject is ::Kernel. A class or enclosing
module that defines its own Kernel must keep that constant: rewriting
Kernel.__dir__ would turn a NoMethodError into a path.
380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 |
# File 'lib/mutineer/isolation.rb', line 380 def self.(subject) cursor = Object modules = subject.lexical_namespace.map do |element| cursor = element.start_with?("::") ? Object.const_get(element.delete_prefix("::")) : cursor.const_get(element) end lookup = [] modules.reverse_each { |mod| mod.ancestors.each { |ancestor| lookup << ancestor if ancestor.is_a?(Module) } } lookup.each do |candidate| next unless candidate.const_defined?(:Kernel, false) return candidate.const_get(:Kernel, false).equal?(::Kernel) end true rescue NameError false end |
.decode(status, cause = nil) ⇒ Mutineer::Result
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.
Decodes a child status into a Result.
526 527 528 529 530 531 532 533 |
# File 'lib/mutineer/isolation.rb', line 526 def self.decode(status, cause = nil) case status.exitstatus when 0 then Result.survived when 1 then Result.killed when 2 then Result.error(cause || "child exited with status 2") else Result.error("unexpected exit status: #{status.exitstatus.inspect}") end end |
.defined_path(subject) ⇒ String?
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.
The file the live method was defined in, when that method is subject's
own. An inherited method, or a method that is not defined yet, returns nil
so anchor_file uses the subject path.
432 433 434 435 436 437 438 439 440 441 |
# File 'lib/mutineer/isolation.rb', line 432 def self.defined_path(subject) target = subject.namespace.empty? ? Object : Object.const_get(subject.namespace.join("::")) target = target.singleton_class if subject.singleton method = target.instance_method(subject.name) return unless method.owner == target method.source_location&.first rescue NameError nil end |
.drain(rd, buffer) ⇒ 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.
Reads what the channel holds now, without blocking.
146 147 148 149 150 151 152 153 154 |
# File 'lib/mutineer/isolation.rb', line 146 def self.drain(rd, buffer) loop do chunk = rd.read_nonblock(65_536, exception: false) return true if chunk == :wait_readable return false if chunk.nil? buffer << chunk end end |
.finish(result, rd, buffer, finished:) ⇒ Mutineer::Result
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.
The Result to return. Without a channel it is result itself. With one,
the rest of the channel is read, and the Result carries the Kills it
names.
The verdict matches a run without --matrix, which skips everything after
the first failing serial test except the code around it (see
KillChannel). So when a serial test has named a failure and the child then
ended inside a region that run would skip (an exit, a crash or the
timeout in a later test, class or group), its first failure decides:
error for an unavailable database outcome, otherwise killed. The
plain run never reached that point. An end anywhere else keeps the exit
status, because the plain run reaches that code too: the rest of the
failing test's class wrapper or group hooks, or the suite hooks. A kill in
the parallel tests of a Minitest run also keeps it, because the stop
cannot skip tests already queued.
The row is complete only when the child ended before the timeout, sent a
valid stream with both start and end, lost no line, and its kills
agree with the verdict (a killed mutant names a killer; a survivor names
none). An invalid stream promotes nothing, and its tests are dropped: an
out-of-order line means the parent cannot tell which outcomes are real.
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 |
# File 'lib/mutineer/isolation.rb', line 184 def self.finish(result, rd, buffer, finished:) return result unless rd drain(rd, buffer) report = KillChannel.parse(buffer) return result.with(kills: Kills.new(killed_by: [], ran: [], complete: false)) if report.invalid result = Result.killed if report.started && report.serial_kill && report.skipping.positive? # Early end after a serial DB error: the child never reached the naming # code that would write the exception class (#417 / KTD5). if report.started && report.serial_error && report.skipping.positive? result = Result.error(ChildCause::MATRIX_EARLY_END) end agrees = result.killed? ? report.killed.any? : result.survived? && report.killed.empty? complete = finished && report.started && report.finished && report.lost.zero? && agrees result.with(kills: Kills.new(killed_by: report.killed, ran: report.ran, complete: complete)) end |
.method_visibility(mod, name) ⇒ Symbol?
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 the visibility for a method name.
512 513 514 515 516 517 518 |
# File 'lib/mutineer/isolation.rb', line 512 def self.method_visibility(mod, name) return :private if mod.private_method_defined?(name) return :protected if mod.protected_method_defined?(name) return :public if mod.public_method_defined?(name) nil end |
.mutated_def(mutation, subject, source, reach_path: nil, reach_key: nil) ⇒ String
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.
The enclosing def with the mutation applied, wrapped in class << self
for a singleton def with no receiver (#20). Pure text: it reads no live
module, so the tool process can call it too (JobPlan.hook_mutant).
466 467 468 469 470 471 472 473 474 475 476 477 478 |
# File 'lib/mutineer/isolation.rb', line 466 def self.mutated_def(mutation, subject, source, reach_path: nil, reach_key: nil) loc = subject.def_node.location def_start = loc.start_offset snippet = source.byteslice(def_start...loc.end_offset) rel_s = mutation.start_offset - def_start rel_e = mutation.end_offset - def_start mutated = snippet.byteslice(0...rel_s) + mutation.replacement + snippet.byteslice(rel_e..) if reach_path && rel_s >= 0 && rel_s + mutation.replacement.bytesize <= mutated.bytesize probed = ReachProbe.wrap(mutated, rel_s, rel_s + mutation.replacement.bytesize, reach_path, reach_key) mutated = probed if probed end subject.singleton && subject.def_node.receiver.nil? ? "class << self\n#{mutated}\nend" : mutated end |
.nesting_keywords(namespace) ⇒ Array<[String, String]>
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.
Resolve each namespace ELEMENT to its live Module and pick the correct
keyword (reopening a class with module — or vice versa — raises
TypeError), so the textual wrapper matches the real definitions.
#5: a compact element like "Foo::Bar" stays a SINGLE wrapper class Foo:: Bar (nesting [Foo::Bar]), matching how a whole-file load (reload) sees
it. Splitting it into module Foo; class Bar gave nesting [Foo::Bar,
Foo], so an unqualified constant defined only in Foo would resolve under
redefine but not reload — a strategy disagreement.
A root-anchored element (::Top, #145) resolves from Object and keeps its
:: in the wrapper, so module Outer; class ::Top rebuilds nesting
[Top, Outer] exactly as the source does.
497 498 499 500 501 502 503 504 |
# File 'lib/mutineer/isolation.rb', line 497 def self.nesting_keywords(namespace) mod = Object namespace.map do |name| # const_get resolves a compact "Foo::Bar" too mod = name.start_with?("::") ? Object.const_get(name.delete_prefix("::")) : mod.const_get(name) [mod.is_a?(Class) ? "class" : "module", name] end end |
.run(timeout: DEFAULT_TIMEOUT, channel: false) {|channel| ... } ⇒ Mutineer::Result
Runs the block in a forked child. The block's return value (an Integer
exit code) or any explicit exit is honoured; an unhandled exception
becomes exit 2 with the cause written to STDERR. The cause also reaches
the Result's details through a ChildCause pipe.
The child silences its stdout (see ChildStdout.silence) before the block runs, so test output never reaches the user. Stderr stays open.
With channel: true (a --matrix run) the block gets the write end of a
pipe for KillChannel lines. The parent reads it while it waits, so a
child with more than a pipe buffer to say never blocks, and attaches the
lines to the Result as Kills. The verdict is the one a run without
--matrix gives (see finish).
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 |
# File 'lib/mutineer/isolation.rb', line 60 def self.run(timeout: DEFAULT_TIMEOUT, channel: false) rd, wr = IO.pipe if channel wr&.sync = true cause_rd, cause_wr = IO.pipe cause_wr.sync = true pid = fork do child = Process.pid rd&.close cause_rd.close ChildCause.arm!(cause_wr, child) # Own process group so a timeout kill can reap grandchildren (match # daemon/external backends). Best-effort: if setpgid fails, kill the pid. Process.setpgid(0, 0) rescue nil # rubocop:disable Style/RescueModifier code = 0 begin ChildStdout.silence ChildCoverage.allow_start # A block that takes no channel (a zero-arity lambda) still runs. result = channel ? yield(wr) : yield code = result.is_a?(Integer) ? result : 0 rescue SystemExit => e code = e.status rescue Exception => e # rubocop:disable Lint/RescueException # STDERR, not `warn`: a test may have left `$stderr` as a StringIO. STDERR.puts "[mutineer-child] #{Redaction.describe(e)}" ChildCause.write(cause_wr, e, child) code = 2 ensure ChildCause.disarm! end STDERR.flush # exit! skips at_exit handlers — critical, since a child forked from # inside our own Minitest suite would otherwise re-run the parent's # at_exit autorun hook on the way out. exit!(code) end wr&.close cause_wr.close buffer = +"" if rd reading = !rd.nil? # Single-threaded deadline poll: we are the ONLY caller of waitpid on this # pid, so we never reap-then-kill. SIGKILL the process group only after # WNOHANG shows the child is still alive past the deadline. deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout loop do reaped, status = Process.waitpid2(pid, Process::WNOHANG) return finish(decode(status, ChildCause.read(cause_rd)), rd, buffer, finished: true) if reaped if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline begin Process.kill(:KILL, -pid) rescue Errno::ESRCH, Errno::EPERM Process.kill(:KILL, pid) rescue nil # rubocop:disable Style/RescueModifier end begin _reaped, status = Process.waitpid2(pid) # Child may have finished cleanly between WNOHANG and kill; honor it. return finish(decode(status, ChildCause.read(cause_rd)), rd, buffer, finished: true) if status && status.exited? && !status.signaled? rescue Errno::ECHILD # already reaped end return finish(Result.timeout, rd, buffer, finished: false) end if reading IO.select([rd], nil, nil, POLL_INTERVAL) reading = drain(rd, buffer) else sleep POLL_INTERVAL end end ensure rd&.close cause_rd&.close # Closed after the fork in the normal path; still open if fork raised. wr.close if wr && !wr.closed? cause_wr.close if cause_wr && !cause_wr.closed? end |
.same_file?(left, right) ⇒ 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.
Whether left and right are the same file after resolving symlinks.
449 450 451 452 453 |
# File 'lib/mutineer/isolation.rb', line 449 def self.same_file?(left, right) File.realpath(left) == File.realpath(right) rescue SystemCallError false end |
.write_beside(code, source_file, fallback: false) {|path| ... } ⇒ Object
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.
Writes code to a hidden .mutineer_mutant file beside source_file,
yields its path, and removes it after the block. Both strategies write
through here. Only redefine enables the system-temp fallback when the
source directory is not writable.
The file is locked until the block ends, as the daemon locks its own file
(#295). A SIGKILL drops the lock too. The pid in the name and the lock
tell another run's sweep that the file is in use, so the sweep does not
delete it between the write and the load.
252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 |
# File 'lib/mutineer/isolation.rb', line 252 def self.write_beside(code, source_file, fallback: false) dir = File.dirname(File.(source_file)) dir = Dir.tmpdir if fallback && !File.writable?(dir) Tempfile.create([".mutineer_mutant", ".rb"], dir) do |f| f.flock(File::LOCK_EX) rescue nil # rubocop:disable Style/RescueModifier # Binary: a text write would follow the locale and could change # the bytes. SourceBytes encodes the text to the encoding its # magic comment names, and adds one when a redefine snippet has # none (#346). f.binmode f.write(SourceBytes.for_file(code)) f.flush yield f.path end end |