I wanted to test this claim with SAT problems. Why SAT? Because solving SAT problems require applying very few rules consistently. The principle stays the same even if you have millions of variables or just a couple. So if you know how to reason properly any SAT instances is solvable given enough time. Also, it's easy to generate completely random SAT problems that make it less likely for LLM to solve the problem based on pure pattern recognition. Therefore, I think it is a good problem type to test whether LLMs can generalize basic rules beyond their training data.

What is SAT?

SAT (short for "satisfiability") is a logic problem that given a boolean formula, it asks whether the boolean formula has an assignment that makes the problem true. An example boolean formula is:

(a || b) && !a

This formula is satisfiable because if we set to b to true and a to false, then the whole formula is true. All other assignments make the formula false, but it doesn't change that the formula is satisfiable as long as there is at least one assignment makes the formula true.

An unsatisfiable formula is:

b && !b

No matter what you assign to the b, it will be false since either the left or the right of the && operator is false.

CNF Form

There is a special form for boolean formulas called "Conjunctive Normal Form" (CNF). A problem in this form consists of clauses connected with and operators, where each clause only contains variables connected with or operators. The variables can appear negated, but only variables can be directly negated, something like !(a && b) is not allowed. An example boolean formula in CNF form is:

(a || b || c) &&
(!a || d || e) &&
(e || g || x)

SAT solvers usually expect boolean formulas in this form, because they are specialized to solve problems in this form efficiently. I decided to use this form to validate results of the LLM output with a SAT solver.

Testing Approach

My approach is very simple:

1. Generate random SAT instances, both SAT and UNSAT.
2. Feed the SAT instance to the LLM.
3. Verify the output.

Generating SAT problems

For the test to be fair for LLMs, the SAT instance should be reasonably large, but not too big. I can't just give SAT problems with thousands of variables. But also it shouldn't be too easy.

I learned that for 4-SAT, if clause to variable ratio is more than 10, the generated problems become difficult to solve, and the likelihood of formula to be SAT or UNSAT is close to 50%. So I generated 3 types of formulas:

1. SAT problem with 10 variables and 200 clauses
2. SAT problem with 14 variables and 126 clauses
3. UNSAT problem with 10 variables and 200 clauses

I used cnfgen to generate SAT instances using the following command:

cnfgen -q randkcnf 4 $VARIABLES $CLAUSES

This command outputs the formula in dimacs format, which is a standard format for CNF supported by every SAT solver. This makes it possible to validate LLM decision with another program.

Models

I used https://openrouter.ai to test multiple models without having to register to different LLM providers.

I tested following models:

• Gemini 3 Pro
• GPT 5.2 Mini
• GPT 5.2

For each model reasoning was enabled, and the reasoning effort is set to high. I included GPT 5.2 because it could be argued that it can reason better than mini. However, I couldn't test GPT 5.2 as much as the other models because it was too costly. Gemini 3 Pro was costly as well, but it didn't spend as much time as GPT 5.2 during reasoning which made it more affordable in my experience.

For each model, I used the same system prompt:

The user will give a CNF in dimacs format.
Determine if it's satisfiable or not WITHOUT USING ANY EXTERNAL TOOLS.
Use your own reasoning. Don't stop even if the formula is too large just try to solve it manually.
After determining the result output a JSON with two fields:
    - satisfiable: Boolean. True if the formula is satisfiable
    - assignment: Array of booleans. If the formula is satisfiable provide an assignment for each variable from 1 to N. If the formula is not satisfiable this field is null.

EXAMPLE INPUT: 
p cnf 10 10
-7 9 10 0
7 8 9 0
-7 -9 10 0
-2 3 5 0
-4 -6 -8 0
-1 3 -5 0
1 -3 -8 0
4 -5 -10 0
4 -7 -8 0
-2 -5 8 0

EXAMPLE JSON OUTPUT:
{
	"satisfiable": true,
	"assignment": [false, false, false, false, false, false, false, false, false, false]
}

Testing LLM Output

I used z3 theorem prover to assess LLM output, which is a pretty decent SAT solver. I considered the LLM output successful if it determines the formula is SAT or UNSAT correctly, and for SAT case it needs to provide a valid assignment. Testing the assignment is easy, given an assignment you can add a single variable clause to the formula. If the resulting formula is still SAT, that means the assignment is valid otherwise it means that the assignment contradicts with the formula, and it is invalid.

Initially I aimed to test with at least 10 formulas for each model for SAT/UNSAT, but it turned out to be more expensive than I expected, so I tested ~5 formulas for each case/model. First, I used the openrouter API to automate the process, but I experienced response stops in the middle due to long reasoning process, so I reverted to using the chat interface (I don't if this was a problem from the model provider or if it's an openrouter issue). For this reason I don't have standard outputs for each testing, but I linked to the output for each case I mentioned in results.

Results

All formulas used in this test can be found here.

Gemini 3 Pro

As a frontier flagship model, it was disappointing. It got no successful outcome. It seemed that it didn't reason thoroughly even though the reasoning was enabled, and the level set to high.

For SAT problems with 10 variables and 200 clauses, it usually output SAT as expected, but the assignment was never valid (Examples: first, second). Once it claimed a SAT formula was UNSAT. For this reason I didn't bother testing with more variables for the SAT case.

For UNSAT problems with 10 variables and 200 clauses, it always claimed that the formula is SAT and made up assignments (See this example).

GPT 5.2 Mini

Surprisingly, as a smaller model it performed better than Gemini 3 Pro. It found some valid assignments for SAT formulas, but has the same issue of making up assignments for UNSAT formulas.

For SAT problems with 10 variables and 200 clauses, sometimes outputted UNSAT because it couldn't find any satisfying assignment, and it would take a lot more time to find one, which is logically sound. I don't consider this as bad reasoning as it is about performance. So I tried it with only 100 clauses and it successfully found valid assignments.

For UNSAT problems with 10 variables and 200 clauses, it had the same issue as Gemini 3 Pro of making up assignments.

GPT 5.2

This one was a lot better than others. For every SAT problem with 10 variables and 200 clauses it was able to find a valid satisfying assignment. Therefore, I pushed it to test with 14 variables and 100 clauses, and it got half correct among 4 instances (See files with prefix formula14_ in here). Half correct sounds like a decent performance, but it is equivalent to random guessing.

For UNSAT problems with 10 variables and 200 clauses it had the same issue as others: making up assignments.

Conclusion

Testing LLM reasoning abilities with SAT is not an original idea; there is a recent research that did a thorough testing with models such as GPT-4o and found that for hard enough problems, every model degrades to random guessing. But I couldn't find any research that used newer models like I used. It would be nice to see a more thorough testing done again with newer models.

Even though my dataset is very small, I think it's sufficient to conclude that LLMs can't consistently reason. Also their reasoning performance gets worse as the SAT instance grows, which may be due to the context window becoming too large as the model reasoning progresses, and it gets harder to remember original clauses at the top of the context. A friend of mine made an observation that how complex SAT instances are similar to working with many rules in large codebases. As we add more rules, it gets more and more likely for LLMs to forget some of them, which can be insidious. Of course that doesn't mean LLMs are useless. They can be definitely useful without being able to reason, but due to lack of reasoning, we can't just write down the rules and expect that LLMs will always follow them. For critical requirements there needs to be some other process in place to ensure that these are met.

These concepts are very important to write and read modern C++ (though I doubt if C++11 is still considered "modern"). Even if you just want to write C with Classes-style C++, you will probably use standard containers like std::vector, which requires an understanding of C++ ownership related features such as RAII, references, and move semantics to use it properly. Without knowing those, you simply can't have the correct memory model for C++, resulting in buggy programs full of undefined behaviors and inefficient programs due to unnecessary copying. By knowing these concepts, you can both avoid introducing bugs due to lack of understanding and reason about programs better.

This writing is my understanding of C++ ownership model. I think it can be useful to you if you have a basic level understanding of C++ and you want to learn more, or you are familiar with C++ but never learned the concepts and terminology formally.

Who owns the Object?

In C++, every object has an owner, which is responsible for cleaning up the data once it's not used anymore. If you come from garbage collected languages, the concept of ownership may seem strange to you. But consider the following code:

char* get_name(File* file);

This is a function that returns the file's name as a C-style string. What's not documented though, is who is supposed to deallocate the returned string. In this case there are two possibilities:

1. The function allocates new memory, and the caller must deallocate it once it's no longer being used.
2. file has a property that holds the file's name, and the function only returns the address of this property. The caller must not deallocate it.

