Pull request 2138: AG-27492-client-persistent-storage

Squashed commit of the following:

commit 37e33ec
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Wed Feb 14 15:25:25 2024 +0300

    aghalg: imp code

commit 6b2f09a
Merge: b8ea924 3773628
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Wed Feb 14 15:04:59 2024 +0300

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

commit b8ea924
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Tue Feb 13 19:07:52 2024 +0300

    home: imp tests

commit aa6fec0
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Tue Feb 13 14:54:28 2024 +0300

    home: imp docs

commit 10637fd
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Thu Feb 8 20:16:11 2024 +0300

    all: imp code

commit b45c7d8
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Wed Feb 7 19:15:11 2024 +0300

    aghalg: add tests

commit 7abe33d
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Tue Feb 6 20:50:22 2024 +0300

    all: imp code, tests

commit 4a44e99
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Thu Feb 1 14:59:11 2024 +0300

    all: persistent client index

commit 66b16e2
Author: Stanislav Chzhen <s.chzhen@adguard.com>
Date:   Wed Jan 31 15:06:05 2024 +0300

    aghalg: ordered map

internal/aghalg/sortedmap.go

@@ -0,0 +1,86 @@
+package aghalg
+
+import (
+	"slices"
+)
+
+// SortedMap is a map that keeps elements in order with internal sorting
+// function.  Must be initialised by the [NewSortedMap].
+type SortedMap[K comparable, V any] struct {
+	vals map[K]V
+	cmp  func(a, b K) (res int)
+	keys []K
+}
+
+// NewSortedMap initializes the new instance of sorted map.  cmp is a sort
+// function to keep elements in order.
+//
+// TODO(s.chzhen):  Use cmp.Compare in Go 1.21.
+func NewSortedMap[K comparable, V any](cmp func(a, b K) (res int)) SortedMap[K, V] {
+	return SortedMap[K, V]{
+		vals: map[K]V{},
+		cmp:  cmp,
+	}
+}
+
+// Set adds val with key to the sorted map.  It panics if the m is nil.
+func (m *SortedMap[K, V]) Set(key K, val V) {
+	m.vals[key] = val
+
+	i, has := slices.BinarySearchFunc(m.keys, key, m.cmp)
+	if has {
+		m.keys[i] = key
+	} else {
+		m.keys = slices.Insert(m.keys, i, key)
+	}
+}
+
+// Get returns val by key from the sorted map.
+func (m *SortedMap[K, V]) Get(key K) (val V, ok bool) {
+	if m == nil {
+		return
+	}
+
+	val, ok = m.vals[key]
+
+	return val, ok
+}
+
+// Del removes the value by key from the sorted map.
+func (m *SortedMap[K, V]) Del(key K) {
+	if m == nil {
+		return
+	}
+
+	if _, has := m.vals[key]; !has {
+		return
+	}
+
+	delete(m.vals, key)
+	i, _ := slices.BinarySearchFunc(m.keys, key, m.cmp)
+	m.keys = slices.Delete(m.keys, i, i+1)
+}
+
+// Clear removes all elements from the sorted map.
+func (m *SortedMap[K, V]) Clear() {
+	if m == nil {
+		return
+	}
+
+	m.keys = nil
+	clear(m.vals)
+}
+
+// Range calls cb for each element of the map, sorted by m.cmp.  If cb returns
+// false it stops.
+func (m *SortedMap[K, V]) Range(cb func(K, V) (cont bool)) {
+	if m == nil {
+		return
+	}
+
+	for _, k := range m.keys {
+		if !cb(k, m.vals[k]) {
+			return
+		}
+	}
+}

internal/aghalg/sortedmap_test.go

@@ -0,0 +1,95 @@
+package aghalg
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNewSortedMap(t *testing.T) {
+	var m SortedMap[string, int]
+
+	letters := []string{}
+	for i := 0; i < 10; i++ {
+		r := string('a' + rune(i))
+		letters = append(letters, r)
+	}
+
+	t.Run("create_and_fill", func(t *testing.T) {
+		m = NewSortedMap[string, int](strings.Compare)
+
+		nums := []int{}
+		for i, r := range letters {
+			m.Set(r, i)
+			nums = append(nums, i)
+		}
+
+		gotLetters := []string{}
+		gotNums := []int{}
+		m.Range(func(k string, v int) bool {
+			gotLetters = append(gotLetters, k)
+			gotNums = append(gotNums, v)
+
+			return true
+		})
+
+		assert.Equal(t, letters, gotLetters)
+		assert.Equal(t, nums, gotNums)
+
+		n, ok := m.Get(letters[0])
+		assert.True(t, ok)
+		assert.Equal(t, nums[0], n)
+	})
+
+	t.Run("clear", func(t *testing.T) {
+		lastLetter := letters[len(letters)-1]
+		m.Del(lastLetter)
+
+		_, ok := m.Get(lastLetter)
+		assert.False(t, ok)
+
+		m.Clear()
+
+		gotLetters := []string{}
+		m.Range(func(k string, _ int) bool {
+			gotLetters = append(gotLetters, k)
+
+			return true
+		})
+
+		assert.Len(t, gotLetters, 0)
+	})
+}
+
+func TestNewSortedMap_nil(t *testing.T) {
+	const (
+		key = "key"
+		val = "val"
+	)
+
+	var m SortedMap[string, string]
+
+	assert.Panics(t, func() {
+		m.Set(key, val)
+	})
+
+	assert.NotPanics(t, func() {
+		_, ok := m.Get(key)
+		assert.False(t, ok)
+	})
+
+	assert.NotPanics(t, func() {
+		m.Range(func(_, _ string) (cont bool) {
+			return true
+		})
+	})
+
+	assert.NotPanics(t, func() {
+		m.Del(key)
+	})
+
+	assert.NotPanics(t, func() {
+		m.Clear()
+	})
+}

internal/home/client.go

@@ -30,6 +30,16 @@ func NewUID() (uid UID, err error) {
 	return UID(uuidv7), err
 }
 
+// MustNewUID is a wrapper around [NewUID] that panics if there is an error.
+func MustNewUID() (uid UID) {
+	uid, err := NewUID()
+	if err != nil {
+		panic(fmt.Errorf("unexpected uuidv7 error: %w", err))
+	}
+
+	return uid
+}
+
 // type check
 var _ encoding.TextMarshaler = UID{}