feat: implementing p2p-circuit (#74)

* feat: implementing p2p-circuit

* chore: add comments to tests

Author: acul71

multiaddr/multiaddr.py

@@ -360,9 +360,11 @@ def _from_string(self, addr: str) -> None:
                     try:
                         self._bytes += varint.encode(proto.code)
                         buf = codec.to_bytes(proto, value)
+                        # Add length prefix for variable-sized or zero-sized codecs
                         if codec.SIZE <= 0:
                             self._bytes += varint.encode(len(buf))
-                        self._bytes += buf
+                        if buf:  # Only append buffer if it's not empty
+                            self._bytes += buf
                     except Exception as e:
                         raise exceptions.StringParseError(str(e), addr) from e
                     continue
@@ -408,10 +410,17 @@ def _from_string(self, addr: str) -> None:
 
             try:
                 self._bytes += varint.encode(proto.code)
+
+                # Special case: protocols with codec=None are flag protocols
+                # (no value, no length prefix, no buffer)
+                if proto.codec is None:
+                    continue
+
                 buf = codec.to_bytes(proto, value or "")
-                if codec.SIZE <= 0:
+                if codec.SIZE <= 0:  # Add length prefix for variable-sized or zero-sized codecs
                     self._bytes += varint.encode(len(buf))
-                self._bytes += buf
+                if buf:  # Only append buffer if it's not empty
+                    self._bytes += buf
             except Exception as e:
                 raise exceptions.StringParseError(str(e), addr) from e
 
@@ -432,13 +441,36 @@ def _from_bytes(self, addr: bytes) -> None:
     def get_peer_id(self) -> Optional[str]:
         """Get the peer ID from the multiaddr.
 
+        For circuit addresses, returns the target peer ID, not the relay peer ID.
+
         Returns:
             The peer ID if found, None otherwise.
 
         Raises:
             BinaryParseError: If the binary multiaddr is invalid.
         """
         try:
-            return self.value_for_protocol(protocol_with_name("p2p").code)
-        except ValueError:
+            tuples = []
+
+            for _, proto, codec, part in bytes_iter(self._bytes):
+                if proto.name == "p2p":
+                    tuples.append((proto, part))
+
+                # If this is a p2p-circuit address, reset tuples to get target peer id
+                # not the peer id of the relay
+                if proto.name == "p2p-circuit":
+                    tuples = []
+
+            # Get the last p2p tuple (target peer ID for circuits)
+            if tuples:
+                last_tuple = tuples[-1]
+                proto, part = last_tuple
+                # Get the codec for this specific protocol
+                codec = codec_by_name(proto.codec)
+                # Handle both fixed-size and variable-sized codecs
+                if codec is not None and codec.SIZE != 0:
+                    return codec.to_string(proto, part)
+
+            return None
+        except Exception:
             return None

multiaddr/transforms.py

@@ -20,14 +20,22 @@ def string_to_bytes(string: str) -> bytes:
         )
         logger.debug(
             f"[DEBUG string_to_bytes] Processing: proto={proto.name}, "
-            f"codec.SIZE={getattr(codec, 'SIZE', None)}, value={value}"
+            f"codec.SIZE={getattr(codec, 'SIZE', None) if codec else None}, value={value}"
         )
         logger.debug(f"[DEBUG string_to_bytes] Protocol code: {proto.code}")
         encoded_code = varint.encode(proto.code)
         logger.debug(f"[DEBUG string_to_bytes] Encoded protocol code: {encoded_code}")
         bs.append(encoded_code)
+
+        # Special case: protocols with codec=None are flag protocols
+        # (no value, no length prefix, no buffer)
         if codec is None:
-            raise ValueError(f"Unknown codec for protocol {proto.name}")
+            logger.debug(
+                f"[DEBUG string_to_bytes] Protocol {proto.name} has no data, "
+                "skipping value encoding"
+            )
+            continue
+
         if value is None:
             raise ValueError("Value cannot be None")
         try:
