Project

General

Profile

Repo Protocol Specification » History » Version 32

Shuo Chen, 02/21/2014 03:49 PM

1 1 Shuo Chen
Repo Protocol Specification
2
===========================
3
4 2 Shuo Chen
Repo is persistent storage of data objects model in NDN. The NDN repo protocol is a specification of repo operations including reading, insertion and deletion of data objects in repo.
5
6
Repo semantics is based on [Command Interests](http://redmine.named-data.net/projects/nfd/wiki/Command_Interests) with signed commponents an the end of the name and basic common semantics of NDN. 
7
8 11 Shuo Chen
When some operation of repo including insertion and deletion of data objects is requested, a command interest is sent. The command interest is the interest as command of insertion and deletion and signed as form of command interest for access control. The repo will response the command with the data object.
9 4 Shuo Chen
10
The repo protocol can be categorized in three sections of reading, insertion and deletion of data objects.
11
12
## Repo Reading Specification
13
14 11 Shuo Chen
The repo could be viewed as the data container of the data objects. It will register some specific prefixes of data objects it holds into NFD (NDN Forwarding Deamon) and the repo will respond the data with such prefixes.
15 6 Shuo Chen
16 11 Shuo Chen
A standard interest is used to fetch content from the repo. The repo will respond when the name of the interest matches the prefix it registered in NFD. If the content in repo matches the interests, it will respond with the data object. When the interest is not matched, it will not respond.
17 6 Shuo Chen
18
The protocol is listed as bellow
19
20
If there is a matching data object:
21
22 7 Shuo Chen
    Requester                     Repo
23
        |                           |
24
        |                           |
25
        |         Interest          |
26
     t1 |-------------------------->|
27
        |                           |
28
        |        Data Object        |
29
     t2 |<==========================|
30 1 Shuo Chen
        |                           |
31 7 Shuo Chen
        |                           |
32 1 Shuo Chen
        |                           |
33 7 Shuo Chen
34
If there is no matching data object:
35 6 Shuo Chen
36
    Requester                     Repo
37
        |                           |
38 1 Shuo Chen
        |                           |
39 7 Shuo Chen
        |         Interest          |
40
     t1 |-------------------------->|
41
        |                           |
42
        |                           |
43
        |                           |
44
45 30 Shuo Chen
## Repo Command
46
For insertion, deletion and other operations of repo, these commands are encoded in the form of [sigend command interest](http://redmine.named-data.net/projects/nfd/wiki/Command_Interests). The semantics of repo command interest is as follows:
47 14 Shuo Chen
48 8 Shuo Chen
The name semantics is defined to have following components:
49 1 Shuo Chen
50 17 Shuo Chen
* ``<name of repo>`` refers to specific name of repo
51 30 Shuo Chen
* ``<command verb>`` refers to the name of command
52
* ``<RepoCommandParameters>`` refers to parameters of repo command
53 1 Shuo Chen
54 29 Shuo Chen
The folloing components are components of singed interest for access control:
55 1 Shuo Chen
56
* ``<timestamp>``
57 8 Shuo Chen
* ``<random-value>``
58
* ``<SignatureInfo>``
59
* ``<SignatureValue>``
60
61 30 Shuo Chen
For name of the repo /ucla/cs/repo/, the command will be defined as this:
62
    /ucla/cs/repo/<command verb>/<RepoCommandParameters>/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>
63 14 Shuo Chen
64 30 Shuo Chen
### RepoCommandParameters
65 29 Shuo Chen
66 1 Shuo Chen
    RepoCommandParameters  ::= SEGMENTATIONINFO-TYPE TLV-LENGTH
67
                               Name?
68
                               StartBlockId?
69
                               EndBlockId?
70 29 Shuo Chen
71 30 Shuo Chen
    Name ::= NAME-TYPE TLV-LENGTH NameComponent*
72
    NameComponent ::= NAME-COMPONENT-TYPE TLV-LENGTH BYTE+
73 1 Shuo Chen
    
74
    StartBlockId          ::= STARTBLOCKID-TYPE TLV-LENGTH
75
                                nonNegativeInteger
76
    
77
    EndBlockId            ::= ENDBLOCKID-TYPE TLV-LENGTH
78
                                nonNegativeInteger
79
80 30 Shuo Chen
## Repo Command Response
81 1 Shuo Chen
82 30 Shuo Chen
Repo command response is the response data packet of repo command interest. The response contains statuscode to indicate the status of command process and other information. A TLV-encoded block called ``RepoCommandResponse`` is encoded in content of the data packet.
83 1 Shuo Chen
84 30 Shuo Chen
    RepoCommandResponse   ::= INSERTSTATUS-TYPE TLV-LENGTH
85 1 Shuo Chen
                               StatusCode?
86
                               StartBlockId?
87
                               EndBlockId?
88
                               InsertNum?
89 30 Shuo Chen
                               DeleteNum?
90 1 Shuo Chen
91
    StatusCode            ::= STATUSCODE-TYPE TLV-LENGTH
92
                                nonNegativeInteger    
93
94
    StartBlockId          ::= STARTBLOCKID-TYPE TLV-LENGTH
95
                                nonNegativeInteger
96
    
97
    EndBlockId            ::= ENDBLOCKID-TYPE TLV-LENGTH
98
                                nonNegativeInteger
99 17 Shuo Chen
100
    InsertNum             ::= INSERTNUM-TYPE TLV-LENGTH
101
                                nonNegativeInteger
102
103 30 Shuo Chen
    DeleteNum             ::= DELETENUM-TYPE TLV-LENGTH
104
                                nonNegativeInteger
105 17 Shuo Chen
106 30 Shuo Chen
## Repo Insertion Specification
107
108
Insertion specification is for some client and application to insert data objects into certain NDN repo. A command interest as insertion command will be sent to the repo. This command interest is a signed interest and will be validated with access control policy defined by the repo. When the interested is validated and name of the data is not existed in the repo. The repository will reponse with a data object containing OK status and start to send the interest to fetch the data to insert.
109
110
Segmented data insertion is also supported in the insertion protocol. Segmantation info is defined as a TLV-encoded SegmantationInfo block. If the content is segmented, the final segment id will be encoded in this block.
111
112
### Insertion command interest semantics
113
114
The name semantics is follows the format of the repo command. The <command verb> is defined as ``insert``.
115
For example, for ``<name of repo>`` as ``/ucla/cs/repo``, the following is an example:
116 1 Shuo Chen
117 31 Shuo Chen
    /ucla/cs/repo/insert/<RepoCommandParameters>/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>
118 30 Shuo Chen
119
### Insertion status check
120
121
During the insertion progress, the requester could send insertion status check command to check the status of the insertion progress. This status check command is also signed interest. The semantics of insertion status check command is shown as follows:
122
123
<command verb> equals to ``insert check``. For example:
124 1 Shuo Chen
125 32 Shuo Chen
    /ucla/cs/repo/insert check/<RepoCommandParameters>/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>
126 30 Shuo Chen
127
### Insertatation status response
128
129
This insert status data object could be the response data object of both insert command and insert check command. It will follow the format of repo command response.
130
131
StatusCode indicates the status of insertion. InsertNum represents how many data has been intersted into the repo. StartBlockId and EndBlockId is the start and end segment id of data inserted. InsertNum is the how many data segments have been inserted.
132
133
For insert cammand, status code will be set according to definition below, StartBlockId and EndBlockId will be set according to the insert command.
134
135
For insert check command, status code will be set according to definition below, StartBlockId and EndBlockId will be set according to the insert command, insertnum will be set according to insertion progress.
136
137 1 Shuo Chen
StatusCode Definition:
138 17 Shuo Chen
139
``StatusCode`` | Description
140
-------------- | ----------------------------------------------
141 19 Shuo Chen
``100``        | The command is OK. can start to fetch the data
142
``200``        | All the data has been inserted
143 17 Shuo Chen
``300``        | This insertion is in progress
144
``401``        | This insertion check is invalidated
145
``404``        | No such this insertion is in progress
146 30 Shuo Chen
``505``        | status check command is not supported
147 17 Shuo Chen
148 22 Alex Afanasyev
### Protocol Process
149
150 20 Alex Afanasyev
1. start to authorize the command; if authorization does not fail immediately, go to step 3
151 17 Shuo Chen
152 20 Alex Afanasyev
2. send a negative response indicating authorization failure, and abort these steps
153 14 Shuo Chen
154 20 Alex Afanasyev
3. if both StartBlockId and EndBlockId are missing, go to step 6
155 14 Shuo Chen
156 20 Alex Afanasyev
4. if both StartBlockId and EndBlockId are present, and StartBlockId is less than or equal to EndBlockId, go to step 6
157 14 Shuo Chen
158 20 Alex Afanasyev
5. send a negative response indicating malformed command, and abort these steps
159 14 Shuo Chen
160 20 Alex Afanasyev
6. wait for authorization completion
161 14 Shuo Chen
162 20 Alex Afanasyev
7. if authorization fails, go to step 2
163 14 Shuo Chen
164 20 Alex Afanasyev
8. send a positive response indicating insert is in progress
165 14 Shuo Chen
166 20 Alex Afanasyev
9. if both StartBlockId and EndBlockId are present, go to step 15
167 14 Shuo Chen
168 20 Alex Afanasyev
10. start to retrieve Name
169 14 Shuo Chen
170 20 Alex Afanasyev
11. wait for retrieval completion
171 14 Shuo Chen
172 20 Alex Afanasyev
12. if retrieval fails, abort these steps
173 14 Shuo Chen
174 20 Alex Afanasyev
13. store retrieved Data packet
175 14 Shuo Chen
176 20 Alex Afanasyev
14. abort these steps
177 14 Shuo Chen
178 20 Alex Afanasyev
15. append StartBlockId to Name
179 1 Shuo Chen
180 20 Alex Afanasyev
16. start to retrieve Name
181 14 Shuo Chen
182 20 Alex Afanasyev
17. wait for retrieval completion
183 14 Shuo Chen
184 20 Alex Afanasyev
18. if retrieval fails, abort these steps
185 14 Shuo Chen
186 20 Alex Afanasyev
19. store retrieved Data packet
187 15 Shuo Chen
188 20 Alex Afanasyev
20. if retrieved Data packet contains FinalBlockId, and FinalBlockId is less than EndBlockId, let EndBlockId be FinalBlockId
189 15 Shuo Chen
190 20 Alex Afanasyev
21. if the last component of Name is greater than or equal to EndBlockId, abort these steps
191 15 Shuo Chen
192 20 Alex Afanasyev
22. increment the last component of Name
193 15 Shuo Chen
194 20 Alex Afanasyev
23. go to step 16
195 15 Shuo Chen
196 20 Alex Afanasyev
Implementation MAY pipeline the Interests.
197 1 Shuo Chen
198 20 Alex Afanasyev
### Repo command progress report
199 16 Shuo Chen
200 20 Alex Afanasyev
Implementation MAY publish a notification of status regarding insert progress. The process of status check is as follows:
201 18 Shuo Chen
202 20 Alex Afanasyev
1. start to authorize the insert status command
203 1 Shuo Chen
204 20 Alex Afanasyev
2. send a negative response indicating authorization failure, and abort these steps
205 18 Shuo Chen
206 20 Alex Afanasyev
3. start to check the progress of the insert with the data name in the command. If no such progress is found, go to 4. or go to 5.
207 18 Shuo Chen
208 20 Alex Afanasyev
4. reponse status with status code of 404
209 18 Shuo Chen
210 20 Alex Afanasyev
5. ckeck te status of insertion. return the status data content
211
212 17 Shuo Chen
### Protocol diagram:
213 10 Alex Afanasyev
214
    Requester                     Repo                          Data producer
215
        |                           |                                 |
216
        |                           |                                 |
217
      +---+  Insert command       +---+                               |
218
      |   | --------------------> |   |                               |
219
      +---+                       |   |                               |
220
        |                         |   |                               |
221
      +---+   Confirm start       |   |                               |
222
      |   | <==================== |   |                               |
223
      +---+   Reject command      +---+                               |
224
        |     (with status code)    |                                 |
225
        |                         +---+     Interest for Data       +---+
226 1 Shuo Chen
        |                         |   | --------------------------> |   |
227
        |                         +---+                             |   |
228 10 Alex Afanasyev
        |                           |                               |   |
229
        |                         +---+       Data segment          |   |
230
        |                         |   | <========================== |   |
231
        |                         +---+                             +---+
232
        |                           |                                 |
233
        |                           ~                                 ~
234
        |                           ~                                 ~
235
        |                           |                                 |
236
        |                         +---+     Interest for Data       +---+
237
        |                         |   | --------------------------> |   |
238
        |                         +---+                             |   |
239 1 Shuo Chen
        |                           |                               |   |
240
        |                         +---+       Data segment          |   |
241
        |                         |   | <========================== |   |
242
        |                         +---+                             +---+
243
        |                           |                                 |
244
        |                           |                                 |
245
        |                           ~                                 ~
246 19 Shuo Chen
        |                           ~                                 ~
247
        |                           |                                 |
248
        |                           |                                 |
249 17 Shuo Chen
        |                           |                                 |
250
      +---+   Status interest     +---+                               |
251
      |   | --------------------> |   |                               |
252
      +---+                       |   |                               |
253
        |                         |   |                               |
254
      +---+    Status response    |   |                               |
255
      |   | <==================== |   |                               |
256
      +---+                       +---+                               |
257
        |                           |                                 |
258
        |                           |                                 |
259
260
## Repo Deletion Specification
261
262 1 Shuo Chen
Deletion of one content object or content objects under certain prefix are both supported in repo specification. Selectors are used to select multiple content objects. These selectors are different from conventional [selectors](http://named-data.net/doc/ndn-tlv/interest.html#selectors) of interest packet. The conventional selecors of interest would select one data packet of repo. Selecors of delete command will return any data packets which applies for these selectors.
263
264
### Deletion command interest semantics
265
266 30 Shuo Chen
Deletion command interest follows the format of the repo command. For example:
267 19 Shuo Chen
268 30 Shuo Chen
    /ucla/cs/repo/delete/<RepoCommandParameters>/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>
269 19 Shuo Chen
270
### Deletion Command Selectors
271
272
    Selectors             ::= SELECTORS-TYPE TLV-LENGTH
273
                               MinSuffixComponents?
274
                               MaxSuffixComponents?
275
                               PublisherPublicKeyLocator?
276
                               Exclude?
277
    
278
    MinSuffixComponents   ::= MIN-SUFFIX-COMPONENTS-TYPE TLV-LENGTH
279
                               nonNegativeInteger
280
281
    MaxSuffixComponents   ::= MAX-SUFFIX-COMPONENTS-TYPE TLV-LENGTH
282
                               nonNegativeInteger
283
284
    PublisherPublicKeyLocator ::= KeyLocator
285
    
286
    Exclude               ::= EXCLUDE-TYPE TLV-LENGTH Any? (NameComponent (Any)?)+
287
    Any                   ::= ANY-TYPE TLV-LENGTH(=0)
288
289
The definitions of delete command selectors is the same as the selectors of conventional [selectors](http://named-data.net/doc/ndn-tlv/interest.html#selectors). The difference is that this delete command selectors will return any data packets that comforms to the selectors. If selectors are not presented, the repo will just delete the data of exact name. So, for example, if somebody wants to delete all the data under certain prefix, at least, MinSuffixComponents should be set to 0.
290
291
### Deletion status check
292
293 30 Shuo Chen
During the deletion progress, the requester could send deletion status check command to check the status of the deletion progress. This status check command is also signed interest. The semantics of deletion status check command follows the format of repo command. ``<command verb>`` equals to ``delete check``. For example:
294
    /ucla/cs/repo/delete/<RepoCommandParameters>/<timestamp>/<random-value>/<SignatureInfo>/<SignatureValue>
295 19 Shuo Chen
296
297
### Deletion status response
298
299 30 Shuo Chen
This delete status data object could be the response data packet of both delete command and delete check command. The name of data packet is the same as that of command.The deletion status is enocoded as a TLV echoded block in content block in data packet. The TLV block format follows RepoCommandResponse.
300 19 Shuo Chen
301
StatusCode indicates the status of deletion. DeleteSum is the sum of the deletion. DeleteNum represents how many data has been deleted.
302
303
StatusCode Definition:
304
305
``StatusCode`` | Description
306
-------------- | --------------------------------------
307
``200``        | All the data has been deleted
308
``300``        | This deletion is in progress
309
``401``        | This deletion check is invalidated
310
``404``        | No such this deletion is in progress
311 30 Shuo Chen
``505``        | status check command is not supported
312 19 Shuo Chen
313 17 Shuo Chen
### Protocol process
314 1 Shuo Chen
315 21 Alex Afanasyev
1. start to authorize the command; if authorization does not fail immediately, go to step 3
316 1 Shuo Chen
317 21 Alex Afanasyev
2. send a negative response indicating authorization failure, and abort these steps
318 1 Shuo Chen
319 21 Alex Afanasyev
3. check whether selectors are presented. If selectors are presented, go to step 4, or select the data packet of the exact name of command. If some data is selected, go to step 6. If no data selected, go to step 5
320 1 Shuo Chen
321 21 Alex Afanasyev
4. select all the data packets that comforms to data name of the command and the selectors. If some data packets are selected, go to step 6. Or no data selected, go to step 5.
322 1 Shuo Chen
323 21 Alex Afanasyev
5. send a negative response and abort the delete transaction.
324 1 Shuo Chen
325 21 Alex Afanasyev
6. wait for authorization completion
326 1 Shuo Chen
327 21 Alex Afanasyev
7. if authorization fails, go to step 2
328 1 Shuo Chen
329 21 Alex Afanasyev
8. start to delete the selected data. If deletion success, return positive reponse, or return negative response and abort the deletion.
330 19 Shuo Chen
331 21 Alex Afanasyev
Implementation MAY publish a notification of status regarding delete progress. The process of status check is as follows:
332 19 Shuo Chen
333 21 Alex Afanasyev
1. start to authorize the delete status command
334 19 Shuo Chen
335 21 Alex Afanasyev
2. send a negative response indicating authorization failure, and abort these steps
336 19 Shuo Chen
337 21 Alex Afanasyev
3. start to check the progress of the delete with the data name in the command. If no such progress is found, go to 4. or go to 5.
338 19 Shuo Chen
339 21 Alex Afanasyev
4. reponse status with status code of 404
340
341
5. ckeck te status of delete. return the status data content
342 19 Shuo Chen
343
### Protocol diagram:
344
345
    Requester                     Repo 
346
        |                           |                                 
347
        |                           |                                 
348
      +---+  Delete command       +---+                               
349
      |   | --------------------> |   |                               
350
      +---+                       +---+                               
351
        |                           |                                 
352
        |                           |                                 
353
        |                           |                                 
354
      +---+   Status interest     +---+                               
355
      |   | --------------------> |   |                               
356
      +---+                       |   |                               
357
        |                         |   |                               
358
      +---+    Status response    |   |                               
359
      |   | <==================== |   |                               
360
      +---+                       +---+                               
361
        |                           |                                 
362
        |                           |                                 
363
        |                           |                                 
364
      +---+   Confirm Deletion    +---+                               
365
      |   | <==================== |   |                               
366
      +---+   Reject command      +---+                               
367
        |     (with status code)    |    
368 20 Alex Afanasyev
        |                           |