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
• Password Authentication
• Basic Operations
• Client Integration
• ArmaFireflyClient Integration
• Performance Considerations

Starting the Server

Basic Start

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

With Command Line Options

# 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:

// 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

// 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

// 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 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