X-Git-Url: http://git.bytex64.net/?a=blobdiff_plain;f=www%2Fdoc%2Findex.html;h=25f6519f08cbce3d88ef46bdcf7d06a1572cb4d3;hb=efce7ece23d93ca5274ceb1e2bd3579c480d999a;hp=9a85061c81821c1ec30277e749b258d6497ae406;hpb=93ac2090dfae4917cfdd3324d35b60756f5dd8b3;p=blerg.git diff --git a/www/doc/index.html b/www/doc/index.html index 9a85061..25f6519 100644 --- a/www/doc/index.html +++ b/www/doc/index.html @@ -3,6 +3,7 @@
I know I'm gonna get shit for not using an autoconf-based system, but -I really didn't want to spend time figuring it out. 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 @@ -95,11 +106,11 @@ more portable, I'd be happy to hear them.
At this point, it should be gravy. Type 'make' and in a few seconds,
-you should have blerg.httpd
, blerg.cgi
,
-rss.cgi
, and blergtool
. Each of those can be
-made individually as well, if you, for example, don't want to install
-the prerequisites for blerg.httpd
or
-blerg.cgi
.
+you should have blerg.cgi
, blergtool
, and
+blerglatest
.
+
+
NOTE: blerg.httpd is deprecated and will not be +updated with new features.
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. - -
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
.
+domains (though you can probably get around it these days with Cross-origin
+ resource sharing).
-
Copy the files in www/ to the root of your web server. Copy
blerg.cgi
to your web server. Included in www-configs/ is
@@ -136,10 +138,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
+
There is an optional RSS cgi (aux/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. @@ -165,21 +204,34 @@ 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), or maybe a 502 Bad Gateway if you have it behind another web server.
All usernames must be 32 characters or less. Usernames must contain
-only the ASCII characters 0-9, A-Z, a-z, underscore (_), period (.),
-hyphen (-), single quote ('), and space ( ). Passwords can be at most
-64 bytes, and have no limits on characters (but beware: if you have a
-null in the middle, it will stop checking there because I use
-strncmp(3)
to compare).
+only the ASCII characters 0-9, A-Z, a-z, underscore (_), and hyphen (-).
+Passwords can be at most 64 bytes, and have no limits on characters (but
+beware: if you have a null in the middle, it will stop checking there
+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, hyphen (-), and underscore (_). +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.
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.
author
field, like so:
There is currently no support for getting more than 50 tags, but /tag will probably mutate to work like /get. +
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 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. + +
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: + +
+{ + "feed_new": 3, + "mentioned": false +} ++ +
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} ++ +
The value of "subscribed" will be either true or false depending on +the subscription status. + +
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.
+
+
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
.
+
+
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.
+
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 @@ -362,28 +508,27 @@ until after I wrote Blërg. :)
I was impressed by varnish's design, so I decided 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 one or more data and -index files, and a metadata file. When a database is opened, only the -metadata is actually read (currently a single 64-bit integer keeping -track of the last record id). The data and index files are memory +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. 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 |