TODOs and docs and openmicroblogging spec

Moved around a few TODOs.

Linked to docs in the foot menu better.

Added a specification for the openmicroblogging standard.

darcs-hash:20080522172006-84dde-060372ec90444faf0e3453229cfd33aceaf28e4a.gz

2 files changed, 347 insertions, 20 deletions

diff --git a/doc/TODO b/doc/TODO
index 146a364c4..5f9db9675 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -46,9 +46,9 @@
 + fix layout of textarea
 + make notices into "big links"
 + RSS 1.0 feeds of a user's notices
-- RSS 1.0 feeds of a user's notices + friends
++ RSS 1.0 feeds of a user's notices + friends
 + RSS 1.0 dump of a user's notices
-- RSS 1.0 feed of all public notices
++ RSS 1.0 feed of all public notices
 - FOAF dump for user
 - license on showstream
 - license on shownotice
@@ -62,46 +62,50 @@
 - add a next page link to showstream
 - add a next page link to public
 - add a next page link to all
-- source link in footer menu
-- public stream link in top menu
++ source link in footer menu
++ public stream link in top menu
+- about doc
+- help doc
+- privacy doc
+- source doc
 - AGPL notification
 - gettext
 - pretty URLs
++ dump, fix, undump database
+- subscribe remote
+- add subscriber remote
+- send remote notice
+- receive remote notice
 - release 0.2
 - Automatically linkify URLs in notices
-- RDF dump of entire site
+- tinyurl-ification of URLs
 - use only canonical email addresses
 - license per notice
 - allow mixed-case usernames
 - allow non-latin usernames
 - store canonical username for comparison and fetch
-- site logo
 - set Last-Modified
 - XML sitemap generation
+- themes
 - theme per site
 - theme per profile
 - email confirmation for registration
 - change cookie handling for anon users to be more cache-friendly
-- subscribe remote
-- add subscriber remote
-- send remote notice
-- receive remote notice
-- confirmation email
-- tinyurl-ification of URLs
 - jQuery for as much as possible
-- themes
-- RDFa for stream pages
-- RDFa for subscriber pages
-- RDFa for subscribed pages
-- plugins and hooks
 - content negotiation for interface language
 - content negotiation for content type
 - content negotiation for encoding
 - content negotiation for charset
 - If-Modified-Since support
 - Vary
-- delete a notice
+- site logo
 - release 0.3
+- RDF dump of entire site
+- delete a notice
+- plugins and hooks
+- RDFa for stream pages
+- RDFa for subscriber pages
+- RDFa for subscribed pages
 - @ messages
 - # tags
 - L: location
@@ -124,8 +128,8 @@
 - release 0.5
 - Twitter-compatible API
 - Pownce-compatible API
-- include twitter subscriptions
-- include Pownce subscriptions
+- include twitter subscriptions (push and pull)
+- include Pownce subscriptions (push and pull)
 - privacy
 - Wrap DB_DataObject with memcached caching layer
 - login throttle to prevent brute-force attacks
