In typical use, Hakyll programs convert external content files into HTML pages. But what if your content is defined in Haskell source files that are part of the Hakyll program? That can work—but you need a trick or two. In this post I’ll show you how.

The scenario §

For whatever reason, you’ve got some Haskell data structure you want to present somehow. A typical example would be a list or table or tree of data. My use case was a list of objects describing some files, to be presented as a table. A file may or may not be available for download (Maybe FilePath).

module Files where

data File = File
  { fileDate :: String
  , fileName :: Maybe FilePath
  , fileDesc :: String
  }

fileList :: [File]
fileList =
  [ File "2026-01-15" (Just "alice-to-tribunal.pdf")
      "Alice's submissions to the Tribunal"
  , File "2025-12-23" Nothing
      "Bob's submissions to the Tribunal (confidential)"
  , File "2025-12-17" (Just "tribunal-directions.pdf")
      "Orders made at the directions hearing"
  ]

I want Hakyll to generate an HTML page that formats this list as a <table>. Importantly, I also want Hakyll to notice when Files.hs changes and update the output, even when nothing else changed.

Context and template §

We first define how to process a File into a Context File that can be fed to a template.

fileContext :: Context File
fileContext =
  field "filename"
    ( maybe
        (noResult "unavailable")
        (pure . toUrl . ("files/" <>))
    . fileName . itemBody )
  <> field "date" (pure . fileDate . itemBody)
  <> field "desc" (pure . fileDesc . itemBody)

The Hakyll compiler for the HTML page populates a listField with contents of fileList. fileContext generates the context for the individual items.

import Hakyll
import Files

main :: IO ()
main = hakyll $ do

  create ["files.html"] $ do
    route idRoute
    compile $ do
      let filesContext =
            listField "files" fileContext
              (traverse makeItem fileList)

      makeItem ""
        >>= loadAndApplyTemplate
              "templates/files.html" filesContext
        >>= loadAndApplyTemplate
              "templates/default.html" defaultContext
        >>= relativizeUrls

The template content follows:

<table id="files">
    <tr><th colspan="3">Tribunal proceeding files</th></tr>
    $for(files)$
    <tr>
        <td>$date$</td>
        $if(filename)$
        <td><a href="$filename$">download</a></td>
        $else$
        <td><em>N/A</em></td>
        $endif$
        <td>$desc$</td>
    </tr>
    $endfor$
</table>

The noResult in the Nothing case for the fileName field is what makes the $if(filename)$ / $else$ conditional work. Apart from that, the template is trivial.

Recompiling on change §

One more thing. Because the source of the data is not a markdown (or whatever) file, Hakyll won’t automatically notice if the data changed and regenerate the HTML. We have to set up an explicit dependency on the Haskell source file.

Add a match rule for the relevant .hs file, so that Hakyll will monitor it. Also update the compiler for files.html load the Files.hs “item”, to establish the dependency:

main = hakyll $ do

  match "Files.hs" $ do
    compile $ makeItem ()

  create ["files.html"] $ do
    route idRoute
    compile $ do
      _ <- load "Files.hs" :: Compiler (Item ())
      let filesContext =
        …

And that’s all there is to it!

I find type-level naturals useful for enforcing proper usage of APIs or protocols that involve transactions, locking, memory (de)allocation, and similar concerns. In this post I demonstrate the main idea and discuss some of the shortcomings when using this technique with Haskell.

Overview of the technique §

Consider the following API.