Depending on which one is the case, the caller must act differently. This is because the owner of the data is different between these two cases. In the first case, owner is the variable assigned to the function's return value, and in the second, owner is the file variable. If the latter is the case, the variable assigned to the return value borrows the data owned by file.

In a garbage collected language, you don't have this distinction because, in a sense every variable is a borrower, and the owner is the garbage collector (GC). The GC just ensures that the data is allocated as long as there is a reference (borrower) to it. But at the same time every variable can be considered an owner since holding a variable keeps the data alive. C++ doesn't have a garbage collector, but it has a mechanism to automate some parts of object creation and destruction.

Creating and Destroying Objects

When you declare a variable to an object in C++, it will create the object, and the variable will be the owner of the object. If the object has a destructor (a special function that destroys the resources represented by the object), it's automatically destroyed when the block of the variable ends. This technique of connecting resources to variables is called RAII^[1]. The span that object is alive is called the lifetime of the object.

In modern C++, it is advised that you create objects with destructors so the resources are cleaned up automatically at the end of their lifetime. To see why, consider this example:

void foo(std::size_t buffer_size) {
  // Allocate some memory
  char* buffer = new char[buffer_size];
  
  int result = 0;
  try {
    while (has_more) {
	  read(buffer.get());
	  result += process(buffer.get());
    }
  } catch (std::exception e) {
    delete buffer;
    throw e;
  }
  delete buffer;
  return result;
}

The code essentially reads some data and writes it to buffer, and then adds the processed output of the buffer into result. Assume that read may throw, which means that it's possible to never execute the delete statement before return. To handle this case, then we must write a try catch block to delete the buffer in case an exception occurs and then rethrow the exception.

Instead of using raw char*, we can use an object with a destructor called unique_ptr. This class owns a pointer and destroys it once its lifetime ends:

void foo(std::size_t buffer_size) {
  // Allocate some memory
  std::unique_ptr<char[]> buffer = std::make_unique<char[]>(buffer_size);
  
  int result = 0;  
  while (has_more) {
    read(buffer.get());
    result += process(buffer.get());
  }
  
  // `s` will be freed before returning
  return result;
}

We don't need to write any free or delete because the buffer is a unique_ptr^[2]. This is a "smart" pointer type that de-allocates the memory once the block it declared ends (this is related to lifetime, which I will talk about shortly). Note that even if the body throws, the cleanup process will still work. This may not seem like a big issue in the scale of this code, but in a large function, resource cleanup gets messy real quick. In fact, this is one of the few use cases where it still makes sense to use goto in C today.

RAII^[1] (Resource Acquisition Is Initialization) basically means constructing a value means creating the resource it represents, and consequently when the value is no longer reachable, destroying the resource. To make it more concrete, consider using a heap memory, but there are other resource types like files, mutex locks etc... In the absence of a garbage collector, one must deallocate every allocated heap memory manually. With RAII one can make it handled automatically.

So RAII is very convenient, but is it magic? It is certainly not. RAII calls the object's destructor function when the object's lifetime ends. So if you hold a reference or pointer to an object that had its lifetime ended, you are in undefined behavior territory. So unlike garbage collectors, RAII without lifetime analysis doesn't protect you from accessing dangling references, even though it's still an improvement over manual allocation and deallocation.

Destructors

Destructors are basically functions that is executed when the object's lifetime ends. They are supposed to clean whatever resources were created in the object's constructor. Notice the "supposed to", because this part depends on the programmer to implement it correctly. For instance, if your class allocates a memory in the constructor and does nothing in the destructor, it will just leak memory. Therefore one must ensure everything is cleaned properly in the destructor of a class.

The name of a destructor function is ~A where A is the class name. When such a function is defined, it is automatically inserted to the end of the scope where a variable is no longer used anymore. To make it more concrete, consider the following mutex class:

class RAIIMutex {
private:
  std::mutex& mutex;
public:
  RAIIMutex(std::mutex& mutex): mutex{mutex} {
    mutex.lock();
  }
  
  ~RAIIMutex() {
    mutex.unlock();
  }
}

Then we can use it as following:

char* global_variable = ...;
std::mutex global_variable_mutex = ...;

void foo() {
  RAIIMutex guard(global_variable_mutex);
  
  // Can access global_variable safely
  process(global_variable);
  
  // Will automatically drop the lock here
}

As you see, destructors are used by RAII to deallocate the resource once the variable is no longer accessible, which leads us to the lifetime concept.

Lifetime

In C++, every object and reference has a lifetime, which means any object or reference has a point in time where its lifetime begins and ends. What does this mean? This may seem like a silly concept if you are used to garbage collected languages, because in those languages you rarely think, "when is this object not usable anymore?". You only create objects, and as long as you refer to an object, it's usable by definition. However, in C++ you must think about when an object stops being usable because it's possible that you refer to it through a variable name, pointer or reference, but the object is already destroyed.

Local variables, which are by far the most used variable type in most programs, begin their lifetime in the block they are declared in and end it when the block ends. If we go back to the RAII example, the lifetime of the buffer variable starts in the beginning of foo (because it's declared in foo's block) and is deallocated at the end of the block, which is the end of foo.

There are other types of variables with different lifetime behavior^[3] such as static variables, but it's out of scope for this writing.

One important observation is that, if there is an object that is reaching to the end of its lifetime, we can reuse its resources for another object since otherwise they will be destroyed anyway. This is essential to understanding moves.

Pointers/References

In many cases, you want to pass a variable to another function but don't want to copy the whole data. In this case you need to pass a pointer or reference to that variable. From now on I will only talk about references but almost everything equally applies to pointers as well. Analogous to normal variables, references also have their lifetimes. And intuitively, reference's lifetime must always be equal or smaller than the object's lifetime that reference points to. Otherwise you would be having a reference to an object that is already destroyed and as you may know that is undefined behavior.

A simple way to ensure this is to never store a reference passed to function such that the reference is used after function returns. Let me give an example. Consider:

size_t bar(const std::vector<int>& vec) {
  size_t result = 0;
  for (auto i : vec) {
    // Do something with i
  }
  return result;
}

This function is totally safe since it only uses vec to calculate a result. Once the function returns, the reference doesn't live anywhere else. But consider this:

class B {
std::vector<int>& vec;
public:
  void set_vec(std::vector<int>& vec) {
    this->vec = vec;
  }

  size_t bar() {
	  size_t result = 0;
	  for (auto i : vec) {
	    // Do something with i
	  }
	  return result;
  }
}

int main() {
  B b;
  if (some_condition) {
    std::vector<int> vec{1, 2, 3};
    b.set_vec(vec);
  }
  b.bar();
}

In this code, main creates an instance of B and conditionally sets it's reference variable to vec inside the if. However, then it calls b.bar, which refers to vec that is already destroyed at the end of the if block. Essentially the problem is that the lifetime of vec is limited to the if block but b has a larger lifetime which leads to a dangling reference.

In short, always ensure that references point to objects with a large enough lifetime to prevent painful debugging sessions.

Move

Up until this point, we learned how to create objects, copy them and hold references to them while they are alive. These are enough to write many useful programs, as C++ until C++11 only had these features. But there is one missing piece: transferring resources from one object to another. You can emulate moves with pointers to some degree (since you can just copy a pointer and reassign the old pointer to something else), but there are some things that's not possible to do without moves.

Consider how std::vector reallocates it's buffer. When you grow a vector you need to copy the object's from the old buffer to the new buffer. A simplistic implementation would be:

template <typename T>
void vector<T>::grow(size_t new_capacity) {
  T* new_buffer = new T[new_capacity];
  for (size_t i = 0; i < this->size; ++i) {
    new_buffer[i] = this->buffer[i];
  }
  T* old_buffer = this->buffer;
  this->buffer = new_buffer;
  this->capacity = new_capacity;
  delete[] old_buffer;
}

If you look into the in the for loop, you see that we make a copy assignment (because the value category of this->buffer[i] is lvalue but don't worry if you don't know what this means) from the old buffer to the new buffer for each element. This is a cheap operation if the type of the vector is a simple type but if it's holding large heap allocated objects it means every value in vector is duplicated. Since the old buffer is immediately deleted after the copy this is really unnecessary. As these objects are going to be destroyed anyway, it would actually not a problem to steal the contents of the objects in the old buffer.

You may think, "can't I just mempcy the old buffer to new buffer?". It wouldn't work because it would call destructor both in the old and new buffer for every memcpyed object. You can't also zero the old buffer since you don't know if that's a valid object representation. Also it's quite possible that object is self referential. In that case you would end up with a dangling pointer.

This is where the concept of move comes into the picture. By introducing move into C++ we can now steal resources from an object that is about to be destroyed, thus avoiding making unnecessary copies. Using std::move, we can rewrite the copy loop as:

