Add proc_regex option to filter which processes open the TCP debug port

[crystianleao]

Summary

Adds --open-proctitle=PROCTITLE (env var RUBY_DEBUG_OPEN_PROCTITLE). When set, UI_TcpServer#accept compares the value against $0 in each process and opens the listening TCP port only when it matches; otherwise it returns silently without affecting the rest of the debugger session.

The value accepts two forms:

• "foo" -> exact-match string (compared with ==)
• "/foo/i" -> regexp, parsed from /pattern/[flags]

Following discussion with @ko1, the single-flag dual-form design was preferred over a -regexp-suffixed flag.

Motivation

In multi-process job runners (the use case that drove this change is solid_queue), the supervisor forks several differently-named child processes and renames them via Process.setproctitle. The proctitles in solid_queue look like:

./bin/jobs
solid-queue-worker(0.9.0): waiting for jobs in *
solid-queue-dispatcher(0.9.0): dispatching every 1 seconds

--port-range (#1119) addresses port collisions when several processes try to bind, but it cannot select which process should be debuggable. Startup order in solid_queue is non-deterministic, so a fixed port-in-range mapping is not viable.

With --open-proctitle='/\Asolid-queue-worker/', only worker processes whose $0 matches will open a port; the supervisor and the dispatcher run unaffected. Exact-match form is convenient when proctitles are stable, e.g. --open-proctitle='my-worker'.

Behaviour

• The match value is parsed once in UI_TcpServer.parse_open_proctitle. An invalid regexp raises ArgumentError at startup rather than being deferred to accept time.
• To handle the timing window between fork and Process.setproctitle in the child, accept() waits up to 5 seconds for $0 to change from the value captured on the first accept call (tracked in InitialProcInfo) before evaluating the match.
• On no-match, accept() simply returns without yielding. The reader thread exits cleanly, the rest of the debugger session is left intact, and any forked children inherit a working session that re-evaluates the match in their own context.
• The README documents that this option is intended to be used together with --nonstop (-n). Without --nonstop, RUBY_DEBUG_OPEN arms an initial-suspend breakpoint that non-matching processes would hit and block on while waiting for a connection that will never arrive.

Example

$ rdbg --port 3003 --open-proctitle '/\Asolid-queue-worker/' \
       --host 0.0.0.0 -n --open -c './bin/jobs'

The supervisor (./bin/jobs) does not match; no port is opened. Each worker, after fork and setproctitle, matches and opens the port.

New tests in test/console/open_proctitle_test.rb:

• Parser: string form, regexp form, regexp flags, invalid regexp, nil input, path that starts with / but isn't a regexp.
• Initialize: regexp value is compiled, string value is kept, invalid regexp raises, missing value leaves the attribute nil.
• Remote: port opens on regexp match, port opens on string equality, port is skipped on no-match (program runs to completion under --nonstop).

[ko1]

• In Ruby, Proc is ambiguous with Proc class
• It is ambiguous which affect this option (it affects only opening the port)

So how about: --open-proctitle-regexp ?
In this case, we can omit --open.

[ko1]

optional thought: we can specify exact match with --open-proctitle=foo or regexp with --open-proctitle=/foo/

but it should be regexp (no exact match usecases)?

[crystianleao]

Good catch, didn't see the ambiguity with Proc. Agreed, --open-proctitle-regexp works well.

Regarding exact match vs regexp: I built this to debug solid_queue, whose proctitles look like:

./bin/jobs
solid-queue-worker(0.9.0): waiting for jobs in *
solid-queue-dispatcher(0.9.0): dispatching every 1 seconds

So exact matches would be brittle here, they'd break if solid_queue changes its proctitle format (e.g. version bumps, status changes after the initial title is set). Regexp-only seems like the right call.

That said, supporting both wouldn't hurt, --open-proctitle=foo for exact match and --open-proctitle=/foo/ for regexp, as you suggested. Happy to implement it that way if you think it's worth the small added complexity.

@ko1