Cache Mate

A Next.js-based cache management API service with pluggable cache drivers.

Table of Contents

• Features
• Supported Cache Drivers
• Environment Configuration
• API Endpoints
  • Cache Operations
    • GET /api/cache/[namespace]/[...key]
    • POST /api/cache/[namespace]/[...key]
    • DELETE /api/cache/[namespace]/[...key]
  • Cache Administration
    • GET /api/cache/admin
    • POST /api/cache/admin
  • Health Check
    • GET /api/healthz
• API Usage Examples
  • Store Data in Cache
  • Retrieve Cached Data
  • Delete Cached Data
  • Get Cache Statistics
  • Cleanup Expired Entries
  • Clear All Cache Entries
• Getting Started
• Development

Features

• Pluggable Cache System: Support for PostgreSQL cache backend via a CACHE_DRIVER environment variable
• PostgreSQL Driver: Production-ready cache storage with automatic table creation and cleanup
• Cache Operations API: RESTful endpoints for cache operations (GET, POST, DELETE)
• Optional Authentication: Token-based authentication (disabled by default for easy development)
• Health Check: System health monitoring endpoint with cache connectivity testing
• Admin Operations: Cache statistics, cleanup, and management endpoints
• TTL Support: Time-to-live functionality for automatic cache expiration
• Namespace Support: Organize cache entries by namespace for better management

Supported Cache Drivers

• PostgreSQL (postgres) - Default driver with persistent storage, TTL support, and automatic cleanup

Environment Configuration

Copy .env.example to .env.local and configure your environment:

cp .env.example .env.local

Cache Driver Configuration

Set the CACHE_DRIVER environment variable to choose your cache backend:

# Use PostgreSQL (default)
CACHE_DRIVER=postgres
POSTGRES_URL=postgresql://username:password@localhost:5432/cache_mate

Authentication Configuration

Authentication is disabled by default. Enable with AUTH_ENABLED=true for production.

# Optional authentication (default: disabled)
AUTH_ENABLED=true
CACHE_AUTH_TOKEN=your_cache_token_here    # For cache operations
ADMIN_AUTH_TOKEN=your_admin_token_here    # For admin + cache operations

When enabled, include token in requests: Authorization: Bearer your_token_here

API Endpoints

Cache Operations

GET /api/cache/[namespace]/[...key]

Retrieve cached data from the specified namespace and key.

Auth: Requires cache or admin token when AUTH_ENABLED=true

Parameters:

• namespace - The cache namespace (string)
• key - The cache key, can be nested (e.g., users/123/profile)

Response:

• 200 - Cache entry found
• 404 - Cache entry not found or expired
• 500 - Internal server error

Example Response (200):

{
  "namespace": "users",
  "key": "john/profile",
  "value": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "retrieved_at": "2025-06-24T10:30:00.000Z"
}

POST /api/cache/[namespace]/[...key]

Store data in cache with optional TTL (time-to-live).

Auth: Requires cache or admin token when AUTH_ENABLED=true

Parameters:

• namespace - The cache namespace (string)
• key - The cache key, can be nested (e.g., users/123/profile)

Request Body:

{
  "value": any,
  "ttl": number (optional, seconds)
}

Response:

• 200 - Data stored successfully
• 400 - Invalid request (missing value)
• 500 - Internal server error

Example Response (200):

{
  "namespace": "users",
  "key": "john/profile",
  "value": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "ttl": 3600,
  "stored_at": "2025-06-24T10:30:00.000Z"
}

DELETE /api/cache/[namespace]/[...key]

Remove cached data from the specified namespace and key.

Auth: Requires cache or admin token when AUTH_ENABLED=true

Parameters:

• namespace - The cache namespace (string)
• key - The cache key, can be nested (e.g., users/123/profile)

Response:

• 200 - Data deleted successfully
• 500 - Internal server error

Example Response (200):

{
  "namespace": "users",
  "key": "john/profile",
  "deleted_at": "2025-06-24T10:30:00.000Z"
}

Cache Administration

GET /api/cache/admin

Get cache statistics and health status.

Auth: Requires admin token when AUTH_ENABLED=true

Response:

• 200 - Statistics retrieved successfully
• 500 - Internal server error

Example Response (200):

{
  "driver": "postgres",
  "status": "healthy",
  "stats": {
    "total": 150,
    "expired": 5,
    "byNamespace": {
      "users": 100,
      "sessions": 45,
      "products": 5
    }
  },
  "timestamp": "2025-06-24T10:30:00.000Z"
}

POST /api/cache/admin

Perform administrative operations on the cache.

Auth: Requires admin token when AUTH_ENABLED=true

Request Body:

{
  "action": "cleanup" | "stats" | "clear"
}

Actions:

• cleanup - Remove expired entries
• stats - Get detailed statistics
• clear - Remove all cache entries

Response:

• 200 - Operation completed successfully
• 400 - Invalid action
• 500 - Internal server error

Example Response for cleanup (200):

{
  "action": "cleanup",
  "status": "completed",
  "timestamp": "2025-06-24T10:30:00.000Z"
}

Example Response for clear (200):

{
  "action": "clear",
  "status": "completed",
  "timestamp": "2025-06-24T10:30:00.000Z"
}

Health Check

GET /api/healthz

Get service health status including cache connectivity.

Auth: No authentication required

Response:

• 200 - Service is healthy
• 503 - Service has issues

Example Response (200):

{
  "status": "ok",
  "uptime": 3600.5,
  "timestamp": 1719225000000,
  "cache": {
    "driver": "postgres",
    "status": "ok"
  }
}

Example Response (503):

{
  "status": "error",
  "uptime": 3600.5,
  "timestamp": 1719225000000,
  "cache": {
    "driver": "postgres",
    "status": "error",
    "error": "Cache connectivity failed"
  }
}

API Usage Examples

Note: Add -H "Authorization: Bearer your_token" when authentication is enabled.

Store Data in Cache

curl -X POST http://localhost:3000/api/cache/users/john/profile \
  -H "Content-Type: application/json" \
  -d '{"value": {"name": "John Doe", "email": "john@example.com"}, "ttl": 3600}'

Retrieve Cached Data

curl http://localhost:3000/api/cache/users/john/profile

Delete Cached Data

curl -X DELETE http://localhost:3000/api/cache/users/john/profile

Get Cache Statistics

curl http://localhost:3000/api/cache/admin

Cleanup Expired Entries

curl -X POST http://localhost:3000/api/cache/admin \
  -H "Content-Type: application/json" \
  -d '{"action": "cleanup"}'

Clear All Cache Entries

curl -X POST http://localhost:3000/api/cache/admin \
  -H "Content-Type: application/json" \
  -d '{"action": "clear"}'

Health Check

curl http://localhost:3000/api/healthz

Getting Started

Install dependencies and run the development server:

npm install
npm run dev

The API will be available at http://localhost:3000.

Development

npm run dev    # Start development server with Turbopack
npm run build  # Build for production
npm run start  # Start production server
npm run lint   # Run ESLint