![\"Abstraction](\"/files/fall-f80554c0d842f42384135cac3c4c5cd2.png\")
Abstraction layers breaking down.
We cover the basics of correct error handling, so it is no longer an afterthought.\nIn previous post, we left some crucial questions unanswered, such as\n“What exactly makes an error recoverable?”.
In this post, we dive into levels of abstraction and what they mean for error handling.
\n--- excerpt ---
\nIn previous post, we defined an error as a\nbroken assumption, then split those into unexpected errors and expected errors.\nEventually, we outlined a decision process, leaving some crucial questions unanswered, namely:
\nWe said the key to answering those is keeping levels of abstraction consistent,\nand that is the subject of this post.
\nA level of abstraction is a consistent\nview of a set of related concepts or components of an application.\nWe decompose that view into contracts that specify\nwhat each part does and what it requires. In software design, those contracts are usually\nformalized as interfaces.
\nAbstractions hide the innards of components, allowing\nseparation of concerns and\ninteroperability.\nThat is, they enable reasoning about and re-using components as black‑boxes, not caring\nabout their working details.
\nFor instance an http module might provide an abstraction of connecting to webservers to download\ndocuments and all of a sudden, we can “fetch-that-url” and not worry about how\nthe fetching works.
\n\nhttp_fetch(
\nurl) →bytes
\nRetrieve a document over HTTP.\n
- Arguments
url: address of document to retrieve.
- Returns
Document content as a
bytesobject.
We might say we lie on top of that abstraction layer.
\nUnderneath, that http module probably only implements the logic that deals with the HTTP\nprotocol itself. For the actual sending and receiving of data, it will rely on other\nabstraction layers down the line. Maybe some encryption layer for SSL, some connection\npooling layer, a low-level networking layer, …
\nThus we compose our applications by stacking and juxtaposing abstraction layers,\niteratively decomposing our use case until we have all the details sorted out,\nor composing increasingly complex features until we can answer our use case.\nAs long as we keep those abstraction layers isolated from each other, communicating\nonly though their interfaces, everything is fine.
\nUntil it fails.
\nSay the encryption layer in our example above fails to fulfill its contract\nbecause the peer rejected our certificate. What now?
\nThe answers lie in our design. When we model our layers of abstraction, we define interfaces\nthat formalize what our components can do and what they require.
\n![\"Design](\"/files/contract-a44f57a27fb319ba08238a69aeda0a93.png\")
Excluding straight bugs, this implicitly creates two realms for errors:
\nThe client/caller of the component fails to meet the requirements\n(eg: it provides an invalid URL).
Our component fails to fulfill its contract, either by failing to produce side-effects,\nor by failing to reach postconditions. At this stage, this is usually because of external\nconditions (eg: network is down).
Preconditions violations are easy. The interface must simply state either that:
\nthis is forbidden and such program is ill-formed (ie: this is a bug).\nWhich means this is unexpected error territory.
\ndef http_fetch(url):\n # force crash on interface violation\n assert is_valid_url(url)or this is an expected error that will get reported. The interface then defines how.\nIn this example, it generates a python ValueError exception.
def http_fetch(url):\n if not is_valid_url(url):\n raise ValueError(\"invalid url\")Mixing is possible: for instance the interface could define that passing an improper\nurl type (eg: a number instead of a string) is a bug, while passing a string that\nholds an invalid url generates an error.
Interesting errors are those belonging to the latter realm: the component we are designing\nfails to fulfill its contract.
\nWe must define this failure. As software designer, our job is to create a language.\nWe define interfaces, which are somewhat like things, bearing nouns: HTTPConnector,\nCookieJar, etc. And we define tasks, which are somewhat like verbs: fetchDocument,\nsaveCookies, etc.
\nAs we do so, we pick the correct granularity, giving power and flexibility but not so\nmuch that simple tasks become a chore. Identifying all relevant interfaces,\ngrouping or splitting them correctly, and differentiating between\nimplementation details we hide and features we expose is an art.
\nAnd that art applies to errors as well: it is our job as a designer to:
\nTogether, those tasks create a language of errors.
\nAn interesting consequence is that this language is specific to the abstraction layer we\nare designing. This means that:
\nwhat is an error at a level of abstraction might not be at levels above.
\nThe upper layer might expect that error and have a recovery process in place. For instance,\nthe interface specification of http_fetch function above might define that failure\nto connect shall be resolved by falling back to a cached copy. Thus, a connection error\ndoes not necessarily imply an http_fetch error.
Hey, we just answered our first question:
\n\n\n\n
- What makes an error recoverable?
➥ An error is recoverable, at a specific level of abstraction, if and only if that\nlevel defines a recovery process for that error.
This is why error handling focuses a lot on abstraction boundaries: different abstraction\nlayers speak a different error language, so translation should happen when crossing boundaries.
\nSummarizing our thoughts so far:
\n\n\n\n
- What is meant by exposing internals?
➥ Errors are part of abstraction.
\n➥ The purpose of abstractions is to encapsulate and hide details.
\n➥ As a part of abstraction, errors contribute to encapsulation.
In particular, when an error cannot be recovered from at a specific level of abstraction, we\nstill must ensure encapsulation is not broken. We do this by translating from lower-level\nerror language to the error language of current level.\nThat is, we convert the error.
\nNamely, proper error conversion should:
\nFor instance, assuming we designed our interface as a very simplistic one, hiding SSL usage,\nand we grouped all transfer-related errors under a generic TransferError, we could write:
try:\n connection.do_handshake()\nexcept SSLError as exc:\n raise TransferError(\n f\"Handshake error while loading ${url} \"\n f\"with connection ${connection_id}: ${exc}\",\n url=url\n ) from excOur interface encapsulates the use of SSL as an implementation detail, therefore we cannot\nlet an SSLError propagate.\nWe thus change the error type to one of those that client\ncode can expect from us. We don't forward working details of SSL handshake, but we add\nthe url as a context field, and ensure that, should the error be logged at some point,\nthe log will include the connection id.
We also use python error chaining\nfrom\nclause to ensure discarded details will be available for error investigation.\nThe handling of those discarded parts needs special care because,\neven though it's not relevant up the abstraction stack, they might be useful for debugging.
\n\nA word about functions
\nAs we close this part on levels of abstraction, we should note that at the smallest scope,\neven a single function:
\n\n
\n- encapsulates a task, giving it a name and therefore defining vocabulary.
\n- has preconditions: predicates that must be true at beginning of the function.
\n- has postconditions: predicates that must be true at the end of the function.
\nIn fact, every function is an abstraction. And the principles we covered so far\napply to functions just as well as they apply to components.
\n
That was longer than I expected. Enough theory, in the next post\nwe will see actual error handling mechanisms in code.
","fields":{"isPage":false,"slug":"/2019/error-handling-levels"},"frontmatter":{"title":"Error Handling part 2: Abstractions","classname":null,"date":"2019-02-28T00:00:00.000Z","formattedDate":"February 28, 2019","isoDate":"2019-02-28T00:00:00+00:00"},"headings":[{"value":"Levels of abstraction","depth":1},{"value":"Until it fails","depth":2},{"value":"Errors are part of abstraction","depth":2},{"value":"Speaking in errors","depth":2},{"value":"A level-by-level process","depth":3},{"value":"Translating errors","depth":3},{"value":"Conclusion","depth":1}],"image":{"original":{"src":"/static/fall-f80554c0d842f42384135cac3c4c5cd2.png"}},"series":{"name":"software","fullName":"software engineering","fields":{"slug":"/software"}},"tags":[{"name":"code","slug":"/tag/code"}]}},"pageContext":{"series":"software","slug":"/2019/error-handling-levels","previous":{"fields":{"slug":"/2019/error-handling-introduction"},"frontmatter":{"title":"Error Handling part 1: Introduction","series":"software"},"tags":[{"name":"code","slug":"/tag/code"}]},"next":{"fields":{"slug":"/2019/zero-cost-unique_ptr"},"frontmatter":{"title":"Zero-cost unique_ptr deleters","series":"software"},"tags":[{"name":"code","slug":"/tag/code"},{"name":"c++","slug":"/tag/c"}]},"seriesPrevious":{"fields":{"slug":"/2019/error-handling-introduction"},"frontmatter":{"title":"Error Handling part 1: Introduction","series":"software"},"tags":[{"name":"code","slug":"/tag/code"}]},"seriesNext":{"fields":{"slug":"/2019/zero-cost-unique_ptr"},"frontmatter":{"title":"Zero-cost unique_ptr deleters","series":"software"},"tags":[{"name":"code","slug":"/tag/code"},{"name":"c++","slug":"/tag/c"}]}}}, "staticQueryHashes": ["1733002695","4006707078"]}