🗑️ teardown

Composable, idempotent & transparent application resource cleanup sub-routines

Table Of Contents

• Raison d'etre
• Development
• Documentation
• License
• Report teardown sub-routine results

Raison d'etre

The correct teardown of a system becomes a crucial matter when running applications through GHCi while doing REPL driven development; this library provides a stable API to manage the cleanup process of resources your application allocates when it starts up.

One could naively implement a teardown sub-routine of an application by doing something like the following:

-- All functions in this example initialize hypothetical resources, the
-- idea stands that there is a way to allocate a system resource
-- using some sort of configuration record, and there is a
-- sub-routine to release those resources once the application
-- shuts down

initDb :: Logger -> DbConnInfo -> IO (DbConn, IO ())
initDb logger connInfo = do
  conn <- newConn connInfo
  return (conn, info logger "Teardown Database" >> closeConn conn)

initTcpServer :: Logger -> ServerInfo -> IO (Socket, IO ())
initTcpServer logger serverInfo = do
  socket <- startServer serverInfo
  return (socket, info logger "Teardown Tcp Server" >> closeSocket socket)

initApp :: Logger -> DbConnInfo -> ServerInfo -> IO (IO ())
initApp logger connInfo serverInfo = do
  (connInfo, teardownDb) <- initDb logger connInfo
  (serverInfo, teardownSocket) <- initTcpServer logger serverInfo
  -- do something with connInfo and serverInfo ...
  return (info logger "Teardown Application"
          >> teardownDb
          >> teardownSocket)

The previous implementation does not address a few concerns:

• If for some reason we execute the @IO ()@ sub-routine returned by the @initApp@ function more than once, there is likely going to be a runtime exception of the "already closed resource" nature. This library ensures that teardown sub-routines are executed /exactly/ once, even on the scenario where we execute the teardown procedure multiple times.

• The teardown of sub-systems can be built and composed via the @(>>)@ operator, what happens if the @teardownDb@ sub-routine in the previous example throws an exception? Likely other resource teardown sub-routines are going to be affected. This library ensures that errors are isolated from every other resource teardown sub-routines.

• All teardown sub-routines use a description argument to keep track of what is being cleaned up; By requiring this, we avoid confusion around what is going on when shutting down an application. This library makes this documentation a /required/ argument when building teardown sub-routines, thus helping trace-ability.

• You may notice the structure of teardown sub-routines form a tree shape. This library provides a data structure representation of this tree that allows the developer to report all teardown sub-routines in hierarchy order, with other details around if sub-routines failed (or not).

• Also, this library keeps track how much time every teardown sub-routine takes, allowing the developer to learn which parts of the teardown procedure are slow and adequately address those on development time (e.g., Faster reload => Faster development feedback loops).

By using this library, you may implement without much effort a good, reliable and transparent strategy for application resource teardown sub-routines.

Documentation

To learn more about the library, please refer to the documentation in Hackage for

• Teardown

• ComponentM [pending]

Development

This library is intended to be minimal, providing a few functions that work reliably among many different kind of projects. If you want to contribute, Pull Request are very welcome! Please try to follow these simple rules:

• Please create a topic branch for every separate change you make.
• Update the README.md file if necessary.
• Please do not change the version number on your Pull Request.

Open Commit Bit

This project has an open commit bit policy: Anyone with an accepted pull request gets added as a repository collaborator. Please try to follow these simple rules:

• Commit directly onto the master branch only for typos, improvements to the README and documentation.
• Create a feature branch and open a pull-request early for any new features to get feedback.
• Make sure you adhere to the general pull request rules above.

License

Copyright (c) 2027, Roman Gonzalez

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.