go/valkey
1
0
Fork 0
Code Issues Pull Requests Packages Releases 1 Activity

1 Release 1 Tag

RSS Feed
  • v0.9.0 eda54153d6
    Compare

    Release 0.9.0 Stable

    Rene Nochebuena released this 2026-03-19 07:31:18 -06:00 | 0 commits to main since this release

    v0.9.0

    code.nochebuena.dev/go/valkey

    Overview

    valkey manages the lifecycle of a valkey-go
    client: constructs it from config, verifies connectivity at startup, exposes the native
    client to consumers, and closes it gracefully on shutdown. Health checks run via PING.

    This is the initial stable release. The API has been designed through multiple architecture
    reviews and validated end-to-end via the todo-api POC. It is versioned v0.9.0 rather than
    v1.0.0 because it has not yet been exercised across all production edge cases, and minor
    API refinements may follow.

    What's Included

    • Config — connection settings loaded from environment variables:
      • VK_ADDRS (required, comma-separated) — server addresses
      • VK_PASSWORD — authentication password
      • VK_DB — database index (default: 0)
      • VK_CLIENT_CACHE_MB — per-connection client-side cache size in MB (default: 0, disabled)
    • Provider interface — Client() valkey.Client for consumers that only need the native client
    • Component interface — embeds launcher.Component + health.Checkable + Provider for
      full lifecycle management
    • New(logger, cfg) Component — constructor; register with lc.Append(vk)
    • Health check — issues PING; priority is health.LevelDegraded (cache outage degrades
      service but should not halt it)
    • Graceful shutdown — OnStop calls client.Close()

    Installation

    go get code.nochebuena.dev/go/valkey@v0.9.0

    import "code.nochebuena.dev/go/valkey"

vk := valkey.New(logger, valkey.Config{
    Addrs: []string{"localhost:6379"},
})
lc.Append(vk)

    Design Highlights

    Native client exposed directly. Client() returns valkey.Client from the
    valkey-go library without any wrapping. Callers use the full command-builder API.
    There is no re-exported subset.

    No serialisation helpers. Marshal and unmarshal belong in the caller or in a
    separate cache repository layer. This module makes no assumptions about encoding.

    Optional client-side caching. Setting CacheSizeEachConn to a non-zero MB value
    enables valkey-go's built-in client-side cache per connection. Zero (the default)
    disables it entirely.

    Health priority is Degraded, not Critical. A Valkey outage should degrade service
    gracefully. Callers must handle cache misses by falling back to the primary datastore.

    Provider / Component split. Inject Provider into repositories and services that
    only read or write keys. Inject Component only at the lifecycle registration site.

    Known Limitations & Edge Cases

    • No serialisation helpers (SetJSON, GetJSON, etc.). Callers handle all encoding.
    • No key namespacing. Key collision prevention is the caller's responsibility.
    • Health check uses PING only — it does not verify that specific keys or data are
      accessible.
    • Client() returns nil before OnInit has run. Guard against this in any code path
      that may execute before the launcher has started the component.
    • Config.Addrs is required. An empty slice will result in a client construction error
      from the underlying library.

    v0.9.0 → v1.0.0 Roadmap

    • Validate production behaviour under connection churn and network partitions.
    • Consider adding an optional KeyPrefix to Config for namespace isolation.
    • Evaluate whether a higher-level Repository helper (with generic get/set + TTL) belongs
      here or in a separate module.
    • Harden health check with a configurable timeout distinct from the caller's context.
    Downloads