v1 - Complete Library Redesignc - ( •͡˘ _•͡˘)ノð

[alessiosavi]

Summary

Complete redesign of GoGPUtils library from the ground up, applying modern Go best practices, generics (Go 1.18+), and production-ready patterns. This PR represents a breaking change from the legacy implementation with significant improvements in safety, testability, and API design.

Key Changes

• Rebuilt all utility packages with Go generics for type safety
• Redesigned AWS SDK v2 helpers with explicit client management
• Added comprehensive test coverage with LocalStack integration tests
• Replaced insecure cryptographic implementations with modern alternatives
• Introduced generic data structures (Stack, Queue, Set, BST)
• Added GitHub Actions CI/CD with integration testing

Test Plan

• Run unit tests: go test ./...
• Run with race detector: go test -race ./...
• Run integration tests: go test -tags=integration ./aws/...
• Run benchmarks: go test -bench=. ./...
• Verify linting passes: golangci-lint run

---

Design Principles

Principle	Description
Errors over panics	All functions return errors; no runtime panics
No global state	Explicit client/state management; no singletons
Context-aware	All I/O operations accept context.Context
Generic when useful	Generics reduce duplication without over-abstraction
Zero external deps	Core utilities have no external dependencies
Testable by design	Interface-based clients enable easy mocking

---

Package Changes

Renamed/Restructured Packages

Old Package	New Package	Changes
array/	sliceutil/	Generic slice operations (Filter, Map, Reduce, Chunk, etc.)
string/	stringutil/	String manipulation + similarity algorithms
math/	mathutil/	Generic math/stats operations
files/	fileutil/	Context-aware file operations
crypt/	cryptoutil/	AES-GCM encryption (replaces insecure AES-ECB)
datastructure/	collection/	Generic Stack, Queue, Set, BST
(new)	randutil/	Cryptographically secure random generation

AWS Package Redesign

Old Package	New Package	Changes
aws/S3/	aws/s3/	SDK v2, interface-based client, functional options
aws/dynamodb/	aws/dynamodb/	SDK v2, automatic marshaling, batch operations
aws/sqs/	aws/sqs/	SDK v2, batch send/receive/delete
aws/ssm/ssmutils.go	aws/ssm/	SDK v2, full parameter store support
aws/secrets/	aws/secretsmanager/	SDK v2, JSON unmarshaling, rotation support
aws/lambda/	aws/lambda/	SDK v2, sync/async invoke, deployment
(new)	aws/internal/testutil/	LocalStack test infrastructure

Removed Packages

The following packages were removed (low usage, outdated, or AWS SDK v1 only):

• aws/cloudwatch/, aws/codepipeline/, aws/ec2/, aws/ecr/
• aws/glue/, aws/iam/, aws/identity_store/, aws/rds/
• aws/redshift/, aws/ses/, aws/sfnutils/, aws/workspaces/
• csv/, http/, search/, sql/, tcp/, zip/, helper/, goutils/

---

New Features

1. Generic Slice Operations (sliceutil)

  // Filter, Map, Reduce with type safety
  evens := sliceutil.Filter(nums, func(n int) bool { return n%2 == 0 })
  doubled := sliceutil.Map(nums, func(n int) int { return n * 2 })
  sum := sliceutil.Reduce(nums, 0, func(acc, n int) int { return acc + n })

  // Set operations
  common := sliceutil.Intersection(a, b)
  unique := sliceutil.Unique(items)
  grouped := sliceutil.GroupBy(users, func(u User) string { return u.Role })

2. Generic Data Structures (collection)

  // Type-safe Stack
  stack := collection.NewStack[int]()
  stack.Push(42)
  val, ok := stack.Pop() // val is int, not interface{}

  // Set with operations
  set := collection.NewSetFrom([]string{"a", "b", "c"})
  union := set.Union(otherSet)
  intersection := set.Intersection(otherSet)

  // Binary Search Tree
  bst := collection.NewBST[int]()
  bst.Insert(5, 3, 7)
  sorted := bst.InOrder() // [3, 5, 7]

3. Secure Cryptography (cryptoutil)

  // AES-GCM authenticated encryption (replaces insecure AES-ECB)
  key, _ := cryptoutil.GenerateKey()
  ciphertext, _ := cryptoutil.Encrypt(plaintext, key)
  decrypted, _ := cryptoutil.Decrypt(ciphertext, key)

  // Password-based key derivation (Argon2)
  key, _ := cryptoutil.DeriveKey("password", salt)

4. AWS SDK v2 with LocalStack Testing

  // Explicit configuration - no global state
  cfg, _ := aws.LoadConfig(ctx, aws.WithRegion("us-west-2"))
  s3Client, _ := s3.NewClient(cfg)

  // Interface-based for easy mocking
  mock := &mockS3API{...}
  client := s3.NewClientWithAPI(mock, nil, nil)

  // Full integration test suite with LocalStack
  // docker-compose up -d
  // go test -tags=integration ./aws/...

5. String Similarity Algorithms (stringutil)

  distance := stringutil.LevenshteinDistance("kitten", "sitting") // 3
  score := stringutil.JaroWinklerSimilarity("martha", "marhta")   // ~0.96
  coefficient := stringutil.DiceSimilarity("night", "nacht")      // ~0.25

---

Breaking Changes

Error Handling

  // OLD: Panics on error
  client := awsutils.NewS3Client() // panics!

  // NEW: Returns error
  client, err := s3.NewClient(cfg)
  if err != nil {
      return fmt.Errorf("create S3 client: %w", err)
  }

Context Support

  // OLD: No context, no cancellation
  data := S3utils.GetObject("bucket", "key")

  // NEW: Context-aware with timeout support
  ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
  defer cancel()
  data, err := client.GetObject(ctx, "bucket", "key")

Generic Collections

  // OLD: Type assertions required
  stack := datastructure.NewStack()
  stack.Push(1.5)
  val := stack.Pop().(float64) // runtime panic if wrong type

  // NEW: Compile-time type safety
  stack := collection.NewStack[float64]()
  stack.Push(1.5)
  val, ok := stack.Pop() // val is float64, ok indicates success

Cryptography

  // OLD: Insecure AES-ECB mode
  crypt.EncryptAES(plaintext, key)

  // NEW: Secure AES-GCM authenticated encryption
  ciphertext, err := cryptoutil.Encrypt(plaintext, key)

---

CI/CD Improvements

GitHub Actions Workflow

• Unit Tests: Run on every push/PR with race detector
• Integration Tests: LocalStack service container for AWS testing
• Benchmarks: Run on master branch only
• Linting: golangci-lint with non-blocking errors
• Coverage: Uploaded to Codecov

LocalStack Integration

  services:
    localstack:
      image: localstack/localstack:latest
      ports:
        - "4566:4566"
      env:
        SERVICES: s3,dynamodb,sqs,ssm,secretsmanager,lambda

Note: This is marked as v1 - Experimental. APIs may change in future versions based on feedback and usage patterns.