@bcelep/capint 0.4.2 → 0.7.0

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

@@ -0,0 +1,39 @@
+---
+title: Monitor Key Redis Metrics
+impact: MEDIUM
+impactDescription: Early detection of performance and capacity issues
+tags: observability, metrics, monitoring, memory, connections
+description: Monitor Key Redis Metrics
+alwaysApply: true
+---
+
+## Monitor Key Redis Metrics
+
+Track these metrics to catch issues before they impact users.
+
+| Metric | What It Tells You | Alert When |
+|--------|-------------------|------------|
+| `used_memory` | Current memory usage | > 80% of maxmemory |
+| `connected_clients` | Number of connections | Sudden spikes or drops |
+| `blocked_clients` | Clients waiting on blocking ops | > 0 sustained |
+| `instantaneous_ops_per_sec` | Current throughput | Significant drops |
+| `keyspace_hits/misses` | Cache hit ratio | Hit ratio < 80% |
+| `rejected_connections` | Connection limit issues | > 0 |
+| `rdb_last_save_time` | Last persistence snapshot | Too old |
+
+**Correct:** Export metrics to your monitoring system.
+
+```python
+# Get key metrics
+info = redis.info()
+print(f"Memory: {info['used_memory_human']}")
+print(f"Connections: {info['connected_clients']}")
+print(f"Ops/sec: {info['instantaneous_ops_per_sec']}")
+print(f"Hit ratio: {info['keyspace_hits'] / (info['keyspace_hits'] + info['keyspace_misses']) * 100:.1f}%")
+```
+
+**Redis Insight:**
+Use Redis Insight for visual monitoring, query profiling, and debugging. It includes Redis Copilot for natural language queries.
+
+Reference: [Redis Insight](https://redis.io/insight/)
+

package/skills/redis-development/rules/ram-limits.md

@@ -0,0 +1,42 @@
+---
+title: Configure Memory Limits and Eviction Policies
+impact: HIGH
+impactDescription: Prevents out-of-memory crashes and unpredictable behavior
+tags: memory, maxmemory, eviction, lru, ttl
+description: Configure Memory Limits and Eviction Policies
+alwaysApply: true
+---
+
+## Configure Memory Limits and Eviction Policies
+
+Always configure `maxmemory` and an eviction policy to prevent Redis from consuming all available memory.
+
+**Correct:** Set explicit memory limits.
+
+```
+maxmemory 2gb
+maxmemory-policy allkeys-lru
+```
+
+| Policy | Use Case |
+|--------|----------|
+| `volatile-lru` | Evict keys with TTL, least recently used first |
+| `allkeys-lru` | Evict any key, least recently used first |
+| `volatile-ttl` | Evict keys closest to expiration |
+| `noeviction` | Return errors when memory is full (use for critical data) |
+
+**Incorrect:** Running Redis without memory limits.
+
+```
+# No maxmemory set - Redis will use all available RAM
+# Can cause OOM killer to terminate Redis or other processes
+```
+
+**Memory optimization tips:**
+- Use Hashes for small objects (more memory-efficient than separate keys)
+- Use `OBJECT ENCODING key` to check how Redis stores your data
+- Use `MEMORY USAGE key` to check individual key memory consumption
+- Enable compression in your client for large values
+
+Reference: [Redis Memory Optimization](https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/memory-optimization/)
+

package/skills/redis-development/rules/ram-ttl.md

@@ -0,0 +1,55 @@
+---
+title: Set TTL on Cache Keys
+impact: HIGH
+impactDescription: Prevents unbounded memory growth
+tags: ttl, expiration, cache, memory
+description: Set TTL on Cache Keys
+alwaysApply: true
+---
+
+## Set TTL on Cache Keys
+
+Always set expiration times on cache keys to prevent unbounded memory growth.
+
+**Correct:** Set TTL at write time.
+
+**Python** (redis-py):
+```python
+# Good: TTL set atomically with the value
+redis.setex("cache:user:1001", 3600, user_json)
+
+# Good: For hashes, set TTL after
+redis.hset("session:abc", mapping=session_data)
+redis.expire("session:abc", 1800)
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.params.SetParams;
+
+// Good: TTL set atomically with SetParams
+jedis.set("cachedItem:1", "fe8c357903ac9", new SetParams().ex(120));
+```
+
+**Incorrect:** Forgetting TTL on cache keys.
+
+**Python** (redis-py):
+```python
+# Risk: This key may live forever
+redis.set("cache:user:1001", user_json)
+```
+
+**Java** (Jedis):
+```java
+// Risk: This key may live forever
+jedis.set("cachedItem:1", "fe8c357903ac9");
+```
+
+**TTL strategies:**
+- Cache data: 1-24 hours depending on freshness requirements
+- Sessions: 30 minutes to 24 hours
+- Rate limiting: Seconds to minutes
+- Temporary locks: Seconds with automatic release
+
+Reference: [Redis EXPIRE](https://redis.io/commands/expire/)
+

package/skills/redis-development/rules/rqe-dialect.md

@@ -0,0 +1,47 @@
+---
+title: Use DIALECT 2 for Query Syntax
+impact: MEDIUM
+impactDescription: Ensures consistent query behavior and access to modern features
+tags: rqe, dialect, query, syntax
+description: Use DIALECT 2 for Query Syntax
+alwaysApply: true
+---
+
+## Use DIALECT 2 for Query Syntax
+
+Use DIALECT 2 for consistent query behavior. Many Redis client libraries now default to DIALECT 2, and other dialects (1, 3, 4) are deprecated as of Redis 8.
+
+**Correct:** Use DIALECT 2 explicitly or rely on modern client defaults.
+
+```python
+from redis import Redis
+
+r = Redis()
+
+# Modern redis-py (6.0+) defaults to DIALECT 2
+# You can also set it explicitly
+results = r.ft("idx:products").search(
+    "@name:laptop",
+    dialect=2
+)
+```
+
+```
+# In raw commands, specify DIALECT 2
+FT.SEARCH idx:products "@name:laptop" DIALECT 2
+
+FT.AGGREGATE idx:products "@category:{electronics}"
+    GROUPBY 1 @category
+    REDUCE COUNT 0 AS count
+    DIALECT 2
+```
+
+**Note:** DIALECT 2 is required for vector search queries. Most modern client libraries (redis-py 6.0+, go-redis, Lettuce) now use DIALECT 2 by default.
+
+**Why DIALECT 2:**
+- Consistent handling of special characters
+- Better NULL value handling
+- More predictable query parsing
+- Required for vector search
+
+Reference: [Query Dialects](https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/dialects/)

package/skills/redis-development/rules/rqe-field-types.md

@@ -0,0 +1,81 @@
+---
+title: Choose the Correct Field Type
+impact: HIGH
+impactDescription: Use TAG instead of TEXT for filtering to improve query speed 10x
+tags: rqe, field-types, text, tag, numeric, geo, geoshape, vector
+description: Choose the Correct Field Type
+alwaysApply: true
+---
+
+## Choose the Correct Field Type
+
+Each field type has different capabilities and performance characteristics.
+
+| Field Type | Use When | Notes |
+|------------|----------|-------|
+| TEXT | Full-text search needed | Tokenized, stemmed |
+| TAG | Exact match, filtering | Faster than TEXT for filtering |
+| NUMERIC | Range queries, sorting | Use for prices, counts, timestamps |
+| GEO | Point location queries | Lat/long coordinates (single points) |
+| GEOSHAPE | Area/region queries | Polygons, circles, rectangles |
+| VECTOR | Similarity search | HNSW or FLAT algorithm |
+
+**Correct:** Use TAG for exact matching.
+
+```
+# Good: TAG for exact category matching
+FT.CREATE idx:products ON HASH PREFIX 1 product:
+    SCHEMA
+        category TAG SORTABLE
+        status TAG
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.search.*;
+
+Schema schema = new Schema()
+    .addTextField("name", 1)
+    .addTagField("categories");  // TAG for exact matching
+
+IndexDefinition def = new IndexDefinition(IndexDefinition.Type.HASH);
+
+jedis.ftCreate("idx", IndexOptions.defaultOptions().setDefinition(def), schema);
+
+// Query with TAG syntax
+SearchResult result = jedis.ftSearch("idx", "@categories:{chef|runner}");
+```
+
+**Incorrect:** Using TEXT when you don't need full-text features.
+
+```
+# Overkill: TEXT for category adds unnecessary tokenization
+FT.CREATE idx:products ON HASH PREFIX 1 product:
+    SCHEMA
+        category TEXT
+        status TEXT
+```
+
+**Java** (Jedis):
+```java
+// Bad: TEXT for categories adds unnecessary overhead
+Schema schema = new Schema()
+    .addTextField("name", 1)
+    .addTextField("categories", 1);  // Overkill for exact matching
+```
+
+**Correct:** Use GEO for points, GEOSHAPE for areas.
+
+```
+# GEO for point locations (stores, users)
+FT.CREATE idx:stores ON HASH PREFIX 1 store:
+    SCHEMA
+        location GEO
+
+# GEOSHAPE for areas (delivery zones, boundaries)
+FT.CREATE idx:zones ON JSON PREFIX 1 zone:
+    SCHEMA
+        $.boundary AS boundary GEOSHAPE
+```
+
+Reference: [Redis Search Field Types](https://redis.io/docs/latest/develop/interact/search-and-query/indexing/geoindex/)

package/skills/redis-development/rules/rqe-index-creation.md

@@ -0,0 +1,73 @@
+---
+title: Index Only Fields You Query
+impact: HIGH
+impactDescription: Reduces index size and improves write performance
+tags: rqe, ft.create, index, schema
+description: Index Only Fields You Query
+alwaysApply: true
+---
+
+## Index Only Fields You Query
+
+Create indexes with only the fields you need to search, filter, or sort on.
+
+**Correct:** Index specific fields and use prefixes.
+
+```
+FT.CREATE idx:products ON HASH PREFIX 1 product:
+    SCHEMA
+        name TEXT WEIGHT 2.0
+        description TEXT
+        category TAG SORTABLE
+        price NUMERIC SORTABLE
+        location GEO
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.search.*;
+
+Schema schema = new Schema()
+    .addTextField("name", 1)
+    .addTagField("categories");
+
+// Good: Specify prefix to index only matching keys
+IndexDefinition def = new IndexDefinition(IndexDefinition.Type.HASH)
+    .setPrefixes("person:");
+
+jedis.ftCreate("idx", IndexOptions.defaultOptions().setDefinition(def), schema);
+```
+
+**Incorrect:** Over-indexing or indexing unused fields.
+
+```
+# Bad: Indexing every field "just in case"
+FT.CREATE idx:products ON HASH PREFIX 1 product:
+    SCHEMA
+        name TEXT
+        description TEXT
+        category TEXT
+        subcategory TEXT
+        brand TEXT
+        sku TEXT
+        price NUMERIC
+        cost NUMERIC
+        margin NUMERIC
+        ...
+```
+
+**Java** (Jedis):
+```java
+// Bad: No prefix means all hashes get indexed
+IndexDefinition def = new IndexDefinition(IndexDefinition.Type.HASH);
+// This will index every hash in the database!
+```
+
+**Tips:**
+- Start with the minimum required fields
+- Add fields as query patterns emerge
+- Use `FT.INFO` to monitor index size
+- Always specify a prefix to avoid indexing unrelated keys
+
+Reference: [Redis Search Indexing](https://redis.io/docs/latest/develop/interact/search-and-query/indexing/)
+

package/skills/redis-development/rules/rqe-index-management.md

@@ -0,0 +1,49 @@
+---
+title: Manage Indexes for Zero-Downtime Updates
+impact: MEDIUM
+impactDescription: Use aliases for seamless index updates
+tags: rqe, index, alias, management, reindex
+description: Manage Indexes for Zero-Downtime Updates
+alwaysApply: true
+---
+
+## Manage Indexes for Zero-Downtime Updates
+
+Use aliases to swap indexes without application changes.
+
+**Correct:** Use aliases for production indexes.
+
+```
+# Create versioned index
+FT.CREATE idx:products_v2 ON HASH PREFIX 1 product:
+    SCHEMA
+        name TEXT
+        category TAG SORTABLE
+        price NUMERIC SORTABLE
+
+# Point alias to new index
+FT.ALIASADD products idx:products_v2
+
+# Application queries use alias
+FT.SEARCH products "@category:{electronics}"
+
+# Later, swap to new version
+FT.ALIASUPDATE products idx:products_v3
+```
+
+**Useful management commands:**
+
+```
+# Check index info
+FT.INFO idx:products
+
+# Drop and recreate (non-blocking)
+FT.DROPINDEX idx:products
+FT.CREATE idx:products ...
+
+# List all indexes
+FT._LIST
+```
+
+Reference: [Redis Search Index Management](https://redis.io/docs/latest/develop/interact/search-and-query/administration/)
+

package/skills/redis-development/rules/rqe-query-optimization.md

@@ -0,0 +1,49 @@
+---
+title: Write Efficient Queries
+impact: HIGH
+impactDescription: Proper filtering reduces query time by orders of magnitude
+tags: rqe, ft.search, query, performance, filters
+description: Write Efficient Queries
+alwaysApply: true
+---
+
+## Write Efficient Queries
+
+Be specific and use filters to reduce the result set early.
+
+**Correct:** Use specific filters and limit results.
+
+```
+# Good: Specific query with filters
+FT.SEARCH idx:products "@category:{electronics} @price:[100 500]"
+    LIMIT 0 20
+    RETURN 3 name price category
+
+# Good: Use SORTBY and LIMIT
+FT.SEARCH idx:products "@name:laptop"
+    SORTBY price ASC
+    LIMIT 0 10
+```
+
+**Incorrect:** Broad queries returning large result sets.
+
+```
+# Bad: Wildcard prefix scans entire index
+FT.SEARCH idx:products "*" LIMIT 0 10000
+
+# Bad: Loading all fields from source document
+FT.AGGREGATE idx:products "*" LOAD *
+```
+
+**Performance tips:**
+- Add `SORTABLE` to fields used in `SORTBY`
+- Use `TAG SORTABLE UNF` for best performance on tag fields
+- Use `NOSTEM` if you don't need stemming
+- Profile queries with `FT.PROFILE`
+
+```
+FT.PROFILE idx:products SEARCH QUERY "@category:{electronics}"
+```
+
+Reference: [Redis Search Query Syntax](https://redis.io/docs/latest/develop/interact/search-and-query/query/)
+

package/skills/redis-development/rules/rqe-skip-initial-scan.md

@@ -0,0 +1,82 @@
+---
+title: Use SKIPINITIALSCAN for New Data Only Indexes
+impact: MEDIUM
+impactDescription: Faster index creation, avoids indexing existing data
+tags: index, skipinitialscan, rqe, search
+description: Use SKIPINITIALSCAN for New Data Only Indexes
+alwaysApply: true
+---
+
+## Use SKIPINITIALSCAN for New Data Only Indexes
+
+Enable the `SKIPINITIALSCAN` option when creating an index if you only want to include items that are added after the index is created. This makes index creation faster and avoids indexing existing data that you don't need to search.
+
+**Correct:** Use SKIPINITIALSCAN when you only need to index new data.
+
+**Python** (redis-py):
+```python
+import redis
+from redis.commands.search.field import TextField, TagField
+from redis.commands.search.indexDefinition import IndexDefinition, IndexType
+
+client = redis.Redis(host='localhost', port=6379)
+
+# Create index that only indexes new documents
+schema = (
+    TextField("name"),
+    TagField("categories")
+)
+
+definition = IndexDefinition(
+    prefix=["person:"],
+    index_type=IndexType.HASH
+)
+
+# SKIPINITIALSCAN - only index documents added after creation
+client.ft("idx").create_index(
+    schema,
+    definition=definition,
+    skip_initial_scan=True
+)
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.UnifiedJedis;
+import redis.clients.jedis.search.FTCreateParams;
+import redis.clients.jedis.search.IndexDataType;
+import redis.clients.jedis.search.schemafields.SchemaField;
+import redis.clients.jedis.search.schemafields.TagField;
+import redis.clients.jedis.search.schemafields.TextField;
+
+try (UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379")) {
+    FTCreateParams params = new FTCreateParams()
+        .on(IndexDataType.HASH)
+        .skipInitialScan();  // Only index new documents
+
+    jedis.ftCreate(
+        "idx",
+        params,
+        new SchemaField[]{
+            new TextField("name"),
+            new TagField("categories")
+        }
+    );
+}
+```
+
+**When to use SKIPINITIALSCAN:**
+- Creating an index for a new feature where existing data is irrelevant
+- Setting up indexes in advance before data arrives
+- When existing data would be too large to scan during index creation
+- Event-driven architectures where you only care about new events
+
+**When NOT to use (default behavior is correct):**
+- You need to search existing data immediately after index creation
+- Migrating to a new index schema and need all data indexed
+- Most typical use cases where historical data matters
+
+**Note:** The default behavior (without SKIPINITIALSCAN) indexes all existing matching keys, which is usually what you want.
+
+Reference: [FT.CREATE SKIPINITIALSCAN](https://redis.io/docs/latest/commands/ft.create/)
+

package/skills/redis-development/rules/security-acls.md

@@ -0,0 +1,41 @@
+---
+title: Use ACLs for Fine-Grained Access Control
+impact: HIGH
+impactDescription: Limits blast radius if credentials are compromised
+tags: security, acl, users, permissions, least-privilege
+description: Use ACLs for Fine-Grained Access Control
+alwaysApply: true
+---
+
+## Use ACLs for Fine-Grained Access Control
+
+Create users with only the permissions they need (principle of least privilege).
+
+**Correct:** Create specific users with limited permissions.
+
+```
+# Read-only user for cache access
+ACL SETUSER app_readonly on >password ~cache:* +get +mget +scan
+
+# Writer that can't run dangerous commands
+ACL SETUSER app_writer on >password ~* +@all -@dangerous
+
+# Admin user (use sparingly)
+ACL SETUSER admin on >strong-password ~* +@all
+```
+
+**Incorrect:** Using the default user for everything.
+
+```
+# Bad: Single password for all access
+requirepass shared-password
+```
+
+**ACL categories:**
+- `@read` - Read commands
+- `@write` - Write commands
+- `@dangerous` - Commands like FLUSHALL, DEBUG
+- `@admin` - Administrative commands
+
+Reference: [Redis ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/)
+

package/skills/redis-development/rules/security-auth.md

@@ -0,0 +1,78 @@
+---
+title: Always Use Authentication in Production
+impact: HIGH
+impactDescription: Prevents unauthorized access to your data
+tags: security, authentication, password, tls, ssl
+description: Always Use Authentication in Production
+alwaysApply: true
+---
+
+## Always Use Authentication in Production
+
+Never run Redis without authentication in production environments.
+
+**Correct:** Use password and TLS.
+
+**Python** (redis-py):
+```python
+r = redis.Redis(
+    host='localhost',
+    port=6379,
+    password='your-strong-password',
+    ssl=True,
+    ssl_cert_reqs='required'
+)
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.*;
+import javax.net.ssl.*;
+import java.security.KeyStore;
+
+// Create SSL context with trust store and key store
+KeyStore trustStore = KeyStore.getInstance("jks");
+trustStore.load(new FileInputStream("./truststore.jks"), "password".toCharArray());
+
+TrustManagerFactory tmf = TrustManagerFactory.getInstance("X509");
+tmf.init(trustStore);
+
+SSLContext sslContext = SSLContext.getInstance("TLS");
+sslContext.init(null, tmf.getTrustManagers(), null);
+
+JedisClientConfig config = DefaultJedisClientConfig.builder()
+    .ssl(true)
+    .sslSocketFactory(sslContext.getSocketFactory())
+    .user("redisUser")
+    .password("redisPassword")
+    .build();
+
+JedisPooled jedis = new JedisPooled(new HostAndPort("redis-host", 6379), config);
+```
+
+**Incorrect:** Connecting without authentication.
+
+**Python** (redis-py):
+```python
+# Bad: No authentication
+r = redis.Redis(host='localhost', port=6379)
+```
+
+**Java** (Jedis):
+```java
+// Bad: No authentication or TLS
+UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379");
+```
+
+**Configuration:**
+
+```
+# redis.conf
+requirepass your-strong-password
+tls-port 6380
+tls-cert-file /path/to/redis.crt
+tls-key-file /path/to/redis.key
+```
+
+Reference: [Redis Security](https://redis.io/docs/latest/operate/oss_and_stack/management/security/)
+

package/skills/redis-development/rules/security-network.md

@@ -0,0 +1,52 @@
+---
+title: Secure Network Access
+impact: HIGH
+impactDescription: Reduces attack surface and prevents unauthorized access
+tags: security, network, firewall, bind, tls
+description: Secure Network Access
+alwaysApply: true
+---
+
+## Secure Network Access
+
+Restrict network access to Redis to only trusted sources.
+
+**Correct:** Bind to specific interfaces.
+
+```
+# redis.conf
+bind 127.0.0.1 192.168.1.100
+protected-mode yes
+```
+
+**Correct:** Use firewall rules.
+
+```bash
+# Allow only application servers
+iptables -A INPUT -p tcp --dport 6379 -s 192.168.1.0/24 -j ACCEPT
+iptables -A INPUT -p tcp --dport 6379 -j DROP
+```
+
+**Incorrect:** Exposing Redis to the internet.
+
+```
+# Bad: Binds to all interfaces
+bind 0.0.0.0
+protected-mode no
+```
+
+**Security checklist:**
+- Use TLS for connections
+- Bind to specific interfaces, not `0.0.0.0`
+- Use firewall rules to restrict access
+- Disable dangerous commands in production
+
+```
+# Disable dangerous commands
+rename-command FLUSHALL ""
+rename-command DEBUG ""
+rename-command CONFIG ""
+```
+
+Reference: [Redis Security](https://redis.io/docs/latest/operate/oss_and_stack/management/security/)
+