{-# language DerivingStrategies #-}
{-# language DeriveAnyClass #-}

-- | All of the exceptions defined in this module indicate either misuse
-- of the library or an implementation mistake in the libary.
module Network.Unexceptional.Types
  ( NonpositiveReceptionSize(..)
  , ReceivedTooManyBytes(..)
  ) where

import Control.Exception (Exception)

-- | Thrown when any of the @receive@ functions are called with
-- a length less than 1. This includes zero and any negative numbers.
-- This indicates misuse of the API and is not considered a recoverable
-- exception.
--
-- Requesting a negative number is bytes is clear misuse of the API.
-- But what about zero? This deserves some justification. POSIX allows
-- requesting zero bytes with @recv@, and the result is that it copies
-- no bytes into the buffer and returns 0. Essentially, it's a no-op.
-- However, the return length 0 is also used to indicate a shutdown.
-- This overloaded meaning of the return value 0 makes it difficult to
-- interpret what it means. (It would be nice if @recv@ instead set the
-- error code to something indicating EOF when the peer had shutdown,
-- but we live in a more difficult world.) To correctly interpret the
-- meaning of return length 0, an application must consider what buffer
-- size it passed to @recv@. To prevent the caller from having to do this
-- bookkeeping, this library simply forbids requesting 0 bytes with @recv@.
-- If you do request 0 bytes with @recv@, you get this exception, and you
-- can fix the part of your program that failed to satisfy the
-- precondition.
data NonpositiveReceptionSize = NonpositiveReceptionSize
  deriving stock (Show)
  deriving anyclass (Exception)

-- | This indicates a mistake in this library. Open an issue if this
-- exception is ever thrown. 
data ReceivedTooManyBytes = ReceivedTooManyBytes
  deriving stock (Show)
  deriving anyclass (Exception)