There is now an experimental autoconf build system. If you run
-add-autoconf, it'll do the magic and create a
-configure script that'll do the familiar things. If I ever
-get around to distributing source packages, you should find that this
-has already been done.
-
-
If you'd rather stick with the manual system, you should edit libs.mk -and put in the paths where you can find headers and libraries for the -above requirements. +
Edit libs.mk and put in the paths where you can find headers and +libraries for the above requirements.
Also, further apologies to BSD folks — I've probably committed
several unconscious Linux-isms. It would not surprise me if the
@@ -123,26 +123,17 @@ reason, it's better to use a subdomain (i.e., blerg.yoursite.com is
easier than yoursite.com/blerg/). If you do want to put it in a
subdirectory, you will have to modify 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 +141,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 +207,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 +222,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 +251,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 +394,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
@@ -414,14 +487,15 @@ make the layers more efficient, or reduce the number of layers.
Blërg does both by smashing the last two or three layers into one
-application. Blërg can be run as either a standalone web server, or as
-a CGI (FastCGI support is planned, but I just don't care right now).
-Less waste, more throughput. As a consequence of this, the entirety of
-the application logic that the user sees is implemented in the client
-app in Javascript. That's why all the URLs have #'s — the page is
-loaded once and switched on the fly to show different views, further
-reducing load on the server. Even parsing hash tags and URLs are done
-in client JS.
+application. Blërg can be run as either a standalone web server
+(currently deprecated because maintaining two versions is hard), or as a
+CGI (FastCGI support is planned, but I just don't care right now). Less
+waste, more throughput. As a consequence of this, the entirety of the
+application logic that the user sees is implemented in the client app in
+Javascript. That's why all the URLs have #'s — the page is loaded
+once and switched on the fly to show different views, further reducing
+load on the server. Even parsing hash tags and URLs are done in client
+JS.
The API is simple and pragmatic. It's not entirely RESTful, but is
rather designed to work well with web-based front-ends. Client data is
@@ -440,24 +514,24 @@ early in the design process that I'd try out mmaped I/O. Each user in
Blërg has their own database, which consists of a metdata file, and one
or more data and index files. The data and index files are memory
mapped, which hopefully makes things more efficient by letting the OS
-handle when to read from disk (or maybe not &mdash I haven't benchmarked
-it). The index files are preallocated because I believe it's more
-efficient than writing to it 40 bytes at a time as records are added.
-The database's limits are reasonable:
+handle when to read from disk (or maybe not — I haven't
+benchmarked it). The index files are preallocated because I believe
+it's more efficient than writing to it 40 bytes at a time as records are
+added. The database's limits are reasonable:
| maximum record size | 65535 bytes |
| maximum number of records per database | 264 - 1 bytes |
| maximum number of records per database | 264 - 1 |
| maximum number of tags per record | 1024 |