for (size_t i = 0; i < this->size; ++i) {
    new_buffer[i] = std::move(this->buffer[i]);
}

Notice how the only difference is that we call std::move with the variable we want to move from and assign it's return value to the variable we want to move to. With this change the source object's resources will be reused in the new buffer, thus eliminating the unnecessary copying.

We now know how to move objects, so can we just spam std::move to any object type to achieve move behavior? The answer is no, unlike Rust move semantics, C++ move is something of a convention than a pure language feature, but there are also few language features playing a role.

One way to understand how something works is to simply look how it's implemented. So let's see, here is an overly simplified example std::move implementation:

template<class T>
typename T&& move(T& t) {
  return static_cast<T&&>(t);
}

Were you expecting something this simple? Probably not, but that's essentially what std::move is. In itself std::move doesn't actually move anything (great naming right?). It's just a glorified cast from an lvalue reference T& to an rvalue reference T&&. Previously, when we only talked about references in general what we actually meant was lvalue references. An rvalue reference is by convention a reference to an object that is about to expire, one can steal resources from it. There is nothing instrintic to the language that makes rvalue references stealing, and lvalue references non-stealing. We can treat them as opposites and write code that way, but that would be working against the whole standard library and overload resolution rules so it doesn't make sense to do. Existence of rvalue references allows writing overloads that normally copy to instead reuse the resources from the rvalue reference parameter. For example, consider two constructors for std::string:

std::string(const std::string& other);
std::string(std::string&& other);

