As I migrate dnscontrol to dns v2, I have some suggestions that would be useful for https://codeberg.org/miekg/dns/src/branch/main/README-diff-with-v1.md
I can turn these into a PR if you wish.
General tips:
-
Before you convert to dns v2, convert from net.IP to netip.Addr. DNS v2 uses netip.Addr to represent IP addresses. It is easier to only do one conversion at a time.
-
Rename the old code "dnsv1".
Change all imports from
"github.com/miekg/dns"
to
dnsv1 "github.com/miekg/dns"
Now v1 and v2 can co-exist. dnsv1.RR is the old code and dns.RR is the new code.
This is not required, but it will make things easier. In fact, first I made a release that changed nothing but dns to dnsv1. Once that worked, it was easy to search for dnsv1 and convert things one at a time.
VSCode makes this easy. Find a user of dns and use "Rename Symbol" (i.e. F2). For example, I found dns.IP, moved the cursor
to the "d" in "dns", and pressed F2. Renamed dns to dnsv1. This changed the import and all uses of that package. However you need to do this once for each file.
You can do something similar for dnsutil (dnsutilv1) and so on.
Again, this isn't required. I just found it useful.
- Make a temporary conversion function
I wanted v1 and v2 to co-exist so that I could work and test incrementally. To make that easy I created a way to convert RR from v1 to v2 and back. The functions are slow and ugly, but accuracy is more important. I actually like that the functions are slow because it gives me incentive to finish porting to v2.
Here are the functions I am using:
package dnsrr
import (
dnsv2 "codeberg.org/miekg/dns"
dnsv1 "github.com/miekg/dns"
)
// RRv1tov2 converts github.com/miekg/dns (v1) RR to codeberg.org/miekg/dns (v2) RR.
// Typically used in providers that still use v1.
// Note: this function is not efficient. It converts via string representation.
// Use it until you are able to convert to v2 fully.
// Note: Panics on error.
func RRv1tov2(rrv1 dnsv1.RR) dnsv2.RR {
rrv2, err := dnsv2.New(rrv1.String())
if err != nil {
panic("Failed to convert RR to v2: " + err.Error())
}
return rrv2
}
// RRv2tov1 converts codeberg.org/miekg/dns (v2) RR to github.com/miekg/dns (v1) RR.
// Typically used in providers that still use v1.
// Note: this function is not efficient. It converts via string representation.
// Use it until you are able to convert to v1 fully.
// Note: Panics on error.
func RRv2tov1(rrv2 dnsv2.RR) dnsv1.RR {
rrv1, err := dnsv1.NewRR(rrv2.String())
if err != nil {
panic("Failed to convert RR to v1: " + err.Error())
}
return rrv1
}
Converting idioms
Some of these took a while to figure out. Hopefully this will save time for others:
What type is this RR? (and convert to a string)
OLD:
header := rr.Header()
rrtype := header.Rrtype
typeStr := dns.TypeToString[header.Rrtype]
NEW:
rrtype := dns.RRToType(rr)
rrtypeStr := dns.TypeToString[rrtype]
Canonicalize a DNS name:
OLD:
id := dns.CanonicalName(foo)
NEW:
id := dnsutil.Canonical(foo)
Find the TTL
OLD:
rr.Header().Ttl
NEW:
rr.Header().TTL
Allow includes
OLD:
zp := dns.NewZoneParser(...)
zp.SetIncludeAllowed(true)
NEW:
zp := dns.NewZoneParser(...)
(nothing. that's the default)
Don't allow includes:
OLD:
zp := dns.NewZoneParser(...)
zp.SetIncludeAllowed(false)
NEW:
zp := dns.NewZoneParser(...)
zp.IncludeAllowFunc = func() bool { return false }
Useful idioms
These aren't for the conversion guide. These are for the general documentation.
Create a RR of a specific record type:
rr := dns.TypeToRR[rdtype]()
Update the header of an RR:
*(rr.Header()) = dns.Header{Name: rc.NameFQDN + ".", Class: dns.ClassINET}
or
hdr := rr.Header()
*hdr = dns.Header{Name: rc.NameFQDN + ".", Class: dns.ClassINET}
or
rr.Header().Name = "example.com."
rr.Header().Class = dns.ClassINET
By the way... the example in https://pkg.go.dev/codeberg.org/miekg/dns
r := &MX{Header{Name:"miek.nl.", Class: dns.ClassINET, TTL: 3600}, MX: rdata.MX{Preference: 10, Mx: "mx.miek.nl."}}
it might be easier for newcomers if &MX was written &dns.MX
r := &dns.MX{Header{Name:"miek.nl.", Class: dns.ClassINET, TTL: 3600}, MX: rdata.MX{Preference: 10, Mx: "mx.miek.nl."}}
Hope that helps!