@@ -41,12 +49,15 @@ def string_to_bytes(string: str) -> bytes:
             f"[DEBUG string_to_bytes] Appending: proto={proto.name}, "
             f"codec.SIZE={getattr(codec, 'SIZE', None)}"
         )
+        # Only add length prefix for variable-sized codecs (SIZE <= 0)
         if codec.SIZE <= 0:
             bs.append(varint.encode(len(buf)))
             logger.debug(
                 f"[DEBUG string_to_bytes] Appending varint length: {varint.encode(len(buf))}"
             )
-        bs.append(buf)
+        # Only append the buffer if it's not empty
+        if buf:
+            bs.append(buf)
         logger.debug(f"[DEBUG string_to_bytes] Final bs: {bs}")
     return b"".join(bs)
 
@@ -103,7 +114,7 @@ def size_for_addr(codec: CodecBase, buf_io: io.BytesIO) -> int:
 
 
 def string_iter(
-    string: str
+    string: str,
 ) -> Generator[tuple[Protocol, CodecBase | None, str | None], None, None]:
     """Iterate over the parts of a string multiaddr.
 
@@ -136,12 +147,10 @@ def string_iter(
             value = parts[i + 1]
             i += 1  # Skip the next part since we used it as value
             logger.debug(f"[DEBUG string_iter] Using next part as value: {value}")
+            yield proto, codec, value
         else:
             logger.debug(f"[DEBUG string_iter] No value found for protocol {proto.name}")
-        logger.debug(
-            f"[DEBUG string_iter] Yielding: proto={proto.name}, codec={codec}, value={value}"
-        )
-        yield proto, codec, value
+            yield proto, codec, None
         i += 1
 
 

ruff.toml

@@ -20,4 +20,7 @@ dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 quote-style = "double"
 indent-style = "space"
 skip-magic-trailing-comma = false
-line-ending = "lf"
+line-ending = "lf"
+
+[lint.per-file-ignores]
+"tests/test_multiaddr.py" = ["E501"]

tests/test_multiaddr.py

@@ -242,9 +242,11 @@ def assert_value_for_proto(multi, proto, expected):
 @pytest.mark.parametrize(
     "addr_str,proto,expected",
     [
-        ("/ip4/127.0.0.1/tcp/4001/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC",
-         "p2p",
-         "QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC"),
+        (
+            "/ip4/127.0.0.1/tcp/4001/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC",
+            "p2p",
+            "QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC",
+        ),
         ("/ip4/127.0.0.1/tcp/4001", "tcp", "4001"),
         ("/ip4/127.0.0.1/tcp/4001", "ip4", "127.0.0.1"),
         ("/ip4/127.0.0.1/tcp/4001", "udp", None),
@@ -264,8 +266,7 @@ def test_get_value(addr_str, proto, expected):
 
 def test_get_value_original():
     ma = Multiaddr(
-        "/ip4/127.0.0.1/tcp/5555/udp/1234/"
-        "p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC"
+        "/ip4/127.0.0.1/tcp/5555/udp/1234/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC"
     )
 
     assert_value_for_proto(ma, P_IP4, "127.0.0.1")
@@ -436,3 +437,153 @@ def test_sequence_behavior():
         list(ma.items())[len(ma)]
     with pytest.raises(IndexError):
         list(ma.values())[len(ma)]
+
+
+def test_circuit_peer_id_extraction():
+    """Test that get_peer_id() returns the correct peer ID for circuit addresses."""
+
+    # Basic circuit address - should return target peer ID
+    ma = Multiaddr("/p2p-circuit/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC")
+    assert ma.get_peer_id() == "QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC"
+
+    # Circuit with relay - should return target peer ID, not relay peer ID
+    ma = Multiaddr(
+        "/ip4/0.0.0.0/tcp/8080/p2p/QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6/p2p-circuit/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC"
+    )
+    assert ma.get_peer_id() == "QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC"
+
+    # Circuit without target peer ID - should return None
+    ma = Multiaddr(
+        "/ip4/127.0.0.1/tcp/123/p2p/QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6/p2p-circuit"
+    )
+    assert ma.get_peer_id() is None
+
+    # Input: bafzbeigweq4zr4x4ky2dvv7nanbkw6egutvrrvzw6g3h2rftp7gidyhtt4 (CIDv1 Base32)
+    # Expected: QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi (CIDv0 Base58btc)
+    ma = Multiaddr("/p2p-circuit/p2p/bafzbeigweq4zr4x4ky2dvv7nanbkw6egutvrrvzw6g3h2rftp7gidyhtt4")
+    assert ma.get_peer_id() == "QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi"
+
+    # Base58btc encoded identity multihash (no conversion needed)
+    ma = Multiaddr("/p2p-circuit/p2p/12D3KooWNvSZnPi3RrhrTwEY4LuuBeB6K6facKUCJcyWG1aoDd2p")
+    assert ma.get_peer_id() == "12D3KooWNvSZnPi3RrhrTwEY4LuuBeB6K6facKUCJcyWG1aoDd2p"
+
+
+def test_circuit_peer_id_edge_cases():
+    """Test edge cases for circuit peer ID extraction."""
+
+    # Multiple circuits - should return the target peer ID after the last circuit
+    # Input: bafzbeigweq4zr4x4ky2dvv7nanbkw6egutvrrvzw6g3h2rftp7gidyhtt4 (CIDv1 Base32)
+    # Expected: QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi (CIDv0 Base58btc)
+    ma = Multiaddr(
+        "/ip4/1.2.3.4/tcp/1234/p2p/QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6/p2p-circuit/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC/p2p-circuit/p2p/bafzbeigweq4zr4x4ky2dvv7nanbkw6egutvrrvzw6g3h2rftp7gidyhtt4"
+    )
+    assert ma.get_peer_id() == "QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi"
+
+    # Circuit with multiple p2p components after it
+    # Input: bafzbeigweq4zr4x4ky2dvv7nanbkw6egutvrrvzw6g3h2rftp7gidyhtt4 (CIDv1 Base32)
+    # Expected: QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi (CIDv0 Base58btc)
+    ma = Multiaddr(
+        "/ip4/1.2.3.4/tcp/1234/p2p/QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6/p2p-circuit/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC/p2p/bafzbeigweq4zr4x4ky2dvv7nanbkw6egutvrrvzw6g3h2rftp7gidyhtt4"
+    )
+    assert ma.get_peer_id() == "QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi"
+
+    # Circuit at the beginning (invalid but should handle gracefully)
+    ma = Multiaddr("/p2p-circuit/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC")
+    assert ma.get_peer_id() == "QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC"
+
+    # No p2p components at all
+    ma = Multiaddr("/ip4/127.0.0.1/tcp/1234")
+    assert ma.get_peer_id() is None
+
+    # Only relay peer ID, no target
+    ma = Multiaddr(
+        "/ip4/127.0.0.1/tcp/1234/p2p/QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6/p2p-circuit"
+    )
+    assert ma.get_peer_id() is None
+
+
+def test_circuit_address_parsing():
+    """Test that circuit addresses can be parsed correctly."""
+
+    # Basic circuit address
+    ma = Multiaddr("/p2p-circuit/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC")
+    assert str(ma) == "/p2p-circuit/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC"
+
+    # Circuit with relay
+    ma = Multiaddr(
+        "/ip4/0.0.0.0/tcp/8080/p2p/QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6/p2p-circuit/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC"
+    )
+    assert "p2p-circuit" in str(ma)
+    assert "QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC" in str(ma)
+
+    # Input: bafzbeigweq4zr4x4ky2dvv7nanbkw6egutvrrvzw6g3h2rftp7gidyhtt4 (CIDv1 Base32)
+    # Expected: QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi (CIDv0 Base58btc)
+    ma = Multiaddr(
+        "/ip4/127.0.0.1/tcp/1234/tls/p2p/QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6/p2p-circuit/p2p/bafzbeigweq4zr4x4ky2dvv7nanbkw6egutvrrvzw6g3h2rftp7gidyhtt4"
+    )
+    assert (
+        str(ma)
+        == "/ip4/127.0.0.1/tcp/1234/tls/p2p/QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6/p2p-circuit/p2p/QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi"
+    )
+
+
+def test_circuit_address_manipulation():
+    """Test circuit address manipulation (encapsulate/decapsulate)."""
+
+    # Input: bafzbeigweq4zr4x4ky2dvv7nanbkw6egutvrrvzw6g3h2rftp7gidyhtt4 (CIDv1 Base32)
+    # Expected: QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi (CIDv0 Base58btc)
+    relay = Multiaddr("/ip4/127.0.0.1/tcp/1234/p2p/QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6")
+    circuit = Multiaddr(
+        "/p2p-circuit/p2p/bafzbeigweq4zr4x4ky2dvv7nanbkw6egutvrrvzw6g3h2rftp7gidyhtt4"
+    )
+    combined = relay.encapsulate(circuit)
+    assert (
+        str(combined)
+        == "/ip4/127.0.0.1/tcp/1234/p2p/QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6/p2p-circuit/p2p/QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi"
+    )
+    assert combined.get_peer_id() == "QmckZzdVd72h9QUFuJJpQqhsZqGLwjhh81qSvZ9BhB2FQi"
+
+    # Decapsulate circuit
+    decapsulated = combined.decapsulate("/p2p-circuit")
+    assert (
+        str(decapsulated)
+        == "/ip4/127.0.0.1/tcp/1234/p2p/QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6"
+    )
+    assert decapsulated.get_peer_id() == "QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6"
+
+
+def test_circuit_with_consistent_cid_format():
+    """Test circuit functionality using consistent CIDv0 format for easier comparison."""
+
+    # All peer IDs in CIDv0 Base58btc format for easy visual comparison
+    relay_peer_id = "QmZR5a9AAXGqQF2ADqoDdGS8zvqv8n3Pag6TDDnTNMcFW6"
+    target_peer_id = "QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC"
+
+    # Basic circuit with consistent format
+    ma = Multiaddr(f"/p2p-circuit/p2p/{target_peer_id}")
+    assert ma.get_peer_id() == target_peer_id
+
+    # Circuit with relay using consistent format
+    ma = Multiaddr(f"/ip4/127.0.0.1/tcp/1234/p2p/{relay_peer_id}/p2p-circuit/p2p/{target_peer_id}")
+    assert ma.get_peer_id() == target_peer_id
+
+    # Test string representation preserves format
+    assert (
+        str(ma) == f"/ip4/127.0.0.1/tcp/1234/p2p/{relay_peer_id}/p2p-circuit/p2p/{target_peer_id}"
+    )
+
+    # Test encapsulate/decapsulate with consistent format
+    relay = Multiaddr(f"/ip4/127.0.0.1/tcp/1234/p2p/{relay_peer_id}")
+    circuit = Multiaddr(f"/p2p-circuit/p2p/{target_peer_id}")
+    combined = relay.encapsulate(circuit)
+
+    assert (
+        str(combined)
+        == f"/ip4/127.0.0.1/tcp/1234/p2p/{relay_peer_id}/p2p-circuit/p2p/{target_peer_id}"
+    )
+    assert combined.get_peer_id() == target_peer_id
+
+    # Decapsulate should return relay address
+    decapsulated = combined.decapsulate("/p2p-circuit")
+    assert str(decapsulated) == f"/ip4/127.0.0.1/tcp/1234/p2p/{relay_peer_id}"
+    assert decapsulated.get_peer_id() == relay_peer_id