]> www.wagner.pp.ru Git - oss/stilllife.git/blob - doc/distributed-comments.txt
*** empty log message ***
[oss/stilllife.git] / 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