Fix some documentation and other issues with the code on this branch.

FossilOrigin-Name: a9ec68627a4533ca6aa7cc1b73f864db615a80e86eda9e33660f22d269a1ba1e

ext/session/sessionrebase.test

@@ -376,6 +376,13 @@ foreach {tn p} {
     INSERT INTO abcdefghijkl VALUES(22, 25, 26);
     UPDATE abcdefghijkl SET y=400 WHERE x=22;
   } [list $p $p $p $p $p $p $p $p]
+
+  do_rebase_test 3.4.$tn {
+    INSERT INTO abcdefghijkl VALUES(22, 23, 24);
+  } {
+    INSERT INTO abcdefghijkl VALUES(22, 25, 26);
+    UPDATE abcdefghijkl SET y=400 WHERE x=22;
+  } [list REPLACE $p]
 }
 
 finish_test

ext/session/sqlite3session.c

@@ -3681,7 +3681,6 @@ static int sessionStat1Sql(sqlite3 *db, SessionApplyCtx *p){
         "AND (?4 OR stat IS ?3)"
     );
   }
-  assert( rc==SQLITE_OK );
   return rc;
 }
 
@@ -4384,7 +4383,7 @@ static int sessionChangesetApply(
     sqlite3_exec(db, "RELEASE changeset_apply", 0, 0, 0);
   }
 
