-- SPDX-FileCopyrightText: 2026 Alexandra de Wit
--
-- SPDX-License-Identifier: MIT

-- | A scoped inflater over the existing streaming-commons ABI, with deterministic release on every exit.
module Ecluse.Core.Registry.Archive.Inflate (InflateFormat (..), withInflatedChunks, inflateBounded) where

import Data.ByteString qualified as BS
import Data.Streaming.Zlib.Lowlevel qualified as Z
import Foreign.C.Types (CInt)
import Foreign.ForeignPtr (ForeignPtr, mallocForeignPtrBytes, withForeignPtr)
import Foreign.Ptr (castPtr)
import UnliftIO.Exception (bracket, mask_, throwIO)

import Ecluse.Core.Registry (ParseError (..), parseRefusal)
import Ecluse.Core.Zlib (ZlibFault (InvalidZlibState, ZlibAllocationFailed), advanceStream, initialiseInflate, openStream, releaseInflate)

-- | Raw deflate, one zlib stream, or a bounded sequence of gzip members.
data InflateFormat = RawDeflate | ZlibStream | GzipMembers Int

data Inflater = Fresh !Int ByteString | Active !Int Z.ZStream' ByteString | Finished | Failed ParseError

-- | Use the pull action sequentially inside its callback. Empty output denotes the verified stream end.
withInflatedChunks :: InflateFormat -> (Int -> IO ()) -> ByteString -> (IO (Either ParseError ByteString) -> IO a) -> IO a
withInflatedChunks :: forall a.
InflateFormat
-> (Int -> IO ())
-> ByteString
-> (IO (Either ParseError ByteString) -> IO a)
-> IO a
withInflatedChunks InflateFormat
format Int -> IO ()
charge ByteString
bytes IO (Either ParseError ByteString) -> IO a
consume = do
    -- zlib documents a 32 KiB window plus 7 KiB state. One 32 KiB output buffer is reused.
    Int -> IO ()
charge (Int
32768 Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
7168 Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
chunkBytes)
    output <- Int -> IO (ForeignPtr Word8)
forall a. Int -> IO (ForeignPtr a)
mallocForeignPtrBytes Int
chunkBytes
    bracket (newIORef (Fresh 0 bytes)) close $ \IORef Inflater
owner -> IO (Either ParseError ByteString) -> IO a
consume (InflateFormat
-> IORef Inflater
-> ForeignPtr Word8
-> IO (Either ParseError ByteString)
nextChunk InflateFormat
format IORef Inflater
owner ForeignPtr Word8
output)

-- | Collect one payload of at most @bound@ inflated bytes, paying @73728 + 3 * held@ before keeping each chunk.
inflateBounded :: InflateFormat -> Text -> Int -> (Int -> IO ()) -> ByteString -> IO (Either ParseError ByteString)
inflateBounded :: InflateFormat
-> Text
-> Int
-> (Int -> IO ())
-> ByteString
-> IO (Either ParseError ByteString)
inflateBounded InflateFormat
format Text
refusal Int
bound Int -> IO ()
charge ByteString
bytes = InflateFormat
-> (Int -> IO ())
-> ByteString
-> (IO (Either ParseError ByteString)
    -> IO (Either ParseError ByteString))
-> IO (Either ParseError ByteString)
forall a.
InflateFormat
-> (Int -> IO ())
-> ByteString
-> (IO (Either ParseError ByteString) -> IO a)
-> IO a
withInflatedChunks InflateFormat
format Int -> IO ()
charge ByteString
bytes (Int
-> [ByteString]
-> IO (Either ParseError ByteString)
-> IO (Either ParseError ByteString)
collect Int
0 [])
  where
    collect :: Int
-> [ByteString]
-> IO (Either ParseError ByteString)
-> IO (Either ParseError ByteString)
collect Int
seen [ByteString]
held IO (Either ParseError ByteString)
pull =
        IO (Either ParseError ByteString)
pull IO (Either ParseError ByteString)
-> (Either ParseError ByteString
    -> IO (Either ParseError ByteString))
