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

{- | Length framing for byte strings that stand for a tuple of components: the input of a digest, or
the identity of a cache key. Each component carries its own length, so no content can pass for a boundary.
-}
module Ecluse.Core.Server.Framing (
    frameBytes,
    putFrame,
    frameComponents,
) where

import Control.Monad.ST (ST)
import Data.ByteString qualified as BS
import Data.ByteString.Builder (Builder, byteString, intDec)
import Data.ByteString.Builder.Extra (smallChunkSize, toLazyByteStringWith, untrimmedStrategy)
import Data.ByteString.Lazy qualified as LBS

import Ecluse.Core.Registry.Json.Scratch (Scratch, putByte, putDecimal)

-- | One component: its decimal byte length, a colon, then its bytes.
frameBytes :: ByteString -> Builder
frameBytes :: ByteString -> Builder
frameBytes ByteString
bytes = Int -> Builder
intDec (ByteString -> Int
BS.length ByteString
bytes) Builder -> Builder -> Builder
forall a. Semigroup a => a -> a -> a
<> Builder
":" Builder -> Builder -> Builder
forall a. Semigroup a => a -> a -> a
<> ByteString -> Builder
byteString ByteString
bytes

-- | 'frameBytes' in a scratch buffer: the byte length, a colon, then a writer of exactly that many bytes.
putFrame :: Scratch st -> Int -> ST st () -> ST st ()
putFrame :: forall st. Scratch st -> Int -> ST st () -> ST st ()
putFrame Scratch st
scratch Int
len ST st ()
body = Scratch st -> Int -> ST st ()
forall st. Scratch st -> Int -> ST st ()
putDecimal Scratch st
scratch Int
len ST st () -> ST st () -> ST st ()
forall a b. ST st a -> ST st b -> ST st b
forall (m :: * -> *) a b. Monad m => m a -> m b -> m b
>> Scratch st -> Word8 -> ST st ()
forall st. Scratch st -> Word8 -> ST st ()
putByte Scratch st
scratch Word8
0x3a ST st () -> ST st () -> ST st ()
forall a b. ST st a -> ST st b -> ST st b
forall (m :: * -> *) a b. Monad m => m a -> m b -> m b
>> ST st ()
body

{- | A tuple's components in order, so that no two tuples frame to the same bytes. An absent
component is a lone @-@, which no length starts with, so it never frames as the shorter tuple.
-}
frameComponents :: [Maybe ByteString] -> ByteString
frameComponents :: [Maybe ByteString] -> ByteString
frameComponents [Maybe ByteString]
components =
    LazyByteString -> ByteString
LBS.toStrict (AllocationStrategy -> LazyByteString -> Builder -> LazyByteString
toLazyByteStringWith (Int -> Int -> AllocationStrategy
untrimmedStrategy Int
room Int
smallChunkSize) LazyByteString
LBS.empty Builder
frames)
  where
    frames :: Builder
frames = (Maybe ByteString -> Builder) -> [Maybe ByteString] -> Builder
forall m a. Monoid m => (a -> m) -> [a] -> m
forall (t :: * -> *) m a.
(Foldable t, Monoid m) =>
(a -> m) -> t a -> m
foldMap (Builder -> (ByteString -> Builder) -> Maybe ByteString -> Builder
forall b a. b -> (a -> b) -> Maybe a -> b
maybe Builder
"-" ByteString -> Builder
frameBytes) [Maybe ByteString]
components
    -- Each present component gets its bytes, a colon, and the 20 free bytes the writer wants before a length.
    -- An absent one gets the 4 it wants before a marker. A component over the builder's copy limit is its own chunk.
    room :: Int
room = [Int] -> Int
forall a (f :: * -> *). (Foldable f, Num a) => f a -> a
sum ((Maybe ByteString -> Int) -> [Maybe ByteString] -> [Int]
forall a b. (a -> b) -> [a] -> [b]
map (Int -> (ByteString -> Int) -> Maybe ByteString -> Int
forall b a. b -> (a -> b) -> Maybe a -> b
maybe Int
4 ((Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
21) (Int -> Int) -> (ByteString -> Int) -> ByteString -> Int
forall b c a. (b -> c) -> (a -> b) -> a -> c
. ByteString -> Int
BS.length)) [Maybe ByteString]
components)