Add more error checking in auth

[blerg.git] / www / doc / index.html

diff --git a/www/doc/index.html b/www/doc/index.html
index 5a170e6..e98ef47 100644 (file)
--- a/www/doc/index.html
+++ b/www/doc/index.html
@@ -40,6 +40,7 @@ C.
       <li><a href="#api_unsubscribe">/unsubscribe/(user) - Unsubscribe from a user's updates</a></li>
       <li><a href="#api_feed">/feed - Get updates for subscribed users</a></li>
       <li><a href="#api_feedinfo">/feedinfo, /feedinfo/(user) - Get subscription status</a></li>
       <li><a href="#api_unsubscribe">/unsubscribe/(user) - Unsubscribe from a user's updates</a></li>
       <li><a href="#api_feed">/feed - Get updates for subscribed users</a></li>
       <li><a href="#api_feedinfo">/feedinfo, /feedinfo/(user) - Get subscription status</a></li>

+      <li><a href="#api_passwd">/passwd - Change a user's password</a></li>

     </ul>
   </li>
   <li><a href="#design">Design</a>
     </ul>
   </li>
   <li><a href="#design">Design</a>


@@ -111,6 +112,9 @@ made individually as well, if you, for example, don't want to install
 the prerequisites for <code>blerg.httpd</code> or
 <code>blerg.cgi</code>.
 
 the prerequisites for <code>blerg.httpd</code> or
 <code>blerg.cgi</code>.
 

+<p><strong>NOTE</strong>: blerg.httpd is deprecated and will not be
+updated with new features.
+

 <h3><a name="installing">Installing</a></h3>
 
 <p>While it's not strictly required, Blërg will be easier to set up if
 <h3><a name="installing">Installing</a></h3>
 
 <p>While it's not strictly required, Blërg will be easier to set up if


@@ -340,6 +344,19 @@ interested in.  The server will respond with a simple JSON object:
 <p>The value of "subscribed" will be either true or false depending on
 the subscription status.
 
 <p>The value of "subscribed" will be either true or false depending on
 the subscription status.
 

+<h3><a name="api_passwd">/passwd</a> - Change a user's password</a></h3>
+
+<p>POST to /passwd with a <code>username</code> parameter and an auth
+cookie, plus <code>password</code> and <code>new_password</code>
+parameters to change the user's password.  For extra protection,
+changing a password requires sending the user's current password in the
+<code>password</code> parameter.  If authentication is successful and
+the password matches, the user's password is set to
+<code>new_password</code> and the server responds with JSON success.
+
+If the password doesn't match, or one of <code>password</code> or
+<code>new_password</code> are missing, the server returns JSON failure.
+

 <h2><a name="design">Design</a></h2>
 
 <h3><a name="motivation">Motivation</a></h3>
 <h2><a name="design">Design</a></h2>
 
 <h3><a name="motivation">Motivation</a></h3>


@@ -397,14 +414,15 @@ make the layers more efficient, or reduce the number of layers.
 </table>
 
 <p>Blërg does both by smashing the last two or three layers into one
 </table>
 
 <p>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 &mdash; 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 &mdash; 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.

 
 <p>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
 
 <p>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


@@ -423,24 +441,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
 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 &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:

 
 <table class="statistics">
 <tr><td>maximum record size</td><td>65535 bytes</td></tr>
 
 <table class="statistics">
 <tr><td>maximum record size</td><td>65535 bytes</td></tr>

-<tr><td>maximum number of records per database</td><td>2<sup>64</sup> - 1 bytes</td></tr>
+<tr><td>maximum number of records per database</td><td>2<sup>64</sup> - 1</td></tr>

 <tr><td>maximum number of tags per record</td><td>1024</td></tr>
 <table>
 
 <p>So as not to create grossly huge and unwieldy data files, the
 database layer splits data and index files into many "segments"
 <tr><td>maximum number of tags per record</td><td>1024</td></tr>
 <table>
 
 <p>So as not to create grossly huge and unwieldy data files, the
 database layer splits data and index files into many "segments"

-containing at most 64K entries each.  Those of you doing some quick math
-in your heads may note that this could cause a problem on 32-bit
-machines &mdash; if a full segment contains entries of the maximum
-length, you'll have to mmap 4GB (32-bit Linux gives each process only
-3GB of virtual address space).  Right now, 32-bit users should change
+containing at most 64K entries each.  Those of you doing some quick
+mental math may note that this could cause a problem on 32-bit machines
+&mdash; if a full segment contains entries of the maximum length, you'll
+have to mmap 4GB (32-bit Linux gives each process only 3GB of virtual
+address space).  Right now, 32-bit users should change

 <code>RECORDS_PER_SEGMENT</code> in <code>config.h</code> to something
 lower like 32768.  In the future, I might do something smart like not
 mmaping the whole fracking file.
 <code>RECORDS_PER_SEGMENT</code> in <code>config.h</code> to something
 lower like 32768.  In the future, I might do something smart like not
 mmaping the whole fracking file.