doc/distributed-comments.txt

   1                                                                 V. Wagner
   2                                                                  March,2008
   3
   4         Distributed Blog Commenting Prototcol
   5
   6 Status of this Memo
   7
   8         I just write it. If considerable interest appear, we might submit it
   9         to the IETF as RFC draft
  10
  11 Copyright
  12
  13         Copyright (c) by Victor B. Wagner, 2008
  14
  15 Abstract
  16
  17         This document describes a protocol which can be used by different
  18         blog sites and web-based RSS aggregators to exchange the comments,
  19         made by users to the blog entries either originating on this site
  20         or recieved from other sites.
  21
  22
  23 1   Introduction
  24
  25 1.1 Purpose of protocol
  26
  27         Some blog sites are more like discussion forums. They allow reader
  28         to comment on blog entries identifying themselfes using some
  29         identity such as OpenID. If it is quite possible to distribute blog
  30         entries to other (mirror) sites using protocols like RSS/Atom feeds,
  31         to distribute load and improve availability of particular blog,
  32         there is no way to allow users to make comments on mirror site and
  33         distribute this comments to all other copies of same blog.
  34
  35         Proposed protocol closes this gap.
  36
  37 1.2 Requrements
  38
  39     Sites participating in this protocol should be able to serve http
  40         request [HTTP] and send those.
  41
  42 1.3 Terminology
  43
  44    The capitalized key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
  45    "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
  46    "OPTIONAL" in this document are to be interpreted as described in BCP
  47    14, RFC 2119 [TERMS].
  48
  49 2  Protocol overview
  50
  51 2.1 Basic terms definition
  52
  53 2.1.1 BLOG
  54
  55         Blog or weblog is a web resource typically consisting of series of
  56         messages (POSTS) which appear on the blog web-page starting from
  57         most recent one. Each blog post can have separate web page, but it
  58         is guaranteed, that by visiting well-known and constant blog URL
  59         any HTTP-client would get most recent post first.
  60         Typically web page on this URL contain some special links which
  61         point to RSS feed of the posts, author information (FOAF) open-id
  62         server which confirms blog owner identity etc. For the purposes of
  63         this protocol blog is identified by this URL.
  64
  65
  66 2.1.2 User
  67
  68     User is an entity which can prove  identity to at least to one of
  69         the servers. This server can confirm this identity to other servers
  70         with OpenID or simular means. So, comments made by the user carry
  71         user identity verified by the server either directly or indirectly
  72         via another server.
  73
  74 2.1.3 Comment
  75
  76         Piece of textual information associated with some post in the
  77         particular blog and, may be with another comment to the same post.
  78
  79 2.2 Required comment properties
  80
  81         Each comment in the system which support  this protocol MUST  have
  82         following proprerties:
  83
  84 2.2.1 Comment text
  85
  86         Fragment of the text which MAY contain some XHTML markup, including
  87         references  to other web resourses, including another comments,
  88         blogs or blog posts.
  89
  90 2.2.2 Globally unique identifier
  91
  92         Globaly unique identifier is created by site where comment was
  93         originally posted. It MUST contain hostname of the originating site
  94         and some string which ensures uniqueness among other comments
  95         originatig to this site
  96
  97 2.2.3 Blog, where comment was posted to
  98
  99         Original URL of blog where comment belong
 100
 101 2.2.4 Blog post where comment was posted to
 102
 103     Permanent URL of blog post on its originating site. This URLs
 104         are always included into RSS/Atom feeds, so any mirror site would
 105         have no problem determining this URL
 106
 107 2.2.5 Original posting date
 108
 109         Timestamp with precision of second when comment is posted
 110
 111         Also comments might have following OPTIONAL properities
 112
 113 2.2.6 Author
 114
 115         URL of verified user identitity of user, who submitted this comment.
 116         If idenitity was provided via OpenID or similar protocol, it MUST
 117         have
 118         form of URL. If user authenticated on the site, where comment was
 119         submitted, directly it SHOULD be OpenID URL which would prove  identity
 120         of this user to other sites.
 121
 122         Sites participating in this protocol MAY allow anonymous comments.
 123         If comment is anonymous, Author property MUST be omitted from
 124         this comment.
 125
 126 2.2.7 Modification time
 127
 128         If comment was changed after its initial submission, it MUST contain
 129         additional timestamp specifying last change date. Servers conforming
 130         to this  protocol SHOULD allow comment author to change comments.
 131
 132         There is one special case - deletion of comments. Either comment
 133         author or owner of blog,
 134         i.e. user with same identity as blog url SHOULD be able to delete
 135         any comments in his blog.
 136
 137 2.2.8 Reference to parent comment
 138
 139         If site allows to comment on another comment in the blog entry, not
 140         only blog entry itself, unique identificator of parent comment
 141         SHOULD be recorded as comment property. If this proprerty is
 142         absent, any server, recieving this comment, SHOULD assume that it is
 143         made on blog entry itself.
 144
 145 3. Comment exchange protocol
 146
 147 3.1     URL structure
 148
 149         Any site participating in this protocol should provide following
 150         web resouces:
 151
 152 3.1.1. Blog list
 153
 154         Page which lists blogs, which can be commented on this site.
 155         This page lists all blogs either originated on this site or
 156         retrieved and cached from other sites.
 157
 158         This page should have content type text/plain and list blog URLs
 159         one per line
 160
 161 3.1.2. Comment list
 162
 163         If URL consisting of BLOG list URL, slash ("/") and blog URL is
 164         requested via HTTP GET method, it should return text/plain list of
 165         recent comments (most recent first) in the form
 166
 167                 timestamp whitespace comment-id
 168
 169         one per line, where timestamp is an integer number of seconds since
 170         Unix epoch (1-1-1970 00:00 GMT).
 171         If this URL is requested with skip=number parameter (i.e. appended
 172         with question mark, workd skip equal sign and number), it should
 173         return list of more earlier comments.
 174
 175 3.1.3 Comments itself
 176
 177         If URL described in 3.1.2 is requested via POST method and POST
 178         request body has content type text/plain and consists of list of
 179         comment identifiers, separated by
 180         newlines, it should return text/xml data containing specified
 181         comments using XML schema described in the section 4 of this
 182         document.
 183
 184         Comments MAY be ordered either earliest first or in order listed in
 185         the request.
 186
 187         Any conforming implementation sending the request SHOULD send
 188         identifiers of requested comments from earliest to latest.
 189
 190 3.1.4 Posting notification
 191
 192         Conforming implementation should understand request to the URL 3.1.1
 193         either by POST by or GET method,
 194         which contains parameter notify=blog-URL. This request means that
 195         site sending this request wants to notify this site that it have new
 196         comments on the specified blog.
 197
 198         If blog-URL doesn't belong to this site, it MAY respond to this
 199         request with 406 (Not Acceptable) HTTP response code.
 200
 201         Otherwise it should respond with 200 response and immediately
 202         initiate procedure of recieving comment from the site which sent
 203         request.
 204
 205         Conforming implementation SHOULD send notify requests only if
 206         comment was posted on the site to the blog originating on the site
 207         where request is sent, unless it is behind firewall or proxy. In
 208         this case it MAY send such requests for each blog commented on it
 209         to some relay site, if permitted by the relay site administrator.
 210
 211         If notifying site is behind NAT or firewall and connection cannot to
 212         it cannot be stablished, reverse protocol described in section 3.3.3
 213         could be used.
 214
 215
 216 3.2 Declaring support of this protocol
 217
 218 3.2.1 Declaring support in the protocol on the blog page
 219
 220         Each site which supports this protocol SHOULD add link tag to its
 221         blog pages with rel="comment-exchange" and href pointing to URL,
 222         described in the section 3.1.1.
 223
 224 3.2.2 Declaring protocol URL during comment exchange.
 225
 226         Each site which performs comment exchange procedure should provide
 227         its peers means to retrieve comments from it. This is done by adding
 228         custom HTTP header X-Comment-Exchange-URL to all requests to
 229         protocol pages. This header should contain URL of page described in
 230         3.1.1, and host name in this URL MUST resolve to the same IP address
 231         request is made from.
 232
 233
 234 3.3. Connect exchange procedure
 235
 236 3.3.1 Procedure initiation.
 237
 238         Site supporting this protocol SHOULD check presense of link
 239         rel=comment-exchange on all sites it retrieves blog entries via
 240         RSS/Atom. If this link is found it MAY periodically initiate comment
 241         exchange procedure with these sites.
 242
 243         It also MAY initiate this procedure with any site which was known
 244         to initiate this protocol with it before.
 245
 246         If 404 NOT FOUND HTTP response code is recieved when requesting URL
 247         3.1.1, this site SHOULD be removed from the list of polled sites
 248         until either explicit user interaction or first protocol session
 249         initiated from that site.
 250
 251 3.3.2 Normal (PULL) procedure
 252
 253         1. Site requests lists of blogs from URL 3.1.1
 254         2. For each blog interesting to this site, list of available
 255                 comments is requesed from URL 3.1.2. If site has reasonable
 256                 expectations that it can miss some comments, which are not
 257                 listed on first page, request page multiple times using skip
 258                 parameter.
 259         3. Prepare list of missing comments, earliest first and send it to
 260           site
 261         4. Repeat steps 2,3 for each blog copy of each is carried on this
 262           site.
 263
 264 3.3.3. Reverse (PUSH) procedure
 265
 266         1. Send notify request (3.1.4) using POST method with list of
 267         available comments as specified in 3.1.3 in the POST body.
 268
 269         2. Recieve list of requested comments as  text/plain resoponse to
 270         the POST request.
 271
 272         3. Send XML stream of the comments using POST request to the same
 273         URL with content type text/xml
 274
 275         4. Repeat steps 1-4 for each blog comments for which are to be
 276         pushed to this site.
 277
 278         when using PUSH method X-Comment-Exchange-URL header MAY be omitted.
 279
 280
 281 4. Comment stream XML format
 282
 283 4.1 Comment stream XML document have <comment-stream> root node.
 284         Contents of this stream is sequence of <comment> element.
 285 4.2     Comment element should contain following elements
 286         <comment-id>unique-identifier</comment-id>
 287         <blog>blog-URL</blog>
 288         <post>post-URL</post>
 289         <parent-id>unique-identifier</parent-id>
 290         <author>url</author>
 291         <posted>date</posted>
 292         <edited>date</edited>
 293         <body>text of comment with optional XHTML markup</body>
 294         Some of this elements are OPTIONAL (see section ).
 295
 296 4.3. Comment deletion
 297         If comment element contain element
 298         <deleted/> and <author> element contains either same  URL as
 299         original comment with same <comment-id> or URL of blog, comment
 300         belongs to,
 301         comment with given identifier should be removed
 302         from the user's view, but deletion notice retained in the database
 303         in case that same
 304         comment would be sent from other site which didn't have recieved
 305         deletion message yet.
 306
 307
 308 4.4     Banning user from commenting.
 309         If comment element contains element
 310         <ban set="1">identity URL</ban> instead of body or along with
 311         <delete> element,
 312         and comment author identity is same as
 313         identity of blog it belongs to, it means that user with given
 314         identity should no more be allowed to comment in this blog, and any
 315         existing comments from this user should not be offered to other
 316         sites, requesting comments using this protocol, even if these
 317         comments has earlier timestamp than ban notice.
 318
 319 4.5 Removing ban
 320
 321         If comment element contain element
 322         <ban set="0">identity URL</ban> than previously set ban should be
 323         removed.
 324
 325 5. Full Copyright Statement
 326         Would write it if document is to be submitted to the IETF as RFC
 327         draft
 328
 329
 330
 331