fpRedis - Redis Client for Free Pascal / Lazarus

A modern, feature-complete Redis client library for Free Pascal / Lazarus with full RESP3 protocol support.

✨ Features

Protocol & Compatibility

• ✅ RESP3 Protocol: Full support for Redis Serialization Protocol 3 (with RESP2 fallback)
• ✅ Redis 8.3 Compatible: Tested with Redis 8.3 (works with Redis 5.0+)
• ✅ Binary-Safe: Handles null bytes, high bytes (0xFF), and embedded CRLF
• ✅ Large Payloads: Tested with 1MB+ data transfers

Redis Features

• ✅ Streams: Full support (XADD, XREAD, XRANGE, Consumer Groups)
• ✅ Pub/Sub: Complete Pub/Sub implementation (PUBLISH, SUBSCRIBE, patterns)
• ✅ Transactions: MULTI/EXEC with queued commands
• ✅ All Data Types: Strings, Lists, Hashes, Sets, Sorted Sets, Streams
• ✅ Key Management: TTL, EXPIRE, SCAN with cursor iteration
• ✅ RESP3 Types: Maps, Sets, Pushes, Booleans, Doubles, Nulls, BigNumbers

Core Commands

• HELLO - Protocol version negotiation
• AUTH - ACL support with username/password
• SCAN - Cursor-based key iteration with patterns
• CLIENT - Connection management
• CONFIG - Server configuration
• And many more...

📦 Installation

Using Boss (Recommended)

Boss is a dependency manager for Delphi/Free Pascal projects.

# Install Boss first: https://github.com/HashLoad/boss

# Install fpRedis
boss install github.com/TechCOMTransport/fpRedis

Manual Installation

1. Clone this repository:

   git clone https://github.com/TechCOMTransport/fpRedis.git

2. Add to your project's unit path:

   • src/ - Core Redis client units
   • synapse/ - Network library (included)

3. In Lazarus IDE:

   • Project → Project Inspector → Compiler Options
   • Paths → Other unit files (-Fu)
   • Add: /path/to/fpRedis/src;/path/to/fpRedis/synapse

🚀 Quick Start

Basic Example

uses
  rd_protocol, rd_commands, rd_types;

var
  Redis: TRedisConnection;
  IO: TRedisIO;
  Response: TRedisReturnType;
begin
  IO := TRedisIO.Create;
  IO.TargetHost := '127.0.0.1';
  IO.TargetPort := '6379';
  
  Redis := TRedisConnection.Create(IO);
  try
    IO.Connect;
    
    // Switch to RESP3 protocol
    Redis.Hello(3);

    // Set a value
    Response := Redis.send_command2('SET', ['mykey', 'myvalue']);
    Response.Free;

    // Get a value
    Response := Redis.send_command2('GET', ['mykey']);
    if Response is TRedisBulkReturnType then
      WriteLn('Value: ', TRedisBulkReturnType(Response).Value);
    Response.Free;

  finally
    Redis.Free;
    IO.Free;
  end;
end;

Streams Example

var
  R: TRedisReturnType;
  StreamId: String;
begin
  // Add entry to stream
  R := Redis.send_command2('XADD', ['mystream', '*', 'sensor', 'temperature', 'value', '23.5']);
  StreamId := TRedisBulkReturnType(R).Value;
  WriteLn('Stream ID: ', StreamId);
  R.Free;
  
  // Read from stream
  R := Redis.send_command2('XRANGE', ['mystream', '-', '+']);
  // Process entries...
  R.Free;
end;

Pub/Sub Example

var
  SubIO: TRedisIO;
  SubRedis: TRedisConnection;
  R: TRedisReturnType;