-> IO (Either ParseError ByteString)
forall a b. IO a -> (a -> IO b) -> IO b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
            Left ParseError
fault -> Either ParseError ByteString -> IO (Either ParseError ByteString)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (ParseError -> Either ParseError ByteString
forall a b. a -> Either a b
Left ParseError
fault)
            Right ByteString
chunk
                | ByteString -> Bool
BS.null ByteString
chunk -> Either ParseError ByteString -> IO (Either ParseError ByteString)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (ByteString -> Either ParseError ByteString
forall a b. b -> Either a b
Right ([ByteString] -> ByteString
BS.concat ([ByteString] -> [ByteString]
forall a. [a] -> [a]
reverse [ByteString]
held)))
                | ByteString -> Int
BS.length ByteString
chunk Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
> Int
bound Int -> Int -> Int
forall a. Num a => a -> a -> a
- Int
seen -> Either ParseError ByteString -> IO (Either ParseError ByteString)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Text -> Either ParseError ByteString
forall a. Text -> Either ParseError a
parseRefusal Text
refusal)
                | Bool
otherwise -> do
                    let next :: Int
next = Int
seen Int -> Int -> Int
forall a. Num a => a -> a -> a
+ ByteString -> Int
BS.length ByteString
chunk
                    Int -> IO ()
charge (Int
73728 Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
3 Int -> Int -> Int
forall a. Num a => a -> a -> a
* Int
next)
                    Int
-> [ByteString]
-> IO (Either ParseError ByteString)
-> IO (Either ParseError ByteString)
collect Int
next (ByteString
chunk ByteString -> [ByteString] -> [ByteString]
forall a. a -> [a] -> [a]
: [ByteString]
held) IO (Either ParseError ByteString)
pull

chunkBytes :: Int
chunkBytes :: Int
chunkBytes = Int
32768

nextChunk :: InflateFormat -> IORef Inflater -> ForeignPtr Word8 -> IO (Either ParseError ByteString)
nextChunk :: InflateFormat
-> IORef Inflater
-> ForeignPtr Word8
-> IO (Either ParseError ByteString)
nextChunk InflateFormat
format IORef Inflater
owner ForeignPtr Word8
output =
    IORef Inflater -> IO Inflater
forall (m :: * -> *) a. MonadIO m => IORef a -> m a
readIORef IORef Inflater
owner IO Inflater
-> (Inflater -> IO (Either ParseError ByteString))
-> IO (Either ParseError ByteString)
forall a b. IO a -> (a -> IO b) -> IO b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
        Inflater
Finished -> Either ParseError ByteString -> IO (Either ParseError ByteString)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (ByteString -> Either ParseError ByteString
forall a b. b -> Either a b
Right ByteString
BS.empty)
        Failed ParseError
fault -> Either ParseError ByteString -> IO (Either ParseError ByteString)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (ParseError -> Either ParseError ByteString
forall a b. a -> Either a b
Left ParseError
fault)
        Fresh Int
count ByteString
input
            | Int
count Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
>= InflateFormat -> Int
memberLimit InflateFormat
format -> IORef Inflater -> Text -> IO (Either ParseError ByteString)
failStream IORef Inflater
owner Text
"compressed member count exceeds its bound"
            | Bool
otherwise -> do
                IO () -> IO ()
forall (m :: * -> *) a. MonadUnliftIO m => m a -> m a
mask_ (IO () -> IO ()) -> IO () -> IO ()
forall a b. (a -> b) -> a -> b
$ InflateFormat -> IO ZStream'
acquire InflateFormat
format IO ZStream' -> (ZStream' -> IO ()) -> IO ()
forall a b. IO a -> (a -> IO b) -> IO b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \ZStream'
native -> IORef Inflater -> Inflater -> IO ()
forall (m :: * -> *) a. MonadIO m => IORef a -> a -> m ()
writeIORef IORef Inflater
owner (Int -> ZStream' -> ByteString -> Inflater
Active (Int
count Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
1) ZStream'
native ByteString
input)
                InflateFormat
