Pull request: AGDNS-3523-imp-proxy-handlers

Merge in GO/dnsproxy from ADG-3523-imp-proxy-handlers to master

Squashed commit of the following:

commit 792b4ed
Author: Dimitry Kolyshev <dkolyshev@adguard.com>
Date:   Fri Feb 6 11:21:07 2026 +0700

    proxy: imp docs

commit dd39a00
Author: Dimitry Kolyshev <dkolyshev@adguard.com>
Date:   Thu Feb 5 10:49:37 2026 +0700

    all: imp code

commit 1f19f5a
Merge: 268659d 9067446
Author: Dimitry Kolyshev <dkolyshev@adguard.com>
Date:   Wed Feb 4 17:16:59 2026 +0700

    Merge remote-tracking branch 'origin/master' into ADG-3523-imp-proxy-handlers

commit 268659d
Author: Dimitry Kolyshev <dkolyshev@adguard.com>
Date:   Wed Feb 4 12:47:21 2026 +0700

    all: add proxy.RequestHandler interface

commit e0e1e8e
Author: Dimitry Kolyshev <dkolyshev@adguard.com>
Date:   Tue Feb 3 12:06:26 2026 +0700

    proxy: removed proxy.ResponseHandler

Author: Mizzick

internal/cmd/proxy.go

