AtlatestRepositorysigil-http3
sigil-http3 / treeREADME.md
1
# sigil-http33
Experimental server HTTP/3 and WebTransport for4
[Sigil](https://codeberg.org/sigil/sigil). The library provides bounded HTTP/35
framing, static QPACK, stream transport, request validation, and WebTransport6
session routing over sigil-quic.8
## Status10
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 is14
not a general HTTP/3 client/server or an implementation of the latest15
WebTransport draft. Dynamic QPACK is unsupported. Phone reachability and16
migration across real networks remain experimental; loopback checks do not17
establish either. Independent security review is needed before production use.19
## Dependency21
Add this entry to your `package.sgl` dependencies, then run `sigil deps install`:23
```scheme24
(from-git url: "codeberg:sigil/sigil-http3" branch: "master")25
```27
The manifest pins the accompanying sigil-quic and sigil-nat revisions.28
The endpoint adapter needs IPv4/IPv6-aware UDP support: `udp-socket` families29
and `socket-normalize-address`. This support is not in a released Sigil yet30
and is planned for an upcoming release.31
Codec use does not establish endpoint availability.33
## Usage35
Encode and decode a DATA frame without opening a connection:37
```scheme38
(import (sigil http3 frame))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
```46
`(sigil http3 connection)` attaches server stream handling to a QUIC engine.47
`(sigil http3 webtransport router)` emits application commands for CONNECT48
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).51
## Tests53
From a checkout, prepare the exact companion sources, then run the Sigil suite:55
```sh56
bash scripts/prepare-quic.sh57
bash scripts/prepare-nat-dependency.sh58
sigil deps install59
sigil test --report60
cd tools/interop61
sigil deps install62
sigil test --report63
```65
The preparation scripts accept a local repository or Git URL as their first66
argument. `HTTP3_QUIC_SOURCE` and `HTTP3_NAT_SOURCE` override the defaults.67
The codec and interop suites have 123 cases combined; endpoint integration68
checks need the socket-capable runtime described above.70
With Node.js 20 or later, OpenSSL and loopback UDP/HTTPS available:72
```sh73
bash scripts/phantom-lifecycle-check.sh74
node --test test/test-punch-prime.mjs test/test-continuous-punch-window.mjs75
node --test tools/port-mapping/test-codecs.mjs76
```78
The retained `phantom-` script names are compatibility names. A Linux host79
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 and82
public-network checks are separate from the offline suite.84
## License86
BSD-3-Clause. See [LICENSE](LICENSE). Generated QPACK/Huffman tables retain87
their RFC source attribution in the source files.