Show last authors
1 {{toc depth="3" numbered="true"/}}
2
3 This page is to follow implementation of the [[ActivityPub protocol >>https://www.w3.org/TR/activitypub/]]inside XWiki and to document the different design decisions.
4
5 == Design choices ==
6
7 === JSON library ===
8
9 The protocol is using JSON-LD to define the various requests body. However JSON-LD is fully compliant with JSON libraries, and we don't need here to use the specifity of JSON-LD. So for now we decided to use Jackson to serialize/parse the requests.
10
11 === HTTP Answers ===
12
13 The protocol doesn't define precisely what should be the answers of the POST request made. So we decided to use the following rule when everything's fine:
14
15 * answer a 202 Accepted, in case of request that needs to be processed later on by the user (e.g. a follow request) with the activity in the body (useful to get the produced ID)
16 * answer a 201 Created, in case of request that leads to a Create activity (e.g. posting a Note) or posted directly with the Create activity, with the activity in the body
17 * answer a 200 OK, in other cases with the activity in the body
18
19 === Persistency ===
20
21 All JSON produced by an instance of AP are immediately stored in a DB: the ID is generated after the storing since IDs are URI that must serve the resource they identify.
22
23 We chose to also store the information that are needed by AP but coming from other servers in AP 1.2 for two reasons:
24
25 ~1. it avoids using too many HTTP requests since the info are immediately available in the DB
26
27 2. it allows to be able to resolve information if an instance is not available right now, which can avoid errors
28
29 === Follow Activity ===
30
31 It is not explicitely explained in the protocol if a follow activity should be public or not.
32 The only information we have is that each actor contains a list of followers/following and
33
34 > The following [or follower] collection [...] MAY be filtered on privileges of an authenticated user or as appropriate when no authentication is given.
35
36 I consider for now that only the logged user can see her/his followings/followers. Any anonymous user will get an empty list.
37
38 Now according to the documentation every actor has an outbox which
39
40 > contains activities the user has published, subject to the ability of the requestor to retrieve the activity (that is, the contents of the outbox are filtered by the permissions of the person reading it).
41
42 So I consider that the follow activity is immediately published (even if it has not been accepted yet), but only the logged user can retrieve it.
43
44 === URLs ===
45
46
47 ActivityPub and more globally ActivityStreams specify that each object is defined by an ID which is also an URI. Moreover, most of the attributes in the JSON answers can be the actual objects or a link (the ID) towards those objects.
48 Now ActivityPub protocol entirely relies on performing GET/POST on Actors' Inbox/Outbox, which are some specific kind of ActivityStreams object.
49
50 I hesitated to use a dedicated URL scheme for actions to perform on Inbox/Outbox, but I finally decided to only use a single URL scheme for all entities manipulated by AP:
51 {{code}}xwiki-server/entity/id{{/code}}
52
53 where **entity** can be: an activity (e.g. Follow) or an object (e.g. a Note or even an Inbox).
54 The ID can be different given the kind of entity: in case of an Inbox, it would be the User reference of that Inbox for example.
55 In case of another type of object it might an UUID provided by the persistency API.
56
57
58 == WebFinger ==
59
60
61 We provide an implementation of WebFinger resolution to help using AP in XWiki.
62
63 The idea of WebFinger is to be able to use "simple" identifier that will be resolved automatically, so for example using {{code}}[email protected]{{/code}} will automatically trigger a request to {{code}}domain.com{{/code}} to find the user {{code}}foo{{/code}}.
64 That being said, we now have several usecases that we need to be able to handle for XWiki, and we want to be able to handle them with WebFinger:
65
66 1. find an XWiki user from the main wiki
67 2. find an XWiki user from a subwiki
68 3. find a Wiki (main or sub) from the main wiki
69 4. find a Wiki (main or sub) from a subwiki
70
71 The usecase 4 might look strange, but we can imagine that {{code}}domain.com{{/code}} actually points to a subwiki and not the main wiki. And we might want to be able to follow a sibling subwiki, or its main wiki.
72 I ordered the usecases by what I consider is their priority and how likely they will happen.
73
74 Before providing a scheme to solve those usecases, let's sum up some rules regarding XWiki and WebFinger names:
75 - WebFinger resolution name must be a valid URI so {{code}}xwiki:[email protected]{{/code}} is not supported
76 - XWiki User name currently does not accept symbol other than underscore, so dots {{code}}.{{/code}} and @ are not supported
77 - XWiki Wiki name currently cannot be {{code}}xwiki{{/code}} since it's the default main wiki name
78 - XWiki User name might be {{code}}xwiki{{/code}}
79
80 We propose the following resolution name scheme:
81 {{code}}resolutionName = identifier '@' host
82 identifier = username
83 || username '.' subwiki
84 || wikiname '.xwiki'{{/code}}
85
86 Examples:
87
88 {{box title="Example 1"}}
89 resolutionName: {{code}}[email protected]{{/code}}
90 Assumption: {{code}}domain.com{{/code}} points to the main wiki
91
92 Resolution:
93 - the XWiki User named {{code}}foo{{/code}} is looked in the main wiki.
94 - if the user is not found a 404 is answered.
95 {{/box}}
96
97 {{box title="Example 2"}}
98 resolutionName: {{code}}[email protected]{{/code}}
99 Assumption: {{code}}domain.com{{/code}} points to the main wiki
100
101 Resolution:
102 - A subwiki {{code}}bar{{/code}} is looked for, if not found a 404 is answered
103 - if the subwiki is found, the user {{code}}foo{{/code}} is looked for, by following the user policy of the subwiki
104 - if the user is not found a 404 is answered.
105 {{/box}}
106
107 {{box title="Example 3"}}
108 resolutionName: {{code}}[email protected]{{/code}}
109 Assumption: {{code}}domain.com{{/code}} points to the sub wiki {{code}}bar{{/code}}
110
111 Resolution:
112 - the user {{code}}foo{{/code}} is looked for, by following the user policy of the subwiki
113 - if the user is not found a 404 is answered.
114 {{/box}}
115
116 {{box title="Example 4"}}
117 resolutionName: {{code}}[email protected]{{/code}}
118 Assumption: {{code}}domain.com{{/code}} points to the sub wiki {{code}}bar{{/code}}
119
120 Resolution:
121 - the user {{code}}foo{{/code}} is looked for, by following the user policy of the subwiki
122 - if the user is not found a 404 is answered.
123 {{/box}}
124
125 {{box title="Example 5"}}
126 resolutionName: {{code}}[email protected]{{/code}}
127 Assumption: {{code}}domain.com{{/code}} points to the sub wiki {{code}}bar{{/code}}
128
129 Resolution:
130 - A subwiki {{code}}buz{{/code}} is looked for, if not found a 404 is answered
131 - the user {{code}}foo{{/code}} is looked for, by following the user policy of the subwiki
132 - if the user is not found a 404 is answered.
133 {{/box}}
134
135 {{box title="Example 6"}}
136 resolutionName: {{code}}[email protected]{{/code}}
137 Assumption: {{code}}domain.com{{/code}} points to the main wiki
138
139 Resolution:
140 - the XWiki User named {{code}}xwiki{{/code}} is looked in the main wiki.
141 - if the user is not found a 404 is answered.
142 {{/box}}
143
144 {{box title="Example 7"}}
145 resolutionName: {{code}}[email protected]{{/code}}
146 Assumption: {{code}}domain.com{{/code}} points to the main wiki
147
148 Resolution:
149 - a subwiki named {{code}}bar{{/code}} is looked for, if not found a 404 is answered
150 - the actor corresponding of the sub wiki is returned if found
151 {{/box}}
152
153 {{box title="Example 8"}}
154 resolutionName: {{code}}[email protected]{{/code}}
155 Assumption: {{code}}domain.com{{/code}} points to the main wiki
156
157 Resolution:
158 - the actor corresponding of the main wiki is directly returned
159 {{/box}}
160
161 {{box title="Example 9"}}
162 resolutionName: {{code}}[email protected]{{/code}}
163 Assumption: {{code}}domain.com{{/code}} points to the sub wiki {{code}}bar{{/code}}
164
165 Resolution:
166 - a subwiki named {{code}}foo{{/code}} is looked for, if not found a 404 is answered
167 - the actor corresponding of the sub wiki is returned if found
168 {{/box}}
169
170 {{box title="Example 10"}}
171 resolutionName: {{code}}[email protected]{{/code}}
172 Assumption: {{code}}domain.com{{/code}} points to the sub wiki {{code}}bar{{/code}}
173
174 Resolution:
175 - the actor corresponding of the main wiki on top of this subwiki is directly returned
176 {{/box}}
177
178 {{box title="Example 11"}}
179 resolutionName: {{code}}[email protected]{{/code}}
180 Assumption: {{code}}domain.com{{/code}} points to the sub wiki {{code}}bar{{/code}}
181
182 Resolution:
183 - the actor corresponding of this subwiki is directly returned
184 {{/box}}

Get Connected