AtlatestRenderedmarkdown
Readme

Private HQ interoperability adapter

This standalone test package drives one QUIC v1 connection and client-initiated bidirectional stream at a time using hq-interop. It sends bounded HQ requests and exchanges binary responses. It does not link peer libraries.

Build and run only on the designated test machine. Install this package's released dependencies with sigil deps install, then run sigil build --config native in this directory. It uses sigil-crypto ^0.18.1. The executable is build/native/bin/quic-hq.

Generate an ephemeral P-256 key and self-signed certificate with a localhost SAN on that machine, as key.pem and cert.pem in a private directory. Run node prepare-fixtures.mjs DIRECTORY there to produce cert.der, public.raw and owner-readable private.raw. Private credentials are test fixtures and must not be saved with test results. The client authenticates the exact leaf DER and localhost name before accepting its P-256 public key.

Set HQ_ROLE to client or server, and supply these environment variables:

  • HQ_CERT_DER: certificate DER path, both roles.
  • HQ_PUBLIC_RAW: uncompressed 65-byte P-256 public key path, client.
  • HQ_PRIVATE_RAW: 32-byte P-256 scalar path, server.
  • HQ_PEER_PORT: loopback server port, client.
  • HQ_LOCAL_PORT: loopback listen port, server.
  • HQ_PAYLOAD: response file path, server; at most 16 MiB.
  • HQ_OUTPUT: downloaded response path, client; at most 16 MiB.
  • HQ_CASE: handshake (default) or transfer.
  • HQ_RETRY: 1 requires authenticated Retry transport parameters. The server issues Retry through the private endpoint; a client expects the peer server to issue it. Unset or 0 preserves ordinary admission. Other values are errors. Save an independent wire capture to prove the Retry exchange.
  • HQ_DIRECTORY: transfer case input directory for server, output directory for client; replaces HQ_PAYLOAD/HQ_OUTPUT in that case.

The endpoint binds literal 127.0.0.1. Run external peers inside a private network namespace containing only loopback, since a peer CLI may bind wildcard addresses. Bound peer lifetimes with a timeout and signal only PIDs started by the harness. Save peer logs/qlogs, adapter handshake/transfer markers and a binary comparison against the original response.

The handshake case downloads /payload on stream 0; use a 1 KiB fixture. The transfer case downloads /payload2, /payload3, /payload5 on bounded sequential streams 0, 4, 8 of the same connection. Provide exact binary fixtures of 2, 3 and 5 MiB respectively, and compare every downloaded byte. Each stream advances only after consumed receiving FIN and acknowledged sending FIN. Logs record stream IDs, names, byte counts, one handshake and final file count. A single file or successful handshake alone does not pass transfer.