Fossil SCM
Update the clone documentation for protocol 3 and the 'cfile' card format.
Commit
d16018c8e19195881c861415cd18140d0a5783b5
Parent
ef6f7dee43779e1…
1 file changed
+55
-9
+55
-9
| --- www/sync.wiki | ||
| +++ www/sync.wiki | ||
| @@ -159,15 +159,21 @@ | ||
| 159 | 159 | |
| 160 | 160 | <p>Privileges are cumulative. There can be multiple successful |
| 161 | 161 | login cards. The session privileges are the bit-wise OR of the |
| 162 | 162 | privileges of each individual login.</p> |
| 163 | 163 | |
| 164 | -<h3>3.3 File Cards</h3> | |
| 164 | +<h3>3.3 File and Compressed File Cards</h3> | |
| 165 | 165 | |
| 166 | -<p>Artifacts are transferred using "file" cards. (The name "file" | |
| 167 | -card comes from the fact that most artifacts correspond to files.) | |
| 168 | -File cards come in two different formats depending | |
| 166 | +<p>Artifacts are transferred using either "file" cards, or "cfile" cards. | |
| 167 | +(The name "file" card comes from the fact that most artifacts correspond to | |
| 168 | +files, and "cfile" is just a compressed file.) | |
| 169 | +</p> | |
| 170 | + | |
| 171 | +<h4>3.3.1 File Cards</h4> | |
| 172 | + | |
| 173 | +<p>For sync protocols, artifacts are transferred using "file" | |
| 174 | +cards. File cards come in two different formats depending | |
| 169 | 175 | on whether the artifact is sent directly or as a delta from some |
| 170 | 176 | other artifact.</p> |
| 171 | 177 | |
| 172 | 178 | <blockquote> |
| 173 | 179 | <b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i><br> |
| @@ -176,11 +182,11 @@ | ||
| 176 | 182 | |
| 177 | 183 | <p>File cards are different from all other cards in that they |
| 178 | 184 | followed by in-line "payload" data. The content of the artifact |
| 179 | 185 | or the artifact delta consists of the first <i>size</i> bytes of the |
| 180 | 186 | x-fossil content that immediately follow the newline that |
| 181 | -terminates the file card. No other cards have this characteristic. | |
| 187 | +terminates the file card. Only file and cfile cards have this characteristic. | |
| 182 | 188 | </p> |
| 183 | 189 | |
| 184 | 190 | <p>The first argument of a file card is the ID of the artifact that |
| 185 | 191 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 186 | 192 | representation of the SHA1 hash of the artifact. |
| @@ -194,10 +200,43 @@ | ||
| 194 | 200 | <p>File cards are sent in both directions: client to server and |
| 195 | 201 | server to client. A delta might be sent before the source of |
| 196 | 202 | the delta, so both client and server should remember deltas |
| 197 | 203 | and be able to apply them when their source arrives.</p> |
| 198 | 204 | |
| 205 | +<h4>3.3.2 Compressed File Cards</h4> | |
| 206 | + | |
| 207 | +<p>A client that sends a clone protocol version "3" or greater will | |
| 208 | +receive artifacts as "cfile" cards while cloning. This card was | |
| 209 | +introduced to improve the speed of the transfer of content by sending the | |
| 210 | +compressed artifact directly from the server database to the client.</p> | |
| 211 | + | |
| 212 | +<p>Compressed File cards are similar to File cards, sharing the same | |
| 213 | +in-line "payload" data characteristics and also the same treatment of | |
| 214 | +direct content or delta content. It comes in two different formats | |
| 215 | +depending on whether the artifact is sent directly or as a delta from | |
| 216 | +some other artifact.</p> | |
| 217 | + | |
| 218 | +<blockquote> | |
| 219 | +<b>cfile</b> <i>artifact-id usize csize</i> <b>\n</b> <i>content</i><br> | |
| 220 | +<b>cfile</b> <i>artifact-id delta-artifact-id usize csize</i> <b>\n</b> <i>content</i><br> | |
| 221 | +</blockquote> | |
| 222 | + | |
| 223 | +<p>The first argument of the cfile card is the ID of the artifact that | |
| 224 | +is being transferred. The artifact ID is the lower-case hexadecimal | |
| 225 | +representation of the SHA1 hash of the artifact. The second argument of | |
| 226 | +the cfile card is the original size in bytes of the artifact. The last | |
| 227 | +argument of the cfile card is the number of compressed bytes of payload | |
| 228 | +that immediately follow the cfile card. If the cfile card has only | |
| 229 | +three arguments, that means the payload is the complete content of the | |
| 230 | +artifact. If the cfile card has four arguments, then the payload is a | |
| 231 | +delta and the second argument is the ID of another artifact that is the | |
| 232 | +source of the delta and the third argument is the original size of the | |
| 233 | +delta artifact.</p> | |
| 234 | + | |
| 235 | +<p>Unlike file cards, cfile cards are only sent in one direction during a | |
| 236 | +clone from server to client for clone protocol version "3" or greater.</p> | |
| 237 | + | |
| 199 | 238 | <h3>3.4 Push and Pull Cards</h3> |
| 200 | 239 | |
| 201 | 240 | <p>Among the first cards in a client-to-server message are |
| 202 | 241 | the push and pull cards. The push card tells the server that |
| 203 | 242 | the client is pushing content. The pull card tells the server |
| @@ -232,15 +271,22 @@ | ||
| 232 | 271 | <blockquote> |
| 233 | 272 | <b>clone</b><br> |
| 234 | 273 | <b>clone</b> <i>protocol-version sequence-number</i> |
| 235 | 274 | </blockquote> |
| 236 | 275 | |
| 237 | -<h4>3.5.1 Protocol 2</h4> | |
| 276 | +<h4>3.5.1 Protocol 3</h4> | |
| 238 | 277 | |
| 239 | 278 | <p>The latest clients send a two-argument clone message with a |
| 240 | -protocol version of "2". (Future versions of Fossil might use larger | |
| 241 | -protocol version numbers.) The sequence-number sent is the number | |
| 279 | +protocol version of "3". (Future versions of Fossil might use larger | |
| 280 | +protocol version numbers.) Version "3" of the protocol enhanced version | |
| 281 | +"2" by introducing the "cfile" card which is intended to speed up clone | |
| 282 | +operations. Instead of sending "file" cards, the server will send "cfile" | |
| 283 | +cards</p> | |
| 284 | + | |
| 285 | +<h4>3.5.2 Protocol 2</h4> | |
| 286 | + | |
| 287 | +<p>The sequence-number sent is the number | |
| 242 | 288 | of artifacts received so far. For the first clone message, the |
| 243 | 289 | sequence number is 0. The server will respond by sending file |
| 244 | 290 | cards for some number of artifacts up to the maximum message size. |
| 245 | 291 | |
| 246 | 292 | <p>The server will also send a single "clone_seqno" card to the client |
| @@ -256,11 +302,11 @@ | ||
| 256 | 302 | |
| 257 | 303 | <p>In response to an initial clone message, the server also sends the client |
| 258 | 304 | a push message so that the client can discover the projectcode for |
| 259 | 305 | this project.</p> |
| 260 | 306 | |
| 261 | -<h4>3.5.2 Legacy Protocol</h4> | |
| 307 | +<h4>3.5.3 Legacy Protocol</h4> | |
| 262 | 308 | |
| 263 | 309 | <p>Older clients send a clone card with no argument. The server responds |
| 264 | 310 | to a blank clone card by sending an "igot" card for every artifact in the |
| 265 | 311 | repository. The client will then issue "gimme" cards to pull down all the |
| 266 | 312 | content it needs. |
| 267 | 313 |
| --- www/sync.wiki | |
| +++ www/sync.wiki | |
| @@ -159,15 +159,21 @@ | |
| 159 | |
| 160 | <p>Privileges are cumulative. There can be multiple successful |
| 161 | login cards. The session privileges are the bit-wise OR of the |
| 162 | privileges of each individual login.</p> |
| 163 | |
| 164 | <h3>3.3 File Cards</h3> |
| 165 | |
| 166 | <p>Artifacts are transferred using "file" cards. (The name "file" |
| 167 | card comes from the fact that most artifacts correspond to files.) |
| 168 | File cards come in two different formats depending |
| 169 | on whether the artifact is sent directly or as a delta from some |
| 170 | other artifact.</p> |
| 171 | |
| 172 | <blockquote> |
| 173 | <b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i><br> |
| @@ -176,11 +182,11 @@ | |
| 176 | |
| 177 | <p>File cards are different from all other cards in that they |
| 178 | followed by in-line "payload" data. The content of the artifact |
| 179 | or the artifact delta consists of the first <i>size</i> bytes of the |
| 180 | x-fossil content that immediately follow the newline that |
| 181 | terminates the file card. No other cards have this characteristic. |
| 182 | </p> |
| 183 | |
| 184 | <p>The first argument of a file card is the ID of the artifact that |
| 185 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 186 | representation of the SHA1 hash of the artifact. |
| @@ -194,10 +200,43 @@ | |
| 194 | <p>File cards are sent in both directions: client to server and |
| 195 | server to client. A delta might be sent before the source of |
| 196 | the delta, so both client and server should remember deltas |
| 197 | and be able to apply them when their source arrives.</p> |
| 198 | |
| 199 | <h3>3.4 Push and Pull Cards</h3> |
| 200 | |
| 201 | <p>Among the first cards in a client-to-server message are |
| 202 | the push and pull cards. The push card tells the server that |
| 203 | the client is pushing content. The pull card tells the server |
| @@ -232,15 +271,22 @@ | |
| 232 | <blockquote> |
| 233 | <b>clone</b><br> |
| 234 | <b>clone</b> <i>protocol-version sequence-number</i> |
| 235 | </blockquote> |
| 236 | |
| 237 | <h4>3.5.1 Protocol 2</h4> |
| 238 | |
| 239 | <p>The latest clients send a two-argument clone message with a |
| 240 | protocol version of "2". (Future versions of Fossil might use larger |
| 241 | protocol version numbers.) The sequence-number sent is the number |
| 242 | of artifacts received so far. For the first clone message, the |
| 243 | sequence number is 0. The server will respond by sending file |
| 244 | cards for some number of artifacts up to the maximum message size. |
| 245 | |
| 246 | <p>The server will also send a single "clone_seqno" card to the client |
| @@ -256,11 +302,11 @@ | |
| 256 | |
| 257 | <p>In response to an initial clone message, the server also sends the client |
| 258 | a push message so that the client can discover the projectcode for |
| 259 | this project.</p> |
| 260 | |
| 261 | <h4>3.5.2 Legacy Protocol</h4> |
| 262 | |
| 263 | <p>Older clients send a clone card with no argument. The server responds |
| 264 | to a blank clone card by sending an "igot" card for every artifact in the |
| 265 | repository. The client will then issue "gimme" cards to pull down all the |
| 266 | content it needs. |
| 267 |
| --- www/sync.wiki | |
| +++ www/sync.wiki | |
| @@ -159,15 +159,21 @@ | |
| 159 | |
| 160 | <p>Privileges are cumulative. There can be multiple successful |
| 161 | login cards. The session privileges are the bit-wise OR of the |
| 162 | privileges of each individual login.</p> |
| 163 | |
| 164 | <h3>3.3 File and Compressed File Cards</h3> |
| 165 | |
| 166 | <p>Artifacts are transferred using either "file" cards, or "cfile" cards. |
| 167 | (The name "file" card comes from the fact that most artifacts correspond to |
| 168 | files, and "cfile" is just a compressed file.) |
| 169 | </p> |
| 170 | |
| 171 | <h4>3.3.1 File Cards</h4> |
| 172 | |
| 173 | <p>For sync protocols, artifacts are transferred using "file" |
| 174 | cards. File cards come in two different formats depending |
| 175 | on whether the artifact is sent directly or as a delta from some |
| 176 | other artifact.</p> |
| 177 | |
| 178 | <blockquote> |
| 179 | <b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i><br> |
| @@ -176,11 +182,11 @@ | |
| 182 | |
| 183 | <p>File cards are different from all other cards in that they |
| 184 | followed by in-line "payload" data. The content of the artifact |
| 185 | or the artifact delta consists of the first <i>size</i> bytes of the |
| 186 | x-fossil content that immediately follow the newline that |
| 187 | terminates the file card. Only file and cfile cards have this characteristic. |
| 188 | </p> |
| 189 | |
| 190 | <p>The first argument of a file card is the ID of the artifact that |
| 191 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 192 | representation of the SHA1 hash of the artifact. |
| @@ -194,10 +200,43 @@ | |
| 200 | <p>File cards are sent in both directions: client to server and |
| 201 | server to client. A delta might be sent before the source of |
| 202 | the delta, so both client and server should remember deltas |
| 203 | and be able to apply them when their source arrives.</p> |
| 204 | |
| 205 | <h4>3.3.2 Compressed File Cards</h4> |
| 206 | |
| 207 | <p>A client that sends a clone protocol version "3" or greater will |
| 208 | receive artifacts as "cfile" cards while cloning. This card was |
| 209 | introduced to improve the speed of the transfer of content by sending the |
| 210 | compressed artifact directly from the server database to the client.</p> |
| 211 | |
| 212 | <p>Compressed File cards are similar to File cards, sharing the same |
| 213 | in-line "payload" data characteristics and also the same treatment of |
| 214 | direct content or delta content. It comes in two different formats |
| 215 | depending on whether the artifact is sent directly or as a delta from |
| 216 | some other artifact.</p> |
| 217 | |
| 218 | <blockquote> |
| 219 | <b>cfile</b> <i>artifact-id usize csize</i> <b>\n</b> <i>content</i><br> |
| 220 | <b>cfile</b> <i>artifact-id delta-artifact-id usize csize</i> <b>\n</b> <i>content</i><br> |
| 221 | </blockquote> |
| 222 | |
| 223 | <p>The first argument of the cfile card is the ID of the artifact that |
| 224 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 225 | representation of the SHA1 hash of the artifact. The second argument of |
| 226 | the cfile card is the original size in bytes of the artifact. The last |
| 227 | argument of the cfile card is the number of compressed bytes of payload |
| 228 | that immediately follow the cfile card. If the cfile card has only |
| 229 | three arguments, that means the payload is the complete content of the |
| 230 | artifact. If the cfile card has four arguments, then the payload is a |
| 231 | delta and the second argument is the ID of another artifact that is the |
| 232 | source of the delta and the third argument is the original size of the |
| 233 | delta artifact.</p> |
| 234 | |
| 235 | <p>Unlike file cards, cfile cards are only sent in one direction during a |
| 236 | clone from server to client for clone protocol version "3" or greater.</p> |
| 237 | |
| 238 | <h3>3.4 Push and Pull Cards</h3> |
| 239 | |
| 240 | <p>Among the first cards in a client-to-server message are |
| 241 | the push and pull cards. The push card tells the server that |
| 242 | the client is pushing content. The pull card tells the server |
| @@ -232,15 +271,22 @@ | |
| 271 | <blockquote> |
| 272 | <b>clone</b><br> |
| 273 | <b>clone</b> <i>protocol-version sequence-number</i> |
| 274 | </blockquote> |
| 275 | |
| 276 | <h4>3.5.1 Protocol 3</h4> |
| 277 | |
| 278 | <p>The latest clients send a two-argument clone message with a |
| 279 | protocol version of "3". (Future versions of Fossil might use larger |
| 280 | protocol version numbers.) Version "3" of the protocol enhanced version |
| 281 | "2" by introducing the "cfile" card which is intended to speed up clone |
| 282 | operations. Instead of sending "file" cards, the server will send "cfile" |
| 283 | cards</p> |
| 284 | |
| 285 | <h4>3.5.2 Protocol 2</h4> |
| 286 | |
| 287 | <p>The sequence-number sent is the number |
| 288 | of artifacts received so far. For the first clone message, the |
| 289 | sequence number is 0. The server will respond by sending file |
| 290 | cards for some number of artifacts up to the maximum message size. |
| 291 | |
| 292 | <p>The server will also send a single "clone_seqno" card to the client |
| @@ -256,11 +302,11 @@ | |
| 302 | |
| 303 | <p>In response to an initial clone message, the server also sends the client |
| 304 | a push message so that the client can discover the projectcode for |
| 305 | this project.</p> |
| 306 | |
| 307 | <h4>3.5.3 Legacy Protocol</h4> |
| 308 | |
| 309 | <p>Older clients send a clone card with no argument. The server responds |
| 310 | to a blank clone card by sending an "igot" card for every artifact in the |
| 311 | repository. The client will then issue "gimme" cards to pull down all the |
| 312 | content it needs. |
| 313 |