About

A very simple web server providing an HTTP interface to Redis. It uses hiredis, jansson, libevent, and http-parser.

Webdis depends on libevent-dev. You can install it on Ubuntu by typing sudo apt-get install libevent-dev or on OS X by typing brew install libevent.

Try in Docker

Clone the repository and open a terminal in the webdis directory, then run:

Features

• GET and POST are supported, as well as PUT for file uploads.
• JSON output by default, optional JSONP parameter (?jsonp=myFunction or ?callback=myFunction).
• Raw Redis 2.0 protocol output with .raw suffix
• MessagePack output with .msg suffix
• HTTP 1.1 pipelining (70,000 http requests per second on a desktop Linux machine.)
• Multi-threaded server, configurable number of worker threads.
• WebSocket support (Currently using the “hixie-76” specification).
• 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.
• Custom Content-Type using a pre-defined file extension, or with ?type=some/thing.
• URL-encoded parameters for binary data or slashes and question marks. For instance, %2f is decoded as / but not used as a command separator.
• Logs, with a configurable verbosity.
• Cross-origin requests, usable with XMLHttpRequest2 (Cross-Origin Resource Sharing - CORS).
• File upload with PUT.
• With the JSON output, the return value of INFO is parsed and transformed into an object.
• Optional daemonize: set "daemonize": true and "pidfile": "/var/run/webdis.pid" in webdis.json.
• Default root object: Add "default_root": "/GET/index.html" in webdis.json to substitute the request to / with a Redis request.
• HTTP request limit with http_max_request_size (in bytes, set to 128MB by default).
• Database selection in the URL, using e.g. /7/GET/key to run the command on DB 7.

Ideas, TODO...

• Add better support for PUT, DELETE, HEAD, OPTIONS? How? For which commands?
  • This could be done using a “strict mode” with a table of commands and the verbs that can/must be used with each command. Strict mode would be optional, configurable. How would webdis know of new commands remains to be determined.
• MULTI/EXEC/DISCARD/WATCH are disabled at the moment; find a way to use them.
• 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 (maybe for some commands only?). What should the response be? 504 Gateway Timeout? 503 Service Unavailable?
• Multi-server support, using consistent hashing.
• SSL?
  • Not sure if this is such a good idea.
• SPDY?
  • SPDY is mostly useful for parallel fetches. Not sure if it would make sense for Webdis.
• Send your ideas using the github tracker, on twitter @yowgi or by mail to n.favrefelix@gmail.com.

HTTP error codes

• Unknown HTTP verb: 405 Method Not Allowed.
• Redis is unreachable: 503 Service Unavailable.
• Matching ETag sent using If-None-Match: 304 Not Modified.
• Could also be used:
  • Timeout on the redis side: 503 Service Unavailable.
  • Missing key: 404 Not Found.
  • Unauthorized command (disabled in config file): 403 Forbidden.

Command format

The URI /COMMAND/arg0/arg1/.../argN.ext executes the command on Redis and returns the response to the client. GET, POST, and PUT are supported:

• GET /COMMAND/arg0/.../argN.ext
• POST / with COMMAND/arg0/.../argN in the HTTP body.
• PUT /COMMAND/arg0.../argN-1 with argN in the HTTP body (see section on file uploads.)

.ext is an optional extension; it is not read as part of the last argument but only represents the output format. Several formats are available (see below).

Special characters: / and . have special meanings, / separates arguments and . changes the Content-Type. They can be replaced by %2f and %2e, respectively.

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:

ACLs are interpreted in order, later authorizations superseding earlier ones if a client matches several. The special value "*" matches all commands.

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:

RAW output

This is the raw output of Redis; enable it with the .raw suffix.

Custom content-type

Several content-types are available:

• .json for application/json (this is the default Content-Type).
• .msg for application/x-msgpack. See http://msgpack.org/ for the specs.
• .txt for text/plain
• .html for text/html
• xhtml for application/xhtml+xml
• xml for text/xml
• .png for image/png
• jpg or jpeg for image/jpeg
• Any other with the ?type=anything/youwant query string.
• Add a custom separator for list responses with ?sep=, query string.

File upload

Webdis supports file upload using HTTP PUT. The command URI is slightly different, as the last argument is taken from the HTTP body.
For example: instead of /SET/key/value, the URI becomes /SET/key and the value is the entirety of the body. This works for other commands such as LPUSH, etc.

Uploading a binary file to webdis:

The file was uploaded and re-downloaded properly: it has the same hash and the content-type was set properly thanks to the .png extension.

WebSockets

Webdis supports WebSocket clients implementing dixie-76.
Web Sockets are supported with the following formats, selected by the connection URL:

• JSON (on / or /.json)
• Raw Redis wire protocol (on /.raw)

Example:

This produces the following output:

Pub/Sub with chunked transfer encoding

Webdis exposes Redis PUB/SUB channels to HTTP clients, forwarding messages in the channel as they are published by Redis. This is done using chunked transfer encoding.

Example using XMLHttpRequest:

Publish messages to redis to see output similar to the following: