feat(sdk,net): full std::net::TcpStream surface

[joshuajbouw]

Summary

Outbound TCP for capsules. Mirrors std::net::TcpStream end-to-end — every method a Rust binary expects on a connected TCP stream is available on the SDK side. WebSocket libraries, TLS wrappers, postgres drivers — anything generic over Read + Write — drops in unmodified.

Added

Free functions (low-level, one per WIT host fn)

• connect(host, port) -> StreamHandle — opens an outbound TCP connection. Capability-gated against Capsule.toml net_connect allowlist; SSRF airlock on resolved IP; 10s connect timeout.
• read_bytes(stream, max) -> Vec<u8> / write_bytes(stream, data) -> u32 — byte-stream read/write (no length-prefix framing).
• peek(stream, max) -> Vec<u8> — non-destructive read.
• shutdown(stream, Shutdown::{Read,Write,Both}) — half-close. Backed by socket2::SockRef for full direction support.
• peer_addr / local_addr — ip:port strings.
• set_nodelay / nodelay — TCP_NODELAY.
• set_read_timeout / read_timeout — Option<Duration>.
• set_write_timeout / write_timeout.
• set_ttl / ttl — IP TTL.

TcpStream facade

std::net::TcpStream-shaped wrapper around StreamHandle with std::io::Read + Write impls, RAII close-on-drop, and matching inherent methods (set_nodelay, peer_addr, shutdown(Shutdown::*), peek, timeouts, set_ttl).

use astrid_sdk::net::TcpStream;
use std::io::{Read, Write};

let mut sock = TcpStream::connect("fulcrum.unicity.network:443")?;
sock.set_nodelay(true)?;
sock.write_all(b"GET / HTTP/1.1\\r\\nHost: example.com\\r\\n\\r\\n")?;

Shutdown enum

Local mirror of std::net::Shutdown (Read / Write / Both), wired to the WIT shutdown-how enum.

Submodule

contracts/ bumped to feat/net-connect-tcp tip on canonical unicity-astrid/wit#5.

TLS

Out of scope — std::net::TcpStream doesn't ship TLS either. Capsules that need TLS bring their own crate (rustls, etc.) over this byte-stream surface, matching how native Rust binaries do it.

Refs

• RFC: unicity-astrid/rfcs#27
• WIT: unicity-astrid/wit#5
• Tracking issue: unicity-astrid/astrid#745

Verification

• cargo build/test/clippy -p astrid-sdk clean
• Doctest on TcpStream compiles

[gemini-code-assist]

Code Review

This pull request introduces outbound TCP support to the astrid-sdk, adding a low-level connect function and a high-level TcpStream facade that implements std::io::Read and std::io::Write. The WIT interface has been expanded to include new functions for byte-stream operations, peeking, and socket options like TTL and Nagle's algorithm. Feedback identifies a critical issue where the Read and peek implementations incorrectly return Ok(0) when no data is ready, which is ambiguous with EOF. Other recommendations include refactoring timeout validation into a shared helper function and improving IPv6 address parsing to handle square brackets.