Skip to main content
21.6k
The /tmp Trap: How One Hardcoded Path Broke py-libp2p on Windows

The /tmp Trap: How One Hardcoded Path Broke py-libp2p on Windows

py-libp2p cross-platform windows
by Yash Kumar Saini 5 min read

A Crash Before the First Packet

Picture this: you're a Windows developer trying out py-libp2p for the first time. You set LIBP2P_DEBUG=INFO to see what's happening under the hood. The library crashes — not during a handshake, not during peer discovery, but while trying to open a log file. The culprit is a line that's been sitting in the codebase since the logging module was written:

log_file = f"/tmp/py-libp2p_{timestamp}_{unique_id}.log"

A Unix path, hardcoded into a library that claims to support all platforms. In this PR, I replaced this and other scattered platform-specific paths with a single, centralized cross-platform toolkit — and shipped an audit script to make sure no hardcoded paths sneak back in.

Background

py-libp2p is the Python implementation of libp2p, the modular peer-to-peer networking framework behind IPFS and Filecoin. Like any networking library, it needs to work everywhere Python runs — Linux, macOS, and Windows.

Python offers two approaches to path handling. The older os.path module treats paths as strings: you call os.path.join(), os.path.dirname(), and hope you never forget and concatenate with / instead. The newer pathlib module (Python 3.4+) represents paths as objects that handle OS-specific separators automatically. The / operator replaces string concatenation, and methods like .parent and .resolve() replace verbose function chains. The general rule: if you're writing new code, use pathlib. If you're maintaining old code, migrate when you touch it.

The Problem

Issue #882 documented the state of affairs. A previous attempt (PR #792) had introduced a paths.py utility module, but only wired it into test utilities. Core modules and examples were still doing their own thing.

The worst offender was libp2p/utils/logging.py:

if os.name == "nt":  # Windows
    log_file = f"C:\\Windows\\Temp\\py-libp2p_{timestamp}.log"
else:  # Unix
    log_file = f"/tmp/py-libp2p_{timestamp}.log"

This pattern — branching on os.name to pick a hardcoded path — is the classic platform if/else anti-pattern. It breaks when assumptions about directory structure don't hold (macOS doesn't always use /tmp; Windows may restrict C:\Windows\Temp). And it requires every developer to remember both branches.

The kademlia example had a different flavor of the same problem:

SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
SERVER_ADDR_LOG = os.path.join(SCRIPT_DIR, "server_node_addr.txt")

Not broken per se, but scattered os.path calls with no standardization — every module reinventing the same wheel.

Before PR #886: each module handled paths independently, with hardcoded platform branches or raw os.path calls.

Before after path construction

The Solution

The fix came in three parts: build the toolkit, migrate the critical modules, audit the rest.

Part 1: The toolkit. I built the new libp2p/utils/paths.py with 15 functions built on pathlib and Python's tempfile module. The key ones:

Every function returns a Path object. No strings, no separators, no platform branches at the call site.

Part 2: Migration. The logging module's hardcoded temp path became a single line:

-        if os.name == "nt":  # Windows
-            log_file = f"C:\\Windows\\Temp\\py-libp2p_{timestamp}_{unique_id}.log"
-        else:  # Unix-like
-            log_file = f"/tmp/py-libp2p_{timestamp}_{unique_id}.log"
+        from libp2p.utils.paths import create_temp_file
+        log_file = str(create_temp_file(prefix="py-libp2p_", suffix=".log"))

Six lines of platform branching replaced by one function call. The kademlia example got a similar treatment:

-SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
-SERVER_ADDR_LOG = os.path.join(SCRIPT_DIR, "server_node_addr.txt")
+SCRIPT_DIR = get_script_dir(__file__)
+SERVER_ADDR_LOG = join_paths(SCRIPT_DIR, "server_node_addr.txt")

I also added proper handler cleanup in the logging module — closing FileHandler instances on exit — which prevents file-lock issues on Windows where open files can't be deleted.

Part 3: The audit script. I wrote scripts/audit_paths.py to scan the entire codebase for six anti-patterns: hardcoded /tmp, os.path.join(), os.path.dirname(), os.path.abspath(), string path concatenation, and hardcoded forward slashes. It outputs a priority matrix — P0 for hardcoded temp paths, P1 for os.path usage, P2 for style inconsistencies — so the next contributor knows exactly where to start.

The audit script identifies remaining path anti-patterns and prioritizes them for migration in future PRs.

Audit pipeline

Before & After

BeforeAfter
Temp file creationHardcoded /tmp or C:\Windows\Tempcreate_temp_file() via tempfile
Script directoryos.path.dirname(os.path.abspath())get_script_dir(__file__)
Path joiningos.path.join() (string-based)join_paths() (pathlib-based)
Config directoryNot standardizedget_config_dir() (per-platform)
File handle cleanupMissing on exitExplicit FileHandler.close()
Remaining issue discoveryManualaudit_paths.py with priority matrix
Test coverageNo path utility tests19 tests across 3 test classes
Platform verificationLinux onlyLinux + macOS + Windows 10

Lessons Learned

Build the toolkit before you migrate. PR #792 tried to introduce utilities and migrate code in the same breath — it stalled. My PR succeeded by first completing the paths.py module with comprehensive tests, then migrating modules one by one. When the utility layer is solid and tested, each migration becomes a trivial find-and-replace. The temptation is to "just fix the one broken path," but that leads to fifteen one-off fixes instead of one reusable abstraction.

An audit script is a gift to your future self. The audit_paths.py script doesn't just find current problems — it prevents regressions. Any contributor can run it before opening a PR. It transforms "did I miss any hardcoded paths?" from a manual code review question into an automated check. The script found six categories of path anti-patterns and ranked them by severity. That priority matrix became the roadmap for future work.

Conclusion

This PR eliminates the class of bugs where py-libp2p silently fails on non-Linux platforms because someone wrote /tmp instead of using tempfile. With 668 tests passing across Linux, macOS, and Windows, the library's cross-platform story went from "works on my machine" to verified on three. The audit script ensures this stays true. Sometimes the most impactful refactoring isn't glamorous — it's replacing six lines of platform branching with one function call that does the right thing everywhere.

Resources

If you would like to contribute, please connect with the libp2p maintainers.