socat-rs (socat in Rust)

A modern Rust rewrite project for socat, built around two goals:

• Full legacy capability coverage (compatibility-first)
• A simpler, AI-friendly and human-friendly command model

Project/package name: socat-rs
Binary names: socat (compat) and socat-rs (explicit)

This repository already includes:

• Cross-platform async core (tokio) for Linux/macOS/Windows
• Legacy input path: socat <ADDR1> <ADDR2>
• Simpler path: socat link --from <URI> --to <URI>
• Planning path: socat plan --from <ADDR> --to <ADDR>
• Validation path: socat validate --from <ADDR> --to <ADDR>
• Tunnel path: socat tunnel --via <proxy-uri> --to <host:port> [--from stdio://]
• Check path: socat check <address>
• Doctor path: socat doctor
• Agent JSON input path: socat run --input-json <file-or->
• CI for Linux/macOS/Windows
• Legacy inventory extraction script from upstream socat source

Current implemented endpoint families:

• stdio
• tcp-connect
• tcp-listen
• udp-connect
• udp-listen
• tls-connect
• tls-listen (requires SOCAT_RS_TLS_PKCS12)
• socks4-connect
• socks4a-connect
• socks5-connect
• http-proxy-connect
  • supports URI auth: socks5://user:pass@proxy:1080?target=host:443
  • supports URI auth: http-proxy://user:pass@proxy:8080?target=host:443
• exec
• system
• shell
• unix-connect (unix only)
• unix-listen (unix only)
• file
• named-pipe-connect (Windows, npipe:// / PIPE: / NPIPE:)
• runtime option engine v1:
  • connect-timeout
  • retry
  • retry-delay
  • retry-backoff (constant / exponential)
  • retry-max-delay
  • tls-verify
  • tls-sni
• built-in profiles:
  • dev
  • prod
  • lan
  • wan
• run-report JSON for executed links (--json)
• JSON report file output: --report-file <path>
• Prometheus metrics endpoint: --metrics-bind <host:port>

legacy: keep compatibility with classic socat grammar.

socat TCP-LISTEN:8080 STDIO
socat STDIO TCP:127.0.0.1:8080

simple: predictable and easy for AI tools to generate.

socat link --from tcp-listen://0.0.0.0:8080 --to stdio://
socat link --from stdio:// --to tcp://127.0.0.1:8080
socat link --from npipe://./pipe/socat-rs --to tcp://127.0.0.1:9000
socat link --from "tcp://127.0.0.1:9000?connect-timeout=2s&retry=3&retry-delay=500ms" --to stdio://
socat link --from "tcp://127.0.0.1:9000?retry=5&retry-backoff=exponential&retry-max-delay=8s" --to stdio://
socat link --from "tls://example.com:443?tls-verify=false&sni=alt.example.com" --to stdio://
socat link --profile prod --from tcp://example.com:443 --to stdio://
socat tunnel --via socks5://127.0.0.1:1080 --to example.com:443
socat tunnel --from stdio:// --via http-proxy://u:p@127.0.0.1:8080 --to api.example.com:443
socat tunnel --via socks5://127.0.0.1:1080 --via http-proxy://127.0.0.1:8080 --to api.example.com:443

Use --dry-run and --json to make planning deterministic:

socat --dry-run --json link --from tcp://127.0.0.1:80 --to stdio://
socat --json plan --from "TCP:127.0.0.1:9000,retry=2" --to STDIO
socat --json validate --profile wan --from tcp://api.example.com:443 --to stdio://
socat --json check "tcp://127.0.0.1:8080?connect-timeout=1s"
socat --json explain "TCP-LISTEN:8080"
socat --json explain "TCP:127.0.0.1:9000,connect-timeout=2000,retry=3,retry-delay=500ms"
socat --json inventory
socat --json --metrics-bind 0.0.0.0:9464 link --from tcp://127.0.0.1:9000 --to stdio://
socat --json --report-file ./run-report.json link --from tcp://127.0.0.1:9000 --to stdio://

When --json is enabled, every command returns one stable envelope:

• schema_version
• ok
• command
• input
• plan
• result
• error
• next_actions
• version
• timestamp

Stable error codes now include:

• E_ADDR_PARSE
• E_CONNECT_TIMEOUT
• E_TLS_ENV
• E_PROXY_AUTH

plan now includes:

• normalized_endpoints
• executable_command

Use structured JSON input for agent-safe invocation:

cat <<'JSON' | socat run --input-json -
{
  "mode": "plan",
  "from": "tcp://127.0.0.1:8080",
  "to": "stdio://",
  "json": true
}
JSON

Supported mode values in JSON input:

• link
• tunnel
• plan
• validate
• check
• explain
• inventory
• doctor
• legacy

• src/main.rs: binary entrypoint, command name remains socat
• crates/socat-rs-core: runtime core
  • spec.rs: endpoint grammar parsing (legacy + URI)
  • endpoint.rs: endpoint openers and platform branches
  • relay.rs: bidirectional streaming relay
  • error.rs: typed errors
• crates/socat-rs-compat: compatibility metadata and feature counters
• docs/: analysis and roadmap
• .github/workflows/ci.yml: CI for all target OS

Upstream socat has very broad surface area (hundreds of options and many address families). This project keeps a strict compatibility ledger and lands support incrementally in grouped modules.

See:

• docs/socat-analysis.md
• docs/compatibility-roadmap.md
• docs/FEATURE_STATUS.zh-CN.md
• docs/FEATURE_STATUS.en.md
• docs/V1_READY.en.md
• docs/V1_READY.zh-CN.md
• docs/ALL_FEATURES.en.md
• docs/ALL_FEATURES.zh-CN.md
• README.zh-CN.md

cargo build
cargo test
cargo run --bin socat -- --help
cargo test --test json_protocol_smoke

Quick environment check:

cargo run --bin socat -- doctor
cargo run --bin socat -- --json doctor

Local package creation (after building a target):

rustup target add x86_64-unknown-linux-gnu
cargo build --release --workspace --target x86_64-unknown-linux-gnu
PACKAGE_VERSION=local ./scripts/package-artifact.sh x86_64-unknown-linux-gnu

CI release workflow (.github/workflows/release.yml) builds and packages:

• Ubuntu: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu
• Windows: x86_64-pc-windows-msvc, aarch64-pc-windows-msvc
• macOS: x86_64-apple-darwin, aarch64-apple-darwin

Given upstream source at ../socat:

./scripts/extract_legacy_inventory.sh ../socat