alksocks/tasks/implementation/vendor-differential-tests.md

id, name, status, depends_on, scope, risk, impact, level

id	name	status	depends_on	scope	risk	impact	level
implementation/vendor-differential-tests	Vendor — the differential RFC edge-case test suite	pending	implementation/vendor-server-typestate implementation/vendor-client-session	moderate	medium	component	implementation

Description

Build the crate's RFC edge-case test suite for the extracted vendor — the differential-testing posture vendor.md pins: "the crate's test suite covers the edge cases the extracted code must keep passing; when in doubt, diff behavior against the reference checkout." The per-task unit tests (wire vocabulary, typestate, client session) cover the happy paths; this task covers the RFC edge cases and the extraction-fidelity checks, using /workspace/fast-socks5 as the behavioral reference (read-only — tests never depend on it at build time; the reference is consulted while writing the tests, and the assertions pin the expected bytes).

Test infrastructure: tokio duplex streams (tokio::io::duplex) — no sockets, no local feature, runs in the default wasm-clean crate's test suite (tests are native-only via dev-deps; the crate itself stays wasm-clean). A first-party test harness drives the vendored typestate server against the vendored client session over duplex pairs.

Edge-case coverage (each pinned with explicit expected bytes where the wire form is the point):

1. Negotiation edge cases: method-list parsing (empty method list, zero methods offered → 0xff), method-order preference (server picks its first match, not the client's first offer), version mismatch (0x04 greeting → refusal), truncated greeting (EOF mid-handshake → typed error, no hang), password-auth sub-protocol (empty username → EmptyUsername, empty password → EmptyPassword, reject path → 0x01/0xff reply then error).
2. Command-read edge cases: unknown command byte (0x04+ → UnknownCommand → 0x07 reply), reserved-byte tolerance (RSV ≠ 0 — upstream reads it without checking; pin the upstream behavior), address-type edge cases (ATYP 0x02/0x05+ → IncorrectAddressType → 0x08 reply), domain-length boundary (255-byte domain OK, 256+ rejected at encode time by to_be_bytes), truncated address fields (EOF mid-address → typed error).
3. Reply-form edge cases (the new_reply carried change's regression guard): v4 reply = 10 bytes, v6 reply = 22 bytes, VER=0x05/RSV=0x00 in every reply, error replies carry 0.0.0.0:0-equivalent (ATYP=1, zero addr+port), success replies carry the caller's sock_addr verbatim.
4. Client-session edge cases: reply#1 with a non-zero reply code → the mapped ReplyError (the from_u8 table), domain-target request encoding (ATYP=3, len-prefixed), the UDP-ASSOCIATE zero-target fallback (upstream request_header's target_addr: None branch — pin the 10-byte zero form), skip_auth behavior (no method negotiation bytes on the wire).
5. UDP codec edge cases: parse_udp_request with garbage RSV → GarbageInReserved, FRAG ≠ 0 passthrough (the parser returns frag; the caller refuses — pin the parser's contract), new_udp_header/parse_udp_request round-trip for v4/v6/domain.
6. transfer/wait_on_tcp semantics: transfer pumps both directions to completion over duplexes (including half-close propagation); wait_on_tcp returns EOF on clean close, UnexpectedUdpControlGarbage on a control byte.

Differential method: for each behavior above, consult the reference checkout's behavior (its own tests + code reading) and pin the same expectation in-tree, noting the upstream source line in the test's doc comment where the expectation is non-obvious. Where the extraction deliberately diverges (the pruned error variants, the published new_reply), the test pins the in-tree contract and the divergence is already recorded in vendor.md — no new divergence may be introduced by this task.

Acceptance Criteria

• The six coverage groups above each have at least one test; all pass in cargo test
• Tests use only duplex/in-memory streams — no TcpListener/ UdpSocket/tokio::net in test code (the suite runs in the default-feature build)
• Every non-obvious expectation carries a doc-comment note naming the upstream behavior it pins (file + line in /workspace/fast-socks5)
• cargo test (default features) green; cargo test --all-features green (no feature-gated vendor code exists, so both must pass identically)
• cargo check --target wasm32-unknown-unknown still clean (tests are dev-only; the crate surface unchanged)
• cargo clippy --all-targets -- -D warnings and cargo fmt --check clean

References

• docs/architecture/vendor.md §Maintenance Posture (the differential-testing contract)
• docs/architecture/decisions/011-inline-vendor.md (differential testing guards the RFC edge cases)
• docs/architecture/decisions/002-protocol-base.md (faithful reply-code mapping)
• Reference checkout: /workspace/fast-socks5 (v1.0.0 — behavior source for the pinned expectations; its src/lib.rs test module and src/server.rs test module are the upstream coverage to mirror where extractable)
• RFC 1928 (the wire form's authority)

Notes

To be filled by implementation agent

Summary

To be filled on completion