Merge pull request #29 from dchudik/master

Added client for new version DNS v2 API.

.golangci.yml

@@ -8,4 +8,38 @@ linters:
     - gosec
     - lll
     - wsl
-    - gomnd
+    - testpackage
+    # deprecated linters
+    - maligned
+    - interfacer
+    - ifshort
+    - golint
+    - scopelint
+    - structcheck
+    - deadcode
+    - varcheck
+    - nosnakecase
+    - exhaustivestruct
+
+
+
+linters-settings:
+  tagliatelle:
+    case:
+      use-field-name: true
+      rules:
+        json: snake
+        yaml: snake
+  depguard:
+    rules:
+      main:
+        allow:
+          - "$gostd"
+          - "github.com/selectel/domains-go/pkg/v2"
+          - "github.com/jarcoal/httpmock"
+          - "github.com/stretchr/testify/assert"
+          - "github.com/stretchr/testify/require"
+          - "github.com/stretchr/testify/suite"
+        deny:
+          - pkg: io/ioutil
+            desc: The io/ioutil package has been deprecated, see https://go.dev/doc/go1.16#ioutil

GNUmakefile

@@ -8,4 +8,7 @@ unittest:
 golangci-lint:
 	@sh -c "'$(CURDIR)/scripts/golangci_lint_check.sh'"
 
+doc:
+	godoc -http=:6060
+
 .PHONY: tests unittest golangci-lint

README.md

@@ -6,6 +6,15 @@
 
 Package domains-go provides Go SDK to work with the Selectel Domains API.
 