@@ -81,7 +81,7 @@ func createProxyConfig(
 		MaxGoroutines:          conf.MaxGoRoutines,
 		UsePrivateRDNS:         conf.UsePrivateRDNS,
 		PrivateSubnets:         netutil.SubnetSetFunc(netutil.IsLocallyServed),
-		RequestHandler:         reqHdlr.HandleRequest,
+		RequestHandler:         reqHdlr,
 		PendingRequests: &proxy.PendingRequestsConfig{
 			Enabled: conf.PendingRequestsEnabled,
 		},

internal/handler/default.go

@@ -33,7 +33,7 @@ type Default struct {
 	isIPv6Halted bool
 }
 
-// NewDefault creates a new [Default] handler.
+// NewDefault creates a new *Default handler.
 func NewDefault(conf *DefaultConfig) (d *Default) {
 	mc, ok := conf.MessageConstructor.(messageConstructor)
 	if !ok {
@@ -50,12 +50,14 @@ func NewDefault(conf *DefaultConfig) (d *Default) {
 	}
 }
 
-// HandleRequest resolves the DNS request within proxyCtx.  It only calls
+// type check
+var _ proxy.RequestHandler = (*Default)(nil)
+
+// Handle implements the [proxy.RequestHandler] interface for *Default.  It
+// resolves the DNS request within proxyCtx.  It only calls
 // [proxy.Proxy.Resolve] if the request isn't handled by any of the internal
 // handlers.
-func (h *Default) HandleRequest(p *proxy.Proxy, proxyCtx *proxy.DNSContext) (err error) {
-	// TODO(e.burkov):  Use the [*context.Context] instead of
-	// [*proxy.DNSContext] when the interface-based handler is implemented.
+func (h *Default) Handle(p *proxy.Proxy, proxyCtx *proxy.DNSContext) (err error) {
 	ctx := context.TODO()
 
 	h.logger.DebugContext(ctx, "handling request", "req", &proxyCtx.Req.Question[0])

proxy/config.go

@@ -28,24 +28,6 @@ const (
 	DefaultOptimisticAnswerTTL = 30 * time.Second
 )
 
-// RequestHandler is an optional custom handler for DNS requests.  It's used
-// instead of [Proxy.Resolve] if set.  The resulting error doesn't affect the
-// request processing.  The custom handler is responsible for calling
-// [ResponseHandler], if it doesn't call [Proxy.Resolve].
-//
-// TODO(e.burkov):  Use the same interface-based approach as
-// [BeforeRequestHandler].
-type RequestHandler func(p *Proxy, dctx *DNSContext) (err error)
-
-// ResponseHandler is an optional custom handler called when DNS query has been
-// processed.  When called from [Proxy.Resolve], dctx will contain the response
-// message if the upstream or cache succeeded.  err is only not nil if the
-// upstream failed to respond.
-//
-// TODO(e.burkov):  Use the same interface-based approach as
-// [BeforeRequestHandler].
-type ResponseHandler func(dctx *DNSContext, err error)
-
 // Config contains all the fields necessary for proxy configuration.
 //
 // TODO(a.garipov): Consider extracting conf blocks for better fieldalignment.
@@ -79,13 +61,9 @@ type Config struct {
 	BeforeRequestHandler BeforeRequestHandler
 
 	// RequestHandler is an optional custom handler for DNS requests.  It's used
-	// instead of [Proxy.Resolve] if set.  See [RequestHandler].
+	// instead of DefaultRequestHandler if set.
 	RequestHandler RequestHandler
 
-	// ResponseHandler is an optional custom handler called when DNS query has
-	// been processed.  See [ResponseHandler].
-	ResponseHandler ResponseHandler
-
 	// UpstreamConfig is a general set of DNS servers to forward requests to.
 	UpstreamConfig *UpstreamConfig
 

proxy/handler_internal_test.go

@@ -17,21 +17,13 @@ func TestFilteringHandler(t *testing.T) {
 	m := &sync.RWMutex{}
 	blockResponse := false
 
-	// Prepare the proxy server
-	dnsProxy := mustNew(t, &Config{
-		Logger:                 slogutil.NewDiscardLogger(),
-		UDPListenAddr:          []*net.UDPAddr{net.UDPAddrFromAddrPort(localhostAnyPort)},
-		TCPListenAddr:          []*net.TCPAddr{net.TCPAddrFromAddrPort(localhostAnyPort)},
-		UpstreamConfig:         newTestUpstreamConfig(t, defaultTimeout, testDefaultUpstreamAddr),
-		TrustedProxies:         defaultTrustedProxies,
-		RatelimitSubnetLenIPv4: 24,
-		RatelimitSubnetLenIPv6: 64,
-		RequestHandler: func(p *Proxy, d *DNSContext) error {
+	reqHandler := &TestRequestHandler{
+		OnHandle: func(p *Proxy, d *DNSContext) (err error) {
 			m.Lock()
 			defer m.Unlock()
 
 			if !blockResponse {
-				// Use the default Resolve method if response is not blocked
+				// Use the default Resolve method if response is not blocked.
 				return p.Resolve(d)
 			}
 
@@ -41,8 +33,21 @@ func TestFilteringHandler(t *testing.T) {
 
 			// Set the response right away
 			d.Res = &resp
+
 			return nil
 		},
+	}
+
+	// Prepare the proxy server.
+	dnsProxy := mustNew(t, &Config{
+		Logger:                 slogutil.NewDiscardLogger(),
+		TrustedProxies:         defaultTrustedProxies,
+		UpstreamConfig:         newTestUpstreamConfig(t, defaultTimeout, testDefaultUpstreamAddr),
+		RequestHandler:         reqHandler,
+		UDPListenAddr:          []*net.UDPAddr{net.UDPAddrFromAddrPort(localhostAnyPort)},
+		TCPListenAddr:          []*net.TCPAddr{net.TCPAddrFromAddrPort(localhostAnyPort)},
+		RatelimitSubnetLenIPv4: 24,
+		RatelimitSubnetLenIPv6: 64,
 	})
 
 	servicetest.RequireRun(t, dnsProxy, testTimeout)

proxy/pending_test.go

@@ -79,6 +79,14 @@ func TestPendingRequests(t *testing.T) {
 	workloadWG := &sync.WaitGroup{}
 	workloadWG.Add(reqsNum)
 
+	reqHandler := &proxy.TestRequestHandler{
+		OnHandle: func(p *proxy.Proxy, d *proxy.DNSContext) (err error) {
+			workloadWG.Done()
+
+			return p.Resolve(d)
+		},
+	}
+
 	once := &sync.Once{}
 	u := &dnsproxytest.Upstream{
 		OnExchange: func(req *dns.Msg) (resp *dns.Msg, err error) {
@@ -98,25 +106,21 @@ func TestPendingRequests(t *testing.T) {
 	}
 
 	p, err := proxy.New(&proxy.Config{
-		Logger:                 slogutil.NewDiscardLogger(),
+		Logger:         slogutil.NewDiscardLogger(),
+		UpstreamConfig: &proxy.UpstreamConfig{Upstreams: []upstream.Upstream{u}},
+		TrustedProxies: testTrustedProxies,
+		PendingRequests: &proxy.PendingRequestsConfig{
+			Enabled: true,
+		},
+		RequestHandler:         reqHandler,
 		UDPListenAddr:          []*net.UDPAddr{net.UDPAddrFromAddrPort(localhostAnyPort)},
 		TCPListenAddr:          []*net.TCPAddr{net.TCPAddrFromAddrPort(localhostAnyPort)},
-		UpstreamConfig:         &proxy.UpstreamConfig{Upstreams: []upstream.Upstream{u}},
-		TrustedProxies:         testTrustedProxies,
 		RatelimitSubnetLenIPv4: 24,
 		RatelimitSubnetLenIPv6: 64,
 		Ratelimit:              0,
-		CacheEnabled:           true,
 		CacheSizeBytes:         testCacheSize,
+		CacheEnabled:           true,
 		EnableEDNSClientSubnet: true,
-		PendingRequests: &proxy.PendingRequestsConfig{
-			Enabled: true,
-		},
-		RequestHandler: func(prx *proxy.Proxy, dctx *proxy.DNSContext) (err error) {
-			workloadWG.Done()
-
-			return prx.Resolve(dctx)
-		},
 	})
 	require.NoError(t, err)
 

proxy/proxy.go

@@ -92,6 +92,10 @@ type Proxy struct {
 	// beforeRequestHandler handles the request's context before it is resolved.
 	beforeRequestHandler BeforeRequestHandler
 
+	// requestHandler handles the DNS request after it's been processed by the
+	// beforeRequestHandler.  It is never nil.
+	requestHandler RequestHandler
+
 	// dnsCryptServer serves DNSCrypt queries.
 	dnsCryptServer *dnscrypt.Server
 
@@ -227,6 +231,7 @@ func New(c *Config) (p *Proxy, err error) {
 			c.BeforeRequestHandler,
 			noopRequestHandler{},
 		),
+		requestHandler:   cmp.Or[RequestHandler](c.RequestHandler, DefaultRequestHandler{}),
 		upstreamRTTStats: map[string]upstreamRTTStats{},
 		rttLock:          sync.Mutex{},
 		ratelimitLock:    sync.Mutex{},
@@ -751,10 +756,6 @@ func (p *Proxy) Resolve(dctx *DNSContext) (err error) {
 	// Complete the response.
 	dctx.scrub()
 
-	if p.ResponseHandler != nil {
-		p.ResponseHandler(dctx, err)
-	}
-
 	return err
 }
 

proxy/requesthandler.go

@@ -0,0 +1,21 @@
+package proxy
+
+// RequestHandler is an interface for handling DNS requests.
+type RequestHandler interface {
+	// Handle resolves the DNS request within *DNSContext.
+	//
+	// TODO(e.burkov):  Use the [context.Context] instead of [*DNSContext] when
+	//  the interface-based handler is implemented.
+	Handle(p *Proxy, dctx *DNSContext) (err error)
+}
+
+// DefaultRequestHandler implements [RequestHandler] by calling [Proxy.Resolve].
+type DefaultRequestHandler struct{}
+
+// type check
+var _ RequestHandler = DefaultRequestHandler{}
+
+// Handle implements the [RequestHandler] interface for DefaultRequestHandler.
+func (DefaultRequestHandler) Handle(p *Proxy, proxyCtx *DNSContext) (err error) {
+	return p.Resolve(proxyCtx)
+}

proxy/requesthandler_internal_test.go

@@ -0,0 +1,17 @@
+package proxy
+
+// TestRequestHandler is a mock request handler implementation to simplify
+// testing.
+//
+// TODO(d.kolyshev):  Move to internal/dnsproxytest.
+type TestRequestHandler struct {
+	OnHandle func(p *Proxy, dctx *DNSContext) (err error)
+}
+
+// type check
+var _ RequestHandler = (*TestRequestHandler)(nil)
+
+// Handle implements the [RequestHandler] interface for *TestRequestHandler.
+func (h *TestRequestHandler) Handle(p *Proxy, dctx *DNSContext) (err error) {
+	return h.OnHandle(p, dctx)
+}

proxy/server.go

@@ -121,11 +121,8 @@ func (p *Proxy) handleDNSRequest(d *DNSContext) (err error) {
 
 	d.Res = p.validateRequest(d)
 	if d.Res == nil {
-		if p.RequestHandler != nil {
-			err = errors.Annotate(p.RequestHandler(p, d), "using request handler: %w")
-		} else {
-			err = errors.Annotate(p.Resolve(d), "using default request handler: %w")
-		}
+		// TODO(d.kolyshev):  Consider using middlewares.
+		err = p.requestHandler.Handle(p, d)
 	}
 
 	p.logDNSMessage(d.Res)

proxy/serverhttps_internal_test.go

@@ -75,27 +75,30 @@ func TestProxy_trustedProxies(t *testing.T) {
 	)
 
 	doRequest := func(t *testing.T, addr, expectedClientIP netip.Addr) {
+		var gotAddr netip.Addr
+		reqHandler := &TestRequestHandler{
+			OnHandle: func(p *Proxy, d *DNSContext) (err error) {
+				gotAddr = d.Addr.Addr()
+
+				return p.Resolve(d)
+			},
+		}
+
 		// Prepare the proxy server.
 		tlsConf, caPem := newTLSConfig(t)
 		dnsProxy := mustNew(t, &Config{
 			Logger:                 slogutil.NewDiscardLogger(),
+			UpstreamConfig:         newTestUpstreamConfig(t, defaultTimeout, testDefaultUpstreamAddr),
+			TrustedProxies:         defaultTrustedProxies,
+			RequestHandler:         reqHandler,
+			TLSConfig:              tlsConf,
 			TLSListenAddr:          []*net.TCPAddr{net.TCPAddrFromAddrPort(localhostAnyPort)},
 			HTTPSListenAddr:        []*net.TCPAddr{net.TCPAddrFromAddrPort(localhostAnyPort)},
 			QUICListenAddr:         []*net.UDPAddr{net.UDPAddrFromAddrPort(localhostAnyPort)},
-			TLSConfig:              tlsConf,
-			UpstreamConfig:         newTestUpstreamConfig(t, defaultTimeout, testDefaultUpstreamAddr),
-			TrustedProxies:         defaultTrustedProxies,
 			RatelimitSubnetLenIPv4: 24,
 			RatelimitSubnetLenIPv6: 64,
 		})
 
-		var gotAddr netip.Addr
-		dnsProxy.RequestHandler = func(_ *Proxy, d *DNSContext) (err error) {
-			gotAddr = d.Addr.Addr()
-
-			return dnsProxy.Resolve(d)
-		}
-
 		client := createTestHTTPClient(dnsProxy, caPem, false)
 
 		msg := newTestMessage()