Pensieve is a durable, in-memory key–value store written in Rust. It uses an LRU (Least Recently Used) cache for eviction and exposes a HTTP REST API via the Axum. The name Pensieve comes from one of the most fascinating magical objects in the Wizarding World

Table of Contents

• Overview
• Features
• Getting Started
  • Prerequisites
  • Building
  • Running
• Configuration
• API Reference
  • GET /get/{key}
  • POST /put
  • DELETE /delete/{key}
• Project Structure
• Error Handling
• Contributing
• License
• Acknowledgments

Overview

Pensieve provides a lightweight, durable, thread-safe REST API for storing, retrieving, and deleting string values by key. Internally, it maintains a capacity-limited LRU cache so that the most-recently-accessed keys stay in memory, while old entries are evicted when capacity is reached.

Features

• HTTP REST API with JSON communication
• LRU eviction policy (configurable capacity)
• Append-only logs for durability
• Thread-safe via Arc<Mutex<...>>
• Multi-node cluster support with Docker
• Inter-node heartbeat system for failure detection
• Built with Tokio and Axum

Getting Started

Prerequisites

• Rust (1.65+ recommended)
• Cargo (comes with Rust)
• Docker

Building

cargo build --release

Running

Deploy a 3-node cluster

make docker

This creates nodes accessible on ports 8001, 8002, and 8003 with automatic peer discovery and failure detection.

Configuration

Environment Variables

• NODE_ID: Unique identifier for the node (required for multi-node setup)
• PORT: Port number for the node (required for multi-node setup)
• PEERS: Comma-separated list of peer URLs for heartbeat communication (required for multi-node setup)

Cache Configuration

The cache capacity is currently hard-coded to 1000 entries in src/main.rs:

let store = Store::new(1000);

To change the capacity, edit that value or extend the code to accept a CLI flag or environment variable.

API Reference

All endpoints use application/json for requests and responses.

Core API Endpoints

GET /get/{key}

Retrieve the value associated with a key.

Request:

GET /get/foo HTTP/1.1
Host: localhost:7878

Example with curl: PORT = [8001,8002,8003]

curl http://localhost:{PORT}/get/foo

Response (key exists):

{ "val": "bar" }

Response (key missing):

{ "val": "" }

POST /put

Store or update a key–value pair.

Request (JSON body):

{ "key": "foo", "val": "bar" }

Example with curl:

curl -X POST http://localhost:{PORT}/put \
     -H "Content-Type: application/json" \
     -d '{ "key": "foo", "val": "bar" }'

Response:

{ "status": "ok" }

DELETE /delete/{key}

Remove a key from the store.

Request:

DELETE /delete/foo HTTP/1.1
Host: localhost:{PORT}

Example with curl:

curl -X DELETE http://localhost:{PORT}/delete/foo

Response:

{ "status": "ok" }

Contributing

Contributions, bug reports, and feature requests are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/...)
3. Commit your changes and open a pull request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

• Axum
• Tokio
• lru
• Serde & Serde JSON