Skip to content
Start a REST-like API service for your Redis database, without writing a single line of code
Go Dockerfile Shell
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Integration test against Redis 3.2.12 & 2.8.23 as well Nov 10, 2019
conn Code cleaning & reduce single function complexity (#8) Oct 28, 2019
types New Feature: list keys which match pattern to expose, by logical DB (#12 Nov 4, 2019
.gitignore 1.0.0-alpha Oct 15, 2019
.travis.yml Add Travis CI; Add badges for build status, coverage and license (#3) Oct 21, 2019
Dockerfile Update Dockerfile to allow run command easilier with 'docker run' Nov 9, 2019
Jenkinsfile 1.0.0-alpha Oct 15, 2019
LICENSE 1.0.0-alpha Oct 15, 2019
README.md Refine authentication documentation Nov 10, 2019
actions.go Support API Key Authentication; Integration Test against Different Re… Nov 9, 2019
actions_test.go Support API Key Authentication; Integration Test against Different Re… Nov 9, 2019
codecov.yml Refactor to more properly handle Addr to serve (#6) Oct 22, 2019
constants.go Allow running Rediseen in daemon mode (#7) Oct 27, 2019
go.mod Support API Key Authentication; Integration Test against Different Re… Nov 9, 2019
go.sum Support API Key Authentication; Integration Test against Different Re… Nov 9, 2019
prepare_dev_env.sh Support API Key Authentication; Integration Test against Different Re… Nov 9, 2019
rediseen.go Support API Key Authentication; Integration Test against Different Re… Nov 9, 2019
rediseen_test.go Add goreport badge; Address golint minor issues Oct 27, 2019
services.go Support API Key Authentication; Integration Test against Different Re… Nov 9, 2019
services_test.go Support API Key Authentication; Integration Test against Different Re… Nov 9, 2019
version.go Update Dockerfile to allow run command easilier with 'docker run' Nov 9, 2019

README.md

Rediseen

"Latest Release" action travis codecov License Go Report Card

Start a REST-like API service for your Redis database, without writing a single line of code.

(Inspired by sandman2, and built on shoulder of go-redis/redis )

drawing

1. Quick Start

Let's assume that your Redis database URI is redis://:@localhost:6379, and you want to expose keys with prefix key: in logical database 0.

1.1 Quick Start with Homebrew

# Install using Homebrew
brew install XD-DENG/rediseen/rediseen

# Configuration
export REDISEEN_REDIS_URI="redis://:@localhost:6379"
export REDISEEN_DB_EXPOSED=0
export REDISEEN_KEY_PATTERN_EXPOSED="^key:([0-9a-z]+)"

# Start the service
rediseen start

Now you should be able to query against your Redis database, like http://localhost:8000/0 or http://localhost:8000/0/key:1 (say you have keys key:1 (string) and key:2 (hash) set in your logical DB 0). Sample responses follow below

GET /0

{
    "count": 2,
    "total": 2,
    "keys": [
        {
            "key": "key:1",
            "type": "string"
        },
        {
            "key": "key:2",
            "type": "hash"
        }
    ]
}
GET /0/key:1

{
    "type": "string",
    "value": "rediseen"
}

For more details, please refer to the rest of this README documentation.

1.2 Quick Start with Docker

docker run \
    -e REDISEEN_REDIS_URI="redis://:@redis_host:6379" \
    -e REDISEEN_DB_EXPOSED=0 \
    -e REDISEEN_KEY_PATTERN_EXPOSED="^key:([0-9a-z]+)" \
    -p 8000:8000 \
    xddeng/rediseen:latest

Please note:

  • REDISEEN_HOST has already been set to 0.0.0.0 in Dockerfile, in order to expose the service outside the container.
  • redis_host in REDISEEN_REDIS_URI should not be something like "localhost" or "127.0.0.1" even if you are running Redis on the same Docker host, because "localhost" here would refer to docker runtime itself.
  • You can choose the image tag among latest (latest release version), nightly (latest code in master branch), unstable (latest dev branch), and release tags (like 1.1.1. Check Docker Hub/xddeng/rediseen for full tag list)

2. Usage

2.1 How to Install

You can choose to install Rediseen either using Homebrew or from source.

  • Install Using Homebrew

You can use Homebrew to install Rediseen, no matte you are using macOS, or Linux/ Windows 10 Subsystem for Linux (how to install Homebrew).

brew install XD-DENG/rediseen/rediseen

rediseen help
  • Build from source (with Go 1.12 or above installed)

You can also build Rediseen from source.

git clone https://github.com/XD-DENG/rediseen.git
cd rediseen
go build . # executable binary file "rediseen" will be created

./rediseen help

2.2 How to Configure

Configuration is done via environment variables.

Item Description Remark
REDISEEN_REDIS_URI URI of your Redis database, e.g. redis://:@localhost:6379 Compulsory
REDISEEN_HOST Host of the service. Host will be localhost if REDISEEN_HOST is not explicitly set. Set to 0.0.0.0 if you want to expose your service to the world. Optional
REDISEEN_PORT Port of the service. Default port is 8000. Optional
REDISEEN_DB_EXPOSED Redis logical database(s) to expose.

E.g., 0, 0;3;9, 0-9;15, or * (expose all logical databases)
Compulsory
REDISEEN_KEY_PATTERN_EXPOSED Regular expression pattern, representing the name pattern of keys that you intend to expose.

For example, user:([0-9a-z/.]+)|^info:([0-9a-z/.]+) exposes keys like user:1, user:x1, testuser:1, info:1, etc.
REDISEEN_KEY_PATTERN_EXPOSE_ALL If you intend to expose all your keys, set REDISEEN_KEY_PATTERN_EXPOSE_ALL to true. REDISEEN_KEY_PATTERN_EXPOSED can only be empty (or not set) if you have set REDISEEN_KEY_PATTERN_EXPOSE_ALL to true.
REDISEEN_API_KEY API Key for authentication. Authentication is only enabled when REDISEEN_API_KEY is set and is not "".

Once it is set, client must add the API key into HTTP header as field X-API-KEY in order to access the API.

Note this authentication is only considered secure if used together with other security mechanisms such as HTTPS/SSL [1].
Optional
REDISEEN_TEST_MODE Set to true to skip Redis connection validation for unit tests. For Dev Only

2.3 How to Start the Service

Run command below,

rediseen start

Then you can access the service at

  • http://<your server address>:<REDISEEN_PORT>/<redis DB>
  • http://<your server address>:<REDISEEN_PORT>/<redis DB>/<key>
  • http://<your server address>:<REDISEEN_PORT>/<redis DB>/<key>/<index or value or member>

If you would like to run the service in daemon mode, apply flag -d.

# run service in daemon mode
rediseen -d start

# stop service running in daemon mode
rediseen stop

2.4 How to Consume the Service

2.4.1 /<redis DB>

This endpoint will return response in which you can get

  • the number of keys which are exposed
  • keys exposed and their types (only up to 1000 keys will be showed)

A sample response follows below

{
    "count": 3,
    "total": 3,
    "keys": [
        {
            "key": "key:1",
            "type": "string"
        },
        {
            "key": "key:5",
            "type": "hash"
        },
        {
            "key": "key:100",
            "type": "zset"
        }
    ]
}

2.4.2 /<redis DB>/<key>

Data Type Underlying Redis Command
STRING GET(key)
LIST LRANGE(key, 0, -1)
SET SMEMBERS(key)
HASH HGETALL(key)
ZSET ZRANGE(key, 0, -1)

2.4.3 /<redis DB>/<key>/<index or value or member>

Data Type Usage Return Value
STRING /<redis DB>/<key>/<index> <index>-th character in the string
LIST /<redis DB>/<key>/<index> <index>-th element in the list
SET /<redis DB>/<key>/<member> if <member> is member of the set
HASH /<redis DB>/<key>/<field> value of hash <field> in the hash
ZSET /<redis DB>/<key>/<memeber> index of <member> in the sorted set

3. Authentication

API Key authentication is supported.

To enable authentication, simply set environment variable REDISEEN_API_KEY and the value would be the key. Once it's set, client will have to add the API key as X-API-KEY in their HTTP header in order to access anything meaningful, otherwise 401 error (Unauthorized) will be returned.

For example,

export REDISEEN_REDIS_URI="redis://:@localhost:6379"
export REDISEEN_DB_EXPOSED=0
export REDISEEN_KEY_PATTERN_EXPOSED="^key:([0-9a-z]+)"
export REDISEEN_API_KEY="demo_key" # Set REDISEEN_API_KEY to enforce API Key Authentication

# Start the service and run in background
rediseen -d start

# REJECTED: No X-API-KEY is given in HTTP header
curl -s http://localhost:8000/0 | jq
{
  "error": "unauthorized"
}

# REJECTED: Wrong X-API-KEY is given in HTTP header
curl -s -H "X-API-KEY: wrong_key" http://localhost:8000/0 | jq
{
  "error": "unauthorized"
}

# ACCEPTED: Correct X-API-KEY is given in HTTP header
curl -s -H "X-API-KEY: demo_key" http://localhost:8000/0 | jq
{
  "count": 1,
  "total": 1,
  "keys": [
    {
      "key": "key:1",
      "type": "rediseen"
    }
  ]
}

4. License

Apache-2.0

5. Reference

[1] https://swagger.io/docs/specification/authentication/api-keys/

You can’t perform that action at this time.