Redis REST Proxy

Redis REST Proxy exposes Redis functionality via a RESTful HTTP API. Ideal for client running in a serverless or edge environments where TCP/IP may not be available.

Table of Contents

• Features
• Compatibility Notice
• Quick Start
  • Docker
  • Manual Installation
• Upstash Client Usage
• REST API Usage
  • Health Check
  • Generic Command via URL Path
  • Generic Command Using JSON Body
  • Pipeline Batch Commands
  • Multi-exec (Transaction) Batch Commands
  • Base64 Encoded Responses
• Contributing
• Issues
• License

Features

• RESTful Interface: Converts HTTP requests into Redis commands.
• Serverless Friendly: Connects applications running in serverless environments to Redis.
• High Performance: Built with Bun for fast and efficient operation.
• Upstash Redis client compatible.

Compatibility Notice

This proxy is tested with the Upstash Redis JavaScript Client and aims to maintain basic compatibility with Upstash Redis services.

Supported

• Pipeline & multi-exec transactions
• Base64 encoding/decoding
• Basic Redis commands
• Authentication via bearer token

Not Supported

• Upstash-specific extensions

---

Quick Start

Docker

docker pull ghcr.io/nielspeter/redis-rest-proxy:latest
docker run -p 3000:3000 \
  -e AUTH_TOKEN="MY_SUPER_SECRET_TOKEN" \
  -e REDIS_HOST="your.redis.host" \
  ghcr.io/nielspeter/redis-rest-proxy

Manual Installation

git clone https://github.com/nielspeter/redis-rest-proxy.git
cd redis-rest-proxy
bun install
bun run start

---

Upstash Client Usage

import { Redis } from '@upstash/redis';

const redis = new Redis({
  url: 'http://localhost:3000',
  token: 'MY_SUPER_SECRET_TOKEN',
});

// Works like Upstash Redis!
await redis.set('key', 'value');
const result = await redis.get('key');

---

REST API Usage

Authorization: Use the Authorization header with the value Bearer YOUR_AUTH_TOKEN to authenticate requests.

Command Parsing: Commands can be provided via:

• URL path segments (e.g., /get/mykey)
• A JSON array in the request body (e.g., ["set", "mykey", "hello"])

Additionally, URL query parameters (except _token) are appended as extra command arguments.

Response Encoding: If the header Upstash-Encoding or Encoding is set to base64, string responses (except "OK") will be encoded in Base64. The encoding is applied recursively to arrays and objects.

Example Usage with cURL

Below are some examples demonstrating how to use the REST API. In these examples, the server is assumed to be running at http://localhost:3000 and the auth token is MY_SUPER_SECRET_TOKEN.

1. Health Check

Check that the proxy is healthy and that Redis responds:

curl -H "Authorization: Bearer MY_SUPER_SECRET_TOKEN" http://localhost:3000/health

Expected response:

{
  "status": "healthy",
  "redis": "PONG"
}

2. Generic Command via URL Path

For a simple command like PING, you can issue the command directly in the URL:

curl -H "Authorization: Bearer MY_SUPER_SECRET_TOKEN" http://localhost:3000/set/mykey/hello

Expected Response:

{
  "result": "Ok"
}

3. Generic Command Using JSON Body

Send commands as a JSON array in the POST body. For example, to set a key:

curl -X POST \
  -H "Authorization: Bearer MY_SUPER_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '["set", "mykey", "hello"]' \
  http://localhost:3000

Expected Response:

{
  "result": "OK"
}

4. Pipeline Batch Commands

Execute multiple commands in one request using the /pipeline endpoint. For example, to set a key and then get its value:

curl -X POST \
  -H "Authorization: Bearer MY_SUPER_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[["set", "key1", "value1"], ["get", "key1"]]' \
  http://localhost:3000/pipeline

Expected Response:

[{ "result": "OK" }, { "result": "value1" }]

5. Multi‑exec (Transaction) Batch Commands

Run commands transactionally with the /multi-exec endpoint. For example, to increment a counter and then get its value:

curl -X POST \
  -H "Authorization: Bearer MY_SUPER_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[["incr", "counter"], ["get", "counter"]]' \
  http://localhost:3000/multi-exec

Expected Response:

[{ "result": 1 }, { "result": "1" }]

6. Base64 Encoded Responses

Request Base64 encoding by adding the Encoding: base64 header. For example, to get a key’s value in Base64:

curl -H "Authorization: Bearer MY_SUPER_SECRET_TOKEN" \
  -H "Encoding: base64" \
  http://localhost:3000/get/mykey

Expected Response:

{
  "result": "aGVsbG8=" // (Base64 for "hello", if that's the value)
}

---

Contributing

We welcome contributions to the project! Please follow these steps to contribute:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Make your changes and commit them with clear and concise messages.
4. Push your changes to your fork.
5. Submit a pull request to the main repository.

Issues

Report Issue

License

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