{"id":25352284,"url":"https://github.com/andygeiss/cloud-native-utils","last_synced_at":"2026-01-17T14:55:41.044Z","repository":{"id":268886814,"uuid":"900436820","full_name":"andygeiss/cloud-native-utils","owner":"andygeiss","description":"A collection of high-performance, modular utilities for enhancing testing, transactional consistency, efficiency, security and stability in cloud-native Go applications.","archived":false,"fork":false,"pushed_at":"2026-01-16T19:22:19.000Z","size":5737,"stargazers_count":27,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-17T05:22:23.525Z","etag":null,"topics":["assert","automated-testing","batteries-included","best-practices","cloud-native","cloud-native-patterns","consistency","efficiency","extensibility","go","golang","logging","resource","security","service","stability","templating","utils"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andygeiss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security/assets/static/keepalive.txt","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-08T19:11:17.000Z","updated_at":"2026-01-16T19:22:23.000Z","dependencies_parsed_at":"2024-12-19T14:30:04.023Z","dependency_job_id":"5e22d75d-3676-4f86-9bf5-dc1d78066757","html_url":"https://github.com/andygeiss/cloud-native-utils","commit_stats":null,"previous_names":["andygeiss/cloud-native-utils"],"tags_count":158,"template":false,"template_full_name":null,"purl":"pkg:github/andygeiss/cloud-native-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andygeiss%2Fcloud-native-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andygeiss%2Fcloud-native-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andygeiss%2Fcloud-native-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andygeiss%2Fcloud-native-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andygeiss","download_url":"https://codeload.github.com/andygeiss/cloud-native-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andygeiss%2Fcloud-native-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28510925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assert","automated-testing","batteries-included","best-practices","cloud-native","cloud-native-patterns","consistency","efficiency","extensibility","go","golang","logging","resource","security","service","stability","templating","utils"],"created_at":"2025-02-14T18:38:36.884Z","updated_at":"2026-01-17T14:55:41.028Z","avatar_url":"https://github.com/andygeiss.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/andygeiss/cloud-native-utils/blob/main/logo.png?raw=true\" /\u003e\n\u003c/p\u003e\n\n# Cloud Native Utils\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/andygeiss/cloud-native-utils.svg)](https://pkg.go.dev/github.com/andygeiss/cloud-native-utils)\n[![License](https://img.shields.io/github/license/andygeiss/cloud-native-utils)](https://github.com/andygeiss/cloud-native-utils/blob/master/LICENSE)\n[![Releases](https://img.shields.io/github/v/release/andygeiss/cloud-native-utils)](https://github.com/andygeiss/cloud-native-utils/releases)\n[![Go Report Card](https://goreportcard.com/badge/github.com/andygeiss/cloud-native-utils)](https://goreportcard.com/report/github.com/andygeiss/cloud-native-utils)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/b4e3a9c4859b47f1bc43613970ec8d12)](https://app.codacy.com/gh/andygeiss/cloud-native-utils/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/b4e3a9c4859b47f1bc43613970ec8d12)](https://app.codacy.com/gh/andygeiss/cloud-native-utils/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_coverage)\n\nA modular Go library providing reusable utilities for building cloud-native applications.\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Project Structure](#project-structure)\n- [Running Tests](#running-tests)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Overview\n\nCloud Native Utils is a collection of small, focused Go packages designed to be imported independently. There is no monolithic framework—each package addresses a single concern and can be used standalone.\n\nThe library covers common cloud-native needs: resilience patterns, structured logging, message dispatching, generic CRUD persistence, security primitives, and HTTP middleware.\n\n---\n\n## Features\n\n| Package | Description |\n|---------|-------------|\n| **assert** | Minimal test assertion helper (`assert.That`) |\n| **consistency** | Transactional event log with JSON file persistence |\n| **efficiency** | Channel helpers (`Generate`, `Merge`, `Split`, `Process`) and gzip middleware |\n| **event** | Domain event interfaces (`Event`, `EventPublisher`, `EventSubscriber`) |\n| **extensibility** | Dynamic Go plugin loading |\n| **imaging** | QR code generation |\n| **logging** | Structured JSON logging via `log/slog` with HTTP middleware |\n| **messaging** | Publish-subscribe dispatcher (in-memory or Kafka-backed) |\n| **redirecting** | HTMX-compatible PRG redirects |\n| **resource** | Generic CRUD interface with multiple backends (memory/JSON/YAML/SQLite) |\n| **security** | AES-GCM encryption, password hashing, OIDC, HTTP server |\n| **service** | Context helpers, function wrapper, lifecycle management |\n| **slices** | Generic slice utilities (`Map`, `Filter`, `Unique`, etc.) |\n| **stability** | Resilience wrappers (circuit breaker, retry, throttle, debounce, timeout) |\n| **templating** | HTML template engine with `embed.FS` support |\n\n---\n\n## Installation\n\n```bash\ngo get github.com/andygeiss/cloud-native-utils\n```\n\n**Requirements:** Go 1.25.4 or later\n\n---\n\n## Usage\n\nImport only the packages you need:\n\n### Assert\n\n```go\nimport \"github.com/andygeiss/cloud-native-utils/assert\"\n\nfunc TestExample(t *testing.T) {\n    result := 42\n    assert.That(t, \"result should be 42\", result, 42)\n}\n```\n\n### Resource (Generic CRUD)\n\n```go\nimport \"github.com/andygeiss/cloud-native-utils/resource\"\n\n// In-memory storage\nstore := resource.NewInMemoryAccess[string, User]()\n\n// JSON file storage\nstore := resource.NewJsonFileAccess[string, User](\"users.json\")\n\n// CRUD operations\n_ = store.Create(ctx, \"user-1\", user)\nuserPtr, _ := store.Read(ctx, \"user-1\")\n_ = store.Update(ctx, \"user-1\", updatedUser)\n_ = store.Delete(ctx, \"user-1\")\n```\n\n### Stability (Resilience Patterns)\n\n```go\nimport \"github.com/andygeiss/cloud-native-utils/stability\"\n\n// Circuit breaker - opens after 3 failures\nfn := stability.Breaker(yourFunc, 3)\n\n// Retry with 5 attempts\nfn := stability.Retry(yourFunc, 5, time.Second)\n\n// Throttle concurrent executions\nfn := stability.Throttle(yourFunc, 10)\n\n// Timeout execution\nfn := stability.Timeout(yourFunc, 5*time.Second)\n```\n\n### Logging\n\n```go\nimport \"github.com/andygeiss/cloud-native-utils/logging\"\n\nlogger := logging.NewJsonLogger()\nhandler := logging.WithLogging(logger, yourHandler)\n```\n\n### Messaging\n\n```go\nimport \"github.com/andygeiss/cloud-native-utils/messaging\"\n\ndispatcher := messaging.NewInternalDispatcher()\n_ = dispatcher.Subscribe(ctx, \"user.created\", handlerFunc)\n_ = dispatcher.Publish(ctx, messaging.NewMessage(\"user.created\", payload))\n```\n\nFor Kafka-backed messaging, use `messaging.NewExternalDispatcher()` with `KAFKA_BROKERS` environment variable.\n\n### Event (Domain Events)\n\n```go\nimport \"github.com/andygeiss/cloud-native-utils/event\"\n\n// Define a domain event\ntype UserCreated struct {\n    UserID string\n}\n\nfunc (e UserCreated) Topic() string { return \"user.created\" }\n\n// Use with EventPublisher and EventSubscriber interfaces\nvar publisher event.EventPublisher = yourPublisher\n_ = publisher.Publish(ctx, UserCreated{UserID: \"123\"})\n\nvar subscriber event.EventSubscriber = yourSubscriber\nfactory := func() event.Event { return \u0026UserCreated{} }\nhandler := func(e event.Event) error { /* handle event */ return nil }\n_ = subscriber.Subscribe(ctx, \"user.created\", factory, handler)\n```\n\n### Security\n\n```go\nimport \"github.com/andygeiss/cloud-native-utils/security\"\n\n// AES-GCM encryption\nkey := security.GenerateKey()\nciphertext := security.Encrypt([]byte(\"secret\"), key)\nplaintext, _ := security.Decrypt(ciphertext, key)\n\n// Password hashing\nhash, _ := security.Password([]byte(\"p@ssw0rd\"))\nok := security.IsPasswordValid(hash, []byte(\"p@ssw0rd\"))\n\n// Configured HTTP server\nserver := security.NewServer(mux)\n```\n\n### Service (Context \u0026 Lifecycle)\n\n```go\nimport \"github.com/andygeiss/cloud-native-utils/service\"\n\nctx, cancel := service.Context()\ndefer cancel()\n\nservice.RegisterOnContextDone(ctx, func() {\n    // Cleanup logic\n})\n```\n\n---\n\n## Project Structure\n\n```\ncloud-native-utils/\n├── assert/          # Test assertions\n├── consistency/     # Event logging\n├── efficiency/      # Channel helpers, compression\n├── event/           # Domain event interfaces\n├── extensibility/   # Plugin loading\n├── imaging/         # QR code generation\n├── logging/         # Structured logging\n├── messaging/       # Pub-sub dispatchers\n├── redirecting/     # HTTP redirects\n├── resource/        # CRUD backends\n├── security/        # Encryption, auth, server\n├── service/         # Context, lifecycle\n├── slices/          # Slice utilities\n├── stability/       # Resilience patterns\n└── templating/      # Template engine\n```\n\nFor detailed architecture and conventions, see [CONTEXT.md](CONTEXT.md).\n\n---\n\n## Running Tests\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run tests with coverage\ngo test -cover ./...\n\n# Run tests verbose\ngo test -v ./...\n```\n\n---\n\n## Contributing\n\nContributions are welcome:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nPlease ensure your code:\n- Follows the conventions in [CONTEXT.md](CONTEXT.md)\n- Includes tests (`*_test.go` files)\n- Passes `go test ./...` and `go vet ./...`\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandygeiss%2Fcloud-native-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandygeiss%2Fcloud-native-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandygeiss%2Fcloud-native-utils/lists"}