AtlatestRepositorysigil-quic
1# Private HQ interoperability adapter
2
3This standalone test package drives one QUIC v1 connection and client-initiated
4bidirectional stream at a time using `hq-interop`. It sends bounded HQ requests
5and exchanges binary responses. It does not link peer libraries.
6
7Build and run only on the designated test machine. Install this package's
8released dependencies with `sigil deps install`, then run
9`sigil build --config native` in this directory. It uses sigil-crypto ^0.18.1.
10The executable is `build/native/bin/quic-hq`.
12Generate an ephemeral P-256 key and self-signed certificate with a localhost SAN
13on that machine, as `key.pem` and `cert.pem` in a private directory. Run
14`node prepare-fixtures.mjs DIRECTORY` there to produce `cert.der`, `public.raw`
15and owner-readable `private.raw`. Private credentials are test fixtures and
16must not be saved with test results. The client authenticates the exact leaf
17DER and localhost name before accepting its P-256 public key.
19Set `HQ_ROLE` to `client` or `server`, and supply these environment variables:
21- `HQ_CERT_DER`: certificate DER path, both roles.
22- `HQ_PUBLIC_RAW`: uncompressed 65-byte P-256 public key path, client.
23- `HQ_PRIVATE_RAW`: 32-byte P-256 scalar path, server.
24- `HQ_PEER_PORT`: loopback server port, client.
25- `HQ_LOCAL_PORT`: loopback listen port, server.
26- `HQ_PAYLOAD`: response file path, server; at most 16 MiB.
27- `HQ_OUTPUT`: downloaded response path, client; at most 16 MiB.
28- `HQ_CASE`: `handshake` (default) or `transfer`.
29- `HQ_RETRY`: `1` requires authenticated Retry transport parameters. The
30 server issues Retry through the private endpoint; a client expects the peer
31 server to issue it. Unset or `0` preserves ordinary admission. Other values
32 are errors. Save an independent wire capture to prove the Retry exchange.
33- `HQ_DIRECTORY`: transfer case input directory for server, output directory
34 for client; replaces `HQ_PAYLOAD`/`HQ_OUTPUT` in that case.
36The endpoint binds literal `127.0.0.1`. Run external peers inside a private
37network namespace containing only loopback, since a peer CLI may bind wildcard
38addresses. Bound peer lifetimes with a timeout and signal only PIDs started by
39the harness. Save peer logs/qlogs, adapter handshake/transfer markers and a
40binary comparison against the original response.
42The handshake case downloads `/payload` on stream 0; use a 1 KiB fixture.
43The transfer case downloads `/payload2`, `/payload3`, `/payload5` on bounded
44sequential streams 0, 4, 8 of the same connection. Provide exact binary fixtures
45of 2, 3 and 5 MiB respectively, and compare every downloaded byte.
46Each stream advances only after consumed receiving FIN and acknowledged sending
47FIN. Logs record stream IDs, names, byte counts, one handshake and final file
48count. A single file or successful handshake alone does not pass transfer.