begin
  // Create subscriber connection
  SubIO := TRedisIO.Create;
  SubIO.TargetHost := '127.0.0.1';
  SubIO.TargetPort := '6379';
  SubRedis := TRedisConnection.Create(SubIO);
  SubIO.Connect;
  
  // Subscribe to channel
  R := SubRedis.send_command2('SUBSCRIBE', ['mychannel']);
  R.Free;
  
  // Publish from another connection
  R := Redis.send_command2('PUBLISH', ['mychannel', 'Hello World!']);
  R.Free;
  
  // Note: For production, run subscriber in separate thread
  // to continuously receive messages
  
  SubRedis.Free;
  SubIO.Free;
end;

🧪 Testing

The library includes comprehensive tests covering all Redis 8.3 features:

# Compile tests
cd tests
fpc -MObjFPC -Scghi -O1 -g -gl -l \
    -Fi../src -Fi../synapse \
    -Fu../src -Fu../synapse \
    -FU. test_deep.pas

# Run tests (requires Redis running on 10.1.0.35:6379 or update REDIS_HOST)
./test_deep.exe

Test Coverage

• ✅ 128 test assertions
• ✅ 13 test categories
• ✅ 100% pass rate
• ✅ All RESP3 types
• ✅ Binary data safety
• ✅ Large payloads (1MB+)
• ✅ Streams operations
• ✅ Pub/Sub protocol
• ✅ Transactions
• ✅ All data structures

See tests/TEST_COVERAGE.md for detailed coverage report.

📚 Documentation

Core Units

• rd_protocol: Low-level protocol handling, socket I/O
• rd_commands: High-level Redis commands (TRedisConnection)
• rd_types: Response type definitions (TRedisReturnType and subclasses)

Response Types

Type	Description	RESP3
TRedisStatusReturnType	Simple strings like "OK"	+
TRedisErrorReturnType	Error messages	-
TRedisNumericReturnType	Integer values	:
TRedisBulkReturnType	Binary-safe strings	$
TRedisMultiBulkReturnType	Arrays	*
TRedisNullReturnType	Null values	_
TRedisBooleanReturnType	Boolean values	#
TRedisDoubleReturnType	Floating point	,
TRedisMapReturnType	Key-value maps	%
TRedisSetReturnType	Unordered sets	~

🔧 Advanced Usage

Binary-Safe Strings

var
  BinData: String;
begin
  // String with null bytes
  BinData := 'Hello' + #0 + 'World' + #255;
  
  Redis.send_command2('SET', ['binkey', BinData]).Free;
  
  R := Redis.send_command2('GET', ['binkey']);
  // Correctly handles binary data including null bytes
  R.Free;
end;

Transactions

begin
  Redis.send_command2('MULTI').Free;
  Redis.send_command2('SET', ['key1', 'value1']).Free;
  Redis.send_command2('SET', ['key2', 'value2']).Free;
  
  R := Redis.send_command2('EXEC');
  // R contains array of results
  R.Free;
end;

Consumer Groups (Streams)

begin
  // Create consumer group
  Redis.send_command2('XGROUP', ['CREATE', 'mystream', 'mygroup', '0', 'MKSTREAM']).Free;
  
  // Read as consumer
  R := Redis.send_command2('XREADGROUP', 
    ['GROUP', 'mygroup', 'consumer1', 'COUNT', '10', 'STREAMS', 'mystream', '>']);
  // Process messages...
  R.Free;
end;

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Fork the repository
2. Create your feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request

📋 Requirements

• Free Pascal 3.2.0+ or Lazarus 2.0+
• Redis 5.0+ (tested with Redis 8.3)
• Synapse networking library (included)

📄 License

Modified LGPL-3.0 - See LICENSE for details.

The modified LGPL allows you to link this library with your projects without requiring your code to be released under LGPL.

🙏 Credits

• Original implementation by Ido Kanner
• RESP3 protocol support and modernization by MFernstrom
• Synapse networking library by Lukas Gebauer

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

• Async/callback-based Pub/Sub
• Connection pooling
• Cluster support
• Sentinel support
• More helper methods for common patterns

---

Made with ❤️ for the Free Pascal community