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.bundle
LICENSEadded
@@ -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
2579c236d9b3a1b7b65a1ba75bd94f768c6d44dd
package.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
565208c66e5a6034507d628817e180eb64085673
scripts/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` });