-> IORef Inflater
-> ForeignPtr Word8
-> IO (Either ParseError ByteString)
nextChunk InflateFormat
format IORef Inflater
owner ForeignPtr Word8
output
        Active Int
count ZStream'
native ByteString
input -> do
            (status, consumed, bytes) <- ZStream'
-> ByteString -> ForeignPtr Word8 -> IO (CInt, Int, ByteString)
step ZStream'
native ByteString
input ForeignPtr Word8
output
            let remaining = Int -> ByteString -> ByteString
BS.drop Int
consumed ByteString
input
            case status of
                CInt
1 -> do
                    IORef Inflater -> IO ()
close IORef Inflater
owner
                    case InflateFormat
format of
                        InflateFormat
RawDeflate | Bool -> Bool
not (ByteString -> Bool
BS.null ByteString
remaining) -> IORef Inflater -> Text -> IO (Either ParseError ByteString)
failStream IORef Inflater
owner Text
"deflate member has trailing compressed bytes"
                        InflateFormat
ZlibStream | Bool -> Bool
not (ByteString -> Bool
BS.null ByteString
remaining) -> IORef Inflater -> Text -> IO (Either ParseError ByteString)
failStream IORef Inflater
owner Text
"zlib stream has trailing compressed bytes"
                        GzipMembers Int
_ | Bool -> Bool
not (ByteString -> Bool
BS.null ByteString
remaining) -> do
                            IORef Inflater -> Inflater -> IO ()
forall (m :: * -> *) a. MonadIO m => IORef a -> a -> m ()
writeIORef IORef Inflater
owner (Int -> ByteString -> Inflater
Fresh Int
count ByteString
remaining)
                            ByteString -> IO (Either ParseError ByteString)
emitOrContinue ByteString
bytes
                        InflateFormat
_ -> Either ParseError ByteString -> IO (Either ParseError ByteString)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (ByteString -> Either ParseError ByteString
forall a b. b -> Either a b
Right ByteString
bytes)
                CInt
0
                    | Int
consumed Int -> Int -> Bool
forall a. Eq a => a -> a -> Bool
== Int
0 Bool -> Bool -> Bool
&& ByteString -> Bool
BS.null ByteString
bytes -> IORef Inflater -> Text -> IO (Either ParseError ByteString)
failStream IORef Inflater
owner Text
"compressed stream made no progress"
                    | Bool
otherwise -> do
                        IORef Inflater -> Inflater -> IO ()
forall (m :: * -> *) a. MonadIO m => IORef a -> a -> m ()
writeIORef IORef Inflater
owner (Int -> ZStream' -> ByteString -> Inflater
Active Int
count ZStream'
native ByteString
remaining)
                        ByteString -> IO (Either ParseError ByteString)
emitOrContinue ByteString
bytes
                -4 -> ZlibFault -> IO (Either ParseError ByteString)
forall (m :: * -> *) e a. (MonadIO m, Exception e) => e -> m a
throwIO ZlibFault
ZlibAllocationFailed
                -2 -> ZlibFault -> IO (Either ParseError ByteString)
forall (m :: * -> *) e a. (MonadIO m, Exception e) => e -> m a
throwIO (CInt -> ZlibFault
InvalidZlibState CInt
status)
                CInt
_ -> IORef Inflater -> Text -> IO (Either ParseError ByteString)
failStream IORef Inflater
owner Text
"malformed or truncated compressed stream"
  where
    emitOrContinue :: ByteString -> IO (Either ParseError ByteString)
emitOrContinue ByteString
bytes = if ByteString -> Bool
BS.null ByteString
bytes then InflateFormat
-> IORef Inflater
-> ForeignPtr Word8
-> IO (Either ParseError ByteString)
nextChunk InflateFormat
format IORef Inflater
owner ForeignPtr Word8
output else Either ParseError ByteString -> IO (Either ParseError ByteString)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (ByteString -> Either ParseError ByteString
forall a b. b -> Either a b
Right ByteString
bytes)

