github.com/creachadair/ffs@v0.17.3/storage/dbkey/dbkey.go

// Copyright 2019 Michael J. Fromberger. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Package dbkey provides some common utility code for working with key-value
// stores that use prefixes to partition the key space.
package dbkey

import (
	"crypto/sha256"
	"encoding/hex"
	"strings"
)

// PrefixLen is the length in bytes of the prefixes generated by this package.
const PrefixLen = 6

// Prefix is a prefix that defines a subset of the keys of a key-value store.
// Any string can be a valid prefix, including "".
type Prefix string

// Sub creates a subspace prefix based on p, using name.
// Derived prefixes are always [PrefixLen] bytes long.
func (p Prefix) Sub(name string) Prefix { return p.derive(".", name) }

// Keyspace creates a keyspace prefix based on p, using name.
// Derived prefixes are always [PrefixLen] bytes long.
func (p Prefix) Keyspace(name string) Prefix { return p.derive(":", name) }

// String renders p as a hexadecimal string.
func (p Prefix) String() string { return hex.EncodeToString([]byte(p)) }

// Add returns a copy of s with the representation of p prepended to it.
func (p Prefix) Add(s string) string { return string(p) + s }

// Remove returns a copy of s with the representation of p removed from it.
func (p Prefix) Remove(s string) string { return strings.TrimPrefix(s, string(p)) }

// Cut reports whether s begins with p, and if so returns p.Remove(s).
// If not, it returns s unmodified.
func (p Prefix) Cut(s string) (string, bool) { return strings.CutPrefix(s, string(p)) }

// derive computes a key prefix based on p and the name of the derived
// entity. The resulting prefix should be unique among all paths from the root.
//
// The prefix is constructed by hashing (SHA256) the base prefix with the name
// and taking off "enough" bytes from the hash to ensure uniqueness without
// too-much expanding the storage cost.  The separator distinguishes between
// prefixes for substores (".") and for key spaces (":").
//
//   - The initial root store prefix is "".
//   - To derive a prefix for a substore, compute SHA256(cur, ".", sub)
//   - To derive a prefix for a keyspace, compute SHA256(cur, ":", name)
//   - Truncate the hash to the first 6 bytes to form the prefix.
//
// Using different separators ensures a subspace cannot collide with a keyspace
// at the same level of indirection. These rules are iterated, so that the
// prefix for the keyspace "" → "sub1" → "sub2" → "ks" will be:
//
//	SHA256(SHA256(SHA256(".sub1")[:6]+".sub2")[:6]+":ks")[:6]
//
// or in this case, 47b256a71b00 (manually verified).
func (p Prefix) derive(sep, name string) Prefix {
	sum := sha256.Sum256([]byte(string(p) + sep + name))
	return Prefix(sum[:6])
}