feat: add LookupTXTWithTTL to Resolver (#75)

* feat: add LookupTXTWithTTL to Resolver

Resolver.LookupTXT returns only TXT values and drops the TTL, so a
resolver that knows it (such as DNS-over-HTTPS) cannot report it and
callers cannot tell how long a record set is valid or when to
re-resolve. Correct caching and expiration needs that TTL for both
kinds of TXT records this library resolves:

- DNSADDR (dnsaddr=): the TTL bounds how long a resolved multiaddr is
  valid. Multiaddrs increasingly carry rotating /certhash/ segments
  (AutoTLS WebTransport and WebRTC-direct nodes, including libp2p
  bootstrappers); without the TTL these cannot be cached or expired
  correctly, so a peer cannot reliably publish addresses whose certhash
  changes over time.
- DNSLink (dnslink=): the TTL lets an IPFS gateway set Cache-Control
  max-age for /ipns/<dnslink-host> responses (ipfs/boxo#329).

Add LookupTXTWithTTL, which routes to the matched per-domain resolver
and returns its TTL when it implements the new TXTWithTTLResolver
interface; resolvers without TTL support (such as the OS resolver)
report 0 (unknown). LookupTXT and BasicResolver are unchanged, so this
is additive.

* docs: clarify which resolver reports the TTL

LookupTXTWithTTL routes TTL reporting through whichever resolver the
lookup matches, including the default one, not only per-domain
resolvers. New test pins the default-resolver path.

* chore: release v0.6.0

Author: lidel

resolve.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"net"
 	"strings"
+	"time"
 
 	ma "github.com/multiformats/go-multiaddr"
 )
@@ -312,3 +313,29 @@ func (r *Resolver) LookupIPAddr(ctx context.Context, domain string) ([]net.IPAdd
 func (r *Resolver) LookupTXT(ctx context.Context, txt string) ([]string, error) {
 	return r.getResolver(txt).LookupTXT(ctx, txt)
 }
+
+// TXTWithTTLResolver is an optional interface a [BasicResolver] may implement to
+// report the TTL of a TXT record set alongside its values. Resolvers backed by
+// a protocol that carries TTLs (such as DNS-over-HTTPS) can implement it; the
+// default OS resolver cannot.
+type TXTWithTTLResolver interface {
+	LookupTXTWithTTL(ctx context.Context, name string) (txt []string, ttl time.Duration, err error)
+}
+
+// a Resolver routes TXT-with-TTL lookups, so it satisfies the interface too
+var _ TXTWithTTLResolver = (*Resolver)(nil)
+
+// LookupTXTWithTTL resolves the TXT records for a domain and, when the resolver
+// the lookup routes to (a matched per-domain resolver, or the default one
+// otherwise) implements [TXTWithTTLResolver], also returns their TTL. Resolvers
+// that cannot report a TTL (such as the default OS resolver) yield a TTL of 0,
+// meaning unknown.
+func (r *Resolver) LookupTXTWithTTL(ctx context.Context, domain string) ([]string, time.Duration, error) {
+	rslv := r.getResolver(domain)
+	if ttlRslv, ok := rslv.(TXTWithTTLResolver); ok {
+		return ttlRslv.LookupTXTWithTTL(ctx, domain)
+	}
+
+	txt, err := rslv.LookupTXT(ctx, domain)
+	return txt, 0, err
+}

resolve_ttl_test.go

@@ -0,0 +1,87 @@
+package madns
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// mockTTLResolver is a MockResolver that also reports a fixed TTL for TXT lookups.
+type mockTTLResolver struct {
+	*MockResolver
+	ttl time.Duration
+}
+
+func (r *mockTTLResolver) LookupTXTWithTTL(ctx context.Context, name string) ([]string, time.Duration, error) {
+	txt, err := r.MockResolver.LookupTXT(ctx, name)
+	return txt, r.ttl, err
+}
+
+func TestLookupTXTWithTTL(t *testing.T) {
+	ctx := context.Background()
+
+	def := &MockResolver{TXT: map[string][]string{
+		"example.com": {"dnslink=/ipfs/bafkqaaa"},
+	}}
+	withTTL := &mockTTLResolver{
+		MockResolver: &MockResolver{TXT: map[string][]string{
+			"custom.test": {"dnslink=/ipfs/bafkqaaa"},
+		}},
+		ttl: 42 * time.Second,
+	}
+
+	rslv, err := NewResolver(
+		WithDefaultResolver(def),
+		WithDomainResolver("custom.test", withTTL),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// the matched per-domain resolver supports TTL, so it is reported
+	txt, ttl, err := rslv.LookupTXTWithTTL(ctx, "custom.test")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(txt) != 1 {
+		t.Fatalf("expected 1 TXT record, got %d", len(txt))
+	}
+	if ttl != 42*time.Second {
+		t.Fatalf("expected ttl 42s, got %s", ttl)
+	}
+
+	// the default resolver does not support TTL, so it is reported as unknown (0)
+	_, ttl, err = rslv.LookupTXTWithTTL(ctx, "example.com")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ttl != 0 {
+		t.Fatalf("expected unknown ttl 0 for resolver without TTL support, got %s", ttl)
+	}
+}
+
+func TestLookupTXTWithTTLDefaultResolver(t *testing.T) {
+	ctx := context.Background()
+
+	// TTL flows through when the default resolver (no per-domain match)
+	// supports it
+	withTTL := &mockTTLResolver{
+		MockResolver: &MockResolver{TXT: map[string][]string{
+			"example.com": {"dnslink=/ipfs/bafkqaaa"},
+		}},
+		ttl: 7 * time.Second,
+	}
+
+	rslv, err := NewResolver(WithDefaultResolver(withTTL))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, ttl, err := rslv.LookupTXTWithTTL(ctx, "example.com")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ttl != 7*time.Second {
+		t.Fatalf("expected ttl 7s from the default resolver, got %s", ttl)
+	}
+}

version.json

@@ -1,3 +1,3 @@
 {
-  "version": "v0.5.0"
+  "version": "v0.6.0"
 }