Struct StorageEngine 

pub struct StorageEngine { /* private fields */ }

The main storage engine for FlashKV.

This is the “brain” of the database - it stores all key-value pairs and handles concurrent access from multiple client connections.

Thread Safety

This struct is designed to be wrapped in an Arc and shared across all client handler tasks. All operations are thread-safe.

Example

use flashkv::storage::StorageEngine;
use bytes::Bytes;
use std::time::Duration;

let engine = StorageEngine::new();

// Set a key
engine.set(Bytes::from("name"), Bytes::from("Ariz"));

// Get the value
let value = engine.get(&Bytes::from("name"));
assert_eq!(value, Some(Bytes::from("Ariz")));

// Set with expiry
engine.set_with_ttl(Bytes::from("session"), Bytes::from("abc123"), Duration::from_secs(60));

Implementations

impl StorageEngine

pub fn new() -> Self

Creates a new storage engine with default settings.

pub fn set(&self, key: Bytes, value: Bytes) -> bool

Sets a key-value pair without expiry.

If the key already exists, its value is overwritten.

Returns

Returns true if a new key was created, false if an existing key was updated.

pub fn set_with_ttl(&self, key: Bytes, value: Bytes, ttl: Duration) -> bool

Sets a key-value pair with a TTL (Time-To-Live).

The key will automatically expire after the specified duration.

Returns

Returns true if a new key was created, false if an existing key was updated.

pub fn get(&self, key: &Bytes) -> Option<Bytes>

Gets the value for a key.

Returns None if the key doesn’t exist or has expired. This implements “lazy expiry” - expired keys are detected and removed on access.

pub fn get_entry(&self, key: &Bytes) -> Option<Entry>

Gets the full entry for a key (including metadata).

This is useful for commands like TTL that need access to expiry information.

pub fn delete(&self, key: &Bytes) -> bool

Deletes a key from the database.

Returns

Returns true if the key was deleted, false if it didn’t exist.

pub fn delete_many(&self, keys: &[Bytes]) -> u64

Deletes multiple keys from the database.

Returns

Returns the number of keys that were deleted.

pub fn exists(&self, key: &Bytes) -> bool

Checks if a key exists (and is not expired).

pub fn exists_many(&self, keys: &[Bytes]) -> u64

Counts how many of the given keys exist.

pub fn expire(&self, key: &Bytes, ttl: Duration) -> bool

Sets an expiry time on an existing key.

Returns

Returns true if the expiry was set, false if the key doesn’t exist.

pub fn persist(&self, key: &Bytes) -> bool

Removes the expiry from a key (makes it persistent).

Returns

Returns true if the expiry was removed, false if the key doesn’t exist or didn’t have an expiry.

pub fn ttl(&self, key: &Bytes) -> Option<i64>

Gets the remaining TTL for a key in seconds.

Returns

• Some(seconds) if the key exists and has an expiry
• Some(-1) if the key exists but has no expiry
• None if the key doesn’t exist

pub fn pttl(&self, key: &Bytes) -> Option<i64>

Gets the remaining TTL for a key in milliseconds.

pub fn incr(&self, key: &Bytes) -> Result<i64, &'static str>

Increments an integer value by 1.

If the key doesn’t exist, it’s set to 0 before the operation. Returns an error if the value is not a valid integer.

pub fn incr_by(&self, key: &Bytes, delta: i64) -> Result<i64, &'static str>

Increments an integer value by a specified amount.

pub fn decr(&self, key: &Bytes) -> Result<i64, &'static str>

Decrements an integer value by 1.

pub fn decr_by(&self, key: &Bytes, delta: i64) -> Result<i64, &'static str>

Decrements an integer value by a specified amount.

pub fn append(&self, key: &Bytes, value: &Bytes) -> usize

Appends a value to an existing string.

If the key doesn’t exist, it’s created with the given value.

Returns

Returns the length of the string after the append.

pub fn strlen(&self, key: &Bytes) -> usize

Gets the length of a string value.

Returns 0 if the key doesn’t exist.

pub fn keys(&self, pattern: &str) -> Vec<Bytes>

Returns all keys matching a pattern (simplified glob matching).

Supported patterns:

• * matches everything
• h*llo matches hello, hallo, hxllo
• h?llo matches hello, hallo, but not hllo
• h[ae]llo matches hello and hallo, but not hillo

Warning: This operation scans all keys and can be slow on large databases.

pub fn flush(&self)

Clears all data from the database.

This is equivalent to the Redis FLUSHDB command.

pub fn len(&self) -> u64

Returns the approximate number of keys in the database.

This is an approximation because it uses relaxed atomic ordering.

pub fn is_empty(&self) -> bool

Returns true if the database is empty.

pub fn stats(&self) -> StorageStats

Returns database statistics.

pub fn cleanup_expired(&self) -> u64

Cleans up expired keys from all shards.

This is called by the background expiry sweeper.

Returns

Returns the number of keys that were cleaned up.

pub fn lpush(&self, key: Bytes, values: Vec<Bytes>) -> usize

Pushes one or more values to the left (head) of a list. Creates the list if it doesn’t exist.

Returns

The length of the list after the push operation.

pub fn rpush(&self, key: Bytes, values: Vec<Bytes>) -> usize

Pushes one or more values to the right (tail) of a list. Creates the list if it doesn’t exist.

Returns

The length of the list after the push operation.

pub fn lpop(&self, key: &Bytes) -> Option<Bytes>

Removes and returns the first element (head) of a list.

Returns

The removed element, or None if the list is empty or doesn’t exist.

pub fn rpop(&self, key: &Bytes) -> Option<Bytes>

Removes and returns the last element (tail) of a list.

Returns

The removed element, or None if the list is empty or doesn’t exist.

pub fn llen(&self, key: &Bytes) -> usize

Returns the length of a list.

Returns

The length of the list, or 0 if the list doesn’t exist.

pub fn lindex(&self, key: &Bytes, index: i64) -> Option<Bytes>

Returns the element at the specified index in a list. Negative indices count from the end (-1 is the last element).

Returns

The element at the index, or None if index is out of range.

pub fn lrange(&self, key: &Bytes, start: i64, stop: i64) -> Vec<Bytes>

Returns a range of elements from a list. Both start and stop are inclusive. Negative indices count from the end.

Returns

A vector of elements in the specified range.

pub fn lset(&self, key: &Bytes, index: i64, value: Bytes) -> Result<(), String>

Sets the element at the specified index in a list. Negative indices count from the end.

Returns

Ok(()) if successful, Err with message if index is out of range or list doesn’t exist.

pub fn lrem(&self, key: &Bytes, count: i64, value: &Bytes) -> usize

Removes elements equal to the given value from a list.

• count > 0: Remove count elements equal to value, from head to tail.
• count < 0: Remove |count| elements equal to value, from tail to head.
• count = 0: Remove all elements equal to value.

Returns

The number of removed elements.

pub fn list_exists(&self, key: &Bytes) -> bool

Checks if a key exists as a list.

pub fn key_type(&self, key: &Bytes) -> &'static str

Returns the type of a key (“string”, “list”, or “none”).

pub fn memory_info(&self) -> MemoryInfo

Returns memory usage information (approximate).

Trait Implementations

impl Debug for StorageEngine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for StorageEngine

fn default() -> Self

Returns the “default value” for a type.