% !TeX root = ../Thesis.tex

%********************************************************************
% Some Proof (Appendix)
%*******************************************************
% -- TemplateKnob
% If problems with the headers: get headings in appendix etc. right
%\markboth{\spacedlowsmallcaps{Appendix}}{\spacedlowsmallcaps{Appendix}}
\chapter{Some Proof}\label{ch:SomeProof}
\glsresetall % Resets all acronyms to not used

\section{Exception Handling}
\label{sec:exception-handling}

% Idea: have exception class which inherits from EuiccException base class -> class has mapping from error code to exception
% erorrs are reused by other functions -> have errors inherit from base class and function based errors raise these errors -> restructure inheritence before raising so that inheritence order is: ErrorException <- FunctionException <- common EuiccBaseException
% ErrorException can be like IccidOrAidNotFound Exception and function exception can be something like ProfileInteractionException
% Goal: Capture all exception that are possibly raised by a function but still have access to more granualar exception handling
% lising1 shows CodeBaseException from which the functionexceptions inherit: restructures exception inheritance from error_map to have all mapped exception inherit from the functionexception instead of the common base exception
% listing2 shows implemention of a function exception class with a fill error_map and some example error exception


Robust exception handling is critical in the context of \gls{euicc} interactions, especially when performing differential testing. The SGP.22 specification defines a comprehensive set of error codes, many of which are reused across different functions. To allow both coarse-grained and fine-grained error handling, the exception hierarchy in our implementation is explicitly structured around two core ideas:

\begin{itemize}
  \item \textbf{Function-based exceptions} encapsulate the context in which the error occurred (e.g., Profile Management, \gls{isdr} interactions).
  \item \textbf{Error-based exceptions} represent the specific error raised (e.g., \gls{iccid} not found, \gls{aid} missing).
\end{itemize}

All exceptions inherit from a common \texttt{EuiccException} base class, ensuring they can be captured uniformly when needed.

\subsection*{Exception Hierarchy}

The exception hierarchy is structured such that all specific error exceptions (e.g. \texttt{IccidNotFound}) inherit from a relevant function exception (e.g. \texttt{ProfileInteractionException}), which itself inherits from \texttt{EuiccException}. This enables both precise and broad exception matching, depending on the caller’s needs. For example:

\begin{center}
\texttt{EuiccException} $\rightarrow$ \texttt{ProfileInteractionException} $\rightarrow$ \texttt{IccidOrAidNotFound}
\end{center}

This structure is illustrated in \cref{lst:code-base-exception} and \cref{lst:function-exception}.

\begin{lstlisting}[language=python,label={lst:code-base-exception},caption={Class to raise exception based on the error code and restructure the inheritance.}]
class CodeBaseException(EuiccException):
    """Base class for all exceptions raised by the result handling."""

    message: str = "An unknown code error occurred"
    error_map: dict[int, Type['EuiccException']]

    def __init__(self, message: str | None = None):
        if message:
            self.message = message

        super().__init__(self.message)

    @classmethod
    def raise_from_code(cls, code: int):
        """Raises the appropriate exception subclass based on the error code."""
        exception_class = cls.error_map.get(code, UndefinedError)
        exception_class.__bases__ = (cls,)

        raise exception_class()
\end{lstlisting}

\begin{lstlisting}[language=python,label={lst:function-exception},caption={Implementation of the \lstinline{CodeBaseException} Class.}]
class ProfileInteractionException(CodeBaseException):
    """Base class for all exceptions raised by the profile handling."""

    message: str = "An unknown profile interaction error occurred"
    error_map = {
        1: IccidOrAidNotFound,
        2: ProfileNotInEnabledState,
        3: DisallowedByPolicy,
        4: WrongProfileReenabling,
        5: CatBusy,
        6: DisallowedByEnterpriseRule,
        7: CommandError,
        8: DisallowedForRpm,
        9: NoEsimPortAvailable,
        127: UndefinedError,
    }
    
class IccidOrAidNotFound(EuiccException):
    message = "ICCID or AID not found"
\end{lstlisting}

\subsection*{Benefits}

This exception model provides the following advantages:
\begin{itemize}
  \item \textbf{Modular extensibility:} New error types can be added per function with minimal changes.
  \item \textbf{Granular diagnostics:} Developers can differentiate between general failure (\texttt{ProfileInteractionException}) and specific causes (\texttt{IccidNotFoundException}).
  \item \textbf{Cleaner call sites:} Exceptions can be caught using either the general or specific class, depending on context.
\end{itemize}

This exception system enables detailed introspection during fuzzing and testing while maintaining a clean abstraction between components.