{"id":31952345,"url":"https://github.com/agilira/balios","last_synced_at":"2026-04-21T03:31:36.084Z","repository":{"id":318735431,"uuid":"1074424758","full_name":"agilira/balios","owner":"agilira","description":"Balios is a high-performance in-memory cache for Go based on W-TinyLFU, designed for maximum throughput, optimal hit ratio, advanced security \u0026 observability.","archived":false,"fork":false,"pushed_at":"2025-10-26T22:07:15.000Z","size":390,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-26T22:10:46.219Z","etag":null,"topics":["agilira","agilira-argus","cache","context","fuzz-testing","go","hot-reload","lock-free","logger-interface","open-telemetry","otel","performance","red-team","ttl","type-safe-api","w-tinylfu"],"latest_commit_sha":null,"homepage":"https://github.com/agilira/balios","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agilira.png","metadata":{"files":{"readme":"README.md","changelog":"changelog/v1.0.0.txt","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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":"2025-10-11T19:02:53.000Z","updated_at":"2025-10-26T22:06:21.000Z","dependencies_parsed_at":"2025-10-26T22:08:03.584Z","dependency_job_id":null,"html_url":"https://github.com/agilira/balios","commit_stats":null,"previous_names":["agilira/balios"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/agilira/balios","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fbalios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fbalios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fbalios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fbalios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agilira","download_url":"https://codeload.github.com/agilira/balios/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fbalios/sbom","scorecard":{"id":1239240,"data":{"date":"2025-10-13T13:29:17Z","repo":{"name":"github.com/agilira/balios","commit":"bad6b65c5dd163b26340302eb63de4031e342514"},"scorecard":{"version":"v5.0.0-rc2","commit":"7ce8609469289d5f3b1bf5ee3122f42b4e3054fb"},"score":5.2,"checks":[{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#binary-artifacts"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#branch-protection"}},{"name":"CI-Tests","score":-1,"reason":"no pull request found","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#ci-tests"}},{"name":"CII-Best-Practices","score":5,"reason":"badge detected: Passing","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#cii-best-practices"}},{"name":"Code-Review","score":0,"reason":"Found 0/15 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#code-review"}},{"name":"Contributors","score":0,"reason":"project has 0 contributing companies or organizations -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#contributors"}},{"name":"Dangerous-Workflow","score":0,"reason":"dangerous workflow patterns detected","details":["Warn: script injection with untrusted input ' github.event.pull_request.title ': .github/workflows/dependabot-auto-merge.yml:43"],"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#dangerous-workflow"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: .github/dependabot.yml:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#dependency-update-tool"}},{"name":"Fuzzing","score":10,"reason":"project is fuzzed","details":["Info: GoBuiltInFuzzer integration found: balios_fuzz_test.go:682","Info: GoBuiltInFuzzer integration found: balios_fuzz_test.go:682","Info: GoBuiltInFuzzer integration found: balios_fuzz_test.go:682","Info: GoBuiltInFuzzer integration found: balios_fuzz_test.go:682","Info: GoBuiltInFuzzer integration found: balios_fuzz_test.go:682","Info: GoBuiltInFuzzer integration found: balios_fuzz_test.go:682","Info: GoBuiltInFuzzer integration found: balios_fuzz_test.go:682"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.md:0","Info: FSF or OSI recognized license: Mozilla Public License 2.0: LICENSE.md:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#license"}},{"name":"Maintained","score":0,"reason":"project was created in last 90 days. please review its contents carefully","details":["Warn: Repository was created in last 90 days."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#packaging"}},{"name":"Pinned-Dependencies","score":4,"reason":"dependency not pinned by hash detected -- score normalized to 4","details":["Warn: containerImage not pinned by hash: examples/otel-prometheus/Dockerfile:2","Warn: containerImage not pinned by hash: examples/otel-prometheus/Dockerfile:19: pin your Docker image by updating alpine:3.19 to alpine:3.19@sha256:6baf43584bcb78f2e5847d1de515f23499913ac9f12bdf834811a3145eb11ca1","Warn: goCommand not pinned by hash: .github/workflows/ci.yml:31","Warn: goCommand not pinned by hash: .github/workflows/ci.yml:32","Warn: goCommand not pinned by hash: .github/workflows/codeql.yml:43","Warn: goCommand not pinned by hash: .github/workflows/pr.yml:40","Info:  18 out of  18 GitHub-owned GitHubAction dependencies pinned","Info:   2 out of   2 third-party GitHubAction dependencies pinned","Info:   0 out of   2 containerImage dependencies pinned","Info:   0 out of   4 goCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#pinned-dependencies"}},{"name":"SAST","score":10,"reason":"SAST tool detected: CodeQL","details":["Info: SAST configuration detected: CodeQL","Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#sast"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#security-policy"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#signed-releases"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql.yml:18","Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql.yml:17","Info: topLevel 'contents' permission set to 'read': .github/workflows/ci.yml:10","Warn: no topLevel permission defined: .github/workflows/codeql.yml:1","Warn: topLevel 'contents' permission set to 'write': .github/workflows/dependabot-auto-merge.yml:8","Info: topLevel 'contents' permission set to 'read': .github/workflows/pr.yml:8","Warn: topLevel 'contents' permission set to 'write': .github/workflows/release.yml:9","Warn: topLevel 'packages' permission set to 'write': .github/workflows/release.yml:10","Info: topLevel permissions set to 'read-all': .github/workflows/scorecard.yml:15","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#token-permissions"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/7ce8609469289d5f3b1bf5ee3122f42b4e3054fb/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-10-26T22:11:31.728Z","repository_id":318735431,"created_at":"2025-10-26T22:11:31.728Z","updated_at":"2025-10-26T22:11:31.728Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32075222,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T02:38:07.213Z","status":"ssl_error","status_checked_at":"2026-04-21T02:38:06.559Z","response_time":128,"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":["agilira","agilira-argus","cache","context","fuzz-testing","go","hot-reload","lock-free","logger-interface","open-telemetry","otel","performance","red-team","ttl","type-safe-api","w-tinylfu"],"created_at":"2025-10-14T13:13:31.351Z","updated_at":"2026-04-21T03:31:36.079Z","avatar_url":"https://github.com/agilira.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Balios: High-Performance Caching Library for Go\n\n![Balios Banner](assets/banner.png)\n\nBalios is a high-performance in-memory caching library for Go, based on W-TinyLFU, engineered for maximum throughput, optimal hit ratio, professional security \u0026 advanced observability—without sacrificing developer experience.\n\n[![CI/CD Pipeline](https://github.com/agilira/balios/actions/workflows/ci.yml/badge.svg)](https://github.com/agilira/balios/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/agilira/balios/actions/workflows/codeql.yml/badge.svg)](https://github.com/agilira/balios/actions/workflows/codeql.yml)\n[![Security](https://img.shields.io/badge/security-gosec-brightgreen.svg)](https://github.com/agilira/balios/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/agilira/balios)](https://goreportcard.com/report/github.com/agilira/balios)\n[![Test Coverage](https://img.shields.io/badge/coverage-94.0%25-brightgreen)](https://github.com/agilira/balios)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/11297/badge)](https://www.bestpractices.dev/projects/11297)\n\n**[Features](#features) • [Quick Start](#quick-start) • [Performance](#performance) • [Observability Architecture](#observability-architecture) • [Philosophy](#the-philosophy-behind-balios) • [Documentation](#documentation)**\n\n## Features\n\n- **Type-Safe Generics API**: `GenericCache[K comparable, V any]` with compile-time type safety\n- **Automatic Loading**: `GetOrLoad()` API with singleflight pattern for cache stampede prevention\n- **W-TinyLFU Algorithm**: Combines frequency and recency for optimal eviction decisions\n- **Lock-Free**: Uses atomic primitives for high concurrency\n- **TTL Support**: Hybrid expiration strategy with inline opportunistic cleanup + manual `ExpireNow()` API (v1.1.32+)\n- **Context Support**: Timeout and cancellation for loader functions\n- **Negative Caching**: Cache loader errors to prevent repeated failed operations (v1.1.2+)\n- **Structured Errors**: Rich error context with [go-errors](https://github.com/agilira/go-errors) - see [examples/errors/](examples/errors/)\n- **Observability**: OpenTelemetry integration for metrics (p50/p95/p99 latencies, hit ratio) \u0026 logger interface. Zero overhead when disabled (compiler eliminates no-op implementations) - see [examples/otel-prometheus/](examples/otel-prometheus/)\n- **Secure by Design**: [Red-team tested](balios_security_test.go) and [fuzz tested](balios_fuzz_test.go) against a wide range of attacks\n\n## Compatibility and Support\n\nBalios is designed for Go 1.24+ environments and follows Long-Term Support guidelines to ensure consistent performance across production deployments.\n\n## Installation\n\n```bash\ngo get github.com/agilira/balios\n```\n\n## Quick Start\n\n### Type-Safe Generic API\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"time\"\n    \n    \"github.com/agilira/balios\"\n)\n\ntype User struct {\n    ID   int\n    Name string\n    Role string\n}\n\nfunc main() {\n    // Create type-safe cache\n    cache := balios.NewGenericCache[string, User](balios.Config{\n        MaxSize: 10_000,\n        TTL:     time.Hour,\n    })\n    \n    // Set a value\n    cache.Set(\"user:123\", User{\n        ID:   123,\n        Name: \"John Doe\",\n        Role: \"admin\",\n    })\n    \n    // Get a value (no type assertion needed)\n    if user, found := cache.Get(\"user:123\"); found {\n        fmt.Printf(\"User: %s (%s)\\n\", user.Name, user.Role)\n    }\n    \n    // Check stats\n    stats := cache.Stats()\n    fmt.Printf(\"Hit ratio: %.2f%%\\n\", stats.HitRatio()*100)\n}\n```\n## Performance\n\n**Single-Threaded Performance:**\n\n| Package | Set (ns/op) | Set % vs Balios | Get (ns/op) | Get % vs Balios | Allocations |\n| :------ | ----------: | --------------: | ----------: | --------------: | ----------: |\n| **Balios** | **194.4 ns/op** | **+0%** | **110.8 ns/op** | **+0%** | **2/0 allocs/op** |\n| Balios-Generic | 198.2 ns/op | +2% | 115.0 ns/op | +4% | 2/0 allocs/op |\n| Otter | 365.3 ns/op | +88% | 121.2 ns/op | +9% | 1/0 allocs/op |\n| Ristretto | 280.0 ns/op | +44% | 156.7 ns/op | +41% | 2/0 allocs/op |\n\n**Parallel Performance (8 cores):**\n\n| Package | Set (ns/op) | Set % vs Balios | Get (ns/op) | Get % vs Balios | Allocations |\n| :------ | ----------: | --------------: | ----------: | --------------: | ----------: |\n| **Balios** | **59.26 ns/op** | **+0%** | **25.50 ns/op** | **+0%** | **2/0 allocs/op** |\n| Balios-Generic | 60.84 ns/op | +3% | 27.33 ns/op | +7% | 2/0 allocs/op |\n| Otter | 240.1 ns/op | +305% | 25.78 ns/op | +1% | 1/0 allocs/op |\n| Ristretto | 115.1 ns/op | +94% | 30.04 ns/op | +18% | 1/0 allocs/op |\n\n**Mixed Workloads (Realistic Scenarios):**\n\n| Workload | Balios | Balios-Generic | Otter | Ristretto | Best |\n| :------- | -----: | -------------: | ----: | --------: | :--- |\n| Write-Heavy (10% R / 90% W) | **85.82 ns/op** | 100.7 ns/op | 210.3 ns/op | 125.4 ns/op | **Balios** |\n| Balanced (50% R / 50% W) | **50.01 ns/op** | 52.81 ns/op | 132.5 ns/op | 113.2 ns/op | **Balios** |\n| Read-Heavy (90% R / 10% W) | **35.08 ns/op** | 36.84 ns/op | 47.64 ns/op | 70.81 ns/op | **Balios** |\n| Read-Only (100% R) | **36.59 ns/op** | 55.91 ns/op | 46.95 ns/op | 31.63 ns/op | **Ristretto** |\n\n**Hit Ratio (100K requests, Zipf distribution):**\n\n| Cache | Hit Ratio | Notes |\n| :---- | --------: | :---- |\n| **Balios** | 79.86% | Excellent |\n| Balios-Generic | 79.71% | Excellent |\n| **Otter** | 79.53% | Excellent |\n| Ristretto | 71.19% | Good |\n\n**Test Environment:** AMD Ryzen 5 7520U, Go 1.25+\n\nRun the benchmarks on your hardware [benchmarks/](benchmarks/) to evaluate performance on your specific workload and configuration. \nSee [docs/PERFORMANCE.md](docs/PERFORMANCE.md) for detailed analysis and methodology.\n\n### Advanced Configuration\n\n**Negative Caching** (v1.1.2+): Cache loader errors to prevent repeated failed operations\n\n```go\ncache := balios.NewGenericCache[int, User](balios.Config{\n    MaxSize:          10_000,\n    TTL:              5 * time.Minute,\n    NegativeCacheTTL: 30 * time.Second, // Cache errors for 30s\n})\n\n// First call: loader fails\n_, err := cache.GetOrLoad(123, func() (User, error) {\n    return User{}, fmt.Errorf(\"database unavailable\")\n})\n// Error returned\n\n// Subsequent calls within 30s: cached error returned WITHOUT calling loader\n_, err = cache.GetOrLoad(123, func() (User, error) {\n    panic(\"This won't be called - error is cached!\")\n})\n// Same error returned (no loader execution)\n```\n\n**Use cases**: Circuit breaker pattern, API rate limiting, external service failures.  \n**See**: [GetOrLoad documentation](docs/GETORLOAD.md#negative-caching-v112) for complete guide.\n\n### Automatic Loading with GetOrLoad\n\nPrevent cache stampede with singleflight pattern:\n\n```go\n// Multiple concurrent requests for same key = single loader execution\nuser, err := cache.GetOrLoad(\"user:123\", func() (User, error) {\n    // This expensive operation runs only once\n    return fetchUserFromDB(123)\n})\nif err != nil {\n    log.Printf(\"Failed to load user: %v\", err)\n    return\n}\n```\n\nWith context support for timeout/cancellation:\n\n```go\nctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\ndefer cancel()\n\nuser, err := cache.GetOrLoadWithContext(ctx, \"user:123\", \n    func(ctx context.Context) (User, error) {\n        return fetchUserFromDBWithContext(ctx, 123)\n    })\n```\n\n**Key characteristics:**\n- Cache hit: Same performance as `Get()` operations (27.90 ns/op parallel, 0 allocations)\n- Concurrent requests: 1000 simultaneous requests = 1 loader call (singleflight)\n- Error handling: Loader errors can be cached with `NegativeCacheTTL` option\n- Panic recovery: Returns `BALIOS_PANIC_RECOVERED` error if loader panics\n\nSee [examples/getorload/](examples/getorload/) for comprehensive examples.\n\n## Observability Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Core Cache Module\"\n        CACHE[Balios Cache\u003cbr/\u003eGet/Set/Delete Operations]\n        IFACE[MetricsCollector Interface\u003cbr/\u003eThread-Safe API]\n        NOOP[NoOpMetricsCollector\u003cbr/\u003eZero Overhead Default\u003cbr/\u003eCompiler Inlined]\n    end\n\n    subgraph \"Implementation Layer\"\n        OTEL[OpenTelemetry Collector\u003cbr/\u003eotel package\u003cbr/\u003eProfessional Metrics]\n        CUSTOM[Custom Collector\u003cbr/\u003eUser Implementation\u003cbr/\u003eDomain-Specific]\n    end\n\n    subgraph \"Observability Backends\"\n        PROM[Prometheus\u003cbr/\u003eMetrics Storage\u003cbr/\u003eTime-Series DB]\n        JAEGER[Jaeger\u003cbr/\u003eDistributed Tracing\u003cbr/\u003ePerformance Analysis]\n        GRAFANA[Grafana\u003cbr/\u003eVisualization\u003cbr/\u003eDashboards]\n    end\n\n    subgraph \"Custom Integrations\"\n        DD[DataDog\u003cbr/\u003eAPM Platform]\n        CUSTOM_BACK[Custom Backend\u003cbr/\u003eInternal Tools\u003cbr/\u003eDomain-Specific]\n    end\n\n    %% Connections\n    CACHE --\u003e IFACE\n    IFACE --\u003e NOOP\n    IFACE --\u003e OTEL\n    IFACE --\u003e CUSTOM\n\n    OTEL --\u003e PROM\n    OTEL --\u003e JAEGER\n    PROM --\u003e GRAFANA\n\n    CUSTOM --\u003e DD\n    CUSTOM --\u003e CUSTOM_BACK\n\n    %% Styling with Argus color scheme\n    classDef core fill:#ecfdf5,stroke:#059669,stroke-width:2px\n    classDef implementation fill:#f0f9ff,stroke:#0369a1,stroke-width:2px\n    classDef observability fill:#fef3c7,stroke:#d97706,stroke-width:2px\n    classDef custom fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px\n\n    class CACHE,IFACE,NOOP core\n    class OTEL,CUSTOM implementation\n    class PROM,JAEGER,GRAFANA observability\n    class DD,CUSTOM_BACK custom\n```\n\n### Logger Interface\n\n```go\n// Logger defines a minimal logging interface with zero overhead.\n// Implementations should use structured logging and be allocation-free.\ntype Logger interface {\n    // Debug logs a debug message with optional key-value pairs.\n    Debug(msg string, keyvals ...interface{})\n\n    // Info logs an info message with optional key-value pairs.\n    Info(msg string, keyvals ...interface{})\n\n    // Warn logs a warning message with optional key-value pairs.\n    Warn(msg string, keyvals ...interface{})\n\n    // Error logs an error message with optional key-value pairs.\n    Error(msg string, keyvals ...interface{})\n}\n```\n\n**Integration example:**\n```go\nimport \"log/slog\"\n\n// Using standard library slog\nlogger := slog.New(slog.NewJSONHandler(os.Stdout, nil))\n\ncache := balios.New[string, User](balios.Config{\n    Size: 1000,\n    Logger: logger,\n})\n```\n\nsee [Metrics \u0026 Observability](docs/METRICS.md) for full documentation.\n\n## The Philosophy Behind Balios\n\nBalios and his brother Xanthos were the immortal horses of Achilles, born from Zephyros, the swiftest of the Anemoi. They were not merely fast—they were the children of the wind itself, incomparable to mortal steeds. Balios possessed intelligence beyond any horse, an instinct that guided Achilles through every battle with perfect judgment.\n\nWhen Patroclus fell, it was Xanthos who spoke—granted voice by Hera herself—to warn Achilles of his fate. But Balios remained silent, his wisdom expressed not in words but in action, in knowing when to charge and when to wheel away, in the perfect synchrony between horse and hero that transcends command.\n\n## Documentation\n\n- [Architecture](docs/ARCHITECTURE.md) - W-TinyLFU internals, lock-free design, memory layout\n- [Performance](docs/PERFORMANCE.md) - Comprehensive benchmarks, hit ratio analysis, scalability\n- [GetOrLoad API](docs/GETORLOAD.md) - Cache stampede prevention, singleflight pattern, best practices\n- [Metrics \u0026 Observability](docs/METRICS.md) - OpenTelemetry integration, Prometheus queries, monitoring best practices\n- [Error Handling](docs/ERRORS.md) - Structured error codes and contexts\nfindings, and production safety guarantees\n- [Examples](examples/) - Comprehensive usage examples\n- [Benchmarks](benchmarks/) - Performance comparison with popular libraries\n- [otel/README.md](otel/README.md) and [examples/otel-prometheus/](examples/otel-prometheus/) for complete setup with Grafana dashboard.\n\n## Future Enhancements (PLANNED)\n- Async refresh (stale-while-revalidate pattern)\n- Persistence (save/load from disk)\n- Distributed cache coordination\n- Write-through/write-behind patterns\n\n## License\n\nBalios is licensed under the [Mozilla Public License 2.0](./LICENSE.md).\n\n---\n\nBalios • an AGILira fragment\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagilira%2Fbalios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagilira%2Fbalios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagilira%2Fbalios/lists"}