libsql-sqlite3: Add libsql_wal_get_frame() API

This patch adds a libsql_wal_get_frame() API to read the raw WAL frame
from a database.

You can use the API as follows (omitting error handling) to obtain all
the WAL frames in a database:

```c
static int sync_db(sqlite3 *db_primary, sqlite3 *db_backup){
  unsigned int max_frame;

  libsql_wal_frame_count(db_primary, &max_frame);

  for(int i=1; i<=max_frame; i++){
    char frame[4096+24];

    libsql_wal_get_frame(db_primary, i, frame, sizeof(frame));
  }
}
```

Author: penberg

libsql-sqlite3/src/main.c

@@ -2475,6 +2475,35 @@ int libsql_wal_frame_count(
 #endif
 }
 
+int libsql_wal_get_frame(
+  sqlite3* db,
+  unsigned int iFrame,
+  void *pBuf,
+  unsigned int nBuf
+){
+  int rc = SQLITE_OK;
+  Pager *pPager;
+
+#ifdef SQLITE_OMIT_WAL
+  UNUSED_PARAMETER(iFrame);
+  UNUSED_PARAMETER(nBuf);
+  UNUSED_PARAMETER(pBuf);
+  return SQLITE_OK;
+#else
+
+#ifdef SQLITE_ENABLE_API_ARMOR
+  if( !sqlite3SafetyCheckOk(db) ) return SQLITE_MISUSE_BKPT;
+#endif
+  
+    sqlite3_mutex_enter(db->mutex);
+    pPager = sqlite3BtreePager(db->aDb[0].pBt);
+    rc = sqlite3PagerWalReadFrameRaw(pPager, iFrame, pBuf, nBuf);
+    sqlite3_mutex_leave(db->mutex);
+  
+    return rc;
+#endif
+}
+
 /*
 ** Register a function to be invoked prior to each autovacuum that
 ** determines the number of pages to vacuum.

libsql-sqlite3/src/pager.c

@@ -7784,6 +7784,21 @@ int sqlite3PagerWalFrameCount(Pager *pPager, unsigned int *pnFrames){
   }
 }
 
+int sqlite3PagerWalReadFrameRaw(
+  Pager *pPager,
+  unsigned int iFrame,
+  void *pFrameOut,
+  unsigned int nFrameOutLen
+){
+  if( pagerUseWal(pPager) ){
+    unsigned int nFrameLen = 24+pPager->pageSize;
+    if( nFrameOutLen!=nFrameLen ) return SQLITE_MISUSE;
+    return pPager->wal->methods.xReadFrameRaw(pPager->wal->pData, iFrame, nFrameOutLen, pFrameOut);
+  }else{
+    return SQLITE_ERROR;
+  }
+}
+
 #ifdef SQLITE_ENABLE_SETLK_TIMEOUT
 /*
 ** If pager pPager is a wal-mode database not in exclusive locking mode,

libsql-sqlite3/src/pager.h

@@ -134,6 +134,7 @@ void sqlite3PagerSetBusyHandler(Pager*, int(*)(void *), void *);
 int sqlite3PagerSetPagesize(Pager*, u32*, int);
 Pgno sqlite3PagerMaxPageCount(Pager*, Pgno);
 int sqlite3PagerWalFrameCount(Pager *, unsigned int *);
+int sqlite3PagerWalReadFrame(Pager *, unsigned int, void *, unsigned int);
 
 void sqlite3PagerSetCachesize(Pager*, int);
 int sqlite3PagerSetSpillsize(Pager*, int);

libsql-sqlite3/src/sqlite.h.in

@@ -10573,6 +10573,17 @@ int libsql_wal_disable_checkpoint(sqlite3 *db);
 */
 int libsql_wal_frame_count(sqlite3*, unsigned int*);
 
+/*
+** CAPI3REF: Get a frame from the WAL file
+** METHOD: sqlite3
+**
+** ^The [libsql_wal_get_frame(D,I,P,S)] interface extracts frame I from
+** the WAL file for [database connection] D into memory obtained from
+** [sqlite3_malloc64()] and returns a pointer to that memory. The size of
+** the memory allocated is given by S.
+*/
+int libsql_wal_get_frame(sqlite3*, unsigned int, void*, unsigned int);
+
 /*
 ** CAPI3REF: Low-level system error code
 ** METHOD: sqlite3