feat: valkey #1179

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

kzndotsh merged 95 commits into main from 1164-valkey

Jan 29, 2026

.env.example

-Original file line number
+Diff line change
@@ -1,4 +1,4 @@
-    # Postgres, ExternalServices, BOT_TOKEN, DATABASE_URL, DEBUG, LOG_LEVEL, MAINTENANCE_MODE.
+    # Postgres, Valkey, ExternalServices, BOT_TOKEN, DATABASE_URL, DEBUG, LOG_LEVEL, MAINTENANCE_MODE.
     # Used by Tux and Docker Compose. Other settings → config/config.json (config.json.example).
     DEBUG=false
@@ Expand All / @@ -11,6 +11,11 @@ POSTGRES_DB=tuxdb @@
     POSTGRES_USER=tuxuser
     POSTGRES_PASSWORD=YOUR_POSTGRES_PASSWORD_HERE
     DATABASE_URL=
+    VALKEY_HOST=
+    VALKEY_PORT=6379
+    VALKEY_DB=0
+    VALKEY_PASSWORD=YOUR_VALKEY_PASSWORD_HERE
+    VALKEY_URL=
     EXTERNAL_SERVICES__SENTRY_DSN=
     EXTERNAL_SERVICES__SENTRY_ENVIRONMENT=
     EXTERNAL_SERVICES__GITHUB_APP_ID=
@@ Expand Down @@

AGENTS.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -6,7 +6,7 @@ @@
     **Core:** Python 3.13.2+ • discord.py • PostgreSQL 17+ • SQLModel • Docker
     **Tools:** uv • ruff • basedpyright • pytest • loguru • sentry-sdk • httpx • Zensical
-    **Additional:** typer (CLI) • Alembic (migrations) • psycopg (async PostgreSQL) • pydantic-settings
+    **Additional:** typer (CLI) • Alembic (migrations) • psycopg (async PostgreSQL) • pydantic-settings • Valkey (optional cache)
     ## Cursor Rules & Commands
