SharpKV

SharpKV is a Redis-like key-value store for .NET. It supports an embedded in-memory API and a TCP server that speaks RESP for the commands listed below.

Highlights

• RESP-compatible protocol for the supported command set
• Use as an embedded library or run as a standalone server
• Append-only file (AOF) persistence
• TTL-based expiration
• Thread-safe operations
• Dockerfile included for container builds

Usage Modes

SharpKV can be used in two ways:

• Library (embedded): reference SharpKV and use KeyValueStore and extension helpers directly in your .NET process.
• Standalone server: run SharpKV.Server and connect via RESP (e.g., redis-cli or KVClient).

Examples

See examples/README.md for runnable samples and scripts.

• examples/SharpKV.Example.Embedded (embedded store usage)
• examples/SharpKV.Example.Client (client against a running server)
• examples/redis-tools (redis-cli and redis-benchmark helpers)

Quick Start

Prerequisites

• .NET 8 SDK

Build

git clone https://github.com/0xConstant1/SharpKV
cd SharpKV
dotnet build

Run the server

# Default (127.0.0.1:6379)
dotnet run --project src/SharpKV.Server

# Custom port with AOF persistence
dotnet run --project src/SharpKV.Server -- --port 7000 --aof data/store.aof

# Show all options
dotnet run --project src/SharpKV.Server -- --help

Test with redis-cli

redis-cli -p 6379

127.0.0.1:6379> SET greeting "Hello, SharpKV!"
OK
127.0.0.1:6379> GET greeting
"Hello, SharpKV!"
127.0.0.1:6379> INCR counter
(integer) 1
127.0.0.1:6379> SET session "abc123" EX 3600
OK
127.0.0.1:6379> TTL session
(integer) 3599

Library Usage

Install from NuGet

dotnet add package SharpKV

Use KeyValueStore directly for an embedded in-memory store:

using SharpKV;

using var store = new KeyValueStore();

store.Set("user:1:name", "Alice");
string? name = store.GetString("user:1:name");

store.Set("session:abc", "token123", TimeSpan.FromMinutes(30));
long ttl = store.TTL("session:abc");

store.Set("views", 0);
long count = store.Incr("views");

You can also store .NET objects as JSON via KeyValueStoreExtensions:

using SharpKV;

public record User(string Id, string Name, int Age);

using var store = new KeyValueStore();

var user = new User("u-123", "Alice", 32);
store.Set("user:u-123", user);

User? loaded = store.Get<User>("user:u-123");
Console.WriteLine(loaded?.Name);

For more helpers, see KeyValueStoreExtensions and the examples folder.

Server Mode

Command line options (see src/SharpKV.Server/Program.cs):

Usage:
  dotnet run --project src/SharpKV.Server -- [options]

Options:
  --host <address>        Bind address (default: 127.0.0.1)
  --port <number>         Port number (default: 6379)
  --max-connections <n>   Max concurrent connections (default: 1000)
  --aof <path>            Enable AOF persistence to file
  --client                Run client demo
  --help                  Show help

Docker

A Dockerfile is included at the repo root:

# Build and run
docker build -t sharpkv .
docker run -d -p 6379:6379 -v ./data:/app/data --name sharpkv sharpkv --aof /app/data/store.aof

Supported Commands

Command	Syntax	Description
GET	GET key	Get value by key
SET	SET key value [EX seconds] [PX milliseconds]	Set value with optional TTL
GETSET	GETSET key value	Atomically set a new value and return the old value
GETDEL	GETDEL key	Atomically get and delete a key
DEL / DELETE	DEL key [key ...]	Delete one or more keys
EXISTS	EXISTS key [key ...]	Check if keys exist
KEYS	KEYS pattern	Find keys matching glob pattern
MGET	MGET key [key ...]	Get multiple values
MSET	MSET key value [key value ...]	Set multiple key-value pairs
HSET	HSET key field value [field value ...]	Set one or more hash fields
HGET	HGET key field	Get a hash field value
HDEL	HDEL key field [field ...]	Delete one or more hash fields
HGETALL	HGETALL key	Get all hash fields and values
HLEN	HLEN key	Get number of fields in a hash
HEXISTS	HEXISTS key field	Check if a hash field exists
HMGET	HMGET key field [field ...]	Get one or more hash field values
HMSET	HMSET key field value [field value ...]	Set multiple hash fields
INCR	INCR key	Atomically increment integer
DECR	DECR key	Atomically decrement integer
INCRBY	INCRBY key amount	Increment integer by amount
DECRBY	DECRBY key amount	Decrement integer by amount
LPUSH	LPUSH key value [value ...]	Push values to the left of a list
RPUSH	RPUSH key value [value ...]	Push values to the right of a list
LPOP	LPOP key	Pop a value from the left of a list
RPOP	RPOP key	Pop a value from the right of a list
LRANGE	LRANGE key start stop	Get a range of elements from a list
SADD	SADD key member [member ...]	Add one or more members to a set
SREM	SREM key member [member ...]	Remove one or more members from a set
SPOP	SPOP key [count]	Pop one or more random members from a set
EXPIRE	EXPIRE key seconds	Set key expiration
TTL	TTL key	Get remaining TTL in seconds
INFO	INFO [section]	Server information
CONFIG GET	CONFIG GET pattern	Get server configuration values
PING	PING [message]	Health check
ECHO	ECHO message	Echo message back
FLUSH	FLUSH	Delete all keys
FLUSHDB	FLUSHDB	Delete all keys

Development

Run tests

dotnet test

Run benchmarks

dotnet run --project SharpKV.Benchmarks -c Release

Project Structure

SharpKV/
|-- SharpKV.slnx
|-- src/
|   |-- SharpKV/                 # Core library
|   |-- SharpKV.Server/          # Standalone server
|-- SharpKV.Tests/               # Unit tests
|-- SharpKV.Benchmarks/          # Benchmarks
|-- examples/                    # Example apps and scripts

License

GPL-2.0-only License. See LICENSE.