feat(dev): Add provider example package

internal/provider/example/updater/api.go

@@ -0,0 +1,61 @@
+package updater
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+)
+
+var (
+	errHTTPStatusCodeNotOK = errors.New("HTTP status code not OK")
+)
+
+type apiData struct {
+	Servers []apiServer `json:"servers"`
+}
+
+type apiServer struct {
+	OpenVPNHostname   string `json:"openvpn_hostname"`
+	WireguardHostname string `json:"wireguard_hostname"`
+	Country           string `json:"country"`
+	Region            string `json:"region"`
+	City              string `json:"city"`
+	WgPubKey          string `json:"wg_public_key"`
+}
+
+func fetchAPI(ctx context.Context, client *http.Client) (
+	data apiData, err error) {
+	// TODO: adapt this URL and the structures above to match the real
+	// API models you have.
+	const url = "https://example.com/servers"
+
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return data, err
+	}
+
+	response, err := client.Do(request)
+	if err != nil {
+		return data, err
+	}
+
+	if response.StatusCode != http.StatusOK {
+		_ = response.Body.Close()
+		return data, fmt.Errorf("%w: %d %s",
+			errHTTPStatusCodeNotOK, response.StatusCode, response.Status)
+	}
+
+	decoder := json.NewDecoder(response.Body)
+	if err := decoder.Decode(&data); err != nil {
+		_ = response.Body.Close()
+		return data, fmt.Errorf("failed unmarshaling response body: %w", err)
+	}
+
+	if err := response.Body.Close(); err != nil {
+		return data, fmt.Errorf("cannot close response body: %w", err)
+	}
+
+	return data, nil
+}

internal/provider/example/updater/resolve.go

@@ -0,0 +1,32 @@
+package updater
+
+import (
+	"time"
+
+	"github.com/qdm12/gluetun/internal/updater/resolver"
+)
+
+// TODO: remove this file if the parallel resolver is not used
+// by the updater.
+func parallelResolverSettings(hosts []string) (settings resolver.ParallelSettings) {
+	// TODO: adapt these constant values below to make the resolution
+	// as fast and as reliable as possible.
+	const (
+		maxFailRatio    = 0.1
+		maxDuration     = 20 * time.Second
+		betweenDuration = time.Second
+		maxNoNew        = 2
+		maxFails        = 2
+	)
+	return resolver.ParallelSettings{
+		Hosts:        hosts,
+		MaxFailRatio: maxFailRatio,
+		Repeat: resolver.RepeatSettings{
+			MaxDuration:     maxDuration,
+			BetweenDuration: betweenDuration,
+			MaxNoNew:        maxNoNew,
+			MaxFails:        maxFails,
+			SortIPs:         true,
+		},
+	}
+}

internal/provider/example/updater/servers.go

