From dfd9f2ccb8a86e20401c2d789bd4152786484024 Mon Sep 17 00:00:00 2001 From: Chip Black Date: Fri, 4 Mar 2011 01:16:01 -0800 Subject: [PATCH] Add new documentation --- www/doc/changelog.html | 58 +++++++++++++++++++++++++++++++ www/doc/index.html | 79 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 137 insertions(+) create mode 100644 www/doc/changelog.html diff --git a/www/doc/changelog.html b/www/doc/changelog.html new file mode 100644 index 0000000..b1359f6 --- /dev/null +++ b/www/doc/changelog.html @@ -0,0 +1,58 @@ + + + +Blërg Changelog + + + + +

Changelog

+ +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. + +

Version 1.5 - released Friday, March 4th 2011

+ +

Features Added

+ + +

Bugs Squashed

+ + +

Version 1.0 - released Wednesday, February 9th 2011

+ +

Features Added

+ + +

Bugs Squashed

+ + +

Version 0.ofuckreddit - released Thursday, Jan 13th 2011

+ +

Initial Release

+ + + diff --git a/www/doc/index.html b/www/doc/index.html index 9b2e3df..21982bd 100644 --- a/www/doc/index.html +++ b/www/doc/index.html @@ -36,6 +36,10 @@ C.
  • /get/(user), /get/(user)/(start record)-(end record) - get records for a user
  • /info/(user) - Get information about a user
  • /tag/(#|H|@)(tagname) - Retrieve records containing tags
    • +
  • /subscribe/(user) - Subscribe to a user's updates
    • +
  • /unsubscribe/(user) - Unsubscribe from a user's updates
    • +
  • /feed - Get updates for subscribed users
    • +
  • /feedinfo/(user) - Get subscription status for a user
  • Design @@ -43,6 +47,7 @@ C.
  • Motivation
  • Web App Stack
  • Database
    • +
  • Subscriptions
  • Problems and Future Work
    • @@ -281,6 +286,44 @@ extra author field, like so:

    There is currently no support for getting more than 50 tags, but /tag will probably mutate to work like /get. +

    /subscribe/(user) - Subscribe to a +user's updates

    + +

    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. + +

    /unsubscribe/(user) - Unsubscribe from +a user's updates

    + +

    Identical to /subscribe, but removes the subscription. + +

    /feed - Get updates for subscribed users

    + +

    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. + +

    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. + +

    /feedinfo/(user) - Get subscription +status for a user

    + +

    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: + +

    +{"subscribed":true}
+
    + +

    The value of "subscribed" will be either true or false depending on +the subscription status. +

    Design

    Motivation

    @@ -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? :] +

    Subscriptions

    + +

    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. + +

    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." + +

    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. +

    Problems, Caveats, and Future Work

    Blërg probably doesn't actually work like Twitter because I've never -- 2.34.1