-
Notifications
You must be signed in to change notification settings - Fork 0
/
messages.xml
255 lines (255 loc) · 15 KB
/
messages.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
<?xml version="1.0" encoding="UTF-8"?>
<section anchor="messages" title="Messages">
<t>Messages are the basic unit of communication in the FOSP network.
There are three different types of messages which serve different purposes.
How a message is serialized depends on the protocol that is used to transport the message.
</t>
<section anchor="msg-type" title="Types">
<t>Each message has a specific type, which determines the kind of purpose this message serves.
The type is implicitly given in the way that the content of the message determines it’s type.
For now there are only three types of messages needed to support all functionality.
The types are requests, responses and notifications.
Should there be the need for additional types of messages, a new one can be added in later versions of the protocol.
</t>
<t>All messages can have headers and a body, similar to HTTP messages and are distinguished by their main attributes.
Requests and notifications usually act on, or are emitted from an object or an attachemnt.
The identifier of the object or attachemnt is then part of the request.
If a request does not act upon an object, the identifier is replaced with an asterisk.
</t>
</section>
<section anchor="msg-request" title="Request">
<t>Requests are sent from clients to servers to authenticate or manipulate objects.
A request consists of ...
<list>
<t>a request type</t>
<t>optionally an identifier of a resource that it manipulates</t>
</list>
</t>
<t>The content of the body depends on the type of request.
For example, the body of a GET or DELETE request is empty and the body of a CREATE request contains the new object.
In general the body is a JSON object, except for the WRITE request that has the byte representation of the file as the body.
</t>
<t>The server MUST always responde to a request with a response message.
Depending on the request, the server must check access rights and whether a certain object exits, bevor the request can be processed.
If the user does not have sufficent rights or an required object does not exist (e.g. a parent object when creating a child), a failure response MUST be sent.
When the request is successfully processed, a success response MUST be sent.
Depending on the request, it may contain information in its body, like the object that was requested, or an attachment that was read.
</t>
<t>The request types are described in the following sections.</t>
<section anchor="msg-request-options" title="Options">
<t>The OPTIONS request is used to discover the capabilities of the server.
Currently, the only use is to detect supported SASL mechanisms.
When detecting capabilities of the whole server, the request URL is replaced by "*".
</t>
<t>The server MUST return a 200 response and a body that contains information about it's capabilities.
The returned object MUST contain a field named "sasl" which in turn contains an object with a field named "mechanisms".
This field contains an array of all supported SASL mechanisms.
</t>
<t>In the future, the OPTIONS request might be used to discover allowed operations on resources.
</t>
</section>
<section anchor="msg-request-auth" title="Auth">
<t>The AUTH request is used to authenticate the client.
The authentication uses the SASL framework.
How SASL messages are transported is defined in <xref target="auth-sasl" />.
Multiple requests might be needed to successfully authenticate, depending on the mechanism.
</t>
<t>
The server verifies that the authentication is successfull and sents a success response or a failed response otherwise.
All future request are made in the name of this authenticated user.
How the state is kept depends on the transport protocol used.
It can for example either be a tied to network connection, or be a cookie supplied in each request.
</t>
</section>
<section anchor="msg-request-get" title="Get">
<t>The GET request is used to retrieve an object.
The resource identifier in the request denotes the object that should be returned.
The server MUST ignore any content in the body of the request.
</t>
<t>If the request was successfull, the object is returned in the body of the response..
Even on success, not the whole object might be returned as the user might have the right to read some attributes but not others.
</t>
</section>
<section anchor="msg-request-list" title="List">
<t>The LIST request is used to discover all child objects of a certain object.
The resource identifier specifies the object of which the children should be returned.
</t>
<t>If successfull, the response contains an array of names of the child objects.
</t>
</section>
<section anchor="msg-request-create" title="Create">
<t>The CREATE request is used to store new objects on the server.
The resource identifier is the desired location for the new object.
The body containes the object to store.
</t>
<t>On success, an empty success response is returned and the object is stored at the given location.
</t>
</section>
<section anchor="mgs-request-patch" title="Patch">
<t>The PATCH request is used to update an already existing object on the server.
The resource identifier specifies the object that should be updated.
The body containes an object with the differences that should be applied to the object.
The semantics of the patch object and the algorithm to apply it are the ones defined in <xref target="RFC7396" />.
</t>
<t>The differences are merged into the object as follows.
If the original object does not have an attribute the differences object has, the attribute is copied to the object.
If the original object already has an attribute the differences object has and the new value is "null", the attribute is deleted from the object.
If the original object already has an attribute the differences object has and the value is not "null", the attribute is replaced with the new attribute except when the value of the old and the new attribute are both an object.
In this case the merging is done on the attribute recursivly as it is on the whole object.
</t>
<t>On success, the updated object is returned.
</t>
</section>
<section anchor="msg-request-delete" title="Delete">
<t>The DELETE request is used to remove an object from a tree.
The resource identifier specifies the object that should be removed.
</t>
<t>If the object that should be deleted has children, the DELETE request MUST fail and a 409 response MUST be returned.
In the future, a header might be supported to enable recursive deleting of objects.
</t>
<t>If successfull, a succeeded message is returned and the object is permanently removed.
</t>
</section>
<section anchor="msg-request-read" title="Read">
<t>The READ request is used to read the attachment.
The resource identifier specifies the object of which the attachment should be read.
</t>
<t>The success response body contains the raw bytes of the attachment.
</t>
</section>
<section anchor="msg-request-write" title="Write">
<t>The WRITE request is used to write to the attachment.
The resource identifier specifies the object of which the attachment should be written.
The body contains the raw bytes of the attachment.
</t>
<t>The success response is empty.
</t>
</section>
</section>
<section anchor="msg-response" title="Response">
<t>Responses are sent from servers to clients when a request has been processed.
A response has ...
<list>
<t>a type, either “SUCCEEDED” or “FAILED”.</t>
<t>a status code, an integer greater zero.</t>
</list>
</t>
<t>The body of a response depends on the request that is answered.
For a CREATE or DELETE request it would be empty, for a GET request it would be the object that was requested.
In case of a READ request it would contain the raw bytes of the attachment.
</t>
<t>The status code is explained in <xref target="msg-status-codes" />.
</t>
<t>An FAILED response SHOULD contain an object describing the error that occured.
The object should contain a "message" attribute with a string value that explains the error.
</t>
</section>
<section anchor="msg-type-notification" title="Notification">
<t>Notifications are sent from servers to clients when objects change and the client
has subscribed to those changes. A notification consists of ...
<list>
<t>an event which is one of “CREATED”, “UPDATED” or “DELETED”.</t>
<t>a resource identifier.</t>
</list>
</t>
<t>The notifications are sent when a request triggers an event, for example CREATE triggers a CREATED event.
If the event equals DELETED then the body of the notification must be empty.
Otherwise it should contain the new version of the object.
</t>
<t>When and to who notifications are sent is explained in <xref target="pol-subscriptions" />.
</t>
</section>
<section anchor="msg-status-codes" title="Status codes">
<t>The status codes reuse and extend the status codes used in HTTP.
They are wildly known and also used in similar fashion in other protocols.
The status codes are also divided into the same classes, with the same meaning.
Not all status codes of HTTP are used, but all are reserved and MUST NOT be used for custom statuses.
</t>
<section anchor="msg-status-codes-100" title="Informal 1xx">
<t>The 1xx status codes are not used at the moment.
A client MUST ignore any such responses and continue to wait for a final response.
</t>
</section>
<section anchor="msg-status-codes-200" title="Successful 2xx">
<t>The 2xx status codes indicate that the request was successful.
<list style="hanging">
<t hangText="200 OK">The request has succeeded.</t>
<t hangText="201 Created">The request has succeeded and a new object has been created.</t>
<t hangText="204 No Content">The request has succeeded but no content is returned.
This can be for example the case when a DELETE request has been sent.
</t>
</list>
</t>
</section>
<section anchor="msg-status-codes-300" title="Redirection 3xx">
<t>The 3xx status codes indicate that the requested object can be found elsewhere.
<list style="hanging">
<t hangText="301 Moved Permanently">The object was moved permanently and is now found at the location indicated in the "Location" header.
Moving objects is not yet supported but might be in the future.
Clients SHOULD be able to understand this status and in case of a GET, LIST or READ request MAY resent the request with the new location.
However, a client MUST never automatically resent the request if the request alters the object, e.g. is a CREATE, PATCH, DELETE or WRITE request.
</t>
<t hangText="304 Not Modified">If the request did contain a condition that checks for the modification date and the object did not change, the server SHOULD respond with this status code.
Conditional requests are not supported yet, but might be in the future.
</t>
<t hangText="310 Additional data needed" anchor="status-code-310">This status code can only be returned while authenticating.
If the used SASL mechanism requires the server to return a challenge before continuing authentication, this response code MUST be returned.
</t>
</list>
</t>
</section>
<section anchor="msg-status-codes-400" title="Client error 4xx">
<t>The 4xx status codes indicate that the client made an error.
<list style="hanging">
<t hangText="400 Bad Request">The request could not be parsed by the server due to malformed syntax.</t>
<t hangText="401 Unauthorized">The client tried to send a request that needs authentication but is not yet authenticated.
The client must make a successful AUTH request bevor retrying this request.
</t>
<t hangText="403 Forbidden">The client does not have the necessary permissions.
If the server MUST only return this status if the client is already authenticated.
</t>
<t hangText="404 Not Found">The object the client requested could not be found.</t>
<t hangText="405 Method Not Allowed">The request method is not allowed on this object.
This status can be returned if a client tries to READ and attachment of an object without attachment.
</t>
<t hangText="409 Conflict">The request could not be completed due to a conflict with an resource.
This status MUST be returned by the server if the client tries to create an object that already exists.
</t>
<t hangText="412 Precondition Failed">If the request did contain a condition and condition is not satisfied, then the server MUST return this status.
Conditional request are not supported yet, but might be in the future.
This status can also be returned if a new object should be created but the parent object does not exist.
</t>
<t hangText="413 Request Entity Too Large">The server might choose to accept only messages smaller than a certain size.
In this case, if a client tries to send a larger message, the server CAN respond with this status and drop the request.
</t>
</list>
</t>
</section>
<section anchor="msg-status-code-500" title="Server Error 5xx">
<t>The 5xx status codes indicate an error in the server.
<list style="hanging">
<t hangText="500 Internal Server Error">The server could not process the request due to an internal error.
</t>
<t hangText="501 Not Implemented">The server does not support the requested functionality.
</t>
<t hangText="502 Bad Gateway">The server tried to forward the request, but was unsuccessful.
This might be because the authentication failed, the remote server rejected the connection or other reasons.
If the remote server can not be reached at all, 504 SHOULD be returned instead.
</t>
<t hangText="503 Service Unavailable">The server can currently not process any requests but will likly be able to in the near future.
</t>
<t hangText="504 Gateway Timeout">The server tried to forward the request but could not reach the upstream server at all.
This can be a permanent problem and indicate that the requested object does not exist on any remote server at all.
</t>
</list>
</t>
</section>
</section>
<section anchor="msg-fowarding" title="Forwarding">
<t>If a request applies to a resource that is not stored by the home server of the user, the server can forward it to a server that does store it.
In this case, the server MUST insert an additional "From" header that contains the full username of the user that sent the request.
Similar, when a server sends a response to a forwarded request, an additional "To" header is added.
This also applies if a notification is to be sent to a user of a different provider.
</t>
</section>
</section>