@@ -0,0 +1,122 @@
+package updater
+
+import (
+	"context"
+	"fmt"
+	"sort"
+
+	"github.com/qdm12/gluetun/internal/constants/vpn"
+	"github.com/qdm12/gluetun/internal/models"
+	"github.com/qdm12/gluetun/internal/provider/common"
+)
+
+func (u *Updater) FetchServers(ctx context.Context, minServers int) (
+	servers []models.Server, err error) {
+	// FetchServers obtains information for each VPN server
+	// for the VPN service provider.
+	//
+	// You should aim at obtaining as much information as possible
+	// for each server, such as their location information.
+	// Required fields for each server are:
+	// - the `VPN` protocol string field
+	// - the `Hostname` string field
+	// - the `IPs` IP slice field
+	// - have one network protocol set, either `TCP` or `UDP`
+	// - If `VPN` is `wireguard`, the `WgPubKey` field to be set
+	//
+	// The information obtention can be done in different ways
+	// or by combining ways, depending on how the provider exposes
+	// this information. Some common ones are listed below:
+	//
+	// - you can use u.client to fetch structured (usually JSON)
+	// data of the servers from an HTTP API endpoint of the provider.
+	// Example in: `internal/provider/mullvad/updater`
+	// - you can use u.unzipper to download, unzip and parse a zip
+	// file of OpenVPN configuration files.
+	// Example in: `internal/provider/fastestvpn/updater`
+	// - you can use u.parallelResolver to resolve all hostnames
+	// found in parallel to obtain their corresponding IP addresses.
+	// Example in: `internal/provider/fastestvpn/updater`
+	//
+	// The following is an example code which fetches server
+	// information from an HTTP API endpoint of the provider,
+	// and then resolves in parallel all hostnames to get their
+	// IP addresses. You should pay attention to the following:
+	// - we check multiple times we have enough servers
+	// before continuing processing.
+	// - hosts are deduplicated to reduce parallel resolution
+	// load.
+	// - servers are sorted at the end.
+	//
+	// Once you are done, please check all the TODO comments
+	// in this package and address them.
+	data, err := fetchAPI(ctx, u.client)
+	if err != nil {
+		return nil, fmt.Errorf("fetching API: %w", err)
+	}
+
+	uniqueHosts := make(map[string]struct{}, len(data.Servers))
+
+	for _, serverData := range data.Servers {
+		if serverData.OpenVPNHostname != "" {
+			uniqueHosts[serverData.OpenVPNHostname] = struct{}{}
+		}
+
+		if serverData.WireguardHostname != "" {
+			uniqueHosts[serverData.WireguardHostname] = struct{}{}
+		}
+	}
+
+	if len(uniqueHosts) < minServers {
+		return nil, fmt.Errorf("%w: %d and expected at least %d",
+			common.ErrNotEnoughServers, len(uniqueHosts), minServers)
+	}
+
+	hosts := make([]string, 0, len(uniqueHosts))
+	for host := range uniqueHosts {
+		hosts = append(hosts, host)
+	}
+
+	resolveSettings := parallelResolverSettings(hosts)
+	hostToIPs, warnings, err := u.parallelResolver.Resolve(ctx, resolveSettings)
+	for _, warning := range warnings {
+		u.warner.Warn(warning)
+	}
+	if err != nil {
+		return nil, fmt.Errorf("resolving hosts: %w", err)
+	}
+
+	if len(hostToIPs) < minServers {
+		return nil, fmt.Errorf("%w: %d and expected at least %d",
+			common.ErrNotEnoughServers, len(servers), minServers)
+	}
+
+	maxServers := 2 * len(data.Servers) //nolint:gomnd
+	servers = make([]models.Server, 0, maxServers)
+	for _, serverData := range data.Servers {
+		server := models.Server{
+			Country:  serverData.Country,
+			Region:   serverData.Region,
+			City:     serverData.City,
+			WgPubKey: serverData.WgPubKey,
+			UDP:      true,
+		}
+		if serverData.OpenVPNHostname != "" {
+			server.VPN = vpn.OpenVPN
+			server.TCP = true
+			server.Hostname = serverData.OpenVPNHostname
+			server.IPs = hostToIPs[serverData.OpenVPNHostname]
+			servers = append(servers, server)
+		}
+		if serverData.WireguardHostname != "" {
+			server.VPN = vpn.Wireguard
+			server.Hostname = serverData.WireguardHostname
+			server.IPs = hostToIPs[serverData.WireguardHostname]
+			servers = append(servers, server)
+		}
+	}
+
+	sort.Sort(models.SortableServers(servers))
+
+	return servers, nil
+}

internal/provider/example/updater/updater.go

@@ -0,0 +1,26 @@
+package updater
+
+import (
+	"net/http"
+
+	"github.com/qdm12/gluetun/internal/provider/common"
+)
+
+type Updater struct {
+	// TODO: remove fields not used by the updater
+	client           *http.Client
+	unzipper         common.Unzipper
+	parallelResolver common.ParallelResolver
+	warner           common.Warner
+}
+
+func New(warner common.Warner, unzipper common.Unzipper,
+	client *http.Client, parallelResolver common.ParallelResolver) *Updater {
+	// TODO: remove arguments not used by the updater
+	return &Updater{
+		client:           client,
+		unzipper:         unzipper,
+		parallelResolver: parallelResolver,
+		warner:           warner,
+	}
+}