diff --git a/doc/openlisten.txt b/doc/openlisten.txt
new file mode 100644
index 000000000..b3208c24f
--- /dev/null
+++ b/doc/openlisten.txt
@@ -0,0 +1,323 @@
+===============================
+OpenMicroBlogging specification
+===============================
+
+Version 0.1
+
+Purpose
+=======
+
+To allow users of one microblogging service to publish notices to
+users of another service, given the other users' permission.
+
+Enabling technologies
+=====================
+
+Depends on OAuth 1.0, YADIS 1.0.
+
+We piggy-back additional information onto these protocols to pass
+microblogging information back and forth.
+
+Terminology
+===========
+
+microblogging service
+    undefined.
+user
+    undefined.
+listen
+    to allow a remote service to send notices to the user's local
+    service on a remote user's behalf.
+listener
+    the person listening.
+listenee
+    the user sending notices.
+remote service
+    the listenee's service.
+local service
+    the listener's service.
+profile URL
+    "home" URL for the listener, typically their profile page on a
+    microblogging site.
+nickname
+    An alphanumeric short name for a person, 1-64 characters.
+identifier URI
+    A globally unique and unchanging identifying URI for a user.
+    Need not be an URL. [*]_
+notice URI
+    A unique and unchanging identifier for a notice. Need not be an
+    URL. [*]_
+    
+.. [*] May be the profile URL, if it's defined not to change or be
+   re-used. The profile URL of some services includes the nickname,
+   and some let the user change his/her nickname. This user's profile
+   URL may change from 'http://example.net/~john' to 
+   'http://example.net/~johnsmith' A tag URI, like 
+   'tag:example.net,2008:user:1' may be more appropriate here.
+.. [*] IWBNI the notice URI is used everywhere the notice is
+   published; for example, in any RSS feeds.
+
+Initiation
+==========
+
+The user submits their profile URL to the remote service somehow --
+for example, with an HTML form on the remote service's Web site. 
+
+Discovery
+=========
+
+The remote service recovers a YADIS document from the profile URL, as
+described in YADIS 1.0.
+
+The remote service looks for a service of this type:
+
+    http://openmicroblogging.org/protocol/0.1
+
+The service must include the following 5 URLs. [*]_
+
+omb:requestToken
+    Request Token URL, as in OAuth 1.0
+
+omb:userAuthorization
+    User Authorization URL, as in OAuth 1.0
+
+omb:accessToken
+    Access Token URL, as in OAuth 1.0
+
+omb:postNotice
+    Post Notice URL, as defined below.
+
+omb:updateProfile
+    Update Profile URL, as defined below.
+
+It must also include the following URI:
+
+omb:identifier
+    identifier URI for the user with this profile URL.
+    
+Here, omb: is the namespace prefix for:
+
+    http://openmicroblogging.org/xmlns/0.1
+
+The YADIS URI defined for the service can be ignored.
+
+.. [*] I decided to use a separate namespace with 5 elements to enable
+   having different providers for general OAuth and specific OµB. A
+   future version of this document may have a mode that allows a
+   single URL defined in the <URI> element with an additional URL
+   parameter like 'action=requesttoken', 'action=userauthorization' or
+   something similar. But that simplifies the YADIS doc at the expense
+   of the rest of the protocol.
+
+Authorization
+=============
+
+The remote service must go through the OAuth 1.0 dance to get
+authorization to post notices and update profiles.
+
+In all OAuth, the consumer key should be blank (''), unless the remote
+server and local service have negotiated another key. Such negotiation
+is out-of-scope for this document, and we assume an "open" network of
+microblogging services. But if you want to have that kind of network,
+do it with this key.
+
+The remote service MUST do OAuth for every new listener, regardless of
+whether they've already received authorization for posting to the
+given postNotice URL. See `Posting a Notice`_ below.
+
+Request token
+-------------
+
+The remote service uses the defined requestToken URL to get a request
+token.
+
+In the request token HTTP request, the remote service MUST send the
+following additional parameter(s):
+
+omb_version
+    'http://openmicroblogging.org/protocol/0.1'
+omb_listener
+    The identifier URI for the listener.
+
+In the results for the request token request, the local service MUST
+send the following additional parameters:
+
+omb_version
+    'http://openmicroblogging.org/protocol/0.1'
+ 
+User authorization
+------------------
+
+In requesting user authorization, the remote service must send the
+following parameters:
+
+omb_version
+    'http://openmicroblogging.org/protocol/0.1'.
+omb_listener
+    The identifier URI for the listener.
+omb_listenee
+    The identifier URI for the listenee.
+omb_listenee_profile
+    The profile URL of the listenee.
+omb_listenee_nickname
+    The nickname of the listenee.
+omb_listenee_license
+    The default license URL for the listenee's stream. Typically the
+    URL of a Creative Commons license, with the Attribution license
+    being heavily encouraged. CC0 quitclaim also pretty good. The
+    local service MAY reject listenees if their licenses are
+    incompatible with the service.
+    
+The remote service should send as many of the following parameters as
+possible. This will help the user decide if they really want to allow
+the listening to happen, and allow the local service to store a copy
+of the listenee's profile.
+
+omb_listenee_fullname
+    The full name of the listenee. Up to 255 chars.
+omb_listenee_homepage
+    The home page of the listenee (may be distinct from the profile
+    URL).
+omb_listenee_bio
+    A brief biography of the listenee; less than 140 chars.
+omb_listenee_location
+    Physical location of the listenee; less that 255 chars. No fixed
+    structure, but "Locality, Region, Country" or "Locality, Country"
+    or "Locality, Region" recommended.
+omb_listenee_avatar
+    URL of a 96px by 96px image in PNG, GIF or JPEG format representing
+    the listenee.
+
+The local service, in a successful response, must return the
+following additional parameters:
+
+omb_version
+    'http://openmicroblogging.org/protocol/0.1'.
+omb_listener_nickname
+    A nickname for the listener.
+omb_listener_profile
+    The profile URL for the listener, possibly cleaned up or
+    canonicalized.
+    
+It should return as many of the following as possible:
+
+omb_listener_fullname
+    The full name of the listener. Up to 255 chars.
+omb_listener_homepage
+    The home page of the listener (may be distinct from the profile
+    URL).
+omb_listener_bio
+    A brief biography of the listener; less than 140 chars.
+omb_listener_location
+    Physical location of the listener; less that 255 chars. No fixed
+    structure, but "Locality, Region, Country" or "Locality, Country"
+    or "Locality, Region" recommended.
+omb_listener_avatar
+    URL of a 96px by 96px image in PNG, GIF or JPEG format representing
+    the listener.
+
+This will allow the remote service to display information about the
+listener in the listenee's "listeners" or "subscribers" list.
+
+Posting a Notice
+================
+
+To post a notice to the local service, the remote service sends an HTTP
+POST message to the postNotice URL discovered above. The message must
+use OAuth authorization. The message must also include the following
+parameters:
+
+omb_version
+    'http://openmicroblogging.org/protocol/0.1'.
+omb_listenee
+    The identifier URI for the listenee.
+omb_notice
+    The notice URI.
+omb_notice_content
+    The content of the notice. No maximum, but 140 chars is recommended.
+    
+The message may include the following parameters:
+
+omb_notice_url
+    The URL of the notice, if the notice is retrievable.
+omb_notice_license
+    The URL of the license for the notice, if different from the
+    listenee's default license.
+omb_seealso
+    URL of additional content for the notice; for example, an image,
+    video, or audio file.
+omb_seealso_disposition
+    One of 'link' or 'inline', to recommend how the extra data should
+    be shown. Default 'link'.
+omb_seealso_mediatype
+    Internet Media Type of the see-also data. Advisory, probably
+    shouldn't be trusted.
+omb_seealso_license
+    License for the attached data. May be distinct from the notice's
+    license (if they're passing along someone else's content).
+    
+The local service should include the following parameters in its
+response:
+
+omb_version
+    'http://openmicroblogging.org/protocol/0.1'.
+
+The local service makes no guarantees about the delivery of the notice
+to anyone.
+
+The remote service SHOULD NOT send a message with the same notice URL
+to the same postNotice URL more than once. [2]_ If the request returns
+a 403 Unauthorized message, the remote service SHOULD NOT post
+messages to the same URL again with the same listenee, until another
+listener has gone through the OAuth dance. [3]_
+
+.. [2] A half-assed optimization. A local service may have a lot of
+   listeners listening to the same listenee. It would be pointless to
+   have the remote service post the same notice 100 times to the same
+   service. However, if the local service wants fine-grained control,
+   it can have a different postNotice URL for each listener.
+.. [3] If there's one postNotice URL per listener, the 403 message
+   means the listener has told the local service not to allow posting
+   any more ("unsubscribed"). If there's one postNotice URL per local
+   service, it means that the count of listeners has dropped to 0.
+
+Updating a profile
+==================
+
+If the listenee's profile information changes, the remote service MAY
+send an HTTP POST message to to the updateProfile URL to tell the
+local service about the change.
+
+The message must use OAuth authorization. The message must also
+include the following parameters:
+
+omb_version
+    'http://openmicroblogging.org/protocol/0.1'.
+omb_listenee
+    The identifier URI for the listenee.
+    
+The message may include any of the following parameters:
+
+omb_listenee_profile
+    The profile URL of the listenee.
+omb_listenee_nickname
+    The nickname of the listenee.
+omb_listenee_license
+    The default license URL for the listenee's stream. A change in the
+    default license only applies to future notices; notices previous
+    to the update SHOULD be treated as under the old license.
+omb_listener_fullname
+    The full name of the listener. Up to 255 chars.
+omb_listener_homepage
+    The home page of the listener.
+omb_listener_bio
+    A brief biography of the listener; less than 140 chars.
+omb_listener_location
+    Physical location of the listener; less that 255 chars.
+omb_listener_avatar
+    URL of a 96px by 96px image in PNG, GIF or JPEG format representing
+    the listener.
+
+Missing parameters should not be construed to mean that the profile
+field has been blanked. The remote service MUST set the parameter to
+an empty string to show that the field is blank.