[feat] - Add Generic Hasher Interface with Blake2b Implementation

pkg/hasher/blake2b.go

@@ -0,0 +1,14 @@
+package hasher
+
+import "golang.org/x/crypto/blake2b"
+
+// Blaker2bHasher implements the Hasher interface using Blake2b algorithm.
+type Blaker2bHasher struct{ baseHasher }
+
+// NewBlaker2bHasher creates a new Blaker2bHasher.
+func NewBlaker2bHasher() *Blaker2bHasher {
+ h, _ := blake2b.New256(nil)
+ return &Blaker2bHasher{
+ baseHasher: baseHasher{hash: h},
+ }
+}

pkg/hasher/fnv.go

@@ -0,0 +1,13 @@
+package hasher
+
+import "hash/fnv"
+
+// FNVHasher implements the Hasher interface using FNV algorithm.
+type FNVHasher struct{ baseHasher }
+
+// NewFNVHasher creates a new FNVHasher.
+func NewFNVHasher() *FNVHasher {
+ return &FNVHasher{
+ baseHasher: baseHasher{hash: fnv.New64a()},
+ }
+}

pkg/hasher/hasher.go

@@ -0,0 +1,54 @@
+// Package hasher provides a generic interface and base implementation for hashing data.
+package hasher
+
+import (
+ "fmt"
+ "hash"
+)
+
+// Hasher defines a generic interface for hashing data.
+// Implementations of this interface may choose to be safe for concurrent use,
+// but it is not a requirement. Users should check the documentation of specific
+// implementations for concurrent safety guarantees.
+type Hasher interface {
+ // Hash takes input data and returns the hashed result.
+ // It returns an error if the input data is too large.
+ // The function is idempotent - calling it multiple times with the same input
+ // will produce the same output, assuming the underlying hash function is deterministic.
+ Hash(data []byte) ([]byte, error)
+}
+
+// baseHasher provides a base implementation for the Hasher interface.
+// It uses the hash.Hash interface from the standard library to perform the actual hashing.
+// This implementation is not safe for concurrent use. Each goroutine/worker should
+// use its own instance of baseHasher for concurrent operations.
+// Implementations that require concurrent access should wrap baseHasher with a mutex. (e.g., MutexHasher)
+type baseHasher struct{ hash hash.Hash }
+
+// InputTooLargeError is returned when the input data exceeds the maximum allowed size.
+type InputTooLargeError struct {
+ inputSize int
+ maxSize int
+}
+
+func (e *InputTooLargeError) Error() string {
+ return fmt.Sprintf("input data exceeds the maximum allowed size: %d > %d", e.inputSize, e.maxSize)
+}
+
+const maxInputSize = 1 << 14 // 16KB
+
+// Hash computes the hash of the given data.
+// It returns an ErrEmptyData if the input is empty or if writing to the hash fails.
+// This method resets the underlying hash before each computation to ensure
+// that previous hashing operations do not affect the result.
+func (b *baseHasher) Hash(data []byte) ([]byte, error) {
+ if len(data) > maxInputSize {
+ return nil, &InputTooLargeError{inputSize: len(data), maxSize: maxInputSize}
+ }
+ b.hash.Reset()
+ // nolint:errcheck
+ // The hash.Hash interface does not return errors on Write.
+ // (https://cs.opensource.google/go/go/+/refs/tags/go1.23.1:src/hash/hash.go;l=27-28)
+ _, _ = b.hash.Write(data)
+ return b.hash.Sum(nil), nil
+}

pkg/hasher/hasher_test.go

