{ "number": 36434, "input_hash": "427ca2e06f0bcf7c", "model": "ledger", "prompt_hash": null, "created": "2026-10-30T01:14:01+00:00", "result": { "summary": "Adds UNIX domain socket support to Bitcoin Core's HTTP RPC server and bitcoin-cli via the -rpcbind and -rpcconnect configuration options using unix and unix: syntax. It introduces UnixSocketAddr and a SocketAddr variant in netbase to decouple generic endpoint handling from P2P-specific networking classes like CService, and updates Proxy and HTTPServer accordingly. When binding exclusively to UNIX domain sockets, -rpcallowip is no longer required and default TCP loopback listeners are disabled.", "problem": "Local JSON-RPC and REST communication previously required TCP loopback connections, forcing node operators to manage IP-based allowlists instead of operating system filesystem permissions and incurring TCP stack overhead. Additionally, earlier UNIX socket support added in PR #27375 was isolated to the Proxy class, leaving technical debt where socket abstractions were tangled with P2P networking classes.", "card": "Adds UNIX domain socket support to the HTTP RPC server and bitcoin-cli using -rpcbind=unix[:path] and -rpcconnect=unix[:path]. This enables local RPC communication without TCP loopback overhead, relying on filesystem permissions instead of -rpcallowip. The PR also refactors netbase by introducing UnixSocketAddr and SocketAddr, resolving technical debt left from PR #27375. This closes issue #5029, a feature request open since 2014.", "evidence": [ "Closes issue #5029, an open feature request for UNIX domain socket support in RPC since 2014.", "Description notes that earlier UNIX socket support in #27375 created technical debt in Proxy that this PR resolves with generic abstractions." ], "scope_notes": "Refactors networking abstractions across netbase and httpserver by replacing CService with SocketAddr (a std::variant of CService and UnixSocketAddr) in HTTPRemoteClient and Proxy. Includes substantial new unit tests in src/test/netbase_tests.cpp (+498 lines) and functional test framework support via --httpunix.", "changed_since_previous": "Added release notes and documentation for JSON-RPC, and extended functional test coverage for bitcoin-cli over UNIX domain sockets in interface_bitcoin_cli.py and test_runner.py.", "thread": { "last_event_at": "2026-10-29T13:26:48Z", "events": 34, "head_sha": "ccbace1c33f30f9fb842451851263a7d83449323", "schema_floor": 2, "schema": 2 }, "waiting_on": [ { "at": "2026-10-16", "id": "r:5478881949", "on": "author", "url": "https://github.com/bitcoin/bitcoin/pull/36434#pullrequestreview-5478881949", "what": "winterrdog's question about abstract sockets and suggestion to update the PR description" } ], "risk": { "level": "medium", "touches": [ "rpc_api", "tooling", "tests", "docs" ], "why": "A mistake in socket path resolution or socket binding permissions could prevent local RPC access or inadvertently expose the RPC interface to unauthorized local users." }, "discussion": { "author_status": "last statement processed 2026-10-29", "open_concerns": [ "winterrdog: Whether abstract namespace unix sockets should be supported in the future for Linux-specific setups.", "winterrdog: Update the PR description to match the code regarding Unix socket path resolution." ], "resolved_concerns": [ "b-l-u-e: A second node started with the same -rpcbind=unix: will overwrite the live socket file without error, making the first node unreachable while it remains running. (fixed by pinheadmz 2026-10-08)", "b-l-u-e: bitcoin-cli sends the resolved IP in the HTTP Host header instead of the hostname passed via -rpcconnect=, introducing a behavior change/regression from master. (fixed by pinheadmz 2026-10-08)", "winterrdog: On platforms where char is signed, non-ASCII UTF-8 bytes wrap to negative values and match c < 0x20, causing valid UTF-8 paths like /tmp/jos\u00e9.sock to be replaced with \"unix\" in logs. (fixed by pinheadmz 2026-10-28)", "winterrdog: Place Unix socket handling code behind an #ifdef HAVE_SOCKADDR_UN guard to avoid compiling unused code on unsupported platforms. (fixed by pinheadmz 2026-10-28)", "winterrdog: Log host instead of strRPCBind in the bind failure warning to avoid redundant port strings when a port is included in the address. (fixed by pinheadmz 2026-10-28)", "winterrdog: Whether duplicate -rpcbind unix socket endpoints unlinking the earlier socket and rebinding silently without warning is intended behavior or should fail like TCP. (answered by pinheadmz 2026-10-28)", "winterrdog: Refactor GetBindAddresses() to reduce cognitive load and streamline the control flow. (fixed by pinheadmz 2026-10-28)", "hodlinator: What is the benefit of allowing HTTP over unix sockets compared to using IPC over unix sockets, given executeRpc() is already exposed through IPC? (answered by pinheadmz 2026-10-29)" ] }, "reviewability": { "state": "Ready", "label": "Ready", "reason": "Nothing known that would invalidate a review now." }, "agreement": { "state": "Strong", "summary": "Strong: substantive support, no open objection (winterrdog, winterrdog)", "reason": "Added hodlinator as a participant and recorded their question about the benefit of HTTP over unix sockets vs IPC, which was answered by pinheadmz. A typo remark in rc:4412188649 was omitted as a nit.", "evidence": [ "winterrdog (question, scope, must be answered, open): Whether abstract namespace unix sockets should be supported in the future for Linux-specific setups.", "winterrdog (suggestion, maintenance, must be answered, open): Update the PR description to match the code regarding Unix socket path resolution.", "winterrdog: Concept ACK \u2014 users of other projects relying on Core have wanted Unix domain socket support, and previous libevent blockers are gone", "b-l-u-e: Concept ACK", "winterrdog: Approach ACK \u2014 convinced by the implementation and design choices, particularly using std::variant over polymorphism for SocketAddr; security is tight" ], "objections": [ { "reviewer": "b-l-u-e", "association": "CONTRIBUTOR", "type": "objection", "kind": "correctness", "harm": "A second node started with the same -rpcbind=unix: will overwrite the live socket file without error, making the first node unreachable while it remains running.", "request": "", "question": "", "text": "A second node started with the same -rpcbind=unix: will overwrite the live socket file without error, making the first node unreachable while it remains running.", "clears_with": "change", "blocking": true, "status": "fixed", "status_note": "author pushed changes adopting ipcbind parameter format to make sockets datadir-scoped by default", "cleared": true, "author_replied": true, "others_replied": false, "fix_pushed": true, "replies": [ "c:6062694537" ], "evidence": "2026-10-05: 'second node can take over a live rpc unix socket path, if two nodes use different datadirs but the same -rpcbind=unix: the second node starts with no error..since it removes the first node socke'", "url": "https://github.com/bitcoin/bitcoin/pull/36434#issuecomment-5993254913", "id": "c:5993254913", "at": "2026-10-05", "status_at": "2026-10-08", "status_by": "pinheadmz", "resolution_evidence": "2026-10-08: pinheadmz: 'This should also adderss @b-l-u-e concern about multiple processes messing with each others sockets.'", "pin": null, "from_schema": 2 }, { "reviewer": "b-l-u-e", "association": "CONTRIBUTOR", "type": "objection", "kind": "interface", "harm": "bitcoin-cli sends the resolved IP in the HTTP Host header instead of the hostname passed via -rpcconnect=, introducing a behavior change/regression from master.", "request": "", "question": "", "text": "bitcoin-cli sends the resolved IP in the HTTP Host header instead of the hostname passed via -rpcconnect=, introducing a behavior change/regression from master.", "clears_with": "change", "blocking": true, "status": "fixed", "status_note": "author pushed fix for Host header in bitcoin-cli", "cleared": true, "author_replied": true, "others_replied": false, "fix_pushed": true, "replies": [ "c:6062694537" ], "evidence": "2026-10-05: 'the host header contains the resolved IP instead of the hostname given in `-rpcconnect=localhost`'", "url": "https://github.com/bitcoin/bitcoin/pull/36434#issuecomment-5999886903", "id": "c:5999886903", "at": "2026-10-05", "status_at": "2026-10-08", "status_by": "pinheadmz", "resolution_evidence": "2026-10-08: pinheadmz: 'fix `\"Host:` header in bitcoin-cli (@b-l-u-e)'", "pin": null, "from_schema": 2 }, { "reviewer": "winterrdog", "association": "CONTRIBUTOR", "type": "objection", "kind": "correctness", "harm": "On platforms where char is signed, non-ASCII UTF-8 bytes wrap to negative values and match c < 0x20, causing valid UTF-8 paths like /tmp/jos\u00e9.sock to be replaced with \"unix\" in logs.", "request": "", "question": "", "text": "On platforms where char is signed, non-ASCII UTF-8 bytes wrap to negative values and match c < 0x20, causing valid UTF-8 paths like /tmp/jos\u00e9.sock to be replaced with \"unix\" in logs.", "clears_with": "change", "blocking": true, "status": "fixed", "status_note": "author fixed using unsigned char and std::ranges in push e34ffb6de9", "cleared": true, "author_replied": true, "others_replied": false, "fix_pushed": true, "replies": [ "rc:4405304914" ], "evidence": "2026-10-11: 'char is signed on some platforms (e.g. x86), so bytes above 0x7f are interpreted as negative values (they wrap around) and also match c < 0x20. this means a utf-8 path like /tmp/jos\u00e9.sock could end up'", "url": "https://github.com/bitcoin/bitcoin/pull/36434#discussion_r4239802579", "id": "rc:4239802579", "at": "2026-10-11", "status_at": "2026-10-28", "status_by": "pinheadmz", "resolution_evidence": "2026-10-28: pinheadmz: 'good suggestion thanks, using `std::ranges` and `unsigned char` here'", "pin": null, "from_schema": 2 }, { "reviewer": "winterrdog", "association": "CONTRIBUTOR", "type": "suggestion", "kind": "approach", "harm": "", "request": "Place Unix socket handling code behind an #ifdef HAVE_SOCKADDR_UN guard to avoid compiling unused code on unsupported platforms.", "question": "", "text": "Place Unix socket handling code behind an #ifdef HAVE_SOCKADDR_UN guard to avoid compiling unused code on unsupported platforms.", "clears_with": "answer", "blocking": false, "status": "fixed", "status_note": "author added compile guard in push e34ffb6de9", "cleared": true, "author_replied": true, "others_replied": false, "fix_pushed": true, "replies": [ "rc:4405247453" ], "evidence": "2026-10-14: 'why don't we just put this behind an #ifdef HAVE_SOCKADDR_UN guard so we skip this code entirely on platforms that do not support unix sockets ?'", "url": "https://github.com/bitcoin/bitcoin/pull/36434#discussion_r4276497992", "id": "rc:4276497992", "at": "2026-10-14", "status_at": "2026-10-28", "status_by": "pinheadmz", "resolution_evidence": "2026-10-28: pinheadmz: 'yep fair enough, putting behind a compile guard'", "pin": null, "from_schema": 2 }, { "reviewer": "winterrdog", "association": "CONTRIBUTOR", "type": "suggestion", "kind": "interface", "harm": "", "request": "Log host instead of strRPCBind in the bind failure warning to avoid redundant port strings when a port is included in the address.", "question": "", "text": "Log host instead of strRPCBind in the bind failure warning to avoid redundant port strings when a port is included in the address.", "clears_with": "answer", "blocking": false, "status": "fixed", "status_note": "author resolved this along with the GetBindAddresses refactor", "cleared": true, "author_replied": true, "others_replied": false, "fix_pushed": true, "replies": [ "rc:4405179611" ], "evidence": "2026-10-15: 'strRPCBind can show up in the logs if the optional port is included in the bind address (e.g. 127.0.0.1:8332), leading to logs like this one: Could not bind RPC on address 127.0.0.1:8332 port 8332: Ad'", "url": "https://github.com/bitcoin/bitcoin/pull/36434#discussion_r4286800301", "id": "rc:4286800301", "at": "2026-10-15", "status_at": "2026-10-28", "status_by": "pinheadmz", "resolution_evidence": "2026-10-28: pinheadmz: 'fixed this along with the `GetBindAddresses()` refactor.'", "pin": null, "from_schema": 2 }, { "reviewer": "winterrdog", "association": "CONTRIBUTOR", "type": "question", "kind": "correctness", "harm": "", "request": "", "question": "Whether duplicate -rpcbind unix socket endpoints unlinking the earlier socket and rebinding silently without warning is intended behavior or should fail like TCP.", "text": "Whether duplicate -rpcbind unix socket endpoints unlinking the earlier socket and rebinding silently without warning is intended behavior or should fail like TCP.", "clears_with": "answer", "blocking": false, "status": "answered", "status_note": "author replied that duplicate binds are considered an acceptable edge case", "cleared": true, "author_replied": true, "others_replied": false, "fix_pushed": false, "replies": [ "rc:4405162282" ], "evidence": "2026-10-15: 'if two -rpcbind values resolve to the same path (e.g. -rpcbind=unix and -rpcbind=unix:http.sock, or the same value in bitcoin.conf and perhaps on the command line), PreparePath() (later called in HTTP'", "url": "https://github.com/bitcoin/bitcoin/pull/36434#discussion_r4287174385", "id": "rc:4287174385", "at": "2026-10-15", "status_at": "2026-10-28", "status_by": "pinheadmz", "resolution_evidence": "2026-10-28: pinheadmz: 'Heh that's kind of a funny edge case. We don't complain if a user sets `-rpcport=50000` twice for example. I think it's '", "pin": null, "from_schema": 2 }, { "reviewer": "winterrdog", "association": "CONTRIBUTOR", "type": "question", "kind": "scope", "harm": "", "request": "", "question": "Whether abstract namespace unix sockets should be supported in the future for Linux-specific setups.", "text": "Whether abstract namespace unix sockets should be supported in the future for Linux-specific setups.", "clears_with": "answer", "blocking": false, "status": "open", "status_note": "", "cleared": false, "author_replied": false, "others_replied": false, "fix_pushed": false, "replies": [], "evidence": "2026-10-16: 'i saw UnixSocketAddr::SetSockAddr() handles empty and abstract namespace addresses, but we do not support binding or connecting to abstract sockets. do you think it is worth supporting them in the fut'", "url": "https://github.com/bitcoin/bitcoin/pull/36434#pullrequestreview-5478881949", "id": "r:5478881949", "at": "2026-10-16", "status_at": null, "status_by": null, "resolution_evidence": "", "pin": null, "from_schema": 2 }, { "reviewer": "winterrdog", "association": "CONTRIBUTOR", "type": "suggestion", "kind": "maintenance", "harm": "", "request": "Update the PR description to match the code regarding Unix socket path resolution.", "question": "", "text": "Update the PR description to match the code regarding Unix socket path resolution.", "clears_with": "answer", "blocking": false, "status": "open", "status_note": "", "cleared": false, "author_replied": false, "others_replied": false, "fix_pushed": false, "replies": [], "evidence": "2026-10-16: 'the docs, release notes and -help text already match the code, so i think the PR description just needs updating to reflect this, so other reviewers do not get tripped up by the mismatch'", "url": "https://github.com/bitcoin/bitcoin/pull/36434#pullrequestreview-5478881949", "id": "r:5478881949#2", "at": "2026-10-16", "status_at": null, "status_by": null, "resolution_evidence": "", "pin": null, "from_schema": 2 }, { "reviewer": "winterrdog", "association": "CONTRIBUTOR", "type": "suggestion", "kind": "maintenance", "harm": "", "request": "Refactor GetBindAddresses() to reduce cognitive load and streamline the control flow.", "question": "", "text": "Refactor GetBindAddresses() to reduce cognitive load and streamline the control flow.", "clears_with": "answer", "blocking": false, "status": "fixed", "status_note": "author adopted the suggested refactor with tweaks in push e34ffb6de9", "cleared": true, "author_replied": true, "others_replied": false, "fix_pushed": true, "replies": [ "rc:4405115790" ], "evidence": "2026-10-16: 'while reviewing GetBindAddresses(), i ended up rewriting it to lower the cognitive load a bit and help me get my head around the flow. thought i could share it and see what you think'", "url": "https://github.com/bitcoin/bitcoin/pull/36434#discussion_r4292770911", "id": "rc:4292770911", "at": "2026-10-16", "status_at": "2026-10-28", "status_by": "pinheadmz", "resolution_evidence": "2026-10-28: pinheadmz: 'I think it's a good idea to clean this up now, thanks. Taking the suggestion and tweaking a bit more on top (comments an'", "pin": null, "from_schema": 2 }, { "reviewer": "hodlinator", "association": "MEMBER", "type": "question", "kind": "usefulness", "harm": "", "request": "", "question": "What is the benefit of allowing HTTP over unix sockets compared to using IPC over unix sockets, given executeRpc() is already exposed through IPC?", "text": "What is the benefit of allowing HTTP over unix sockets compared to using IPC over unix sockets, given executeRpc() is already exposed through IPC?", "clears_with": "answer", "blocking": false, "status": "answered", "status_note": "author explained that unix sockets do not require capnproto or multiprocess mode and have a lower barrier to entry", "cleared": true, "author_replied": true, "others_replied": false, "fix_pushed": false, "replies": [ "c:6497954399" ], "evidence": "2026-10-29: 'What is the benefit of allowing HTTP over unix sockets compared to using IPC over unix sockets?'", "url": "https://github.com/bitcoin/bitcoin/pull/36434#pullrequestreview-5697528630", "id": "r:5697528630", "at": "2026-10-29", "status_at": "2026-10-29", "status_by": "pinheadmz", "resolution_evidence": "2026-10-29: pinheadmz: 'You get the security advantage and possibly an efficiency advantage with a very low bar for entry. IPC requires capnproto, unix sockets only require platform support.'", "pin": null, "from_schema": 2 } ], "support": [ { "reviewer": "winterrdog", "reason": "users of other projects relying on Core have wanted Unix domain socket support, and previous libevent blockers are gone", "substantive": true, "verdict": "Concept ACK", "id": "r:5408186323", "url": "https://github.com/bitcoin/bitcoin/pull/36434#pullrequestreview-5408186323", "at": "2026-10-04", "association": "CONTRIBUTOR", "evidence": "read", "areas": [] }, { "reviewer": "b-l-u-e", "reason": "", "substantive": false, "verdict": "Concept ACK", "id": "c:5993254913", "url": "https://github.com/bitcoin/bitcoin/pull/36434#issuecomment-5993254913", "at": "2026-10-05", "association": "CONTRIBUTOR", "evidence": "none", "areas": [] }, { "reviewer": "winterrdog", "reason": "convinced by the implementation and design choices, particularly using std::variant over polymorphism for SocketAddr; security is tight", "substantive": true, "verdict": "Approach ACK", "id": "r:5478881949", "url": "https://github.com/bitcoin/bitcoin/pull/36434#pullrequestreview-5478881949", "at": "2026-10-16", "association": "CONTRIBUTOR", "evidence": "read", "areas": [] } ], "participants": [ { "login": "winterrdog", "stance": "objection", "note": "Approach ACK; raised signed char bug (fixed), suggestions on compile guard and refactoring, and questions", "association": "CONTRIBUTOR", "comments": 12, "first": "2026-10-04", "last": "2026-10-16" }, { "login": "b-l-u-e", "stance": "objection", "note": "Concept ACK; reported socket takeover on collision and Host header regression (both fixed)", "association": "CONTRIBUTOR", "comments": 2, "first": "2026-10-05", "last": "2026-10-05" }, { "login": "hodlinator", "stance": "question", "note": "asked about the benefits of HTTP over unix sockets compared to IPC", "association": "MEMBER", "comments": 2, "first": "2026-10-29", "last": "2026-10-29" } ], "derivation": "substantive support, no open objection (winterrdog, winterrdog)", "model_state": null, "corrections": [], "notes": "Added hodlinator as a participant and recorded their question about the benefit of HTTP over unix sockets vs IPC, which was answered by pinheadmz. A typo remark in rc:4412188649 was omitted as a nit." }, "dependencies": { "depends_on": [], "enables": [] }, "categories": [ { "name": "docs", "member": false, "evidence": "Doc changes in doc/JSON-RPC-interface.md and release notes follow the RPC implementation rather than documentation being the primary change.", "band": "Unranked", "reason_tag": "cleanup", "score": 0.0, "factors": { "bug_severity": 0, "leverage": 1, "performance": 1, "security_stability": 1, "user_value": 2 }, "rationale": "Follow-up documentation changes for a code feature do not make the PR a member of docs." }, { "name": "p2p", "member": false, "evidence": "Changes in src/netbase.cpp and src/netbase.h update low-level socket abstractions to support local UNIX sockets, not node-to-node P2P transport, peer selection, or relay.", "band": "Unranked", "reason_tag": "cleanup", "score": 0.0, "factors": { "bug_severity": 0, "leverage": 1, "performance": 1, "security_stability": 1, "user_value": 2 }, "rationale": "The PR affects local RPC server transport and proxy abstractions rather than P2P message protocol or peer networking." }, { "name": "rpc", "member": true, "evidence": "Carries the RPC/REST/ZMQ label and directly modifies src/httpserver.cpp, src/bitcoin-cli.cpp, and RPC configuration handling.", "band": "P2", "reason_tag": "user request", "score": 0.68, "factors": { "bug_severity": 0, "leverage": 1, "performance": 1, "security_stability": 1, "user_value": 2 }, "rationale": "Closes a decade-old feature request (#5029) to support UNIX domain sockets for the HTTP RPC server and bitcoin-cli. This provides substantial user value by allowing filesystem permissions instead of IP allowlists and eliminating TCP loopback overhead." }, { "name": "tests", "member": false, "evidence": "Modifications to test framework files (test_node.py, authproxy.py) merely support test coverage for the RPC UNIX socket feature.", "band": "Unranked", "reason_tag": "test coverage", "score": 0.0, "factors": { "bug_severity": 0, "leverage": 1, "performance": 1, "security_stability": 1, "user_value": 2 }, "rationale": "Changes to test utilities that follow directly from testing an RPC feature belong to RPC, not general test infrastructure." }, { "name": "utils", "member": false, "evidence": "Changes to src/init.cpp and netbase primitives exist to serve RPC and proxy configuration rather than general node-wide utilities.", "band": "Unranked", "reason_tag": "cleanup", "score": 0.0, "factors": { "bug_severity": 0, "leverage": 1, "performance": 1, "security_stability": 1, "user_value": 2 }, "rationale": "Settings and socket changes whose point is another specific area's behavior belong to that area." } ], "confidence": "high", "uncertainties": [], "needs": [] }, "cost_usd": 0.0, "source": { "record": "2026-10-30T01:14:01+00:00", "code": "2026-10-30T01:17:00+00:00", "judgments": 5 } }