Skip to content
clstr.io

Persistence

In this stage, you’ll add persistence to your key-value store. Data should survive clean shutdowns and be restored when the server restarts.

Graceful Shutdown

Section titled “Graceful Shutdown”

When your server receives a termination signal (SIGTERM or SIGINT), it should:

  1. Wait for in-flight requests to complete (within 5 seconds)
  2. Save all key-value pairs to disk
  3. Exit with status code 0

Startup Recovery

Section titled “Startup Recovery”

When your server starts, it should:

  1. Check the DATA_DIR environment variable for the data directory path
  2. Load any previously saved key-value pairs
  3. Continue serving requests with the restored data

If no previous data exists, start with an empty store.

Storage

Section titled “Storage”

Save your in-memory state to disk during shutdown and restore it on startup. Create your data files in the directory given by the DATA_DIR environment variable. The serialization format and file naming are up to you - JSON, binary (Protocol Buffers, MessagePack, BSON, gob, pickle), plain text, whatever.

This approach survives clean shutdowns but not crashes. If the process dies unexpectedly, you’ll lose any data that wasn’t saved. That’s fine for this stage - you’ll add crash recovery in the next stage.

Testing

Section titled “Testing”

The test harness mounts a persistent volume at /app/data and sets the DATA_DIR environment variable to /app/data.

You can test your implementation using the clstr command:

Terminal window
$ clstr test
Testing persistence: Data Survives SIGTERM


✓ Data Survives a Graceful Restart
✓ All Data Survives Repeated Graceful Restarts
✓ Rapid Sequential Writes Survive a Graceful Restart
✓ Rapid Concurrent Writes Survive a Graceful Restart
✓ CLEAR Survives a Graceful Restart


PASSED ✓


Run 'clstr next' to advance to the next stage.

The tests will:

  1. Store data in your server
  2. Send SIGTERM to trigger graceful shutdown
  3. Restart your server
  4. Verify all data is still present

Debugging

Section titled “Debugging”

Your server’s output (stdout/stderr) is captured during testing and viewable with clstr logs. The STOPPED and STARTED markers show exactly when the server was restarted:

Terminal window
$ clstr logs n1


================ STARTED ================


Server listening on 0.0.0.0:8080
PUT /kv/kenya:capital accepted, value=Nairobi
PUT /kv/germany:capital accepted, value=Berlin
Flushing 2 keys to /app/data/store.json


================ STOPPED ================




================ STARTED ================


Server listening on 0.0.0.0:8080
Loaded 2 keys from /app/data/store.json
GET /kv/kenya:capital returning 200
GET /kv/germany:capital returning 200

Resources

Section titled “Resources”