@@ -0,0 +1,249 @@
+package hasher
+
+import (
+ "bytes"
+ "encoding/hex"
+ "errors"
+ "fmt"
+ "sync"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+)
+
+func TestHasherHash(t *testing.T) {
+ testCases := []struct {
+ name string
+ hasher Hasher
+ input []byte
+ expectedHex string
+ expectError error
+ }{
+ {
+ name: "FNV-64a with 'Hello, World!'",
+ hasher: NewFNVHasher(),
+ input: []byte("Hello, World!"),
+ expectedHex: "6ef05bd7cc857c54",
+ },
+ {
+ name: "SHA-256 with 'Hello, World!'",
+ hasher: NewSHA256Hasher(),
+ input: []byte("Hello, World!"),
+ expectedHex: "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f",
+ },
+ {
+ name: "SHA-256 input at max size",
+ hasher: NewSHA256Hasher(),
+ input: bytes.Repeat([]byte("a"), maxInputSize),
+ expectedHex: "f3336bea752b5a28743033dd2c844a4a63fba08871aaee2586a2bf2d69be83a2",
+ },
+ {
+ name: "FN-64a input exceeds max size",
+ hasher: NewFNVHasher(),
+ input: bytes.Repeat([]byte("a"), maxInputSize+1),
+ expectError: &InputTooLargeError{},
+ },
+ }
+
+ for _, tc := range testCases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ got, err := tc.hasher.Hash(tc.input)
+ checkError(t, err, tc.expectError, len(tc.input))
+
+ if tc.expectError != nil {
+ return
+ }
+
+ expected, err := hex.DecodeString(tc.expectedHex)
+ if err != nil {
+ t.Fatalf("invalid expected hex string '%s': %v", tc.expectedHex, err)
+ }
+
+ if !bytes.Equal(got, expected) {
+ t.Errorf("hash mismatch.\nGot: %x\nExpected: %x", got, expected)
+ }
+ })
+ }
+}
+
+func checkError(t *testing.T, err, expectError error, inputSize int) {
+ t.Helper()
+
+ if expectError != nil {
+ var inputTooLargeError *InputTooLargeError
+ if errors.As(expectError, &inputTooLargeError) {
+ var inputTooLargeErr *InputTooLargeError
+ if assert.ErrorAs(t, err, &inputTooLargeErr) {
+ assert.Equal(t, inputSize, inputTooLargeErr.inputSize)
+ assert.Equal(t, maxInputSize, inputTooLargeErr.maxSize)
+ }
+ }
+ } else {
+ assert.NoError(t, err)
+ }
+}
+
+func TestBaseHasherHashIdempotency(t *testing.T) {
+ t.Parallel()
+
+ hasher := NewFNVHasher()
+ input := bytes.Repeat([]byte("a"), maxInputSize)
+
+ hash1, err1 := hasher.Hash(input)
+ assert.NoError(t, err1, "unexpected error on first hash")
+
+ hash2, err2 := hasher.Hash(input)
+ assert.NoError(t, err2, "unexpected error on second hash")
+
+ if !bytes.Equal(hash1, hash2) {
+ t.Errorf("hash results are not identical.\nFirst: %x\nSecond: %x", hash1, hash2)
+ }
+}
+
+const (
+ numGoroutines = 512
+ numIterations = 10_000
+)
+
+// TestMutexHasherConcurrentHash verifies that MutexHasher is thread-safe
+// and produces consistent hash results when used concurrently.
+func TestMutexHasherConcurrentHash(t *testing.T) {
+ t.Parallel()
+
+ mutexHasher := NewMutexHasher(NewSHA256Hasher())
+
+ input := []byte("Concurrent Hashing Test")
+
+ // Compute the expected hash once for comparison.
+ expectedHash, err := mutexHasher.Hash(input)
+ assert.NoError(t, err, "unexpected error computing expected hash")
+
+ // Channel to collect errors from goroutines.
+ // Buffered to prevent goroutines from blocking if the main thread is slow.
+ errs := make(chan error, numGoroutines*numIterations)
+
+ var wg sync.WaitGroup
+ wg.Add(numGoroutines)
+
+ // Launch multiple goroutines to perform hashing concurrently.
+ for i := range numGoroutines {
+ go func(goroutineID int) {
+ defer wg.Done()
+ for j := range numIterations {
+ hash, err := mutexHasher.Hash(input)
+ if err != nil {
+ errs <- fmt.Errorf("goroutine %d: hash error: %v", goroutineID, err)
+ continue
+ }
+ if !bytes.Equal(hash, expectedHash) {
+ errs <- fmt.Errorf("goroutine %d: hash mismatch on iteration %d", goroutineID, j)
+ }
+ }
+ }(i)
+ }
+
+ wg.Wait()
+ close(errs)
+
+ for err := range errs {
+ t.Error(err)
+ }
+}
+
+var sampleData = []byte("The quick brown fox jumps over the lazy dog")
+
+// BenchmarkHasherWithMutex_SHA256 benchmarks hashing using a single SHA-256 Hasher instance
+// protected by a sync.Mutex across multiple goroutines.
+func BenchmarkHasherWithMutex_SHA256(b *testing.B) {
+ mutexHasher := NewMutexHasher(NewSHA256Hasher())
+
+ b.ReportAllocs()
+ b.ResetTimer()
+
+ b.RunParallel(func(pb *testing.PB) {
+ for pb.Next() {
+ _, err := mutexHasher.Hash(sampleData)
+ assert.NoError(b, err)
+ }
+ })
+}
+
+// BenchmarkHasherPerGoroutine_SHA256 benchmarks hashing using separate SHA-256 Hasher instances
+// for each goroutine, eliminating the need for synchronization.
+func BenchmarkHasherPerGoroutine_SHA256(b *testing.B) {
+ b.ReportAllocs()
+ b.ResetTimer()
+
+ b.RunParallel(func(pb *testing.PB) {
+ // Each goroutine maintains its own Hasher instance.
+ hasher := NewSHA256Hasher()
+ for pb.Next() {
+ _, err := hasher.Hash(sampleData)
+ assert.NoError(b, err)
+ }
+ })
+}
+
+// BenchmarkHasherWithMutex_FNV benchmarks hashing using a single FNV-64a Hasher instance
+// protected by a sync.Mutex across multiple goroutines.
+func BenchmarkHasherWithMutex_FNV(b *testing.B) {
+ mutexHasher := NewMutexHasher(NewFNVHasher())
+
+ b.ReportAllocs()
+ b.ResetTimer()
+
+ b.RunParallel(func(pb *testing.PB) {
+ for pb.Next() {
+ _, err := mutexHasher.Hash(sampleData)
+ assert.NoError(b, err)
+ }
+ })
+}
+
+// BenchmarkHasherPerGoroutine_FNV benchmarks hashing using separate FNV-64a Hasher instances
+// for each goroutine, eliminating the need for synchronization.
+func BenchmarkHasherPerGoroutine_FNV(b *testing.B) {
+ b.ReportAllocs()
+ b.ResetTimer()
+
+ b.RunParallel(func(pb *testing.PB) {
+ hasher := NewFNVHasher()
+ for pb.Next() {
+ _, err := hasher.Hash(sampleData)
+ assert.NoError(b, err)
+ }
+ })
+}
+
+// BenchmarkHasherWithMutex_Blake2b benchmarks hashing using a single Blake2b Hasher instance
+// protected by a sync.Mutex across multiple goroutines.
+func BenchmarkHasherWithMutex_Blake2b(b *testing.B) {
+ mutexHasher := NewMutexHasher(NewBlaker2bHasher())
+
+ b.ReportAllocs()
+ b.ResetTimer()
+
+ b.RunParallel(func(pb *testing.PB) {
+ for pb.Next() {
+ _, err := mutexHasher.Hash(sampleData)
+ assert.NoError(b, err)
+ }
+ })
+}
+
+// BenchmarkHasherPerGoroutine_Blake2b benchmarks hashing using separate Blake2b Hasher instances
+// for each goroutine, eliminating the need for synchronization.
+func BenchmarkHasherPerGoroutine_Blake2b(b *testing.B) {
+ b.ReportAllocs()
+ b.ResetTimer()
+
+ b.RunParallel(func(pb *testing.PB) {
+ hasher := NewBlaker2bHasher()
+ for pb.Next() {
+ _, err := hasher.Hash(sampleData)
+ assert.NoError(b, err)
+ }
+ })
+}

