feat: Introduce dns.RawResolver interface by fortuna · Pull Request #594 · OutlineFoundation/outline-sdk

fortuna · 2026-04-01T17:25:16Z

Motivation

The main goal here is to decouple this foundational piece from the DNS parsing library. I've had a few issues with dns.Resolver while working on ECH research:

dnsmessage fails to parse DNS labels with dots in it, which is used in the email field of SOA records.
dnsmessage may not support the latest record types. In my case, it didn't support the HTTPS and SVCB records.

I ended up forced to use miekg's library instead of the SDK for that work.

This decoupling will allow the user to use whatever parsing library they prefer.

It also streamlines the implementation of the system resolver, removing unnecessary transformations when we fetch a []byte response from the system APIs. See #592 for where I'm going.

The new interface takes the output buffer as input, which lets the caller control the lifecycle of the buffer and avoid unnecessary allocations.

I also want this to be a building block for the dnstt implementation.

Changes

The new API includes:

RawResolver (takes QNAME + QTYPE + output buffer)
FuncRawResolver - convenience func -> RawResolver adaptor
RawToResolver - convenience adaptor to map to the current interface.

Extracts the RawResolver interface, FuncRawResolver, RawToResolver, and their tests out of PR #592 to decouple DNS querying from response parsing.

fortuna

Some API questions to consider

fortuna · 2026-04-01T17:49:43Z

