|
| 1 | +CCNx Create Collection Protocol |
| 2 | +=============================== |
| 3 | + |
| 4 | +== Introduction |
| 5 | + |
| 6 | +Sync is a CCNx facility that allows CCN components and applications to define Collections of named data in Repositories that are to be automatically kept in sync with identically defined Collections in neighboring Repositories. Sync is currently embedded in the Repository, and will be available separately in the future. |
| 7 | + |
| 8 | +The CCNx Create Collection Protocol is used to define these Collections. |
| 9 | +At a high-level, the process for creating a Collection and starting its synchronization is as follows: |
| 10 | + |
| 11 | +1. Write a definition of the Collection (known as a _slice_) to the local Repository. |
| 12 | + |
| 13 | +2. Write an identical definition to a remote Repository. (This is done by an application at the remote node.) There must be hash code equality over the two Collections (i.e., agreement on the topological prefix, naming prefix, and filter clauses as <<TermDefinitions,described below>>), and the two Repositories must be neighbors (i.e., reachable with scope = 2). |
| 14 | + |
| 15 | +== Create Slice |
| 16 | + |
| 17 | +A slice is created by writing a Content Object with specially formatted contents to the Repository using the standard Start Write or Checked Start Write command as described in link:RepoProtocol.html[CCNx Repository Protocols]. The response to the write request is a +RepositoryInfo+ object as described in link:RepositoryInfoObject.html[CCNx RepositoryInfo Object]. If the command is accepted, the response +Type+ is +INFO+; if the request is in error, the response +Type+ is +DATA+ and error info is returned in the +Name+ element of the object. |
| 18 | + |
| 19 | +The name in the Interest is, when expressed as a URI, of the form: |
| 20 | + |
| 21 | ++ccnx:/%C1.M.S.localhost/%C1.S.cs/*_slicehash_*/*_version_*/*_segment_*+ |
| 22 | + |
| 23 | +where: |
| 24 | + |
| 25 | +* +%C1.M.S.localhost+ restricts the definition to the local node and Repository. |
| 26 | + |
| 27 | +* +%C1.S.cs+ is the command marker for the Create Slice Interest. |
| 28 | + |
| 29 | +* +*_slicehash_*+ is required, and is the SHA-256 hash of the ccnb encoding in the slice Content Object. |
| 30 | + |
| 31 | +* +*_version_*+ and +*_segment_*+ are required and must follow normal CCN naming practices. (See link:NameConventions.html[CCNx Basic Name Conventions].) |
| 32 | + |
| 33 | +The Content Object for a slice contains a SyncConfigSlice object whose definition is as follows: |
| 34 | + |
| 35 | +....................................................... |
| 36 | +SyncConfigSlice ::= SyncVersion |
| 37 | + Name |
| 38 | + Name |
| 39 | + SyncConfigSliceList |
| 40 | +....................................................... |
| 41 | + |
| 42 | +[[TermDefinitions]] |
| 43 | +=== SyncVersion |
| 44 | + |
| 45 | ++SyncVersion ::= nonNegativeInteger+ |
| 46 | + |
| 47 | +*+SyncVersion+* specifies the version of the Synchronization protocol, which is used to determine how to parse the Content Object. +SYNC_VERSION+ and +SLICE_VERSION+ are both defined in +SyncMacros.h+ to have values of +20110614+. |
| 48 | + |
| 49 | +=== Name |
| 50 | + |
| 51 | +The first *+Name+* is a _topological prefix_ used for routing Root Advise and Node Fetch interests for the Collection. Its purpose is to limit the number of nodes to which these Interests are routed. |
| 52 | + |
| 53 | +The topo prefix must be registered, so its choice is a system-level configuration concern. (See link:RepoPolicies.html[CCNx Repository Policy Handling].) Ideally, it should encompass all nodes on which the Collection _might_ be defined, and no more. |
| 54 | + |
| 55 | +The best strategy for choosing the topo prefix may depend on a number of factors. One choice might be to choose a region-specific topo prefix to limit traffic to an applicable region. Another might be to base it on organization to limit traffic to its members. Note that, although using different topo prefixes can be used to keep traffic separate for organizational reasons, it is not a substitute for real security. |
| 56 | + |
| 57 | +=== Name |
| 58 | + |
| 59 | +The second *+Name+* is the common naming prefix used for every name in the Collection. |
| 60 | + |
| 61 | +=== SyncConfigSliceList |
| 62 | + |
| 63 | ++SyncConfigSliceList ::= (SyncConfigSliceOp, Name)*+ |
| 64 | + |
| 65 | +*+SyncConfigSliceList+* is list of zero or more _filter clauses_ that restrict names that can be in the Collection. If any filter clauses are present, then |
| 66 | +only names that match at least one filter clause are included in the Collection. As a special case, if there are no filter clauses, then every name with the given prefix is included. |
| 67 | + |
| 68 | +==== SyncConfigSliceOp |
| 69 | +*+SyncConfigSliceOp+* is reserved for future use and should be 0. |
| 70 | + |
| 71 | +==== Name |
| 72 | + |
| 73 | +The *+Name+* in a filter clause is a name prefix that restricts the names in the Collection, and may contain wild card components. |
| 74 | + |
| 75 | +* Each wild card component in a filter clause name matches a single component in a name. |
| 76 | + |
| 77 | +* The encoding of a wild card component is the single byte 255 (+0xFF+). To enable byte 255 to start a literal component, any pattern component that starts with byte 255 and has more than 1 byte is treated as the literal component consisting of the bytes following the initial byte. |
| 78 | + |
| 79 | +* A name matches a filter if it matches any of the filter clauses. (All components are required.) Components of a name longer than the name in the filter clause are accepted as matching. For example, using CCN URI syntax, +/X/%FF/Z+ matches the names +/X/Y/Z+ and +/X/Y/Z/W+, but does not match the name +/X/Z+. |
| 80 | + |
| 81 | +== Protocol |
| 82 | + |
| 83 | +The protocol for defining a Collection is illustrated below. |
| 84 | + |
| 85 | +image:CreateSliceProtocol.png[align="center"] |
| 86 | + |
| 87 | +When a slice is defined in a Repository, the Repository begins trying to synchronize the Collection with copies in neighboring Repositories as described in link:SynchronizationProtocol.html[CCNx Synchronization Protocol]. When an identical slice is defined in a neighboring Repository, automatic synchronization of the two Collections begins. |
0 commit comments