AtlatestRepositorysigil-quic
sigil-quic / tree / tools / hqREADME.md
1
# Private HQ interoperability adapter3
This standalone test package drives one QUIC v1 connection and client-initiated4
bidirectional stream at a time using `hq-interop`. It sends bounded HQ requests5
and exchanges binary responses. It does not link peer libraries.7
Build and run only on the designated test machine. Install this package's8
released dependencies with `sigil deps install`, then run9
`sigil build --config native` in this directory. It uses sigil-crypto ^0.18.1.10
The executable is `build/native/bin/quic-hq`.12
Generate an ephemeral P-256 key and self-signed certificate with a localhost SAN13
on that machine, as `key.pem` and `cert.pem` in a private directory. Run14
`node prepare-fixtures.mjs DIRECTORY` there to produce `cert.der`, `public.raw`15
and owner-readable `private.raw`. Private credentials are test fixtures and16
must not be saved with test results. The client authenticates the exact leaf17
DER and localhost name before accepting its P-256 public key.19
Set `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. The30
server issues Retry through the private endpoint; a client expects the peer31
server to issue it. Unset or `0` preserves ordinary admission. Other values32
are errors. Save an independent wire capture to prove the Retry exchange.33
- `HQ_DIRECTORY`: transfer case input directory for server, output directory34
for client; replaces `HQ_PAYLOAD`/`HQ_OUTPUT` in that case.36
The endpoint binds literal `127.0.0.1`. Run external peers inside a private37
network namespace containing only loopback, since a peer CLI may bind wildcard38
addresses. Bound peer lifetimes with a timeout and signal only PIDs started by39
the harness. Save peer logs/qlogs, adapter handshake/transfer markers and a40
binary comparison against the original response.42
The handshake case downloads `/payload` on stream 0; use a 1 KiB fixture.43
The transfer case downloads `/payload2`, `/payload3`, `/payload5` on bounded44
sequential streams 0, 4, 8 of the same connection. Provide exact binary fixtures45
of 2, 3 and 5 MiB respectively, and compare every downloaded byte.46
Each stream advances only after consumed receiving FIN and acknowledged sending47
FIN. Logs record stream IDs, names, byte counts, one handshake and final file48
count. A single file or successful handshake alone does not pass transfer.