-  if( rc==SQLITE_OK && ppRebase && pnRebase ){
+  if( rc==SQLITE_OK && bPatchset==0 && ppRebase && pnRebase ){
     *ppRebase = (void*)sApply.rebase.aBuf;
     *pnRebase = sApply.rebase.nBuf;
     sApply.rebase.aBuf = 0;
@@ -5146,6 +5145,11 @@ static int sessionRebase(
       }
       bNew = 0;
 
+      /* A patchset may not be rebased */
+      if( pIter->bPatchset ){
+        rc = SQLITE_ERROR;
+      }
+
       /* Append a table header to the output for this new table */
       sessionAppendByte(&sOut, pIter->bPatchset ? 'P' : 'T', &rc);
       sessionAppendVarint(&sOut, pIter->nCol, &rc);

ext/session/sqlite3session.h

@@ -948,19 +948,18 @@ void sqlite3changegroup_delete(sqlite3_changegroup*);
 /*
 ** CAPI3REF: Apply A Changeset To A Database
 **
-** Apply a changeset to a database. This function attempts to update the
+** Apply a changeset or patchset to a database. These functions attempt to
-** "main" database attached to handle db with the changes found in the
+** update the "main" database attached to handle db with the changes found in
-** changeset passed via the second and third arguments.
+** the changeset passed via the second and third arguments. 
 **
-** The fourth argument (xFilter) passed to this function is the "filter
+** The fourth argument (xFilter) passed to these functions is the "filter
 ** callback". If it is not NULL, then for each table affected by at least one
 ** change in the changeset, the filter callback is invoked with
 ** the table name as the second argument, and a copy of the context pointer
-** passed as the sixth argument to this function as the first. If the "filter
+** passed as the sixth argument as the first. If the "filter callback"
-** callback" returns zero, then no attempt is made to apply any changes to 
+** returns zero, then no attempt is made to apply any changes to the table.
-** the table. Otherwise, if the return value is non-zero or the xFilter
+** Otherwise, if the return value is non-zero or the xFilter argument to
-** argument to this function is NULL, all changes related to the table are
+** is NULL, all changes related to the table are attempted.
-** attempted.
 **
 ** For each table that is not excluded by the filter callback, this function 
 ** tests that the target database contains a compatible table. A table is 
@@ -1005,7 +1004,7 @@ void sqlite3changegroup_delete(sqlite3_changegroup*);
 **
 ** <dl>
 ** <dt>DELETE Changes<dd>
-**   For each DELETE change, this function checks if the target database 
+**   For each DELETE change, the function checks if the target database 
 **   contains a row with the same primary key value (or values) as the 
 **   original row values stored in the changeset. If it does, and the values 
 **   stored in all non-primary key columns also match the values stored in 
@@ -1050,7 +1049,7 @@ void sqlite3changegroup_delete(sqlite3_changegroup*);
 **   [SQLITE_CHANGESET_REPLACE].
 **
 ** <dt>UPDATE Changes<dd>
-**   For each UPDATE change, this function checks if the target database 
+**   For each UPDATE change, the function checks if the target database 
 **   contains a row with the same primary key value (or values) as the 
 **   original row values stored in the changeset. If it does, and the values 
 **   stored in all modified non-primary key columns also match the values
@@ -1081,11 +1080,21 @@ void sqlite3changegroup_delete(sqlite3_changegroup*);
 ** This can be used to further customize the applications conflict
 ** resolution strategy.
 **
-** All changes made by this function are enclosed in a savepoint transaction.
+** All changes made by these functions are enclosed in a savepoint transaction.
 ** If any other error (aside from a constraint failure when attempting to
 ** write to the target database) occurs, then the savepoint transaction is
 ** rolled back, restoring the target database to its original state, and an 
 ** SQLite error code returned.
+**
+** If the output parameters (ppRebase) and (pnRebase) are non-NULL and
+** the input is a changeset (not a patchset), then sqlite3changeset_apply_v2()
+** may set (*ppRebase) to point to a "rebase" that may be used with the 
+** sqlite3_rebaser APIs buffer before returning. In this case (*pnRebase)
+** is set to the size of the buffer in bytes. It is the responsibility of the
+** caller to eventually free any such buffer using sqlite3_free(). The buffer
+** is only allocated and populated if one or more conflicts were encountered
+** while applying the patchset. See comments surrounding the sqlite3_rebaser
+** APIs for further details.
 */
 int sqlite3changeset_apply(
   sqlite3 *db,                    /* Apply change to "main" db of this handle */
@@ -1102,7 +1111,6 @@ int sqlite3changeset_apply(
   ),
   void *pCtx                      /* First argument passed to xConflict */
 );
-
 int sqlite3changeset_apply_v2(
   sqlite3 *db,                    /* Apply change to "main" db of this handle */
   int nChangeset,                 /* Size of changeset in bytes */
@@ -1294,26 +1302,76 @@ int sqlite3changeset_apply_v2(
 ** case of multiple remote UPDATE operations, some fields of a single 
 ** local change may be rebased for REPLACE while others are rebased for 
 ** OMIT.
+**
+** In order to rebase a local changeset, the remote changeset must first
+** be applied to the local database using sqlite3changeset_apply_v2() and
+** the buffer of rebase information captured. Then:
+**
+** <ol>
+**   <li> An sqlite3_rebaser object is created by calling 
+**        sqlite3rebaser_create().
+**   <li> The new object is configured with the rebase buffer obtained from
+**        sqlite3changeset_apply_v2() by calling sqlite3rebaser_configure().
+**        If the local changeset is to be rebased against multiple remote
+**        changesets, then sqlite3rebaser_configure() should be called
+**        multiple times, in the same order that the multiple
+**        sqlite3changeset_apply_v2() calls were made.
+**   <li> Each local changeset is rebased by calling sqlite3rebaser_rebase().
+**   <li> The sqlite3_rebaser object is deleted by calling
+**        sqlite3rebaser_delete().
+** </ol>
 */
 typedef struct sqlite3_rebaser sqlite3_rebaser;
 
-/* Create a new rebaser object */
+/*
+** CAPIREF: Create a changeset rebaser object.
+**
+** Allocate a new changeset rebaser object. If successful, set (*ppNew) to
+** point to the new object and return SQLITE_OK. Otherwise, if an error
+** occurs, return an SQLite error code (e.g. SQLITE_NOMEM) and set (*ppNew) 
+** to NULL. 
+*/
 int sqlite3rebaser_create(sqlite3_rebaser **ppNew);
 
-/* Call this one or more times to configure a rebaser */
+/*
+** CAPIREF: Configure a changeset rebaser object.
+**
+** Configure the changeset rebaser object to rebase changesets according
+** to the conflict resolutions described by buffer pRebase (size nRebase
+** bytes), which must have been obtained from a previous call to
+** sqlite3changeset_apply_v2().
+*/
 int sqlite3rebaser_configure(
   sqlite3_rebaser*, 
   int nRebase, const void *pRebase
 ); 
 
-/* Rebase a changeset according to current rebaser configuration */
+/*
+** CAPIREF: Rebase a changeset
+**
+** Argument pIn must point to a buffer containing a changeset nIn bytes
+** in size. This function allocates and populates a buffer with a copy
+** of the changeset rebased rebased according to the configuration of the
+** rebaser object passed as the first argument. If successful, (*ppOut)
+** is set to point to the new buffer containing the rebased changset and 
+** (*pnOut) to its size in bytes and SQLITE_OK returned. It is the
+** responsibility of the caller to eventually free the new buffer using
+** sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut)
+** are set to zero and an SQLite error code returned.
+*/
 int sqlite3rebaser_rebase(
   sqlite3_rebaser*,
   int nIn, const void *pIn, 
   int *pnOut, void **ppOut 
 );
 
-/* Destroy a rebaser object */
+/*
+** CAPIREF: Delete a changeset rebaser object.
+**
+** Delete the changeset rebaser object and all associated resources. There
+** should be one call to this function for each successful invocation
+** of sqlite3rebaser_create().
+*/
 void sqlite3rebaser_delete(sqlite3_rebaser *p); 
 
 /*

manifest

@@ -1,5 +1,5 @@
-C Fix\srebasing\sof\sUPDATE\schanges\sagainst\sa\sset\sof\sremote\schangesets\sthat\sfeature\nboth\sOMIT\sand\sREPLACE\sconflict\sresolution\son\sdifferent\sfields\sof\sthe\ssame\srow.
+C Fix\ssome\sdocumentation\sand\sother\sissues\swith\sthe\scode\son\sthis\sbranch.
-D 2018-03-21T17:29:53.542
+D 2018-03-21T19:46:36.826
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F Makefile.in 7016fc56c6b9bfe5daac4f34be8be38d8c0b5fab79ccbfb764d3b23bf1c6fff3
@@ -400,11 +400,11 @@ F ext/session/sessionat.test efe88965e74ff1bc2af9c310b28358c02d420c1fb2705cc7a28
 F ext/session/sessiondiff.test ad13dd65664bae26744e1f18eb3cbd5588349b7e9118851d8f9364248d67bcec
 F ext/session/sessionfault.test da273f2712b6411e85e71465a1733b8501dbf6f7
 F ext/session/sessionfault2.test 883c8919ebcf6c140ba86b480bc14ae642ee9969c009e0b355c8981a5266f9ed
-F ext/session/sessionrebase.test 5dd3d468710631fb389262d46b4768684bf3e5c43a8671992be8ce78e2e14cba
+F ext/session/sessionrebase.test 7cb11b80e6bc13756ac8a51a0601a11f124ee1aa3b1e9eab61ed660b8cab0ef4
 F ext/session/sessionstat1.test 41cd97c2e48619a41cdf8ae749e1b25f34719de638689221aa43971be693bf4e
 F ext/session/sessionwor.test 2f3744236dc8b170a695b7d8ddc8c743c7e79fdc
-F ext/session/sqlite3session.c c2256416b2fa5ffdcf18175ca92506e6776f831ee4f59633b5195845c1ca3dfe
+F ext/session/sqlite3session.c f817bf0360da914bf353797347ed53dd08fda46bcef0d9e827a4c8cf956008aa
-F ext/session/sqlite3session.h be3ec8ab03e1b6251d45d38349e0c57b1a745e291c6f76c2ffd33dadd44d5db3
+F ext/session/sqlite3session.h 5f40a0660ff972c0c50f5fd6b33488fdbd2eb0c1244ea95777f8dbd5e529be04
 F ext/session/test_session.c f253742ea01b089326f189b5ae15a5b55c1c9e97452e4a195ee759ba51b404d5
 F ext/userauth/sqlite3userauth.h 7f3ea8c4686db8e40b0a0e7a8e0b00fac13aa7a3
 F ext/userauth/user-auth.txt e6641021a9210364665fe625d067617d03f27b04
@@ -1713,7 +1713,7 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 7475a363ebb272ae23c0796fe7587714a156dc6a3a4a57ed948ed6f69d3c1218
+P d8bc3fdb6ba165ca8d7cab857ede8e7e6e2fac24ad59580c5e1db1a4942d295c
-R 3c5c6f568034d51df9227a4faa7f0dcd
+R 9dca9b6b419ea7dcdd6c7349b961b063
 U dan
-Z cbf4222d0200eaa670f79abf0e02a69a
+Z 2bd9e2b5f750bb24220e9fd7d7a0ebe6

manifest.uuid

@@ -1 +1 @@
-d8bc3fdb6ba165ca8d7cab857ede8e7e6e2fac24ad59580c5e1db1a4942d295c
+a9ec68627a4533ca6aa7cc1b73f864db615a80e86eda9e33660f22d269a1ba1e