Add new documentation v1.5
authorChip Black <bytex64@bytex64.net>
Fri, 4 Mar 2011 09:16:01 +0000 (01:16 -0800)
committerChip Black <bytex64@bytex64.net>
Fri, 4 Mar 2011 09:16:01 +0000 (01:16 -0800)
www/doc/changelog.html [new file with mode: 0644]
www/doc/index.html

diff --git a/www/doc/changelog.html b/www/doc/changelog.html
new file mode 100644 (file)
index 0000000..b1359f6
--- /dev/null
@@ -0,0 +1,58 @@
+<!DOCTYPE html>
+<html>
+<head>
+<title>Blërg Changelog</title>
+<link rel="stylesheet" href="/css/doc.css">
+</head>
+<body>
+
+<h1>Changelog</h1>
+
+The intent of this changelog is to give an overview of the major changes
+and fixes made to Blërg.  For a detailed changelog, see the git log.
+
+<a name="v1.5"><h2>Version 1.5 - released Friday, March 4th 2011</h2>
+
+<h3>Features Added</h3>
+<ul>
+<li>Added "stalking" (follow)</li>
+<li>Added markdown-style headers (lines beginning with #), wiki-style
+headers (lines beginning with =), lists (groups of lines beginning with
+* separated by blank lines), and quoting (lines beginning with &gt;)</li>
+<li>Added permalinks to posts</li>
+<li>Added a new kind of ref tag (@user/N) that links to a specific post,
+as well as a reply link that auto-enters the perma-ref tag into the
+content of your post</li>
+</ul>
+
+<h3>Bugs Squashed</h3>
+<ul>
+<li>Removed the extra whitespace at the end of multi-line posts.</li>
+<li>Fixed paging so that each page is its own URL, which means the back
+button works in more places</li>
+<li>Fixed a number of places where switching views would do nothing</li>
+<li>Allow formatting metachars to be escaped with backslashes</li>
+</ul>
+
+<a name="v1.0"><h2>Version 1.0 - released Wednesday, February 9th 2011</h2>
+
+<h3>Features Added</h3>
+<ul>
+<li>Added recent tags and posts display</li>
+<li>Added a link to see chatter for users other than yourself</li>
+<li>Changed ref/tag link colors to be gray so that they aren't confused
+with hyperlinks</li>
+</ul>
+
+<h3>Bugs Squashed</h3>
+<ul>
+<li>Fixed a few XSS vulnerabilities in regex parsing for urls</li>
+<li>Fixed tag accessibility issues for longer tags</li>
+</ul>
+
+<a name="v0"><h2>Version 0.ofuckreddit - released Thursday, Jan 13th 2011</h2>
+
+<h3>Initial Release</h3>
+
+</body>
+</html>
index 9b2e3df..21982bd 100644 (file)
@@ -36,6 +36,10 @@ C.
       <li><a href="#api_get">/get/(user), /get/(user)/(start record)-(end record) - get records for a user</a></li>
       <li><a href="#api_info">/info/(user) - Get information about a user</a></li>
       <li><a href="#api_tag">/tag/(#|H|@)(tagname) - Retrieve records containing tags</a></li>
+      <li><a href="#api_subscribe">/subscribe/(user) - Subscribe to a user's updates</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/(user) - Get subscription status for a user</a></li>
     </ul>
   </li>
   <li><a href="#design">Design</a>
@@ -43,6 +47,7 @@ C.
       <li><a href="#motivation">Motivation</a></li>
       <li><a href="#web_app_stack">Web App Stack</a></li>
       <li><a href="#database">Database</a></li>
+      <li><a href="#subscriptions">Subscriptions</a></li>
       <li><a href="#problems">Problems and Future Work</a></li>
     </ul>
   </li>
@@ -281,6 +286,44 @@ extra <code>author</code> field, like so:
 <p>There is currently no support for getting more than 50 tags, but /tag
 will probably mutate to work like /get.
 
+<h3><a name="api_subscribe">/subscribe/(user)</a> - Subscribe to a
+user's updates</a></h3>
+
+<p>POST to /subscribe/(user) with a <code>username</code> 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.
+
+<h3><a name="api_unsubscribe">/unsubscribe/(user)</a> - Unsubscribe from
+a user's updates</h3>
+
+<p>Identical to /subscribe, but removes the subscription.
+
+<h3><a name="api_feed">/feed</a> - Get updates for subscribed users</h3>
+
+<p>POST to /feed, with a <code>username</code> 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.
+
+<p>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.
+
+<h3><a name="api_feedinfo">/feedinfo/(user)</a> - Get subscription
+status for a user</a></h3>
+
+<p>POST to /feedinfo/(user) with a <code>username</code> 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:
+
+<pre>
+{"subscribed":true}
+</pre>
+
+<p>The value of "subscribed" will be either true or false depending on
+the subscription status.
+
 <h2><a name="design">Design</a></h2>
 
 <h3><a name="motivation">Motivation</a></h3>
@@ -425,6 +468,42 @@ disk before returning success.  This should make Blërg extremely fast,
 and totally unreliable in a crash.  But that's the way you want it,
 right? :]
 
+<h3><a name="subscriptions">Subscriptions</a></h3>
+
+<p>When I first started thinking about the idea of subscriptions, I
+immediately came up with the naïve solution: keep a list of users to
+which users are subscribed, then when you want to get updates, iterate
+over the list and find the last entries for each user.  And that would
+work, but it's kind of costly in terms of disk I/O.  I have to visit
+each user in the list, retrieve their last few entries, and store them
+somewhere else to be sorted later.  And worse, that computation has to
+be done every time a user checks their feed. As the number of users and
+subscriptions grows, that will become a problem.
+
+<p>So instead, I thought about it the other way around. Instead of doing
+all the work when the request is received, Blërg tries to do as much as
+possible by "pushing" updates to subscribed users.  You can think of it
+kind of like a mail system.  When a user posts new content, a
+notification is "sent" out to each of that user's subscribers.  Later,
+when the subscribers want to see what's new, they simply check their
+mailbox.  Checking your mailbox is usually a lot more efficient than
+going around and checking everyone's records yourself, even with the
+overhead of the "mailman."
+
+<p>The "mailbox" is a subscription index, which is identical to a tag
+index, but is a per-user construct.  When a user posts a new record, a
+subscription index record is written for every subscriber.  It's a
+similar amount of I/O as the naïve version above, but the important
+difference is that it's only done once.  Retrieving records for accounts
+you're subscribed to is then as simple as reading your subscription
+index and reading the associated records.  This is hopefully less I/O
+than the naïve version, since you're reading, at most, as many accounts
+as you have records in the last N entries of your subscription index,
+instead of all of them.  And as an added bonus, since subscription index
+records are added as posts are created, the subscription index is
+automatically sorted by time!  To support this "mail" architecture, we
+also keep a list of subscribers and subscrib...ees in each account.
+
 <h3><a name="problems">Problems, Caveats, and Future Work</a></h3>
 
 <p>Blërg probably doesn't actually work like Twitter because I've never