Code Repositories xandikos / 83689fb
notes: Touch up - Convert straggler Md file to rST - Use code directive - Fix and normalize bullet points Daniel M. Capella 3 years ago
10 changed file(s) with 371 addition(s) and 293 deletion(s). Raw diff Collapse all Expand all
+13
-12
notes/context.rst less more
22
33 Currently, property get_value/set_value receive three pieces of context:
44
5 * HREF for the resource
6 * resource object
7 * Element object to update
5 - HREF for the resource
6 - resource object
7 - Element object to update
88
99 However, some properties need WebDAV server metadata:
1010
11 supported-live-property-set needs list of properties
12 supported-report-set needs list of reports
13 supported-method-set needs list of methods
11 - supported-live-property-set needs list of properties
12 - supported-report-set needs list of reports
13 - supported-method-set needs list of methods
1414
1515 Some operations need access to current user information:
1616
17 current-user-principal
18 current-user-privilege-set
19 calendar-user-address-set
17 - current-user-principal
18 - current-user-privilege-set
19 - calendar-user-address-set
2020
2121 PUT/DELETE/MKCOL need access to username (for author) and possibly things like user agent
2222 (for better commit message)
2323
24 .. code:: python
2425
25 class Context(object):
26 class Context(object):
2627
27 def get_current_user(self):
28 return (name, principal)
28 def get_current_user(self):
29 return (name, principal)
+0
-223
notes/dav-compliance.md less more
0 This document aims to document the compliance with various RFCs.
1
2 # rfc4918.txt (Core WebDAV) (obsoletes rfc2518)
3
4 Mostly supported.
5
6 ## HTTP Methods
7 - PROPFIND [supported]
8 - PROPPATCH [supported]
9 - MKCOL [supported]
10 - DELETE [supported]
11 - PUT [supported]
12 - COPY [not implemented]
13 - MOVE [not implemented]
14 - LOCK [not implemented]
15 - UNLOCK [not implemented]
16
17 ## HTTP Headers
18 - (9.1) Dav [supported]
19 - (9.2) Depth ['0, '1' and 'infinity' are supported]
20 - (9.3) Destination [only used with COPY/MOVE, which are not supported]
21 - (9.4) If [not supported]
22 - (9.5) Lock-Token [not supported]
23 - (9.6) Overwrite [only used with COPY/MOVE, which are not supported]
24 - (9.7) Status-URI [not supported]
25 - (9.8) Timeout [not supported, only used for locks]
26
27 ## DAV Properties
28 - (15.1) creationdate [supported]
29 - (15.2) displayname [supported]
30 - (15.3) getcontentlanguage [supported]
31 - (15.4) getcontentlength [supported]
32 - (15.5) getcontenttype [supported]
33 - (15.6) getetag [supported]
34 - (15.7) getlastmodified [supported]
35 - (15.8) lockdiscovery [supported]
36 - (15.9) resourcetype [supported]
37 - (15.10) supportedlock [supported]
38 - (RFC2518 ONLY - 13.10) source [not supported]
39
40 # rfc3253.txt (Versioning Extensions)
41
42 Broadly speaking, only features related to the REPORT method are supported.
43
44 ## HTTP Methods
45 - REPORT [supported]
46 - CHECKOUT [not supported]
47 - CHECKIN [not supported]
48 - UNCHECKOUT [not supported]
49 - MKWORKSPACE [not supported]
50 - UPDATE [not supported]
51 - LABEL [not supported]
52 - MERGE [not supported]
53 - VERSION-CONTROL [not supported]
54 - BASELINE-CONTROL [not supported]
55 - MKACTIVITY [not supported]
56
57 ## DAV Properties
58 - DAV:comment [supported]
59 - DAV:creator-displayname [not supported]
60 - DAV:supported-method-set [not supported]
61 - DAV:supported-live-property-set [not supported]
62 - DAV:supported-report-set [supported]
63 - DAV:predecessor-set [not supported]
64 - DAV:successor-set [not supported]
65 - DAV:checkout-set [not supported]
66 - DAV:version-name [not supported]
67 - DAV:checked-out [not supported]
68 - DAV:chcked-in [not supported]
69 - DAV:auto-version [not supported]
70
71 ## DAV Reports
72 - DAV:expand-property [supported]
73 - DAV:version-tree [not supported]
74
75 # rfc5323.txt (WebDAV "SEARCH")
76
77 Not supported
78
79 ## HTTP Methods
80 - SEARCH [not supported]
81
82 ## DAV Properties
83 - DAV:datatype [not supported]
84 - DAV:searchable [not supported]
85 - DAV:selectable [not supported]
86 - DAV:sortable [not supported]
87 - DAV:caseless [not supported]
88 - DAV:operators [not supported]
89
90 # rfc3744.txt (WebDAV access control)
91
92 Not really supported
93
94 ## DAV Properties
95 - DAV:alternate-uri-set [not supported]
96 - DAV:principal-URL [supported]
97 - DAV:group-member-set [not supported]
98 - DAV:group-membership [supported]
99 - DAV:owner [supported]
100 - DAV:group [not supported]
101 - DAV:current-user-privilege-set [supported]
102 - DAV:supported-privilege-set [not supported]
103 - DAV:acl [not supported]
104 - DAV:acl-restrictions [not supported]
105 - DAV:inherited-acl-set [not supported]
106 - DAV:principal-collection-set [not supported]
107
108 ## DAV Reports
109 - DAV:acl-principal-prop-set [not supported]
110 - DAV:principal-match [not supported]
111 - DAV:principal-property-search [not supported]
112 - DAV:principal-search-property-set [not supported]
113
114 # rfc4791.txt (CalDAV)
115
116 Fully supported.
117
118 ## DAV Properties
119 - CALDAV:calendar-description [supported]
120 - CALDAV:calendar-home-set [supported]
121 - CALDAV:calendar-timezone [supported]
122 - CALDAV:supported-calendar-component-set [supported]
123 - CALDAV:supported-calendar-data [supported]
124 - CALDAV:max-resource-size [supported]
125 - CALDAV:min-date-time [supported]
126 - CALDAV:max-date-time [supported]
127 - CALDAV:max-instances [supported]
128 - CALDAV:max-attendees-per-instance [supported]
129
130 ## HTTP Methods
131 - MKCALENDAR [not supported]
132
133 - DAV Reports
134 - CALDAV:calendar-query [supported]
135 - CALDAV:calendar-multiget [supported]
136 - CALDAV:free-busy-query [supported]
137
138 # rfc6352.txt (CardDAV)
139
140 Fully supported.
141
142 ## DAV Properties
143 - CARDDAV:addressbook-description [supported]
144 - CARDDAV:supported-address-data [supported]
145 - CARDDAV:max-resource-size [supported]
146 - CARDDAV:addressbook-home-set [supported]
147 - CARDDAV:princial-address [supported]
148
149 ## DAV Reports
150 - CARDDAV:addressbook-query [supported]
151 - CARDDAV:addressbook-multiget [supported]
152
153 # rfc6638.txt (CardDAV scheduling extensions)
154
155 ## DAV Properties
156 - CALDAV:schedule-outbox-URL [supported]
157 - CALDAV:schedule-inbox-URL [supported]
158 - CALDAV:calendar-user-address-set [supported]
159 - CALDAV:calendar-user-type [supported]
160
161 # rfc6764.txt (Locating groupware services)
162
163 Most of this is outside of the scope of xandikos, but it does support
164 DAV:current-user-principal
165
166 # rfc7809.txt (CalDAV Time Zone Extensions)
167
168 Not supported
169
170 ## DAV Properties
171 - CALDAV:timezone-service-set [supported]
172 - CALDAV:calendar-timezone-id [not supported]
173
174 # rfc5397.txt (WebDAV Current Principal Extension)
175
176 ## DAV Properties
177 - CALDAV:current-user-principal [supported]
178
179 # Proprietary extensions
180
181 ## Custom properties used by various clients
182 - CARDDAV:max-image-size [supported]
183
184 https://github.com/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-ctag.txt
185 - DAV:getctag [supported]
186
187 https://github.com/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-proxy.txt
188 - DAV:calendar-proxy-read-for [supported]
189 - DAV:calendar-proxy-write-for [supported]
190
191 ## Apple-specific Properties
192 - calendar-color [supported]
193 - getctag [supported]
194
195 ## inf-it properties
196 - headervalue [supported]
197 - settings [supported]
198 - addressbook-color [supported]
199
200 # rfc5995.txt (POST to create members)
201
202 Fully supported.
203
204 ## DAV Properties
205 - DAV:add-member [supported]
206
207 ## HTTP Methods
208 - POST [supported]
209
210 # rfc5689 (Extended MKCOL)
211
212 Fully supported
213
214 ## HTTP Methods
215 - MKCOL [supported]
216
217
218 # rfc7529.txt (WebDAV Quota)
219
220 ## DAV properties
221 - {DAV:}quote-available-bytes [supported]
222 - {DAV:}quote-used-bytes [supported]
+291
-0
notes/dav-compliance.rst less more
0 DAV Compliance
1 ==============
2
3 This document aims to document the compliance with various RFCs.
4
5 rfc4918.txt (Core WebDAV) (obsoletes rfc2518)
6 ---------------------------------------------
7
8 Mostly supported.
9
10 HTTP Methods
11 ^^^^^^^^^^^^
12
13 - PROPFIND [supported]
14 - PROPPATCH [supported]
15 - MKCOL [supported]
16 - DELETE [supported]
17 - PUT [supported]
18 - COPY [not implemented]
19 - MOVE [not implemented]
20 - LOCK [not implemented]
21 - UNLOCK [not implemented]
22
23 HTTP Headers
24 ^^^^^^^^^^^^
25
26 - (9.1) Dav [supported]
27 - (9.2) Depth ['0, '1' and 'infinity' are supported]
28 - (9.3) Destination [only used with COPY/MOVE, which are not supported]
29 - (9.4) If [not supported]
30 - (9.5) Lock-Token [not supported]
31 - (9.6) Overwrite [only used with COPY/MOVE, which are not supported]
32 - (9.7) Status-URI [not supported]
33 - (9.8) Timeout [not supported, only used for locks]
34
35 DAV Properties
36 ^^^^^^^^^^^^^^
37
38 - (15.1) creationdate [supported]
39 - (15.2) displayname [supported]
40 - (15.3) getcontentlanguage [supported]
41 - (15.4) getcontentlength [supported]
42 - (15.5) getcontenttype [supported]
43 - (15.6) getetag [supported]
44 - (15.7) getlastmodified [supported]
45 - (15.8) lockdiscovery [supported]
46 - (15.9) resourcetype [supported]
47 - (15.10) supportedlock [supported]
48 - (RFC2518 ONLY - 13.10) source [not supported]
49
50 rfc3253.txt (Versioning Extensions)
51 -----------------------------------
52
53 Broadly speaking, only features related to the REPORT method are supported.
54
55 HTTP Methods
56 ^^^^^^^^^^^^
57
58 - REPORT [supported]
59 - CHECKOUT [not supported]
60 - CHECKIN [not supported]
61 - UNCHECKOUT [not supported]
62 - MKWORKSPACE [not supported]
63 - UPDATE [not supported]
64 - LABEL [not supported]
65 - MERGE [not supported]
66 - VERSION-CONTROL [not supported]
67 - BASELINE-CONTROL [not supported]
68 - MKACTIVITY [not supported]
69
70 DAV Properties
71 ^^^^^^^^^^^^^^
72
73 - DAV:comment [supported]
74 - DAV:creator-displayname [not supported]
75 - DAV:supported-method-set [not supported]
76 - DAV:supported-live-property-set [not supported]
77 - DAV:supported-report-set [supported]
78 - DAV:predecessor-set [not supported]
79 - DAV:successor-set [not supported]
80 - DAV:checkout-set [not supported]
81 - DAV:version-name [not supported]
82 - DAV:checked-out [not supported]
83 - DAV:chcked-in [not supported]
84 - DAV:auto-version [not supported]
85
86 DAV Reports
87 ^^^^^^^^^^^
88
89 - DAV:expand-property [supported]
90 - DAV:version-tree [not supported]
91
92 rfc5323.txt (WebDAV "SEARCH")
93 -----------------------------
94
95 Not supported
96
97 HTTP Methods
98 ^^^^^^^^^^^^
99
100 - SEARCH [not supported]
101
102 DAV Properties
103 ^^^^^^^^^^^^^^
104
105 - DAV:datatype [not supported]
106 - DAV:searchable [not supported]
107 - DAV:selectable [not supported]
108 - DAV:sortable [not supported]
109 - DAV:caseless [not supported]
110 - DAV:operators [not supported]
111
112 rfc3744.txt (WebDAV access control)
113 -----------------------------------
114
115 Not really supported
116
117 DAV Properties
118 ^^^^^^^^^^^^^^
119
120 - DAV:alternate-uri-set [not supported]
121 - DAV:principal-URL [supported]
122 - DAV:group-member-set [not supported]
123 - DAV:group-membership [supported]
124 - DAV:owner [supported]
125 - DAV:group [not supported]
126 - DAV:current-user-privilege-set [supported]
127 - DAV:supported-privilege-set [not supported]
128 - DAV:acl [not supported]
129 - DAV:acl-restrictions [not supported]
130 - DAV:inherited-acl-set [not supported]
131 - DAV:principal-collection-set [not supported]
132
133 DAV Reports
134 ^^^^^^^^^^^
135
136 - DAV:acl-principal-prop-set [not supported]
137 - DAV:principal-match [not supported]
138 - DAV:principal-property-search [not supported]
139 - DAV:principal-search-property-set [not supported]
140
141 rfc4791.txt (CalDAV)
142 --------------------
143
144 Fully supported.
145
146 DAV Properties
147 ^^^^^^^^^^^^^^
148
149 - CALDAV:calendar-description [supported]
150 - CALDAV:calendar-home-set [supported]
151 - CALDAV:calendar-timezone [supported]
152 - CALDAV:supported-calendar-component-set [supported]
153 - CALDAV:supported-calendar-data [supported]
154 - CALDAV:max-resource-size [supported]
155 - CALDAV:min-date-time [supported]
156 - CALDAV:max-date-time [supported]
157 - CALDAV:max-instances [supported]
158 - CALDAV:max-attendees-per-instance [supported]
159
160 HTTP Methods
161 ^^^^^^^^^^^^
162
163 - MKCALENDAR [not supported]
164
165 DAV Reports
166 ^^^^^^^^^^^
167
168 - CALDAV:calendar-query [supported]
169 - CALDAV:calendar-multiget [supported]
170 - CALDAV:free-busy-query [supported]
171
172 rfc6352.txt (CardDAV)
173 ---------------------
174
175 Fully supported.
176
177 DAV Properties
178 ^^^^^^^^^^^^^^
179
180 - CARDDAV:addressbook-description [supported]
181 - CARDDAV:supported-address-data [supported]
182 - CARDDAV:max-resource-size [supported]
183 - CARDDAV:addressbook-home-set [supported]
184 - CARDDAV:princial-address [supported]
185
186 DAV Reports
187 ^^^^^^^^^^^
188
189 - CARDDAV:addressbook-query [supported]
190 - CARDDAV:addressbook-multiget [supported]
191
192 rfc6638.txt (CardDAV scheduling extensions)
193 -------------------------------------------
194
195 DAV Properties
196 ^^^^^^^^^^^^^^
197
198 - CALDAV:schedule-outbox-URL [supported]
199 - CALDAV:schedule-inbox-URL [supported]
200 - CALDAV:calendar-user-address-set [supported]
201 - CALDAV:calendar-user-type [supported]
202
203 rfc6764.txt (Locating groupware services)
204 -----------------------------------------
205
206 Most of this is outside of the scope of xandikos, but it does support
207 DAV:current-user-principal
208
209 rfc7809.txt (CalDAV Time Zone Extensions)
210 -----------------------------------------
211
212 Not supported
213
214 DAV Properties
215 ^^^^^^^^^^^^^^
216
217 - CALDAV:timezone-service-set [supported]
218 - CALDAV:calendar-timezone-id [not supported]
219
220 rfc5397.txt (WebDAV Current Principal Extension)
221 ------------------------------------------------
222
223 DAV Properties
224 ^^^^^^^^^^^^^^
225
226 - CALDAV:current-user-principal [supported]
227
228 Proprietary extensions
229 ----------------------
230
231 Custom properties used by various clients
232 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
233
234 - CARDDAV:max-image-size [supported]
235
236 https://github.com/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-ctag.txt
237
238 - DAV:getctag [supported]
239
240 https://github.com/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-proxy.txt
241
242 - DAV:calendar-proxy-read-for [supported]
243 - DAV:calendar-proxy-write-for [supported]
244
245 Apple-specific Properties
246 ^^^^^^^^^^^^^^^^^^^^^^^^^
247
248 - calendar-color [supported]
249 - getctag [supported]
250
251 inf-it properties
252 ^^^^^^^^^^^^^^^^^
253
254 - headervalue [supported]
255 - settings [supported]
256 - addressbook-color [supported]
257
258 rfc5995.txt (POST to create members)
259 ------------------------------------
260
261 Fully supported.
262
263 DAV Properties
264 ^^^^^^^^^^^^^^
265
266 - DAV:add-member [supported]
267
268 HTTP Methods
269 ^^^^^^^^^^^^
270
271 - POST [supported]
272
273 rfc5689 (Extended MKCOL)
274 ------------------------
275
276 Fully supported
277
278 HTTP Methods
279 ^^^^^^^^^^^^
280
281 - MKCOL [supported]
282
283 rfc7529.txt (WebDAV Quota)
284 --------------------------
285
286 DAV properties
287 ^^^^^^^^^^^^^^
288
289 - {DAV:}quote-available-bytes [supported]
290 - {DAV:}quote-used-bytes [supported]
+3
-2
notes/file-format.rst less more
1919 When new items are added, the collection should verify no existing items have the same UID.
2020
2121 Open questions:
22 * How to handle subtrees? Are they just subcollections?
23 * Where should collection metadata (e.g. colors, description) be stored? .git/config?
22
23 - How to handle subtrees? Are they just subcollections?
24 - Where should collection metadata (e.g. colors, description) be stored? .git/config?
+4
-2
notes/goals.rst less more
33 - standards compliant
44 - standards complete
55 - backed by Git
6 * easily hackable/editable with standard tools (e.g. Git/Vim)
7 * version tracked
6
7 - easily hackable/editable with standard tools (e.g. Git/Vim)
8 - version tracked
9
810 - unit tested
+9
-8
notes/monitoring.rst less more
11 ==========
22
33 Things to monitor:
4 - number of uploaded items
5 - number of accessed store items
6 - number of lru cache hits
7 - number of HTTP requests
8 - number of reports
9 - number of properties requested
10 - number of unknown properties requested
11 - number of unknown reports requested
4
5 - number of uploaded items
6 - number of accessed store items
7 - number of lru cache hits
8 - number of HTTP requests
9 - number of reports
10 - number of properties requested
11 - number of unknown properties requested
12 - number of unknown reports requested
+4
-4
notes/principal.rst less more
22
33 Need per principal config:
44
5 * calendar home sets
6 * addressbook home sets
7 * user address set
8 * infit settings
5 - calendar home sets
6 - addressbook home sets
7 - user address set
8 - infit settings
+3
-0
notes/release-process.rst less more
0 Release Process
1 ===============
2
03 1. Update version in setup.py
14 2. Update version in xandikos/__init__.py
25 3. git commit -a -m "Release $VERSION"
+2
-2
notes/store.rst less more
1010
1111 Stores are responsible for making sure that:
1212
13 * their contents are validly formed calendars/contacts
14 * UIDs are unique (where relevant)
13 - their contents are validly formed calendars/contacts
14 - UIDs are unique (where relevant)
+42
-40
notes/webdav.rst less more
00 WebDAV implementation
11 =====================
22
3 class DAVPropertyProvider(object):
3 .. code:: python
44
5 NAME property
5 class DAVPropertyProvider(object):
66
7 matchresource()
7 NAME property
88
9 # One or multiple properties?
9 matchresource()
1010
11 def proplist(self, resource, all=False):
11 # One or multiple properties?
1212
13 def getprop(self, resource, property):
13 def proplist(self, resource, all=False):
1414
15 def propupdate(self, resource, updates):
15 def getprop(self, resource, property):
16
17 def propupdate(self, resource, updates):
1618
1719
18 class DAVBackend(object):
20 class DAVBackend(object):
1921
20 def get_resource(self, path):
22 def get_resource(self, path):
2123
22 def create_collection(self, path):
24 def create_collection(self, path):
2325
2426
25 class DAVReporter(object):
27 class DAVReporter(object):
2628
27 class DAVResource(object):
29 class DAVResource(object):
2830
29 def get_resource_types(self):
31 def get_resource_types(self):
3032
31 def get_body(self):
32 """Returns the body of the resource.
33 def get_body(self):
34 """Returns the body of the resource.
3335
34 :return: bytes representing contents
35 """
36 :return: bytes representing contents
37 """
3638
37 def set_body(self, body):
38 """Set the body of the resource.
39 def set_body(self, body):
40 """Set the body of the resource.
3941
40 :param body: body (as bytes)
41 """
42 :param body: body (as bytes)
43 """
4244
43 def proplist(self):
44 """Return list of properties.
45 def proplist(self):
46 """Return list of properties.
4547
46 :return: List of property names
47 """
48 :return: List of property names
49 """
4850
49 def propupdate(self, updates):
50 """Update properties.
51 def propupdate(self, updates):
52 """Update properties.
5153
52 :param updates: Dictionary mapping names to new values
53 """
54 :param updates: Dictionary mapping names to new values
55 """
5456
55 def lock(self):
57 def lock(self):
5658
57 def unlock(self):
59 def unlock(self):
5860
59 def members(self):
60 """List members.
61 def members(self):
62 """List members.
6163
62 :return: List tuples of (name, DAVResource)
63 """
64 :return: List tuples of (name, DAVResource)
65 """
6466
65 # TODO(jelmer): COPY
66 # TODO(jelmer): MOVE
67 # TODO(jelmer): MKCOL
68 # TODO(jelmer): LOCK/UNLOCK
69 # TODO(jelmer): REPORT
67 # TODO(jelmer): COPY
68 # TODO(jelmer): MOVE
69 # TODO(jelmer): MKCOL
70 # TODO(jelmer): LOCK/UNLOCK
71 # TODO(jelmer): REPORT