+// allowing callers to parse the response with any library — including those that support
+// record types not yet recognized by golang.org/x/net/dns/dnsmessage.
+type RawResolver interface {
+	QueryRaw(ctx context.Context, name string, qtype uint16) ([]byte, error)


We need to decide on the qname format. Could be the native []byte format with length-prefixed labels, or [][]byte (slice of labels), or a escaped string ("foo.bar.com").

While this doesn't affect regular usage, it can help use cases like DNS tunneling.

This commit modifies RawResolver's QueryRaw to take an arbitrary buf []byte to enable zero-allocation DNS wire-format pipelines logic within queryDatagram and queryStream.

…dAll Extract body read loop to readAllInto, taking ContentLength into consideration to pre-allocate capacity.

…lash escaping

fortuna

Some thoughts.

fortuna · 2026-04-01T22:31:12Z

+// this adapter only unpacks the result.
+func RawToResolver(r RawResolver) Resolver {
+	return FuncResolver(func(ctx context.Context, q dnsmessage.Question) (*dnsmessage.Message, error) {
+		buf := make([]byte, 0, maxUDPMessageSize)


What should the size be? I'm not convinced this is the best approach.

Perhaps we should set the max message size in the resolver object. Each implementation will have different parameters.
We may want to specify OPT options.

Also see https://datatracker.ietf.org/doc/html/rfc6891#section-6.2.5

fortuna · 2026-04-01T22:32:13Z

Should we read it into buf instead to avoid allocating another buffer?

fortuna · 2026-04-01T23:58:53Z

+ 1. Zero-dependency footprint: Bypassing rigid DNS parsing libraries allows Outline to pack esoteric labels natively natively (e.g. obscure DNS tunneling headers).
+ 2. Future-proof compatibility: Callers can inject or parse the raw responses using any external library, including those supporting newer record types.
+ 3. Zero-allocation cycles: Providing a reusable `buf []byte` hands memory management to the caller, removing slice allocations in the hot path.


Let's reorder:

Future proof

Zero Allocation

BYO parsing

fortuna · 2026-04-02T00:01:37Z

+// allowing callers to parse the response with any library — including those that support
+// record types not yet recognized by golang.org/x/net/dns/dnsmessage.
+type RawResolver interface {
+	QueryRaw(ctx context.Context, name string, qtype uint16, buf []byte) ([]byte, error)


We should explain that the returned buffer may or may not be a slice of the input. It depends on the implementation.

Or should we change that to guarantee it?

The main challenge is when we have dynamic lengths, as in TCP and HTTP

fortuna · 2026-04-02T00:03:23Z

+
+// RawToResolver wraps a [RawResolver] in a [Resolver] that parses the wire-format
+// response bytes using golang.org/x/net/dns/dnsmessage.
+// The underlying [RawResolver] is responsible for ID matching and returning valid bytes;


We can remove this line.

fortuna · 2026-04-02T01:34:09Z

+	respQName := rawResp[12 : 12+len(expectedName)]

+	// Case-insensitive comparison, as the server may echo back randomized caps (e.g. 0x20 encoding)
+	for i := 0; i < len(expectedName); i++ {


Move to a function. Also, need to compare the lengths!

fortuna · 2026-04-02T01:34:53Z

+		}
+	}
+
+	respQType := binary.BigEndian.Uint16(rawResp[12+len(expectedName):])


We should check type and class first.

fortuna · 2026-04-02T01:37:42Z

-func checkResponse(reqID uint16, reqQues dnsmessage.Question, respHdr dnsmessage.Header, respQs []dnsmessage.Question) error {
-	if !respHdr.Response {
+// checkResponseRaw verifies the DNS response matches the request parameters directly on the wire bytes.
+func checkResponseRaw(reqID uint16, name string, qtype uint16, rawResp []byte) error {


It seems like we may need another abstraction layer. This kind of check is standard, and independent on how we exchange messages (though the message exchanges depend on the message id)

There's also things like padding, extended errors, client subnet, DNSSEC, and so on.... Where should that live?

Oh, and caching!

fortuna · 2026-04-02T01:40:37Z

 // [DNS-over-UDP]: https://datatracker.ietf.org/doc/html/rfc1035#section-4.2.1
-func NewUDPResolver(pd transport.PacketDialer, resolverAddr string) Resolver {
+func NewUDPRawResolver(pd transport.PacketDialer, resolverAddr string) RawResolver {


I don't think these factory functions work well. We should consider a way to specify configs, like the max packet length for UDP, and layer other functionality that are common across implementations.

fortuna · 2026-04-02T01:42:08Z

-		}
-		if err := checkResponse(0, q, msg.Header, msg.Questions); err != nil {
+		// Ignore invalid packets that fail to parse. It could be injected.
+		if err := checkResponseRaw(0, name, qtype, buf); err != nil {


I think we should match on ID first, then validate.

Introduce RawResolver interface and adapter logic

da612fd

Extracts the RawResolver interface, FuncRawResolver, RawToResolver, and their tests out of PR #592 to decouple DNS querying from response parsing.

fortuna changed the title ~~Introduce dns.RawResolver interface~~ feat: Introduce dns.RawResolver interface Apr 1, 2026

fortuna marked this pull request as draft April 1, 2026 17:34

fortuna commented Apr 1, 2026

View reviewed changes

fortuna added 2 commits April 1, 2026 18:26

Refactor RawResolver to zero-allocation pipeline

d652c08

This commit modifies RawResolver's QueryRaw to take an arbitrary buf []byte to enable zero-allocation DNS wire-format pipelines logic within queryDatagram and queryStream.

dns: move RawResolver API design rationale to doc.go

918b795

fortuna force-pushed the fortuna/raw-resolver branch from c48ea1c to 918b795 Compare April 1, 2026 22:35

fortuna added 2 commits April 1, 2026 18:46

dns: use caller-provided buffer in NewHTTPSResolver instead of io.Rea…

bb9d388

…dAll Extract body read loop to readAllInto, taking ContentLength into consideration to pre-allocate capacity.

dns: inline appendName test assertions and properly support dot/backs…

3d02c7f

…lash escaping

fortuna commented Apr 2, 2026

View reviewed changes

Conversation

fortuna commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes

Uh oh!

fortuna left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

fortuna left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

fortuna commented Apr 1, 2026 •

edited

Loading