packages feed

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

{-# LANGUAGE BlockArguments #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE StrictData #-}

-- |
-- Module      : Database.DuckDB.Simple.Logging.Internal
-- Description : Share the log sink registration for connections and extensions.
--
-- The cabal file lists this hidden module in @other-modules@.
-- 'registerLogSinkOn' takes a registration target.
-- "Database.DuckDB.Simple.Logging" exports the connection and instance forms.
-- "Database.DuckDB.Simple.Extension" exports the extension form.
module Database.DuckDB.Simple.Logging.Internal (
  LogEntry (..),
  LogLevel (..),
  LogScope (..),
  registerLogStorage,
  registerLogSink,
  registerInstanceLogSink,
  registerLogSinkOn,
  logConnectionMessage,
  logInstanceMessage,
) where

import Control.Exception (bracket)
import Control.Monad (when)
import Data.Ratio ((%))
import Data.Text (Text)
import qualified Data.Text as Text
import Data.Time.Clock (UTCTime)
import Data.Time.Clock.POSIX (posixSecondsToUTCTime)
import Data.Word (Word64)
import Database.DuckDB.Simple.Callback (
  RegistrationTarget (..),
  attachOpaque,
  install,
  installAll,
  requireWorkerCallbackRuntime,
  runCallback,
  withCallbackResourcesFinally,
 )
import Database.DuckDB.Simple.Internal (Connection, Instance, withConnectionHandle, withDatabaseHandle, withInstanceHandle)
import Database.DuckDB.Simple.Native
import Foreign.C.ConstPtr (ConstPtr (..))
import Foreign.C.Types (CBool)
import Foreign.Marshal.Alloc (alloca)
import Foreign.Ptr (Ptr)
import Foreign.Storable (peek)

-- | A copied log event. Native context identifiers are absent outside their scope.
data LogEntry = LogEntry
  { logEntryTimestamp :: Maybe UTCTime
  , logEntryLevel :: Text
  , logEntryType :: Text
  , logEntryMessage :: Text
  , logEntrySeverity :: LogLevel
  , logEntryScope :: LogScope
  , logEntryConnectionId :: Maybe Word64
  , logEntryTransactionId :: Maybe Word64
  , logEntryQueryId :: Maybe Word64
  , logEntryThreadId :: Maybe Word64
  }
  deriving (Eq, Show)

-- | Register a log sink without a flush action.
-- Select the sink through DuckDB's logging configuration to receive entries.
registerLogStorage :: Connection -> Text -> (LogEntry -> IO ()) -> IO ()
registerLogStorage conn name write = registerLogSink conn name write (pure ())

-- | Register an instance log sink through a live connection. Log sinks require
-- the threaded GHC runtime (@-threaded@), including with one query thread.
-- Callbacks can run concurrently on native threads. They must not log or change
-- logging settings. Native logging discards callback errors after containment.
-- The flush action also runs when DuckDB releases the sink. If the registration
-- fails after the name check, the flush action runs one time.
registerLogSink :: Connection -> Text -> (LogEntry -> IO ()) -> IO () -> IO ()
registerLogSink conn name write flush = withDatabaseHandle conn \instance_ ->
  withInstanceFactory instance_ \factory ->
    registerSink
      factory
      (checked . c_duckdb_v2_instance_register_log_sink instance_)
      name
      write
      flush

-- | Register a log sink on an explicitly managed instance. If the registration
-- fails after the name check, the flush action runs one time.
registerInstanceLogSink :: Instance -> Text -> (LogEntry -> IO ()) -> IO () -> IO ()
registerInstanceLogSink instance_ name write flush = withInstanceHandle instance_ \native ->
  withInstanceFactory native \factory ->
    registerSink
      factory
      (checked . c_duckdb_v2_instance_register_log_sink native)
      name
      write
      flush

-- | Register a log sink on a connection or a loading extension.
registerLogSinkOn :: RegistrationTarget -> Text -> (LogEntry -> IO ()) -> IO () -> IO ()
registerLogSinkOn target name write flush = case target of
  ConnectionTarget conn -> registerLogSink conn name write flush
  ExtensionTarget extension context -> withContextFactory context \factory ->
    registerSink
      factory
      (checked . c_duckdb_v2_extension_register_log_sink extension)
      name
      write
      flush

-- | Transfer callback ownership to the native sink and release its builder.
registerSink
  :: DuckDBV2FactoryHandle -> (DuckDBV2LogSinkHandle -> IO ()) -> Text -> (LogEntry -> IO ()) -> IO () -> IO ()
registerSink factory register name write flush = do
  when (Text.null name || Text.any (== '\0') name) $ throwInvalidArgument "log sink name must be nonempty and must not contain NUL"
  bracket (output (c_duckdb_v2_log_sink_create factory)) (destroy c_duckdb_v2_log_sink_destroy) \sink ->
    withCallbackResourcesFinally
      (requireWorkerCallbackRuntime "log sink")
      flush
      ( \allocate ->
          installAll
            [ install
                allocate
                DuckDBV2LogSinkWriteCallbackFn
                ( DuckDBV2LogSinkWriteCallbackFn_Aux \info _ timestamp level scope (ConstPtr kind) (ConstPtr message) err -> runCallback err do
                    category <- peek kind >>= readText
                    body <- peek message >>= readText
                    connection <- optionalId (c_duckdb_v2_log_sink_write_info_get_connection_id info)
                    transaction <- optionalId (c_duckdb_v2_log_sink_write_info_get_transaction_id info)
                    query <- optionalId (c_duckdb_v2_log_sink_write_info_get_query_id info)
                    thread <- optionalId (c_duckdb_v2_log_sink_write_info_get_thread_id info)
                    severity <- logLevelFromNative level
                    origin <- logScopeFromNative scope
                    let time = posixSecondsToUTCTime (fromRational (toInteger timestamp % 1000000))
                    write (LogEntry (Just time) (levelName severity) category body severity origin connection transaction query thread)
                )
                (c_duckdb_v2_log_sink_set_write_callback sink)
            , install
                allocate
                DuckDBV2LogSinkFlushCallbackFn
                (DuckDBV2LogSinkFlushCallbackFn_Aux \_ _ err -> runCallback err flush)
                (c_duckdb_v2_log_sink_set_flush_callback sink)
            ]
      )
      (attachOpaque (c_duckdb_v2_log_sink_set_user_data sink))
      \installCallbacks -> do
        withIdentifier name $ checked . c_duckdb_v2_log_sink_set_name sink
        installCallbacks
        register sink

-- | Copy an optional identifier from a borrowed log-entry context.
optionalId :: (Ptr DuckDBIdx -> Ptr CBool -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error) -> IO (Maybe Word64)
optionalId getter = alloca \present -> do
  value <- output (\slot -> getter slot present)
  exists <- peek present
  pure (if exists == 0 then Nothing else Just (fromIntegral value))

-- | Retain the textual severity names of the log-storage interface.
levelName :: LogLevel -> Text
levelName = \case
  LogLevelTrace -> "TRACE"
  LogLevelDebug -> "DEBUG"
  LogLevelInfo -> "INFO"
  LogLevelWarning -> "WARNING"
  LogLevelError -> "ERROR"
  LogLevelFatal -> "FATAL"

-- | Emit a connection-scoped message through its current logging configuration.
logConnectionMessage :: Connection -> LogLevel -> Text -> Text -> IO ()
logConnectionMessage conn level category message = withConnectionHandle conn \native ->
  withText category \kind -> withText message \body ->
    checked (c_duckdb_v2_connection_log native (logLevelToNative level) kind body)

-- | Emit a database-scoped message on an explicit instance.
logInstanceMessage :: Instance -> LogLevel -> Text -> Text -> IO ()
logInstanceMessage instance_ level category message = withInstanceHandle instance_ \native ->
  withText category \kind -> withText message \body ->
    checked (c_duckdb_v2_instance_log native (logLevelToNative level) kind body)