feat: b64 encoding for nixl_connect metadata

[milesial]

Overview:

Changes the encoding of the compressed NIXL agent metadata

Details:

hex encoding has an overhead of 100%, doubling the size of the actual data. This means that if the zlib compression ratio is less than 2x (which it seems to be in many cases), then the metadata send over the network after compression+encoding is even larger than the original metadata size.

Base64 has a 33% overhead and mitigates this while keeping the payload JSON-safe. Base85 could be another option with 25% overhead but I feel like base64 has more support for external integration and compatibility.

Example:

NIXL raw metadata: 670 bytes
After zlib:  366 bytes

Main: After hex: 732 bytes
This MR: After b64: 488 bytes

@whoisj

Summary by CodeRabbit

• Refactor
  • Updated internal data encoding mechanism for improved compatibility and transport efficiency. No user-facing functionality changes.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Walkthrough

The pull request modifies internal encoding mechanisms for NIXL metadata in the Python RDMA connection module, switching serialization from hexadecimal to base64 encoding in RdmaMetadata construction and Remote initialization paths. No public API changes were introduced.

Changes

Cohort / File(s)	Summary
RDMA metadata encoding migration lib/bindings/python/src/dynamo/nixl_connect/__init__.py	Modified nixl_metadata handling to use base64 encoding/decoding instead of hex format. Added base64 import and updated serialization in RdmaMetadata construction and Remote deserialization paths. Control flow and error handling logic remain unchanged.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Base64 hops in, hex takes a rest,
Metadata flows through compression's test,
From burrows to servers, the data takes flight,
Encoded and cozy, now perfectly right! ✨

Pre-merge checks

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "feat: b64 encoding for nixl_connect metadata" is concise, clear, and directly relates to the main change in the changeset. The raw summary confirms that the primary modification involves introducing base64 encoding/decoding for NIXL metadata instead of hex, and the title accurately captures this core change. The title is specific enough that a team member reviewing git history would immediately understand the purpose of this change without ambiguity.
Description Check	✅ Passed	The pull request description contains two of the four template sections: the Overview section clearly states the main change (switching from hex to base64 encoding), and the Details section provides comprehensive technical justification with specific overhead percentages, a rationale for choosing base64 over alternatives, and a concrete example showing byte size improvements (670 bytes raw, 366 after zlib, 732 with hex, 488 with base64). The "Where should the reviewer start?" and "Related Issues" sections are missing from the template structure; however, the core technical content is substantial and well-articulated, making the description mostly complete in the areas that matter most for understanding the change.

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7bb6368 and b864ef3.

📒 Files selected for processing (1)

• lib/bindings/python/src/dynamo/nixl_connect/__init__.py (3 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build and Test - dynamo

🔇 Additional comments (3)

lib/bindings/python/src/dynamo/nixl_connect/__init__.py (3)

19-19: LGTM!

The base64 import is correctly added to support the new encoding scheme.

---

1215-1215: Excellent optimization: hex to base64 encoding reduces overhead.

The change from hex encoding (100% overhead) to base64 encoding (33% overhead) significantly reduces the serialized payload size. The implementation correctly compresses with zlib, encodes to base64, and converts to a UTF-8 string for JSON compatibility.

---

1475-1481: LGTM! Symmetric decoding matches the encoding changes.

The decoding logic correctly reverses the encoding process: base64 decode followed by zlib decompress. The comments are accurate, and the type check at line 1477 ensures the string type before decoding. The implementation is symmetric with the encoding in PassiveOperation.metadata().

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ishandhanani]

This PR makes sense and looks good to me. But @whoisj should take a look as well

[whoisj]

while b64 encoding is a win in size, we cannot just change the encoding and walk away.

please add a method to fallback to hex encoding to retain compatability.

[milesial]

Added a fallback to hex in case people work with mismatched nixl_connect versions.

In some cases b64 and hex data cannot be distinguished so I added a small identifiable prefix for the new b64 encoding.

[whoisj]

code changes LGTM, but has this been tested using the multimodal examples?