Fossil SCM
Refinements to the "sync protocol" document.
Commit
aa2fdc286c5e6739e5dbdd69473473c482cc3a6e
Parent
a17ed85c08993b4…
1 file changed
+126
-6
+126
-6
| --- www/sync.wiki | ||
| +++ www/sync.wiki | ||
| @@ -223,21 +223,56 @@ | ||
| 223 | 223 | |
| 224 | 224 | <h3>3.5 Clone Cards</h3> |
| 225 | 225 | |
| 226 | 226 | <p>A clone card works like a pull card in that it is sent from |
| 227 | 227 | client to server in order to tell the server that the client |
| 228 | -wants to pull content. But unlike the pull card, the clone | |
| 229 | -card has no arguments.</p> | |
| 228 | +wants to pull content. The clone card comes in two formats. Older | |
| 229 | +clients use the no-argument format and newer clients use the | |
| 230 | +two-argument format.</p> | |
| 231 | + | |
| 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 since 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 if 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 | |
| 247 | +so that the client can know where the server left off. | |
| 230 | 248 | |
| 231 | 249 | <blockquote> |
| 232 | -<b>clone</b> | |
| 250 | +<b>clone_seqno</b> <i>sequence-number</i> | |
| 233 | 251 | </blockquote> |
| 234 | 252 | |
| 235 | -<p>In response to a clone message, the server also sends the client | |
| 253 | +<p>The clone message in subquence HTTP requests for the same clone | |
| 254 | +operation will use the sequence-number from the | |
| 255 | +clone_seqno of the previous reply.</p> | |
| 256 | + | |
| 257 | +<p>In response to an initial clone message, the server also sends the client | |
| 236 | 258 | a push message so that the client can discover the projectcode for |
| 237 | 259 | this project.</p> |
| 238 | 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 | + | |
| 268 | +<p>The legacy protocol works well for smaller repositories (50MB with 50,000 | |
| 269 | +artifacts) but because too slow and unwieldy for larger repositories. | |
| 270 | +The version 2 protocol is an effort to improve performance. Further | |
| 271 | +performance improvements with higher-numbered clone protocols are | |
| 272 | +possible in future versions of Fossil. | |
| 273 | + | |
| 239 | 274 | <h3>3.6 Igot Cards</h3> |
| 240 | 275 | |
| 241 | 276 | <p>An igot card can be sent from either client to server or from |
| 242 | 277 | server to client in order to indicate that the sender holds a copy |
| 243 | 278 | of a particular artifact. The format is:</p> |
| @@ -287,15 +322,100 @@ | ||
| 287 | 322 | a cookie from another server. (Typically the server will embed |
| 288 | 323 | its servercode as part of the cookie.)</p> |
| 289 | 324 | |
| 290 | 325 | <h3>3.9 Request-Configuration Cards</h3> |
| 291 | 326 | |
| 292 | -<i>TBD...</i> | |
| 327 | +<p>A request-configuration or "reqconfig" card is sent from client to | |
| 328 | +server in order to request that the server send back "configuration" | |
| 329 | +data. "Configuration" data is information about users or website | |
| 330 | +appearance or other administrative details which are not part of the | |
| 331 | +persistent and versioned state of the project. For example, the "name" | |
| 332 | +of the project, the default Cascading Style Sheet (CSS) for the web-interface, | |
| 333 | +and the project logo displayed on the web-interface are all configuration | |
| 334 | +data elements. | |
| 335 | + | |
| 336 | +<p>The reqconfig card is normally sent in response to the | |
| 337 | +"fossil configuration pull" command. The format is as follows: | |
| 338 | + | |
| 339 | +<blockquote> | |
| 340 | +<b>reqconfig</b> <i>configuration-name</i> | |
| 341 | +</blockquote> | |
| 342 | + | |
| 343 | +<p>As of this writing ([2010-11-12]), the configuration-name must be one of the | |
| 344 | +following values: | |
| 345 | + | |
| 346 | +<center><table border=0> | |
| 347 | +<tr><td valign="top"> | |
| 348 | +<ul> | |
| 349 | +<li> css | |
| 350 | +<li> header | |
| 351 | +<li> footer | |
| 352 | +<li> logo-mimetype | |
| 353 | +<li> logo-image | |
| 354 | +<li> project-name | |
| 355 | +<li> project-description | |
| 356 | +<li> manifest | |
| 357 | +<li> index-page | |
| 358 | +<ul></td><td valign="top"><ul> | |
| 359 | +<li> timeline-block-markup | |
| 360 | +<li> timeline-max-comment | |
| 361 | +<li> ticket-table | |
| 362 | +<li> ticket-common | |
| 363 | +<li> ticket-newpage | |
| 364 | +<li> ticket-viewpage | |
| 365 | +<li> ticket-editpage | |
| 366 | +<li> ticket-reportlist | |
| 367 | +<li> ticket-report-template | |
| 368 | +<ul></td><td valign="top"><ul> | |
| 369 | +<li> ticket-key-template | |
| 370 | +<li> ticket-title-expr | |
| 371 | +<li> ticket-closed-expr | |
| 372 | +<li> @reportfmt | |
| 373 | +<li> @user | |
| 374 | +<li> @concealed | |
| 375 | +<li> @shun | |
| 376 | +</ul></td></tr> | |
| 377 | +</table></center> | |
| 378 | + | |
| 379 | +<p>New configuration-names are likely to be added in future releases of | |
| 380 | +Fossil. If the server receives a configuration-name that it does not | |
| 381 | +understand, the entire reqconfig card is silently ignored. The reqconfig | |
| 382 | +card might also be ignored if the user lacks sufficient privilege to | |
| 383 | +access the requested information. | |
| 384 | + | |
| 385 | +<p>The configuration-names that begin with an alphabetic character refer | |
| 386 | +to values in the "config" table of the server database. For example, | |
| 387 | +the "logo-image" configuration item refers to the project logo image | |
| 388 | +that is configured on the Admin page of the [./webui.wiki | web-interface]. | |
| 389 | +The value of the configuration item is returned to the client using a | |
| 390 | +"config" card. | |
| 391 | + | |
| 392 | +<p>If the configuration-name begins with "@", that refers to a class of | |
| 393 | +values instead of a single value. The content of these configuration items | |
| 394 | +is returned in a "config" card that contains pure SQL text that is | |
| 395 | +intended to evaluated by the client. | |
| 396 | + | |
| 397 | +<p>The @user and @concealed configuration items contain sensitive information | |
| 398 | +are ignored for clients without sufficient privilege. | |
| 293 | 399 | |
| 294 | 400 | <h3>3.10 Configuration Cards</h3> |
| 295 | 401 | |
| 296 | -<i>TBD...</i> | |
| 402 | +<p>A "config" card is used to send configuration information from client | |
| 403 | +to server (in response to a "fossil configuration push" command) or | |
| 404 | +from server to client (in response to a "fossil configuration pull" or | |
| 405 | +"fossil clone" command). The format is as follows: | |
| 406 | + | |
| 407 | +<blockquote> | |
| 408 | +<b>config</b> <i>configuration-name size</i> <b>\n</b> <i>content</i> | |
| 409 | +</blockquote> | |
| 410 | + | |
| 411 | +<p>The server will only accept a config card if the user has | |
| 412 | +"Admin" privilege. A client will only accept a config card if | |
| 413 | +it had sent a correponding reqconfig card in its request. | |
| 414 | + | |
| 415 | +<p>The content of the configuration item is used to overwrite the | |
| 416 | +corresponding configuration data in the receiver. | |
| 297 | 417 | |
| 298 | 418 | <h3>3.11 Error Cards</h3> |
| 299 | 419 | |
| 300 | 420 | <p>If the server discovers anything wrong with a request, it generates |
| 301 | 421 | an error card in its reply. When the client sees the error card, |
| 302 | 422 |
| --- www/sync.wiki | |
| +++ www/sync.wiki | |
| @@ -223,21 +223,56 @@ | |
| 223 | |
| 224 | <h3>3.5 Clone Cards</h3> |
| 225 | |
| 226 | <p>A clone card works like a pull card in that it is sent from |
| 227 | client to server in order to tell the server that the client |
| 228 | wants to pull content. But unlike the pull card, the clone |
| 229 | card has no arguments.</p> |
| 230 | |
| 231 | <blockquote> |
| 232 | <b>clone</b> |
| 233 | </blockquote> |
| 234 | |
| 235 | <p>In response to a clone message, the server also sends the client |
| 236 | a push message so that the client can discover the projectcode for |
| 237 | this project.</p> |
| 238 | |
| 239 | <h3>3.6 Igot Cards</h3> |
| 240 | |
| 241 | <p>An igot card can be sent from either client to server or from |
| 242 | server to client in order to indicate that the sender holds a copy |
| 243 | of a particular artifact. The format is:</p> |
| @@ -287,15 +322,100 @@ | |
| 287 | a cookie from another server. (Typically the server will embed |
| 288 | its servercode as part of the cookie.)</p> |
| 289 | |
| 290 | <h3>3.9 Request-Configuration Cards</h3> |
| 291 | |
| 292 | <i>TBD...</i> |
| 293 | |
| 294 | <h3>3.10 Configuration Cards</h3> |
| 295 | |
| 296 | <i>TBD...</i> |
| 297 | |
| 298 | <h3>3.11 Error Cards</h3> |
| 299 | |
| 300 | <p>If the server discovers anything wrong with a request, it generates |
| 301 | an error card in its reply. When the client sees the error card, |
| 302 |
| --- www/sync.wiki | |
| +++ www/sync.wiki | |
| @@ -223,21 +223,56 @@ | |
| 223 | |
| 224 | <h3>3.5 Clone Cards</h3> |
| 225 | |
| 226 | <p>A clone card works like a pull card in that it is sent from |
| 227 | client to server in order to tell the server that the client |
| 228 | wants to pull content. The clone card comes in two formats. Older |
| 229 | clients use the no-argument format and newer clients use the |
| 230 | two-argument format.</p> |
| 231 | |
| 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 since 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 if 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 |
| 247 | so that the client can know where the server left off. |
| 248 | |
| 249 | <blockquote> |
| 250 | <b>clone_seqno</b> <i>sequence-number</i> |
| 251 | </blockquote> |
| 252 | |
| 253 | <p>The clone message in subquence HTTP requests for the same clone |
| 254 | operation will use the sequence-number from the |
| 255 | clone_seqno of the previous reply.</p> |
| 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 | |
| 268 | <p>The legacy protocol works well for smaller repositories (50MB with 50,000 |
| 269 | artifacts) but because too slow and unwieldy for larger repositories. |
| 270 | The version 2 protocol is an effort to improve performance. Further |
| 271 | performance improvements with higher-numbered clone protocols are |
| 272 | possible in future versions of Fossil. |
| 273 | |
| 274 | <h3>3.6 Igot Cards</h3> |
| 275 | |
| 276 | <p>An igot card can be sent from either client to server or from |
| 277 | server to client in order to indicate that the sender holds a copy |
| 278 | of a particular artifact. The format is:</p> |
| @@ -287,15 +322,100 @@ | |
| 322 | a cookie from another server. (Typically the server will embed |
| 323 | its servercode as part of the cookie.)</p> |
| 324 | |
| 325 | <h3>3.9 Request-Configuration Cards</h3> |
| 326 | |
| 327 | <p>A request-configuration or "reqconfig" card is sent from client to |
| 328 | server in order to request that the server send back "configuration" |
| 329 | data. "Configuration" data is information about users or website |
| 330 | appearance or other administrative details which are not part of the |
| 331 | persistent and versioned state of the project. For example, the "name" |
| 332 | of the project, the default Cascading Style Sheet (CSS) for the web-interface, |
| 333 | and the project logo displayed on the web-interface are all configuration |
| 334 | data elements. |
| 335 | |
| 336 | <p>The reqconfig card is normally sent in response to the |
| 337 | "fossil configuration pull" command. The format is as follows: |
| 338 | |
| 339 | <blockquote> |
| 340 | <b>reqconfig</b> <i>configuration-name</i> |
| 341 | </blockquote> |
| 342 | |
| 343 | <p>As of this writing ([2010-11-12]), the configuration-name must be one of the |
| 344 | following values: |
| 345 | |
| 346 | <center><table border=0> |
| 347 | <tr><td valign="top"> |
| 348 | <ul> |
| 349 | <li> css |
| 350 | <li> header |
| 351 | <li> footer |
| 352 | <li> logo-mimetype |
| 353 | <li> logo-image |
| 354 | <li> project-name |
| 355 | <li> project-description |
| 356 | <li> manifest |
| 357 | <li> index-page |
| 358 | <ul></td><td valign="top"><ul> |
| 359 | <li> timeline-block-markup |
| 360 | <li> timeline-max-comment |
| 361 | <li> ticket-table |
| 362 | <li> ticket-common |
| 363 | <li> ticket-newpage |
| 364 | <li> ticket-viewpage |
| 365 | <li> ticket-editpage |
| 366 | <li> ticket-reportlist |
| 367 | <li> ticket-report-template |
| 368 | <ul></td><td valign="top"><ul> |
| 369 | <li> ticket-key-template |
| 370 | <li> ticket-title-expr |
| 371 | <li> ticket-closed-expr |
| 372 | <li> @reportfmt |
| 373 | <li> @user |
| 374 | <li> @concealed |
| 375 | <li> @shun |
| 376 | </ul></td></tr> |
| 377 | </table></center> |
| 378 | |
| 379 | <p>New configuration-names are likely to be added in future releases of |
| 380 | Fossil. If the server receives a configuration-name that it does not |
| 381 | understand, the entire reqconfig card is silently ignored. The reqconfig |
| 382 | card might also be ignored if the user lacks sufficient privilege to |
| 383 | access the requested information. |
| 384 | |
| 385 | <p>The configuration-names that begin with an alphabetic character refer |
| 386 | to values in the "config" table of the server database. For example, |
| 387 | the "logo-image" configuration item refers to the project logo image |
| 388 | that is configured on the Admin page of the [./webui.wiki | web-interface]. |
| 389 | The value of the configuration item is returned to the client using a |
| 390 | "config" card. |
| 391 | |
| 392 | <p>If the configuration-name begins with "@", that refers to a class of |
| 393 | values instead of a single value. The content of these configuration items |
| 394 | is returned in a "config" card that contains pure SQL text that is |
| 395 | intended to evaluated by the client. |
| 396 | |
| 397 | <p>The @user and @concealed configuration items contain sensitive information |
| 398 | are ignored for clients without sufficient privilege. |
| 399 | |
| 400 | <h3>3.10 Configuration Cards</h3> |
| 401 | |
| 402 | <p>A "config" card is used to send configuration information from client |
| 403 | to server (in response to a "fossil configuration push" command) or |
| 404 | from server to client (in response to a "fossil configuration pull" or |
| 405 | "fossil clone" command). The format is as follows: |
| 406 | |
| 407 | <blockquote> |
| 408 | <b>config</b> <i>configuration-name size</i> <b>\n</b> <i>content</i> |
| 409 | </blockquote> |
| 410 | |
| 411 | <p>The server will only accept a config card if the user has |
| 412 | "Admin" privilege. A client will only accept a config card if |
| 413 | it had sent a correponding reqconfig card in its request. |
| 414 | |
| 415 | <p>The content of the configuration item is used to overwrite the |
| 416 | corresponding configuration data in the receiver. |
| 417 | |
| 418 | <h3>3.11 Error Cards</h3> |
| 419 | |
| 420 | <p>If the server discovers anything wrong with a request, it generates |
| 421 | an error card in its reply. When the client sees the error card, |
| 422 |