First constructor takes an lvalue reference, so it will allocate a new buffer and copy the contents from other. Since it is only copying it's also const. While second constructor takes an rvalue reference, thus can simply assign the buffer from other to the new object, and assign other's buffer to nullptr (Therefore can't be const). When you normally pass an lvalue to a function, the overload with the lvalue reference will be choosen. But if you first call std::move then the second constructor will be picked. So that's essentially what std::move does, it makes you pick the rvalue reference overload among the other options.

Conclusion

This was a long one, so if you came this far, thank you! I hope now you have an understanding of the ownership system in C++. Essentially it's bunch of seemingly unrelated features that together forms a coherent (!) system. There is a lot more gritty details about this stuff, but for the most cases you don't need to know that well.

Thanks to Uğur for his feedback on the initial draft.

Further Reading

If you liked what you read and want to dive deeper, I recommend looking into these:

• https://cbarrete.com/move-from-scratch.html
• A video about C++ value categories

In this article I aim to provide an explanation of algebraic types for the working programmer. I intentionally avoid any terminology that a regular programmer may not know about. I hope by the end of the article you know what algebraic types are and can use it in real programming and spot it where it appears.

Types as Sets

What is a type, really? For instance, when we write int, what does it mean? One useful way to think about it is to treat types as sets. In this perspective, every type is treated as a set of possible values that is compatible with the type. For instance, bool is a type that has only true and false values. In OCaml bool is defined as:

type bool = true | false

In the left hand side we define the type bool. The right side provides the possible values, separated with |.

For integers, this is 0, 1 or any other integer value. It's a bit more difficult to define integers directly as a regular type because in this case there are infinitely many values that integer can take. Writing all these is impossible. But assuming it was possible, we could write:

type int = ... | -3 | -2 | -1 | 0 | 1 | 2 | 3 | ...

In practice, integer types are usually limited to some finite range (but still too large) but this is not related to what we are discussing here. Strings are very similar to integers from this perspective.

What about void type? What are the values that it accepts? In some languages it's not obvious, but we can think void as a type with only a single possible value. In OCaml for instance, unit corresponds to void. It's defined as:

type unit = ()

In C, C++ or Java, void is treated differently than other types which makes it awkward to use in some cases. If we consider it as just any other type, there is no real need to make an exception for void. This simplifies the type system as well as the implementation of the programming language. I will give some examples to this after we understand Algebraic Types.

Another interesting case is non-termination. What is the type of a while loop that never returns? Well, using the set perspective, if the expression returns no value, maybe it's type is a type which has no possible values? Note that this type is different than void because void has one value that it can take but this type can take none. Sometimes this type is called never, as in it's never possible to have a value of this type. We can also trivially define this type as:

type never

Since there is no value for this type, it is impossible to have a value of this type. Thus we can use it as the type of expressions or functions that doesn't terminate. Because, if it would terminate and return a value we would get a type error indicating that the value doesn't conform to the specified type.

Algebraic Types are Just Elementary School Algebra

Using this view of types as sets of values, it's really easy to understand algebraic types. In fact, it's actually based on the algebra you learned in elementary school!

What is algebra on numbers? It's addition, multiplication, subtraction and division. Algebraic types are exactly that, it's basically doing algebra over types. So basically it's addition and multiplication over types.

Product Types

Let's start with the more familiar one. If you have two types T1 and T2, what other types you can have with it? Well, you can have a value that contains from both of these types, one from T1 and one from T2. Similar to how a struct or class works in mainstream languages. We could express this in Java as:

class Pair {
    T1 first;
    T2 second;
}

In the algebraic type terminology, this is called a product type. The reason is simple, when you combine two types, the resulting type contains every value whose parts are the values from the respective types. If the first type has N values, and the second has M values. Let's assume both to be enum types, with N having 2 and M having 3 variants. If we create a pair type from N and M, we could have 6 different values. Because we can choose 2 from N and 3 from M, which results with 2 * 3 = 6. Hence, a pair type in the general case has N * M many values, hence the term product.

Every mainstream language supports this notion, because it's a very common use case, I am sure that this doesn't need any convincing. However, most languages doesn't support combining two types as a first class construct such as tuple types, therefore one has to explicitly define a new type for every combination. In practice, this lack leads to worse API designs, like the pattern of using pointers/references ^[1] to return multiple values or Go's multiple return values ^[2], because to return multiple arguments one has to create a custom type. Not having product types forces you to circumvent it with more specialized constructs that creates accidental complexity. Supporting product types as first class (See Rust and OCaml as examples) makes the language simpler and more unified, reducing the cognitive load for the user ^[3].

Sum Types

Now this part is a bit less apparent if you never used a functional language. But it's a really a common use case in programming that, you probably seen a problem before where you could use sum types.

A sum type is a type composed of two other types, where the values can be either from the first type or the second type. For instance if you want to denote a fallible arithmetic operation, where the result is int if successful and a string containing the error message if not, the type of this result is int or string.

The name sum comes from the fact that, similar to products, if you create a sum type from types N and M, you get a type where there are N + M different possible values. Because you can have N options from the first and M option from the second. It's similar to logical or in the sense that, a value of a sum type is actually from the first type or the second type.

Sum types appear commonly in real life. A value that can be null is a sum type, usually called Option or Maybe in programming languages. In OCaml it is defined as:

type a option = Some of a | None

The a denotes a generic type, if you are familiar with Java, it is equivalent to Option<A>. First construct Some is the case where a value is present, while None corresponds to null in imperative languages. This is not just an example, option type is very commonly used in programs written in OCaml and other functional languages. null being at the type level prevents many runtime errors and reduces verbosity (you don't have to write null checks everywhere).

Another example is modeling errors. In Go, when a function can return an error, it's idiomatic to return it as the second value. By convention, either the first value or the second value is nil (Go's null value). However, this convention is implicit and in nowhere is enforced. So when you return two values, you have 4 cases, but you actually assume only two cases can happen in practice. If both values are not null or null, that would violate the assumption. We can summarize it in a table:

The problem is, this invariant is never validated by the type checker and therefore the user has to be aware of the convention, which creates unnecessary cognitive load for the user. For instance, io.Reader interface may return EOF error while also returning some data. This is not what the general Go programmers assume to be the case, since they expect either err or val to be non-nil. This discrepancy causes real life bugs even though it's documented.

Another disadvantage is that the programmer can't know the product is in fact intended to model a sum type unless it's in the documentation or they read the whole code. Both of these create more cognitive load compared to sum type in the signature. Moreover, the lack of sum types cause real life bugs in general, like anything that requires human validation, such as this one.

Instead, we could simply use a sum type to denote it's either a success with the result value, or an error with the error information. In OCaml, there is result type exactly for that:

type (a, b) result = Ok of a | Error of b

When we have a value of type error, the type checker enforces that only two desired conditions can happen, and the undesired conditions are impossible to represent in code, making the code simpler and less prone to errors.

Using Algebraic Types in Practice

To demonstrate the practical benefits of algebraic types, lets write an interpreter for arithmetic expressions. We will only have integers and arithmetic operators. We will not go through parsing arithmetic expressions as it's not related to the topic.

The type of expressions follows naturally from the definition:

type expr =
| Number of int
| Add of { left : expr; right: expr }
| Sub of { left : expr; right: expr }
| Mul of { left : expr; right: expr }
| Div of { left : expr; right: expr }

The first case denotes integers for the operands. Following cases correspond to each arithmetic operator. For instance, 2 + (3 * 2) corresponds to:

let e = Add { 
  left = Number 2; 
  right = Mul { 
    left = Number 3; 
    right = Number 2; 
  } 
}

To evaluate expressions, we can write a simple evaluator, using pattern matching:

let rec eval (e : expr) : int =
  match e with
  | Number n -> n
  | Add { left; right } ->
    (eval left) + (eval right)
  | Sub { left; right } ->
    (eval left) - (eval right)
  | Mul { left; right } ->
    (eval left) * (eval right)
  | Div { left; right } ->
    (eval left) / (eval right)

If you are not familiar with pattern matching, it lets us determine the which variant the value has. The possible variants come from it's type. In this case, from the definition of expr, we know it's either a Number or one of the 4 operations. For the number case, we can return it directly. In other cases, the left and right fields have type expr, so first we have to recursively evaluate those subterms to get their int value. Then we can evaluate the current expression value by using the appropriate operator.

How could you do this without algebraic types? Abstract methods with inheritance can be used to emulate sum types. So we could have an abstract base class Expr then extend it for each case:

abstract class Expr { abstract int eval(); }

class Number extends Expr {
    int value;
    int eval() { return value; }
}

class Plus extends Expr {
    Expr left, right;
    int eval() { return left.eval() + right.eval(); }
}

// Rest is omitted

The base class Expr has a method eval which should return the evaluated value of the expression. Each subclass implements it, recursively calling subexpression's eval method. In this case, there is no clear definition of the data structure, but it's mixed with the behavior.

What if we want to interpret the expressions in a different way? Say we just want to convert it to it's written form. For the inheritance based solution, we would have to add a new base method to the class, and then implement it in the subclasses, like eval. With algebraic types, we could write another function that performs pattern matching. Something like:

let rec expr_to_string (e : expr) : string =
  match e with
  | Number n -> string_of_int n
  | Add { left; right } ->
    "(" ^ (expr_to_string left) ^ "+" ^ (expr_to_string right) ^ ")"
  | Sub { left; right } ->
    "(" ^ (expr_to_string left) ^ "-" ^ (expr_to_string right) ^ ")"
  | Mul { left; right } ->
    "(" ^ (expr_to_string left) ^ "*" ^ (expr_to_string right) ^ ")"
  | Div { left; right } ->
    "(" ^ (expr_to_string left) ^ "/" ^ (expr_to_string right) ^ ")"

I don't know you but I find the latter approach better. Because in the inheritance approach the relevant behavior is far away from each other. When someone wants to understand how string conversion works, they need to jump through every class. Whereas with the pattern matching, the relevant logic stays closer. Another issue is that operations implemented as a method in the class, therefore they have full access to the object's internals. However, those operations should only access the public interface of the objects.

The abstract method approach is not the only alternative. The Visitor Pattern ^[4] exists specifically to model sum types with object hierarchies ^[5]. Using visitor pattern, we could have the following implementation:

abstract class Expr { 
  abstract <R> R accept(Visitor<R> visitor);
}

class Number extends Expr {
    int value;
    <R> R accept(Visitor<R> visitor) { return visitor.visit(this); }
}

class Plus extends Expr {
    Expr left, right;
    <R> R accept(Visitor<R> visitor) { return visitor.visit(this); }
}

class Mul extends Expr {
    Expr left, right;
    <R> R accept(Visitor<R> visitor) { return visitor.visit(this); }
}

class Sub extends Expr {
    Expr left, right;
    <R> R accept(Visitor<R> visitor) { return visitor.visit(this); }
}

class Div extends Expr {
    Expr left, right;
    <R> R accept(Visitor<R> visitor) { return visitor.visit(this); }
}

interface Visitor<R> {
  R visit(Number number);
  R visit(Plus plus);
  R visit(Mul mul);
  R visit(Sub sub);
  R visit(Div div);
}

class EvalVisitor implements Visitor<Integer> {
  public Integer visit(Number number) { return number.value; }
  public Integer visit(Plus plus) { return plus.left.accept(this) + plus.right.accept(this); }
  public Integer visit(Mul mul) { return mul.left.accept(this) * mul.right.accept(this); }
  public Integer visit(Sub sub) { return sub.left.accept(this) - sub.right.accept(this); }
  public Integer visit(Div div) { return div.left.accept(this) / div.right.accept(this); }
}

It solves the problem of having to add new methods to the base class compared to naive inheritance approach. Also the relevant logic sits inside a single place, in this case the visitor implementation. However, it's a lot more verbose than pattern matching and more difficult to understand. It has more accidental complexity ^[6] compared to pattern matching. Essentially visitor pattern is poor man's pattern matching. As Mark Seeman said ^[5]:

That's not to say that these two representations are equal in readability or maintainability. F# and Haskell sum types are declarative types that usually only take up a few lines of code. Visitor, on the other hand, is a small object hierarchy; it's a more verbose way to express the idea that a type is defined by mutually exclusive and heterogeneous cases. I know which of these alternatives I prefer, but if I were caught in an object-oriented code base, it's nice to know that it's still possible to model a domain with algebraic data types.

Conclusion

In short, for the most programming tasks you need two fundamental ways to combine types: the product and the sum. With these you can create arbitrary structures that can model real world data. Most languages have a way to express these two constructs, albeit some ways to represent it are more cumbersome such as using inheritance to emulate sum types. Using fundamental concepts you can model things in a simpler way without introducing unnecessary complexity.

Credits

Thanks Uğur for his detailed and valuable feedback on the draft of this article.

There are already articles about generating Docker images for a Scala project even with Nix, so why am I writing another one? The reason is that when I followed them, I ended up with a 722 MB Docker image! I found this to be unnecessarily big which motivated me to look for ways to reduce it. So this article is about building a minimal Docker image for a Scala project using Nix. Most of it can be applied to any program that runs on JVM (Java, Kotlin, etc.) as well.

Containerization of a JVM application feels a bit strange because one has to also bundle the JVM to execute the JAR, so it's essentially virtualization over virtualization, which also most probably runs on a virtual machine.

Side note: If you just want to the see the end result, you can jump directly to the last section.

Anyway... let's start.

First attempt

In order to containerize an sbt project one has to:

1. Build a JAR with all the dependencies included. This is called "über JAR". Normally JARs don't include their dependencies and load them at runtime, similar to how shared libraries work.
2. Bundle it with a JVM (Java Virtual Machine). JVM applications need a virtual machine to be executed.
3. Package the whole thing into a Docker-compatible container image.

Side note: If you are not familiar with sbt (Scala Build Tool), it's the de-facto build tool for Scala projects.

I am going to do all steps with Nix, since that gives me reproducible builds and I already use it for development.

My first attempt was the following:

let
    repository = builtins.fetchTarball {
        url = "https://github.com/zaninime/sbt-derivation/archive/master.tar.gz";
    };
    sbt-derivation = import "${repository}/overlay.nix";
    app = sbt-derivation.mkSbtDerivation.${system} {
        pname = "app";
        version = "0.0.1";
        src = ./.;
        depsSha256 = "sha256-06Qog8DyDgisnBhUQ9wW46WqqnhGXlakI1DSuFHkriQ=";

        buildInputs = with pkgs; [ sbt jdk23 makeWrapper ];

        buildPhase = "sbt assembly";

        installPhase = ''
        mkdir -p $out/bin
        mkdir -p $out/share/java

        cp src/app/target/scala-3.*/*.jar $out/share/java

        makeWrapper ${pkgs.jdk23_headless}/bin/java $out/bin/scala-app \
            --add-flags "-cp \"$out/share/java/*\" org.app.Application"
        '';
    };
    app-container = pkgs.dockerTools.buildImage {
        name = "app-container";
        tag = "latest";

        copyToRoot = [ app pkgs.busybox ];

        config = { Cmd = [ "/bin/${app.pname}" ]; };
    };
in 
    app-container

Explanation:

1. sbt-derivation is a convenience utility to generate Nix derivations for sbt projects.
2. sbt-assembly lets us generate "über JAR" with all the necessary dependencies.
3. makeWrapper creates a binary that wraps the JAR with a java binary so it looks like a regular binary from the outside. The binary comes from jdk23_headless package.

After I built the container, I was pushing it into the hosting provider's registry, but I noticed it took a lot of time to upload it. My home connection is not really fast (I would expect better from Germany), so having to wait 15 minutes to deploy a new version of the application was very annoying. I checked the image size locally, and I saw:

REPOSITORY                                   TAG                               IMAGE ID      CREATED        SIZE
localhost/app-container                      latest                            f0e2ad8f1167  55 years ago   722 MB

Ignore the obviously incorrect CREATED 55 years ago, the image was 722 MB! This is huge for a project like this. Annoyed by it, I went to check out the contents of the image. Using docker/podman one can export the image filesystem into a .tar archive:

aiono ❯ docker create localhost/app-container:latest
0b08b8de863228c8211d7c844a3e84a9b03c5032f68ee582e1e0fca6caee0244
aiono ❯ TMP_DIR=$(mktemp -d)
aiono ❯ docker export 0b08b8de863228c8211d7c844a3e84a9b03c5032f68ee582e1e0fca6caee0244 > "$TMP_DIR/image.tar"
aiono ❯ mkdir "$TMP_DIR/image"
aiono ❯ tar -xf "$TMP_DIR/image.tar" -C "$TMP_DIR/image"

Then I checked the contents of the image using du:

aiono ❯ du -sh $TMP_DIR/image/*
1,2M    /tmp/tmp.3xnIHXwY1l/image/bin
4,0K    /tmp/tmp.3xnIHXwY1l/image/default.script
0       /tmp/tmp.3xnIHXwY1l/image/linuxrc
651M    /tmp/tmp.3xnIHXwY1l/image/nix
1,2M    /tmp/tmp.3xnIHXwY1l/image/sbin
37M     /tmp/tmp.3xnIHXwY1l/image/share

It seems like most of the size comes from /nix/store which is not surprising. What's under /share should be the JVM. So it seems like the problem is not in the JAR since it's just 37 MB. Let's verify:

aiono ❯ du -sh /tmp/tmp.3xnIHXwY1l/image/share/java/*
37M     /tmp/tmp.3xnIHXwY1l/image/share/java/scala-app-assembly-0.1.0.jar

Correct!

Let's see what are the largest directories under /nix/store:

aiono ❯ du -sh $TMP_DIR/image/nix/store/* | sort -h | tail -n 10
484K    /tmp/tmp.3xnIHXwY1l/image/nix/store/mk9nhl6b48gpqhdbjy9ir16wrz6r3qn6-lcms2-2.17
628K    /tmp/tmp.3xnIHXwY1l/image/nix/store/ncdwsrgq6n6161l433m4x34057zq0hhf-libidn2-2.3.8
1,2M    /tmp/tmp.3xnIHXwY1l/image/nix/store/skijwg3cx0hkl5p2l5l4zz898glxi644-busybox-1.36.1
1,7M    /tmp/tmp.3xnIHXwY1l/image/nix/store/00zrahbb32nzawrmv9sjxn36h7qk9vrs-bash-5.2p37
2,0M    /tmp/tmp.3xnIHXwY1l/image/nix/store/vm18dxfa5v7y3linrg1x1q9wx41bkxwf-libunistring-1.3
2,0M    /tmp/tmp.3xnIHXwY1l/image/nix/store/w753b87diqcja7gc3kifydxdfpi967ns-libjpeg-turbo-3.1.0
9,6M    /tmp/tmirectories undep.3xnIHXwY1l/image/nix/store/l7d6vwajpfvgsd3j4cr25imd1mzb7d1d-gcc-14.3.0-lib
31M     /tmp/tmp.3xnIHXwY1l/image/nix/store/q4wq65gl3r8fy746v9bbwgx4gzn0r2kl-glibc-2.40-66
37M     /tmp/tmp.3xnIHXwY1l/image/nix/store/778xsjch86fyv4qdzznqyihcw7s5r029-scala-app-0.0.1
566M    /tmp/tmp.3xnIHXwY1l/image/nix/store/w7rphym6zk35wsx3aknbn3y7srj3x5qa-openjdk-headless-23.0.2+7

The winner is definitely openjdk-headless. Almost all of the 722 MB comes from it. So that will be the first thing we will try to reduce. Second is odd; scala-app is the package for our app, but we already have a copy of our app in /share! So it looks like a duplication, but first focus on our JDK package.

Minimal Java Runtime Environments

My first mistake was to bundle a full Java Development Kit (JDK) with the application. JDKs are used to build a JVM app but to run it, you only need Java Runtime Environment (JRE). I searched for jre in Nix Search. The second option was jre_minimal, which sounded very promising. So I made the following change:

- makeWrapper ${pkgs.jdk23_headless}/bin/java $out/bin/scala-app \
+ makeWrapper ${pkgs.jre_minimal}/bin/java $out/bin/scala-app \

Let's see how our image size changed:

aiono ❯ nix-build
aiono ❯ cat result | docker load
aiono ❯ docker images
REPOSITORY                        TAG                               IMAGE ID      CREATED        SIZE
localhost/app-container           latest                            0b25de30d43c  55 years ago   508 MB

It's down to 508 MB. Still very big but at least we managed to trim it down 200 MB. Let's try to run our app:

aiono ❯ nix-build
aiono ❯ docker run --expose 4041 --network host localhost/app-container:latest
Exception in thread "main" java.lang.NoClassDefFoundError: sun/misc/Unsafe
        at ...

Not good. It seems like we need sun.misc.Unsafe but jre_minimal doesn't come with it. We need to fix this.

I don't remember how I found it, but this section in the nixpkgs reference shows how to use jre_minimal. Turns out, jre_minimal strips out all the standard modules to provide a minimal JRE, so you need to provide which libraries you want. Under the hood, it uses jlink to generate a minimal JRE.

How do we know which modules we need? Thankfully, there is a tool for that called jdeps. We can run it in our assembled jar to see which dependencies we need.

aiono ❯ jdeps --ignore-missing-deps --list-reduced-deps result/share/java/server-assembly-0.1.0.jar
   java.base
   java.desktop
   java.managementcipher suites 
   java.naming
   java.security.jgss
   java.security.sasl
   java.sql
   jdk.unsupported

Side note: In my case, I later realized that I needed some more modules for my application to actually work. These were jdk.crypto.ec and jdk.crypto.cryptoki. Without these, I couldn't make requests to some websites which requires encryption algorithms provided from these modules. In case you see javax.net.ssl.SSLHandshakeException: Received fatal alert: insufficient_security adding these may solve your issues.

Let's add those:

let
    repository = builtins.fetchTarball {
        url = "https://github.com/zaninime/sbt-derivation/archive/master.tar.gz";
    };
    sbt-derivation = import "${repository}/overlay.nix";
    app = let
        # Define custom JRE 👇
        jre = pkgs.jre_minimal.override {
            modules = [
                "java.base"
                "java.desktop"
                "java.logging"
                "java.management"
                "java.naming"
                "java.security.jgss"
                "java.security.sasl"
                "java.sql"
                "java.transaction.xa"
                "java.xml"
                "jdk.unsupported"
            ];
        };
    in
    sbt-derivation.mkSbtDerivation.${system} {
        # ...

        installPhase = ''
        mkdir -p $out/bin
        mkdir -p $out/share/java

        cp src/app/target/scala-3.*/*.jar $out/share/java

        # Use custom JRE 👇
        makeWrapper ${jre}/bin/java $out/bin/scala-app \
            --add-flags "-cp \"$out/share/java/*\" org.app.Application"
        '';
    };
    in 
    # ...

Let's build:

aiono ❯ nix-build
aiono ❯ cat result | docker load
aiono ❯ docker images
REPOSITORY                        TAG                               IMAGE ID      CREATED        SIZE
localhost/app-container           latest                            54a30dcb4708  55 years ago   596 MB

Got a bit bigger, but hopefully at least it runs:

aiono ❯ docker run --expose 4041 --network host localhost/app-container:latest
Server is listening at '/127.0.0.1:4041'

Yes! It successfully runs now.

While we made some progress, still it's far away from an appropriate size. The bulk of the size still comes from the JRE.

So I kept reading around, I noticed that I didn't notice an important part of the jre_minimal derivation. While I optimized the modules we need, I didn't pick an appropriate JDK. We can override the jdk attribute of the derivation for that.

let
    repository = builtins.fetchTarball {
        url = "https://github.com/zaninime/sbt-derivation/archive/master.tar.gz";
    };
    sbt-derivation = import "${repository}/overlay.nix";
    app = let
        jre = pkgs.jre_minimal.override {
            modules = [
                "java.base"
                "java.desktop"
                "java.logging"
                "java.management"
                "java.naming"
                "java.security.jgss"
                "java.security.sasl"
                "java.sql"
                "java.transaction.xa"
                "java.xml"jdk to J
                "jdk.unsupported"
            ];
            # Set JDK to headless 👇
            jdk = pkgs.jdk21_headless;
        };
    in
    ...

Let's build our image again:

aiono ❯ nix-build
aiono ❯ cat result | docker load
aiono ❯ docker images
REPOSITORY                        TAG                               IMAGE ID      CREATED        SIZE
localhost/app-container           latest                            ed070c56e715  55 years ago   239 MB

239 MB! That seems promising. Let's run and hopefully it doesn't crash:

aiono ❯ docker run --expose 4041 --network host localhost/app-container:latest
Server is listening at '/127.0.0.1:4041'

Great! We have come a long way from 722 MB to 239 MB.

dockerTools.copyToRoot Gotchas

I wrote before that the application JAR is duplicated. It appears both under /share and /nix/store paths in the file system of the container. Let's look into how we defined our container image:

let
    # ...
    app-container = pkgs.dockerTools.buildImage {
        name = "app-container";
        tag = "latest";

        # What does it do 🤔
        copyToRoot = [ app pkgs.busybox ];

        config = { Cmd = [ "/bin/${app.pname}" ]; };
    };
in
    # ...

We duplicated the JAR because we tell Nix to copy the contents of the packages given in copyToRoot to the root of the container image. What we actually want to do is to put symlinks to the root that point to /nix/store because everything we need is already there.

The following change fixes the problem:

let
    # ...
    app-container = pkgs.dockerTools.buildImage {
        name = "app-container";
        tag = "latest";

        # Use buildEnv 👇
        copyToRoot = pkgs.buildEnv {
            name = "image-root";
            paths = [ app pkgs.busybox ];
            pathsToLink = [ "/bin" ];
        };

        config = { Cmd = [ "/bin/${app.pname}" ]; };
    };
in
    # ...

There are two changes we made here:

1. We wrapped the packages with pkgs.buildEnv which allows us to generate symlinks to /nix/store via the pathsToLink attribute.
2. We only included /bin in pathsToLink so everything else (such as /share) won't be put to the root of the image from the packages.

For some reason, pkgs.buildEnv is heavily underdocumented. The best documentation I could find was here which doesn't even exclusively talk about buildEnv. But essentially it's a simpler version of mkShell. Using it we can create an environment with the packages we want. In our case the important part is that it allows us to generate symlinks to the actual content in the /nix/store.

Again, let's build the image to see its size:

aiono ❯ nix-build
aiono ❯ cat result | docker load
aiono ❯ docker images
REPOSITORY                        TAG                               IMAGE ID      CREATED        SIZE
localhost/app-container           latest                            5cfef9f22c2a  55 years ago   198 MB

We got down to 198 MB from 239 MB.

Comparison with other approaches

After I had something I considered acceptable, I wanted to compare it with other approaches. By following this article I was able to build an image with size of 123 MB, which is better than 198 MB but I think it's not that bad. Also, with this approach the filesystem is a lot more cluttered and there are many unwanted binaries lying in /bin. Apart from the size these can cause complications. But this approach shows that there are still things I could possibly improve.

Compared to other articles like https://zendesk.engineering/using-nix-to-develop-and-package-a-scala-project-cadccd56ad06 (568 MB) and https://dev.to/fialhorenato/how-to-create-slim-docker-java-images-using-a-minimal-jre-3a20 (349 MB) this approach leads to much smaller images.

Final derivation

In the end, we have the following derivation:

    let 
    repository = builtins.fetchTarball {
        url = "https://github.com/zaninime/sbt-derivation/archive/master.tar.gz";
    };
    sbt-derivation = import "${repository}/overlay.nix";
    app = let
        jre = pkgs.jre_minimal.override {
            # NOTE: What you need to put here depends on your application dependencies
            modules = [
                "java.base"
                "java.desktop"
                "java.logging"
                "java.management"
                "java.naming"
                "java.security.jgss"
                "java.security.sasl"
                "java.sql"
                "java.transaction.xa"
                "java.xml"
                "jdk.unsupported"
                # These modules are necessary for establishing SSL connections.
                # Otherwise I get "javax.net.ssl.SSLHandshakeException: Received fatal alert: insufficient_security"
                "jdk.crypto.ec"
                "jdk.crypto.cryptoki"
            ];
            jdk = pkgs.jdk21_headless;
        }; in 
        sbt-derivation.mkSbtDerivation.${system} {
            pname = "app";
            version = "0.0.1";
            src = ./.;
            depsSha256 = "sha256-06Qog8DyDgisnBhUQ9wW46WqqnhGXlakI1DSuFHkriQ=";

            buildInputs = with pkgs; [ makeWrapper ];

            buildPhase = "sbt assembly";

            installPhase = ''
            mkdir -p $out/bin
            mkdir -p $out/share/java

            cp src/app/target/scala-3.*/*.jar $out/share/java

            makeWrapper ${jre}/bin/java $out/bin/scala-app \
                --set JAVA_HOME ${jre} \
                --add-flags "-cp \"$out/share/java/*\" org.app.Application"
            '';
        };
    app-container = pkgs.dockerTools.buildImage {
        name = "app-container";
        tag = "latest";

        copyToRoot = pkgs.buildEnv {
            name = "image-root";
            paths = [ app pkgs.busybox ];
            pathsToLink = [ "/bin" ];
        };

        config = { Cmd = [ "/bin/${app.pname}" ]; };
    }; in
    app-container

Conclusion

In conclusion, I was able to reduce the container size from 722 MB to 198 MB with the changes I mentioned. Thanks to Nix, creating a minimal image is really convenient because the build system does the most of the heavy lifting to figure out the necessary packages. Java also has very good tooling to create a minimal JRE, just enough for the application to run. I believe there is still room for improvement to reduce the size, but it is already good enough for my use case.

With modern tools and workflows we easily forget how much waste we produce because most of the time it's not noticeable unless you are looking for it. Some of the waste makes sense, memory and CPU are not the only resources we have, developer time and time to implement new changes are also very valuable resources which a lot of the times more important than hardware resources. But still I think it's worthwhile to spend some time for reducing the waste and inefficiency in our software. These times are opportunities to learn new things, and also it can be helpful for other resources along with hardware efficiency.

Strangely, mainstream languages still suck at providing tools for good error handling. The main issues I see are:

• Not differentiating between bugs and recoverable errors (more on that later).
• Increasing the cognitive load more than necessary. It's caused by not leveraging type system for error handling.
• Poor composability of functions that can raise an error. Especially when you want to chain multiple functions that return different set of errors. This is usually because type system is too restrictive.

In this article series, I will try to describe what "error" really means in programming context. Then I will go about mainstream approaches to error handling, argue about their strengths and weaknesses. I won't say anything novel or groundbreaking. I don't have answers on the best error handling approach. It will be more like documentation of what we know about error handling. It's also to help myself to organize my thoughts about error handling.

Bugs and Recoverable Errors

When we say "error", we actually possibly mean one of the two things:

1. A bug in the system.
2. A faulty situation that can't be avoided.

These two things are fundamentally different. However, many programming languages don't make a clear differentiation between the two when they are designing their error model. This causes complications because they are very different in nature. When one tries to deal with two very different things with the same tools, the tool becomes unnecessarily complex. Instead, it would be better to build two separate tools that solve each of them well.

Bugs cause your system to go into an unanticipated state. Because you didn't actually think that this case would happen in reality and your whole design is based on that assumption. Naturally, this means that all your previous assumptions are not true anymore. Invariants may be violated or state may be corrupted.

A recoverable error, on the other hand, are the things that may happen, and usually it's outside the control of the system. The system has to interact with the outside world and outside world is a lot of the times unpredictable. Therefore, the system should have a way to handle these errors. A download manage should retry when a network error occurs, a text editor should not crash if it fails to save.

If the system continues to operate in the face of a bug, it will likely to start behaving in weird ways. There is no proper way to "handle" a bug other than immediately stopping and reporting it. That's why "did you turn it on and off again?" is such a popular thing with computer. By restarting a system, we reset the state and it goes back to a case which doesn't break our assumptions about the system. We didn't actually solve the issue, it's still possible to go into the undesired state.

But you can be saying: "If I kill my application every time there was a division by zero or null pointer dereference, it would restart every second". I don't imply that you should restart all your system when a bug occurs. But you should reset all the affected components. If two threads share a memory region and one encounters a bug, the second is also potentially buggy. You need to reset both. We have problems with restarting only because we can't easily restart a granular part of a system. If components are properly isolated, restarting a process in the face of a bug doesn't bring down the whole system, which prevents cascading failures in the downstream. You end up with a more reliable system. Also, one of the issues with just continuing in the face of a bug, it makes it easier not to fix the bug than to fix the bug. This leads to a pit of despair where you ironically end up with a less reliable system that always runs but not it's not certain that it's actually in a well-defined state.

I believe Java especially made significant harms into the understanding of error handling because they don't clearly separate bugs and recoverable errors. A NullPointerException is handled the same way an IOException is handled. This blurs the line and makes it harder to notice the fundamental differences. Also, Java doesn't provide a functionality like Rust's unwrap to ignore error cases for dirty hacking. Which makes people to hate checked exceptions.

When we try to deal with both bugs and recoverable errors in the same way, error handling sucks more than necessary.

The Philosophy of Error Handling

As far as I know, there are two main philosophical approaches to error handling. First, one acknowledges that error handling is too hard and complex to manage it in a type system. Therefore, they either use special error values or runtime exceptions. There are further divisions in this camp (like Go's approach vs. unchecked exception approach) but I won't go into detail about them. All of those subcamps has the same belief that it's not worth encoding errors into the types.

The other camp believes that error handling is complex, but it can be somewhat tracked in the type system even if it's not possible for every case. They think that many trivial errors (like famous NullPointerException) could be prevented with encoding more information into type system. Examples to this camp are Rust, OCaml and Haskell. Scala is also in this camp but it's possible to code in all possible ways with Scala.

Both camps have their advantages and shortcomings. First approach is good when you want to focus on the happy path and reliability is not that important. Many times we want to write a hacky prototype before we actually want to write a proper system. We can save a lot of time by just throwing the ball (such as terminating the program or whatever appropriate unit of execution) when a failure case occurs. But when it comes to seriously building a system, it shouldn't be hard to become stricter with error handling. It should be easy to spot where we are not dealing with a possible error so that we can build reliable and robust systems. That's why I especially find Rust's approach really good. Because if you are doing hacky prototype, you can just unwrap errors and let the program panic if an error happens. When you return, you can rewrite your code to handle these errors. It's very easy to figure out where you should look. Compared to this if you use Java for instance, any function can throw a runtime exception and there is no way of telling it from the signature. In order to be sure you have to read the whole implementation of the function. This is terrible because it causes unnecessary cognitive load.

Second approach is good that it lets you abstract over failure modes by incorporating into type system. This way you can just look at the signature and not have to read the implementation to see what errors are possible. It provides better abstraction and reduces cognitive load. However, in the way it's currently implemented in programming languages it's usually painful to write. Particularly, it's hard or impossible to compose error cases from multiple functions or narrow cases by partially handling some of the errors. So composability suffers. I will talk about this in the next article when we discuss monadic errors.

Conclusion

We reached the end of the first part in this series. I hope it helped you to understand the purpose of error handling and different approaches to it. In the next article, I will delve on different types of error handling models of mainstream programming languages and some cutting-edge ones. We will learn pros and cons of each approach.

One popular alternative for the traditional Nix derivations is to use flakes. There are even efforts to stabilize them for a long time. However, they are a whole new approach and require some learning for a traditional Nix user. Moreover, they are still experimental so the API is subject to change in the future.

In this post I will show how you can get rid of channels but still use the traditional nix derivations and pin your nixpkgs for your derivations, shells, NixOS configuration and home manager configurations. In the end you will end up with a setting where nixpkgs version is managed via plain text and can easily be updated when desired.

The Problem

Conventional nix shells contain code snippet similar to the following:

let pkgs = import <nixpkgs> {}; in
pkgs.mkShell {
  # ...
}

You may wonder, what does <nixpkgs> mean in this code?. This syntax is called "lookup path"^[1]. When you write a name in angle brackets, it's matched with the corresponding key-value pair in NIX_PATH environment variable. The value is typically a Nix channel.

Nix Channels are essentially URLs that point to a nixpkgs^[2]. Conventionally there are certain channels which are listed here. The exact contents of a channel are updated regularly. So they act like package indices which can be found in other traditional package managers. Having a package index has several benefits. First, they allow conveniently updating all installed packages like one does in traditional package managers. Furthermore, having a global version of a dependency is also beneficial for caching purposes, because packages we use that may depend on the same package depend on the same version, so we don't end up with many versions of the dependency with slight differences.

But of course it's not all good. First problem is, having a global version for every dependency makes it hard if we really want multiple different versions of the same package. For example it's not uncommon that one wants multiple versions of JDK installed at the same time. For this, nixpkgs have conventions that exposes several different major versions (for example JDK has many versions such as jdk8 and jdk17) which solves this issue for many cases but it's still sometimes not enough. Second problem is exact version of the nixpkgs is not specified in the Nix derivation. If someone tries to build your Nix Derivation couple years later it may not build because the channel is updated with breaking changes. This is a really bad UX, because a channel url says nothing about actual version of nixpkgs being returned. For example, if NIX_PATH environment variable is set to nixpkgs-unstable=nixos-24.05, <nixpkgs-unstable> will refer to the NixOS 24.05 stable branch! This can be very unintuitive. Or worse, many use <nixpkgs> channel for their default channel but some set it to a stable and others to an unstable channel. Reader has no idea which version <nixpkgs> is meant to refer. Also, the exact contents of the channel url changes over time which means that the derivation may get broken in the future.

We can't really fix the first problem with the traditional Nix. I believe that it's an inherent trade-off between space usage and preciseness. But fortunately we can solve the second problem. Therefore ensuring reproducibility and improving the UX.

In order to fix this issue, we have the following options:

1. Don't use <nixpkgs> expressions in the code.
2. Keep <nixpkgs> but change NIX_PATH variable to refer to a specific version of nixpkgs instead of a channel.

We will use both options depending on the use case. But first we need to introduce a new tool.

First Attempt at a Solution

As I have described above, the problematic line is:

let pkgs = import <nixpkgs> {}; in

We already know that <nixpkgs> is supposed return a version of nixpkgs. So one simple solution could be to download a specific commit of nixpkgs instead of using channels via lookup paths. Is this possible?

Yes, fortunately it is possible. The nixpkgs repository is hosted at GitHub. GitHub has a nice feature that allowing downloading the source archive of any commit. Nix has a builtin called fetchTarball which, as the name suggests, downloads the tarball and returns it's Nix store path. With this knowledge, we can instead write:

let pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/$COMMIT_HASH.tar.gz") {}; in

This solves the reproducibility issue. So can we know stop and be happy?

Unfortunately not, we have achieved perfect reproducibility. However, how do we update nixpkgs version if we want to? Our current option is to go to nixpkgs repository and pick the latest commit then copy-paste it. But if we have a lot of shell configurations this can easily get very tedious. Can we automate the process a bit?

Well we can. Enter npins.

Npins

Npins is a tool that allows "pinning" a specific commit of the nixpkgs in nix derivations. The version is stored in a text file, therefore you can easily add it to version control. It also lets you conveniently update the version when you want, no manual text editing is required. It's available in nixpkgs.

Once you have it installed, you need to initialize it in the directory you want to use:

npins init --bare

This will create npins subdirectory on the current directory. Initially there are no pinned nixpkgs and it needs to be added with another command.

Adding nixpkgs can be done with:

npins add github nixos $NIXPKGS_NAME --branch $NIXPKGS_BRANCH

Where $NIXPKGS_BRANCH can be a Nix Channel name. $NIXPKGS_NAME is the name of nixpkgs. This is necessary because npins lets you pin multiple nixpkgs in the same repository.

After having nixpkgs pinned, it can be used in nix derivations as following:

{
  system ? builtins.currentSystem,
  sources ? import ./npins,
}:
let
  pkgs = import sources.nixpkgs { inherit system; };
in
...

sources contains the pinned nixpkgs, the name you gave above becomes an attribute in sources to access. So if you have the name foo, you would get nixpks by import sources.foo {}.

Packaging & Shell

As shown above, nix shell configurations utilize <nixpkgs> syntax, which is the main deal breaker for reproducibility. Therefore the solution is to import nixpkgs from sources provided via npins.

I use the following template:

• nix/shell.nix : Contains the actual shell configuration which should be built with callPackage. Example:

{
  mkShell,
  # Other dependencies...
}:

mkShell {
  # Shell configuration...
}

• shell.nix : Calls nix/shell.nix with the pinned nixpkgs. For example if we have nixpkgs with name nixpkgs:

{
  system ? builtins.currentSystem,
  sources ? import ./npins,
}:
let
  pkgs = import sources.nixpkgs { inherit system; };
in
pkgs.callPackage ./nix/shell.nix {}

Bonus: direnv

For convenience I use direnv to enter nix-shell. It's convenient because it automatically enters into the environment and it's for some reason faster than calling nix-shell directly.

With direnv installed, I have the following .envrc file:

use nix

Which is all we need.

NixOS configuration

It's harder to pin nixpkgs for NixOS configurations, because NixOS configurations implicitly depend on <nixpkgs/nixos>, and because it's a lookup path, it requires NIX_PATH environment variable to point to nixpkgs. It kind of creates a loop if you want to declare NIX_PATH inside configuration.nix, because in order to interpret configuration.nix you first need to determine the location of nixpkgs which is only available after NIX_PATH is set. So this way of managing requires to run nixos-rebuild twice to actually take effect. I think this is not a good UX. Fortunately, we can write a script that passes the appropriate NIX_PATH to nixos-rebuild. In order to prevent incorrect usage, NIX_PATH shouldn't be empty by default.

I use the following Nu Shell script for this:

def build-nixos-configuration [
  device_path: string, # Path for the system configuration. Must contain a 'configuration.nix' and an 'npins' directory.
  command: string = "switch", # Main command for 'nixos-rebuild'. 'switch' or 'dry-run'
  ...extra_args: string, # Passed to 'nixos-rebuild'
]: nothing -> nothing {
  let abs_device_path = ($device_path | path expand --strict);

  let npins_path = ($abs_device_path | path join npins default.nix);
  let nixpkgs_pin = run-external "nix" "eval" "--raw" "-f" $npins_path "nixpkgs";

  let configuration_path = ($abs_device_path | path join configuration.nix);

  let nix_path = $"nixpkgs=($nixpkgs_pin):nixos-config=($configuration_path)";
  with-env {
    NIX_PATH: $nix_path,
  } {
    # For some reason '--preserve-env=NIX_PATH' doesn't pass the env variable.
    sudo "--preserve-env" "-u" $"(whoami)" "nixos-rebuild" $command "--fast" ...$extra_args
  }
}

It may seem complicated, but the essential part is very simple:

let nixpkgs_pin = run-external "nix" "eval" "--raw" "-f" $npins_path "nixpkgs";
let nix_path = $"nixpkgs=($nixpkgs_pin):nixos-config=($configuration_path)";
with-env {
  NIX_PATH: $nix_path,
} {
  sudo "--preserve-env" "-u" $"(whoami)" "nixos-rebuild" $command "--fast" ...$extra_args
}

1. First line evaluates the nixpkgs and returns a Nix Store path.
2. Second line creates the appropriate NIX_PATH env variables. nixpkgs is a path to nixpkgs and nixos-config is the path to configuration.nix.
3. Sixth line calls nixos-rebuild with appropriate arguments.

The same part can be written in bash as (disclaimer: I didn't test it):

NIXPKGS_PIN=$(nix eval --raw -f $NPINS_PATH nixpkgs)
NIX_PATH="nixpkgs=$NIXPKGS_PIN:nixos-config=$CONFIGURATION_PATH"
sudo --preserve-env -u "$(whoami)" nixos-rebuild $command --fast $@

With a script like this, one can pin nixpkgs for their system configuration.

Home Manager

If you use Home Manager the approach is very close to the system configuration. It's essentially the same, except in NIX_PATH you don't need to set nixos-config but you need home-manager:

NIXPKGS_PIN=$(nix eval --raw -f $NPINS_PATH nixpkgs)
HOME_MANAGER_PIN=$(nix eval --raw -f $NPINS_PATH home-manager)
NIX_PATH="nixpkgs=$NIXPKGS_PIN:home-manager=$HOME_MANAGER_PIN"
home-manager $command -f $HOME_MANAGER_PATH

Conlusion

If you have come this far, thank you for giving your time. I believe that traditional Nix does many things right, but the way nixpkgs is managed really needs to change. With pinning nixpkgs using npins you can improve this one specific issue.

Credits: This post is heavily inspired by https://jade.fyi/blog/pinning-nixos-with-npins/. If you want more deep dive explanation on the same topic I would recommend it.

For a while, I wanted to start blogging about programming, and writing my own blog engine seemed like a good idea to keep it interesting. While keeping me interested in working as intended, I think I could have published my first post much earlier if I used an existing blog engine. But it's like scripting, doing a task manually sometimes shorter than writing a script for it, but programmers still choose scripting. Also, I like the idea of being familiar with every stack of my projects. Nowadays, it's rare to work without frameworks or libraries that abstract over the basic primitives (not that this is a bad thing), especially in the web development setting. I thought it would be interesting if I learned web frontend fundamentals from scratch. Thanks to Uğur for helping me with HTML/CSS.

If you would like to check out the source code, the repository is here.

Why OCaml?

I am aware that there are a lot of blog posts about writing a blog engine, but I didn't see anyone using OCaml. I chose OCaml because it seems close to the ideal language in my mind. I really like Rust, and OCaml is similar to Rust in many aspects such as having good support for functional programming while allowing to escape into imperative style when necessary. But OCaml has a garbage collector instead of lifetime analysis so it's more convenient to use if you don't need to control memory management. And it has some interesting features like modules, GADTs and polymorphic variants. However, I miss the guarantees provided by the ownership system. I had some bugs while working on this project that would be caught by the borrow checker if it existed. Promisingly, there is an ongoing work to implement some sort of borrow checking for OCaml.

Another good thing about OCaml is that its similar to Go in the sense that it compiles fast and has a very minimal runtime. That makes iterations very quick, and also deployment simple since it just requires a single binary. Furthermore, while it produces very efficient binary executables it still feels like a scripting language thanks to it's type inference. I could talk about OCaml's features more in detail, but this post is not about that so I will save this to a future article. I wanted to try the language in a realistic setting to see how this language works in practice.

Project Structure

The project has two main folders:

• content: Blog content. Page templates and blog posts.
• site-generator: OCaml program that generates the website.

content folder contains three subfolders:

• templates: HTML templates for components and pages.
• pages: The content for pages such as 'about me' and blog posts. For each post, there is a .json file (metadata) and a .md (content) with the same name before the extension.
• css: As the name implies this contains the css files.

The static site generator generates a static HTML website. Basically, it takes each post's content in markdown form and converts it to HTML. Then it instantiates the blog post template with the post content.

Tech Stack

I use the following tech stack:

• For the build system I chose dune which is the de-facto build system for OCaml.
• Instead of the default standard library, I use Core because it contains more functionality and it was used in Real World OCaml book that I read.
• For HTML manipulation I use Lambda soup library.
• The markdown files are converted to HTML using omd.
• The post metadata is stored in json files, to parse them I use yojson. Though I would prefer to have them as YAML Front Matter, I couldn't find a library for it and didn't want to spend time implementing myself. Maybe in the future, I can work on that.
• CLI interface is implemented using core_unix.

Unfortunately, while OCaml ecosystem is active it's worse than mainstream languages in terms of library support. You may be disappointed if you expect to find a library for everything.

Code Structure

The project is mainly organized by Modules.

• main: Programs entry point.
• DiskIO: Wraps the disk related functionality so the underlying IO library can be changed easily. All actual IO functionality is constrained here.
• SiteGenerator: Reads the content and generates the website files but doesn't actually write them.
• SiteDirectory: Writes generated website files into the disk.

Templating

The templating functionality is very simple, it basically finds the appropriate element with the element id and then replaces it with the actual content. For example, in posts page:

<main class="container">
    <!-- ... -->
    <div id="blog-content"></p>
</main>

The blog-content is substituted with actual content with the following code:

let page =
    DiskIO.read_all
        (Path.join content_path (Path.from_parts [ "templates"; "post.html" ]))
    |> Soup.parse
in
Soup.replace (page $ "#blog-content") post_component;

Notice that Soup.replace API has side effects, it doesn't return the modified page but updates the target in place. The unexpected thing was, it also mutates the component that is substituted as well, leaving it empty after the operation. I was expecting that the second argument left unmodified. It's a good example why borrow checking is useful, if OCaml had borrow checking I would know that the second argument is mutated by looking at the signature and didn't have this surprise. An immutable API would also prevent such mistakes.

Modules

OCaml has a concept called modules which can be used as a substitute for interfaces in other languages. I find the module system in general better than classic OO-style interfaces. One reason is that a module can have multiple related types defined together and not necessarily tied into a single type. Though for this project, there were no cases where I really needed a module. All of my modules signatures in the project resembles interfaces.

Conclusion

In short, I liked my experience with OCaml though since this project is very simple it wouldn't matter if I used any other reasonable language. Unfortunately, some libraries are not well maintained and lack documentation but tooling is very straightforward and easy to use. But it's very much an alive ecosystem with a lot of efforts to improve the language.