Commit13762299Recorded25 Oct 2026Repositorysigil-http3
Document public HTTP3 APIs and pin publishable companion sources
Changed
.gitignore | 2 ++
LICENSE | 27 +++++++++++++++++++++++++++
README.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
docs/tool-configuration.md | 31 +++++++++++++++++++++++++++++++
nat.rev | 2 +-
package.sgl | 4 ++--
quic.rev | 2 +-
scripts/continuous-punch-window.mjs | 4 ++--
scripts/prepare-nat-dependency.sh | 5 +++--
scripts/prepare-quic.sh | 5 +++--
scripts/punch-window.mjs | 2 +-
scripts/vpn-phone-run.mjs | 2 +-
spikes/webrtc/peer.mjs | 2 +-
spikes/webrtc/window.mjs | 2 +-
14 files changed, 160 insertions(+), 18 deletions(-)Diff
.gitignoremodified
@@ -2,3 +2,5 @@ build/
2
.sigil/ 3
.deps/ 4
*.sgb+5
+6
*-source.bundleLICENSEadded
@@ -0,0 +1,27 @@
+1
BSD 3-Clause License+2
+3
Copyright (c) 2026, David Wilson+4
All rights reserved.+5
+6
Redistribution and use in source and binary forms, with or without+7
modification, are permitted provided that the following conditions are met:+8
+9
1. Redistributions of source code must retain the above copyright notice,+10
this list of conditions and the following disclaimer.+11
2. Redistributions in binary form must reproduce the above copyright notice,+12
this list of conditions and the following disclaimer in the documentation+13
and/or other materials provided with the distribution.+14
3. Neither the name of the copyright holder nor the names of its contributors+15
may be used to endorse or promote products derived from this software+16
without specific prior written permission.+17
+18
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"+19
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE+20
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE+21
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE+22
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL+23
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR+24
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER+25
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,+26
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE+27
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.README.mdmodified
@@ -1,7 +1,87 @@
1
# sigil-http3 2
−3
Experimental bounded HTTP/3 and WebTransport support for Sigil.−4
See the source modules, test fixtures, and package manifest for the APIs−5
and dependencies available at this revision.+3
Experimental server HTTP/3 and WebTransport for+4
[Sigil](https://codeberg.org/sigil/sigil). The library provides bounded HTTP/3+5
framing, static QPACK, stream transport, request validation, and WebTransport+6
session routing over sigil-quic. 7
−7
BSD-3-Clause.+8
## Status+9
+10
Early development. Frame and SETTINGS codecs, bounded Huffman decoding,+11
request HEADERS/DATA/trailers, control streams, concurrent server streams,+12
CONNECT/session routing, capsules, and stream/DATAGRAM echo are implemented.+13
The browser driver targets the legacy draft02 WebTransport profile. This is+14
not a general HTTP/3 client/server or an implementation of the latest+15
WebTransport draft. Dynamic QPACK is unsupported. Phone reachability and+16
migration across real networks remain experimental; loopback checks do not+17
establish either. Independent security review is needed before production use.+18
+19
## Dependency+20
+21
Add this entry to your `package.sgl` dependencies, then run `sigil deps install`:+22
+23
```scheme+24
(from-git url: "codeberg:sigil/sigil-http3" branch: "master")+25
```+26
+27
The manifest pins the accompanying sigil-quic and sigil-nat revisions. Live+28
IPv4/IPv6 endpoints additionally require Sigil's family-aware `udp-socket`+29
and `socket-normalize-address` APIs. The currently declared 0.22 runtime+30
alone lacks them; `spike-sdk.rev` identifies the required socket groundwork.+31
Codec use does not establish endpoint availability.+32
+33
## Usage+34
+35
Encode and decode a DATA frame without opening a connection:+36
+37
```scheme+38
(import (sigil http3 frame))+39
+40
(let* ((wire (encode-h3-frame 0 #u8(104 105)))+41
(frame (decode-h3-frame wire)))+42
(display (vector-ref frame 0)) ; => 0 (DATA)+43
(vector-ref frame 1)) ; => #u8(104 105)+44
```+45
+46
`(sigil http3 connection)` attaches server stream handling to a QUIC engine.+47
`(sigil http3 webtransport router)` emits application commands for CONNECT+48
sessions and associated streams. See the [router contract](docs/webtransport-router.md),+49
[browser profile](docs/chrome-interop.md), and [bounded echo lifecycle](docs/echo-lifecycle.md).+50
+51
## Tests+52
+53
From a checkout, prepare the exact companion sources, then run the Sigil suite:+54
+55
```sh+56
bash scripts/prepare-quic.sh+57
bash scripts/prepare-nat-dependency.sh+58
sigil deps install+59
sigil test --report+60
cd tools/interop+61
sigil deps install+62
sigil test --report+63
```+64
+65
The preparation scripts accept a local repository or Git URL as their first+66
argument. `HTTP3_QUIC_SOURCE` and `HTTP3_NAT_SOURCE` override the defaults.+67
The codec and interop suites have 123 cases combined; endpoint integration+68
checks need the socket-capable runtime described above.+69
+70
With Node.js 20 or later, OpenSSL and loopback UDP/HTTPS available:+71
+72
```sh+73
bash scripts/phantom-lifecycle-check.sh+74
node --test test/test-punch-prime.mjs test/test-continuous-punch-window.mjs+75
node --test tools/port-mapping/test-codecs.mjs+76
```+77
+78
The retained `phantom-` script names are compatibility names. A Linux host+79
with a C toolchain runs builds; browser probes additionally need Chrome.+80
Live helpers use explicit host, interface, origin and input-directory settings;+81
see [tool configuration](docs/tool-configuration.md). Browser, phone and+82
public-network checks are separate from the offline suite.+83
+84
## License+85
+86
BSD-3-Clause. See [LICENSE](LICENSE). Generated QPACK/Huffman tables retain+87
their RFC source attribution in the source files.docs/tool-configuration.mdadded
@@ -0,0 +1,31 @@
+1
# Tool configuration+2
+3
The live browser and phone helpers are experimental examples. Supply an exact+4
numeric bind address, certificate, origin and completed input build for the+5
host where they run. They check ownership, hashes, certificates, host identity,+6
port bounds and lifetimes before starting their child processes.+7
+8
| Setting | Purpose |+9
| --- | --- |+10
| HTTP3_QUIC_SOURCE / HTTP3_NAT_SOURCE | Companion Git source, local path or URL |+11
| HTTP3_SDK_SOURCE | Git source containing the socket groundwork in spike-sdk.rev |+12
| HTTP3_SPIKE_SDK_SOURCE | Built checkout of that SDK, including its bootstrap executable |+13
| SIGIL_BUILDER | Compiler executable, default sigil |+14
| HTTP3_WORKSPACE_ROOT | Parent of completed input workspaces; default build/workspaces in JavaScript helpers |+15
| HTTP3_INPUT_DIRECTORY / HTTP3_INPUT_JOB | Completed trace input directory and its metadata identity |+16
| HTTP3_VERIFIED_NATIVE_JOB | Completed echo workspace name under HTTP3_WORKSPACE_ROOT |+17
| HTTP3_IPV4_ADDRESS | Exact IPv4 bind address, default 127.0.0.1 |+18
| HTTP3_IPV6_ADDRESS | Explicit global IPv6 bind for live direct tests |+19
| HTTP3_INTERFACE | Interface carrying that address; no fixed interface is assumed |+20
| HTTP3_PAGE_URL / HTTP3_PAGE_ORIGIN | Hosted page URL and its exact secure origin |+21
| NAT_EXPECTED_GATEWAY / NAT_EXPECTED_LOCAL_ADDRESS | Exact route for live discovery |+22
+23
The example public origin is https://example.com. Replace it with an origin+24
you control and configure both the browser and peer consistently. Input+25
workspaces retain their rc file and src/build result layout. Live SDK sources+26
must match spike-sdk.rev exactly; this is a source prerequisite, not an+27
available released-runtime claim. No key material belongs in committed files.+28
+29
The offline suite uses fixtures and loopback sockets. Scripts that launch a+30
phone window, inspect a real gateway or prepare a firewall rule are separate+31
live experiments. Inspect their configuration before running them.nat.revmodified
@@ -1 +1 @@
−1
2a507e89d4c076439f3cd97558d1507d46cc2dba+1
2579c236d9b3a1b7b65a1ba75bd94f768c6d44ddpackage.sglmodified
@@ -7,8 +7,8 @@
7
authors: (list "David Wilson <david@daviwil.com>") 8
9
dependencies: (list−10
(from-path dir: ".deps/sigil-nat" name: "sigil-nat")−11
(from-path dir: ".deps/sigil-quic" name: "sigil-quic")+10
(from-git url: "codeberg:sigil/sigil-nat" commit: "2579c236d9b3a1b7b65a1ba75bd94f768c6d44dd")+11
(from-git url: "codeberg:sigil/sigil-quic" commit: "565208c66e5a6034507d628817e180eb64085673") 12
(from-git url: "codeberg:sigil/sigil" package: "sigil-lib" version: "^0.22") 13
(from-git url: "codeberg:sigil/sigil" package: "sigil-stdlib" version: "^0.22")) 14
quic.revmodified
@@ -1 +1 @@
−1
5245f5a43bb818766ec09131a8af1bad0b65eb68+1
565208c66e5a6034507d628817e180eb64085673scripts/continuous-punch-window.mjsmodified
@@ -9,7 +9,7 @@ import { identity, inspectPlan, runTest, sameIdentity, stopRun } from './echo-li
9
import { preparePunchFirewall } from './punch-firewall.mjs'; 10
import { punchPorts, validateRendezvous } from './punch-prime.mjs'; 11
−12
const page = 'https://example.com/wt-spike/phone.html';+12
const page = process.env.HTTP3_PAGE_URL ?? 'https://example.com/wt-spike/phone.html'; 13
const pause = ms => new Promise(done => setTimeout(done, ms)); 14
const digest = path => createHash('sha256').update(readFileSync(path)).digest('hex'); 15
function check(value, message) { if (!value) throw new Error(message); }@@ -50,7 +50,7 @@ async function run() {
50
'configured /128 not assigned on expected physical interface'); 51
const input = json('build/punch-input-proof.json'), receipt = json('build/browser/capabilities.json'); 52
const original = resolve('tools/interop/build/native/bin/http3-preflight');−53
check(input.continuous && input.job === 'http3-example' && input.binarySha256 === digest(original) &&+53
check(input.continuous && input.job === (process.env.HTTP3_INPUT_JOB ?? 'http3-example') && input.binarySha256 === digest(original) && 54
receipt.binarySha256 === input.binarySha256 && receipt.quicRevision === readFileSync('quic.rev', 'utf8').trim() && 55
receipt.spikeSdkRevision === readFileSync('spike-sdk.rev', 'utf8').trim(), 'Continuous binary provenance mismatch'); 56
check(['ready', 'bidirectionalEcho', 'unidirectionalEcho', 'datagramEcho', 'chromeReaped', 'serverReaped']scripts/prepare-nat-dependency.shmodified
@@ -5,12 +5,13 @@ source_repo=${1:-${HTTP3_NAT_SOURCE:-https://codeberg.org/sigil/sigil-nat.git}}
5
pin=$(cat nat.rev) 6
mkdir -p .deps 7
if [ ! -d .deps/sigil-nat/.git ]; then−8
git clone --quiet --no-hardlinks --no-checkout "$source_repo" .deps/sigil-nat+8
git clone --quiet --no-tags --no-hardlinks --no-checkout "$source_repo" .deps/sigil-nat+9
else+10
test -z "$(git -C .deps/sigil-nat status --porcelain)" 11
fi 12
if ! git -C .deps/sigil-nat cat-file -e "$pin^{commit}" 2>/dev/null; then 13
git -C .deps/sigil-nat fetch --quiet "$source_repo" "$pin" 14
fi−13
test -z "$(git -C .deps/sigil-nat status --porcelain)" 15
git -C .deps/sigil-nat checkout --quiet --detach "$pin" 16
test "$(git -C .deps/sigil-nat rev-parse HEAD)" = "$pin" 17
printf 'Pinned sigil-nat source: %s\n' "$pin"scripts/prepare-quic.shmodified
@@ -5,12 +5,13 @@ source_repo=${1:-${HTTP3_QUIC_SOURCE:-https://codeberg.org/sigil/sigil-quic.git}
5
pin=$(cat quic.rev) 6
mkdir -p .deps 7
if [ ! -d .deps/sigil-quic/.git ]; then−8
git clone --quiet --no-hardlinks --no-checkout "$source_repo" .deps/sigil-quic+8
git clone --quiet --no-tags --no-hardlinks --no-checkout "$source_repo" .deps/sigil-quic+9
else+10
test -z "$(git -C .deps/sigil-quic status --porcelain)" 11
fi 12
if ! git -C .deps/sigil-quic cat-file -e "$pin^{commit}" 2>/dev/null; then 13
git -C .deps/sigil-quic fetch --quiet "$source_repo" "$pin" 14
fi−13
test -z "$(git -C .deps/sigil-quic status --porcelain)" 15
git -C .deps/sigil-quic checkout --quiet --detach "$pin" 16
test "$(git -C .deps/sigil-quic rev-parse HEAD)" = "$pin" 17
printf 'Pinned sigil-quic source: %s\n' "$pin"scripts/punch-window.mjsmodified
@@ -58,7 +58,7 @@ async function run() {
58
const input = json('build/punch-input-proof.json'); 59
const receipt = json('build/browser/capabilities.json'); 60
const originalBinary = resolve('tools/interop/build/native/bin/http3-preflight');−61
check(input.job === 'http3-example' && input.binarySha256 === digest(originalBinary) &&+61
check(input.job === (process.env.HTTP3_INPUT_JOB ?? 'http3-example') && input.binarySha256 === digest(originalBinary) && 62
receipt.binarySha256 === input.binarySha256 && receipt.quicRevision === readFileSync('quic.rev', 'utf8').trim() && 63
receipt.spikeSdkRevision === readFileSync('spike-sdk.rev', 'utf8').trim(), 'Reused traced artifact proof mismatch'); 64
check(['ready', 'bidirectionalEcho', 'unidirectionalEcho', 'datagramEcho', 'chromeReaped', 'serverReaped'].every(key => receipt[key] === true) &&scripts/vpn-phone-run.mjsmodified
@@ -41,7 +41,7 @@ async function runVpnPhone() {
41
address?.family === 'IPv6' && address.address === bindAddress && !address.internal), 42
'configured IPv6 address is not assigned'); 43
const verifiedJob = process.env.HTTP3_VERIFIED_NATIVE_JOB;−44
check(/^http3-spike-echo-[0-9]{3}$/.test(verifiedJob ?? ''), 'Expected the admitted native gate');+44
check(/^[a-z0-9][a-z0-9-]{0,63}$/.test(verifiedJob ?? ''), 'Expected the admitted native gate'); 45
const verified = `${process.env.HTTP3_WORKSPACE_ROOT ?? (process.cwd() + "/build/workspaces")}/${verifiedJob}`; 46
check(readFileSync(verified + '/rc', 'utf8').trim() === '0', 'Native gate must have completed successfully'); 47
check(readFileSync(verified + '/src/build/spike-echo/result.txt', 'utf8')spikes/webrtc/peer.mjsmodified
@@ -201,7 +201,7 @@ export async function startPeer(config) {
201
server.headersTimeout = 5000; server.requestTimeout = 10000; server.keepAliveTimeout = 1000; server.maxConnections = 8; 202
server.on('connection', socket => { httpSockets.add(socket); socket.once('close', () => httpSockets.delete(socket)); socket.setTimeout(12000, () => socket.destroy()); }); 203
await new Promise((done, reject) => { server.once('error', reject); server.listen(config.signalPort ?? 0, '127.0.0.1', done); });−204
origin = config.scope === 'gate' ? `http://127.0.0.1:${server.address().port}` : 'https://example.com';+204
origin = config.scope === 'gate' ? `http://127.0.0.1:${server.address().port}` : (config.origin ?? process.env.HTTP3_PAGE_ORIGIN ?? 'https://example.com'); 205
UdpTransport.init = tracedInit; 206
const lifetime = setTimeout(() => void close(), config.lifetimeSeconds * 1000); 207
function armSession({ name, address, homePrefix = false }) {spikes/webrtc/window.mjsmodified
@@ -91,7 +91,7 @@ async function run(checkOnly = false) {
91
lifetimeSeconds: seconds, signalPort: checkOnly ? 0 : 47880, admit: () => rootWindow(directory, state) }); 92
state.signalPort = app.server.address().port; 93
state.phase = 'awaiting-firewall'; save();−94
privateJson(join(directory, 'parameters.json'), { page: 'https://example.com/wt-spike/webrtc.html',+94
privateJson(join(directory, 'parameters.json'), { page: process.env.HTTP3_PAGE_URL ?? 'https://example.com/wt-spike/webrtc.html', 95
token: 'issued privately only after fresh root proof and current phone rendezvous', 96
expiresAt: state.expiresAt, signalPort: state.signalPort, icePorts, 97
openCommand: `sudo bash ${directory}/firewall/open.sh`, closeCommand: `sudo bash ${directory}/firewall/close.sh` });