@bcelep/capint 0.4.2 → 0.6.5

package/skills/redis-development/rules/conn-pooling.md

@@ -0,0 +1,71 @@
+---
+title: Use Connection Pooling or Multiplexing
+impact: HIGH
+impactDescription: Reduces connection overhead by 10x or more
+tags: connections, pooling, multiplexing, performance
+description: Use Connection Pooling or Multiplexing
+alwaysApply: true
+---
+
+## Use Connection Pooling or Multiplexing
+
+Reuse connections via a pool or multiplexing instead of creating new connections per request.
+
+**Correct:** Use a connection pool.
+
+**Python** (redis-py):
+```python
+import redis
+
+# Good: Connection pool - reuses existing connections
+pool = redis.ConnectionPool(host='localhost', port=6379, max_connections=50)
+r = redis.Redis(connection_pool=pool)
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.JedisPooled;
+
+// JedisPooled manages a connection pool internally
+try (JedisPooled jedis = new JedisPooled("redis://localhost:6379")) {
+    jedis.set("testKey", "testValue");
+}
+```
+
+**Correct:** Use multiplexing (Lettuce, NRedisStack).
+
+```java
+// Lettuce uses multiplexing by default - single connection handles all traffic
+RedisClient client = RedisClient.create("redis://localhost:6379");
+StatefulRedisConnection<String, String> connection = client.connect();
+
+// All commands share the single connection efficiently
+connection.sync().set("key", "value");
+```
+
+**Incorrect:** Creating new connections per request.
+
+**Python** (redis-py):
+```python
+# Bad: New connection every time
+def get_user(user_id):
+    r = redis.Redis(host='localhost', port=6379)  # Don't do this
+    return r.get(f"user:{user_id}")
+```
+
+**Java** (Jedis):
+```java
+// Bad: Creating new client per request
+public String getUser(String userId) {
+    try (UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379")) {
+        return jedis.get("user:" + userId);  // Don't do this
+    }
+}
+```
+
+**Pooling vs Multiplexing:**
+- **Pooling**: Multiple connections shared across requests (redis-py, Jedis, go-redis)
+- **Multiplexing**: Single connection handles all traffic (NRedisStack, Lettuce)
+- Multiplexing cannot support blocking commands (BLPOP, etc.) as they would stall all callers
+
+Reference: [Connection Pools and Multiplexing](https://redis.io/docs/latest/develop/clients/pools-and-muxing/)

package/skills/redis-development/rules/conn-timeouts.md

@@ -0,0 +1,41 @@
+---
+title: Configure Connection Timeouts
+impact: MEDIUM
+impactDescription: Improves connection resilience and failure recovery
+tags: timeouts, connections, reliability
+description: Configure Connection Timeouts
+alwaysApply: true
+---
+
+## Configure Connection Timeouts
+
+Configure appropriate timeout values to improve your application's connection resilience. While most Redis clients set default timeouts, choosing well-tuned values based on your application's usage patterns leads to better failure recovery.
+
+**Correct:** Set timeouts based on your application needs.
+
+```python
+r = redis.Redis(
+    host='localhost',
+    socket_timeout=5.0,         # Read/write timeout - tune based on expected operation time
+    socket_connect_timeout=2.0,  # Connection timeout - shorter for fast failure detection
+    retry_on_timeout=True        # Automatic retry on timeout
+)
+```
+
+**Incorrect:** Relying solely on defaults without considering your use case.
+
+```python
+# Not ideal: Default timeouts may not match your application's needs
+r = redis.Redis(host='localhost')
+
+# For example, if your app needs fast failure detection,
+# the default timeouts might be too generous
+```
+
+**Considerations:**
+- Set `socket_connect_timeout` shorter than `socket_timeout` for quick connection failure detection
+- For latency-sensitive apps, use tighter timeouts with retry logic
+- For batch operations, allow longer timeouts to complete large operations
+- Consider using health checks alongside timeouts for robust failure handling
+
+Reference: [Redis Client Configuration](https://redis.io/docs/latest/develop/clients/)

package/skills/redis-development/rules/data-choose-structure.md

@@ -0,0 +1,76 @@
+---
+title: Choose the Right Data Structure
+impact: HIGH
+impactDescription: Optimal memory usage and operation performance
+tags: data-structures, strings, hashes, sets, lists, sorted-sets, json, streams, vector-sets
+description: Choose the Right Data Structure
+alwaysApply: true
+---
+
+## Choose the Right Data Structure
+
+Selecting the appropriate Redis data type for your use case is fundamental to performance and memory efficiency.
+
+| Use Case | Recommended Type | Why |
+|----------|------------------|-----|
+| Simple values, counters | String | Fast, atomic operations |
+| Object with fields | Hash | Memory efficient, partial updates, field-level expiration |
+| Queue, recent items | List | O(1) push/pop at ends |
+| Unique items, membership | Set | O(1) add/remove/check |
+| Rankings, ranges | Sorted Set | Score-based ordering |
+| Nested/hierarchical data | JSON | Path queries, nested structures, geospatial indexing with RQE |
+| Event logs, messaging | Stream | Persistent, consumer groups |
+| Similarity search | Vector Set | Native vector storage with built-in HNSW indexing |
+
+**Incorrect:** Using strings for everything.
+
+**Python** (redis-py):
+```python
+# Storing object as JSON string loses atomic field updates
+redis.set("user:1001", json.dumps({"name": "Alice", "email": "alice@example.com"}))
+
+# To update email, must fetch, parse, modify, and rewrite entire object
+user = json.loads(redis.get("user:1001"))
+user["email"] = "new@example.com"
+redis.set("user:1001", json.dumps(user))
+```
+
+**Java** (Jedis):
+```java
+// Bad: Storing as delimited string requires manual parsing
+jedis.set("bicycle", "Deimos;Ergonom;Enduro bikes;4972");
+String bike = jedis.get("bicycle");
+String[] fields = bike.split(";");
+String model = fields[0];  // Fragile and error-prone
+```
+
+**Correct:** Use Hash for objects with fields.
+
+**Python** (redis-py):
+```python
+# Hash allows atomic field updates
+redis.hset("user:1001", mapping={"name": "Alice", "email": "alice@example.com"})
+
+# Update single field without touching others
+redis.hset("user:1001", "email", "new@example.com")
+```
+
+**Java** (Jedis):
+```java
+import java.util.Map;
+import java.util.HashMap;
+
+// Good: Hash models properties naturally
+Map<String, String> hashFields = new HashMap<>();
+hashFields.put("model", "Deimos");
+hashFields.put("brand", "Ergonom");
+hashFields.put("type", "Enduro bikes");
+hashFields.put("price", "4972");
+
+jedis.hset("bicycle", hashFields);
+
+// Read individual field
+String model = jedis.hget("bicycle", "model");
+```
+
+Reference: [Choosing the Right Data Type](https://redis.io/docs/latest/develop/data-types/compare-data-types/)

package/skills/redis-development/rules/data-hash-field-expiry.md

@@ -0,0 +1,62 @@
+---
+title: Use Hash Field Expiration for Per-Field TTL
+impact: MEDIUM
+impactDescription: Fine-grained expiration without managing timers
+tags: hash, expiration, ttl, hexpire
+description: Use Hash Field Expiration for Per-Field TTL
+alwaysApply: true
+---
+
+## Use Hash Field Expiration for Per-Field TTL
+
+Use hash field expiration (Redis 7.4+) to delete individual fields automatically from a hash after a specific period of time. This is useful for caching scenarios where different fields have different lifetimes, and is easier than managing expiration from your own code.
+
+**Correct:** Use HEXPIRE to set per-field TTL on hash fields.
+
+**Python** (redis-py):
+```python
+import redis
+
+client = redis.Redis(host='localhost', port=6379)
+
+# Set hash fields
+client.hset("sensor:sensor1", mapping={
+    "air_quality": "256",
+    "battery_level": "89"
+})
+
+# Set 60-second TTL on specific fields (Redis 7.4+)
+client.hexpire("sensor:sensor1", 60, "air_quality", "battery_level")
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.UnifiedJedis;
+import java.util.Map;
+import java.util.HashMap;
+
+try (UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379")) {
+    Map<String, String> hashFields = new HashMap<>();
+    hashFields.put("air_quality", "256");
+    hashFields.put("battery_level", "89");
+
+    jedis.hset("sensor:sensor1", hashFields);
+    
+    // Set 60-second TTL on specific fields (Redis 7.4+)
+    jedis.hexpire("sensor:sensor1", 60, "air_quality", "battery_level");
+}
+```
+
+**When to use:**
+- Sensor data or metrics that become stale after a period
+- Session attributes where different fields have different lifetimes
+- Cached values within a hash that should auto-expire independently
+- Temporary flags or tokens stored alongside persistent data
+
+**When NOT needed:**
+- Persistent user profiles or configuration
+- Data where the entire hash should expire together (use `EXPIRE` on the key instead)
+- Fields managed by application logic with explicit deletion
+
+Reference: [HEXPIRE command](https://redis.io/docs/latest/commands/hexpire/)
+

package/skills/redis-development/rules/data-incr.md

@@ -0,0 +1,76 @@
+---
+title: Use INCR for Atomic Counters
+impact: MEDIUM
+impactDescription: Atomic increment avoids race conditions
+tags: incr, counters, atomic, performance
+description: Use INCR for Atomic Counters
+alwaysApply: true
+---
+
+## Use INCR for Atomic Counters
+
+If a string represents an integer value, use the `INCR` command to increment the number directly. The increment is atomic and always returns the new value. Use `INCRBY` to increment by any integer (positive or negative). This is more efficient and race-condition-free than reading, incrementing in code, and writing back.
+
+**Correct:** Use INCR/INCRBY for atomic counter updates.
+
+**Python** (redis-py):
+```python
+import redis
+
+client = redis.Redis(host='localhost', port=6379)
+
+# Initialize counter
+client.set("counter", "0")
+
+# Atomic increment - returns new value
+new_value = client.incr("counter")  # Returns 1
+
+# Increment by specific amount
+new_value = client.incrby("counter", 10)  # Returns 11
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.UnifiedJedis;
+
+try (UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379")) {
+    jedis.set("counter", "0");
+    
+    // Atomic increment - returns new value
+    long newValue = jedis.incr("counter");  // Returns 1
+    
+    // Increment by specific amount
+    newValue = jedis.incrBy("counter", 10);  // Returns 11
+}
+```
+
+**Incorrect:** Read-modify-write pattern creates race conditions.
+
+**Python** (redis-py):
+```python
+import redis
+
+client = redis.Redis(host='localhost', port=6379)
+
+client.set("counter", "0")
+
+# BAD: Race condition - another client could modify between GET and SET
+curr_value = int(client.get("counter"))
+client.set("counter", str(curr_value + 1))  # Not atomic!
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.UnifiedJedis;
+
+try (UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379")) {
+    jedis.set("counter", "0");
+    
+    // BAD: Race condition between GET and SET
+    long currValue = Long.parseLong(jedis.get("counter"));
+    jedis.set("counter", Long.toString(currValue + 1));  // Not atomic!
+}
+```
+
+Reference: [INCR command](https://redis.io/docs/latest/commands/incr/)
+

package/skills/redis-development/rules/data-key-naming.md

@@ -0,0 +1,62 @@
+---
+title: Use Consistent Key Naming Conventions
+impact: MEDIUM
+impactDescription: Improved maintainability and debugging
+tags: keys, naming, conventions, prefixes
+description: Use Consistent Key Naming Conventions
+alwaysApply: true
+---
+
+## Use Consistent Key Naming Conventions
+
+Well-structured key names improve code maintainability, debugging, and enable efficient key scanning.
+
+**Correct:** Use colons as separators with a consistent hierarchy.
+
+```
+# Pattern: service:entity:id:attribute
+user:1001:profile
+user:1001:settings
+order:2024:items
+cache:api:users:list
+session:abc123
+```
+
+**Python** (redis-py):
+```python
+# Good: Short, meaningful key
+redis.set("product:8361", cached_html)
+page = redis.get("product:8361")
+```
+
+**Java** (Jedis):
+```java
+// Good: Short, meaningful key derived from URL
+jedis.set("product:8361", "<some cached HTML>");
+String page = jedis.get("product:8361");
+```
+
+**Incorrect:** Inconsistent naming, spaces, or very long keys.
+
+```
+# These cause confusion and waste memory
+User_1001_Profile
+my key with spaces
+com.mycompany.myapp.production.users.profile.data.1001
+```
+
+**Java** (Jedis):
+```java
+// Bad: Using full URL as key wastes memory and slows comparisons
+jedis.set("http://www.verylongurlkey.com/store/products/product.html?id=8361",
+          "<some cached HTML>");
+```
+
+**Key naming tips:**
+- Keep keys short but readable—they consume memory
+- Consider key prefixes for multi-tenant applications
+- Extract short identifiers from URLs or long strings rather than using the whole thing
+- For large binary values, consider using a hash digest as the key instead of the value itself
+- Use consistent separators (colons are conventional)
+
+Reference: [Redis Keys](https://redis.io/docs/latest/develop/use/keyspace/)

package/skills/redis-development/rules/data-transactions.md

@@ -0,0 +1,74 @@
+---
+title: Use Transactions for Atomic Multi-Command Operations
+impact: MEDIUM
+impactDescription: Prevents race conditions and data inconsistency
+tags: transactions, multi, exec, atomicity
+description: Use Transactions for Atomic Multi-Command Operations
+alwaysApply: true
+---
+
+## Use Transactions for Atomic Multi-Command Operations
+
+Use the `MULTI`/`EXEC` commands to create a transaction when you need to execute multiple commands atomically. No other client requests will be processed while the transaction is executing, preventing other clients from modifying the keys used in the transaction and avoiding inconsistent data.
+
+**Correct:** Use transactions when multiple related keys must be updated together.
+
+**Python** (redis-py):
+```python
+import redis
+
+client = redis.Redis(host='localhost', port=6379)
+
+# Transaction ensures all commands execute atomically
+pipe = client.pipeline(transaction=True)
+pipe.set("person:1:name", "Alex")
+pipe.set("person:1:rank", "Captain")
+pipe.set("person:1:serial", "AB1234")
+pipe.execute()  # All commands execute as one atomic unit
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.UnifiedJedis;
+import redis.clients.jedis.Transaction;
+
+try (UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379")) {
+    Transaction tran = (Transaction) jedis.multi();
+
+    tran.set("person:1:name", "Alex");
+    tran.set("person:1:rank", "Captain");
+    tran.set("person:1:serial", "AB1234");
+
+    tran.exec();  // All commands execute atomically
+}
+```
+
+**Incorrect:** Executing related commands individually when atomicity is required.
+
+**Python** (redis-py):
+```python
+import redis
+
+client = redis.Redis(host='localhost', port=6379)
+
+# BAD when atomicity matters - another client could read partial state
+client.set("person:1:name", "Alex")
+# Another client could read here and see incomplete data
+client.set("person:1:rank", "Captain")
+client.set("person:1:serial", "AB1234")
+```
+
+**When to use transactions:**
+- Multiple keys must be updated as a single atomic unit
+- Other clients reading partial state would cause bugs
+- Implementing patterns like "transfer balance between accounts"
+
+**When transactions are NOT needed:**
+- Independent operations that don't need to be atomic
+- Single-command operations (already atomic)
+- When using pipelining purely for performance (use `pipeline(transaction=False)`)
+
+**Note:** Transactions add overhead. Only use them when atomicity is actually required.
+
+Reference: [Transactions](https://redis.io/docs/latest/develop/interact/transactions/)
+

package/skills/redis-development/rules/json-partial-updates.md

@@ -0,0 +1,49 @@
+---
+title: Use JSON Paths for Partial Updates
+impact: MEDIUM
+impactDescription: Avoids fetching and rewriting entire documents
+tags: json, partial-updates, paths, atomic
+description: Use JSON Paths for Partial Updates
+alwaysApply: true
+---
+
+## Use JSON Paths for Partial Updates
+
+Use JSON path syntax to update specific fields without fetching the entire document.
+
+**Correct:** Use JSON paths for targeted updates.
+
+```python
+# Store JSON document
+redis.json().set("user:1001", "$", {
+    "name": "Alice",
+    "email": "alice@example.com",
+    "preferences": {"theme": "dark", "notifications": True}
+})
+
+# Update nested field without fetching entire document
+redis.json().set("user:1001", "$.preferences.theme", "light")
+
+# Get specific field
+theme = redis.json().get("user:1001", "$.preferences.theme")
+
+# Increment numeric field atomically
+redis.json().numincrby("user:1001", "$.preferences.volume", 5)
+
+# Append to array
+redis.json().arrappend("user:1001", "$.tags", "premium")
+```
+
+**Incorrect:** Storing JSON as a string and parsing client-side.
+
+```python
+# Bad: Loses queryability and atomic updates
+redis.set("user:1001", json.dumps(user_data))
+
+# Must fetch, parse, modify, serialize, and rewrite
+data = json.loads(redis.get("user:1001"))
+data["preferences"]["theme"] = "light"
+redis.set("user:1001", json.dumps(data))
+```
+
+Reference: [Redis JSON Path](https://redis.io/docs/latest/develop/data-types/json/path/)

package/skills/redis-development/rules/json-vs-hash.md

@@ -0,0 +1,105 @@
+---
+title: Choose JSON vs Hash vs String Appropriately
+impact: MEDIUM
+impactDescription: Optimal data model for your use case
+tags: json, hash, string, data-structures, documents
+description: Choose JSON vs Hash vs String Appropriately
+alwaysApply: true
+---
+
+## Choose JSON vs Hash vs String Appropriately
+
+Redis offers three ways to store structured data: JSON, Hash, and serialized strings. Each has distinct trade-offs around atomic partial operations and indexability.
+
+| Feature | JSON | Hash | String (serialized JSON) |
+|---------|------|------|--------------------------|
+| **Structure** | Nested objects and arrays | Flat key-value pairs | Any structure |
+| **Atomic partial reads** | Yes (`$.field`) | Yes (`HGET`) | No (must fetch entire value) |
+| **Atomic partial writes** | Yes (`JSON.SET $.field`) | Yes (`HSET`) | No (must rewrite entire value) |
+| **RQE indexing** | Yes | Yes | No |
+| **Geospatial indexing** | Yes | Yes | No |
+| **Memory efficiency** | Higher overhead | More efficient | Most compact |
+| **Field-level expiration** | No | Yes (HEXPIRE) | No |
+
+**When to use each:**
+- **JSON**: Nested structures with atomic partial updates and indexing needs
+- **Hash**: Flat objects with atomic field access, field-level expiration, or memory efficiency
+- **String**: Simple caching where you always read/write the entire object and don't need indexing
+
+**Correct:** Use JSON for nested structures with atomic partial updates.
+
+**Python** (redis-py):
+```python
+# JSON supports nested structures and atomic deep updates
+redis.json().set("user:1001", "$", {
+    "name": "Alice",
+    "preferences": {"theme": "dark", "notifications": True}
+})
+
+# Atomic update of nested field - no read-modify-write needed
+redis.json().set("user:1001", "$.preferences.theme", "light")
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.UnifiedJedis;
+import redis.clients.jedis.json.Path2;
+import org.json.JSONObject;
+
+try (UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379")) {
+    JSONObject user = new JSONObject();
+    user.put("name", "Alice");
+    user.put("preferences", new JSONObject().put("theme", "dark"));
+
+    jedis.jsonSet("user:1001", new Path2("$"), user);
+
+    // Atomic update of nested field
+    jedis.jsonSet("user:1001", new Path2("$.preferences.theme"), "light");
+}
+```
+
+**Correct:** Use Hash for flat objects with atomic field access.
+
+**Python** (redis-py):
+```python
+# Hash is efficient for flat data with atomic field operations
+redis.hset("session:abc", mapping={
+    "user_id": "1001",
+    "created_at": "2024-01-01",
+    "ip": "192.168.1.1"
+})
+
+# Atomic field read and update
+ip = redis.hget("session:abc", "ip")
+redis.hset("session:abc", "ip", "10.0.0.1")
+```
+
+**Correct:** Use String for simple caching without partial updates.
+
+**Python** (redis-py):
+```python
+import json
+
+# String is fine when you always read/write the entire object
+# and don't need indexing or partial updates
+config = {"feature_flags": {"dark_mode": True}, "version": "1.0"}
+redis.set("config:app", json.dumps(config), ex=3600)
+
+# Must fetch and parse entire object
+config = json.loads(redis.get("config:app"))
+```
+
+**Incorrect:** Using String when you need atomic partial updates.
+
+**Python** (redis-py):
+```python
+import json
+
+# BAD: Must fetch, parse, modify, serialize, and rewrite entire object
+data = json.loads(redis.get("user:1001"))
+data["preferences"]["theme"] = "light"  # Not atomic!
+redis.set("user:1001", json.dumps(data))
+# Another client could have modified the object between GET and SET
+```
+
+Reference: [Data Type Comparison](https://redis.io/docs/latest/develop/data-types/compare-data-types/#documents)

package/skills/redis-development/rules/observe-commands.md

@@ -0,0 +1,53 @@
+---
+title: Use Observability Commands for Debugging
+impact: MEDIUM
+impactDescription: Enables quick diagnosis of performance issues
+tags: observability, slowlog, info, memory, debugging
+description: Use Observability Commands for Debugging
+alwaysApply: true
+---
+
+## Use Observability Commands for Debugging
+
+Redis provides built-in commands for monitoring and debugging.
+
+**Key commands:**
+
+```
+# Slow query log - find slow commands
+SLOWLOG GET 10
+SLOWLOG LEN
+SLOWLOG RESET
+
+# Server info - comprehensive stats
+INFO all
+INFO memory
+INFO stats
+INFO replication
+INFO clients
+
+# Memory analysis
+MEMORY DOCTOR
+MEMORY STATS
+MEMORY USAGE mykey
+
+# Client connections
+CLIENT LIST
+CLIENT INFO
+
+# Index info (RQE)
+FT.INFO idx:products
+FT.PROFILE idx:products SEARCH QUERY "@name:laptop"
+```
+
+**Correct:** Check SLOWLOG regularly.
+
+```python
+# Get recent slow queries
+slow_queries = redis.slowlog_get(10)
+for query in slow_queries:
+    print(f"Duration: {query['duration']}μs, Command: {query['command']}")
+```
+
+Reference: [Redis Monitoring](https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/latency/)
+