Pull request 2110: AG-27492-client-persistent

Squashed commit of the following:

commit 6605cd1
Merge: 5b294a2 bec3cab
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Thu Dec 28 16:51:39 2023 +0300

    Merge branch 'master' into AG-27492-client-persistent

commit 5b294a2
Merge: afe4d5f d75712b
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Wed Dec 27 19:13:50 2023 +0300

    Merge branch 'master' into AG-27492-client-persistent

commit afe4d5f
Merge: 05dc0bf ad147ac
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Tue Dec 26 14:59:10 2023 +0300

    Merge branch 'master' into AG-27492-client-persistent

commit 05dc0bf
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Wed Dec 20 19:44:04 2023 +0300

    home: imp err msg

commit c3b21c7
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Mon Dec 18 15:05:29 2023 +0300

    all: imp docs

commit a2118f5
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Fri Dec 15 18:27:50 2023 +0300

    all: add persistent client uid

CHANGELOG.md

@@ -40,6 +40,8 @@ NOTE: Add new changes BELOW THIS COMMENT.
 
 #### Configuration changes
 
+- The new property `clients.persistent.*.uid`, which is unique identifier of the
+  persistent client.
 - The properties `dns.'all_servers` and `dns.fastest_addr` were removed, their
   values migrated to newly added field `dns.upstream_mode` that describes the
   logic through which upstreams will be used.

internal/home/client.go

@@ -1,17 +1,46 @@
 package home
 
 import (
+	"encoding"
 	"fmt"
 	"time"
 
 	"github.com/AdguardTeam/AdGuardHome/internal/filtering"
 	"github.com/AdguardTeam/AdGuardHome/internal/filtering/safesearch"
 	"github.com/AdguardTeam/dnsproxy/proxy"
 	"github.com/AdguardTeam/golibs/stringutil"
+	"github.com/google/uuid"
 )
 
-// Client contains information about persistent clients.
-type Client struct {
+// UID is the type for the unique IDs of persistent clients.
+type UID uuid.UUID
+
+// NewUID returns a new persistent client UID.  Any error returned is an error
+// from the cryptographic randomness reader.
+func NewUID() (uid UID, err error) {
+	uuidv7, err := uuid.NewV7()
+
+	return UID(uuidv7), err
+}
+
+// type check
+var _ encoding.TextMarshaler = UID{}
+
+// MarshalText implements the [encoding.TextMarshaler] for UID.
+func (uid UID) MarshalText() ([]byte, error) {
+	return uuid.UUID(uid).MarshalText()
+}
+
+// type check
+var _ encoding.TextUnmarshaler = (*UID)(nil)
+
+// UnmarshalText implements the [encoding.TextUnmarshaler] interface for UID.
+func (uid *UID) UnmarshalText(data []byte) error {
+	return (*uuid.UUID)(uid).UnmarshalText(data)
+}
+
+// persistentClient contains information about persistent clients.
+type persistentClient struct {
 	// upstreamConfig is the custom upstream configuration for this client.  If
 	// it's nil, it has not been initialized yet.  If it's non-nil and empty,
 	// there are no valid upstreams.  If it's non-nil and non-empty, these
@@ -31,6 +60,9 @@ type Client struct {
 	Tags      []string
 	Upstreams []string
 
+	// UID is the unique identifier of the persistent client.
+	UID UID
+
 	UpstreamsCacheSize    uint32
 	UpstreamsCacheEnabled bool
 
@@ -45,7 +77,7 @@ type Client struct {
 
 // ShallowClone returns a deep copy of the client, except upstreamConfig,
 // safeSearchConf, SafeSearch fields, because it's difficult to copy them.
-func (c *Client) ShallowClone() (sh *Client) {
+func (c *persistentClient) ShallowClone() (sh *persistentClient) {
 	clone := *c
 
 	clone.BlockedServices = c.BlockedServices.Clone()
@@ -57,7 +89,7 @@ func (c *Client) ShallowClone() (sh *Client) {
 }
 
 // closeUpstreams closes the client-specific upstream config of c if any.
-func (c *Client) closeUpstreams() (err error) {
+func (c *persistentClient) closeUpstreams() (err error) {
 	if c.upstreamConfig != nil {
 		if err = c.upstreamConfig.Close(); err != nil {
 			return fmt.Errorf("closing upstreams of client %q: %w", c.Name, err)
@@ -68,7 +100,7 @@ func (c *Client) closeUpstreams() (err error) {
 }
 
 // setSafeSearch initializes and sets the safe search filter for this client.
-func (c *Client) setSafeSearch(
+func (c *persistentClient) setSafeSearch(
 	conf filtering.SafeSearchConfig,
 	cacheSize uint,
 	cacheTTL time.Duration,