Errors.hs

-- | Module      : IPLD.DagCBOR.Decoder.Errors
--   Description : Invalid states for DAG-CBOR Decoder
--   Copyright   : Zoey McBride (c) 2026
--   License     : AGPL-3.0-or-later
--   Maintainer  : zoeymcbride@mailbox.org
--   Stability   : experimental
module IPLD.DagCBOR.Decoder.Errors
  ( -- * Functor for wrapping results w/ error.
    Okay,

    -- * Error constructors
    Error (..),

    -- * For resolving items and changing decoder data.
    DecoderMethod,
    DecoderRoutine,

    -- * Results from running DecoderMethods
    Result (Result),
    pattern Finish,
  )
where

import Control.DeepSeq (NFData (..))
import Data.Bifunctor (Bifunctor (bimap))
import IPLD.DM.Decoder qualified as DM
import MultiFormats.CID.Errors qualified as CID

-- | The Result value `obj` and the remaining input tokens.
data Result obj bxc = Result obj bxc deriving (Show, Eq)

instance Functor (Result obj) where
  fmap f (Result a b) = Result a (f b)

instance Bifunctor Result where
  bimap f g (Result a b) = Result (f a) (g b)

-- | Short hand for data model DecoderMethod in DagCBOR.
type DecoderMethod item bxc = DM.DecoderMethod item bxc Okay Result

-- | Short hand for a `DecoderMethod` with a Null `Result` item.
type DecoderRoutine bxc = DecoderMethod () bxc

-- | Pattern synonym for routine bytes results.
pattern Finish :: forall bxc. bxc -> Result () bxc
pattern Finish bxc = Result () bxc

-- | Type-alias for erroring results.
type Okay = Either Error

-- | Provides errors for parsing major-type arguments.
data Error
  = -- | Used to implement the empty in `Alternative`.
    EmptyAlternative
  | -- | When the file was parsed with trailing bytes.
    TrailingBytes
  | -- | When a collection is marked indefinite.
    Indefinite
  | -- | When the undefined simple value is given.
    NotDefined
  | -- | When an invalid tag id is given.
    InvalidTag
  | -- | When -∞, ∞, or NaN is encountered, these are not supported.
    InvalidIEEE754
  | -- | For parameters marked reserved in RFC-8949.
    ReservedParam
  | -- | When a section of data expects more, but there is none, leaving gaps.
    Fragmented
  | -- | When the decoder finished unexpectedly.
    UnexpectedStop
  | -- | When some identifier is expected, but another is found.
    UnexpectedValue
  | -- | When converting CBOR IntData to smaller values fail.
    DowncastFailed
  | -- | For integers that aren't minimally encoded.
    NotMinimal
  | -- | When the major-type for a map isn't a string. IPLD forbids this.
    NotStringKey
  | -- | When two or more of the keys in a CBOR map are not unique.
    NotUniqueKey
  | -- | IPLD forbids maps with non-lexographically sorted strings.
    NotSortedMap
  | -- | Passes CID operation errors.
    CIDError CID.Error
  | -- | Marks unimplemented feature of DAG-CBOR and developement assertions.
    NotImplemented String
  deriving (Eq, Show)

-- | Fully instantiates an Error object from lazy Haskell object.
instance NFData Error where
  rnf (CIDError ciderr) = rnf ciderr
  rnf (NotImplemented devmsg) = rnf devmsg
  rnf _ = ()