pkg/hasher/mutex.go

@@ -0,0 +1,24 @@
+package hasher
+
+import (
+ "sync"
+)
+
+// MutexHasher wraps a Hasher with a sync.Mutex to ensure thread-safe access.
+// This implementation is safe for concurrent use.
+type MutexHasher struct {
+ hasher Hasher
+ mu sync.Mutex
+}
+
+// NewMutexHasher creates a new MutexHasher wrapping the provided Hasher.
+func NewMutexHasher(hasher Hasher) *MutexHasher {
+ return &MutexHasher{hasher: hasher}
+}
+
+// Hash synchronizes access to the underlying Hasher using a mutex.
+func (m *MutexHasher) Hash(data []byte) ([]byte, error) {
+ m.mu.Lock()
+ defer m.mu.Unlock()
+ return m.hasher.Hash(data)
+}

pkg/hasher/sha256.go

@@ -0,0 +1,13 @@
+package hasher
+
+import "crypto/sha256"
+
+// SHA256Hasher implements the Hasher interface using SHA-256 algorithm.
+type SHA256Hasher struct{ baseHasher }
+
+// NewSHA256Hasher creates a new SHA256Hasher.
+func NewSHA256Hasher() *SHA256Hasher {
+ return &SHA256Hasher{
+ baseHasher: baseHasher{hash: sha256.New()},
+ }
+}