TCP Protocol

Overview

The distributed cache uses a simple text-based TCP protocol, similar to Redis. Commands are sent as strings with \r\n delimiters.

Client ─── SET key value\r\n ───→ Server
Client ←── OK\r\n ────────────── Server

Commands

Command	Syntax	Response	Description
SET	SET key value [ttl]	OK	Store key-value pair
GET	GET key	VALUE data or NULL	Retrieve value
DEL	DEL key	OK or NULL	Delete key
PING	PING	PONG	Health check
REPLICATE	REPLICATE key value	OK	Replicate data to node
ELECT	ELECT nodeId	OK	Leader election

Wire Format

# Request format
COMMAND key value ttl\r\n

# Response format
STATUS data\r\n

Examples

# Store a value
SET user:123 {"name":"John","email":"john@example.com"}\r\n
→ OK\r\n

# Retrieve a value
GET user:123\r\n
→ VALUE {"name":"John","email":"john@example.com"}\r\n

# Delete a key
DEL user:123\r\n
→ OK\r\n

# Health check
PING\r\n
→ PONG\r\n

Error Handling

# Unknown command
INVALID_CMD\r\n
→ ERR Unknown command\r\n

# Key not found
GET nonexistent\r\n
→ NULL\r\n

Usage with CacheClient

import { CacheClient } from "distributed-cache";

const client = new CacheClient({
  host: "127.0.0.1",
  port: 3000,
  retryAttempts: 3,
  retryDelay: 1000,
  timeout: 5000,
});

await client.connect();

// SET
await client.set("user:123", { name: "John" });
await client.set("temp:data", "value", 5000); // with TTL

// GET
const user = await client.get("user:123");
console.log(user); // { name: "John" }

// DELETE
const deleted = await client.del("user:123");
console.log(deleted); // true

// PING
const alive = await client.ping();
console.log(alive); // true

await client.disconnect();

Client Configuration

Option	Type	Default	Description
host	string	"127.0.0.1"	Server hostname
port	number	3000	Server port
retryAttempts	number	3	Retry on failure
retryDelay	number	1000	Delay between retries (ms)
timeout	number	5000	Request timeout (ms)