# Redis Client API Reference

Complete reference for **raw Redis operations** available in the Forge Server extension. This module returns native Redis values without JSON formatting.

> **Note**: This is a low-level data access layer. Higher-level game modules (actor, garage, etc.) will provide structured JSON responses for SQF consumption.

## 🏗️ Implementation

All Redis operations are implemented using the `redis_operation!` macro for:
- **Consistent Error Handling**: All functions return identical error formats
- **Connection Management**: Automatic pool and connection handling
- **Synchronous Interface**: Functions block until Redis operations complete
- **Performance**: Zero-cost abstraction with compile-time optimization

## 🔗 Command Structure

All redis client commands follow the pattern: `"forge_server" callExtension ["redis:command", [parameters]]`

## 📝 Common Operations

### SET - Store a key-value pair
**Command**: `redis:common:set`
**Parameters**: `[key, value]`

```sqf
"forge_server" callExtension ["redis:common:set", ["player_name", "John"]]
```

**Raw Response**: `"OK"`

### GET - Retrieve a value by key
**Command**: `redis:common:get`
**Parameters**: `[key]`

```sqf
"forge_server" callExtension ["redis:common:get", ["player_name"]]
```

**Raw Response**: `"John"` (the actual stored value)

### INCR - Increment a numeric value
**Command**: `redis:common:incr`
**Parameters**: `[key, increment_amount]`

```sqf
"forge_server" callExtension ["redis:common:incr", ["player_score", 10]]
```

**Raw Response**: `"110"` (the new value as string)

### DECR - Decrement a numeric value
**Command**: `redis:common:decr`
**Parameters**: `[key, decrement_amount]`

```sqf
"forge_server" callExtension ["redis:common:decr", ["player_lives", 1]]
```

**Raw Response**: `"2"` (the new value as string)

### DEL - Delete a key
**Command**: `redis:common:del`
**Parameters**: `[key]`

```sqf
"forge_server" callExtension ["redis:common:del", ["temp_data"]]
```

**Raw Response**: `"1"` (number of keys deleted)

### KEYS - List all keys matching pattern
**Command**: `redis:common:keys`
**Parameters**: `[]` (currently returns all keys with "*" pattern)

```sqf
"forge_server" callExtension ["redis:common:keys", []]
```

**Raw Response**: `"player_name,player_score,mission_state"` (comma-separated list)

## 🗂️ Hash Operations

### HSET - Set hash field
**Command**: `redis:hash:set`
**Parameters**: `[hash_key, field, value]`

```sqf
"forge_server" callExtension ["redis:hash:set", ["player:123", "name", "John"]]
```

**Raw Response**: `"1"` (number of fields added)

### HGET - Get hash field
**Command**: `redis:hash:get`
**Parameters**: `[hash_key, field]`

```sqf
"forge_server" callExtension ["redis:hash:get", ["player:123", "name"]]
```

**Raw Response**: `"John"` (the field value)

### HMSET - Set multiple hash fields
**Command**: `redis:hash:mset`
**Parameters**: `[hash_key, [[field1, value1], [field2, value2], ...]]`

```sqf
"forge_server" callExtension ["redis:hash:mset", ["player:123", [["name", "John"], ["score", "100"]]]]
```

**Raw Response**: `"OK"`

### HGETALL - Get all hash fields
**Command**: `redis:hash:getall`
**Parameters**: `[hash_key]`

```sqf
"forge_server" callExtension ["redis:hash:getall", ["player:123"]]
```

**Raw Response**: `"name,John,score,100,level,5"` (comma-separated key-value pairs)

### HDEL - Delete hash field
**Command**: `redis:hash:del`
**Parameters**: `[hash_key, field]`

```sqf
"forge_server" callExtension ["redis:hash:del", ["player:123", "temp_field"]]
```

**Raw Response**: `"1"` (number of fields removed)

### HKEYS - Get all hash field names
**Command**: `redis:hash:keys`
**Parameters**: `[hash_key]`

```sqf
"forge_server" callExtension ["redis:hash:keys", ["player:123"]]
```

**Raw Response**: `"name,score,level"` (comma-separated field names)

### HVALS - Get all hash values
**Command**: `redis:hash:vals`
**Parameters**: `[hash_key]`

```sqf
"forge_server" callExtension ["redis:hash:vals", ["player:123"]]
```

**Raw Response**: `"John,100,5"` (comma-separated values)

### HLEN - Get hash field count
**Command**: `redis:hash:len`
**Parameters**: `[hash_key]`

```sqf
"forge_server" callExtension ["redis:hash:len", ["player:123"]]
```

**Raw Response**: `"3"` (number of fields in hash)

## 📋 List Operations

### LSET - Set list element by index
**Command**: `redis:list:set`
**Parameters**: `[list_key, index, value]`

```sqf
"forge_server" callExtension ["redis:list:set", ["mission_queue", 0, "patrol_alpha"]]
```

**Raw Response**: `"OK"`

### LGET - Get list element by index
**Command**: `redis:list:get`
**Parameters**: `[list_key, index]`

```sqf
"forge_server" callExtension ["redis:list:get", ["mission_queue", 0]]
```

**Raw Response**: `"patrol_alpha"` (the element value)

### LLEN - Get list length
**Command**: `redis:list:len`
**Parameters**: `[list_key]`

```sqf
"forge_server" callExtension ["redis:list:len", ["mission_queue"]]
```

**Raw Response**: `"5"` (list length)

### LRANGE - Get list elements in range
**Command**: `redis:list:range`
**Parameters**: `[list_key, start_index, end_index]`

```sqf
"forge_server" callExtension ["redis:list:range", ["mission_queue", 0, 2]]
```

