www/js/blerg.js and
change baseURL at the top as well as a number of other self-references
-in that file and www/index.html. The CGI version should
-work fine this way, but the HTTP version will require the request to be
-rewritten, as it expects to be serving from the root.
+in that file and www/index.html.
You cannot serve the database and client from different domains (i.e., yoursite.com vs othersite.net, or even foo.yoursite.com and bar.yoursite.com). This is a requirement of the web browser — the same origin policy will not allow an AJAX request to travel across -domains. +domains (though you can probably get around it these days with Cross-origin + resource sharing). -
Right now, blerg.httpd doesn't serve any static assets,
-so you're going to have to put it behind a real webserver like apache,
-lighttpd, nginx, or similar. Set the document root to the www
-directory, then proxy /info, /create, /login, /logout, /get, /tag, and
-/put to blerg.httpd. You can change the port blerg.httpd
-listens on in config.h.
-
-
Copy the files in www/ to the root of your web server. Copy
blerg.cgi to your web server. Included in www-configs/ is
@@ -150,10 +148,47 @@ a .htaccess file for Apache that will rewrite the URLs. If you need to
call the CGI something other than blerg.cgi, the .htaccess
file will need to be modified.
+
Nginx can't run CGI directly, and there's currently no FastCGI +version of Blërg, so you will have to run it under some kind of CGI to +FastCGI gateway, like the one described here on the nginx wiki. This +pretty much destroys the performance of Blërg, but it's all we've got +right now. +
There is an optional RSS cgi (rss.cgi) that will serve
RSS feeds for users. Install this like blerg.cgi above.
+As of 1.9.0, this is a perl FastCGI script, so you will have to make
+sure the perl libraries are available to it. A good way of doing that
+is to install to an environment directory, as described below.
+
+
The Makefile has support for installing Blërg into a directory that
+includes tools, libraries, and configuration snippets for shell and web
+servers. Use it as make install-environment
+ ENV_DIR=<directory>. Under <directory>/etc will be
+a shell script that sets environment variables, and configuration
+snippets for nginx and apache to do the same. This should make it
+somewhat easier to use Blërg in a self-contained way.
+
+
For example, this will install Blërg to an environment directory +inside your home directory: + +
user@devhost:~/blerg$ make install-environment ENV_DIR=$HOME/blerg-env +... +user@devhost:~/blerg$ . ~/blerg-env/etc/env.sh ++ +
Then, you will be able to run tools like blergtool, and
+it will operate on data inside ~/blerg-env/data. Likewise,
+you can include
+/home/user/blerg-env/etc/nginx-fastcgi-vars.conf or
+/home/user/blerg-env/etc/apache-setenv.conf in your
+webserver to make the CGI/FastCGI scripts to the same thing.
{"status": "failure"}
+
{"status": "failure"}
Blërg doesn't currently explain why there is a failure, and I'm not sure it ever will. @@ -179,7 +214,7 @@ I'm not sure it ever will. /get, /tag, or /info), or a 'JSON success' response (for /create, /put, /login, or /logout), which looks like this: -
{"status": "success"}
+
{"status": "success"}
For the CGI backend, you may get a 500 error if something goes wrong.
For the HTTP backend, you'll get nothing (since it will have crashed),
@@ -194,6 +229,20 @@ because I use strncmp(3) to compare).
Tags must be 64 characters or less, and can contain only the ASCII characters 0-9, A-Z, a-z, underscore (_), and hyphen (-). +
As the result of a successful login, the server
+will send back a cookie named auth. This cookie authorizes
+restricted requests, and must be sent for any API endpoint marked authorization, or else you will get a 403 Forbidden
+response. The cookie format looks like:
+
+auth=username/abcdef0123456789abcdef0123456789
+
+That is a username, a forward slash, and 32 hexadecimal digits which denote the
+"token" identifying the session. On logout, the server will invalidate the
+token and expire the cookie.
+
To create a user, POST to /create with username and
@@ -209,24 +258,24 @@ success if the user is created.
respond with JSON failure if the user does not exist or if the password
is incorrect. On success, the server will respond with JSON success,
and will set a cookie named 'auth' that must be sent by the client when
-accessing restricted API functions (/put and /logout).
+accessing restricted API functions (See Authorization above).
POST to /logout with with username, the user to log out,
-along with the auth cookie in a Cookie header. The server will respond
-with JSON failure if the user does not exist or if the auth cookie is
-bad. The server will respond with JSON success after the user is
-successfully logged out.
+
POST to /logout. The server will respond with JSON failure if the +user does not exist or if the request is unauthorized. The server will +respond with JSON success after the user is successfully logged out.
POST to /put with username and data
-parameters, and an auth cookie. The server will respond with JSON
-failure if the auth cookie is bad, if the user doesn't exist, or if
-data contains more than 65535 bytes after URL
-decoding. The server will respond with JSON success after the record is
-successfully added.
+
POST to /put with a data parameter. The server will
+respond with JSON failure if the request is unauthorized, if the user
+doesn't exist, or if data contains more than 65535 bytes
+after URL decoding. The server will respond with JSON success
+after the record is successfully added.
POST to /subscribe/(user) with a username parameter and
-an auth cookie, where (user) is the user whose updates you wish to
-subscribe to. The server will respond with JSON failure if the auth
-cookie is bad or if the user doesn't exist. The server will respond
-with JSON success after the subscription is successfully registered.
-
-
Identical to /subscribe, but removes the subscription. +
POST to /subscribe/(user) with a subscribed parameter
+that is either "true" or "false", indicating whether (user) should be
+subscribed to or not. The server will respond with JSON failure if the
+request is unauthorized or if the user doesn't exist. The server will
+respond with JSON success after the subscription request is successfully
+registered.
POST to /feed, with a username parameter and an auth
cookie. The server will respond with a JSON list of the last 50 updates
from all subscribed users, in reverse chronological order. Fetching
-/feed resets the new message count returned from /feedinfo.
+/feed does not reset the new message count returned from /status. To do
+that, look at POST /status.
NOTE: subscription notifications are only stored while subscriptions are active. Any records inserted before or after a subscription is active will not show up in /feed. -
POST to /feedinfo with a username parameter and an auth
-cookie to get general information about your subscribed feeds.
-Currently, this only tells you how many new records there are since the
-last time /feed was fetched. The server will respond with a JSON
-object:
+
GET to /status to get information about your account. It tells you +the number of new subscription records since the last time the +subscription counter was reset, and a flag for whether the account was +mentioned since the last time the mention flag was cleared. The server +will respond with a JSON object:
-{"new":3}
+{
+ "feed_new": 3,
+ "mentioned": false
+}
-POST to /feedinfo/(user) with a username parameter and
-an auth cookie, where (user) is a user whose subscription status you are
-interested in. The server will respond with a simple JSON object:
+
POST to /status with a clear parameter that is either
+"feed" or "mentioned" to reset either the subscription counter or the
+mention flag, respectively. There is not currently a way to clear both
+with a single request. The server will respond with JSON success.
+
+
GET to /status/(user) to get subscription information for a +particular user. The server will respond with a simple JSON object:
{"subscribed":true}
@@ -345,18 +401,42 @@ interested in. The server will respond with a simple JSON object:
the subscription status.
/passwd - Change a user's password
+authorization
-POST to /passwd with a username parameter and an auth
-cookie, plus password and new_password
-parameters to change the user's password. For extra protection,
-changing a password requires sending the user's current password in the
-password parameter. If authentication is successful and
-the password matches, the user's password is set to
-new_password and the server responds with JSON success.
+
POST to /passwd with password and
+new_password parameters to change the user's password. For
+extra protection, changing a password requires sending the user's
+current password in the password parameter. If
+authentication is successful and the password matches, the user's
+password is set to new_password and the server responds
+with JSON success.
If the password doesn't match, or one of password or
new_password are missing, the server returns JSON failure.
+
Libraries
+
+C
+
+Most of Blërg's core functionality is packaged in a static library
+called blerg.a. It's not designed to be public or
+installed with `make install-environment`, but it should be relatively
+straightforward to use it in C programs. Look at the headers under the
+database directory.
+
+
A secondary library called blerg_auth.a handles the
+authentication layer of Blërg. To use it, look at
+common/auth.h.
+
+
Perl
+
+As of 1.9.0, Blërg includes a perl library called
+Blerg::Database. It wraps the core and authentication
+functionality in a perlish interface. The module has its own POD
+documentation, which you can read with your favorite POD reader, from
+the manual installed in an environment directory, or in HTML here.
+
Design
Motivation