Skip to main content

libdoltlite_sys/
lib.rs

1#![expect(non_snake_case, non_camel_case_types)]
2#![cfg_attr(not(test), no_std)]
3pub use self::error::*;
4
5use core::mem;
6#[cfg(not(feature = "loadable_extension"))]
7use core::sync::atomic::{AtomicI32, Ordering};
8
9mod error;
10
11// Keep Cargo's native curl/OpenSSL/zlib link metadata reachable through this
12// sys crate without exposing those low-level crates as part of its API.
13#[cfg(feature = "blockcachevfs")]
14extern crate curl_sys as _;
15#[cfg(feature = "blockcachevfs")]
16extern crate libz_sys as _;
17#[cfg(feature = "blockcachevfs")]
18extern crate openssl_sys as _;
19
20#[must_use]
21pub fn SQLITE_STATIC() -> sqlite3_destructor_type {
22    None
23}
24
25#[must_use]
26pub fn SQLITE_TRANSIENT() -> sqlite3_destructor_type {
27    Some(unsafe { mem::transmute::<isize, unsafe extern "C" fn(*mut core::ffi::c_void)>(-1_isize) })
28}
29
30#[allow(dead_code, clippy::all)]
31mod bindings {
32    include!(concat!(env!("OUT_DIR"), "/bindgen.rs"));
33}
34pub use bindings::*;
35
36/// Raw Cloud Backed SQLite block-cache VFS interface.
37#[cfg(feature = "blockcachevfs")]
38pub mod blockcachevfs {
39    use core::ffi::{c_char, c_int, c_void};
40
41    use super::{sqlite3, sqlite3_int64};
42
43    /// Opaque Cloud Backed SQLite VFS handle.
44    #[repr(C)]
45    pub struct sqlite3_bcvfs {
46        _private: [u8; 0],
47    }
48
49    /// Authentication callback used by the CBS VFS.
50    pub type sqlite3_bcvfs_auth_callback = unsafe extern "C" fn(
51        p_ctx: *mut c_void,
52        z_storage: *const c_char,
53        z_account: *const c_char,
54        z_container: *const c_char,
55        pz_auth_token: *mut *mut c_char,
56    ) -> c_int;
57
58    /// Request-boundary credential refresh callback for session-owned cloud VFSes.
59    pub type sqlite3_bcvfs_auth_refresh_callback = unsafe extern "C" fn(
60        p_ctx: *mut c_void,
61        z_storage: *const c_char,
62        z_account: *const c_char,
63        z_container: *const c_char,
64        reason: c_int,
65        pz_auth_token: *mut *mut c_char,
66    ) -> c_int;
67
68    /// Upload progress event with block and full-block-byte counts.
69    pub type sqlite3_bcvfs_upload_progress_callback =
70        unsafe extern "C" fn(*mut c_void, c_int, sqlite3_int64, sqlite3_int64);
71
72    /// A safe, credential-free terminal storage failure observed by the VFS.
73    pub type sqlite3_bcvfs_storage_failure_callback =
74        unsafe extern "C" fn(*mut c_void, c_int, c_int, c_int);
75
76    /// Busy callback used by an upload checkpoint.
77    pub type sqlite3_bcvfs_busy_callback = unsafe extern "C" fn(*mut c_void, c_int) -> c_int;
78
79    pub const SQLITE_BCV_CACHESIZE: c_int = 1;
80    pub const SQLITE_BCV_NREQUEST: c_int = 2;
81    pub const SQLITE_BCV_HTTPTIMEOUT: c_int = 3;
82    pub const SQLITE_BCV_CURLVERBOSE: c_int = 4;
83    pub const SQLITE_BCV_HTTPLOG_TIMEOUT: c_int = 5;
84    pub const SQLITE_BCV_HTTPLOG_NENTRY: c_int = 6;
85    /// Proactively stage dirty blocks once this percentage of the cache is occupied.
86    pub const SQLITE_BCV_STAGEWATERMARK: c_int = 7;
87    pub const SQLITE_BCV_AUTH_REQUEST: c_int = 0;
88    pub const SQLITE_BCV_AUTH_UNAUTHORIZED: c_int = 1;
89    pub const SQLITE_BCVFS_UPLOAD_PROGRESS_UPLOADED_BLOCK: c_int = 1;
90    pub const SQLITE_BCVFS_UPLOAD_PROGRESS_REUSED_BLOCK: c_int = 2;
91    pub const SQLITE_BCVFS_UPLOAD_PROGRESS_PLAN: c_int = 3;
92    pub const SQLITE_BCVFS_STORAGE_FAILURE_CAUSE_SQLITE: c_int = 0;
93    pub const SQLITE_BCVFS_STORAGE_FAILURE_CAUSE_HTTP: c_int = 1;
94    pub const SQLITE_BCVFS_STORAGE_FAILURE_LOCAL_CACHE: c_int = 1;
95    pub const SQLITE_BCVFS_STORAGE_FAILURE_BLOCK_READ: c_int = 2;
96    pub const SQLITE_BCVFS_STORAGE_FAILURE_STAGE_PUT: c_int = 3;
97    pub const SQLITE_BCVFS_STORAGE_FAILURE_VERIFY_EXISTING: c_int = 4;
98    pub const SQLITE_BCVFS_STORAGE_FAILURE_PROTECT_SESSION: c_int = 5;
99    pub const SQLITE_BCVFS_STORAGE_FAILURE_FINAL_PUT: c_int = 6;
100    pub const SQLITE_BCVFS_STORAGE_FAILURE_SESSION_CHECKPOINT: c_int = 7;
101    pub const SQLITE_BCVFS_STORAGE_FAILURE_SESSION_ACCEPT: c_int = 8;
102    pub const SQLITE_BCVFS_STORAGE_FAILURE_SESSION_PUBLISH: c_int = 9;
103
104    pub const SQLITE_BCV_ATTACH_SECURE: c_int = 0x0001;
105    pub const SQLITE_BCV_ATTACH_IFNOT: c_int = 0x0002;
106    pub const SQLITE_BCVFS_SESSION_HASH_BYTES: usize = 32;
107    pub const SQLITE_BCVFS_SESSION_STATUS_NEW: c_int = 0;
108    pub const SQLITE_BCVFS_SESSION_STATUS_ACCEPTED: c_int = 1;
109    pub const SQLITE_BCVFS_SESSION_STATUS_COMMITTED: c_int = 2;
110    pub const SQLITE_BCVFS_SESSION_STATUS_FAILED: c_int = 3;
111    pub const SQLITE_BCVFS_SESSION_STATUS_CONFLICT: c_int = 4;
112
113    unsafe extern "C" {
114        pub fn sqlite3_bcvfs_create(
115            z_dir: *const c_char,
116            z_name: *const c_char,
117            pp_fs: *mut *mut sqlite3_bcvfs,
118            pz_err: *mut *mut c_char,
119        ) -> c_int;
120        pub fn sqlite3_bcvfs_destroy(fs: *mut sqlite3_bcvfs) -> c_int;
121        pub fn sqlite3_bcvfs_isdaemon(fs: *mut sqlite3_bcvfs) -> c_int;
122        pub fn sqlite3_bcvfs_register_vtab(db: *mut sqlite3) -> c_int;
123        pub fn sqlite3_bcvfs_config(
124            fs: *mut sqlite3_bcvfs,
125            op: c_int,
126            value: sqlite3_int64,
127        ) -> c_int;
128        pub fn sqlite3_bcvfs_auth_callback(
129            fs: *mut sqlite3_bcvfs,
130            auth_ctx: *mut c_void,
131            auth: Option<sqlite3_bcvfs_auth_callback>,
132        ) -> c_int;
133        pub fn sqlite3_bcvfs_auth_refresh_callback(
134            fs: *mut sqlite3_bcvfs,
135            auth_ctx: *mut c_void,
136            auth: Option<sqlite3_bcvfs_auth_refresh_callback>,
137        ) -> c_int;
138        pub fn sqlite3_bcvfs_upload_progress_callback(
139            fs: *mut sqlite3_bcvfs,
140            progress_ctx: *mut c_void,
141            progress: Option<sqlite3_bcvfs_upload_progress_callback>,
142        ) -> c_int;
143        pub fn sqlite3_bcvfs_storage_failure_callback(
144            fs: *mut sqlite3_bcvfs,
145            failure_ctx: *mut c_void,
146            failure: Option<sqlite3_bcvfs_storage_failure_callback>,
147        ) -> c_int;
148        pub fn sqlite3_bcvfs_attach(
149            fs: *mut sqlite3_bcvfs,
150            z_storage: *const c_char,
151            z_account: *const c_char,
152            z_container: *const c_char,
153            z_alias: *const c_char,
154            flags: c_int,
155            pz_err: *mut *mut c_char,
156        ) -> c_int;
157        pub fn sqlite3_bcvfs_attach_session(
158            fs: *mut sqlite3_bcvfs,
159            z_storage: *const c_char,
160            z_account: *const c_char,
161            z_container: *const c_char,
162            z_alias: *const c_char,
163            z_session_id: *const c_char,
164            flags: c_int,
165            pz_err: *mut *mut c_char,
166        ) -> c_int;
167        pub fn sqlite3_bcvfs_attach_session_scoped(
168            fs: *mut sqlite3_bcvfs,
169            z_storage: *const c_char,
170            z_account: *const c_char,
171            z_container: *const c_char,
172            z_alias: *const c_char,
173            z_session_id: *const c_char,
174            z_principal: *const c_char,
175            z_database: *const c_char,
176            z_operations: *const c_char,
177            a_operation_id: *const u8,
178            flags: c_int,
179            pz_err: *mut *mut c_char,
180        ) -> c_int;
181        pub fn sqlite3_bcvfs_detach_session(
182            fs: *mut sqlite3_bcvfs,
183            z_alias: *const c_char,
184            z_session_id: *const c_char,
185            pz_err: *mut *mut c_char,
186        ) -> c_int;
187        pub fn sqlite3_bcvfs_detach(
188            fs: *mut sqlite3_bcvfs,
189            z_alias: *const c_char,
190            pz_err: *mut *mut c_char,
191        ) -> c_int;
192        pub fn sqlite3_bcvfs_poll(
193            fs: *mut sqlite3_bcvfs,
194            z_container: *const c_char,
195            pz_err: *mut *mut c_char,
196        ) -> c_int;
197        pub fn sqlite3_bcvfs_upload(
198            fs: *mut sqlite3_bcvfs,
199            z_container: *const c_char,
200            busy: Option<sqlite3_bcvfs_busy_callback>,
201            busy_ctx: *mut c_void,
202            pz_err: *mut *mut c_char,
203        ) -> c_int;
204        /// Initialize an empty DoltLite store without creating a zero-tip branch.
205        ///
206        /// The connection must have been opened with DoltLite's private no-seed
207        /// flag. This serializes and commits an empty refs table for the named
208        /// SQLite schema.
209        ///
210        /// # Safety
211        /// `db` must be a live SQLite connection and `z_db` must point to a
212        /// NUL-terminated schema name valid for that connection.
213        pub fn sqlite3_doltlite_bcvfs_initialize_empty_store(
214            db: *mut sqlite3,
215            z_db: *const c_char,
216        ) -> c_int;
217        pub fn sqlite3_bcvfs_session_checkpoint(
218            fs: *mut sqlite3_bcvfs,
219            z_alias: *const c_char,
220            z_session_id: *const c_char,
221            checkpoint_hash: *mut u8,
222            pz_etag: *mut *mut c_char,
223            pz_err: *mut *mut c_char,
224        ) -> c_int;
225        pub fn sqlite3_bcvfs_session_rehydrate(
226            fs: *mut sqlite3_bcvfs,
227            z_alias: *const c_char,
228            z_session_id: *const c_char,
229            pz_err: *mut *mut c_char,
230        ) -> c_int;
231        pub fn sqlite3_bcvfs_session_upload(
232            fs: *mut sqlite3_bcvfs,
233            z_alias: *const c_char,
234            z_session_id: *const c_char,
235            pz_err: *mut *mut c_char,
236        ) -> c_int;
237        pub fn sqlite3_bcvfs_session_finalize(
238            fs: *mut sqlite3_bcvfs,
239            z_alias: *const c_char,
240            z_session_id: *const c_char,
241            pz_err: *mut *mut c_char,
242        ) -> c_int;
243        pub fn sqlite3_bcvfs_session_accept(
244            fs: *mut sqlite3_bcvfs,
245            z_alias: *const c_char,
246            z_session_id: *const c_char,
247            pz_etag: *mut *mut c_char,
248            pz_err: *mut *mut c_char,
249        ) -> c_int;
250        pub fn sqlite3_bcvfs_session_operation_status(
251            fs: *mut sqlite3_bcvfs,
252            z_alias: *const c_char,
253            z_session_id: *const c_char,
254            p_status: *mut c_int,
255            pz_err: *mut *mut c_char,
256        ) -> c_int;
257        pub fn sqlite3_bcvfs_delete(
258            fs: *mut sqlite3_bcvfs,
259            z_container: *const c_char,
260            z_database: *const c_char,
261            pz_err: *mut *mut c_char,
262        ) -> c_int;
263        /// Copy a database in an attached container to a new manifest name.
264        ///
265        /// # Safety
266        /// `fs` must be live, all names must be NUL-terminated C strings, and
267        /// `pz_err` must be null or writable for an allocated error pointer.
268        pub fn sqlite3_bcvfs_copy(
269            fs: *mut sqlite3_bcvfs,
270            z_container: *const c_char,
271            z_from: *const c_char,
272            z_to: *const c_char,
273            pz_err: *mut *mut c_char,
274        ) -> c_int;
275    }
276}
277
278/// Raw Cloud Backed SQLite database-management interface.
279#[cfg(feature = "blockcachevfs")]
280pub mod bcvutil {
281    use core::ffi::{c_char, c_int};
282
283    /// Opaque Cloud Backed SQLite database-management handle.
284    #[repr(C)]
285    pub struct sqlite3_bcv {
286        _private: [u8; 0],
287    }
288
289    unsafe extern "C" {
290        pub fn sqlite3_bcv_open(
291            z_module: *const c_char,
292            z_user: *const c_char,
293            z_auth: *const c_char,
294            z_container: *const c_char,
295            pp_out: *mut *mut sqlite3_bcv,
296        ) -> c_int;
297        pub fn sqlite3_bcv_close(handle: *mut sqlite3_bcv);
298        pub fn sqlite3_bcv_errmsg(handle: *mut sqlite3_bcv) -> *const c_char;
299        pub fn sqlite3_bcv_upload(
300            handle: *mut sqlite3_bcv,
301            z_local: *const c_char,
302            z_remote: *const c_char,
303        ) -> c_int;
304        pub fn sqlite3_bcv_cleanup(handle: *mut sqlite3_bcv, n_second: c_int) -> c_int;
305        pub fn sqlite3_bcv_create_if_not_exists(
306            handle: *mut sqlite3_bcv,
307            sz_name: c_int,
308            sz_block: c_int,
309        ) -> c_int;
310    }
311}
312
313#[cfg(all(feature = "remote", not(target_arch = "wasm32")))]
314mod remote {
315    use core::ffi::{c_char, c_int, c_long, c_void};
316
317    use super::{sqlite3, sqlite3_int64};
318
319    pub const DOLTLITE_PUSH_PROGRESS_PLAN: c_int = 1;
320    pub const DOLTLITE_PUSH_PROGRESS_UPLOADED: c_int = 2;
321
322    pub type sqlite3_doltlite_push_progress_callback =
323        unsafe extern "C" fn(*mut c_void, c_int, sqlite3_int64, sqlite3_int64);
324
325    #[repr(C)]
326    pub struct DoltliteServer {
327        _private: [u8; 0],
328    }
329
330    #[repr(C)]
331    pub struct DoltliteServeOpts {
332        pub zDir: *const c_char,
333        pub port: c_int,
334        pub zBindAddr: *const c_char,
335        pub certFile: *const c_char,
336        pub keyFile: *const c_char,
337        pub authKeysDir: *const c_char,
338        pub audience: *const c_char,
339        pub timeoutMs: c_int,
340        pub zVfsName: *const c_char,
341        pub bSessionLoopbackTransfer: c_int,
342    }
343
344    unsafe extern "C" {
345        /// Install a connection-scoped callback for opt-in native `dolt_push` progress.
346        ///
347        /// On success, `context` must remain valid until the matching clear call.
348        /// On failure, ownership remains with the caller.
349        pub fn sqlite3_doltlite_set_push_progress_callback(
350            db: *mut sqlite3,
351            context: *mut c_void,
352            callback: Option<sqlite3_doltlite_push_progress_callback>,
353        ) -> c_int;
354
355        /// Clear the callback only if `context` still owns the registration.
356        pub fn sqlite3_doltlite_clear_push_progress_callback(
357            db: *mut sqlite3,
358            context: *mut c_void,
359        ) -> c_int;
360
361        pub fn doltliteServe(
362            directory: *const c_char,
363            port: c_int,
364            bind_address: *const c_char,
365        ) -> c_int;
366
367        pub fn doltliteServeAsync(
368            directory: *const c_char,
369            port: c_int,
370            bind_address: *const c_char,
371        ) -> *mut DoltliteServer;
372
373        pub fn doltliteServeOpts(options: *const DoltliteServeOpts) -> c_int;
374
375        pub fn doltliteServeAsyncOpts(options: *const DoltliteServeOpts) -> *mut DoltliteServer;
376
377        pub fn doltliteServerStop(server: *mut DoltliteServer);
378
379        pub fn doltliteServerPort(server: *mut DoltliteServer) -> c_int;
380
381        pub fn doltliteCredsVerifyBearer(
382            authorization: *const c_char,
383            expected_audience: *const c_char,
384            authorized_keys_directory: *const c_char,
385            now: c_long,
386            key_id: *mut *mut c_char,
387        ) -> c_int;
388    }
389}
390
391#[cfg(all(feature = "remote", not(target_arch = "wasm32")))]
392pub use remote::*;
393
394#[cfg(not(feature = "loadable_extension"))]
395unsafe extern "C" {
396    fn doltliteInstallAutoExt() -> core::ffi::c_int;
397}
398
399#[cfg(not(feature = "loadable_extension"))]
400static DOLTLITE_INIT_RESULT: AtomicI32 = AtomicI32::new(i32::MIN);
401
402#[cfg(feature = "loadable_extension")]
403pub fn initialize_doltlite() -> core::ffi::c_int {
404    // A loadable extension runs inside an already-initialized host process;
405    // do not load DoltLite's process-wide auto-extension a second time.
406    SQLITE_OK
407}
408
409#[cfg(not(feature = "loadable_extension"))]
410pub fn initialize_doltlite() -> core::ffi::c_int {
411    let existing = DOLTLITE_INIT_RESULT.load(Ordering::Acquire);
412    if existing != i32::MIN {
413        return existing;
414    }
415
416    let result = unsafe { doltliteInstallAutoExt() };
417    match DOLTLITE_INIT_RESULT.compare_exchange(
418        i32::MIN,
419        result,
420        Ordering::AcqRel,
421        Ordering::Acquire,
422    ) {
423        Ok(_) => result,
424        Err(previous) => previous,
425    }
426}
427
428impl Default for sqlite3_vtab {
429    fn default() -> Self {
430        unsafe { mem::zeroed() }
431    }
432}
433
434impl Default for sqlite3_vtab_cursor {
435    fn default() -> Self {
436        unsafe { mem::zeroed() }
437    }
438}