firefly/USAGE.md

# Firefly Server Usage Guide

Firefly is key-value store optimized for performance with native AOT compilation support.

## Table of Contents
- [Starting the Server](#starting-the-server)
- [Password Authentication](#password-authentication)
- [Basic Operations](#basic-operations)
- [Client Integration](#client-integration)
- [ArmaFireflyClient Integration](#armafireflyclient-integration)
- [Performance Considerations](#performance-considerations)

## Starting the Server

### Basic Start
```bash
# Start with default settings (port 6379, backups enabled)
firefly
```

### With Command Line Options
```bash
# Start with custom port
firefly --port 6380

# Start with authentication enabled
firefly --password yourSecretPassword

# Start with backups disabled
firefly --no-backup

# Start with custom backup interval (10 minutes)
firefly --backup-interval 10

# Start with limited backup files
firefly --max-backups 5

# Start with shorter connection timeout
firefly --timeout 60
```

### Full Command Reference
Run `firefly --help` to see all available options.

## Password Authentication

When starting Firefly with a password, clients must authenticate before running commands:

```
AUTH yourSecretPassword
```

### Authentication Behaviors

- If no password is set, all commands work without authentication
- If a password is set, only PING and AUTH commands work without authentication
- After successful authentication, all commands work normally
- Failed authentication attempts return an error but allow retries

## Basic Operations

### String Operations
```
SET key value      # Set a key-value pair
GET key            # Get a value by key
DEL key            # Delete a key (works for all data types)
```

### List Operations
```
LPUSH key value1 value2   # Add values to the beginning of a list
RPUSH key value1 value2   # Add values to the end of a list
LPOP key                  # Remove and return the first value
RPOP key                  # Remove and return the last value
LRANGE key start stop     # Get a range of values (inclusive)
LINDEX key index          # Get a value at a specific index
```

### Hash Table Operations
```
HSET key field value      # Set a field in a hash
HGET key field            # Get a field from a hash
HDEL key field            # Delete a field from a hash
HEXISTS key field         # Check if field exists in hash
HGETALL key               # Get all fields and values
HMSET key field1 value1 field2 value2   # Set multiple fields at once
```

### Backup Operations
```
SAVE                      # Save data immediately
BGSAVE                    # Save data in the background
```

## Client Integration

### Connecting with Redis Client
Firefly is compatible with Redis protocol. Use your preferred Redis client library:

```csharp
// C# example using StackExchange.Redis
ConnectionMultiplexer redis = ConnectionMultiplexer.Connect("localhost:6379,password=yourpassword");
IDatabase db = redis.GetDatabase();
db.StringSet("mykey", "myvalue");
string value = db.StringGet("mykey");
```

### Connecting with Raw TCP
```csharp
// Basic TCP connection example
using System.Net.Sockets;
using System.Text;

TcpClient client = new TcpClient("localhost", 6379);
NetworkStream stream = client.GetStream();

// Authenticate if needed
byte[] authCmd = Encoding.UTF8.GetBytes("AUTH yourpassword\r\n");
await stream.WriteAsync(authCmd);
// ... read response ...

// Send command
byte[] setCmd = Encoding.UTF8.GetBytes("SET mykey myvalue\r\n");
await stream.WriteAsync(setCmd);
// ... read response ...
```

## ArmaFireflyClient Integration

When using ArmaFireflyClient with Arma 3, you need to ensure the client has the correct password configured.

### Setting Up Connection in Arma 3
```sqf
// Connect to a password-protected Firefly server
"setup" callExtension ["127.0.0.1", "6379", "yourSecretPassword"];
```

This updates the client configuration to use the specified password for authentication. The client will automatically authenticate when connecting to the server.

### Using Default XML Configuration
Create a config.xml file in your @firefly directory:
```xml
<?xml version="1.0" encoding="utf-8"?>
<items>
  <host>127.0.0.1</host>
  <port>6379</port>
  <password>yourSecretPassword</password>
  <contextLog>false</contextLog>
  <debug>false</debug>
</items>
```

### Warning About Empty Password
Setting up ArmaFireflyClient without a password when connecting to a password-protected Firefly server will result in authentication failures. Always make sure your password matches the server's password.

## Performance Considerations

- Password authentication adds a small overhead to the initial connection
- For best performance with authenticated connections, reuse existing connections
- The server uses concurrent data structures to maintain performance even with authentication enabled
- Consider using a longer connection timeout (`--timeout`) to keep connections alive for longer periods

## Common Issues

1. **Authentication Errors**: Make sure the client is using the correct password
2. **Connection Refused**: Verify the server is running and listening on the expected port
3. **Timeout Errors**: Increase the connection timeout or check for network issues