+## Contents
+
+* [Documentation](#documentation)
+* [Installation](#installation)
+* [Authentication](#authentication)
+* [Usage example](#usage-example)
+* [Current version vs Legacy version](#current-version-vs-legacy-version)
+* [Usage legacy example](#usage-legacy-example)
+
 ## Documentation
 
 The Go library documentation is available at [go.dev](https://pkg.go.dev/github.com/selectel/domains-go/).
@@ -14,8 +23,8 @@ The Go library documentation is available at [go.dev](https://pkg.go.dev/github.
 
 You can use this library to work with the following objects of the Selectel Domains API:
 
-* [domain](https://pkg.go.dev/github.com/selectel/domains-go/pkg/v1/domain)
-* [record](https://pkg.go.dev/github.com/selectel/domains-go/pkg/v1/record)
+* [zone](https://pkg.go.dev/github.com/selectel/domains-go/pkg/v2/#Zone)
+* [rrset](https://pkg.go.dev/github.com/selectel/domains-go/pkg/v2/#RRSet)
 
 ## Getting started
 
@@ -24,21 +33,123 @@ You can use this library to work with the following objects of the Selectel Doma
 You can install needed `domains-go` packages via `go get` command:
 
 ```bash
-go get github.com/selectel/domains-go/pkg/v1/domain github.com/selectel/domains-go/pkg/v1/record
+go get github.com/selectel/domains-go
 ```
 
 ### Authentication
 
 To work with the Selectel Domains API you first need to:
 
 * Create a Selectel account: [registration page](https://my.selectel.ru/registration).
-* Create an API token: https://my.selectel.ru/profile/apikeys
+* For **current** version create an [Keystone Project Token](https://developers.selectel.com/docs/control-panel/authorization/#project-token)
+* For **legacy** version create an [Selectel Token](https://developers.selectel.com/docs/control-panel/authorization/#selectel-token-api-key)
+
+❗️IMPORTANT❗️  
+`Selectel Token` and `Keystone Project Token` are **different** tokens!  
+Above we mentioned how to get keystone project token, how to obtain selectel token read [here](https://developers.selectel.com/docs/control-panel/authorization)
 
 ### Usage example
 
 ```go
 package main
 
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+
+	v2 "github.com/selectel/domains-go/pkg/v2"
+)
+
+func main() {
+	// Keystone project token. Read more in authorization.
+	token := "gAAAAABeVNzu-..."
+
+	// Domains API V2 endpoint to work with
+	endpoint := "https://api.selectel.ru/domains/v2"
+
+	httpClient := &http.Client{}
+	userAgent := "domains-go-v2"
+	hdrs := http.Header{}
+	hdrs.Add("X-Auth-Token", token)
+	hdrs.Add("User-Agent", userAgent)
+	// Initialize the Domains API V2 client
+	client := v2.NewClient(endpoint, httpClient, hdrs)
+
+	createZoneOpts := &v2.Zone{
+		Name: "domains-go-v2.ru.",
+	}
+
+	// Create zone
+	selectelCreatedZone, err := client.CreateZone(context.Background(), createZoneOpts)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("Created zone: %+v\n", selectelCreatedZone)
+
+	listZonesOpts := &map[string]string{}
+	// List zones
+	selectelZones, err := client.ListZones(context.Background(), listZonesOpts)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	for _, zone := range selectelZones.GetItems() {
+		fmt.Printf("%+v\n", zone)
+	}
+
+	createRrsetOpts := &v2.RRSet{
+		Name: "txt.domains-go-v2.ru.",
+		Type: v2.TXT,
+		TTL:  60,
+		Records: []v2.RecordItem{
+			// Only for TXT Rrset escaping quotes
+			{Content: "\"Hello world!\""},
+		},
+	}
+
+	// Create rrset type TXT
+	selectelCreatedRrset, err := client.CreateRRSet(context.Background(), selectelCreatedZone.UUID, createRrsetOpts)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("Created rrset: %+v\n", selectelCreatedRrset)
+}
+```
+
+
+## Current version vs Legacy version
+
+Current version is `github.com/selectel/domains-go/pkg/v2`  
+Legacy version is `github.com/selectel/domains-go/pkg/v1`  
+
+They are not compatible. They utilize different API and created zones live on different authoritative servers.
+Zone created in v2 API with current version is entirely new zone, and not available via v1 api and vice versa.  
+
+If you are going to create new zone, we strongly recommend to use `github.com/selectel/domains-go/pkg/v2`.  
+If you have zones in v1, you still can manage them with `github.com/selectel/domains-go/pkg/v1`.
+
+Legacy version following objects of the Selectel Domains API v1:
+
+* [domain](https://pkg.go.dev/github.com/selectel/domains-go/pkg/v1/domain)
+* [record](https://pkg.go.dev/github.com/selectel/domains-go/pkg/v1/record)
+
+Current version following objects of the Selectel Domains API v2:
+
+* [zone](https://pkg.go.dev/github.com/selectel/domains-go/pkg/v2/#Zone)
+* [rrset](https://pkg.go.dev/github.com/selectel/domains-go/pkg/v2/#RRSet)
+
+### Usage legacy example
+
+❗️IMPORTANT❗️
+We are not recommending using this example.
+
+```go
+package main
+
 import (
 	"context"
 	"fmt"

go.mod

@@ -1,3 +1,12 @@
 module github.com/selectel/domains-go
 
-go 1.15
+go 1.20
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/jarcoal/httpmock v1.3.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/stretchr/objx v0.5.0 // indirect
+	github.com/stretchr/testify v1.8.4 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

go.sum

@@ -0,0 +1,19 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/jarcoal/httpmock v1.3.1 h1:iUx3whfZWVf3jT01hQTO/Eo5sAYtB2/rqaUuOtpInww=
+github.com/jarcoal/httpmock v1.3.1/go.mod h1:3yb8rc4BI7TCBhFY8ng0gjuLKJNquuDNiPaZjnENuYg=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0 h1:1zr/of2m5FGMsad5YfcqgdqdWrIhu+EBEJRhR1U7z/c=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

pkg/v2/base.go

@@ -0,0 +1,53 @@
+package v2
+
+import (
+	"context"
+	"io"
+	"net/http"
+)
+
+const (
+	rootPath        = "/zones"
+	zonePath        = "/zones/%v"
+	rrsetPath       = "/zones/%v/rrset"
+	singleRRSetPath = "/zones/%v/rrset/%v"
+)
+
+type (
+	DNSClient[Z any, S any] interface {
+		ZoneManager[Z]
+		RRSetManager[S]
+		WithHeaders(headers http.Header) DNSClient[Z, S]
+	}
+
+	ZoneManager[Z any] interface {
+		GetZone(ctx context.Context, zoneID string, options *map[string]string) (*Z, error)
+		ListZones(ctx context.Context, options *map[string]string) (Listable[Z], error)
+		CreateZone(ctx context.Context, zone Creatable) (*Z, error)
+		DeleteZone(ctx context.Context, zoneID string) error
+		UpdateZoneState(ctx context.Context, zoneID string, disabled bool) error
+		UpdateZoneComment(ctx context.Context, zoneID string, comment string) error
+	}
+
+	RRSetManager[S any] interface {
+		CreateRRSet(ctx context.Context, zoneID string, rrset Creatable) (*S, error)
+		GetRRSet(ctx context.Context, zoneID, rrsetID string) (*S, error)
+		ListRRSets(ctx context.Context, zoneID string, options *map[string]string) (Listable[S], error)
+		UpdateRRSet(ctx context.Context, zoneID, rrsetID string, rrset Updatable) error
+		DeleteRRSet(ctx context.Context, zoneID, rrsetID string) error
+	}
+
+	Listable[T any] interface {
+		GetCount() int
+		GetNextOffset() int
+		GetItems() []*T
+	}
+
+	Creatable interface {
+		CreationForm() (io.Reader, error)
+	}
+
+	Updatable interface {
+		UpdateForm() (io.Reader, error)
+	}
+)