Skip to main content

quack_rs/
file_system.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! File system access (`DuckDB` 1.5.0+).
7//!
8//! This module exposes `DuckDB`'s virtual file system (VFS) to extensions, so a
9//! custom table function, replacement scan, or copy function can read and write
10//! files through the *same* abstraction `DuckDB` uses internally. That means
11//! transparently honouring `httpfs` (`s3://`, `http://`), in-memory files, and
12//! any other registered file system — rather than reaching for `std::fs` and
13//! only ever seeing local disk.
14//!
15//! # Obtaining a [`FileSystem`]
16//!
17//! Get one from a [`ClientContext`] (which you can obtain from most function
18//! callbacks):
19//!
20//! ```rust,no_run
21//! use quack_rs::client_context::ClientContext;
22//! use quack_rs::file_system::{FileOpenOptions, FileSystem};
23//!
24//! # fn demo(ctx: &ClientContext) -> Option<()> {
25//! let fs = FileSystem::from_client_context(ctx)?;
26//! let opts = FileOpenOptions::read_only();
27//! let handle = fs.open(c"data.csv", &opts).ok()?;
28//! let mut contents = Vec::new();
29//! handle.read_to_end(&mut contents).ok()?;
30//! # Some(())
31//! # }
32//! ```
33
34use std::ffi::CStr;
35use std::marker::PhantomData;
36use std::os::raw::c_void;
37
38use libduckdb_sys::{
39    duckdb_client_context_get_file_system, duckdb_create_file_open_options,
40    duckdb_destroy_file_handle, duckdb_destroy_file_open_options, duckdb_destroy_file_system,
41    duckdb_file_flag, duckdb_file_flag_DUCKDB_FILE_FLAG_APPEND,
42    duckdb_file_flag_DUCKDB_FILE_FLAG_CREATE, duckdb_file_flag_DUCKDB_FILE_FLAG_CREATE_NEW,
43    duckdb_file_flag_DUCKDB_FILE_FLAG_READ, duckdb_file_flag_DUCKDB_FILE_FLAG_WRITE,
44    duckdb_file_handle, duckdb_file_handle_close, duckdb_file_handle_error_data,
45    duckdb_file_handle_read, duckdb_file_handle_seek, duckdb_file_handle_size,
46    duckdb_file_handle_sync, duckdb_file_handle_tell, duckdb_file_handle_write,
47    duckdb_file_open_options, duckdb_file_open_options_set_flag, duckdb_file_system,
48    duckdb_file_system_error_data, duckdb_file_system_open, DuckDBSuccess,
49};
50
51use crate::client_context::ClientContext;
52use crate::error_data::ErrorData;
53
54/// A file-open mode flag, mirroring `duckdb_file_flag`.
55#[derive(Debug, Clone, Copy, PartialEq, Eq)]
56#[non_exhaustive]
57pub enum FileFlag {
58    /// Open for reading.
59    Read,
60    /// Open for writing.
61    Write,
62    /// Create the file if it does not exist. Requires [`Write`][Self::Write].
63    Create,
64    /// Create the file, failing if it already exists. Requires
65    /// [`Write`][Self::Write].
66    ///
67    /// Setting it also sets [`Create`][Self::Create]: `DuckDB` maps it to
68    /// `FILE_FLAGS_EXCLUSIVE_CREATE`, which only means "fail if it exists" in
69    /// combination with `FILE_FLAGS_FILE_CREATE` (`O_EXCL` without `O_CREAT`
70    /// is ignored by `open(2)`), and on its own neither created a missing file
71    /// nor refused an existing one.
72    ///
73    /// # Windows: an existing file is not refused
74    ///
75    /// `DuckDB`'s local file system on Windows ignores the exclusive flag: it
76    /// opens with `OPEN_ALWAYS` whenever `Create` is set
77    /// (`LocalFileSystem::OpenFile` in `src/common/local_file_system.cpp`,
78    /// checked in `DuckDB` 1.5.5), so an existing file is opened, not
79    /// truncated, and no error is returned. A missing file is still created.
80    /// Do not rely on `CreateNew` for mutual exclusion on Windows.
81    CreateNew,
82    /// Open in append mode.
83    Append,
84}
85
86impl FileFlag {
87    /// Converts to the `DuckDB` C API constant.
88    #[must_use]
89    const fn to_raw(self) -> duckdb_file_flag {
90        match self {
91            Self::Read => duckdb_file_flag_DUCKDB_FILE_FLAG_READ,
92            Self::Write => duckdb_file_flag_DUCKDB_FILE_FLAG_WRITE,
93            Self::Create => duckdb_file_flag_DUCKDB_FILE_FLAG_CREATE,
94            Self::CreateNew => duckdb_file_flag_DUCKDB_FILE_FLAG_CREATE_NEW,
95            Self::Append => duckdb_file_flag_DUCKDB_FILE_FLAG_APPEND,
96        }
97    }
98}
99
100/// RAII wrapper for `duckdb_file_open_options`.
101///
102/// Describes how a file should be opened. Automatically destroyed when dropped.
103pub struct FileOpenOptions {
104    options: duckdb_file_open_options,
105}
106
107impl FileOpenOptions {
108    /// Creates an empty set of file-open options.
109    #[must_use]
110    pub fn new() -> Self {
111        // SAFETY: duckdb_create_file_open_options allocates an owned handle.
112        let options = unsafe { duckdb_create_file_open_options() };
113        Self { options }
114    }
115
116    /// Creates options configured for read-only access.
117    #[must_use]
118    pub fn read_only() -> Self {
119        let opts = Self::new();
120        opts.set_flag(FileFlag::Read, true);
121        opts
122    }
123
124    /// Creates options configured for writing, creating the file if needed.
125    #[must_use]
126    pub fn write_create() -> Self {
127        let opts = Self::new();
128        opts.set_flag(FileFlag::Write, true);
129        opts.set_flag(FileFlag::Create, true);
130        opts
131    }
132
133    /// Sets a file-open flag, returning `true` on success.
134    ///
135    /// Setting [`FileFlag::CreateNew`] also sets [`FileFlag::Create`]; see
136    /// there.
137    ///
138    /// # `value == false` does not clear a flag
139    ///
140    /// `duckdb_file_open_options_set_flag` ORs the flag in and ignores
141    /// `value` (`src/main/capi/file_system-c.cpp`), so a flag cannot be
142    /// unset once set. To change your mind, build a fresh `FileOpenOptions`.
143    pub fn set_flag(&self, flag: FileFlag, value: bool) -> bool {
144        if self.options.is_null() {
145            return false;
146        }
147        if flag == FileFlag::CreateNew && value && !self.set_flag(FileFlag::Create, true) {
148            return false;
149        }
150        // SAFETY: self.options is a valid duckdb_file_open_options.
151        let state =
152            unsafe { duckdb_file_open_options_set_flag(self.options, flag.to_raw(), value) };
153        state == DuckDBSuccess
154    }
155
156    /// Returns the raw handle without consuming the options.
157    #[inline]
158    #[must_use]
159    pub const fn as_raw(&self) -> duckdb_file_open_options {
160        self.options
161    }
162}
163
164impl Default for FileOpenOptions {
165    fn default() -> Self {
166        Self::new()
167    }
168}
169
170impl Drop for FileOpenOptions {
171    fn drop(&mut self) {
172        if !self.options.is_null() {
173            // SAFETY: self.options is a valid handle that we own.
174            unsafe { duckdb_destroy_file_open_options(&raw mut self.options) };
175        }
176    }
177}
178
179/// RAII wrapper for a `duckdb_file_system`.
180///
181/// Automatically destroyed when dropped.
182///
183/// # Lifetime
184///
185/// `duckdb_client_context_get_file_system` does not hand out an owned file
186/// system: its wrapper holds a *reference* to the connection's client file
187/// system, which the connection's `ClientContext` owns and frees when the
188/// connection closes. Using the handle after that is a heap use-after-free, so
189/// a `FileSystem` borrows the [`ClientContext`] it came from for `'ctx`.
190///
191/// ```rust,compile_fail,E0505
192/// use quack_rs::client_context::ClientContext;
193/// use quack_rs::file_system::{FileOpenOptions, FileSystem};
194///
195/// fn demo(ctx: ClientContext) {
196///     let fs = FileSystem::from_client_context(&ctx).unwrap();
197///     drop(ctx); // error[E0505]: cannot move out of `ctx` because it is borrowed
198///     let _ = fs.open(c"data.csv", &FileOpenOptions::read_only());
199/// }
200/// ```
201///
202/// [`FileHandle`]s opened through it borrow it in turn, so a handle cannot
203/// outlive the file system, the client context, or — through the context's
204/// contract — the connection and database behind them.
205pub struct FileSystem<'ctx> {
206    fs: duckdb_file_system,
207    _context: PhantomData<&'ctx ClientContext>,
208}
209
210impl<'ctx> FileSystem<'ctx> {
211    /// Obtains the file system associated with a [`ClientContext`].
212    ///
213    /// The result borrows `context`; see the type-level docs for why.
214    ///
215    /// Returns `None` if `DuckDB` does not provide one.
216    #[must_use]
217    pub fn from_client_context(context: &'ctx ClientContext) -> Option<Self> {
218        // SAFETY: context.as_raw() is a valid duckdb_client_context.
219        let fs = unsafe { duckdb_client_context_get_file_system(context.as_raw()) };
220        if fs.is_null() {
221            None
222        } else {
223            Some(Self {
224                fs,
225                _context: PhantomData,
226            })
227        }
228    }
229
230    /// Wraps a raw `duckdb_file_system` handle, taking ownership.
231    ///
232    /// # Safety
233    ///
234    /// `fs` must be a valid, non-null `duckdb_file_system` handle that the caller
235    /// no longer manages, and the connection whose client context it was
236    /// obtained from must stay open for all of `'ctx` — the handle refers to
237    /// that connection's file system, which is freed when it closes.
238    #[inline]
239    #[must_use]
240    pub const unsafe fn from_raw(fs: duckdb_file_system) -> Self {
241        Self {
242            fs,
243            _context: PhantomData,
244        }
245    }
246
247    /// Returns the raw handle.
248    #[inline]
249    #[must_use]
250    pub const fn as_raw(&self) -> duckdb_file_system {
251        self.fs
252    }
253
254    /// Opens `path` with the given `options`.
255    ///
256    /// The handle borrows this file system; see [`FileHandle`].
257    ///
258    /// # Errors
259    ///
260    /// Returns the structured [`ErrorData`] if the file cannot be opened.
261    pub fn open(
262        &self,
263        path: &CStr,
264        options: &FileOpenOptions,
265    ) -> Result<FileHandle<'_>, ErrorData> {
266        let mut handle: duckdb_file_handle = std::ptr::null_mut();
267        // SAFETY: self.fs, path, and options.as_raw() are all valid; handle is a
268        // valid out-pointer.
269        let state = unsafe {
270            duckdb_file_system_open(self.fs, path.as_ptr(), options.as_raw(), &raw mut handle)
271        };
272        if state == DuckDBSuccess && !handle.is_null() {
273            // SAFETY: open succeeded, so handle is a valid owned file handle.
274            Ok(unsafe { FileHandle::from_raw(handle) })
275        } else {
276            Err(self.error_data())
277        }
278    }
279
280    /// Returns the structured error from the most recent failed operation.
281    #[must_use]
282    pub fn error_data(&self) -> ErrorData {
283        // SAFETY: self.fs is valid; the call returns an owned error data handle.
284        let raw = unsafe { duckdb_file_system_error_data(self.fs) };
285        // SAFETY: raw is an owned duckdb_error_data (possibly null).
286        unsafe { ErrorData::from_raw(raw) }
287    }
288}
289
290impl Drop for FileSystem<'_> {
291    fn drop(&mut self) {
292        if !self.fs.is_null() {
293            // SAFETY: self.fs is a valid handle that we own.
294            unsafe { duckdb_destroy_file_system(&raw mut self.fs) };
295        }
296    }
297}
298
299/// Buffer growth step for [`FileHandle::read_to_end`] when the handle cannot
300/// report a size — 64 KiB, matching the order of magnitude of `DuckDB`'s own
301/// file-read buffers.
302const CHUNK: usize = 64 * 1024;
303
304/// RAII wrapper for an open `duckdb_file_handle`.
305///
306/// Automatically closed and destroyed when dropped.
307///
308/// # Lifetime
309///
310/// A handle refers to the database's underlying file system: once the
311/// database is closed (`duckdb_close` on the last reference), every method is
312/// a use-after-free — valgrind reports an invalid read in
313/// `duckdb::FileHandle::Read`. The handle therefore borrows the
314/// [`FileSystem`] that opened it for `'fs`, which in turn borrows the
315/// [`ClientContext`] whose contract keeps the connection (and so the
316/// database) open. Using a handle after its file system is gone does not
317/// compile:
318///
319/// ```rust,compile_fail,E0505
320/// use quack_rs::client_context::ClientContext;
321/// use quack_rs::file_system::{FileOpenOptions, FileSystem};
322///
323/// fn demo(ctx: &ClientContext) {
324///     let fs = FileSystem::from_client_context(ctx).unwrap();
325///     let handle = fs.open(c"data.csv", &FileOpenOptions::read_only()).unwrap();
326///     drop(fs); // error[E0505]: cannot move out of `fs` because it is borrowed
327///     let _ = handle.size();
328/// }
329/// ```
330///
331/// # Threads
332///
333/// A `FileHandle` is [`Send`]: it may be moved to, used on and dropped on
334/// another thread. It is not [`Sync`], so two threads cannot use one at
335/// the same time; share it behind a [`Mutex`](std::sync::Mutex). See the
336/// `unsafe impl Send` below for the reasoning.
337///
338/// ```rust,compile_fail
339/// fn assert_sync<T: Sync>() {}
340/// assert_sync::<quack_rs::file_system::FileHandle<'static>>();
341/// ```
342///
343/// # Keeping a file open across callbacks
344///
345/// A `COPY ... TO` writer opens its file in `global_init`, writes it in
346/// `sink` and closes it in `finalize`, so the handle has to live in the
347/// statement's global state, which is `'static` and shared by every sink
348/// thread. The borrow above cannot express that the state is destroyed while
349/// the statement — and so the connection and database — are still alive, so
350/// end it explicitly, once, and keep the handle in a `Mutex`:
351///
352/// ```rust,no_run
353/// use std::sync::Mutex;
354/// use quack_rs::copy_function::CopyGlobalInitInfo;
355/// use quack_rs::file_system::{FileHandle, FileOpenOptions, FileSystem};
356///
357/// struct Writer {
358///     file: Mutex<FileHandle<'static>>,
359/// }
360///
361/// # fn global_init(info: &CopyGlobalInitInfo) -> Result<(), String> {
362/// // SAFETY: the context is only used inside this callback.
363/// let ctx = unsafe { info.get_client_context() };
364/// let fs = FileSystem::from_client_context(&ctx).ok_or("no file system")?;
365/// // SAFETY: DuckDB copies the path out before the callback returns.
366/// let path = unsafe { info.get_file_path() }.map_err(|e| e.to_string())?;
367/// let path = std::ffi::CString::new(path).map_err(|e| e.to_string())?;
368/// let file = fs.open(&path, &FileOpenOptions::write_create()).map_err(|e| e.to_string())?;
369/// // SAFETY: the handle ends up in this statement's global state, which
370/// // DuckDB destroys before the statement finishes, while the connection and
371/// // the database it was opened against are still open.
372/// let file: FileHandle<'static> = unsafe { FileHandle::from_raw(file.into_raw()) };
373/// info.set_global_state_typed(Writer { file: Mutex::new(file) });
374/// # Ok(())
375/// # }
376/// ```
377///
378/// `sink` then reads it with `global_state_ref::<Writer>()` and locks the
379/// mutex to write; dropping the state closes the file.
380pub struct FileHandle<'fs> {
381    handle: duckdb_file_handle,
382    _file_system: PhantomData<&'fs ()>,
383}
384
385// SAFETY: a `duckdb_file_handle` is a heap `CFileHandle { ErrorData
386// error_data; unique_ptr<FileHandle> handle; }` (`file_system-c.cpp`,
387// byte-identical in 1.5.6 and 2.0.0), and nothing in it is tied to the thread
388// that created it: `duckdb::FileHandle` holds a reference to the database's
389// file system (one object shared by every connection and thread), the path
390// and the open flags, and a local file's `UnixFileHandle` adds only its file
391// descriptor and a position kept for logging (`local_file_system.cpp`). No
392// call in `file_system-c.cpp` reads thread-local state. Moving a handle to
393// another thread and using or dropping it there is therefore sound.
394// Concurrent use is not — every call writes `error_data` without
395// synchronisation, and `Read`/`Write` move one shared file position — so
396// `Sync` is not implemented. The `'fs` borrow is unaffected: a moved handle
397// still cannot outlive its file system. The live test
398// `a_file_handle_is_used_and_dropped_on_another_thread` opens a file on one
399// thread and writes, reads and drops it on another.
400unsafe impl Send for FileHandle<'_> {}
401
402impl FileHandle<'_> {
403    /// Wraps a raw `duckdb_file_handle`, taking ownership.
404    ///
405    /// # Safety
406    ///
407    /// `handle` must be a valid, non-null `duckdb_file_handle` that the caller no
408    /// longer manages, and the database it was opened against must stay open
409    /// for the whole of the lifetime the caller picks for the result.
410    #[inline]
411    #[must_use]
412    pub const unsafe fn from_raw(handle: duckdb_file_handle) -> Self {
413        Self {
414            handle,
415            _file_system: PhantomData,
416        }
417    }
418
419    /// Returns the raw handle.
420    #[inline]
421    #[must_use]
422    pub const fn as_raw(&self) -> duckdb_file_handle {
423        self.handle
424    }
425
426    /// Consumes the `FileHandle` and returns the raw handle without closing
427    /// it, the inverse of [`from_raw`][Self::from_raw].
428    ///
429    /// The caller takes over closing (`duckdb_file_handle_close`) and
430    /// destroying (`duckdb_destroy_file_handle`) it — or hands it back to
431    /// `from_raw`, which is how a handle is moved into state that outlives
432    /// this borrow (see [Keeping a file open across
433    /// callbacks](Self#keeping-a-file-open-across-callbacks)).
434    #[inline]
435    #[must_use]
436    pub const fn into_raw(self) -> duckdb_file_handle {
437        let raw = self.handle;
438        std::mem::forget(self);
439        raw
440    }
441
442    /// Reads up to `buf.len()` bytes into `buf`, returning the number of bytes
443    /// read (0 at end of file).
444    ///
445    /// # Errors
446    ///
447    /// Returns the structured [`ErrorData`] on read failure.
448    pub fn read(&self, buf: &mut [u8]) -> Result<usize, ErrorData> {
449        let size = i64::try_from(buf.len()).unwrap_or(i64::MAX);
450        // SAFETY: self.handle is valid; buf is writable for `size` bytes.
451        let n = unsafe {
452            duckdb_file_handle_read(self.handle, buf.as_mut_ptr().cast::<c_void>(), size)
453        };
454        if n < 0 {
455            Err(self.error_data())
456        } else {
457            Ok(usize::try_from(n).unwrap_or(0))
458        }
459    }
460
461    /// Writes up to `buf.len()` bytes from `buf`, returning the number written.
462    ///
463    /// # Errors
464    ///
465    /// Returns the structured [`ErrorData`] on write failure.
466    pub fn write(&self, buf: &[u8]) -> Result<usize, ErrorData> {
467        let size = i64::try_from(buf.len()).unwrap_or(i64::MAX);
468        // SAFETY: self.handle is valid; buf is readable for `size` bytes.
469        let n =
470            unsafe { duckdb_file_handle_write(self.handle, buf.as_ptr().cast::<c_void>(), size) };
471        if n < 0 {
472            Err(self.error_data())
473        } else {
474            Ok(usize::try_from(n).unwrap_or(0))
475        }
476    }
477
478    /// Reads exactly `buf.len()` bytes, or fails.
479    ///
480    /// `duckdb_file_handle_read` returns "the number of bytes **actually**
481    /// read", so a single `read` can come up short on any file system — and
482    /// `httpfs` is exactly where that happens. This loops until the buffer is
483    /// full.
484    ///
485    /// # Errors
486    ///
487    /// Returns the structured [`ErrorData`] on read failure, or a
488    /// [`DuckDbErrorType::Io`][crate::error_data::DuckDbErrorType::Io] error if
489    /// the file ends before `buf` is filled.
490    pub fn read_exact(&self, buf: &mut [u8]) -> Result<(), ErrorData> {
491        let mut filled = 0;
492        while filled < buf.len() {
493            let read = self.read(&mut buf[filled..])?;
494            if read == 0 {
495                return Err(ErrorData::new(
496                    crate::error_data::DuckDbErrorType::Io,
497                    &format!(
498                        "unexpected end of file: wanted {} bytes, got {filled}",
499                        buf.len()
500                    ),
501                ));
502            }
503            filled += read;
504        }
505        Ok(())
506    }
507
508    /// Appends the rest of the file to `buf`, returning how many bytes were
509    /// added.
510    ///
511    /// Reads from the current position to end of file, looping over short reads.
512    ///
513    /// # Errors
514    ///
515    /// Returns the structured [`ErrorData`] on read failure.
516    pub fn read_to_end(&self, buf: &mut Vec<u8>) -> Result<usize, ErrorData> {
517        // Start from the remaining length when the handle can report it, so the
518        // common case is a single allocation, but never rely on it: a stream may
519        // report no size at all.
520        let remaining = match (self.size(), self.tell()) {
521            (Ok(size), Ok(position)) => size.saturating_sub(position),
522            _ => 0,
523        };
524        reserve_for_read(buf, remaining);
525
526        let start = buf.len();
527        loop {
528            let filled = buf.len();
529            buf.resize(filled + CHUNK, 0);
530            let read = match self.read(&mut buf[filled..]) {
531                Ok(read) => read,
532                Err(error) => {
533                    buf.truncate(filled);
534                    return Err(error);
535                }
536            };
537            buf.truncate(filled + read);
538            if read == 0 {
539                return Ok(buf.len() - start);
540            }
541        }
542    }
543
544    /// Writes all of `buf`, or fails.
545    ///
546    /// Like [`read_exact`][Self::read_exact], this exists because
547    /// `duckdb_file_handle_write` reports the number of bytes *actually*
548    /// written.
549    ///
550    /// # Errors
551    ///
552    /// Returns the structured [`ErrorData`] on write failure, or a
553    /// [`DuckDbErrorType::Io`][crate::error_data::DuckDbErrorType::Io] error if
554    /// `DuckDB` stops accepting bytes before the buffer is drained.
555    pub fn write_all(&self, buf: &[u8]) -> Result<(), ErrorData> {
556        let mut written = 0;
557        while written < buf.len() {
558            let n = self.write(&buf[written..])?;
559            if n == 0 {
560                return Err(ErrorData::new(
561                    crate::error_data::DuckDbErrorType::Io,
562                    &format!("write stalled: wanted {} bytes, wrote {written}", buf.len()),
563                ));
564            }
565            written += n;
566        }
567        Ok(())
568    }
569
570    /// Seeks to an absolute byte `position`.
571    ///
572    /// # Errors
573    ///
574    /// Returns the structured [`ErrorData`] if the seek fails, and an
575    /// `InvalidInput` error, without calling `DuckDB`, for a position past
576    /// `i64::MAX`, which `DuckDB`'s seek cannot take (it used to be clamped,
577    /// and a file system that accepts that offset returned `Ok`).
578    pub fn seek(&self, position: u64) -> Result<(), ErrorData> {
579        let Ok(pos) = i64::try_from(position) else {
580            return Err(ErrorData::new(
581                crate::error_data::DuckDbErrorType::InvalidInput,
582                &format!("FileHandle::seek: position {position} is past i64::MAX"),
583            ));
584        };
585        // SAFETY: self.handle is valid.
586        let state = unsafe { duckdb_file_handle_seek(self.handle, pos) };
587        self.check(state)
588    }
589
590    /// Returns the current byte offset within the file.
591    ///
592    /// # Errors
593    ///
594    /// Returns the structured [`ErrorData`] if `DuckDB` cannot report the
595    /// position. The C API signals that with a negative return value, which is
596    /// far too easy to clamp to zero by accident.
597    pub fn tell(&self) -> Result<u64, ErrorData> {
598        // SAFETY: self.handle is valid.
599        let position = unsafe { duckdb_file_handle_tell(self.handle) };
600        u64::try_from(position).map_err(|_| self.error_data())
601    }
602
603    /// Returns the total size of the file in bytes.
604    ///
605    /// # Errors
606    ///
607    /// Returns the structured [`ErrorData`] if `DuckDB` cannot report the size.
608    pub fn size(&self) -> Result<u64, ErrorData> {
609        // SAFETY: self.handle is valid.
610        let size = unsafe { duckdb_file_handle_size(self.handle) };
611        u64::try_from(size).map_err(|_| self.error_data())
612    }
613
614    /// Flushes buffered writes to durable storage.
615    ///
616    /// # Errors
617    ///
618    /// Returns the structured [`ErrorData`] if the sync fails.
619    pub fn sync(&self) -> Result<(), ErrorData> {
620        // SAFETY: self.handle is valid.
621        let state = unsafe { duckdb_file_handle_sync(self.handle) };
622        self.check(state)
623    }
624
625    /// Closes the file. The handle is still destroyed on drop.
626    ///
627    /// # Errors
628    ///
629    /// Returns the structured [`ErrorData`] if the close fails. Dropping the
630    /// handle then tries to close it once more, and leaks it if that fails
631    /// too: destroying it would retry the close where an exception aborts the
632    /// process.
633    pub fn close(&self) -> Result<(), ErrorData> {
634        // SAFETY: self.handle is valid.
635        let state = unsafe { duckdb_file_handle_close(self.handle) };
636        self.check(state)
637    }
638
639    /// Returns the structured error from the most recent failed operation.
640    #[must_use]
641    pub fn error_data(&self) -> ErrorData {
642        // SAFETY: self.handle is valid; the call returns an owned error data.
643        let raw = unsafe { duckdb_file_handle_error_data(self.handle) };
644        // SAFETY: raw is an owned duckdb_error_data (possibly null).
645        unsafe { ErrorData::from_raw(raw) }
646    }
647
648    /// Converts a `duckdb_state` into a `Result`, reading the handle's error
649    /// data on failure.
650    fn check(&self, state: libduckdb_sys::duckdb_state) -> Result<(), ErrorData> {
651        if state == DuckDBSuccess {
652            Ok(())
653        } else {
654            Err(self.error_data())
655        }
656    }
657}
658
659impl Drop for FileHandle<'_> {
660    fn drop(&mut self) {
661        if self.handle.is_null() {
662            return;
663        }
664        // `duckdb_destroy_file_handle` calls `Close()` outside any `try`
665        // (`file_system-c.cpp`), so a close that throws — possible for a
666        // handle from an extension's file system — would escape the C API
667        // and abort the process. `duckdb_file_handle_close` catches, so it
668        // closes first; destroy's second `Close()` is then a no-op for
669        // `DuckDB`'s own handles (`local_file_system.cpp`). If the close
670        // failed, destroy would retry it with no `try`, so the handle is
671        // leaked instead. Call [`close`][FileHandle::close] first to see
672        // the error.
673        // SAFETY: self.handle is a valid handle that we own.
674        let state = unsafe { duckdb_file_handle_close(self.handle) };
675        if state == DuckDBSuccess {
676            // SAFETY: as above; destroy nulls the handle.
677            unsafe { duckdb_destroy_file_handle(&raw mut self.handle) };
678        }
679    }
680}
681
682crate::debug_repr::impl_handle_debug!(FileOpenOptions.options);
683
684impl core::fmt::Debug for FileSystem<'_> {
685    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
686        f.debug_struct("FileSystem").field("fs", &self.fs).finish()
687    }
688}
689
690impl core::fmt::Debug for FileHandle<'_> {
691    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
692        f.debug_struct("FileHandle")
693            .field("handle", &self.handle)
694            .finish()
695    }
696}
697
698/// The most [`FileHandle::read_to_end`] reserves up front from the size the
699/// file reports; past it the buffer grows as data actually arrives.
700const MAX_READ_RESERVE: usize = 256 * 1024 * 1024;
701
702/// Reserves room for a read the file says is `remaining` bytes long.
703///
704/// The size is a hint, not a promise: a remote file system reports whatever
705/// the server's `Content-Length` says, and an infallible `reserve` of an
706/// impossible size aborts the whole process. So the hint is capped at
707/// [`MAX_READ_RESERVE`] and a failed reservation falls back to one chunk.
708fn reserve_for_read(buf: &mut Vec<u8>, remaining: u64) {
709    let hint = usize::try_from(remaining).unwrap_or(usize::MAX);
710    let wanted = hint.clamp(CHUNK, MAX_READ_RESERVE.max(CHUNK));
711    if buf.try_reserve(wanted).is_err() {
712        // Nothing reserved; the read loop grows the buffer one chunk at a time.
713        let _ = buf.try_reserve(CHUNK);
714    }
715}
716
717#[cfg(test)]
718mod tests {
719    use super::*;
720
721    /// A file reporting an impossible size must not abort the process: the
722    /// up-front reservation is capped, and a refused one is not fatal.
723    #[test]
724    fn reserve_for_read_caps_and_survives_an_impossible_size() {
725        let mut buf = Vec::new();
726        reserve_for_read(&mut buf, u64::MAX);
727        assert!(buf.capacity() >= CHUNK);
728        assert!(buf.capacity() <= MAX_READ_RESERVE * 2, "{}", buf.capacity());
729
730        let mut small = Vec::new();
731        reserve_for_read(&mut small, 10);
732        assert!(small.capacity() >= CHUNK, "at least one chunk");
733
734        let mut mid = Vec::new();
735        reserve_for_read(&mut mid, 1024 * 1024);
736        assert!(mid.capacity() >= 1024 * 1024, "the hint is used when sane");
737    }
738
739    #[test]
740    fn file_flag_distinct_raw_values() {
741        let flags = [
742            FileFlag::Read,
743            FileFlag::Write,
744            FileFlag::Create,
745            FileFlag::CreateNew,
746            FileFlag::Append,
747        ];
748        for (i, a) in flags.iter().enumerate() {
749            for b in flags.iter().skip(i + 1) {
750                assert_ne!(a.to_raw(), b.to_raw(), "{a:?} and {b:?} share a raw value");
751            }
752        }
753    }
754}