packages feed

duckdb-simple-1.0.0.0: src/Database/DuckDB/Simple/FileSystem.hs

{-# LANGUAGE BlockArguments #-}
{-# LANGUAGE OverloadedStrings #-}

-- |
-- Module      : Database.DuckDB.Simple.FileSystem
-- Description : Checked file operations through the V2 file system.
module Database.DuckDB.Simple.FileSystem (
  FileFlag (..),
  FileHandle,
  withFileHandle,
  readFileHandleChunk,
  writeFileHandleBytes,
  readFileHandleAt,
  writeFileHandleAt,
  fileHandleTell,
  fileHandleSize,
  fileHandleSeek,
  fileHandleSync,
  pathExists,
  pathIsRemote,
  expandPath,
  globPaths,
  movePath,
  removePath,
) where

import Control.Exception (bracket)
import Control.Monad (when)
import qualified Data.ByteString as BS
import qualified Data.ByteString.Internal as BSI
import Data.IORef (modifyIORef', newIORef, readIORef)
import Data.Int (Int64)
import qualified Data.Text as Text
import Database.DuckDB.Simple.Callback (runCallback)
import Database.DuckDB.Simple.Internal (Connection, withConnectionHandle)
import Database.DuckDB.Simple.Native
import Foreign.C.ConstPtr (ConstPtr (..), unConstPtr)
import Foreign.Ptr (castPtr, freeHaskellFunPtr, nullPtr)
import Foreign.Storable (peek)
import HsBindgen.Runtime.Support.FunPtr (toFunPtr)

-- | An open file. 'withFileHandle' gives it to one action. Do not use it after that action returns.
newtype FileHandle = FileHandle DuckDBV2FileHandle

-- | Open a file for one action. Release its handle on every exit path.
withFileHandle :: Connection -> FilePath -> [FileFlag] -> (FileHandle -> IO a) -> IO a
withFileHandle conn path flags action
  | '\0' `elem` path = throwInvalidArgument "file path contains NUL"
  | otherwise = withConnectionHandle conn \handle -> do
      fs <- output (c_duckdb_v2_connection_get_file_system handle)
      bracket (output (c_duckdb_v2_file_open_options_create fs)) (destroy c_duckdb_v2_file_open_options_destroy) \options -> do
        mapM_ (checked . c_duckdb_v2_file_open_options_set_flag options . fileFlagToNative) flags
        withText (Text.pack path) \name ->
          bracket (output (c_duckdb_v2_file_system_open fs name options)) (destroy c_duckdb_v2_file_destroy) (action . FileHandle)

-- | Read up to the requested byte count and advance the file position. The
-- buffer and the size that the native call gets come from one value. A count
-- above that size raises an error. The library cannot check that the native
-- call writes no more than that size: the header of DuckDB states it as the
-- contract of the call.
readFileHandleChunk :: FileHandle -> Int64 -> IO BS.ByteString
readFileHandleChunk (FileHandle handle) requested
  | requested <= 0 = pure BS.empty
  | toInteger requested > toInteger (maxBound :: Int) = throwInvalidArgument "file read size exceeds Int range"
  | otherwise = BSI.createAndTrim size \buffer -> do
      count <- output (c_duckdb_v2_file_read handle (castPtr buffer) (fromIntegral size))
      when (toInteger count > toInteger size) $ throwInternalError "native file read exceeds buffer size"
      pure (fromIntegral count)
  where
    size = fromIntegral requested :: Int

-- | Write bytes and return the byte count. Advance the file position.
writeFileHandleBytes :: FileHandle -> BS.ByteString -> IO Int64
writeFileHandleBytes (FileHandle handle) bytes = BS.useAsCStringLen bytes \(ptr, count) ->
  fromIntegral <$> output (c_duckdb_v2_file_write handle (ConstPtr (castPtr ptr)) (fromIntegral count))

-- | Read exactly the requested bytes without changing the file position. A
-- range whose end exceeds the 'Int64' range raises an error before the native
-- call. DuckDB checks the range against the size of the file, and a read past
-- the end raises the error of DuckDB. The function allocates the buffer before
-- that check. The buffer and the size that the native call gets come from one
-- value. The library cannot check that the native call writes no more than
-- that size: the header of DuckDB states it as the contract of the call.
readFileHandleAt :: FileHandle -> Int64 -> Int64 -> IO BS.ByteString
readFileHandleAt (FileHandle handle) offset requested
  | offset < 0 = throwInvalidArgument "file offset is negative"
  | requested < 0 = throwInvalidArgument "file read size is negative"
  | toInteger requested > toInteger (maxBound :: Int) = throwInvalidArgument "file read size exceeds Int range"
  | toInteger offset + toInteger requested > toInteger (maxBound :: Int64) = throwInvalidArgument "file read range exceeds Int64 range"
  | otherwise = BSI.create size \buffer -> checked (c_duckdb_v2_file_read_at handle (castPtr buffer) (fromIntegral size) (fromIntegral offset))
  where
    size = fromIntegral requested :: Int

-- | Write all bytes at an offset without changing the file position. A range
-- whose end exceeds the 'Int64' range raises an error.
writeFileHandleAt :: FileHandle -> Int64 -> BS.ByteString -> IO ()
writeFileHandleAt (FileHandle handle) offset bytes
  | offset < 0 = throwInvalidArgument "file offset is negative"
  | toInteger offset + toInteger (BS.length bytes) > toInteger (maxBound :: Int64) =
      throwInvalidArgument "file write range exceeds Int64 range"
  | otherwise = BS.useAsCStringLen bytes \(ptr, count) ->
      checked (c_duckdb_v2_file_write_at handle (ConstPtr (castPtr ptr)) (fromIntegral count) (fromIntegral offset))

-- | Return the current byte position.
fileHandleTell :: FileHandle -> IO Int64
fileHandleTell (FileHandle handle) = output (c_duckdb_v2_file_tell handle) >>= checkedPosition

-- | Return the file size in bytes.
fileHandleSize :: FileHandle -> IO Int64
fileHandleSize (FileHandle handle) = output (c_duckdb_v2_file_size handle) >>= checkedPosition

-- | Set the absolute byte position.
fileHandleSeek :: FileHandle -> Int64 -> IO ()
fileHandleSeek (FileHandle handle) position
  | position < 0 = throwInvalidArgument "file offset is negative"
  | otherwise = checked (c_duckdb_v2_file_seek handle (fromIntegral position))

-- | Flush pending file writes to storage.
fileHandleSync :: FileHandle -> IO ()
fileHandleSync (FileHandle handle) = checked (c_duckdb_v2_file_sync handle)

-- | Test whether a file exists in DuckDB's file system. A directory gives 'False'.
pathExists :: Connection -> FilePath -> IO Bool
pathExists conn path = withPath conn path \fs name ->
  (/= 0) <$> output (c_duckdb_v2_file_system_path_exists fs name)

-- | Test whether DuckDB routes a path to a remote file system.
pathIsRemote :: Connection -> FilePath -> IO Bool
pathIsRemote conn path = withPath conn path \fs name ->
  (/= 0) <$> output (c_duckdb_v2_file_system_path_is_remote fs name)

-- | Expand a path with DuckDB's file-system rules.
expandPath :: Connection -> FilePath -> IO FilePath
expandPath conn path = withPath conn path \fs name -> do
  pieces <- newIORef []
  bracket
    ( toFunPtr
        ( DuckDBV2TextSinkFn_Aux
            ( \text _ err -> runCallback err do
                value <- peek (unConstPtr text) >>= readText
                modifyIORef' pieces (value :)
            )
        )
    )
    freeHaskellFunPtr
    \callback -> checked (c_duckdb_v2_file_system_path_expand fs name (DuckDBV2TextSinkFn callback) nullPtr)
  Text.unpack . Text.concat . reverse <$> readIORef pieces

-- | Collect glob matches in the order supplied by DuckDB.
globPaths :: Connection -> FilePath -> IO [FilePath]
globPaths conn pattern_ = withPath conn pattern_ \fs name -> do
  paths <- newIORef []
  bracket
    ( toFunPtr
        ( DuckDBV2FileSystemPathGlobCallbackFn_Aux
            ( \path _ err -> runCallback err do
                value <- peek (unConstPtr path) >>= readText
                modifyIORef' paths (Text.unpack value :)
            )
        )
    )
    freeHaskellFunPtr
    \callback -> checked (c_duckdb_v2_file_system_path_glob fs name (DuckDBV2FileSystemPathGlobCallbackFn callback) nullPtr)
  reverse <$> readIORef paths

-- | Move a path through DuckDB's file system.
movePath :: Connection -> FilePath -> FilePath -> IO ()
movePath conn source target
  | '\0' `elem` target = throwInvalidArgument "file path contains NUL"
  | otherwise = withPath conn source \fs name -> withText (Text.pack target) \destination ->
      checked (c_duckdb_v2_file_system_path_move fs name destination)

-- | Remove a file. Return whether DuckDB removed it.
removePath :: Connection -> FilePath -> IO Bool
removePath conn path = withPath conn path \fs name ->
  (/= 0) <$> output (c_duckdb_v2_file_system_path_remove fs name)

-- | Borrow the connection's file system and a checked path.
withPath :: Connection -> FilePath -> (DuckDBV2FileSystemHandle -> ConstPtr DuckDBV2Str -> IO a) -> IO a
withPath conn path action
  | '\0' `elem` path = throwInvalidArgument "file path contains NUL"
  | otherwise = withConnectionHandle conn \handle -> do
      fs <- output (c_duckdb_v2_connection_get_file_system handle)
      withText (Text.pack path) (action fs)

-- | Check the public signed range before converting a native byte position.
checkedPosition :: DuckDBIdx -> IO Int64
checkedPosition value
  | toInteger value > toInteger (maxBound :: Int64) = throwInternalError "file position exceeds Int64 range"
  | otherwise = pure (fromIntegral value)