@@ Expand Down Expand Up / @@ -66,6 +66,7 @@ uv run tux start --debug @@
     ```text
     tux/
     ├── src/tux/                    # Main source code
+    │   ├── cache/                  # Cache layer (Valkey/in-memory backend, CacheService)
     │   ├── core/                   # Bot core (bot.py, app.py, base_cog.py)
     │   ├── database/               # Database layer
     │   │   ├── models/             # SQLModel models
@@ Expand Down Expand Up / @@ -290,7 +291,16 @@ docker compose up -d tux-postgres @@
     - `production` - Production mode with pre-built image and security hardening
     - `adminer` - Optional database management UI (combine with dev or production)
-    **Note:** `tux-postgres` has no profile and always starts. Do not use `--profile dev` and `--profile production` together.
+    **Note:** `tux-postgres` has no profile and always starts. Use `--profile valkey` to start Valkey (optional cache). Do not use `--profile dev` and `--profile production` together.
+    **Optional: Valkey (cache):** For shared cache across processes or restarts, start Valkey and set env:
+    ```bash
+    docker compose --profile valkey up -d tux-valkey
+    # In .env: VALKEY_URL=valkey://localhost:6379/0  (or leave unset to use in-memory cache)
+    ```
+    When `VALKEY_URL` is set and reachable, guild config, jail status, prefix, and permission caches use Valkey; otherwise they use in-memory TTL caches.
     ## Conventional Commits
@@ Expand Down Expand Up / @@ -376,7 +386,7 @@ refactor(database): optimize query performance @@
     - **Async for I/O** - All database and HTTP operations are async
     - **Connection pooling** - psycopg connection pooling for PostgreSQL
-    - **TTL caching** - Thread-safe TTL cache system for frequently accessed data (guild config, jail status, permissions)
+    - **TTL caching** - Thread-safe TTL cache system for frequently accessed data (guild config, jail status, permissions). Optional Valkey backend for shared cache across restarts (set `VALKEY_URL` and run `tux-valkey` in compose).
     - **Batch operations** - Batch retrieval for permission checks and database queries
     - **Cache pre-warming** - Automatic cache pre-warming on bot startup
     - **Optimize queries** - Use database controllers with proper indexing
@@ Expand Down @@

CHANGELOG.md

-Original file line number
+Diff line change
@@ Expand Up @@
     ### Added
-    * **Cache system**: TTLCache for thread-safe caching with automatic expiration; GuildConfigCacheManager for managing guild configuration data
     * **Database**: Performance indexes for cases table (composite indexes for case lookups and expired tempbans); `fix-sequences` command to synchronize PostgreSQL sequences; safety checks for database reset and nuke operations in test mode
     * **Bot configuration**: BotIntents model for Discord bot gateway intents configuration; HTTP client configuration for high-latency environments; `first_ready` flag for bot readiness tracking
     * **Commands**: Enhanced case viewing with user or case number arguments; FlexibleUserConverter for enhanced user identification; `get_user_safe` utility function for optimized user resolution; `convert_reason` function to clean moderation reasons by removing flag-like prefixes
@@ Expand All @@
     * **Development tools**: Performance profiling command (`profile`) for analyzing Python script performance with cProfile
     * **Testing**: Performance benchmarks for cache operations, data structures, permission systems, and string substitutions
     * **Documentation**: Help command documentation with usage, syntax, and interactive features; enhanced configuration, commands, and caching documentation
+    * **Valkey**: Optional Valkey cache backend with in-memory fallback; CacheService and CacheSetupService for connection and lifecycle; prefix manager, database controllers, and permission system use cache backend; Valkey health check in `db health`; configuration via settings, `.env`, and Docker Compose (service and profile); password validation and URL encoding for Valkey URLs; cache invalidation by key predicate; unit tests for cache backends, service, TTLCache, and managers
     ### Changed
-    * **Caching**: Guild configuration caching for audit log, mod log, jail role, and jail channel IDs; cache invalidation on config updates; cache pre-warming on bot startup; memory efficiency improvements with `__slots__` in cache classes (TTLCache, GuildConfigCacheManager, JailStatusCache)
     * **Performance**: Batch processing for permission checks, member role checks, and subcommand filtering; optimized command category retrieval; parallel execution of Discord actions and case creation in moderation coordinator; memory efficiency with `__slots__` in dependency trackers
     * **Optimizations**: Optimized placeholder substitution in activity handler and fact module using single-pass substitution; optimized TLDR cache directory resolution with `@lru_cache` decorator for command listings
     * **Interaction handling**: Improved deferral logic across all moderation commands; enhanced response handling in Info, XKCD, and other modules; `send_after_defer` method for improved message handling
@@ Expand All @@
     * **Dashboard**: Enhanced ranks management with cache control and rebuild options; improved cache invalidation logic for fresh data retrieval
     * **Task monitor**: Optimized task categorization and processing using generator expressions and defaultdict for better memory efficiency
     * **Guild config**: Simplified logging in `get_log_channel_ids` method; streamlined cache invalidation logic
-    * **Docker Compose**: Removed `initial_sync` from sync actions
+    * **Docker Compose**: Removed `initial_sync` from sync actions; Valkey service runs with warning log level (reduces verbosity)
     * **Python version**: Updated to 3.13.11 across configuration files, workflows, and pre-commit hooks
+    * **Cache**: TTLCache uses _CACHED_NONE sentinel for eviction and None handling; GuildConfigCacheManager has locking and null-lock support; guild config and jail status use async cache operations; permission system and moderation (jail, prefix manager) use cache backend with concurrent retrieval and storage; prefix cache write/delete uses asyncio; jail command has cooldown and invalidates cache on rejoin; moderation coordinator has improved type safety and parallel case creation and DM handling; documentation for caching, Valkey TTL, environment, and Docker setup
     ### Fixed
@@ Expand All @@
     * **Config**: Clarified cache invalidation handling in ConfigDashboard (automatically managed by GuildConfigController.update_config)
     * **Container**: Simplified Python image reference in Containerfile
     * **Pre-commit**: Updated Python version in pre-commit configuration for consistency
+    * **Cache**: TTLCache correctly handles _CACHED_NONE to avoid unnecessary refetching; ValkeyBackend serializes values with JSON (broad type support); CacheSetupService closes properly on init failure; AsyncCacheBackend exists method has type annotation
+    * **Logging**: Cache setup and cache managers use consistent logger message formatting
+    * **Bot and health**: Cache disconnection and Valkey health check have improved error logging
+    * **Permission system**: Command permission cache correctly handles malformed entries and cache hits
     ## [0.1.1] - 2026-01-21
@@ Expand Down @@

compose.yaml

-Original file line number
+Diff line change
@@ Expand Up / @@ -52,6 +52,28 @@ services: @@
           retries: 5
           start_period: 30s
         stop_grace_period: 30s
+      tux-valkey:
+        profiles: [valkey]
+        container_name: tux-valkey
+        hostname: tux-valkey
+        image: valkey/valkey:8.0-alpine
+        restart: ${RESTART_POLICY:-no}
+        ports: [127.0.0.1:6379:6379]
+        volumes:
+          - tux_valkey_data:/data
+        command: valkey-server --save 60 1 --loglevel warning
+        logging:
+          driver: json-file
+          options:
+            max-size: 10m
+            max-file: '3'
+            compress: 'true'
+        healthcheck:
+          test: [CMD, valkey-cli, ping]
+          interval: 10s
+          timeout: 5s
+          retries: 5
+          start_period: 5s
       # Production app: pre-built image, no build, security hardening.
       # Use: docker compose --profile production up -d
@@ Expand Down Expand Up / @@ -188,3 +210,5 @@ services: @@
     volumes:
       tux_postgres_data:
         driver: local
+      tux_valkey_data:
+        driver: local

config/config.json.example

-Original file line number
+Diff line change
@@ Expand Up / @@ -10,6 +10,11 @@ @@
         "HIDE_BOT_OWNER": false,
         "PREFIX": "$"
       },
+      "BOT_INTENTS": {
+        "presences": true,
+        "members": true,
+        "message_content": true
+      },
       "USER_IDS": {
         "BOT_OWNER_ID": 0,
         "SYSADMINS": [
@@ Expand Down @@

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: valkey #1179

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!