go1.16 (#14783)

vendor/github.com/libdns/libdns/README.md

@@ -3,18 +3,57 @@ libdns - Universal DNS provider APIs for Go
 
 <a href="https://pkg.go.dev/github.com/libdns/libdns"><img src="https://img.shields.io/badge/godoc-reference-blue.svg"></a>
 
-`libdns` is a collection of free-range DNS provider client implementations written in Go! With libdns packages, your Go program can manage DNS records across any supported providers.
+**⚠️ Work-in-progress. Exported APIs are subject to change.**
 
-**⚠️ Work-in-progress. Exported APIs are subject to change. More documentation is coming soon.**
+`libdns` is a collection of free-range DNS provider client implementations written in Go! With libdns packages, your Go program can manage DNS records across any supported providers. A "provider" is a service or program that manages a DNS zone.
 
-This repository defines the core interfaces that providers should implement. They are small and idiomatic Go interfaces with well-defined semantics.
+This repository defines the core interfaces that provider packages should implement. They are small and idiomatic Go interfaces with well-defined semantics.
 
 The interfaces include:
 
-- `RecordGetter` to list records.
-- `RecordAppender` to append new records.
-- `RecordSetter` to set (create or change existing) records.
-- `RecordDeleter` to delete records.
+- [`RecordGetter`](https://pkg.go.dev/github.com/libdns/libdns#RecordGetter) to list records.
+- [`RecordAppender`](https://pkg.go.dev/github.com/libdns/libdns#RecordAppender) to append new records.
+- [`RecordSetter`](https://pkg.go.dev/github.com/libdns/libdns#RecordSetter) to set (create or change existing) records.
+- [`RecordDeleter`](https://pkg.go.dev/github.com/libdns/libdns#RecordDeleter) to delete records.
+
+[See full godoc for detailed documentation.](https://pkg.go.dev/github.com/libdns/libdns)
+
+
+## Example
+
+To work with DNS records managed by Cloudflare, for example, we can use [libdns/cloudflare](https://pkg.go.dev/github.com/libdns/cloudflare):
+
+```go
+import (
+	"github.com/libdns/cloudflare"
+	"github.com/libdns/libdns"
+)
+
+ctx := context.TODO()
+
+zone := "example.com."
+
+// configure the DNS provider (choose any from github.com/libdns)
+provider := cloudflare.Provider{APIToken: "topsecret"}
+
+// list records
+recs, err := provider.GetRecords(ctx, zone)
+
+// create records (AppendRecords is similar)
+newRecs, err := provider.SetRecords(ctx, zone, []libdns.Record{
+	Type:  "A",
+	Name:  "sub",
+	Value: "1.2.3.4",
+})
+
+// delete records (this example uses provider-assigned ID)
+deletedRecs, err := provider.DeleteRecords(ctx, zone, []libdns.Record{
+	ID: "foobar",
+})
+
+// no matter which provider you use, the code stays the same!
+// (some providers have caveats; see their package documentation)
+```
 
 
 ## Implementing new providers

vendor/github.com/libdns/libdns/libdns.go

@@ -1,7 +1,23 @@
-// Package libdns defines the core interfaces that should be implemented
-// by DNS provider clients. They are small and idiomatic Go interfaces with
+// Package libdns defines core interfaces that should be implemented by DNS
+// provider clients. They are small and idiomatic Go interfaces with
 // well-defined semantics.
 //
+// Records are described independently of any particular zone, a convention
+// that grants Record structs portability across zones. As such, record names
+// are partially qualified, i.e. relative to the zone. For example, an A
+// record called "sub" in zone "example.com." represents a fully-qualified
+// domain name (FQDN) of "sub.example.com.". Implementations should expect
+// that input records conform to this standard, while also ensuring that
+// output records do; adjustments to record names may need to be made before
+// or after provider API calls, for example, to maintain consistency with
+// all other libdns provider implementations. Helper functions are available
+// in this package to convert between relative and absolute names.
+//
+// Although zone names are a required input, libdns does not coerce any
+// particular representation of DNS zones; only records. Since zone name and
+// records are separate inputs in libdns interfaces, it is up to the caller
+// to pair a zone's name with its records in a way that works for them.
+//
 // All interface implementations must be safe for concurrent/parallel use.
 // For example, if AppendRecords() is called at the same time and two API
 // requests are made to the provider at the same time, the result of both
@@ -9,13 +25,14 @@
 // not synchronize the writing of the zone file and one request overwrites
 // the other, then the client implementation must take care to synchronize
 // on behalf of the incompetent provider. This synchronization need not be
-// global, for example: the scope of synchronization might only need to be
+// global; for example: the scope of synchronization might only need to be
 // within the same zone, allowing multiple requests at once as long as all
 // of them are for different zones. (Exact logic depends on the provider.)
 package libdns
 
 import (
 	"context"
+	"strings"
 	"time"
 )
 
@@ -79,7 +96,31 @@ type Record struct {
 
 	// general record fields
 	Type  string
-	Name  string
+	Name  string // partially-qualified (relative to zone)
 	Value string
 	TTL   time.Duration
 }
+
+// RelativeName makes fqdn relative to zone. For example, for a FQDN of
+// "sub.example.com" and a zone of "example.com", it outputs "sub".
+//
+// If fqdn cannot be expressed relative to zone, the input fqdn is returned.
+func RelativeName(fqdn, zone string) string {
+	return strings.TrimSuffix(strings.TrimSuffix(fqdn, zone), ".")
+}
+
+// AbsoluteName makes name into a fully-qualified domain name (FQDN) by
+// prepending it to zone and tidying up the dots. For example, an input
+// of name "sub" and zone "example.com." will return "sub.example.com.".
+func AbsoluteName(name, zone string) string {
+	if zone == "" {
+		return strings.Trim(name, ".")
+	}
+	if name == "" || name == "@" {
+		return zone
+	}
+	if !strings.HasSuffix(name, ".") {
+		name += "."
+	}
+	return name + zone
+}