What is Kindling?
Kindling is an open-source Go library from Lantern that sends and receives small amounts of data, like configuration files, through censoring firewalls. It races several circumvention techniques (domain fronting, proxyless dialing and Google's AMP cache, with the Soar DNS tunnel held back as a last resort) and sends the request over whichever connects first. Your code gets back an ordinary Go http.Client.
Is Kindling a VPN?
No. Kindling doesn't carry your browsing. It gets a circumvention app's first requests, such as fetching its configuration or its list of servers, through a censored network, so the app can start its own tunnel. If you want a VPN, download Lantern.
Which circumvention techniques does Kindling use?
Four, plus any you add. Domain fronting reaches the real origin through a large CDN under another server name. Proxyless dialing uses the Outline SDK's smart dialer, which tries DNS over HTTPS, TCP stream splitting and TLS record fragmentation to get past DNS and SNI blocking. The AMP cache transport uses Lantern's amp library to go through Google's AMP cache. Soar, a DNS tunnel, is the last resort.
How does Kindling choose which technique to use?
It doesn't choose in advance. Every transport in the first tier without a start delay begins connecting at the same time, so the race measures what actually works on the network the app is on, and the first to connect carries the request. If every transport in the tier fails, the next tier joins at once, and a transport with a start delay joins when its delay passes. WithRaceObserver reports how each race went: which transport won, and what happened to each one tried.
When does Kindling use the DNS tunnel?
Only as a last resort. DNS tunnelling keeps working under heavy censorship but is slow, so Soar joins the race 8 seconds into a request, or as soon as every faster transport has failed, whichever comes first. The delay is there because censored networks often drop packets instead of refusing connections, so the faster transports can hang rather than fail. WithStartDelay changes it.
Will Kindling send a POST request twice?
Not unless you say it's safe. A request that isn't safe to replay is sent once, on the first transport to connect, and its response is returned whatever it is. Failing to connect always moves on to the next transport, because no body was sent. GET and HEAD requests, and requests with the X-Kindling-Idempotent header, also move on after a transport error, a 5xx or a 403, so set that header only on a POST the server can safely receive twice. Other 4xx responses are returned as they are.
How much data can Kindling send?
Kindling is built for small requests, such as config fetches and status checks, not bulk traffic. Each transport declares its own limits: the AMP cache takes request bodies up to 6,000 bytes and can't stream, so Kindling skips it for larger bodies and for streaming requests (those with Accept: text/event-stream).
How does Kindling relate to the Outline SDK?
Kindling's proxyless transport is the Outline SDK smart dialer, which connects straight to the destination and searches for a DNS and TLS strategy that gets through. Kindling races it alongside domain fronting, the AMP cache and DNS tunnelling, so the request has other routes on networks where no proxyless strategy works.
Why not just use domain fronting?
Each technique beats a different kind of blocking, and none works everywhere. A domain front fails if that CDN path is blocked or refuses the client's country. Proxyless dialing works best for widely used services whose addresses aren't blocked. The AMP cache only carries small requests. Kindling runs them together, so one blocked route doesn't fail the request.
How do I use Kindling in a Go program?
Run go get github.com/getlantern/kindling, create a client with kindling.NewKindling and the transports you want (WithDomainFronting, WithProxyless, WithAMPCache, WithDNSTunnel), then call NewHTTPClient() and use the result like any http.Client. See the code examples.
Can I add my own circumvention technique?
Yes. Anything that can return a pre-connected http.RoundTripper can join the race: implement the Transport interface and pass it to WithTransport. Add Priority() int to race in a later tier, or StartDelay() time.Duration to join late. Pull requests for new techniques are welcome on GitHub.
Does Lantern use Kindling?
Yes. Lantern's client backend, radiance, uses Kindling to fetch its configuration. Kindling is meant for any circumvention tool written in Go that needs to fetch configuration reliably on startup.
Who makes Kindling?
The Lantern team, at Brave New Software Project, Inc., which makes the Lantern VPN and censorship-circumvention app.