**Raw Response**: `"patrol_alpha,escort_beta,defend_gamma"` (comma-separated values)

### LPUSH - Add element to list head
**Command**: `redis:list:lpush`
**Parameters**: `[list_key, value]`

```sqf
"forge_server" callExtension ["redis:list:lpush", ["recent_actions", "player_joined"]]
```

**Raw Response**: `"6"` (new list length)

### RPUSH - Add element to list tail
**Command**: `redis:list:rpush`
**Parameters**: `[list_key, value]`

```sqf
"forge_server" callExtension ["redis:list:rpush", ["mission_queue", "new_objective"]]
```

**Raw Response**: `"6"` (new list length)

### LPOP - Remove and return element from list head
**Command**: `redis:list:lpop`
**Parameters**: `[list_key, count]`

```sqf
"forge_server" callExtension ["redis:list:lpop", ["recent_actions", 1]]
```

**Raw Response**: `"player_joined"` (removed element) or `"item1,item2"` (if count > 1)

### RPOP - Remove and return element from list tail
**Command**: `redis:list:rpop`
**Parameters**: `[list_key, count]`

```sqf
"forge_server" callExtension ["redis:list:rpop", ["mission_queue", 1]]
```

**Raw Response**: `"new_objective"` (removed element) or `"item1,item2"` (if count > 1)

### LTRIM - Trim list to specified range
**Command**: `redis:list:trim`
**Parameters**: `[list_key, start_index, end_index]`

```sqf
"forge_server" callExtension ["redis:list:trim", ["recent_actions", 0, 9]]  // Keep only last 10 items
```

**Raw Response**: `"OK"`

### LREM - Remove elements from list
**Command**: `redis:list:del`
**Parameters**: `[list_key, count, value]`

```sqf
"forge_server" callExtension ["redis:list:del", ["mission_queue", 1, "completed_mission"]]
```

**Raw Response**: `"1"` (number of elements removed)

## 🎯 Set Operations

### SADD - Add element to set
**Command**: `redis:set:add`
**Parameters**: `[set_key, value]`

```sqf
"forge_server" callExtension ["redis:set:add", ["online_players", "player_123"]]
```

**Raw Response**: `"1"` (1 if element was added, 0 if already existed)

### SMEMBERS - Get all set members
**Command**: `redis:set:members`
**Parameters**: `[set_key]`

```sqf
"forge_server" callExtension ["redis:set:members", ["online_players"]]
```

**Raw Response**: `"player_123,player_456,player_789"` (comma-separated members)

### SCARD - Get set size
**Command**: `redis:set:card`
**Parameters**: `[set_key]`

```sqf
"forge_server" callExtension ["redis:set:card", ["online_players"]]
```

**Raw Response**: `"3"` (number of elements in set)

### SREM - Remove element from set
**Command**: `redis:set:del`
**Parameters**: `[set_key, value]`

```sqf
"forge_server" callExtension ["redis:set:del", ["online_players", "player_456"]]
```

**Raw Response**: `"1"` (1 if element was removed, 0 if didn't exist)

### SISMEMBER - Check if element is in set
**Command**: `redis:set:ismember`
**Parameters**: `[set_key, value]`

```sqf
"forge_server" callExtension ["redis:set:ismember", ["online_players", "player_123"]]
```

**Raw Response**: `"1"` (1 if member exists, 0 if not)

### SPOP - Remove and return random element
**Command**: `redis:set:pop`
**Parameters**: `[set_key]`

```sqf
"forge_server" callExtension ["redis:set:pop", ["available_missions"]]
```

**Raw Response**: `"mission_alpha"` (the removed element)

### SRANDMEMBER - Get random element without removing
**Command**: `redis:set:randmember`
**Parameters**: `[set_key]`

```sqf
"forge_server" callExtension ["redis:set:randmember", ["available_missions"]]
```

**Raw Response**: `"mission_beta"` (a random element)

### SRANDMEMBER - Get multiple random elements
**Command**: `redis:set:randmembers`
**Parameters**: `[set_key, count]`

```sqf
"forge_server" callExtension ["redis:set:randmembers", ["available_missions", 3]]
```

**Raw Response**: `"mission_alpha,mission_gamma,mission_delta"` (comma-separated random elements)

## ⚠️ Error Responses

All commands may return error responses in this format:

**Raw Error Response**: `"Error: <description>"`

### Common Error Types
- **Pool not initialized**: `"Error: Redis pool not initialized"`
- **Connection failed**: `"Error: Connection refused (os error 61)"`
- **Key not found**: `"Error: key not found"` (for operations on non-existent keys)
- **Invalid type**: `"Error: WRONGTYPE Operation against a key holding the wrong kind of value"`
- **Index out of range**: `"Error: index out of range"` (for list operations)

### Error Handling in Game Modules
Higher-level game modules should check if the response starts with `"Error: "` to distinguish between successful responses and errors.

```json
{
  "status": "error",
  "error": "Failed to connect to Redis server"
}
```

Common error types:
- **Connection errors**: Redis server unavailable
- **Operation errors**: Invalid data type for operation
- **Parameter errors**: Missing or invalid parameters
- **Pool errors**: Connection pool exhausted

## 📊 Response Fields

### Common Fields
- `status`: Always present - "success" or "error"
- `key`: The Redis key being operated on
- `error`: Error message (only on error responses)

### Success-Specific Fields
- `data`: The retrieved data (for GET operations)
- `value`: The stored value (for SET operations)
- `was_new`: Boolean indicating if operation created new data
- `removed_count`: Number of elements removed
- `fields_set`: Number of fields set in hash operations