apotheca / botan Goto Github PK

Error handling

1. The library does not need to throw exceptions on any level.

   The control flow when interfacing with a C library inevitably unrolls to

   handle (\(BotanException r) -> pure r) $ do
     r0 <- botan_foo
     if r0 < 0
       then throw $ BotanException r0
       else do
         r1 <- botan_bar
         ...

   so you can skip all the busywork and just write the following instead

   r0 <- botan_foo
   if r0 < 0
     then pure r0
     else do
       r1 <- botan_bar
       ...

2. Error unification makes the API more complex.

   Most of the functions will only have a few Haskell-level errors and library users do not need error interoperability across the entire library. Making each distinct function have its own error type will also allow for better documentation.

   Unfortunately Botan API does not version errors, so those will have to be passed around as CInts without clarification.

Organization

1. botan-low should work over pointers and sizes, not Haskell datatypes.

   By creating a basic datatype like Bytes = Bytes (Ptr Word8) Int you can leave allocations out of this level. Conversions to such datatypes are generic and you don't need to unbox anything, the simplifier will inline the datatype for you.

2. botan-low can store algorithm names raw using MagicHash: the format is Ptr "Foo\0"#, the result is a C string.

Library structure

1. Preludes and default extensions are bad practices.

   It's easy to add an extra import to a custom prelude, it's hard to remove it, so over time these things bloat, slowing down everything and making the library harder to navigate. Consider creating special modules for functions that need to be shared and inlining function wrappers.

2. Algorithm enumerations may be harmful on the high level, as the C library may not support certain algorithms or support ones you didn't expect.

3. Tests do not need to rely on packages they're in, you can share the source files instead.

   This also allows you to test internal modules without exposing them.

botan.cabal mentions Botan.KeyWrap but no such module seems to be in the repository.

Hey,

I think it would be nice if the library used ByteStringS instead of memory. Any particular reason you chose to use it? IIUC memory suffers from similar fate other Vincent's libraries do.