5.6 KiB
About
A very simple web server providing an HTTP interface to Redis. It uses hiredis, jansson and libevent.
make clean all ./webdis & curl http://127.0.0.1:7379/SET/hello/world → {"SET":[true,"OK"]} curl http://127.0.0.1:7379/GET/hello → {"GET":"world"} curl -d "GET/hello" http://127.0.0.1:7379/ → {"GET":"world"}
Features
- GET and POST are supported.
- JSON output by default, optional JSONP parameter.
- Raw Redis 2.0 protocol output with
?format=raw
- HTTP 1.1 pipelining (50,000 http requests per second on a desktop Linux machine.)
- Connects to Redis using a TCP or UNIX socket.
- Restricted commands by IP range (CIDR subnet + mask) or HTTP Basic Auth, returning 403 errors.
- Possible Redis authentication in the config file.
- Pub/Sub using
Transfer-Encoding: chunked
, works with JSONP as well. Webdis can be used as a Comet server. - Drop privileges on startup.
- For
GET
commands:- MIME type in a second key with
/GET/k?typeKey=type-k
. This will transform theGET
request intoMGET
and fetch bothk
andtype-k
. Iftype-k
is a string, it will be used as Content-Type in the response. If the key doesn't exist or isn't a string,binary/octet-stream
is used instead. - Custom MIME type with
?type=text/plain
(or any other MIME type).
- MIME type in a second key with
- URL-encoded parameters for binary data or slashes. For instance,
%2f
is decoded as/
but not used as a command separator.
Ideas, TODO...
- Support PUT, DELETE, HEAD, OPTIONS? How? For which commands?
- MULTI/EXEC/DISCARD/WATCH are disabled at the moment; find a way to use them.
- Add logs.
- Support POST of raw Redis protocol data, and execute the whole thing. This could be useful for MULTI/EXEC transactions.
- Enrich config file:
- Provide timeout (this needs to be added to hiredis first.)
- Multi-server support, using consistent hashing.
- Send your ideas using the github tracker, on twitter @yowgi or by mail to n.favrefelix@gmail.com.
- Add WebSocket support, allow cross-origin XHR.
HTTP error codes
- Unknown HTTP verb: 405 Method Not Allowed
- Redis is unreachable: 503 Service Unavailable
- Could also be used:
- Timeout on the redis side: 503 Service Unavailable (this isn't supported by HiRedis yet).
- Missing key: 404 Not Found
- Unauthorized command (disabled in config file): 403 Forbidden
Command format
The URI /COMMAND/arg0/arg1/.../argN
executes the command on Redis and returns the response to the client. GET and POST are supported:
GET /COMMAND/arg0/.../argN
POST /
withCOMMAND/arg0/.../argN
in the HTTP body.
ACL
Access control is configured in webdis.json
. Each configuration tries to match a client profile according to two criterias:
- CIDR subnet + mask
- HTTP Basic Auth in the format of "user:password".
Each ACL contains two lists of commands, enabled
and disabled
. All commands being enabled by default, it is up to the administrator to disable or re-enable them on a per-profile basis.
Examples:
{ "disabled": ["DEBUG", "FLUSHDB", "FLUSHALL"], }, { "http_basic_auth": "user:password", "disabled": ["DEBUG", "FLUSHDB", "FLUSHALL"], "enabled": ["SET"] }, { "ip": "192.168.10.0/24", "enabled": ["SET"] }, { "http_basic_auth": "user:password", "ip": "192.168.10.0/24", "enabled": ["SET", "DEL"] }
ACLs are interpreted in order, later authorizations superseding earlier ones if a client matches several.
JSON output
JSON is the default output format. Each command returns a JSON object with the command as a key and the result as a value.
Examples:
// string $ curl http://127.0.0.1:7379/GET/y {"GET":"41"} // number $ curl http://127.0.0.1:7379/INCR/y {"INCR":42} // list $ curl http://127.0.0.1:7379/LRANGE/x/0/1 {"LRANGE":["abc","def"]} // status $ curl http://127.0.0.1:7379/TYPE/y {"TYPE":[true,"string"]} // error, which is basically a status $ curl http://127.0.0.1:7379/MAKE-ME-COFFEE {"MAKE-ME-COFFEE":[false,"ERR unknown command 'MAKE-ME-COFFEE'"]} // JSONP callback: $ curl "http://127.0.0.1:7379/TYPE/y?jsonp=myCustomFunction" myCustomFunction({"TYPE":[true,"string"]})
RAW output
This is the raw output of Redis; enable it with ?format=raw
.
// string $ curl http://127.0.0.1:7379/GET/z?format=raw $5 hello // number curl http://127.0.0.1:7379/INCR/a?format=raw :2 // list $ curl http://127.0.0.1:7379/LRANGE/x/0/-1?format=raw *2 $3 abc $3 def // status $ curl http://127.0.0.1:7379/TYPE/y?format=raw +zset // error, which is basically a status $ curl http://127.0.0.1:7379/MAKE-ME-COFFEE?format=raw -ERR unknown command 'MAKE-ME-COFFEE'
Custom content-type
Webdis can serve GET
requests with a custom content-type. There are two ways of doing this; the content-type can be in a key that is fetched with the content, or given as a query string parameter.
Content-Type in parameter:
curl -v "http://127.0.0.1:7379/GET/hello.html?type=text/html" [...] < HTTP/1.1 200 OK < Content-Type: text/html < Date: Mon, 03 Jan 2011 20:43:36 GMT < Content-Length: 137 < <!DOCTYPE html> <html> ... </html>
Content-Type in a separate key:
curl "http://127.0.0.1:7379/SET/hello.type/text%2fhtml" {"SET":[true,"OK"]} curl "http://127.0.0.1:7379/GET/hello.type" {"GET":"text/html"} curl -v "http://127.0.0.1:7379/GET/hello.html?typeKey=hello.type" [...] < HTTP/1.1 200 OK < Content-Type: text/html < Date: Mon, 03 Jan 2011 20:56:43 GMT < Content-Length: 137 < <!DOCTYPE html> <html> ... </html>