memberLimit :: InflateFormat -> Int
memberLimit :: InflateFormat -> Int
memberLimit InflateFormat
RawDeflate = Int
1
memberLimit InflateFormat
ZlibStream = Int
1
memberLimit (GzipMembers Int
limit) = Int
limit

-- Allocation failures belong to the worker fault boundary, not the archive-refusal result.
acquire :: InflateFormat -> IO Z.ZStream'
acquire :: InflateFormat -> IO ZStream'
acquire InflateFormat
format = (ZStream' -> IO CInt) -> IO ZStream'
openStream (ZStream' -> CInt -> IO CInt
`initialiseInflate` (case InflateFormat
format of InflateFormat
RawDeflate -> -CInt
15; InflateFormat
ZlibStream -> CInt
15; GzipMembers Int
_ -> CInt
31))

close :: IORef Inflater -> IO ()
close :: IORef Inflater -> IO ()
close IORef Inflater
owner = IO () -> IO ()
forall (m :: * -> *) a. MonadUnliftIO m => m a -> m a
mask_ (IO () -> IO ()) -> IO () -> IO ()
forall a b. (a -> b) -> a -> b
$ do
    previous <- IORef Inflater -> (Inflater -> (Inflater, Inflater)) -> IO Inflater
forall (m :: * -> *) a b.
MonadIO m =>
IORef a -> (a -> (a, b)) -> m b
atomicModifyIORef' IORef Inflater
owner (Inflater
Finished,)
    case previous of
        Active Int
_ ZStream'
native ByteString
_ -> ZStream' -> IO ()
releaseInflate ZStream'
native
        Fresh{} -> () -> IO ()
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure ()
        Inflater
Finished -> () -> IO ()
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure ()
        Failed{} -> () -> IO ()
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure ()

failStream :: IORef Inflater -> Text -> IO (Either ParseError ByteString)
failStream :: IORef Inflater -> Text -> IO (Either ParseError ByteString)
failStream IORef Inflater
owner Text
message = do
    IORef Inflater -> IO ()
close IORef Inflater
owner
    let fault :: ParseError
fault = Text -> ParseError
ParseError Text
message
    IORef Inflater -> Inflater -> IO ()
forall (m :: * -> *) a. MonadIO m => IORef a -> a -> m ()
writeIORef IORef Inflater
owner (ParseError -> Inflater
Failed ParseError
fault)
    Either ParseError ByteString -> IO (Either ParseError ByteString)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (ParseError -> Either ParseError ByteString
forall a b. a -> Either a b
Left ParseError
fault)

step :: Z.ZStream' -> ByteString -> ForeignPtr Word8 -> IO (CInt, Int, ByteString)
step :: ZStream'
-> ByteString -> ForeignPtr Word8 -> IO (CInt, Int, ByteString)
step ZStream'
native ByteString
input ForeignPtr Word8
output =
    ForeignPtr Word8
-> (Ptr Word8 -> IO (CInt, Int, ByteString))
-> IO (CInt, Int, ByteString)
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtr ForeignPtr Word8
output ((Ptr Word8 -> IO (CInt, Int, ByteString))
 -> IO (CInt, Int, ByteString))
-> (Ptr Word8 -> IO (CInt, Int, ByteString))
-> IO (CInt, Int, ByteString)
forall a b. (a -> b) -> a -> b
$ \Ptr Word8
destination -> do
        (status, consumed, written) <- (ZStream' -> IO CInt)
-> ZStream'
-> ByteString
-> Ptr Word8
-> Int
-> IO (CInt, Int, Int)
advanceStream ZStream' -> IO CInt
Z.c_call_inflate_noflush ZStream'
native (Int -> ByteString -> ByteString
BS.take Int
chunkBytes ByteString
input) Ptr Word8
destination Int
chunkBytes
        bytes <- BS.packCStringLen (castPtr destination, written)
        pure (status, consumed, bytes)