-- provides type-level numeric literals
{-# LANGUAGE DataKinds #-}  -- 

-- provides type-level numeric operations
import GHC.TypeLits

data DbHandle n

openDatabase      :: IO (DbHandle 0)
startTransaction  :: DbHandle n -> IO (DbHandle (n + 1))
commitTransaction :: DbHandle n -> IO (DbHandle (n - 1))
closeDatabase     :: DbHandle 0 -> IO ()

The phantom type parameter n in DbHandle n tracks the level of nested transactions. The database is initially opened at level 0 and can only be closed when the level is 0. The API enforces that transactions must be committed. (Error handling and rollback is left as an exercise for the reader.)

Here’s a trivial example of using this API:

main :: IO ()
main = do
  db <- startTransaction =<< openDatabase
  -- do stuff
  commitTransaction db >>= closeDatabase

All happy. But if we fail to commit the transaction…

main = do
  db <- startTransaction =<< openDatabase
  -- do stuff
  closeDatabase db

…then we get a type error:

ExampleX.hs:21:9: error: [GHC-83865]
    • Couldn't match type ‘1’ with ‘0’
      Expected: DbHandle 0 -> IO (DbHandle 0)
        Actual: DbHandle 0 -> IO (DbHandle (0 + 1))
    • In the first argument of ‘(=<<)’, namely ‘startTransaction’
      In a stmt of a 'do' block: db <- startTransaction =<< openDatabase
      In the expression:
        do db <- startTransaction =<< openDatabase
           closeDatabase db
   |
21 |   db <- startTransaction =<< openDatabase
   |         .hs:21:9: error: [GHC-83865]
    • Couldn't match type ‘1’ with ‘0’
      Expected: DbHandle 0 -> IO (DbHandle 0)
        Actual: DbHandle 0 -> IO (DbHandle (0 + 1))
    • In the first argument of ‘(=<<)’, namely ‘startTransaction’
      In a stmt of a 'do' block: db <- startTransaction =<< openDatabase
      In the expression:
        do db <- startTransaction =<< openDatabase
           closeDatabase db
   |
21 |   db <- startTransaction =<< openDatabase
   |

Very well.

Unnatural inhabitants §

Because GHC’s type-level naturals are not a true inductive type, subtraction is allowed even when the result with be less than zero. In this case, the value just appears as an un-normalised (0 - 1). We can see this in the type error when we attempt to compile the following program:

main = do
  db <- openDatabase  -- we didn't start a transaction
  -- do stuff
  commitTransaction db >>= closeDatabase

X.hs:23:3: error: [GHC-83865]
    • Couldn't match type ‘0 - 1’ with ‘0’
      Expected: IO (DbHandle 0)
        Actual: IO (DbHandle (0 - 1))

Unfortunately, the compiler could accept a program that commits a transaction when no transaction is in progress. The following program compiles without error:

main = do
  db <- openDatabase
  -- do stuff
  commitTransaction db  -- we didn't start a transaction
  pure ()               -- we didn't close the database

Constraints to the rescue §

We can add a constraint to commitTransaction to ensure that it can only be applied to handles that are in a (possibly nested) transaction:

commitTransaction
  :: (1 <= n)
  => DbHandle n -> IO (DbHandle (n - 1))

Compiling the previous program now results in an error:

X.hs:25:3: error: [GHC-64725]
    • Cannot satisfy: 1 <= 0
    • In a stmt of a 'do' block: commitTransaction db
      In the expression:
        do db <- openDatabase
           commitTransaction db
           pure ()

And the original (correct) program continues still compiles. But now it emits a redundant constraint warning:

X.hs:15:6: warning: [GHC-30606] [-Wredundant-constraints]
    Redundant constraint: 1 <= n
    In the type signature for:
         commitTransaction :: forall (n :: Natural).
                              (1 <= n) =>
                              DbHandle n -> IO (DbHandle (n - 1))
   |
15 |   :: (1 <= n)

This is a bit annoying. I don’t know how to dispel this error except to disable -Wredundant-constraints, and I don’t want to do that. But in the end, these few spurious warnings are a small price to pay for a safer API that prevents incorrect use at compile time.

Ergonomics §

User code typically use locks, transactions or allocation in a symmetric way. In other words, they initialise a context, perform some actions, then tidy up. It makes sense to wrap this pattern up in a function that handles the bookkeeping:

withTransaction
  :: DbHandle (n :: Natural)
  -> (forall m. DbHandle (m :: Natural) -> IO a)
  -> IO a
withTransaction db k = do
  db' <- startTransaction db
  r <- k db
  commitTransaction db'
  pure r

The forall m. (universal quantification) prevents improper use of the database handle (e.g. premature commit) by requiring the action function to work with database handles with any transaction level (including 0).

Unfortunately this code does not compile:

X.hs:28:3: error: [GHC-64725]
    • Cannot satisfy: 1 <= n + 1
    • In a stmt of a 'do' block: commitTransaction db'
      In the expression:
        do db' <- startTransaction db
           r <- k db
           commitTransaction db'
           pure r

The proposition to be satisfied is obviously true. But again the lack of inductive reasoning in GHC’s type-level naturals bites us. Sprinkling this constraint into the type signature solves the problem (and also lets us avoid the explicit kind signatures):

withTransaction
  :: (1 <= n + 1)
  => DbHandle n
  -> (forall m. (1 <= m + 1) => DbHandle m -> IO a)
  -> IO a

Now we can write a program that uses transactions like so:

main = do
  db <- openDatabase
  withTransaction db (const $ pure ())
  closeDatabase db

Nested transactions also work:

main = do
  db <- openDatabase
  withTransaction db
    ( \db' -> withTransaction db' (const $ pure ()) )
  closeDatabase db

But operations that rely on knowing the transaction level—like committing—are excluded. This program:

main = do
  db <- openDatabase
  withTransaction db (\db' -> commitTransaction db')
  closeDatabase db

…results in a type error:

X.hs:38:31: error: [GHC-64725]
    • Cannot satisfy: 1 <= m
    • In the expression: commitTransaction db'
      In the second argument of ‘withTransaction’, namely
        ‘(\ db' -> commitTransaction db')’
      In a stmt of a 'do' block:
        withTransaction db (\ db' -> commitTransaction db')
   |
38 |   withTransaction db (\db' -> commitTransaction db')
   |                               ^^^^^^^^^^^^^^^^^

Which is exactly what we want.

Conclusion §

I have demonstrated a technique that enables safer APIs for resource-related operations such as locking/unlocking, transactions, and memory management. Some type-level boilerplate is needed to work around shortcomings in Haskell’s type-level naturals.

We also discussed an idea to make the the API more ergonomic by providing a “wrapper” function that handles the initialisation and cleanup. You would need additional functionality to safely handle special operations that should be callable by user code, such as rollbacks. One idea is to use a sum type that allows user code to request special operations. For example:

data TransactionResult a = Rollback | Commit a

withTransaction
  :: (1 <= n + 1)
  => DbHandle n
  -> (forall m. (1 <= m + 1) => DbHandle m -> TransactionResult a)
  -> IO (TransactionResult a)
withTransaction db k = do
  db' <- startTransaction db
  r <- k db
  case r of
    Rollback -> rollback db' $> r
    Commit _ -> pure r

This is just a sketch of the idea (I haven’t tried it myself yet). I encourage interested readers to explore further and share their results.

Like most people, I don’t like big financial surprises or sudden, substantial changes to cashflow. Although we can’t control all circumstances, we can plan for projected future expenses, like your kids’ education. In this post I share a basic model built in Haskell to help plan for education expenses (or other large, future, time-bounded expenses).

This beginner-friendly post demonstrates many simple Haskell functions, especially for working with lists. It also shows how to build and execute stateful computations using State from mtl. I (mostly) avoid type signatures and just focus on defining the terms, but there are plenty of links to API documentation. At the end of the post I suggest some enhancements to the model that would be good exercises for learners (and might be fun even for more experienced Haskell programmers).

Scenario and simplifying assumptions §

The general scenario I built the model for is to save for private secondary school fees for two children. They are 3 years apart with the older child commencing in 4 years. Costs of primary (elementary) schooling are not considered in this scenario, although the model would accommodate that.

Given the time span (> 10 years) we have to consider inflation. The model uses a constant rate of inflation of 5% per annum, which is less than the rate of inflation in Australia at time of writing, but more than the our RBA’s long term target of 2–3%.

We also model an annual investment return of 8%. Short-term volatility is inevitable but this is less than the long-term average for the Australian stock market.

Contributions to the fund will be annual. In real life, for stable cashflow and to achieve dollar cost averaging, contributions could be made more regularly (e.g. each pay day). The model is therefore slightly pessimistic in this regard, but simpler to implement.

General description of the model §

The inputs to the model are a fee structure, and an annual contribution amount which is fixed (does not grow with inflation or income).

The model projects the costs of education in future years, and works backwards to determine how much money needs to be in the fund at the start of each year. The output of the model is a list of these required balances, the first of which is the required initial starting balance for the education fund. If the starting balance is too high, increase the yearly contribution and evaluate the model again. Continue until you find a balance between starting value and contribution amount that works for you.

Modelling the costs §

A school’s current fee structure, for the six years of secondary education, is the ordered list of these numbers:

feesBase =
  [ 12000, 12000, 12000     -- grade  7,  8,  9
  , 13500, 13500, 13500 ]   -- grade 10, 11, 12

Child 1 will be starting high school in 4 years; Child 2 in 7 years. We consider the intervening years to have nil cost, which we represent by using replicate to make lists of 0 of the required lengths. We append these sublists using <>. We also extend the shorter list with additional zeroes (only the shorter list, because repeat makes an infinite list).

feesChild1Base =
  replicate 4 0 <> feesBase <> repeat 0

feesChild2Base =
  replicate 7 0 <> feesBase

We could add the yearly fees using zipWith, whose arguments are a binary combining function and two lists:

feesCombinedBase =
  zipWith (+) feesChild1Base feesChild2Base

However, many schools offer discounts when you have multiple children enrolled. In this scenario, the school gives a 10% discount for the younger (cheaper) child, when both are enrolled. We define the combining function using min, max, addition and multiplication:

-- define our custom combining function...
sumWithDiscount a b =
  max a b + min a b * 0.9

-- ... and update feesCombinedBase to use it
feesCombinedBase =
  zipWith sumWithDiscount feesChild1Base feesChild2Base

Let’s evaluate feesCombinedBase and print the values. traverse_ applies an action to each element of a list (or other container), then discards the result.

λ> traverse_ print feesCombinedBase
0.0
0.0
0.0
0.0
12000.0
12000.0
12000.0
24300.0
24300.0
24300.0
13500.0
13500.0
13500.0

Now inflation must have its way with these numbers. Use iterate to generate the inflation factor for successive years (ad infinitum) by iteratively apply our inflation rate, starting at 1. To make the numbers presentable we’ll also round to 4 decimal places.

round4    = (/ 10000) . fromIntegral . round . (* 10000)
inflation = fmap round4 (iterate (* 1.05) 1)

Then we can apply the inflation to our uninflated costs, year by year. One thing I did not yet mention is that the fees above are nearly a year old and will be going up soon, so we’ll use drop to “shift left” the inflation figures by one year. Once more we use zipWith for a very neat expression:

feesCombinedInflated =
  zipWith (*) feesCombinedBase (drop 1 inflation)

Let’s print the projected fees:

λ> traverse_ print feesCombinedInflated
0.0
0.0
0.0
0.0
15315.6
16081.2
16885.2
35903.25
37696.59
39582.27
23089.05
24244.65
25455.6

This looks right. The highest costs are in the three “overlap” years where both children are enrolled, and the impact of inflation is evident.

Modelling the fund balance §

A stateful computation will work out how much money we need in the fund at the start of each year. Specifically, we use the State type from the mtl library to define the computation.

The model takes into account the contribution amount and the growth factor. To do this it has to work backwards in time. Each step of the computation takes the schooling fee for that year, and the state value tracks the required balance of the fund.

We define the step function, which considers what happens to the fund over one year. It must first subtract the contribution from the required balance. This excludes the contribution from the (presumed) growth over the year; a simplifying assumption that is reasonable over the long-term. We also ensure the balance will not be negative. We intend to exhaust the fund when fees are paid in the final year, and a negative balance will spoil the subsequent calculations. The modify function applies its argument (the subtraction) to modify the state value.

step contrib fee = do
  modify (max 0 . subtract contrib)

Next we divide the balance (state value) by the growth rate, to obtain a nominal value of the fund at the start of the year:

  modify (/ 1.08)

Finally, we have to pay the fees at (or near) the start of the year. So we must increase the required balance by that amount. Some schools offer a discount for full year payment up-front. This model applies a discount of 5%, but this is another area where the model could be parameterised.

  modify (+ (fee * 0.95))

All together the step function contains a few simple operations. At the end it returns the state value via the get function. This will enable us to see how the value of the fund changes year by year.

step contrib fee = do
  modify (max 0 . subtract contrib)
  modify (/ 1.08)
  modify (+ (fee * 0.95))
  get

Now that we have the step function, we can traverse the list of year costs and apply the step to each element. Like traverse_, traverse applies an action to each element of a container, but instead of discarding the results it replaces each element of the container with the “return value” of the action.

We have to start at the final year and work backwards, so first reverse the list, then traverse it:

go :: Double -> State Double [Double]
go contrib =
  traverse (step contrib) (reverse feesCombinedInflated)

This is the first time I have shown a type signature in this whole post! The go function takes the contribution amount and returns a state computation whose state variable (the required balance) is a real number (Double) and whose output is a list of numbers (the required balance at the start of each year).

To actually run the state computation we use evalState, whose arguments are the state computation and an initial state. Our initial state is $0, because we intend to exhaust the fund when we pay for the final year of schooling.

model contrib = fmap round (reverse (evalState go 0))

The result of model is a list of the required fund balance at the start of each year, in order. The first value is the initial balance required for the given yearly contribution amount.

Running the model §

Let’s see what the model tells us for various contribution amounts. First, let’s just pick a number, say $10,000.

λ> traverse_ print (model 10000)
43542
57025
71587
87314
104299
106929
108984
110379
92373
71086
46161
36165
24183

The final year’s value is 24183. That will always be the final value, regardless of contribution amount, because that is what the final fee payment will be.

As for the required starting value, for a $10,000 yearly contribution we would need to start the fund with $43,542. But what if you don’t have any money to start the fund? With a bit of trial and error I found that a yearly contribution of $15,778 is enough (note the start value for the second year):

λ> traverse_ print (model 15778)
0
15776
32816
51220
71095
76847
82273
87309
73235
56195
35857
30815
24183

Finally, how much would you need if you wanted the fund to be completely passive—no further contributions after the initial amount?

λ> traverse_ print (model 0)
118903
128415
138688
149783
161766
158993
155213
150306
125494
96857
63994
45424
24183

$118,903. Not many people have that kind of money at their immediate disposal. But if you do, or if you get a big windfall, you could “set and forget” an investment for your children’s schooling, or other long-term financial objective.

Possible model enhancements or variations §

There are several ways the model could be improved, or tweaked to suit the circumstances or preferences of the investor.

You could consider increasing the contribution over time to adjust for expected income growth. There are a several ways to do it. One way is to pass the inflation factor to the step function and apply it to the base contribution amount there. Another way is to precompute the annual inflated contribution, zip it with the inflated fee list, and traverse the step function over the (contribution, fee) pairs. I leave it to the reader to play around, if interested.

Another obvious area for improvement is that the model is hardcoded for exactly two children. Enhancing it to handle different numbers of children would be a good exercise. zipWith will no longer cut it for combining fees. Furthermore, schools can have diverse discount structures for multiple children (e.g. second child 10% off, 25% for third child, and so on). So the discount structure should be parameterised. If you want to improve your skill working with lists in Haskell, this would be a good exercise.

Other areas for improvement include dollar-cost averaging the yearly contribution amount, or step functions for different payment frequencies (e.g. quarterly / per term). Both of these tasks would be good practice with State computations.

In this article I show how to extend the haskell-ci GitHub Actions workflow to pass the built executable to subsequent jobs.

Background §

The Haskell Security Response Team recently bootstrapped the haskell/security-advisories database. This repository contains:

• The security advisories themselves. These are freeform Markdown files with a TOML header. The header contains various required or optional fields encoding information about the security issue, the package it affects, and the affected package versions.
• Tools for maintaining the database and exporting the data in various formats. The hsec-tools Cabal package contains a library that defines the advisory data format and parsers, and the hsec-tools executable which is a CLI front-end for processing advisories.

With both tool sources and advisory data in the repository our continuous integration (CI) pipelines have to do several things:

• Build and test the tools. We want to test against several recent GHC versions (to avoid inconvenience for contributors). We also perform a Nix build.
• Check the validity of the advisory data. Advisories have to conform to our schema. We can use hsec-tools to check each advisory file. We should use the version of hsec-tools from the same commit, to allow the advisory format and tooling to evolve in lockstep.
• Publish advisories. We will likely want to set up automation to publish OSV streams, a web site, and other relevant artifacts.

The remainder of this post explains how we use haskell-ci and GitHub Actions reusable workflows to achieve the first two objectives. The Security Response Team has not yet tackled publishing but the same techniques should be applicable.

Introduction to haskell-ci §

haskell-ci is a tool that generates CI workflows for Haskell projects. It supports GitHub Actions (actively maintained) and Travis-CI (unmaintained), and can also generate shell scripts for local testing. You can install haskell-ci via cabal:

% cabal install haskell-ci

Alternatively, you can clone the Git repository and build from there:

% git clone https://github.com/haskell-CI/haskell-ci
% cd haskell-ci
% cabal install

Now that haskell-ci is on the PATH you can generate the GitHub actions workflow in a couple of steps. First, add the GHC versions you want to test with to the tested-with field in your package’s .cabal file:

cabal-version:      2.4
name:               hsec-tools
version:            0.1.0.0
tested-with:
  GHC ==8.10.7 || ==9.0.2 || ==9.2.7 || ==9.4.5 || ==9.6.2
…

Next run haskell-ci github path/to/package.cabal. It will inspect the .cabal file to see what GHC versions to include in the build matrix, and write .github/workflows/haskell-ci.yml. Then commit the changes and push (or create a pull request). For example:

% haskell-ci github code/hsec-tools/hsec-tools.cabal
*INFO* Generating GitHub config for testing for GHC versions: 8.10.7 9.0.2 9.2.7 9.4.5 9.6.2
% git add code .github
% git commit -m 'ci: add haskell-ci workflow' --quiet
% git push
…

What does the haskell-ci workflow do? §

This post is not the place to belabour the details of GitHub Actions workflow syntax. But I will make a few observations about the steps in the haskell-ci workflow.

• The build runs on Ubuntu (version 20.04 at time of writing). You can tell haskell-ci to install extra APT packages via option --apt "space separated list". For example, if your package uses the FFI to bind to a C library, use this option to install that library and its development headers.
• There is a job matrix with a different job for each of the GHC versions mentioned in the tested-with field.
• Each job downloads GHC via GHCUp, a popular, multi-platform installation tool for Haskell.
• The package under test is not built in situ. Instead, a source distribution is built using cabal sdist. It is then unpacked in a different location, and built and tested there. This helps detect packaging errors (e.g. missing extra source or data files).
• The job caches build tools and Haskell dependencies using the GitHub Actions cache mechanism (discussed later in the post). This saves time on subsequent test runs.
• There is a step that runs cabal check, which checks for issues that Hackage may complain about if you try to publish your package there. This could be a mild annoyance for private or toy projects.

Building documentation §

haskell-ci makes it easy to build package documentation during your CI jobs. All you need to do is use the --haddock option when creating the workflow, and it will add a step that runs the Haddock tool.

% haskell-ci github --haddock path/to/package.cabal

The Haddock step (if enabled) runs on every job in the build matrix. Haddock is part of the GHC toolchain so there are no extra dependencies.

Updating the build matrix §

When a new release of GHC comes along, updating the haskell-ci workflow is as simple as adding it to the tested-with list, then running:

% haskell-ci regenerate
No haskell-ci.sh, skipping bash regeneration
*INFO* Generating GitHub config for testing for GHC versions: 8.10.7 9.0.2 9.2.7 9.4.5 9.6.2
No .travis.yml, skipping travis regeneration

haskell-ci regenerate reuses the options from the original invocation of haskell-ci github. These were recorded in a comment starting with # REGENDATA in haskell-ci.yml. After running haskell-ci regenerate, all that’s left is to commit and push the changes.

GitHub Actions: passing the executable between jobs §

Now the haskell-ci job is set up it will build and test the package on every push or pull request. We have a further CI use case: using the built executable to perform additional action. So we now turn to the problem of how to use data produced by the haskell-ci workflow in other jobs.

GitHub Actions provides (at least) 3 mechanisms for passing data between jobs.

• Jobs can define outputs. They must be unicode strings and the size limit is 50MB. Both limitations make this mechanism unsuitable for passing the built executable to dependent jobs.
• Jobs can cache dependencies to speed up the build. But we want to cache the result of the build, which will often be different from previous build. It seems to me that we could use the caching mechanism, but it doesn’t feel like a good fit.
• Jobs can upload build artifacts. This makes them available to subsequent jobs in the workflow. Unlike caches, they can also be downloaded by anyone with access to the repository. This is the appropriate mechanism for our use case.

We need to add two steps to the linux job. First we install the hsec-tools executable. It was already built—this just copies it to a known location. --install-method=copy ensures the executable is copied to that location, not symlinked.

      - name: install executable
        if: matrix.compiler == 'ghc-9.6.2'
        run: |
          $CABAL v2-install $ARG_COMPILER \
            --install-method=copy exe:hsec-tools

The second step uses the upload-artifact action to archive the executable. The artifact bundle name includes the commit hash. The file within the bundle keeps the name hsec-tools.

      - name: upload executable
        uses: actions/upload-artifact@v3
        if: matrix.compiler == 'ghc-9.6.2'
        with:
          name: hsec-tools-${{ github.sha }}
          path: ~/.cabal/bin/hsec-tools

Notice that each of the new steps has the condition:

        if: matrix.compiler == 'ghc-9.6.2'

The build matrix produces jobs for several different GHC versions. But we only need one copy of the hsec-tools executable. I’m not totally happy with this approach because the patch will need updating as the matrix evolves. But I can live with it for now.

GitHub Actions: workflows and jobs §

A repository can define one or more CI workflows. They are written as YAML files in the .github/workflows/ directory.

Each workflow is comprised of one or more jobs. It is straightforward to declare dependencies between jobs within a workflow. But workflows themselves are independent. There is no reasonable way to specify that a particular workflow depends on the result or outputs of another workflow.

This means that for our use case we have to create a new job within the Haskell-CI workflow. Because haskell-ci.yml is generated by the haskell-ci tool we have to patch this file. Fortunately haskell-ci provides a mechanism to apply specified patches when generating haskell-ci.yml (shown later in this article). Unfortunately, defining and maintaining our additional job(s) as patches to YAML files is even more unpleasant than dealing with them as plain YAML.

GitHub Actions: reusable workflows §

Reusable workflows provide a neat solution. A reusable workflow is defined as a separate YAML file, just like ordinary workflows. The main differences are:

• Reusable workflows use the trigger condition workflow_call, instead of the usual triggers like push or pull_request.
• Reusable workflows can be parameterised by inputs. The calling job provides the values. An input can be required or optional.

The main goal of reusable workflows is to enable reuse, like subroutines in programming. Our use case is a bit different. We will define the check-advisories behaviour as a reusable workflow. Although we will not be using it from multiple places, it still gives us several advantages:

• Separation of concerns: checking the advisories uses an artifact from the haskell-ci build/test job, but it’s a distinct task.
• Maintainability: the behaviour is specified in an ordinary workflow YAML file. We do not need to edit patch files to modify the workflow.
• We minimise the size and complexity of the patch to be applied to haskell-ci.yml. The patch itself should rarely change, even if the reusable workflow definition changes.

Defining the check-advisories workflow §

The check-advisories workflow is defined in .github/workflows/check-advisories.yml. The full content is below, with commentary.

name: Check security advisories
on:
  workflow_call:
    inputs:
      artifact-name:
        required: true
        type: string

The workflow_call trigger condition establishes it as a reusable workflow. We also define the artifact-name input. The caller is required to provide it.

jobs:
  check-advisories:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v3
        with:
          path: source

The workflow has a single job called check-advisories. As usual the first step is to check out the repository.

      - run: mkdir -p .local/bin
      - id: download
        uses: actions/download-artifact@v3
        with:
          name: ${{ inputs.artifact-name }}
          path: ~/.local/bin
      - run: chmod +x ~/.local/bin/hsec-tools

Next we download the hsec-tools artifact to ~/.local/bin, which is in the PATH. Then we chmod it to make it executable.

      - name: run checks
        run: |
          cd source
          RESULT=0
          while read FILE ; do
            echo -n "$FILE: "
            hsec-tools check < "$FILE" || RESULT=1
          done < <(find advisories EXAMPLE_ADVISORY.md -name "*.md")
          exit $RESULT

Finally we find all the advisory files and run hsec-tools check on each one. If any of the checks fail the whole job fails (after checking each file—we don’t want to short-circuit).

Calling the check-advisories workflow §

Add a new job to the haskell-ci.yml workflow. It must be a separate job, not a step of the existing linux job.

  check-advisories:
    name: Invoke check-advisories workflow
    needs: linux
    uses: ./.github/workflows/check-advisories.yml
    with:
      artifact-name: hsec-tools-${{ github.sha }}

The meaning of the fields is as follows:

• uses: calls the check-advisories.yml workflow.
• with: specifies values for the inputs, which in our case is the artifact-name.
• needs: expresses the dependency on the linux job.

uses: user-or-org/repo/.github/workflows/workflow.yml@v1

Patching haskell-ci.yml §

At this stage I have committed the check-advisories.yml reusable workflow. I also have uncommitted changes to haskell-ci.yml:

diff --git a/.github/workflows/haskell-ci.yml b/.github/workflows/haskell-ci.yml
index d51bb64..7ff8684 100644
--- a/.github/workflows/haskell-ci.yml
+++ b/.github/workflows/haskell-ci.yml
@@ -224,3 +224,19 @@ jobs:
         with:
           key: ${{ runner.os }}-${{ matrix.compiler }}-${{ github.sha }}
           path: ~/.cabal/store
+      - name: install executable
+        if: matrix.compiler == 'ghc-9.6.2'
+        run: |
+          $CABAL v2-install $ARG_COMPILER \
+            --install-method=copy exe:hsec-tools
+      - name: upload executable
+        uses: actions/upload-artifact@v3
+        if: matrix.compiler == 'ghc-9.6.2'
+        with:
+          name: hsec-tools-${{ github.sha }}
+          path: ~/.cabal/bin/hsec-tools
+  check-advisories:
+    name: Invoke check-advisories workflow
+    needs: linux
+    uses: ./.github/workflows/check-advisories.yml
+    with:
+      artifact-name: hsec-tools-${{ github.sha }}

We could commit these changes as is, but they will be lost the next time we run haskell-ci regenerate. Instead create a patch file:

% git diff > .github/haskell-ci.patch

Then tell haskell-ci to apply the patch when (re)generating haskell-ci.yml. What I would like to do is run:

% haskell-ci regenerate \
    --github-patches .github/haskell-ci.patch

The above command regenerates the haskell-ci.yml and correctly applies our patch. But it does not add the new arguments to the REGENDATA line. As a consequence, subsequent executions of haskell-ci regenerate will not apply the patch unless you use the --github-patches option every time. This is not what we want, and possibly a bug (I will investigate further, but not today).

The workaround: manually edit haskell-ci.yml, inserting "--github-patches",".github/haskell-ci.patch" in the REGENDATA line. As a result of that change, running haskell-ci regenerate without extra arguments applies the patch.

The final step is to commit the patch file together with the updated haskell-ci.yml.

Final words §

In this article I showed how to use haskell-ci to generate a GitHub Actions workflow for testing Haskell projects. I also demonstrated how to extend the haskell-ci workflow to save a built executable as an artifact, which can then be used by other CI jobs.

I hope it has been a useful article, both for people starting out and wondering how to test their Haskell projects, as well as for projects with more advanced CI workflows.

One area I would like to investigate further is how to skip the haskell-ci workflow when the tool code did not change. For example, if someone submits a pull request that adds or updates an advisory but does touch the hsec-tools code. Artifacts and cache entries have a name or key. Right now we use the Git commit hash in the artifact name. Perhaps we could use the Git tree hash of the code/hsec-tools directory instead:

% git rev-parse HEAD:code/hsec-tools 
a08aa5a2ee93ed09ec0025809226571969e24e3d

Uploading the artifact with a name based on the tree hash seems straightforward. The bigger challenge is how to skip the linux jobs when the artifact for the current hsec-tools tree already exists. And how to not skip the check-advisories job, even though it depends on the linux jobs. I think it’s probably possible. But it’s a nice-to-have; this yak’s haircut will have to wait for another day.

The Haskell Foreign Function Interface (FFI) lets you interface with code written in other languages, including C. Some kinds of foreign calls—such as those that could call back into Haskell code—require the GHC runtime system (RTS) to do some bookkeeping. This bookkeeping has a performance cost, so there is a mechanism to out of it for foreign calls that can’t call back into Haskell. This mechanism is called the safety level. There are two levels:

• safe: do the bookkeeping; callbacks are safe
• unsafe: skip the bookkeeping; callbacks have undefined behaviour

But beware! Besides callback safety, there are other situations that require a safe foreign call. And some that may require an unsafe call (not just for performance). In this post I explain the garbage collection behaviour of safe and unsafe foreign calls, and describe how the wrong choice led to a nasty deadlock bug in hs-notmuch.

Foreign imports §

Chapter 8 of the Haskell 2010 Language Report specifies the foreign function interface syntax and semantics. A foreign import declaration creates a Haskell binding to a foreign function or value:

foreign import ccall unsafe "notmuch.h notmuch_database_open"
  notmuch_database_open
    :: CString
    -> CInt
    -> Ptr (Ptr DatabaseHandle)
    -> IO CInt

You can see that the foreign import declaration contains:

• the safety declaration (unsafe)
• a reference to the C header and symbol to be imported
• a name for the function on the Haskell side
• a type annotation, which corresponds to the C type signature

If you need a safe foreign call, write safe or just omit the safety declaration (safe is the default).

Finalizers §

Haskell is a garbage collected language. It is possible to use the garbage collector to clean up objects that were allocated in foreign calls, when they are no longer referenced. The clean up functions are called finalizers. Often, finalizers are themselves imported from the foreign library:

foreign import ccall "notmuch.h &notmuch_database_destroy"
  notmuch_database_destroy :: FinalizerPtr DatabaseHandle

The ampersand (&) denotes that we are importing a function pointer rather than the function itself.

FinalizerPtr is a type synonym defined in the Foreign.ForeignPtr module:

type FinalizerPtr a = FunPtr (Ptr a -> IO ())

This arises from the usual definition of a destructor or free function. That is, a void function whose single argument is the pointer to the object to be destroyed, or memory to be freed.

Programs need to associate finalizers with the objects they are to clean up. The function to do this is newForeignPtr:

newForeignPtr
  :: FinalizerPtr a -> Ptr a -> IO (ForeignPtr a)

FFI safety and garbage collection §

Consider the wording of the Haskell 2010 FFI chapter:

A safe call … guarantees to leave the Haskell system in a state that allows callbacks from the external code. In contrast, an unsafe call, while carrying less overhead, must not trigger a callback into the Haskell system. If it does, the system behaviour is undefined. … Note that a callback into the Haskell system implies that a garbage collection might be triggered after an external entity was called, but before this call returns.

This says that garbage collection can occur during a safe call. But it does not say whether GC is allowed, or not, during an unsafe call. It is up to implementations to decide what to do.

GHC’s behaviour here has changed over time. Since version 8.4, GHC guarantees that garbage collection will never occur during an unsafe FFI call. This guarantee allows unsafe FFI calls to work with heap-allocated data, which enables some performance optimisations.

Crouching GC, hidden deadlock §

We have discussed the FFI, finalizers, foreign call (un)safety and garbage collection. What’s it all coming to?

The earlier foreign import examples are from hs-notmuch, my Haskell binding to the notmuch mail indexer. Note the following:

• notmuch_database_open is an unsafe foreign call (because it doesn’t call back into Haskell and I don’t want the bookkeeping overhead).

• notmuch_database_destroy is a finalizer that closes the database and frees resources. The garbage collector schedules the finalizer when the database handle is no longer in use.

• Wrapper code in hs-notmuch uses newForeignPtr to associate the the notmuch_database_destroy finalizer with the pointers created by notmuch_database_open.

• The finalizer (called after GC) is the only way to close a database handle. The hs-notmuch API does not offer an explicit close function.

An application could attempt to open a database multiple times. This might be intentional. Or it could occur when there is an unreferenced database handle whose finalizer has not yet been executed.

libnotmuch uses locks to prevent multiple read-write sessions to a single database. notmuch_database_open blocks if the lock is already held. In the case of accidental multiple open this isn’t a problem because GC will eventually occur, finalizers will run and the lock will be released.

Except it won’t, because GHC prevents garbage collection during unsafe foreign calls. As a result, the program deadlocks. Non-deterministically.

This bug went unnoticed for a long time. It was eventually detected by purebred’s automated user acceptance tests, which perform many user actions very quickly. (purebred is a mail program that uses hs-notmuch). Whether deadlock is likely to occur depends very much on the application and/or user behaviour.

Fortunately, the fix was simple: make notmuch_database_open a safe foreign call. Opening the database would typically be an infrequent operation so the bookkeeping overhead is tolerable.

Conclusion §

This post discussed the FFI, finalizers, and GHC’s garbage collection behaviour (or lack thereof) during safe and unsafe foreign calls. I used a deadlock bug in a foreign binding library as a case study of this behaviour.

The folk wisdom regarding safe versus unsafe foreign calls mainly deals with callbacks and performance overheads. I have rarely seen the garbage collection mentioned. This is unfortunate because the GC behaviour is critical to program safety and correctness (as the case study proves). Resources (wiki pages, blog posts, etc) that discuss FFI call safety but fail to mention the GC behaviour of safe versus unsafe should be updated.

With these things in mind, here are my recommendations for Haskell programmers working with the FFI:

• If a foreign function could call back into Haskell code, it must be safe.

• If a foreign call might block, it probably needs to be safe (unless you are certain about what you are doing).

• If you are unsure about whether a foreign call could block (or why), make it safe.

In fact, it’s fine to make every foreign import safe unless:

• You need to guarantee that heap-allocated objects (e.g. unpinned ByteArray#) will not move during the foreign call, or

• The bookkeeping overhead is a real performance issue (e.g. C-style _valid()/_get()/_next() iterators, calls in tight loops).

Doing so might deliver you from debugging a non-deterministic deadlock.

In this post I explain how to write functional tests for GHC, with examples.

Overview of the GHC test suite §

The Glasgow Haskell Compiler (GHC) is a huge project. It includes:

• a Haskell compiler (parser, simplifier, codegen, etc)
• the runtime system (GC, thread scheduler, STM, etc)
• GHCi (interactive interpreter / REPL)
• bundled libraries (base, template-haskell, ghc-prim, etc)
• build tooling (Makefiles, Hadrian)
• the users guide
• a test suite

The test suite should test all the functional parts of GHC. There are different kinds of tests:

• Testing the compiler. The test suite includes Haskell program sources. A test can assert that the program compiles, or that compilation failure is expected.
• Testing the resulting programs. Does the behaviour of a program match expectations?
• Testing the bundled libraries. This is conceptually distinct from the preceding point. In practice it can be achieved in the same way.
• Performance tests ensure that the performance of the compiler, and of compiled programs, does not regress. This is a complex topic and I won’t discuss it further in this post. The GHC wiki has a good introduction.

The GHC GitLab instances runs a continuous integration (CI) pipeline for all merge requests. It builds GHC and runs the test suite on a variety of target architectures and operating systems. Here’s an example for one of my merge requests.

The test suite driver is implemented in Python. Tests are described in terms of its library interface. I won’t discuss the implementation of the test driver—I just want to show you how to use it.

Writing tests §

In the GHC source repository, tests are organised heirarchically under testsuite/tests/. Bundled libraries can also supply tests. For example, some tests for base sit under libraries/base/tests/. .T files describe the tests, using the Python DSL. Usually the name all.T is used. The source code for each test lives alongside the .T file.

The test driver DSL §

Each test is described in a .T file by an invocation of the test function:

test(<name>, <setup>, <test-fn>, <args>)

• <name> is the name of the test source file (without file extension), or the directory containing the source code (for multi-module builds). Often, the name is based on an issue number.
• <setup> is a function or list of functions that affect when or how to run the test program. For example, you can set extra program arguments, declare the expected exit status, or supply a predicate for skipping the test. The GHC wiki gives a full list with descriptions.
• <test-fn> specifies how to compile the test program, and whether to run the resulting program. Common values include compile, compile_fail (compilation failure expected) and compile_and_run (run the resulting program). There are several other options such as for multi-module builds, and GHCi sessions.
• <args> specifies extra arguments for GHC when compiling the test program. It also has other use patterns depending on the value of <test-fn>.

Alongside the source file (<name>.hs) are optional files for specifying the input and output of the test program:

• <name>.stdin: data to feed on standard input
• <name>.stdout: data expected on standard output
• <name>.stderr: data expected on standard error from the test program (for compile-only tests, from GHC).

Example §

Test T20757 is a regression test for issue #20757. The test program source code lives in testsuite/tests/ghc-api/T20757.hs:

module Main where

import GHC.SysTools.BaseDir

main :: IO ()
main = findToolDir False "/" >>= print

The test driver file testsuite/tests/ghc-api/all.T declares the test (alongside several others):

test('T20757',
     [unless(opsys('mingw32'), skip), exit_code(1)],
     compile_and_run,
     ['-package ghc'])

This declaration:

• tells the test driver to both compile and run the test program
• skips the test on operating systems other than Windows
• sets the expected exit status to 1
• adds -package ghc to the compiler CLI options

Additionally, testsuite/tests/ghc-api/T20757.stderr exists. The test driver shall assert that whatever the test program writes to standard error matches the contents of that file.

Running tests §

I use Hadrian to build and test GHC:

% ./hadrian/build -j test

The -j[N] option sets the number of jobs that can be run in parallel. If the integer argument is not specified, it defaults to the number of CPU cores.

There are around 9000 tests in the GHC test suite. It takes a while to run them all (~15 minutes with 12 parallel jobs on my 12-core workstation). If you’re hacking on GHC you might want to limit the driver to one or just a few tests. Use the --only option to do this:

% ./hadrian/build -j test --only=T20757
...
SUMMARY for test run started at Wed May 18 22:58:26 2022 
0:00:00.162930 spent to go through
       1 total tests, which gave rise to
       9 test cases, of which
       9 were skipped
       0 had missing libraries

       0 expected passes
       0 expected failures

       0 caused framework failures
       0 caused framework warnings
       0 unexpected passes
       0 unexpected failures
       0 unexpected stat failures
       0 fragile tests

Build completed in 1.30s

The driver ran zero tests. Well, I am using FreeBSD; T20757 skips on all platforms except Windows. Let’s add one more test. You can specify multiple tests via --only, separated by spaces:

% ./hadrian/build -j test --only="T20757 executablePath"
...
SUMMARY for test run started at Wed May 18 23:02:33 2022
0:00:00.513652 spent to go through
       2 total tests, which gave rise to
      18 test cases, of which
      17 were skipped
       0 had missing libraries

       1 expected passes
       0 expected failures

       0 caused framework failures
       0 caused framework warnings
       0 unexpected passes
       0 unexpected failures
       0 unexpected stat failures
       0 fragile tests

Build completed in 11.82s

That’s more like it.

Each test seems to inflate to 9 test cases. I think these correspond to the different compiler ways, and the test is only run for the configured way(s).

Use --test-verbose=[1,2,3,4,5] to see more verbose output. The commands and output for compiling and running the test program appear at level 3 and above.

See the GHC wiki for further details about running tests.

Testing executablePath §

In my previous post I described System.Environment.executablePath, an improved way to query the path to the executable file of the calling process.

executablePath :: Maybe (IO (Maybe FilePath))

The IO query is not defined on all platforms. Where it is defined, its behaviour differs by platform. So it is an interesting feature to test.

One could write multiple small test programs, one for each operating system. Then tell the test driver to run the test for the current system, and skip the others. Alternatively, define a single test program, but tell it what platform it’s running on. That is what I did.

The test driver declaration adds the operating system to the test program’s arguments:

test('executablePath',
     extra_run_opts(config.os),
     compile_and_run,
     [''])

The test program itself then implements some OS-aware checks of the behaviour of executablePath. First come lists of which systems have what behaviour:

canQuery = ["mingw32","freebsd","linux","darwin","netbsd"]
canDelete = ["freebsd","linux","darwin","netbsd"]
canQueryAfterDelete = ["netbsd"]

In main, grab the OS from the program arguments:

main :: IO ()
main = do
  [os] <- getArgs

Next grab the query function. If the query is expectedly undefined, stop here (exitSuccess). If the query is unexpected undefined, or unexpectedly defined, fail the test. Otherwise return the query.

  query <- case (os `elem` canQuery, executablePath) of
    (False, Nothing) -> exitSuccess
    (False, Just _) -> die "query unexpectedly defined"
    (True, Nothing) -> die "query unexpected not defined"
    (True, Just k) -> pure k

Now run the query. If it returns Nothing, fail the test (it should return a result).

  before <- query >>= \r -> case r of
    Nothing   -> die "query unexpectedly returned Nothing"
    Just path -> pure path

We need to compare the result (before) to the expected value. That is, the file executablePath in the current directory:

  cwd <- getCurrentDirectory
  let expected = cwd </> "executablePath"

Also drop the file extension (if any) from the result of the query. This is needed because GHC names the executables it generates with a file extension on some platforms (e.g. .exe on Windows).

  let actual = dropExtension before

Now compare expected and actual. Use equalFilePath because the query may return a non-normalised path on some systems (I have observed this on NetBSD):

  unless (equalFilePath actual expected) $
    die "query result did not match expected"

Now, what happens if we delete the executable while the process runs? First of all, some operating systems don’t even allow that. We grant those systems an honourable discharge. The remaining systems delete the file.

  unless (os `elem` canDelete)
    exitSuccess
  removeFile before

Finally we run the query again. Once again, the expected behaviour differs by platform. On Mac OS X and FreeBSD, we expect Nothing. But NetBSD successfully returns the original value.

  after <- query
  case after of
    Nothing
      | os `elem` canQueryAfterDelete
      -> die "query unexpected failed after delete"
      | otherwise
      -> pure ()
    Just _
      | os `elem` canQueryAfterDelete
      -> pure ()
      | otherwise
      -> die $ "query unexpected succeeded after delete"

Phew, quite a lot of code to test one little feature. There is no standard system interface for querying the executable path. So it is no surprise to see such diverse behaviour across different platforms—including no query mechanism at all (looking at you, OpenBSD).

Conclusion §

In this article I gave an introduction to writing tests for the GHC test suite, with some examples. The GHC wiki contains more comprehensive documentation. Performance tests are a more complex aspect of the GHC test suite which I didn’t discuss in detail.

I previously wrote about System.Environment.getExecutablePath and how I fixed it on FreeBSD. Unfortunately, this function still has some problems. In this post I explain the problems and introduce executablePath, the solution arriving in base-4.17.0.0 (GHC 9.4.1).

Problems with getExecutablePath §

getExecutablePath :: IO FilePath is a way for a Haskell program to query the path to its own executable. It has several significant problems:

• Not all operating systems provide a reliable mechanism to query the executable path. Where an OS-specific implementation does not exist, getExecutablePath falls back to providing the value of argv[0] (#12377). The invoking process chooses the value; it does not necessarily represent the path to the executable. It might represent or resolve to a different executable. argv could even be an empty array, in which case getExecutablePath throws an exception!

• Divergent behaviour when executable has been deleted. When we say “executable” we mean “file which contains program text, which the OS can load and execute (becoming a process)”. That file could be deleted while the process is running. In this case, the behaviour of getExecutablePath differs by platform. On FreeBSD it throws an exception. On Linux it returns the original FilePath suffixed with " (deleted)" (#10957). These differences impede cross-platform development.

• The documentation is wrong. Until I fixed it, the documentation for getExecutablePath stated, “Returns the absolute pathname of the current executable.” It didn’t explain any of the discrepancies mentioned in the preceding points. Programmers can easily stumble into the unsafe behaviour (I did).

Type of the solution §

Types are an essential tool for modelling a problem and guiding the development of a solution. The problems with getExecutablePath reveal that:

• Some OSes provide a mechanism to query the executable path, and some do not. This is a static property of the platform; it does not change over the lifetime of a process.

• The query mechanism (if it exists) might be unable to return a result. For example, when the executable file has been deleted. The result may vary during the lifetime of a process.

The Maybe a type models the existence or absence of a value:

data Maybe a = Nothing | Just a

Accordingly, a suitable type to model this problem is:

executablePath :: Maybe (IO (Maybe FilePath))

The outer Maybe models the presence or absence of a query mechanism. The query itself has the type IO (Maybe FilePath). The inner Maybe models that the query might be unable to return a valid FilePath.

The type is also a kind of (machine-checked) documentation. It reveals things that the written documentation for getExecutablePath should have said, but didn’t.

type FilePath = String
type String   = [Char]

Implementation of executablePath §

In this section I’ll briefly review the implementation. GHC merge request !4779 has the gory details, for those interested.

I was able to implement executablePath without modifying any code that uses the foreign function interface (FFI). getExecutablePath was unchanged. executablePath implementations wrap the former. See my earlier post for an example of how getExecutablePath uses the FFI.

Mac OS X, FreeBSD and NetBSD §

The FreeBSD and NetBSD implementations of getExecutablePath are nearly identical, but the implementation for Mac OS X is very different. Nevertheless, the observable behaviour is identical: the system calls error with ENOENT when the executable has been deleted, and succeed otherwise. No other expected failure scenarios are known (yet).

Therefore, the executablePath implementation for these platforms boils down to catching the Haskell exception value corresponding to ENOENT and turning it into Nothing. Unexpected exceptions are re-thrown.

executablePath =
  Just (fmap Just getExecutablePath `catch` f)
    where
    f e | isDoesNotExistError e = pure Nothing
        | otherwise             = throw e

Linux §

The Linux implementation of getExecutablePath reads the value of /proc/self/exe (part of the procfs(5)). The man page states:

If the pathname has been unlinked, the symbolic link will contain the string ‘(deleted)’ appended to the original pathname.

executablePath checks for this condition and, if detected, returns Nothing. Note that we could have stripped the suffix and returned Just the “original” path. Returning Nothing makes it consistent with the other platforms.

executablePath = Just (fmap check getExecutablePath)
  where
  check s | "(deleted)" `isSuffixOf` s = Nothing
          | otherwise                  = Just s

Windows §

Windows prevents the deletion of an executable file during the lifetime of any process created from it. So executablePath simply wraps the result of getExecutablePath with a Just.

executablePath = Just (fmap Just getExecutablePath)

Fallback implementation §

The “fallback implementation” is for platforms that don’t have a reliable mechanism for querying the executable path (or no one implemented it in GHC yet). In this case, executablePath does not even supply the query IO action.

executablePath = Nothing

Programs that want to query the executable path have to deal with the Nothing case. That is: the possibility that there is no reliable way to get it. That’s a good thing.

Conclusion §

This article explained the problems of getExecutablePath and reviewed the solution coming in GHC 9.4, called executablePath. I encourage programs that use getExecutablePath to migrate when feasible, especially if multi-platform support is important.

One topic I did not discuss is how I implemented tests for this feature in the GHC test suite. I will cover this in an upcoming post.

Haskell has separate namespaces for types and values. When types and data constructors share a name, Haddock, Haskell’s documentation generator, can get confused. In this post I show how to disambiguate types and values in Haddock documentation.

Demonstrating the problem §

For demonstration purposes I created a simple module, ACME.Disamb:

module ACME.Disamb (Foo(..), Bar(..), Quux, Xyxxy) where

data Foo = Foo

-- | A bar contains a 'Foo'.  Example:
--
-- @let bar = 'Bar' 'Foo'@
--
data Bar = Bar Foo

data Quux

class Xyxxy a

Note that Foo is the name of both a type and a data constructor. Same for Bar. Quux is a type with no constructor and Xyxxy is a class. The Haddock for type Bar contains ambiguous references to both Bar and Foo.

Let’s look at the HTML Haddock generated for each top-level declaration:

data Foo §

<div class="top">
  <p class="src">
    <span class="keyword">data</span> <a id="t:Foo" class="def">Foo</a>
    <a href="#t:Foo" class="selflink">#</a>
  </p>
  <div class="subs constructors">
    <p class="caption">Constructors</p>
    <table>
      <tbody>
        <tr>
          <td class="src"><a id="v:Foo" class="def">Foo</a></td>
          <td class="doc empty">&nbsp;</td>
        </tr>
      </tbody>
    </table>
  </div>
</div>

The element representing type Foo has id="t:Foo", whereas the constructor has id="v:Foo". These identifiers can be used as fragment identifiers in hyperlinks. Types and values are disambiguated through the t:… and v:… identifier prefixes.

data Bar §

<div class="top">
  <p class="src">
    <span class="keyword">data</span> <a id="t:Bar" class="def">Bar</a>
    <a href="#t:Bar" class="selflink">#</a>
  </p>
  <div class="doc">
    <p>
      A bar contains a
      <code><a href="ACME-Disamb.html#t:Foo" title="ACME.Disamb">Foo</a></code>. Example:
    </p>
    <pre>let bar = <code><a href="ACME-Disamb.html#t:Bar" title="ACME.Disamb">Bar</a></code> <code><a href="ACME-Disamb.html#t:Foo" title="ACME.Disamb">Foo</a></code></pre>
  </div>
  <!-- constructors elided -->
</div>

Here we can see that all references to Foo and Bar in the documentation I wrote all link to t:Foo or t:Bar. This is not what I intended. The usage example should refer to the data constructors.

In my example this is a minor nuisance, but recall that Foo could be the constructor of some other type. The type Foo could be unrelated!

data Quux §

<div class="top">
  <p class="src">
    <span class="keyword">data</span> <a id="t:Quux" class="def">Quux</a>
    <a href="#t:Quux" class="selflink">#</a>
  </p>
</div>

Quux has no constructor. As a result, there is no element with id="v:…".

class Xyxxy a §

<div class="top">
  <p class="src">
    <span class="keyword">class</span> <a id="t:Xyzzy" class="def">Xyzzy</a> a
    <a href="#t:Xyzzy" class="selflink">#</a>
  </p>
</div>

Type class names inhabit the type namespace. Therefore the corresponding element identifiers also use the t:… prefix.

The solution §

To refer explicitly to a type or value, prefix the reference with t or v. For example:

-- | A bar contains a 'Foo'.  Example:
--
-- @let bar = v'Bar' v'Foo'@
--
data Bar = Bar Foo

The resulting HTML

…
  <div class="doc">
    <p>
      A bar contains a
      <code><a href="ACME-Disamb.html#t:Foo" title="ACME.Disamb">Foo</a></code>. Example:
    </p>
    <pre>let bar = <code><a href="ACME-Disamb.html#v:Bar" title="ACME.Disamb">Bar</a></code> <code><a href="ACME-Disamb.html#v:Foo" title="ACME.Disamb">Foo</a></code></pre>
  </div>
…

Inter-module references §

Consider the following module:

-- | See also 'ACME.Disamb.Quux'.
module ACME.Disamb2 where

Unlike references within a module, inter-module references default to the value namespace:

<p class="caption">Description</p>
<div class="doc">
  <p>
    See also
    <code><a href="ACME-Disamb.html#v:Quux" title="ACME.Disamb">Quux</a></code>.
  </p>
</div>

Recall that Quux has no constructor. So the link doesn’t even target the wrong identifier; it targets a non-existent identifier.

The solution is the same: prefix the whole reference with t:

-- | See also t'ACME.Disamb.Quux'.
module ACME.Disamb2 where

A few weeks ago Tom Sydney Kerckhove (@kerckhove_ts) published an excellent writeup of a serious DoS vulnerability in aeson, a widely used Haskell JSON library. A new aeson release addresses the hash flooding issue, but you need more than a version bump to ensure your programs are protected. This post outlines how aeson addressed the vulnerability and what action you need to take.

Overview of the issue §

Tom’s article is great and if you want the gory details, go read it. There’s no need for me to repeat it here. It’s enough to say that the attack, called hash flooding or hash DoS, exploits the behaviour of the HashMap implementation from unordered-containers, which aeson used. It results in a denial of service through CPU consumption. This technique has been used in real-world attacks against a variety of languages, libraries and frameworks over the years.

Am I vulnerable? §

If you are using aeson < 2.0.0.0 and processing JSON from untrusted sources, you are probably vulnerable. You could mitigate the attack by refusing to decode large inputs, if your use case allows it. Rate limiting may be a possible mitigation for some applications.

How did aeson address the vulnerability? §

Whereas prior versions used HashMap directly, starting at version 2.0.0.0 aeson abstracts the map implementation behind a new data type: Data.Aeson.KeyMap. The ordered-keymap Cabal flag selects the underlying implementation. When set, aeson uses the Ord-based Map from containers. If unset, aeson uses HashMap.

Version 2.0.0.0 defaults the flag to False. As of 2.0.1.0 it defaults to True. Importantly, the maintainers offer no guarantee that the default won’t change again. So if you use aeson and want to protect yourself from hash flooding attacks, take the extra precautions outlined in the following sections.

This is an API-breaking change, hence the major version bump. Most users will not have to change much code, but there will be exceptions (I had to change quite a lot for jose).

The Map version also behaves differently from HashMap. In particular, objects may be serialised with a different key order, and object keys are iterated in different orders. And who knows what systems out there depend on the key order in some way, even though they should not. That is a big reason why the maintainers felt it was necessary to keep the option of using HashMap.

Also, these data structures have different performance characteristics, with Map having O(log n) insertion and lookup time. HashMap insertion and lookup are amortised O(1), degrading to O(n) for pathological inputs—which is the cause of the vulnerability!

Compiling a safe version of aeson §

If you have a program or library that uses aeson, you need to ensure that the aeson you link against was compiled with the ordered-keymap flag. There is no way to express this condition in a .cabal file, but you can can express these constraints in the cabal.project file:

packages: .
constraints:
  aeson +ordered-keymap

For Stack users, configure the flag in your stack.yaml:

flags:
  aeson:
    ordered-keymap: true

If you’re building and installing aeson directly, via cabal-install (the cabal program), you can use the --flags=ordered-keymap command line option.

Runtime checks §

In your program or library you can also detect the KeyMap implementation at runtime. If you detect HashMap you could abort, emit a warning, or employ other mitigations like limiting the input size.

Data.Aeson.KeyMap exports the following types:

coercionToHashMap
  :: Maybe (Coercion (HashMap Key v) (KeyMap v))

coercionToMap
  :: Maybe (Coercion     (Map Key v) (KeyMap v))

The values are coercions—proofs of representational equality enabling zero-cost conversions; see Data.Type.Coercion. Only one of HashMap or Map is actually used, which is why they’re wrapped in Maybe. The map implementation that aeson is using has a non-Nothing coercion.

In jose I will export the following value to make it easy for library users to check that the implementation is safe from hash flooding:

vulnerableToHashFlood :: Bool
vulnerableToHashFlood =
  case KeyMap.coercionToMap of
    Just _  -> False
    Nothing -> True

Users can (and hopefully will) check that value and respond in whatever way is suitable for their use case. I might go even further and cause all JWS processing to immediately fail when the vulnerable implementation is detected, unless the caller overrides this behaviour.

What about other things that use HashMap? §

The HashMap data structure from unordered-containers remains vulnerable to hash flooding attacks. Users and maintainers are discussion potential solutions and mitigations in issue #319. There are several interesting ideas, including:

• Initialise the library with a random salt, via unsafePerformIO. Many libraries in other language ecosystems use this approach. But it breaks referential integrity. Values and orders will not be stable across different executions.

• Use a more collision-resistant hash algorithm, or multiple hashes, to make it harder to compute collisions.

• Don’t do anything, because the other ideas come with performance or usability penalties. If your program needs to be safe against hash flooding, employ other mitigations (size check, rate limiting, etc) or use an ordered map.

This discussion is ongoing. The only change so far is to add a security advisory to the package description.

Conclusion §

aeson >= 2.0.0.0 has mitigated the hash flooding vulnerability. Users of the library must take specific action not only to upgrade aeson to the latest version, but also ensure it is compiled with the correct flags. Programs can also perform runtime checks and take appropriate action if aeson is using HashMap.

Hedgehog has a powerful API for generating arbitrary values of your types. But sometimes a library will already provide a random generator. In this post I show how to use existing generators with Hedgehog, and discuss the advantages and disadvantages.

Random generator use cases §

Libraries may need to provide random generators of (some of) their types for a variety of reasons. Cryptographic keys, secrets and unique identifiers come to mind immediately.

One use case we have in purebred-email is generation of MIME multipart boundary values (RFC 2046). The boundary is a string with 1–70 characters from a restricted alphabet. Using a random boundary is useful because the boundary delimiter line (the boundary value preceded by two hyphens) must not appear anywhere within the message parts.

The Boundary type is defined as follows:

-- constructor NOT exported
newtype Boundary = Boundary ByteString
  deriving (Eq, Show)

unBoundary :: Boundary -> ByteString
unBoundary (Boundary s) = s

-- smart constructor; checks length and validity
makeBoundary :: ByteString -> Either ByteString Boundary

We don’t export the constructor. Users must use the makeBoundary smart constructor which checks that the input is a valid boundary value.

We also instance the Uniform type class from the random package (version 1.2.0 onwards). This instance provides a convenient way for users to generate conformant boundary values that have a negligible probability of matching any line in an arbitrary message.

import qualified Data.ByteString as B
import qualified Data.ByteString.Internal as B
import qualified Data.ByteString.Char8 as C8

instance Uniform Boundary where
  uniformM :: StatefulGen g m => g -> m a
  uniformM g =
    Boundary . B.unsafePackLenBytes 64 <$> randString
  where
    randString  = replicateM 64 randChar
    randChar    = B.index bchars <$> randIndex
    randIndex   = uniformRM (0, B.length bchars - 1) g
    bchars      = C8.pack $
                       ['a'..'z'] <> ['A'..'Z']
                    <> ['0'..'9'] <> "'()+_,-./:=?"

The random library provides a very general interface to instantiate and use random number generators. I cannot cover it in any detail in this post. Assuming you already have a generator value, System.Random.uniform generates a value of any type with an instance of Uniform:

uniform :: (RandomGen g, Uniform a) => g -> (a, g)

You can use uniform with System.Random.getStdRandom to generate values using a global pseudo-random number generated initialised from system entropy, as an IO action:

getStdRandom :: MonadIO m => (StdGen -> (a, StdGen)) ->  m a
getStdRandom ::              (StdGen -> (a, StdGen)) -> IO a

getStdRandom uniform :: (MonadIO m, Uniform a) =>  m a
getStdRandom uniform ::            (Uniform a) => IO a

Hedgehog and hidden constructors §

If a module does not expose the constructor of some type, how can the test suite generate random values of that type? There are several ways you could tackle this:

1. Export the constructor from some “internal” module, which is not really internal. In this way, library users may be discouraged—but not prevented—from constructing bad data. The test module can import the constructor from the library’s “internal” module and use it to define the generator.

2. Export a Hedgehog Gen for the type from the library itself. This causes the library to depend on Hedgehog, which is usually not desirable.

3. For a newtype, use Unsafe.Coerce.unsafeCoerce in the Gen definition to coerce the underlying type to the wrapped type. You cannot use Data.Coerce.coerce if the constructor is not in scope. This is nasty, but not unspeakable given we’re talking about generators for the test suite.

4. Export a “lightweight” random generator from the library, and reuse it to define the Gen in the test suite. If you were going to export a Uniform (or UniformRange) instance anyway, this will be low-effort. This approach is the main topic of this article.

Implementing Gen using Uniform §

I was aware that Hedgehog depends on random, and was hopeful of finding a way to use the existing Uniform instance to implement a Gen Boundary. Looking through the docs, I stumbled across generate:

generate :: MonadGen m => (Size -> Seed -> a) -> m a

It was not immediately apparent whether I could use generate to define a Gen Boundary. First, does Gen have an instance of MonadGen?

type Gen = GenT Identity

Monad m => MonadGen (GenT m)

Yes, it does. Next, I had to work out how to turn a Size and a Seed into a Boundary. To my delight, I saw that Seed has an instance of RandomGen. Putting it together, all that is required is to apply uniform to the Seed, and discard the new generator value. I ignore the Size.

import Hedgehog (Gen)
import Hedgehog.Internal.Gen (generate)

genBoundary :: Gen Boundary
genBoundary = generate (\_size seed -> fst (uniform seed))

Disadvantages §

There are a few disadvantages to reusing a library’s random generator to define your Hedgehog Gen.

First, the generated values are restricted to whatever the library’s generator gives you. In my case, the Boundary generator only generates values of length 64. It follows that Hedgehog could miss all kinds of bugs. For example, if purebred-email fails to decode boundaries of length 70 due to an off-by-one error, I have no hope of catching that bug.

Second, generate gives you a Gen with no shrinks. If Hedgehog finds a counterexample, it can’t do anything to try and simplify it. Automatic shrinking is one of Hedgehog’ss killer features, but you give it up by using generate.

You can use the shrink function to supply additional shrinking behaviour to a Gen:

shrink :: MonadGen m => (a -> [a]) -> m a -> m a 

But when you don’t have access to the constructor for the data type you’re generating, defining your own shrinks is at best awkward, and maybe impossible. I could implement Boundary shrinking by extracting the underlying ByteString (unBoundary), shrinking it, applying the smart constructor (makeBoundary) and filtering invalid values. That’s a lot of work. I didn’t bother.

Conclusion §

Defining Hedgehog Gen values can be awkward or very difficult for types whose constructors are hidden. But if you have a function that uses a RandomGen to generate values, you can use it with Hedgehog’s generate function to define a Gen. The downsides are that you don’t get automatic shrinking, and you are restricted to whatever values the generator produces.

Alternative approaches include exposing the constructor via an “internal” (but actually public) module, or using unsafeCoerce.