DEV Community: Mathieu Kerjouan

Sandbox#1: Flutter Application Design First Steps

Mathieu Kerjouan — Fri, 12 Jun 2026 09:00:00 +0000

Epic things start with small humble steps. Pay respect to your beginnings. And if you're just starting out, know that it's OK to be sucky. To be small. To be messy and chaotic. Just make sure to never ever stop dreaming.

-- Vishen Lakhiani

Let start another chapter of this journey with Dart by creating a mobile application with Flutter. For this post, a really simple application will be created called sandbox. Instead of adding some interactive part, like sending/receiving data from a backend, let simply design an application based on a wireframe.

Bootstrapping

As usual, I'm using asdf to install Flutter on my laptop but it can also be installed manually by following the Flutter Quick Install documentation. This new project will be called sandbox, a good name for a draft.

$ flutter create sandbox
Creating project sandbox...
Resolving dependencies in `sandbox`... 
Downloading packages... 
Got dependencies in `sandbox`.
Wrote 131 files.

All done!
You can find general documentation for Flutter at: https://docs.flutter.dev/
Detailed API documentation is available at: https://api.flutter.dev/
If you prefer video documentation, consider: https://www.youtube.com/c/flutterdev

In order to run your application, type:

  $ cd sandbox
  $ flutter run

Your application code is in sandbox/lib/main.dart.

$ cd sandbox

Wireframe and Prototype

My career is from network and system administration, backend and distributed development, when it comes to design something, I'm thinking like a technician/engineer: I don't care about the look, it should work. In a previous publication, rock-paper-scissors data structure and primitive have been designed, why not starting with a kind of interface for this game?

Creating a prototype or a wireframe with Figma is painful. Really. I still don't believe such kind of "application" can be so successful. Anyway, after a long fight, and without any idea how to expert a layer correctly, I finally decided to do a screenshot of the page. Yeah. Ridiculous. If you are a developer at Figma, are you really using your software? I mean, exporting a selected area can be done quite easily with draw.io.

Anyway, the goal here is to reproduce this with Flutter. No need for interactive feature, just a raw prototype.

First Version

Someone said "start humble", this is the first version, with lot of duplicated code an crappy colors, but it should give the big picture of the application.

The top bar will be used for the menu, to switch to another mode or game for example. It contains the title of the current page. At this time, it will do nothing.

Then comes the opponent container. This part will be empty at first, but in the future, it could be an animated area, where the final shape of the opponent will be loaded.

The third container will contain the final result, when both players selected the shape, and the result should be displayed. If this application is used also by someone else (remotely), one player can see "loss", while the other one will see "win". If the shapes are the same, both players will see "draw".

The fourth container is where the player will select the action. Three shapes are available, rock, paper and scissors. When tapping on one of them, it will send it to a remote server (if playing against someone else), or simply update the state of the application (if playing against the machine).

Finally, the last container is the bottom bar. It will be removed in the second version because I think an user can click by mistake on one of the button instead of selecting one shape. Let begins the implementation. Nothing really fancy at first.

import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

The interesting part is present in MyApp() class where we are defining the different layer of the application.

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      home: Scaffold(
        appBar: AppBar(
          leading: IconButton(onPressed: () {}, icon: Icon(Icons.menu)),
          title: Text("Jan Ken Pon"),
        ),
        body: Column(
          children: <Widget>[
            Expanded(
              child: Center(
                child: InkWell(
                  onTap: () {},
                  child: Ink(
                    height: double.infinity,
                    width: double.infinity,
                    color: Colors.grey,
                    child: Center(child: Text("opponent choice")),
                  ),
                ),
              ),
            ),
            Expanded(
              child: Center(
                child: InkWell(
                  onTap: () {},
                  child: Ink(
                    height: double.infinity,
                    width: double.infinity,
                    color: Colors.amber,
                    child: Center(child: Text("result")),
                  ),
                ),
              ),
            ),
            Expanded(
              child: Center(
                child: Row(
                  children: <Widget>[
                    Expanded(
                      child: InkWell(
                        onTap: () {},
                        child: Ink(
                          height: double.infinity,
                          width: double.infinity,
                          color: Colors.blue,
                          child: Center(child: Text("rock")),
                        ),
                      ),
                    ),
                    Expanded(
                      child: InkWell(
                        onTap: () {},
                        child: Ink(
                          height: double.infinity,
                          width: double.infinity,
                          color: Colors.green,
                          child: Center(child: Text("paper")),
                        ),
                      ),
                    ),
                    Expanded(
                      child: InkWell(
                        onTap: () {},
                        child: Ink(
                          height: double.infinity,
                          width: double.infinity,
                          color: Colors.red,
                          child: Center(child: Text("scissors")),
                        ),
                      ),
                    ),
                  ],
                ),
              ),
            ),
          ],
        ),
        bottomNavigationBar: BottomNavigationBar(
          items: [
            BottomNavigationBarItem(icon: Icon(Icons.star), label: "Home"),
            BottomNavigationBarItem(
              icon: Icon(Icons.star),
              label: "Jan Ken Pon",
            ),
          ],
        ),
      ),
    );
  }
}

I know, this is a disgusting piece of code. The level of indentation is insane and the duplicated code is crazy, but at least, it works. What kind of classes I used here?

Scaffold class is used to configure the visual layout.
AppBar() class is instantiated in the Scaffold object (appBar attribute) and configure the top bar of the application. The menu button on the left currently don't work. The title is a simple Text() object;

AppBar(
  leading: IconButton(
    // ...
  ),
  title: Text(
    // ...
  ),
 )

BottomNavigationBar is also instantiated in Scaffold in the bottomNavigationBar attribute. This object is also made of a list of Widgets defined in the items attribute. At least 2 items must be created, in our case, two BottomNavigationBarItem are created;

BottomNavigationBar(
  items: [
   BottomNavigationBarItem(
     // ...
   ),
   BottomNavigationBarItem(
     // ...
   ),
  ]
)

Column class is used in the body attribute of the Scaffold object. This is where the user will be able to see the actions and play with the application. A list of Widget can be provided using the children attributes, each one will divide the available space. So, in our case, we need 3 "lines", one for the opponent, one for the result and the last one for the user selection;

Column(
  children: <Widget>[
    // ...
  ]
)

Expanded class is used on every "line" to use all the space available from each line;

Expanded(
  child: Center(
    // ...
  )
)

Center is then used to vertically and horizontally center all elements;

Center(
  child: InkWell(
    // ...
  )
)

InkWell classes are then used to define a place that can react to user touch, a bit like a button, but with more flexibility;

InkWell(
  onTap: () {},
  child: Ink(
    // ...
  ),
)

Ink classes are finally used to set the height, width and color of each active elements;

Ink(
  height: double.infinity,
  width: double.infinity,
  color: Colors.amber,
  child: Center(
    // ...
  ),
)

Row is also used for the shapes user layer, where the user can select rock, paper or scissors. The goal of this class is to split the available space in rows.

Row(
  children: <Widget>[
    // ...
  ]
)

Conclusion

This application can be compiled and installed on the Android emulator. Here a screenshot of this first application draft from Android (API 36.0).

The colors have been set simply to see where the important information will be displayed. The same colors will stay there until we have something functional.

With this first version, we also have an idea of the essential bricks we can reuse in the future. It means the next iteration will remove some part of this design, create reusable functions and likely add a bit of interactivity.

Have fun!

Cover Image by Arseny Togulev on Unsplash

Encoding and Decoding JSON in Dart

Mathieu Kerjouan — Thu, 11 Jun 2026 08:00:00 +0000

Is it really necessary to introduce JSON in 2026? Any developers had to deal with JSON at least one time in his career. Anyway, JSON (JavaScript Object Notation) is an open standard format designed for web development usage. In fine, it became one of the most used data format.

Before working on more challengin but interesting serializer like CBOR or Protocol Buffer, let take a moment to learn how use JSON in Dart.

import 'dart:convert';

When one needs to encode or decode JSON, two ways existing, using the JsonCodec() class or use the specific class for encoding (JsonEncoder()) or for decoding (JsonDecoder()). In both case, the result will be the same.

Encoding

JSON encoder is directly integrated in the Dart SDK, and can be included in your code by simply importing dart:convert package.

import 'dart:convert';

Let create a first function called encode() to encode any kind of object using the json.encode() interface.

void encode(Object data, {String label = ""}) {
  print("-- ${label}:");
  var encoded = json.encode(data);
  print(encoded);
  print("");
}

Now, let create another function called encode2(). This one will instantiate an object from the JsonEncoder() class.

void encode2(Object data, {String label = ""}) {
  var encoder = JsonEncoder();
  print("-- ${label}:");
  var encoded = encoder.convert(data);
  print(encoded);
  print("");
}

Great, we have two ways to encode our objects, the main entry-point is still missing though. Let fix that.

void main() {
  print("== encode with JsonCodec");
  encode(1, label: "integer(1)");
  encode("test", label: "string(test)");
  encode([], label: "list()");
  encode([1,2,3], label: "list(1,2,3)");
  encode({}, label: "map()");
  encode({"a": 1}, label: "map(a, 1)");
  encode(0.001, label: "float(0.001)");
  encode(true, label: "bool(true)");
  encode(false, label: "bool(false)");

  print("encode with JsonEncoder");
  encode2(1, label: "integer(1)");
  encode2("test", label: "string(test)");
  encode2([], label: "list()");
  encode2([1,2,3], label: "list(1,2,3)");
  encode2({}, label: "map()");
  encode2({"a": 1}, label: "map(a, 1)");
  encode2(0.001, label: "float(0.001)");
  encode2(true, label: "bool(true)");
  encode2(false, label: "bool(false)");
}

The time has come to execute this program and see the result.

$ dart run bin/encode.dart
== encode with JsonCodec
-- integer(1):
1

-- string(test):
"test"

-- list():
[]

-- list(1,2,3):
[1,2,3]

-- map():
{}

-- map(a, 1):
{"a":1}

-- float(0.001):
0.001

-- bool(true):
true

-- bool(false):
false

encode with JsonEncoder
-- integer(1):
1

-- string(test):
"test"

-- list():
[]

-- list(1,2,3):
[1,2,3]

-- map():
{}

-- map(a, 1):
{"a":1}

-- float(0.001):
0.001

-- bool(true):
true

-- bool(false):
false

It looks okay, the main Dart types are supported, but what will happen if we give an unsupported type to the encoder?

void main() {
  json.encode(Object());
}

The code is simple, we pass a raw Object() to json.encode().

$ dart bin/encode_exception.dart
Uncaught Error, error: Error: Converting object to an encodable object failed: Instance of 'Object'

Doh, it produces an error! In fact, this is normal, the JSON encoder does not know how to deal with such objects. JSON only support a subset of all Dart type, so, in this case, we need to find a way to convert (serialize) similar objects to something compatible with JSON. In most of the case, it will be converted as String(), perhaps using Base64 or something similar.

To illustrate that, let create a new class called Tuple, it will contain two public attributes, a left and a right one. Both are String(). To represent this kind of object in JSON we can easily use a Map containing at least two fields, one for the left and one of the right. Adding a method called toJson() here will help us.

class Tuple {
  String left = "";
  String right = "";
  Tuple(this.left, this.right);
  Map<String, String> toJson() => {
    "_object": "Tuple",
    "left": left,
    "right": right
  };
}

The JSON encoder needs a way to know how to convert this new object, it can be done by creating a simple function like the following one. The idea is to check the type of the object passed as argument and to return another object compatible with the JSON format.

Function(dynamic) toEncodable() {
  return (o) {
    switch (o) {
      case Tuple(): return o.toJson();
      case Object(): return o.toString();
    }
  };
}

The toEncodable() function can be passed to the JsonCodec constructor via the toEncodable attribute. The rest is pure testing.

void main() {
  var encoder = JsonCodec(toEncodable: toEncodable());
  var encoded = encoder.encode([
    1,
    "test",
    Object(),
    Tuple("Left1", "Right1")
  ]);
  print(encoded);
}

Let execute the code and check the result.

$ dart bin/encode_encable.dart
[1,"test","Instance of 'Object'",{"_object":"Tuple","left":"Left1","right":"Right1"}]

Our object is correctly converted to a JSON map containing a left and right field. Regarding the raw object, we have now a string containing "Instance of 'Object'", that's the direct result of the toString() method.

Last trick, it is also possible to encode a JSON using indentation via the JsonEncoder.withIndent() constructor.

import 'dart:convert';

void main() {
  print(JsonEncoder
    .withIndent(" ")
    .convert(
      {"test": [1,2,3]}
    )
  );
}

Let execute our code, the output should be a JSON with indentation.

$ dart bin/encode_indent.dart
{
 "test": [
  1,
  2,
  3
 ]
}

That's right! It works! Next step, decoding JSON.

Decoding

Decoding a JSON String is similar than encoding Dart objects, one can use JsonCodec or create a JsonDecoder object, the result will be the same.

void main() {
  print(
    json.decode(
      '{"test": 1}'
    )
  );

  print(
    JsonDecoder()
    .convert(
      '{"test": 1}'
    )
  );
}

Let execute this code.

$ dart run bin/decode.dart
{test: 1}
{test: 1}

Without surprise, it returns a Map(), but, what if we want to return a specific Object instead? Let take our Tuple class back from the Encoding section.

class Tuple {
  String left = "";
  String right = "";
  Tuple(this.left, this.right);
  Map<String, String> toJson() => {
    "_object": "Tuple",
    "left": left,
    "right": right
  };
}

The JsonDecoder class can accept a reviver() function passed as parameter and can be used for this kind of situation. When some data looks like it's a specific object, the reviver() function will be able to return the correct instantiated object. Here an example:

Object? Function (Object? key, Object? value)? reviver() {
  return (key, value) {
    print("--> key: $key");
    print("--> value: $value");
    switch (value) {
      case {"_object": "tuple"}: 
        var v = value as Map<String,dynamic>;
        return Tuple(v["left"] ?? "", v["right"] ?? "");
      default: return value;
    }
  };
}

The snippet above will check each value returned by the decoder, and if one of these values are matching a specific kind of pattern (in our case if the value is a Map containing a field object containing the string tuple), then it will create the object. Let check that with a new main entry-point.

void main() {
  var toEncode = {
    "1": [{ 
      "test": {
        "data": 2
      }
    }]
  };
  var decoder = JsonDecoder(reviver());
  var x = decoder.convert(
    json.encode(
      toEncode
    )
  );
  print("==> final: $x");
}

Now, we can execute the code and check the output.

$ dart bin/decode_reviver.dart
--> key: data
--> value: 2
--> key: _object
--> value: tuple
--> key: left
--> value: left
--> key: right
--> value: right
--> key: tuple
--> value: {_object: tuple, left: left, right: right}
--> key: test
--> value: {data: 2, tuple: Instance of 'Tuple'}
--> key: 0
--> value: {test: {data: 2, tuple: Instance of 'Tuple'}}
--> key: 1
--> value: [{test: {data: 2, tuple: Instance of 'Tuple'}}]
--> key: null
--> value: {1: [{test: {data: 2, tuple: Instance of 'Tuple'}}]}
==> final: {1: [{test: {data: 2, tuple: Instance of 'Tuple'}}]}

As you can see, the returned value by the decoder includes an instance of a Tuple class. The code is still a bit messy, not enough check, but the idea is there.

Conclusion

This post was a small one, JSON is a simple format, and the interfaces used to encode/decode it are relatively easy to use, at least, for simple use cases. JSON can also be specified using schema or used as serializer, but it will be seen in another publication. As usual, for the ones would like to dive deeper in the subject, here few interesting links for you.

Official JSON Dart Tutorial, where you can see more complex examples;
JsonCodec class, where you will find the complete documentation API for the JsonCodec class;
JsonDecoder class, where you will learn how to use the JsonDecoder class;
JsonEncoder class, where the full description of the JsonEncoder class can be found;
dart:convert JSON source code, where you will find the full documentation of the convert package, containing also the classes for Base64 or UTF8/Unicode;
Passing Data from Dart to JSON for Backend Integration by @avwerosuoghene
Mastering JSON Models in Dart & Flutter: From Basics to Complex Models by Iftekhar Ahmed on Medium
How to Parse JSON in Dart/Flutter by Vikranh Salian on Medium
Mastering JSON Encoding and Decoding in Flutter/Dart: A Comprehensive Guide for API Integration by Bhaveshh Sachala on Medium

Have fun!

Cover Image by Dieter K on Unsplash

Standalone HTTP Server with Relic in Dart

Mathieu Kerjouan — Wed, 10 Jun 2026 08:00:00 +0000

Instead of creating another classic web server displaying some static value, we will create today a local cache management over HTTP using Dart and Relic.

$ dart create -t console-full cache_relic
Creating cache_relic using template console-full...

  .gitignore
  analysis_options.yaml
  CHANGELOG.md
  pubspec.yaml
  README.md
  bin/cache_relic.dart
  lib/cache_relic.dart
  test/cache_relic_test.dart

Running pub get...                     0.5s
  Resolving dependencies...
  Downloading packages...
  Changed 48 dependencies!

Created project cache_relic in cache_relic! In order to get started, run the following commands:

  cd cache_relic
  dart run

$ cd cache_relic

$ dart pub add relic
Resolving dependencies... 
Downloading packages... 
+ relic 1.2.0
+ relic_core 1.2.0
+ relic_io 1.2.0
Changed 3 dependencies!

Cache Server

How to store in-memory data in Dart and how to do it correctly? What kind of solution do we have to "share" a reference to an object containing data? Let review the solution I would have used on Erlang/Elixir:

Creating a gen_server or gen_statem process using a map as main state with at least 3 interfaces, one to push a value, one to get a value and then one to delete a value. One session would be directly associated with a process, under a supervisor using a one_for_one or simple_one_for_one strategy;
Creating a public or protected ETS table managed by a process following the same principle than the previous point (in short, replacing the map with the ETS). Instead of using Erlang messages via gen_server or gen_statem, here we could use the ets interface instead (faster).

Dart is a more complex language, you have in this situation many choices available, and each one should probably tested and profiled before being used. Let try to list them one by one.

Why a cache server? Well, to be, a cache system is the smallest piece of software one can found everywhere. There is a reason why redis, memcached or many other projects like that are used by everybody: developers need a way to store data quick. It could be for a session, for temporary data or simply to avoid annoying the main core database. A cache service is easy to create (key/value store), and can become rapidly something cool to hack. In fact, if you look a bit closely, any web server or database can be seen as a kind of "infinite" cache server, right?

Oh, by the way, all articles published in the French Linux Magazine regarding Erlang were created around a cache system service. Feel free to check them.

Global Variables

A global variable containing an Object like a Map() containing Session() objects. Using global variables are not a good idea, even in Dart, but it's a simple answer and it should work. The big risk here would be the race conditions and other weird behaviors in case of concurrent calls. Here some list to see what we can do with this method. Here a list of few discussion from the web when it comes to use a global variable in Dart:

How to Store Global Variables in Flutter: The Best Approaches Explained at Medium;
Do you use global variables in your app design? from a reddit thread.

So, I would like to avoid using a global variable (for example in module entry-point), I think it could lead to more issues. It could be a good idea to do a quick test though...

Singleton pattern

In object-oriented programming, the singleton pattern is a software design pattern that restricts the instantiation of a class to a singular instance [...] Singletons are often preferred to global variables because they do not pollute the global namespace (or their containing namespace).

-- Singleton pattern on Wikipedia

Object Oriented Programming Design Patterns, a complex topic where programming patterns are standardized and used as common bricks to create something more complex. It was always a pain to work with that to be...

Anyway, let talk a bit about the singleton pattern. When an object is created and instantiated from a specific class , a part of the memory is allocated for it. If you are recreating another object with the same class, another part of the memory will be allocated, both objects living in their own space. A singleton is a pattern that will eventually (on demand for example) return an object already instantiated instead of created a new one. To do that in Dart, we also need to talk about the factory method pattern.

In object-oriented programming, the factory method pattern is a design pattern that uses factory methods to deal with the problem of creating objects without having to specify their exact classes. Rather than by calling a constructor, this is accomplished by invoking a factory method to create an object.

-- Factory method pattern on Wikipedia

The idea here is to allow a method or a function to create different objects from different classes. Those object can be stored in another object in Map for example or any other data-structure. This kind of behavior can be achieved by using the factory keyword.

A factory is a constructor prefaced by the built-in identifier (17.38) factory.

-- Dart Language Specification, Chapter 10, Section 7.2, page 51

Thanks for the information. It does not give us more information about how factory is being used though.

Instance creation expressions generally produce instances and invoke constructors to initialize them. The exception is that a factory constructor invocation works like a regular function call. It may of course evaluate an instance creation expression and thus produce a fresh instance, but no fresh instances are created as a direct consequence of the factory constructor invocation.

-- Dart Language Specification, Chapter 17, Section 13, page 135

That's a bit better. Indeed, the factory function looks like a regular function, and produce fresh instances or create new ones.

A factory constructor can be declared in an abstract class and used safely, as it will either produce a valid instance or throw

-- Dart Language Specification, Chapter 17, Section 13.2, page 137

That's part of the specification is also interesting, it means a factory can be part of an abstract class, then, the factory can be used from it to produce objects from a subclass.

The official documentation is listing few examples about factory constructors, and they give an idea when it could be used.

In object-oriented programming, the factory method pattern is a design pattern that uses factory methods to deal with the problem of creating objects without having to specify their exact classes. Rather than by calling a constructor, this is accomplished by invoking a factory method to create an object.

-- Factory method pattern on Wikipedia

Perhaps having other point of view could help to understand how this thing is working. Here a list of resources from the web:

Factory constructors from the official Dart documentation;
Mastering the Singleton Pattern in Dart by @devdammak
Singleton is a Design Pattern in Dart by Jamirul islam on Medium
https://medium.com/@hpatilabhi10/mastering-the-singleton-design-pattern-in-dart-40adb7dd87ec
Singleton Pattern in Dart by @blackcoda
Understanding Factory Constructors in Dart and Flutter: A Comparison with Static Methods by Shemsedin on Medium
How do you build a Singleton in Dart? on StackOverflow

Using the factory keyword here, is it really for creating a singleton? Let create a class called Singleton to understand this concept.

class Singleton {
  static String _name = "singleton";
  static int _counter = 0;

  Singleton();

  factory Singleton.create() => Singleton();

  static int increment() => _counter++;

  static int decrement() => _counter--;

  static int reset() => _counter=0;

  int get counter => _counter;

  String get name => _name;

  String toString() => "counter (${name}): ${counter}";
}

The _name and _counter attributes are private. They will be used to identify the singleton, to see if the instance is really the same. We can also add a random value instead of the fixed one for the name, but it would be too overkill for a simple test.

The constructor Singleton() simply returns an instantiated Singleton object and do no more. Then the create() method is marked as factory, so, in theory, it should also return the same instance of a Singleton object.

Then, increment(), decrement() and reset() methods are simply there to play with the _counter private attribute to see if when we change one instance, the other variables/functions pointing out this instance will change as well.

Finally, 2 getters are created to easily retrieve the values of the private attributes. The last method called toString() is a simple boilerplate to convert the Singleton as String.

Great, now, let creates an instance of a Singleton inside a synchronous functions called f().

void f() {
  Singleton v = Singleton();
  print("f() name: ${v.name}");
  print("f() counter: ${v.counter}");
  Singleton.increment();
}

Let do the same but for an asynchronous function call this time, using a Future and being delayed of 1 second. This function will be called a().

Future<void> a() async {
  Future
    .delayed(Duration(seconds: 1))
    .then((_) {
      Singleton v = Singleton();
      print("a() name: ${v.name}");
      print("a() counter: ${v.counter}");
      Singleton.decrement();
    });
}

An helper function to inspect the content of the Singleton object can also be good. It could be created directly as a method inside it, or, like in this case, as a function called inspect().

void inspect(Singleton s, {String label = ""}) {
  print("counter (${label}): ${s.counter}");
  print("name (${label}): ${s.name}");
}

Our code looks good, but the entry-point is still missing, let create our main() function. This one will contain most of the interesting stuff, and will try to instantiate many Singleton() objects to see if the values similar or different.

Future<void> main() async {
  // create a first instance
  Singleton v1 = Singleton();
  Singleton.increment();
  inspect(v1, label: "v1");

  // try to create a second instance
  // and increment the counter
  Singleton v2 = Singleton();
  inspect(v2, label: "v2");
  Singleton.increment();

  // check both instance (should return the same
  // values)
  inspect(v1, label: "v1");
  inspect(v2, label: "v2");

  // reset the singleton
  Singleton.reset();
  inspect(v1, label: "v1");
  inspect(v2, label: "v2");

  // asynchronous function call
  a();

  // create a third instance
  Singleton v3 = Singleton();
  inspect(v3, label: "v3");
  inspect(v2, label: "v2");
  inspect(v1, label: "v1");

  // synchronous function call
  f();
}

This code can be invoked, and here the result:

$ dart run bin/singleton.dart
counter (v1): 1
name (v1): singleton
counter (v2): 1
name (v2): singleton
counter (v1): 2
name (v1): singleton
counter (v2): 2
name (v2): singleton
counter (v1): 0
name (v1): singleton
counter (v2): 0
name (v2): singleton
counter (v3): 0
name (v3): singleton
counter (v2): 0
name (v2): singleton
counter (v1): 0
name (v1): singleton
f() name: singleton
f() counter: 0
a() name: singleton
a() counter: 1

Yeah, it seems the singleton pattern is working there. Even when we try to instantiate a new Singleton() object during the execution of the program, the values returned seems similar. I assume then the returned object is always the same. Anyway, I still don't understand everything, it's probably due to the syntax:

when using the constructor, the same instance is returned, does it means when any kind of method is marked with a factory keyword, it will only act as a factory?
what about race condition and asynchronous calls? Is it really safe to have a singleton in this kind of context? It looks like a global variable to me, so, I guess the same issues will be present.

Multiton Pattern

Another concept pattern exists, called multiton pattern, permits to manage more than one object. In fact, it seems this is the example made by the Dart documentation when talking about factories, at least, if the wikipedia can be trusted:

In software engineering, the multiton pattern is a design pattern which generalizes the singleton pattern. Whereas the singleton allows only one instance of a class to be created, the multiton pattern allows for the controlled creation of multiple instances, which it manages through the use of a map.

-- Multiton pattern on Wikipedia

So, what's the idea there? Well, instead of creating one instance of one object, and reusing every time, the multiton pattern deals with many objects stored somewhere, usually a Map like in the example. Let recreate it.

class Multiton {
  int _counter = 0;
  String _id  = "";

  final String _name = "multiton";
  static final Map<String, Multiton> _cache = <String,Multiton>{};

  factory Multiton(String id) {
    return _cache.putIfAbsent(id, () => Multiton._init(id));
  }

  Multiton._init(this._id);

  String get name => _name;

  int get counter => _counter;

  String get id => _id;

  static int length() => _cache.length;

  int increment() => _counter++;

  static Map<String, Multiton> get cache => _cache;

  static void remove(String id) {
    print("==> remove ${id}");
    _cache.remove(id);
  }

  void inspect({String? label = null}) {
    print("--");
    if (label != null) print("label: ${label}");
    print("multiton_length: ${length()}");
    print("object_hashCode: ${hashCode}");
    print("  object_id: ${_id}");
    print("  object_counter: ${_counter}");
    print("  object_name: ${_name}");
  }
}

Okay, it looks like a bit more complex than the singleton. The most complex part is about the _cache attribute, it will store the Multiton instance using a key as String when a new Multiton is created.

the inspect() method has been added directly inside the class to help to see what's happening. Note: only a Multiton instance can execute it, it's not possible to call it via the class itself like Multiton.inspect().

Let create then main() entry-point now.

void main() {
  // create a first multiton instance
  // with the id "test" and increment
  // its counter
  var m1 = Multiton("test");
  m1.inspect(label: "m1");
  m1.increment();

  // create a second multiton instance
  // using the same id "test", this should
  // be the same instance than m1.
  var m2 = Multiton("test");
  m2.inspect(label: "m2");

  // create a third multiton instance
  // with "test2" as id. It should be
  // a new instance.
  var m3 = Multiton("test2");
  m3.inspect(label: "m3");
  m3.increment();
  m3.increment();
  m3.increment();
  m1.inspect(label: "m1");
  m2.inspect(label: "m2");
  m3.inspect(label: "m3");

  // let remove the multiton using
  // "test" as id and recreate a new
  // one. the counter should be reset
  // to 0
  Multiton.remove("test");
  var m4 = Multiton("test");
  m4.inspect(label: "m4");

  // let remove it again
  // but because of garbage collector,
  // the value is still there.
  Multiton.remove("test");
  m4.inspect(label: "m4");

  // let remove the last id "test2"
  // and print the length of the multiton
  // it should be equal to 0
  Multiton.remove("test2");
  print(Multiton.length());
}

To help me (and the readers), some comments have been added. Dealing with multiple instance of objects can be challenging, and I did not even add the asynchronous part. Anyway, the idea there is to instantiate Multiton() objects in different manners. We can also play a bit with the garbage collector.

Indeed, the 2 last inspect() call are interesting. When we remove the key "test" from the _cache, we still have one instance of this object alive, because we are reusing the m4 variable. When we remove all keys, the _cache length drop to 0 and in theory, because no more variables are being used, all instances have been removed.

--
label: m1
multiton_length: 1
object_hashCode: 779530408
  object_id: test
  object_counter: 0
  object_name: multiton
--
label: m2
multiton_length: 1
object_hashCode: 779530408
  object_id: test
  object_counter: 1
  object_name: multiton
--
label: m3
multiton_length: 2
object_hashCode: 938446565
  object_id: test2
  object_counter: 0
  object_name: multiton
--
label: m1
multiton_length: 2
object_hashCode: 779530408
  object_id: test
  object_counter: 1
  object_name: multiton
--
label: m2
multiton_length: 2
object_hashCode: 779530408
  object_id: test
  object_counter: 1
  object_name: multiton
--
label: m3
multiton_length: 2
object_hashCode: 938446565
  object_id: test2
  object_counter: 3
  object_name: multiton
==> remove test
--
label: m4
multiton_length: 2
object_hashCode: 702292414
  object_id: test
  object_counter: 0
  object_name: multiton
==> remove test
--
label: m4
multiton_length: 1
object_hashCode: 702292414
  object_id: test
  object_counter: 0
  object_name: multiton
==> remove test2
0

A quick summary, I find the interface and all the syntactic sugar highly confusing here. It's really like black magic under steroids, the code is working, but you don't really know why and you are a bit afraid of the answer.

Unfortunately, the cache service will use the multiton patterns to store each sessions. When an user will store some value, the session requested will also have access to the cache store and offers getters/setters to modify it.

Observer pattern (Observables)

In software design and software engineering, the observer pattern is a software design pattern in which an object, called the subject (also known as event source or event stream), maintains a list of its dependents, called observers (also known as event sinks), and automatically notifies them of any state changes, typically by calling one of their methods.

Observer pattern on Wikipedia

While I was looking for an answer, some people pointed another solution called the observer pattern. Unfortunately, the package called observable I wanted to use is not maintained anymore. An alternative called simple_observable though. It will be the subject for another publication. Here some interesting link from the web about observer pattern in Dart:

Observer Pattern by Tyler Scott on Github
Design Pattern in Dart: Observer Pattern by Lotus Blog
Implement an Observer pattern in Dart on StackOverflow
Understanding Flutter Observables by Gaurav Swarankar on Medium
Reactive Programming in Flutter: Understanding the Power of Observables and Computed Values with Signals, Riverpod and RxDart by Christan Findlay
How to write your own observables in dart. by yadunandan on Medium
Why the Observer Pattern is Essential for Flutter Developers? by Moamedaliebaid on Medium

Common Functions

The cache service will use Base64Url specified in RFC4648. What's the difference with Base64? Well, this format is URL-friendly, and replace the + plus) and the / (slash) respectively by - (dash) and _ (underscore). It means base64url can easily be passed in a path. Let create the file lib/base64url.dart.

Bloody Eyes Alert: the implementation used here is disgustingly slow and crappy on purpose, I wanted to test the RegExp interface in Dart...

String toBase64Url(String base64) {
  return base64
    .replaceAllMapped(
      RegExp(r'\+'),
      (Match m) => '-'
    )
    .replaceAllMapped(
      RegExp(r'\/'),
      (Match m) => '_'
    );
}

The toBase64Url() function simple replace + and / by - and _ with the help of String.replaceAllMapped() method. A new RegExp() is used there to replace all characters.

String toBase64(String base64) {
  return base64
    .replaceAllMapped(
      RegExp(r'\-'),
      (Match m) => '+'
    )
    .replaceAllMapped(
      RegExp(r'\_'),
      (Match m) => '/'
    );
}

The toBase64() function is doing the opposite of the previous function (and uses the same structure).

bool isBase64Url(String b64) {
  try {
    base64.decode(toBase64(b64));
    return true;
  }
  catch (_) {
    return false;
  }
}

Finally, isBase64Url() checks if a Base64 string is valid or not. Again, dirty code where the Base64Url is converted to Base64 and then decoded.

Is there a better method? Yes. In fact, doing my own implementation of Base64Url could have been done, it would have been faster, but would also mean more work. The goal is not to have production ready tool, but to learn the most from Dart.

Store

The Store class will be one of the most important, it will contain the key/value defined by the clients. The definition should be flexible to accept any kind of data. The checks will be done before inserting data (in the handlers or middlewares).

class CacheStore {
  static final Map<String, String> _store= <String, String>{};

  CacheStore();

  bool exists(String key) => _store.containsKey(key);

  int length() => _store.length;

  String put(String key, String value) {
    _store[key] = value;
    return key;
  }

  String? get(String key) => _store[key];

  String? delete(String key) => _store.remove(key);
}

This class definition is simple, a _store attribute will contain the keys/values, and the get(), delete(), put() and exists() methods the interfaces to interact with it. The test suite can be seen below.

store_test() {
  group('store', () {
    test('create a new store', () {
      expect(CacheStore(), isA<CacheStore>());  
    });
    test('insert and deleting keys', () {
      CacheStore s = CacheStore();
      expect(s.length(), equals(0));

      s.put("test", "test");
      expect(s.get("test"), equals("test"));
      expect(s.length(), equals(1));
      expect(s.exists("test"), equals(true));

      s.delete("test");
      expect(s.get("test"), equals(null));
      expect(s.exists("test"), equals(false));
      expect(s.length(), equals(0));
    });
  });
}

Let execute them to be sure it works correclty.

$ dart test
00:00 +2: All tests passed!

Looks good to me. Go to the next stack.

Session

The Session class is our multiton, it will be in charge to manage the session by their id. Each session got one Store() object. This module is from lib/session.dart.

import 'dart:core';
import 'dart:math';
import 'dart:convert';
import 'cache_store.dart';
import 'base64url.dart';

class CacheSession {
  final String sessionId;
  final CacheStore cache = CacheStore();  

  static final Map<String, CacheSession> _sessions = <String, CacheSession>{};

  factory CacheSession(String id) {
    return _sessions.putIfAbsent(id, () {
      return CacheSession._init(id);
    });
  }

  CacheSession._init(this.sessionId);

  static bool exists(String id) {
    return _sessions.containsKey(id);
  }

  static String? delete(String sessionId) {
    if (_sessions.remove(sessionId) != null) {
      return sessionId;
    }
    return null;
  }

  String toString() => sessionId;
}

The most important part of the code is from the constructor CacheSession marked with the factory keyword. Every time a new Session() object is created, it will check if a similar object is already present using the session id. The exists() function can check if an existing object is associated with a key and the delete() method can remove an instantiated object from the session store if needed. This multiton implementation is similar to the one previously implemented at the beginning of this publication. Then, we need a way to check a session id.

bool checkSessionId(String sessionId) {
  if (sessionId.length>32) {
    return false;
  }
  RegExp regexp = RegExp(r'^([a-zA-Z0-9_-])+$');
  if (regexp.firstMatch(sessionId) == null) {
    return false;
  }
  return true;
}

A session id is a base64url like String, with - for the moment - a fixed length of 32 characters. It should be enough to avoid collision. The checkSessionId() function is dealing with that, but how to generate a random session id?

String generateSessionId(int length) {
  List<int> buf = [];
  final r = Random.secure();
  for (;length>0;length--)
    buf.add(r.nextInt(1<<8));
  return base64url(buf);
}

Well, the generateSessionId() function will generate a random session id as Base64url String using Random.secure() object from dart:math package. The returned String is cryptographically secure (at least, if one can trust the Dart API documentation).

String base64url(List<int> list) {
  String b64 = base64.encode(list);
  return toBase64Url(b64);
}

The last function called base64url() converts a list of integers to a base64url String.

session_test() {
  group('session', () {
    test('create a new session store', () {
      expect(CacheSession("test"), isA<CacheSession>());
    });
    test('dealing with sessions', () {
      var s = CacheSession("test");
      s.cache.put("test", "test");
      expect(s.cache, isA<CacheStore>());
      expect(CacheSession.exists("test"), equals(true));
      expect(s.cache.get("test"), equals("test"));

      var s2 = CacheSession("test2");
      s2.cache.put("test2", "data");
      expect(s.cache, isA<CacheStore>());
      expect(CacheSession.exists("test2"), equals(true));
      expect(s.cache.get("test2"), equals("data"));

      CacheSession.delete("test");
      expect(CacheSession.exists("test"), equals(false));

      CacheSession.delete("test2");
      expect(CacheSession.exists("test2"), equals(false));

    });
  });
}

$ dart test
00:00 +4: All tests passed!

Relic Handlers

The previous parts were talking about the logic of the application, the next parts will talk about the integration of this logic with Relic, a pure Dart HTTP server.

A relic server is using handlers to deal with Request() objects. A request is made when a client is requesting data from a server. A Request() object got some really interesting attributes and methods, mostly used to route it:

body property, contains the body of the request as Stream;
connectionInfo property, contains a ConnectionInfo object which store the client IP address and TCP port information;
header property, contains the HTTP Headers of the client;
method property, containing the HTTP method used by the client like GET or POST;
queryParameters property, contains the queries passed by the client;
rawPathParameters property contains the parameters parsed from the path;
url property contains the full url used by the client;
read and readAsString methods are used to extract the body from the request.

After applying the logic on a Request() object, an Handler should return a Response() object. This response will help to return a specific message to the client when using one of those constructors:

Response.ok() to return a 200 OK HTTP response;
Response.notFound() to return a 404 NOT FOUND HTTP Response;
Response.internalServerError() to return a 500 Internal Server Error HTTP Response.

More of them are present in the documentation, don't hesitate to use the one required for your needs.

Anyway, come back to the cache application; those handlers are currently stored in lib/handlers.dart but a better convention would probably to store them by features. Here the header.

import 'dart:math';
import 'package:relic/relic.dart';
import 'store.dart';
import 'session.dart';

The first step for a client is to ask for a session, on the path /sessions. A session id is generated (base64url String) and returned to the client only if the server can do it. This feature is defined by the newSessionHandler() function.

Response newSessionHandler(final Request req) {
  final String sessionId = generateSessionId(16);
  var s = CacheSession(sessionId);
  return Response.ok(
    body: Body.fromString(sessionId),
  );
}

A client can also check if one of its session is existing (or not). In this case, it will check the path /sessions/:session where :session is a session id. If the session exists, the server returns a 200 OK, if not, a 404 NOT FOUND. The getSessionHandler() function is taking care of this handler.

Response getSessionHandler(final Request req) {
  final String sessionId = req.rawPathParameters[#session]!;
  if (CacheSession.exists(sessionId)) {
    return Response.ok(
      body: Body.fromString("")
    );
  }
  return Response.notFound(
    body: Body.fromString("")
  );
}

A client can also remove a session by using the /session/:session path with the help of the DELETE HTTP method. This feature is implemented in the deleteSessionHandler() function.

Response deleteSessionHandler(final Request req) {
  final String sessionId = req.rawPathParameters[#session]!;
  String? id = CacheSession.delete(sessionId);
  if (id != null) {
    return Response.ok(
      body: Body.fromString(id),
    );
  }
  return Response.notFound(
    body: Body.fromString('not found'),
  );
}

A client with a valid session id can see the number of keys set in the cache by using the /sessions/:session/keys. This is currently not implemented, but it will be managed by the getCacheLengthHandler() function.

Future<Response> getCacheLengthHandler(final Request req) async {
  final String sessionId = req.rawPathParameters[#session]!;
  final CacheSession s = CacheSession(sessionId)!;

  return Response.ok(
    body: Body.fromString(s.cache.length().toString()),
  );
}

A client with a valid session id can retrieve a key from a cache with the path /cache/:session/:key where :key is a String used as key in the cache store. This feature is implemented in the getCacheHandler() function.

Future<Response> getCacheHandler(final Request req) async {
  final String sessionId = req.rawPathParameters[#session]!;
  final CacheSession s = CacheSession(sessionId)!;
  final key = req.rawPathParameters[#key]!;

  if (!s.cache.exists(key))
    return Response.notFound(
      body: Body.fromString("not found"),
    );

  String? value = s.cache.get(key);

  if (value != null)
    return Response.ok(
      body: Body.fromString(value),
    );
  else
    return Response.ok(
      body: Body.fromString(""),
    );
}

A client with a valid session id can also create a new key with a value. In this case, the client will use the /cache/:session/:key with the HTTP POST method. The body of the request will be the value associated with the key (then the data stored in the cache). This feature is implemented in postCacheHandler() function.

Future<Response> postCacheHandler(final Request req) async {
  final String sessionId = req.rawPathParameters[#session]!;
  final CacheSession s = CacheSession(sessionId)!;
  final key = req.rawPathParameters[#key]!;

  String body = await req.readAsString(maxLength: 10000);

  s.cache.put(key, body);
  return Response.ok(
    body: Body.fromString("ok"),
  );
}

Finally, a client with a valid session can also delete a key/value using the /cache/:session/:key path and with the DELETE HTTP method. The deleteCacheHandler() function was created to implement this behavior.

Future<Response> deleteCacheHandler(final Request req) async {
  final String sessionId = req.rawPathParameters[#session]!;
  final CacheSession s = CacheSession(sessionId)!;
  final key = req.rawPathParameters[#key]!;

  s.cache.delete(key);
  return Response.ok(
    body: Body.fromString("ok"),
  );
}

I still don't really know how to deal with the tests though, so, it will be done later. For now, the handlers created there are pretty simple and should not do lot of mess.

Relic Middleware

A Relic Middleware can be seen as a pipeline. It will got a request as input, modify it and returns it as input, before any handlers. A feature called Pipeline was previously available from Relic, but it is now deprecated.

A Middleware

https://pub.dev/documentation/relic/latest/relic/MiddlewareObject-class.html

In our case, the middlewares are currently all stored in lib/middlewares.dart module; we don't have a lot of them, so, it should be okay for the moment.

import 'package:relic/relic.dart';
import 'store.dart';
import 'session.dart';

One of the middleware, called checkSessionId() will be in charge to check if a session id exists or not. If it does not exist, a 404 not found is returned.

/// check if the session id has been defined in the
/// URL path.
Middleware checkSessionId() {
  return (final Handler next) {
    return (final Request req) async {
      final sessionId = req.rawPathParameters[#session];
      if (sessionId == null)
        return Response.badRequest(
          body: Body.fromString('sessionId not defined'),
        );
      return await next(req);
    };
  };
}

I think I made some duplicated code. Anyway, not really important for the moment, it will also be another good reason to test the Dart analyzer tool, and delete dead code.

/// check if the session id exists in the sessions
/// store.
Middleware checkSessionExists() {
  return (final Handler next) {
    return (final Request req) async {
      final String sessionId = req.rawPathParameters[#session]!;
      if (!CacheSession.exists(sessionId))
        return Response.badRequest(
           body: Body.fromString('sessionId "${sessionId}" does not exist'),
        );
      return await next(req);
    };
  };
}

Another middleware can be used to check if a key is present in the cache. Like the previous definition, it will return a not found if it's not the case.

/// check if the key has been defined in the URL path
Middleware checkKeyExists() {
  return (final Handler next) {
    return (final Request req) async {
      final key = req.rawPathParameters[#key];
      if (key == null)
        return Response.badRequest(
          body: Body.fromString('key not defined'),
        );
      return await next(req);
    };
  };
}

3 middlewares have been created, more of them can be added, but let stay with that for now, if you want to have some ideas for the next ones to implement:

a middleware to check the :session id, it must be a valid base64url;
a middleware to check the :key, it must be a valid base64url String and limited to 64 characters;
a middleware to check the size of the data sent by the client, it should be limited (like 65KB).

Relic Routing

Great, we know how to create Handlers and Middlewares, the last step is to assemble them with the help of a routers inside a RelicApp() object. This time, the code is stored in lib/app.dart.

import 'package:relic/relic.dart';
import 'handlers.dart';
import 'middlewares.dart';

For this application, a function called app() has been created. This one is returned a RelicApp() object, but before returning it, the routes can be configured with the help of the followings methods:

use() method adds a new middleware based on path pattern;
get() method is used to deal with GET HTTP method;
post() method is used to route the POST HTTP method;
delete() method is used to deal with the DELETE HTTP method;
fallback() method is the last route called if no others matched a pattern.

As you can see, all those methods are following the same structure, the first argument is used to create a path pattern and the second argument is there to add an handler.

RelicApp app() {
  return RelicApp()
    // sessions API
    ..get('/sessions', newSessionHandler)
    ..use('/sessions/:session', checkSessionId())
    ..use('/sessions/:session', checkSessionExists())
    ..delete('/sessions/:session', deleteSessionHandler)
    ..get('/sessions/:session', getSessionHandler)

    // cache API
    ..use('/cache/:session/:key', checkSessionId())
    ..use('/cache/:session/:key', checkSessionExists())
    ..use('/cache/:session/:key', checkKeyExists())
    ..get('/cache/:session', getCacheLengthHandler)
    ..get('/cache/:session/:key', getCacheHandler)
    ..post('/cache/:session/:key', postCacheHandler)
    ..delete('/cache/:session/:key', deleteCacheHandler)

    // wildcard
    ..fallback = respondWith(
      (_) => Response.notFound(
        body: Body.fromString("not found"),
      ),
    );
}

In the code above, all the routes and their handlers have been defined. The application is practically ready to be started.

Application Entry Point

The last brick to this application is the entry-point. This module is stored in bin/cache_relic.dart. The code is straightforward: start the RelicApp listener by executing the serve() method.

import 'package:relic/relic.dart';
import 'package:cache_relic/app.dart';

Future<void> main() async {
  await app().serve();
}

Voilà! It's done! The application should work now.

Testing

All bricks are ready, the logic has been created, the middlewares and the handlers have been added in the router and the main entry-point can be executed. Let start the application.

$ dart run
Building package executable... 
Built cache_relic:cache_relic.

We can verify if the application is listening correctly on the port TCP/8080 with the help of sshttps://manpages.debian.org/trixie/iproute2/ss.8.en.html.

$ ss -nlpt sport = 8080
State               Recv-Q              Send-Q                            Local Address:Port                             Peer Address:Port              Process                                                    
LISTEN              0                   128                                   127.0.0.1:8080                                  0.0.0.0:*                  users:(("dart:cache_reli",pid=4137059,fd=9))

The service is listening. First step to use it, generate a new session from /sessions end-point.

$ curl localhost:8080/sessions
xYgo--V1c8Bmu8Gp-y1WeQ==

The session id is xYgo--V1c8Bmu8Gp-y1WeQ==, let use it to store our first data into the cache with the help of /cache/xYgo--V1c8Bmu8Gp-y1WeQ==/${key} end-point.

$ curl -XPOST -dtest localhost:8080/cache/xYgo--V1c8Bmu8Gp-y1WeQ==/test
ok

It looks good, but can we be sure it has been correctly stored? We can check that with the /cache/xYgo--V1c8Bmu8Gp-y1WeQ==/${key} end-point.

$ curl -XGET localhost:8080/cache/xYgo--V1c8Bmu8Gp-y1WeQ==/test
test

Nice! It seems our data has been correctly stored! Let delete it now, still with the /cache/xYgo--V1c8Bmu8Gp-y1WeQ==/${key} end-point.

$ curl -XDELETE localhost:8080/cache/xYgo--V1c8Bmu8Gp-y1WeQ==/test
ok

The end-point returns ok, but let check if it's really the case.

$ curl -XGET localhost:8080/cache/xYgo--V1c8Bmu8Gp-y1WeQ==/test
not found

That's good, the data has been correctly removed from the cache store. Let check now the other features we added, especially on the session side. One feature is to check if a session exists, it has been added on the /sessions/xYgo--V1c8Bmu8Gp-y1WeQ== end-point.

$ curl -v -XGET localhost:8080/sessions/xYgo--V1c8Bmu8Gp-y1WeQ==
Note: Unnecessary use of -X or --request, GET is already inferred.
* Host localhost:8080 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* HTTPS-RR: -
*   Trying [::1]:8080...
* connect to ::1 port 8080 from ::1 port 57168 failed: Connection refused
*   Trying 127.0.0.1:8080...
* Established connection to localhost (127.0.0.1 port 8080) from 127.0.0.1 port 49010 
* using HTTP/1.x
> GET /sessions/xYgo--V1c8Bmu8Gp-y1WeQ== HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/8.20.0
> Accept: */*
> 
* Request completely sent off
< HTTP/1.1 200 OK
< content-type: text/plain; charset=utf-8
< date: Sun, 07 Jun 2026 16:20:40 GMT
< content-length: 0
< 
* Connection #0 to host localhost:8080 left intact

It returns a 200 HTTP Code, it means it exists. Let delete the session now.

$ curl -v -XDELETE localhost:8080/sessions/xYgo--V1c8Bmu8Gp-y1WeQ==
xYgo--V1c8Bmu8Gp-y1WeQ==

The session id is returned to the client, and the server looks happy. Let check if the session has been correctly removed.

$ curl -XGET localhost:8080/sessions/xYgo--V1c8Bmu8Gp-y1WeQ==
sessionId "xYgo--V1c8Bmu8Gp-y1WeQ==" does not exist

The xYgo--V1c8Bmu8Gp-y1WeQ== session does not exist anymore. I think the application is working has expected.

Conclusion

The implementation is working correctly, but the code looks dirty, using for example something like a factory to deal with the instantiated objects does not seem to be the right way. In fact, using a factory like that can probably lead to race conditions and other issues. In fact, the factories in Dart are more black magic stuff, even in the language specifications, it's kinda hard to understand how they are working or how they have been implemented.

Furthermore, because this "project" was a draft to test factories in Dart, no tests have been created (really bad practices), but it was also not designed to be used in production! So, be careful if you want to use it for one of your project, and please review it.

Anyway, here a list of cool features to add:

Test:
- Add tests for middlewares
- Add tests for handlers
- Add integration tests
Global:
- the session ttl can be set from the CLI (e.g. --session.ttl=60);
- the session limit size can be set from the CLI (e.g. --session.size.max=123);
- the default key size can be changed from the CLI (e.g. --cache.key.size.max=123);
- the default value size can be changed from the CLI (e.g. --cache.value.size.max=123);
- those parameters could be stored in another immutable factory.
Session:
- Only a limited amount of session can be created, if full, the API returns not more sessions can't be created (session cache full);
- A session has a limited period of validity (60s), after this period, it is automatically removed, except if the client ask for more time;
- A session is limited in size (bytes);
- A session can be exported as JSON.
Cache:
- A store key can be copied to another existing session;
- The x-cache-session-ttl can be added on all request, it will contain the remaining times before the session will be removed.

As usual, if you want to know a bit more, dig a bit deeper into this topic, here few resources that could probably help you:

Relic package on pub.dev;
Relic API Documentation, where you will find the full documentation of the API;
Official Relic Website, where you will find the official documentation and lot of examples;
Relic Repository at Github, where you will find the full relic implementation source code, you should check the examples and the test suite;
in_memory_store package, this package would have been a great alternative to store data in memory, adding and testing it in the future could be great.

The repository containing the source code can be found in niamtokik/cache_relic repository on Github.

Cover Image by Daniil Zameshaev on Unsplash

Interactive Shell with Dart

Mathieu Kerjouan — Tue, 09 Jun 2026 08:00:00 +0000

Any modern languages should have its REPL, Erlang, Elixir, Haskell, Clojure, Ocaml, Python... All of them got one shell-like feature to interact with the application in conception phase. That's kinda mandatory to me, it permits to test functions before adding them in the final commit, it can be used to draft quick ideas and so on. When I started learning Dart, I was a bit sad it was not integrated by default... but someone decided to fix that by creating the interactive package! Let create a new project called myrepl just to check that.

$ dart create myrepl
Creating myrepl using template console...

  .gitignore
  analysis_options.yaml
  CHANGELOG.md
  pubspec.yaml
  README.md
  bin/myrepl.dart
  lib/myrepl.dart
  test/myrepl_test.dart

Running pub get...                     0.3s
  Resolving dependencies...
  Downloading packages...
  Changed 48 dependencies!

Created project myrepl in myrepl! In order to get started, run the following commands:

  cd myrepl
  dart run

$ cd myrepl

As usual, the new dependency can be added using dart pub add. interactive depends on 12 dependencies, so, it could be better to add it only in the dev environment.

$ dart pub add interactive
Resolving dependencies... 
Downloading packages... 
< _fe_analyzer_shared 85.0.0 (was 100.0.0) (100.0.0 available)
< analyzer 7.7.1 (was 13.0.0) (13.0.0 available)
+ cli_repl 0.2.3
< coverage 1.6.4 (was 1.15.0) (1.15.0 available)
+ interactive 1.4.1
+ js 0.6.7 (0.7.2 available)
< matcher 0.12.17 (was 0.12.20) (0.12.20 available)
< test 1.26.3 (was 1.31.1) (1.31.1 available)
< test_api 0.7.7 (was 0.7.12) (0.7.12 available)
< test_core 0.6.12 (was 0.6.18) (0.6.18 available)
< vm_service 11.10.0 (was 15.2.0) (15.2.0 available)
These packages are no longer being depended on:
- cli_config 0.2.0
Changed 12 dependencies!
9 packages have newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information

Next, interactive package must be compiled and activated on the system. It will be installed locally in ${HOME}/.pub-cache/bin directory.

$ dart pub global activate interactive
Package interactive is currently active at version 1.4.1.
Downloading packages... . 
  _fe_analyzer_shared 85.0.0 (100.0.0 available)
  analyzer 7.7.1 (13.0.0 available)
  js 0.6.7 (0.7.2 available)
> meta 1.18.3 (was 1.18.2)
  vm_service 11.10.0 (15.2.0 available)
Building package executables... (2.5s)
Built interactive:interactive.
Installed executable interactive.
Warning: Pub installs executables into $HOME/.pub-cache/bin, which is not on your path.
You can fix that by adding this to your shell's config file (.bashrc, .bash_profile, .zshrc etc.):

  export PATH="$PATH":"$HOME/.pub-cache/bin"

Activated interactive 1.4.1.

$ file ${HOME}/.pub-cache/bin/interactive 
${HOME}/.pub-cache/bin/interactive: a sh script, ASCII text executable

The ${HOME}/.pub-cache/bin/interactive file is a simple shell script using the dart VM to execute the interactive package. The command executed looks like the snippet below. It means this code could be executed anywhere on your system if the interactive package is installed (it will produce some errors outside a Dart project directory).

dart pub -v global run interactive:interactive "$@"

Anyway, let export the Dart bin directory inside our PATH.

$ export PATH="${PATH}:${HOME}/.pub-cache/bin"

Great! Let execute the interactive command (it should be present in our PATH now).

$ interactive
Run: /bin/dart [--enable-vm-service=34273, file:///bin/interactive.dart-3.11.5.snapshot, --vm-service-was-enabled]
Workspace: /tmp/dart_interactive_workspace_2026-06-04T163359990891
The Dart VM service is listening on http://127.0.0.1:34273/HveG-LmYIiQ=/
The Dart DevTools debugger and profiler is available at: http://127.0.0.1:34273/HveG-LmYIiQ=/devtools/?uri=ws://127.0.0.1:34273/HveG-LmYIiQ=/ws
>>>

The command invoke a shell with a >>> prompt. What will happen if we create some Dart code?

>>> 1+1
2

>>> class Meh { String _meh = ""; Meh(String meh) : this._meh = meh; String toString() => "${_meh}!"; }

>>> Meh("test")
test!

>>> import 'dart:async';

>>> Future<int> t() { return 1; }
[WARNING 2026-06-04 20:25:05.859183] Error: Hot reload failed, maybe because code has syntax error?

>>> Future<int> t() async { return 1; }

>>> t().then((x) => print(x))
Instance of 'Future<void>'
>>> 1

It works! interactive gives us a way to dynamically create Dart code, like any modern language! That's very cool! It's even possible to execute command from the system itself by prefixing the line to execute with !.

>>> !ls
lib
pubspec.lock
pubspec.yaml

>>> !pwd
/tmp/dart_interactive_workspace_2026-06-04T201405364736

Conclusion

This is a great project, and it could be even better to see it be added in the SDK! At this time, it works, but it feels like it's a bit unstable and not finished yet. The shell is working but can be slow sometimes. The fact the devtools are already started by default is also another nice feature. What's missing to me? Here a quick list of cool stuff to add:

adding a successful command line index counter, every time a command is being executed, the counter is increased;
removing the "..." for the multi line support, it can be annoying when doing a copy/paste;
integrating the devtools directly into the shell, like @profile to profile the application or @memory to see memory usage;
saved session with state and command history restore;
debugger and tracer integration;
documentation and manual integration like help(Object);
class, function and command Auto-completion when pressing tab;
handlers, hooks and other features to make a custom shell.

As usual, if you want to know more about this project, here some links:

The interactive package at pub.dev;
The official interactive package source code at Github;
The interactive API documentation

Bonus: devtools

While testing interactive I discovered the Dart devtools suite. It's a pretty cool way to debug, trace and profile a Dart application, thanks to the Dart virtual machine. This application is working a bit like the different tools we have with the BEAM (e.g. observer, debugger and so on). Here some screenshot from the previous project created.

http://127.0.0.1:34273/HveG-LmYIiQ=/devtools/home?compiler=wasm

A full post on this feature will be required. For now, it's just a quick overview based on screenshots.

Cover Image by Giulia May on Unsplash

Missing Libraries on OpenBSD

Mathieu Kerjouan — Mon, 08 Jun 2026 10:00:00 +0000

Sometimes, shit happens, and if you are unlucky, it can be many time in a short period of time! Anyway, following the upgrade of OpenBSD to 7.9 on one of my laptop, I got another issue with missing libraries. I still don't know what happened, but I suspect a problem with pkg_add. While installing a package, this one crashed. Anyway, I will give you a way to fix that. First, let describe the problem.

I wanted to use ffmpeg to extract audio from a video file, but when executing it, here the message I got:

$ ffmpeg
ld.so: ffmpeg: can't load library 'libavfilter.so'

Ah! That's annoying. Where this library come from? Let use pkglocate to have our answer.

$ pkglocate libavfilter.so
ffmpeg-8.0.1p1v1:graphics/ffmpeg:/usr/local/lib/libavfilter.so.13.

Ah! This is even more annoying, this library is coming from ffmpeg package, but it seems ffmpeg is installed, right? Let check that with pkg_info (just to confirm).

$ pkg_info -l | grep ffmpeg

Indeed. The package is correctly installed. Let investigate a bit with kdump and ktrace, the equivalent version of strace for OpenBSD. This part is simply for fun, because I was already aware of the problem, but it will give you an idea of the procedure I would have use if I was looking for something weird.

$ ktrace ffmpeg
$ kdump
 75640 ktrace   RET   ktrace 0
 75640 ktrace   CALL  mmap(0,0xd7,0x3<PROT_READ|PROT_WRITE>,0x1002<MAP_PRIVATE|MAP_ANON>,-1,0)
 75640 ktrace   RET   mmap 6423225446400/0x5d786123000
 75640 ktrace   CALL  execve(0x73aa771e3d40,0x73aa771e4340,0x73aa771e4350)
 75640 ktrace   NAMI  "/bin/ffmpeg"
 75640 ktrace   RET   execve -1 errno 2 No such file or directory
 75640 ktrace   CALL  execve(0x73aa771e3d40,0x73aa771e4340,0x73aa771e4350)
 75640 ktrace   NAMI  "/bin/ffmpeg"
 75640 ktrace   RET   execve -1 errno 2 No such file or directory
 75640 ktrace   CALL  execve(0x73aa771e3d40,0x73aa771e4340,0x73aa771e4350)
 75640 ktrace   NAMI  "/sbin/ffmpeg"
 75640 ktrace   RET   execve -1 errno 2 No such file or directory
 75640 ktrace   CALL  execve(0x73aa771e3d40,0x73aa771e4340,0x73aa771e4350)
 75640 ktrace   NAMI  "/usr/bin/ffmpeg"
 75640 ktrace   RET   execve -1 errno 2 No such file or directory
 75640 ktrace   CALL  execve(0x73aa771e3d40,0x73aa771e4340,0x73aa771e4350)
 75640 ktrace   NAMI  "/usr/sbin/ffmpeg"
 75640 ktrace   RET   execve -1 errno 2 No such file or directory
 75640 ktrace   CALL  execve(0x73aa771e3d40,0x73aa771e4340,0x73aa771e4350)
 75640 ktrace   NAMI  "/usr/X11R6/bin/ffmpeg"
 75640 ktrace   RET   execve -1 errno 2 No such file or directory
 75640 ktrace   CALL  execve(0x73aa771e3d40,0x73aa771e4340,0x73aa771e4350)
 75640 ktrace   NAMI  "/usr/local/bin/ffmpeg"
 75640 ktrace   ARGS  
        [0] = "ffmpeg"
 75640 ffmpeg   NAMI  "/usr/libexec/ld.so"
 75640 ffmpeg   NAMI  "/var/run/ld.so.hints"
 75640 ffmpeg   RET   open 3
 75640 ffmpeg   CALL  fstat(3,0x7183b3383150)
 75640 ffmpeg   STRU  struct stat { dev=66628, ino=984995, mode=-r--r--r-- , nlink=1, uid=0<"root">, gid=0<"wheel">, rdev=3943528, atime=1780508371<"Jun  3 17:39:31 2026">.216788585, mtime=1780508368<"Jun  3 17:39:28 2026">.926794253, ctime=1780508368<"Jun  3 17:39:28 2026">.926794253, size=11270, blocks=24, blksize=16384, flags=0x0, gen=0x0 }
 75640 ffmpeg   RET   fstat 0
 75640 ffmpeg   CALL  mmap(0,0x2c06,0x1<PROT_READ>,0x2<MAP_PRIVATE>,3,0)
 75640 ffmpeg   RET   mmap 6587275476992/0x5fdb8370000
 75640 ffmpeg   CALL  mmap(0,0x1000,0x3<PROT_READ|PROT_WRITE>,0x1002<MAP_PRIVATE|MAP_ANON>,-1,0)
 75640 ffmpeg   RET   mmap 6585773539328/0x5fd5eb14000
 75640 ffmpeg   CALL  mimmutable(0x5fdb8370000,0x2c06)
 75640 ffmpeg   RET   mimmutable 0
 75640 ffmpeg   CALL  close(3)
 75640 ffmpeg   RET   close 0
 75640 ffmpeg   CALL  open(0x5fd5eb14150,0x30000<O_RDONLY|O_CLOEXEC|O_DIRECTORY>)
 75640 ffmpeg   NAMI  "/usr/lib"
 75640 ffmpeg   RET   open 3
...
 75640 ffmpeg   GIO   fd 2 wrote 15 bytes
       "ld.so: ffmpeg: "
 75640 ffmpeg   RET   write 15/0xf
 75640 ffmpeg   CALL  write(2,0x5fcc3339190,0x23)
 75640 ffmpeg   GIO   fd 2 wrote 35 bytes
       "can't load library 'libavfilter.so'"
 75640 ffmpeg   RET   write 35/0x23
 75640 ffmpeg   CALL  write(2,0x5fcc3237b0c,0x1)
 75640 ffmpeg   GIO   fd 2 wrote 1 bytes
       "
       "
 75640 ffmpeg   RET   write 1
 75640 ffmpeg   CALL  thrkill(0,SIGKILL,0)
 75640 ffmpeg   PSIG  SIGKILL SIG_DFL

Interesting. It looks like ld.hints is having only /usr/lib configured, let check that with ldconfig and the -r flag.

$ ldconfig -r
ldconfig -r                                                               
/var/run/ld.so.hints:                           
        search directories: /usr/lib

Doh. The problem is from /var/run/ld.so.hints, this file should contain a list of libraries available on the system, here, it returns literally nothing. Let fix that by reusing ldconfig but this time to recreate the file correctly with the help of the -m and -R flags.

$ doas ldconfig -mR /usr/lib /usr/X11R6/lib /usr/local/lib

Let check if the ld.so.hints file now contain more libraries.

$ ldconfig -r
/var/run/ld.so.hints:
        search directories: /usr/lib
        0:-liberty.12.0 => /usr/lib/libiberty.so.12.0
...
        1055:-lhogweed.3.1 => /usr/local/lib/libhogweed.so.3.1
        1056:-latkmm-1.6.10.1 => /usr/local/lib/libatkmm-1.6.so.10.1
...
        1168:-lpixman-1.46.4 => /usr/X11R6/lib/libpixman-1.so.46.4
        1169:-lpoppler.101.0 => /usr/local/lib/libpoppler.so.101.0

It's way better like that! Okay, let run ffmpeg another time.

$ $ ffmpeg -version
ffmpeg version 8.0.2 Copyright (c) 2000-2025 the FFmpeg developers
built with OpenBSD clang version 19.1.7
configuration: --enable-shared --arch=amd64 --cc=cc --cxx=c++ --enable-debug --disable-stripping --disable-indev=jack --disable-vulkan --enable-fontconfig --enable-frei0r --enable-gpl --enable-ladspa --enable-libaom --enable-libass --enable-libdav1d --enable-libfontconfig --enable-libfreetype --enable-libfribidi --enable-libgsm --enable-libharfbuzz --enable-libmp3lame --enable-libopus --enable-libspeex --enable-libsvtav1 --enable-libtheora --enable-libv4l2 --enable-libvorbis --enable-libvpx --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxml2 --enable-libxvid --enable-libzimg --enable-nonfree --enable-openssl --enable-libvidstab --extra-cflags='-I/usr/local/include -I/usr/X11R6/include' --extra-libs='-L/usr/local/lib -L/usr/X11R6/lib' --extra-ldsoflags= --mandir=/usr/local/man --objcc=/usr/bin/false --optflags='-O2 -pipe -g -Wno-redundant-decls'
libavutil      60.  8.102 / 60.  8.102
libavcodec     62. 11.102 / 62. 11.102
libavformat    62.  3.102 / 62.  3.102
libavdevice    62.  1.102 / 62.  1.102
libavfilter    11.  4.102 / 11.  4.102
libswscale      9.  1.102 /  9.  1.102
libswresample   6.  1.102 /  6.  1.102

Exiting with exit code 0

Nice! A last check to be sure everything is fine on the system, it's to execute pkg_check. It will verify if the packages have been correctly installed and if nothing wrong happened to them. If this issue happens again, it could be due to a misconfiguration, or a bug.

$ doas pkg_check                                                                                                   
Packing-list sanity: ok                                                                                                                                       
Direct dependencies: ok                                                                                                                                       
Reverse dependencies: ok                                                                                                                                      
Files from packages: ok

Everything looks good at first glance. Anyway, I think I did something wrong during the last upgrade. That's great! It gives me more opportunities to write publication about OpenBSD! Debugging and fixing problems on OpenBSD is a real pleasure, thanks to the documentation and all the simple Unix-like procedures used everywhere.

Have fun!

Cover Image by CHUTTERSNAP on Unsplash

Tests and Coverage in Dart

Mathieu Kerjouan — Fri, 05 Jun 2026 08:00:00 +0000

Writing tests is one of the most important and tedious task a developer has to do. A test is more than proving something is working in a project - even if it's main goal, it's also a way to see how an API is working, by offering implicit use cases and representing data using different format (mocking).

It's usually a good practice to create the test first and then implement the solution. This is the foundation of both Test-driven Development (TDD) and Extreme Programming (XP) methodologies.

In TDD, the test must be written first, and must fail. During the next iteration, the developer will invest time and effort to ensure the test is passing. In XP, this is practically the same, except this methodology has been created for high speed development (game production), and the tests are also used as source of trust and documentation.

This post is not really about those methodologies, even if we can talk a bit about them, one will find more accurate resources on Wikipedia or elsewhere than reading this publication. The goal of this article is to summarize the different ways available to test an application in Dart. Dart only, not Flutter, this is a different beast, and a dedicated article will be created only for it.

Bootstrapping

As usual, a new dedicated project will be created, let call it... rps for rock-paper-scissors. Let say it will be a library containing the rules for the Jan-ken-pon.

$ dart create rps
Creating rps using template console...

  .gitignore
  analysis_options.yaml
  CHANGELOG.md
  pubspec.yaml
  README.md
  bin/rps.dart
  lib/rps.dart
  test/rps_test.dart

Running pub get...                     0.3s
  Resolving dependencies...
  Downloading packages...
  Changed 48 dependencies!

Created project rps in rps! In order to get started, run the following commands:

  cd rps
  dart run

If no template is being used to create this application, one will need to add the test package as dependencies in pubspec.yaml file, inside the dev_dependencies section. See below for an example.

dev_dependencies:
  lints: ^6.0.0
  test: ^1.25.6

The test package is the main one used to create test suites in Dart. It is maintained by the Dart team and available by default in the SDK.

Rock-Paper-Scissors Rules

The Jan-ken-pon is a simple - and addictive - game. The goal is to win a duel with someone else using one of the 3 movements also called Shapes: Rock (the hand is fully closed), Paper (the hand is fully opened), and Scissors (the hand is half closed and the fingers are doing a scissors).

The Rock wins over Scissors (then the Scissors is losing against Rock);
The Scissors wins over Paper (then the Paper is losing against Scissors);
The Paper wins over Rock (then the Rock is losing against Paper);
If both players are using the same movement, it's a draw and they must start over until one win.

A quick table to summarize the final results:

a vs b	rock	paper	scissors
rock	draw	loss	win
paper	win	draw	loss
scissors	loss	win	draw

Usually, this game is played anywhere and for any reasons (for example for the one who will eat the last chocolate desert in the restaurant). Let call the act to play with someone else a Party. This post will also give me the opportunity to talk about design programming and OOP. Yeah. Marvelous. Finally.

Rock-Paper-Scissors Shapes

To me, a good programming language should give you an idea of an implementation without a lot of effort. When using Object Oriented Programming paradigm, this is never the case. You don't have one or two obvious solutions, but a bunch of potentials valid solutions. Let try to implement our shapes here (rock, paper and scissors).

Here 3 of the implementations I can think of when dealing with this project:

(medium complexity) Like any other OOP language, one will create a first abstract class called Shape, and then will create 3 classes called Rock, Paper and Scissors inheriting from the Shape class;
(low complexity) Because Dart is being used here, one can do something a bit different, using an enumerator as class, and extends it with few methods to compare the defined value between them;
(high complexity) Create a more complex data-structure, based on a ring (linked list) where the first element is linked to the last one, or a directed graph, where the different path can define which shape greater than another one. Those solutions are way more complex, but can give more flexibility and extends the game in the future with new shapes (e.g. Spoke and Snake).

The second option seems to be the easiest one for this kind of publication, so, let implement it. Let begin with something simple, the representation of the shapes using an emoji (utf8/unicode). A test/ directory should already be present in the project, we can add a new test file called shapes_test.dart there.

// file test/shapes_test.dart

import 'dart:convert';
import 'package:test/test.dart';
import 'package:rps/shapes.dart' as shapes show versus;
import 'package:rps/shapes.dart' show Shape;

final utf8Encoder = utf8.encoder;

void shapeRepresentation() {
  group('Shapes Representation', () {
    // see https://unicodeplus.com/U+270A
    test('rock as raised fist unicode', () {
      expect(
        utf8Encoder.convert(Shape.rock.toString()),
        [226, 156, 138]
      );
    });

    // see https://unicodeplus.com/U+1FAF3
    test('paper as palm down hand unicode', () {
      expect(
        utf8Encoder.convert(Shape.paper.toString()),
        [240, 159, 171, 179]
      );
    });

    // see https://unicodeplus.com/U+270C
    test('scissors as victory hand unicode', () {
      expect(
        utf8Encoder.convert(Shape.scissors.toString()),
        [226, 156, 140]
      );
    });
  });
}

void main() {
  shapeRepresentation();
}

Here's an explanation of this code, a new test case is created with the help of the test() function. The first argument is the description of the test as String, and the next argument is an anonymous function containing the code to be executed.

A test case can be added in a test group, in this situation, the group() function can be used. It follows the same principle than the test() function, the first argument is the description of the group as String and the second argument will contain the test cases to be executed.

Then, each test cases is made of functions exposed by the test module, in our case, the expect() function is used to assert a certain value.

$ dart test
00:00 +0 -1: loading test/shapes_test.dart [E]                                                          
  Failed to load "test/shapes_test.dart":
  test/shapes_test.dart:13:29: Error: Undefined name 'Shape'.
          utf8Encoder.convert(Shape.rock.toString()),
                              ^^^^^
  test/shapes_test.dart:21:29: Error: Undefined name 'Shape'.
          utf8Encoder.convert(Shape.paper.toString()),
                              ^^^^^
  test/shapes_test.dart:29:29: Error: Undefined name 'Shape'.
          utf8Encoder.convert(Shape.scissors.toString()),
                              ^^^^^
  test/shapes_test.dart:39:14: Error: Undefined name 'Shape'.
        expect(Shape.rock > Shape.scissors, equals(true));
               ^^^^^
  test/shapes_test.dart:39:27: Error: Undefined name 'Shape'.
        expect(Shape.rock > Shape.scissors, equals(true));

00:00 +0 -1: Some tests failed.

The tests are failing, this is normal, nothing has been created so far. Let fix that by creating a new file called lib/shapes.dart, it will contain our first implementation.

// file lib/shapes.dart

enum Shape {
  rock, paper, scissors;

  String toString() {           
    switch (this) {
      case rock: return "✊";
      case paper: return "🫳";
      case scissors: return  "✌";
    }
  }
}

Let re-invoke dart test to see if our implementation is working correctly.

$ dart test
00:00 +3: All tests passed!

It works! Now we need something to compare Shapes between them; for doing that, let playing with the default operators offered by dart, mainly used to compare numbers. Why not using them to compare Shapes?

// file test/shapes_test.dart

void shapeOperators() {
  group('Shapes Operators', () {
    test('rock operators', () {
      expect(Shape.rock > Shape.scissors, equals(true));
      expect(Shape.rock < Shape.paper, equals(true));
      expect(Shape.rock == Shape.rock, equals(true));
    });

    test('scissors operators', () {
      expect(Shape.scissors > Shape.paper, equals(true));
      expect(Shape.scissors < Shape.rock, equals(true));
      expect(Shape.scissors == Shape.scissors, equals(true));
    });

    test('paper operators', () {
      expect(Shape.paper > Shape.rock, equals(true));
      expect(Shape.paper < Shape.scissors, equals(true));
      expect(Shape.paper == Shape.paper, equals(true));
    });
  });
}

void main() {
  shapeRepresentation();
  shapeOperators();
}

As previously said, the test cases are grouped together. The code here describes how the Shapes will interact when using > (greater than) and < (less than) operators. The code is straightforward and explicit, but one could have done probably more tests with the help of the huge amount of function helpers offered by the test package, here a short list of them:

isFalse constant, ensure the final result is returning false as boolean;
isTrue constant, same than isFalse except it ensure the returned value is true;
isException() contant can be used to be sure the function will throw an exception;
contains() function checks if the returned values contain a specific objects;
fail() function throws a failure;
isA() function checks the type of the data returned;
same() function checks if 2 items are identical.

Anyway, let implement these new requested features to compare Shapes using our standard operators. To do that, we will create methods marked with the operator identifier. From the specification:

Operators are instance methods with special names, except for operator [] which is an instance getter and operator []= which is an instance setter. An operator declaration is identified using the built-in identifier operator.

-- Dart Programming Language Specification, Chapter 10, Section 2.1, page 37

In our case, the methods < and > will be created. They must return a boolean.

// file lib/shapes.dart

enum Shape {
  rock, paper, scissors;

  String toString() {           
    switch (this) {
      case rock: return "✊";
      case paper: return "🫳";
      case scissors: return  "✌";
    }
  }

  bool operator <(Shape other) {
    switch ((this, other)) {
      case (rock, paper): return true;
      case (rock, scissors): return false;
      case (paper, rock): return false;
      case (paper, scissors): return true;
      case (scissors, paper): return true;
      case (scissors, rock): return false;
      case (rock,rock): return false;
      case (paper,paper): return false;
      case (scissors,scissors): return false;
    }
  }

  bool operator >(Shape other) {
    switch ((this, other)) {
      case (rock, paper): return false;
      case (rock, scissors): return true;
      case (paper, rock): return true;
      case (paper, scissors): return false;
      case (scissors, paper): return true;
      case (scissors, rock): return false;
      case (rock,rock): return false;
      case (paper,paper): return false;
      case (scissors,scissors): return false;
    }
  }
}

Now the implementation is done, let runs the tests.

$ dart test
Building package executable... 
Built test:test.
00:00 +6: All tests passed!

Great, finally, we need an easy way to know if a shape versus another can be defined as a Win, a Loss or a Draw. It can be implemented as an exposed function from the module Shapes directly, we don't need something smart, just a function doing a comparison with two Shape.

// file test/shapes_test.dart

import 'package:rps/results.dart';

void shapeVersus() {
  print(shapes.versus(Shape.rock, Shape.scissors));
  group('Shapes Versus', () {
    test('rock', () {
      expect(
        shapes.versus(Shape.rock, Shape.scissors).toString(),
        equals("Win")
      );
      expect(
        shapes.versus(Shape.rock, Shape.rock).toString(),
        equals("Draw")
      );
      expect(
        shapes.versus(Shape.rock, Shape.paper).toString(),
        equals("Loss")
      );
    });
  });
}

New problem. How to represent a Draw, a Win and a Loss? Well, all can be seen as Result, so, let create at first an abstract class called Result first. Then, we can create the needed classes. This code will be stored in lib/results.dart.

// file lib/results.dart

abstract class Result {}

class Draw extends Result {
  toString() => "Draw";
}

class Win extends Result {
  toString() => "Win";
}

class Loss extends Result {
  toString() => "Loss";
}

Great, let work on the versus() function, we can implement it in many ways, let implement the easiest one, using the operators previously created.

// file lib/shapes.dart

Result versus(Shape left, Shape right) {
  if (left == right) return Draw();
  if (left > right) return Win();
  if (left < right) return Loss();
  throw("error");
}

Now our implementation is done, let check the tests.

$ dart test
00:00 +7: All tests passed!

Now we have a quick and dirty implementation of the different available Shapes in Jan Ken Pon, let have a look on the test package and all the features it offers us.

Test Reports

The test package offers a way to create test reports using reporters. The default reporter used is the compact one, only printing the sum of successful test or printing the errors. Another simple reporter is the expanded one, it will display more information about the test suite.

$ dart test --reporter=expanded
00:00 +0: loading test/rps_test.dart
00:00 +0: test/shapes_test.dart: Shapes Representation rock as raised fist unicode
00:00 +1: test/shapes_test.dart: Shapes Representation paper as palm down hand unicode
00:00 +2: test/shapes_test.dart: Shapes Representation scissors as victory hand unicode
00:00 +3: test/shapes_test.dart: Shapes Operators rock operators
00:00 +4: test/shapes_test.dart: Shapes Operators scissors operators
00:00 +5: test/shapes_test.dart: Shapes Operators paper operators
00:00 +6: test/shapes_test.dart: Shapes Versus rock

If your project is running on Github and you are using Github Actions, a specific reporter called github can be used and will output a Github friendly report.

$ dart test --reporter=github

::group::✅ Passing tests
✅ test/shapes_test.dart: Shapes Representation rock as raised fist unicode
✅ test/shapes_test.dart: Shapes Representation paper as palm down hand unicode
✅ test/shapes_test.dart: Shapes Representation scissors as victory hand unicode
✅ test/shapes_test.dart: Shapes Operators rock operators
✅ test/shapes_test.dart: Shapes Operators scissors operators
✅ test/shapes_test.dart: Shapes Operators paper operators
✅ test/shapes_test.dart: Shapes Versus rock
::endgroup::

🎉 7 tests passed.

Finally, if you are using your own CI/CD pipeline with Jenkins or Robot Framework, the result of the test can be returned as JSON with the json reporter.

$ dart test --reporter=json
{"protocolVersion":"0.1.1","runnerVersion":"1.31.1","pid":3420883,"type":"start","time":0}
{"suite":{"id":0,"platform":"vm","path":"test/rps_test.dart"},"type":"suite","time":0}
{"test":{"id":1,"name":"loading test/rps_test.dart","suiteID":0,"groupIDs":[],"metadata":{"skip":false,"skipReason":null},"line":null,"column":null,"url":null},"type":"testStart","time":0}
...
{"success":true,"type":"done","time":310}

Test Coverage

Generating a coverage report via dart test requires LCOV tool installed on your system. If you are using a Debian-like distribution, the LCOV package should be available.

$ sudo apt-get install lcov

To generate a new coverage report, simply use --coverage-path arguments. It will create the directory destination if it does not exist and generate the report.

$ dart run test --coverage-path=./_coverage/lcov.info
00:00 +7: All tests passed!

If you want to have an HTML report, the genhtml command usually present with the LCOV package is needed. It will generate an HTML report in the same directory the lcov.info file has been created.

$ genhtml -o _coverage/report ./_coverage/lcov.info 
Reading tracefile ./_coverage/lcov.info.
Found 3 entries.
Found common filename prefix "/dart/rps"
Generating output.
Processing file lib/rps.dart
  lines=2 hit=0
Processing file lib/results.dart
  lines=3 hit=3
Processing file lib/shapes.dart
  lines=28 hit=18
Overall coverage rate:
  source files: 3
  lines.......: 63.6% (21 of 33 lines)
  functions...: no data found
Message summary:
  no messages were reported

Now, the final result. See below the 3 levels of coverage from the top layer (a global view of the application) and the 2 other layers. The third one is the coverage from the module directly, indicating the numbers of time a line is called.

Conclusion

Testing an application with Dart is an easy task, the tools offered by default are doing what any developer is looking for, unit testing, test coverage and reports. It was a really quick introduction to this complex topic, we still have a lot of things to learn, like mocking techniques, test integration, testing frontend, backend or flutter and much more.

The skeleton of this project can be found in niamtokik/rps_dart repository on Github. If you are still there and want to know more, here a list of interesting resources:

Dart testing guide where you will find a quick introduction to testing and more resources;
Dart testing tutorial where you will find a complete test project example in Dart;
test package on pub.dev;
test package API documentation where you will find the full documentation of the test package;
test package source code on Github, where you will find the implementation of the test package;
Test-Driven Development (TDD) in Flutter: a Practical Guide with Runnable Examples by Oussama DX on Medium, where you will learn how to test Flutter;
Test-Driven Development (TDD) in Dart
by Ayatomide on Github, where you will an example of TDD in Dart;
Unit Testing (TDD) in Dart: A Beginners Guide Part I by Noor Ali on Medium where you will learn how to use TDD in Dart;
Test-Driven Development with Dart: Ensuring Code Quality by CloudDevs.

Have fun!

Cover Image by Tom Crew on Unsplash

Alternative Laptop Manufacturers

Mathieu Kerjouan — Thu, 04 Jun 2026 08:00:00 +0000

IBM/Lenovo was my first choice for the last 20 years when it comes to computers and laptops in particular. Unfortunately, the quality of these systems is slowly decreasing over time. Lenovo is doing nasty things with their recent models. Like Apple and other big manufacturers, plenty of their laptops are now sold with soldered RAM, hidden battery and many other displeasing “features”. Well, this is a bit sad, those laptops were great. Is it possible to find a professional alternative to them? A list of requirements before starting digging:

Multi-core with more than 32GB of RAM. Currently involved in Erlang development on projects consuming a huge amount of RAM and CPU, this is a must have. A system with at least 8 cores and 32GB RAM is the bare minimum in my case. An amd64 architecture is probably better, but any other should do the job as well.

Open-Source Friendly. This is one of the first important point, all my laptops must be compatible with at least OpenBSD and recent Linux distributions. It was fun to debug stuff 10 years ago, but my time is now too valuable to lose it by doing hardware/kernel hacking stuff.
Easy to repair. Fixing an hardware issue on Lenovo laptop was easy. Even too easy. In less than 5 minutes you can replace the RAM, remove a disk, change a fan… My first IBM/Lenovo laptop (a T42p) is still working today, and only few screws need to be removed to replace the most important port of the system.
Documented. It is a big plus to have a documentation on the hardware and a summary of all references in one place like in a PDF file. Lenovo offers this kind of solution and it saved me many time when looking for spares.
Battle Tested. More users means less hacking time. Using obscure laptops from odd manufacturers lead to long hacking session, trying to debug every part of something only one guy lost in China knows. Lenovo is still being used by most engineers and hackers around the world, a good manufacturers should also have this kind of “community”.
Hardened. This is another important point, but not vital. Most of the Lenovo in my collections were quite hard to break. They have not been approved with military grade, but they are hardened enough to survive most of the common issues of life.

These 5 points will generate a score, my own score, to choice one manufacturers between all of them. By the way, why this article? Well, I’m looking for a new laptop, and I was not able to find a decent list of open-source friendly devices on the web. Let’s get started!

Entroware

Entroware specialises in providing Ubuntu Linux based computing solutions and services for our clients' requirements. We have been manufacturing Ubuntu powered Desktops, Laptops, and Servers since early 2014, using only high quality components, both hardware and software.

Entroware is a company specialized in Linux/Ubuntu based computing and located in United Kingdom. They are creating laptops, desktops, workstations and servers. They give access to guides and tutorials.

You can follow them on X/Twitter or Facebook.

Framework

We’re here to remake consumer electronics to respect people and the planet. Unlike most products, ours are open for you to repair, customize, upgrade, and own at the deepest level.

Framework Computer is located in USA, offering an highly customizable and repairable laptop made to last. They are all 100% compatible with Ubuntu, Fedora, Ubuntu and Windows. An official forum and installation/repair guides are available. Documentation about this laptop can also be found on ArchLinux and Gentoo.

You can follow them on X/Twitter, Youtube, Instagram, Facebook, Linkedin and Github.

GPD Technology

GPD Gamepad Company Limited focus on developing high quality of Windows mini Laptop, UMPC and Android handheld game consoles since 2013. With our efforts and the trust from our customers, we have established a deep and long partnership with many overseas distributors all around the world. We proudly share 80% of the target market.

GPD Technology is a Chinese company, located in Hong Kong. The GPD Pocket 2 was my working tool for 4 months during my MakerTour. It was not really a good experience, the support was not really good and the keyboard was not designed for long coding session or writing articles. In other hand, it was quite powerful for its size and was after used to host local pipeline runners for test. The company itself is not really pro-open-source, but the hardware used is compatible with most of the modern Linux distributed available (it will require a bit of hacking sometimes though).

You can follow them on Youtube, X/Twitter, Facebook and TikTok.

Juno Computers

Juno Computers is a Linux computer company based in London, UK. Our goal is to help integrate Linux and non-Linux users to one friendly system. Offering an alternative to Windows and Apple. All of our machines come pre-installed with Ubuntu.

Juno Computers LTD is located in United Kingdom. Their devices to be highly compatible with open-source OS The official support page is quite small, giving only access to some commands to install drivers on Ubuntu/Debian distributions. They are active on Twitter and Facebook.

You can follow them on X/Twitter, Instagram, Linkedin and Facebook.

Malibal

MALIBAL is a forward-thinking technology company that produces high-performance, custom laptops, mobile workstations, and mobile servers. Our commitment is to user autonomy, data privacy, and the right to repair.

Malibal company is located in USA. They are manufacturing powerful open-source friendly laptops, also compatible with Windows.

You can follow them on X/Twitter

Minifree

Minifree Ltd (based in the United Kingdom) sells secure, high quality computer systems with Free, Libre, Open Source Software (FOSS) pre-installed.

Minifree is a company located in United Kingdom. They are reusing old IBM/Lenovo laptop and secures them by installing LibreBoot (open-source BIOS). All laptops are installed with an encrypted version of Debian or QubesOS. Most of the Lenovo laptops are highly compatible with open-source operating systems. If, like me, you like Lenovo, but you don't want to mess with your hardware, just take a moment to check their offers.

Mnt Reform

MNT Research is driven by the idea of a digital future that is open source, collaborative, and modular. Our users make the existence of MNT possible and we are dedicated to give back to them by creating open source hardware that is customizable, repairable, and modifiable.

The Mnt Reform is a crazy laptop project. The goal is to product an highly productive environment 100% compatible for open-source software. A lot of documentation and specifications can also be found. Their company is located in Germany and if you like retro-computing as well (like Amiga), you should really check their website and shop.

Nitrokey

Nitrokey is the world-leading company in open source security hardware. Nitrokey develops IT security hardware for data encryption, key management and user authentication, as well as secure network devices, PCs, laptops and smartphones.

Nitrokey is located in Germany. They are specialized in open-source security hardware and they are selling open-source compatible laptops, smartphones, tablets and desktops computers. Documentations about their products are quite complete

You can follow them on X/Twitter, Mastodon, Github, Youtube, Linkedin, Instagram and Facebook.

NovaCustom

Own. Your. Tech.

NovaCustom is located in Netherlands. They are manufacturing and selling highly compatible open-source hardware including laptops, desktop and smartphones. Some of their laptops are QubeOS certified. In case of issues, a public forum is available.

You can follow them on Mastodon, Reddit, Linkedin and Youtube.

Olimex

Olimex Ltd is a leading provider for IoT solutions, small Linux computers, development tools and programmers for embedded market.

Olimex is located in Bulgeria. They are mainly reselling electronics stuff, but have also DIY laptops available: the Teres A64.

You can follow them on X/Twitter, Github, Youtube, Facebook, Instagram and Mastodon.

Pyra

The DragonBox Pyra being the successor to the OpenPandora, means countless
improvements upon what was already a unique device. Sporting a feature-set not
found in any other mobile device.

Pyra is more like an open-source DIY projects than a reseller. The design seems a bit old-school. It looks like a cheap alternative to GPD laptops, but it is 100% open-source and libre.

Pinebook

Our goal is to push the envelope and deliver ARM and RISC-V devices that you want to use and develop for. To this end, we actively work with the development community and champion end-user initiatives. Rather than applying business to a FOSS setting, we allow FOSS principles to guide our business.

Pine64 team is offering laptops, smartphones and tablets based on ARM64 CPU. All their devices are highly documented and 100% compatible with open-source software.

You can follow them on X/Twitter and Mastodon.

Purism

We believe people should have technology that fully respects their freedoms. Being a social purpose company means doing social good for society before maximizing profits, and that makes us quite a different company indeed.

Purism is located in USA. They are selling open-source friendly smartphones, laptops, tablets and desktops. They also have created their own Linux distribution based on Debian called PureOS (see distrowatch).

Skikk

SKIKK does not believe in one-size-fits-all. We build laptops and mini PCs exactly the way you need them — for school, work, gaming or creativity. Customization at its best.

Skikk is located in Netherlands. They are selling open-source compatible laptops and desktops.

You can follow them on X/Twitter, Instagram, Youtube, Facebook and Linkedin.

Slimbook

Update it. Repair it. Enjoy it longer.
At Slimbook, we design our devices so you can upgrade, maintain, and repair them with ease. Because we believe in hardware that adapts to you and stays with you for years.

Slimbook is located in Spain. They are selling highly open-source compatible and repairable laptops, desktops and mini-PC. They are also offering their own Linux distribution based on Ubuntu and called SlimBookOS (see distrowatch).

You can follow them on X/Twitter, Facebook, Linkedin, Youtube, Instagram and Github.

Starlabs

Linux hardware, built to be owned. Privacy-conscious laptops, open firmware options, and repairable hardware designed for people who want control without turning every setup into a project.

Starlabs is an UK company. They are selling open-source friendly laptops and mini-PCs.

You can follow them on X/Twitter, Facebook, Instagram, Youtube and Github.

System76

System76 proudly engineers and manufactures premium Linux computers and keyboards at our factory in Denver, Colorado. Our user-driven products, alongside Pop!_OS, give creators, makers, and builders the means to bring forth the future.

System76 company is located in USA. They are selling open-source friendly hardware from laptops and desktops to servers and components. They are also in charge to maintain their own Linux distribution called Pop_OS based on Debian (see distrowatch).

You can follow them on X/Twitter, Linkedin, Github, Youtube, and Instagram.

Technoethical

Technoethical is an online shop that sells hardware compatible with operating systems that fully respect users' freedom as defined by the GNU Project.

Technoethical is located in Romania. They are selling mostly open-source compatible hardware and devices including laptops.

Think Penguin

ThinkPenguin, Inc. was founded in 2008 to improve support for GNU/Linux and other free software operating systems. The company's main objective has been to bring together the products, services, documentation, and support needed for users to confidently utilize free software operating systems.

ThinkPenguin is based in USA. They are selling a lot of open-source oriented hardware and devices, including desktop/servers and laptops.

Tuxedo Computers

At TUXEDO Computers you don't only get individually configurable Linux No‍te‍books und PCs, but also hardware that is perfectly optimized for running Linux!

Tuxedo Computers is based in Germany. They are selling high-end and high quality laptops and desktops. All their devices are open-source compatible. They created also their own Linux distribution called TuxedoOS based on Debian (see distrowatch).

You can follow them on Reddit, Facebook, Linkedin, and Mastodon.

Vikings

vikings specialises in fast and effective solutions for *Linux and *BSD environments, and their operation, ranging from day-to-day upkeep to solving complex challenges.

Vikings is located in Germany. This is not really a manufacturer, but they are recycling Lenovo laptops and configure them for more privacy. The list of laptop available is small, but if one is looking for cheap, robust and open source friendly devices, it can be a great choice.

Other Smaller projects/companies

Lot of open-source projects are offering their own laptop designs. In fact, more than 10 years ago, it was probably the only way to have a true open-source friendly laptop. The big problem is coming from their configuration (old) and all the hacks required to make them usable.

GenBook RK3588

The GenBook RK3588 made by the CoolPi is an affordable open-source laptop based on an ARM CPU with 32GB of RAM. The crowd-funding was stopped in December 2024. The full specification of this laptop is available on their website. The beast is available on AliExpress.

Novena

Remember Andrew Bunnie Huang? Yeah, the author of the amazing book "The Hardware Hacker: Adventures in Making and Breaking Harware" created an open-source laptop called Novena. I'm not sure if this project is still active, but it was a really great one.

CrowPi2

The Crowpi manufacturer offers solutions for Arduino-like platform. One of their project called CrowPi2 was created to offer a fully hackable laptop based on RasberryPi. If you are interested by electronics, embedded systems or to learn how a system works, it's probably a good choice.

Anyon_e

The Anyon_e project has been create by Byran Huang. The goal is to create an high end open-source friendly laptop. Everything about the project and the source code can be seen on the official repository on Github. I discovered this project recently and I don't know it is still active but this is a great initiative.

Loongson

Loongson is a Chinese company already created few laptops in the past with their own MIPS-like CPU. I got one more than 10 years ago to play with it, it was usable, but the system was pretty slow and the support not so good, but most of the hardware - if not all - was open-source. This hardware is still supported by many project like Debian, OpenBSD or NetBSD. In 2025, they announced working on another laptop, so, maybe a new open-source friendly laptop will be available. The Loongson CPU/architecture documentation can easily be found online.

Note: for the one thinking CCP will spy on their movement, you should probably think about what the CIA and NSA did during past years on their own citizens and allies. A lot of hardware is already corrupted and backdoored, this is not a news, it has been reveled by Assange and Snowden more than 10 years ago.

Conclusion

Even in 2026, it's still hard to find a decent laptop in this ecosystem. Lot of choice but their is a lake of resources and objective reviews. I will stay on my good old Lenovo laptops, they are working pretty well with all Linux distributions and OpenBSD, that's all I need. Yes, they are a bit expensive, but in fact, open-source friendly hardware are not cheap either. Anyway, at least, you can have an exhaustive list of the alternative available today!

Have fun!

Cover Image by Logan Voss on Unsplash

Standalone HTTP Server in Elixir with Bandit

Mathieu Kerjouan — Wed, 03 Jun 2026 08:00:00 +0000

Writing Elixir code is not really exciting to me, but, to be honest, if someone today wants to create an application from scratch and is looking for a big pool developers and a battle tested distributed infrastructure (the BEAM VM), Elixir is probably one of the best choice nowadays. The community is active, the documentation is great, the language looks like a mix between Ruby and Python, without the annoying object part and with all the good feature from Erlang. This is why, today, we will use Elixir with bandit to create a minimal web server supporting both HTTP and WebSockets.

bandit has been created as an alternative to cowboy, fully coded in Elixir and designed to be integrated and highly compatible with the Phoenix framework. When it came out few years ago, the community did a lot of noise and I never find a moment to test it. bandit supports HTTP/1.1 and HTTP/2 natively. WebSockets protocols support can be added with the help of WebSock and WebSockAdapter modules. At this time, it does not support HTTP/3 (yet?).

The idea here is not to follow blindly the Phoenix framework documentation and to create yet another website-like-project, but just to learn how to use bandit API, a bit like I did in a previous publication on cowboy. Let start our journey by creating a new Elixir library called desperados. It will contain all our experiments.

Bootstrapping

Elixir is using Mix as project manager. To create a new library-like project, one can simply call mix new command

$ mix new desperados

A library template project should have been generated into the desperados directory. I will not create an application or an umbrella for now, I just want something minimalist to break. It also means the application will be started manually, usually with a start like function.

Starting Bandit

The first file to modify is lib/desperados.ex, it will contain the methods to start and stop the application. Let simply implement start_link/1 and start_link/0 for now.

defmodule Desperados do
  def start_link do
    start_link([
      {:plug, Desperados.Plugs},
      {:scheme, :http},
      {:port, 8082},
      {:ip, :any},
      {:startup_log, :debug}
    ])
  end

  def start_link(opts) do
    Bandit.start_link(opts)
  end
end

bandit is using thousand_island to manage the transport layer (TCP). This project is also a rewrite of ranch in pure Erlang and designed for the Phoenix framework. The function to start a new bandit server is Bandit.start_link/1. The unique argument passed to it contains the options() to configure the server.

The smallest configuration is to only set a Plug handler. This Plug callback is mandatory. In fact, when using bandit with Phoenix, this callback can be seen as the Phoenix router. Anyway, to work correctly, a Plug handler is required, so let call it Desperados.Plug for now. The rest of the options are for configuring the server itself

Anatomy of a `Plug`

A Plug is a piece of code containing mandatory callback functions (behaviours) to manage initialization, connections, requests and events. These callbacks functions are following a contract (specification) and must return a certain kind of value. If you are more familiar with Erlang, one can think of a middleware in cowboy. The Plug concept is the foundation of any Phoenix application.

Why Plugs are great? Well, because they are following a contract, those modules can be connected together using a pipeline. The output of one Plug can be the input of another one. This kind of concept makes everything easier. You can see that a bit like a layer of features, where every Plug will deal with only with one request passing through one Plug at a time (e.g. authentication, sanitization...) and the "final" value returned by one of those Plug will be the response to the client.

Let create the most simple Plug possible, Desperados.Plugs.Inspect, a simple Plug to inspect the %Plug.Conn{} data structure passed in the first argument of the call/2 function callback. This file will be created under lib/desperados/plugs directory and called inspect.ex.

defmodule Desperados.Plugs.Inspect do
  @behaviour Plug

  def init(_args), do: {:ok, %{}}

  def call(conn, _state) do
    IO.inspect(conn)
  end
end

A Plug is a concise module, when a request is coming to the server from a client, the first callback executed is init/1, it will simply initialize the the Plug using some kind of arguments passed previously. In this step, a state can be defined, in our case, an empty Map is returned. This state will be then be passed to other callback functions.

If the initialization phase was a success, then the server will call the call/2 function callback with the full request in the first argument using a %Plug.Conn{} data structure and the state previously returned by the init/1 function.

This new plug can be directly used in the Bandit.start_link/1 options but well, I told you previously we can pipeline Plugs together. This feature is already available by default in Phoenix when using the Router plugs feature. We are not using Phoenix, but, we can use Plug.Builder to create our own Plug router using Plug.Builder. Let create a new modules called Desperados.Plugs in lib/desperados/plugs.ex. It will contain the following code:

defmodule Desperados.Plugs do
  use Plug.Builder
  plug Desperados.Plugs.Inspect
end

The Plug.Builder module offers the plug macro. After compilation, all the plugs defined are then put together in a pipeline, where the first defined will be executed at first and the last one, executed during the last step. Let start our minimal configuration right now using iex.

$ iex -S mix
Erlang/OTP 28 [erts-16.0.1] [source] [64-bit] [smp:16:16] [ds:16:16:10] [async-threads:1] [jit:ns]

Interactive Elixir (1.19.5) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> Desperados.start_link

13:31:27.131 [debug] Running Desperados.Plugs with Bandit 1.11.1 at 0.0.0.0:8082 (http)
{:ok, #PID<0.214.0>}

It seems good, the server is started. We can now use curl to check that.

$ curl -svfq http://localhost:8082/test; echo $?
* Host localhost:8082 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* HTTPS-RR: -
*   Trying [::1]:8082...
* connect to ::1 port 8082 from ::1 port 38724 failed: Connection refused
*   Trying 127.0.0.1:8082...
* Established connection to localhost (127.0.0.1 port 8082) from 127.0.0.1 port 42484 
* using HTTP/1.x
> GET /test HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/8.20.0
> Accept: */*
> 
* Request completely sent off
< HTTP/1.1 500 Internal Server Error
< connection: close
* The requested URL returned error: 500
< 
* closing connection #0
22

Ah! It returns an error an error 500! Let check the console on iex to see what happened...

%Plug.Conn{
  adapter: {Bandit.Adapter, :...},
  assigns: %{},
  body_params: %Plug.Conn.Unfetched{aspect: :body_params},
  cookies: %Plug.Conn.Unfetched{aspect: :cookies},
  halted: false,
  host: "localhost",
  method: "GET",
  owner: nil,
  params: %Plug.Conn.Unfetched{aspect: :params},
  path_info: ["test"],
  path_params: %{},
  port: 8082,
  private: %{},
  query_params: %Plug.Conn.Unfetched{aspect: :query_params},
  query_string: "",
  remote_ip: {127, 0, 0, 1},
  req_cookies: %Plug.Conn.Unfetched{aspect: :cookies},
  req_headers: [
    {"host", "localhost:8082"},
    {"user-agent", "curl/8.20.0"},
    {"accept", "*/*"}
  ],
  request_path: "/test",
  resp_body: nil,
  resp_cookies: %{},
  resp_headers: [{"cache-control", "max-age=0, private, must-revalidate"}],
  scheme: :http,
  script_name: [],
  secret_key_base: nil,
  state: :unset,
  status: nil
}

13:32:18.749 [error] ** (Plug.Conn.NotSentError) a response was neither set nor sent from the connection
    (bandit 1.11.1) lib/bandit/pipeline.ex:169: Bandit.Pipeline.commit_response!/1
    (bandit 1.11.1) lib/bandit/pipeline.ex:46: Bandit.Pipeline.run/5
    (bandit 1.11.1) lib/bandit/http1/handler.ex:13: Bandit.HTTP1.Handler.handle_data/3
    (bandit 1.11.1) lib/bandit/delegating_handler.ex:18: Bandit.DelegatingHandler.handle_data/3
    (bandit 1.11.1) lib/bandit/delegating_handler.ex:8: Bandit.DelegatingHandler.handle_continue/2
    (stdlib 7.0.1) gen_server.erl:2424: :gen_server.try_handle_continue/3
    (stdlib 7.0.1) gen_server.erl:2291: :gen_server.loop/4
    (stdlib 7.0.1) proc_lib.erl:333: :proc_lib.init_p_do_apply/3

iex(2)>

It "works", at least, the conn argument is printed to stdout but the application print also an error. In fact, this is normal, the request does not return a response to the client and then, bandit throw an Plug.Conn.NotSentError error. To avoid this kind of issue, a Plug must give a response to a client. Let fix that in the next section.

Quick note regarding a Plug, it's also possible to create one using a function, in this case, the first argument passed must be a %Plug.Conn{} and the second argument can be anything (options).

Anyway, if you want to know a bit more about a plug, check those links:

The official Plug documentation API where you will find great example and the description of the behavior;
The official phoenix Plug tutorial, wwhere you will find how plugs are working when using them in a Phoenix project;
Plug source code on Github, where you will understand how the plug's macros have been implemented;
Plug.Router source code on Github, where you will understand how the router has been implemented using mostly Elixir macros;
Plug.Builder source code on Github where you will learn how the Plug Builder has been created and how the pipeline is working under the hood.

Dealing with HTTP Requests

We can print the connections/requests received with Desperados.Plugs.Inspect Plug, but it's a bit useless. It returns an error to the client and except for debugging purpose, there are no real values. Let create a new module called Desperados.Endpoints.HTTP to deal with the HTTP requests. A new file in lib/desperados/endpoints/http.ex can be created.

defmodule Desperados.Endpoints.HTTP do
  @behaviour Plug
  import Plug.Conn

  def init(_opts), do: {:ok, %{}}

  def call(conn, _state) do
    send_resp(conn, 404, "not found")
  end
end

The Plug structure is the very same than the previous one we just created. We have the init/1 function callback doing mostly nothing and then we have the call/2 function doing something interesting. When a request is received, this plug will call Plug.Conn.send_resp/3 function to reply a message to the client. In our case, this code is simply returning the code 404 with the message "not found". Let add this in our Desperados.Plugs "pipeline".

defmodule Desperados.Plugs do
  use Plug.Builder
  plug Desperados.Plugs.Inspect
  plug Desperados.Endpoints.HTTP
end

The project can now be recompiled in live using recompile function inside the iex shell.

iex(2)> recompile
:ok

Great. curl can now be used to request the server with a GET method. If it works, it should return a 404 not found.

$ curl -v http://localhost:8082/test
* Host localhost:8082 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* HTTPS-RR: -
*   Trying [::1]:8082...
* connect to ::1 port 8082 from ::1 port 34846 failed: Connection refused
*   Trying 127.0.0.1:8082...
* Established connection to localhost (127.0.0.1 port 8082) from 127.0.0.1 port 35288 
* using HTTP/1.x
> GET /test HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/8.20.0
> Accept: */*
> 
* Request completely sent off
< HTTP/1.1 404 Not Found
< date: Sat, 30 May 2026 11:57:36 GMT
< content-length: 9
< vary: accept-encoding
< cache-control: max-age=0, private, must-revalidate
< 
* Connection #0 to host localhost:8082 left intact
not found

No more errors, Desperados.Endpoints.HTTP is returning an "awesome" 404 not found.

%Plug.Conn{
  adapter: {Bandit.Adapter, :...},
  assigns: %{},
  body_params: %Plug.Conn.Unfetched{aspect: :body_params},
  cookies: %Plug.Conn.Unfetched{aspect: :cookies},
  halted: false,
  host: "localhost",
  method: "GET",
  owner: nil,
  params: %Plug.Conn.Unfetched{aspect: :params},
  path_info: ["test"],
  path_params: %{},
  port: 8082,
  private: %{},
  query_params: %Plug.Conn.Unfetched{aspect: :query_params},
  query_string: "",
  remote_ip: {127, 0, 0, 1},
  req_cookies: %Plug.Conn.Unfetched{aspect: :cookies},
  req_headers: [
    {"host", "localhost:8082"},
    {"user-agent", "curl/8.20.0"},
    {"accept", "*/*"}
  ],
  request_path: "/test",
  resp_body: nil,
  resp_cookies: %{},
  resp_headers: [{"cache-control", "max-age=0, private, must-revalidate"}],
  scheme: :http,
  script_name: [],
  secret_key_base: nil,
  state: :unset,
  status: nil
}
iex(3)>

No crashes on the server side anymore as well. The conn variable is still correctly printed to STDOUT and everything is working correctly. Is it? Well, perhaps not, what about WebSocketd support?

$ curl -v ws://localhost:8082/test
* Host localhost:8082 was resolved.                                                                     * IPv6: ::1
* IPv4: 127.0.0.1
* HTTPS-RR: -
*   Trying [::1]:8082...
* connect to ::1 port 8082 from ::1 port 52100 failed: Connection refused
*   Trying 127.0.0.1:8082...
* Established connection to localhost (127.0.0.1 port 8082) from 127.0.0.1 port 43686 
* using HTTP/1.x
> GET /test HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/8.20.0
> Accept: */*
> Upgrade: websocket
> Sec-WebSocket-Version: 13
> Sec-WebSocket-Key: mkqOjlvEfpDPU53U0uVnHw==
> Connection: Upgrade
> 
* Request completely sent off
< HTTP/1.1 404 Not Found
< date: Sat, 30 May 2026 11:59:43 GMT
< content-length: 9
< vary: accept-encoding
< cache-control: max-age=0, private, must-revalidate
* Refused WebSocket upgrade: 404
< 
* closing connection #0
curl: (22) Refused WebSocket upgrade: 404

Ah! It does not work... Let fix that in the next section then. Anyway, if you want to know more about managing HTTP requests with Plugs, you should also check those links:

Plug.Conn module documentation
Plug.Conn source code on Github

Dealing with WebSockets

bandit does not offer WebSockets natively and depends of 2 modules for doing that: WebSock and WebSockAdapter. The first one is used to deal with the events by "extending" the Plug behavior, the second one is used to initialize the WebSocket link with the client. The creation of a small Plug in charge of WebSockets connection still remains easy to implement. Let create a new endpoint called Desperados.Endpoints.Websocket.

defmodule Desperados.Endpoints.Websocket do
  @behaviour Plug

  def init(_opts) do
    state = %{count: 0}
    {:ok, state}
  end

  def call(conn, _state) do
    WebSockAdapter.upgrade(conn, __MODULE__, %{}, timeout: 60_000)
    |> Plug.Conn.halt()
  end
  def call(conn, _opts), do: IO.inspect(conn)

  def handle_in(_event = {"ping\n", [opcode: opcode]}, state) do
    {:reply, :ok, {opcode, "pong\n"},
      state 
      |> Map.update(:count, 0, fn value ->
        value+1
      end)
    }
  end
  def handle_in(_event = {data, opcode: opcode}, state) do
    {:reply, :ok, {opcode, data}, state}
  end
end

This Plug assumes the client is starting to upgrade the HTTP connection to a WebSocket one. During the call/2 callback, the WebSockAdapter.upgrade/4 function is called to acknowledge the upgrade. The first argument is the connection, the second one is the module callback (in our case the name of the current module), the third argument is a state and fourth arguments are websocket connection options. If the handshake is valid, this function will give the control to this connection to a WebSock process.

In this situation, every time an events (e.g. messages) are received, they are transmitted to the handle_in/2 function callback. The Plug router can be modified,

defmodule Desperados.Plugs do
  use Plug.Builder
  plug Desperados.Plugs.Inspect
  plug Desperados.Endpoints.Websocket
end

The Desperados.Endpoints.HTTP has been removed there, because the pipeline cannot support both HTTP and WebSockets at the same time (for now). Again, let recompile the project.

iex (3)> recompile
:ok

curl can now be used again, this time as a WebSocket client.

$ curl -vT. --no-progress-meter ws://localhost:8082/test
* Host localhost:8082 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* HTTPS-RR: -
*   Trying [::1]:8082...
* connect to ::1 port 8082 from ::1 port 36962 failed: Connection refused
*   Trying 127.0.0.1:8082...
* Established connection to localhost (127.0.0.1 port 8082) from 127.0.0.1 port 56496 
* using HTTP/1.x
> GET /test HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/8.20.0
> Accept: */*
> Upgrade: websocket
> Sec-WebSocket-Version: 13
> Sec-WebSocket-Key: GIPpTnAnww9DUOoZGJSiYg==
> Connection: Upgrade
> 
* Request completely sent off
< HTTP/1.1 101 Switching Protocols
< date: Sat, 30 May 2026 18:12:50 GMT
< upgrade: websocket
< connection: Upgrade
< sec-websocket-accept: aMzngyTPS2svr8fgKowmhG9vb44=
< cache-control: max-age=0, private, must-revalidate
< 
* Received 101, Switching to WebSocket
* [WS] Received 101, switch to WebSocket
test
} [11 bytes data]
test
test
test
* upload completely sent off: 22 bytes

It works as expected, the WebSocket server is returning the messages we are sending. Now, I would like to also implement something neat, a plug to detect if the client wants to upgrade the connection and assign a :websocket tag to it if it's the case. In short: one path with HTTP and WebSocket support. Let create that in the next section.

If you want to know more about WebSockets in Elixir, here few links to read:

WebSockAdapter API documentation, where you will learn how to upgrade an HTTP connection to a WebSocket one, including all available parameters;
WebSock API documentation, where you will learn how to create a WebSocket callback module using the WebSock behavior;
WebSockAdapter module source code where all the transition between HTTP to WebSocket happens;
WebSock module source code where the WebSock behavior is implemented;
The Hello world websockets Plug example for Phoenix framework application

HTTP/WebSockets Multi Protocol Endpoint

Usually, one path only is set with WebSocket support. On many examples, one can see /ws endpoint is dedicated for this task but what if one is able to bypass this convention and let a path be compatible with both HTTP and WebSockets? Yeah, it's a bit dirty, but it's also a good way to learn how WebSockets is working.

The WebSockets protocol is starting with the client requesting a connection upgrade containing at least 3 mandatory HTTP headers:

Upgrade set with the string websocket;
Sec-WebSocket-Version set with the version (or the list of versions) of the WebSocket protocol to use;
Sec-WebSocket-key set with a random string (usually a base64 one) and mostly used to ensure this is a correct WebSocket connection requested by the client.

With this information, a Plug can be created to check if those headers are present in the request. If it's the case, we can be pretty sure this is a WebSocket request from a client, else, this is probably a simple HTTP request. Let create a new Plug called Desperados.Plugs.Websocket to help us identify those kind of connections.

defmodule Desperados.Plugs.Websocket do
  @behaviour Plug
  import Plug.Conn

  def init(_args), do: {:ok, %{}}

  def call(conn, state), do: header_upgrade(conn, state)

  defp header_upgrade(conn, state) do
    case get_req_header(conn, "upgrade") do
      [v = "websocket"] ->
        conn
        |> assign(:ws_info, [v])
        |> header_version(state)
      _ ->
        conn
    end
  end

  defp header_version(conn = %Plug.Conn{assigns: %{ws_info: ws}}, state) do
    case get_req_header(conn, "sec-websocket-version") do
      [v] ->
        conn
        |> assign(:ws_info, [v|ws])
        |> header_key(state)
      _ ->
        conn
    end
  end
  defp header_version(conn, _state), do: conn

  defp header_key(conn = %Plug.Conn{assigns: %{ws_info: ws}}, state) do
    case get_req_header(conn, "sec-websocket-key") do
      [k] ->
        conn
        |> assign(:ws_info, [k|ws])
        |> final(state)
      _ ->
        conn
    end
  end
  defp header_key(conn, _state), do: conn

  defp final(conn = %Plug.Conn{assigns: %{ws_info: [_,_,_]}}, _state) do
    assign(conn, :websocket, true)
  end
  defp final(conn, _state), do: conn
end

This is not a really complex Plug, every functions are acting like a waterfall, the first one is looking for the Upgrade header, if it's present, then it will call the second function. This one will look for the Sec-Websocket-Version header, if it's present, then it will call the third function to check if the Sec-Websocket-Key can be found. If those 3 headers are present, the :websocket key set to true is assigned to the connection.

The Desperados.Endpoints.Websocket needs a small patch now, to only start the upgrading process when a connection has the :websocket key assigned.

defmodule Desperados.Endpoints.Websocket do
  @behaviour Plug

  def init(_opts) do
    state = %{count: 0}
    {:ok, state}
  end

  def call(conn = %Plug.Conn{assigns: %{websocket: true}}, _state) do
    WebSockAdapter.upgrade(conn, __MODULE__, %{}, timeout: 60_000)
    |> Plug.Conn.halt()
  end
  def call(conn, _opts), do: IO.inspect(conn)

  def handle_in(_event = {"ping\n", [opcode: opcode]}, state) do
    {:reply, :ok, {opcode, "pong\n"},
      state 
      |> Map.update(:count, 0, fn value ->
        value+1
      end)
    }
  end
  def handle_in(_event = {data, opcode: opcode}, state) do
    {:reply, :ok, {opcode, data}, state}
  end
end

The magic in the call/2 callback function, with the pattern %Plug.Conn{assigns: %{websocket: true}}. If it matches, then the connection will be upgraded, else, it will simply returns the raw connection to the pipeline.

Plug Pipeline

This is mostly done, one of the last section of this post. We have previously created a Plug to print the connection data-structure to stdout, then, a Plug to deal with HTTP requests and another one to deal with WebSockets. Another one was created to alter the connection data-structure and identify if a client is trying to initiate a WebSocket connection. Let update our pipeline.

defmodule Desperados.Plugs do
  use Plug.Builder

  plug Desperados.Plugs.Websocket
  plug Desperados.Endpoints.Websocket
  plug Desperados.Endpoints.HTTP
end

Lean, isn't it? The first Plug will check the client request to see if it's a WebSocket upgrade, if it's the case, the second Plug will deal with it, else, the HTTP Plug will do the job. Desperados.Plugs.Inspect as be removed, it's currently not necessary to have it, but it can be added whenever needed.

Final Test

This is the final part of this post, and it's now the time to test all the features. A test suite would have been the best thing to do, but this publication is already too long. Let just restart the application from scratch and play with curl.

$ iex -S mix
Erlang/OTP 28 [erts-16.0.1] [source] [64-bit] [smp:16:16] [ds:16:16:10] [async-threads:1] [jit:ns]

Interactive Elixir (1.19.5) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> Desperados.start_link()

20:11:42.808 [debug] Running Desperados.Plugs with Bandit 1.11.1 at 0.0.0.0:8082 (http)
{:ok, #PID<0.245.0>}

Let run the curl WebSocket test:

$ curl -vT. --no-progress-meter ws://localhost:8082/test
* Host localhost:8082 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* HTTPS-RR: -
*   Trying [::1]:8082...
* connect to ::1 port 8082 from ::1 port 43916 failed: Connection refused
*   Trying 127.0.0.1:8082...
* Established connection to localhost (127.0.0.1 port 8082) from 127.0.0.1 port 39416 
* using HTTP/1.x
> GET /test HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/8.20.0
> Accept: */*
> Upgrade: websocket
> Sec-WebSocket-Version: 13
> Sec-WebSocket-Key: 7S1xZKpgqoGgC+gI3dtKyQ==
> Connection: Upgrade
> 
* Request completely sent off
< HTTP/1.1 101 Switching Protocols
< date: Sat, 30 May 2026 18:42:15 GMT
< upgrade: websocket
< connection: Upgrade
< sec-websocket-accept: jLWCKodpG0BsuWJT39MhgZTNLq8=
< cache-control: max-age=0, private, must-revalidate
< 
* Received 101, Switching to WebSocket
* [WS] Received 101, switch to WebSocket
test
} [11 bytes data]
test
test
test
* upload completely sent off: 22 bytes

Let run the curl HTTP test:

$ curl -v http://localhost:8082/test
* Host localhost:8082 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* HTTPS-RR: -
*   Trying [::1]:8082...
* connect to ::1 port 8082 from ::1 port 40422 failed: Connection refused
*   Trying 127.0.0.1:8082...
* Established connection to localhost (127.0.0.1 port 8082) from 127.0.0.1 port 34666 
* using HTTP/1.x
> GET /test HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/8.20.0
> Accept: */*
> 
* Request completely sent off
< HTTP/1.1 404 Not Found
< date: Sat, 30 May 2026 18:42:54 GMT
< content-length: 9
< vary: accept-encoding
< cache-control: max-age=0, private, must-revalidate
< 
* Connection #0 to host localhost:8082 left intact
not found

This is working! More is needed to make it production ready, but a client can use both HTTP or WebSockets protocol with the same endpoint! Yeah, that's not really useful, but it was a small objective just to demonstrate how Plugs can be used.

Conclusion

The code required to create a really small HTTP/WebSocket server is incredibly lean. That's a good thing. Even more, if we are trusting the documentation, bandit is faster than cowboy. If we add the Elixir/Phoenix ecosystem, one can create a strong backend in a short amount of time with a huge ton of features.

Have fun!

Cover Image by Richie Bettencourt on Unsplash

WebSocket and curl

Mathieu Kerjouan — Tue, 02 Jun 2026 08:00:00 +0000

In a previous publication I was talking about the lake of WebSocket support from curl, but it seems I was not using the latest version at this time. I retried that with the 8.20.0 release after reading "websocket in curl" post by Stefan Eissing. It's not "perfect" but it works like netcat.

The first step is to fetch/install the latest curl version for your system, at this time, the 8.20.0 release

$ wget https://github.com/stunnel/static-curl/releases/download/8.20.0/curl-linux-x86_64-glibc-8.20.0.tar.xz
$ tar xvf curl-linux-x86_64-glibc-8.20.0.tar.xz
$ ./curl --version
curl 8.20.0 (x86_64-pc-linux-gnu) libcurl/8.20.0 OpenSSL/4.0.0 zlib/1.3.2 brotli/1.2.0 zstd/1.5.7 c-ares/1.34.6 libidn2/2.3.8 libpsl/0.21.5 libssh2/1.11.1 nghttp2/1.69.0 ngtcp2/1.22.1 nghttp3/1.15.0
Release-Date: 2026-04-29
Protocols: dict file ftp ftps gopher gophers http https imap imaps ipfs ipns mqtt mqtts pop3 pop3s rtsp scp sftp smtp smtps telnet tftp ws wss
Features: alt-svc asyn-rr AsynchDNS brotli ECH HSTS HTTP2 HTTP3 HTTPS-proxy HTTPSRR IDN IPv6 Largefile libz PSL SSL SSLS-EXPORT threadsafe TLS-SRP UnixSockets zstd

Then we can use it against a WebSocket server, let try it with buckaroo project.

$ ./curl -T. -kv --no-progress-meter ws://127.0.0.1:8081/ws
*   Trying 127.0.0.1:8081...
* Established connection to 127.0.0.1 (127.0.0.1 port 8081) from 127.0.0.1 port 43194 
* using HTTP/1.x
> GET /ws HTTP/1.1
> Host: 127.0.0.1:8081
> User-Agent: curl/8.20.0
> Accept: */*
> Upgrade: websocket
> Sec-WebSocket-Version: 13
> Sec-WebSocket-Key: Y7nHv/MjumObou+aYHQJTg==
> Connection: Upgrade
> 
* Request completely sent off
< HTTP/1.1 101 Switching Protocols
< connection: Upgrade
< date: Wed, 27 May 2026 13:01:47 GMT
< sec-websocket-accept: nYSHGW+IDHwj5BJCocg6kA6Jsz8=
< server: Cowboy
< upgrade: websocket
< 
* Received 101, Switching to WebSocket
* [WS] Received 101, switch to WebSocket
{ [5 bytes data]
test
heytest
hello!
hello!
* upload completely sent off: 24 bytes

It... Works! Curl is still one of the greatest open-source software available on this planet. Having the power to use a WebSocket like netcat with curl is really really cool.

Have fun!

Cover Image by Sebastian Schuster on Unsplash

HTTP/3 and QUIC in Erlang with Cowboy

Mathieu Kerjouan — Mon, 01 Jun 2026 08:00:00 +0000

Since Cowboy 2.14.0 an experimental implementation of HTTP/3 (or QUIC or RFC9000) has been released. That's a pretty good news, and if stable enough, will change a lot on the web ecosystem. Unfortunately, this feature is not documented yet - because unstable - but it's not a good reason to play with it and try to understand how to configure a cowboy server with HTTP/3 and QUIC.

Cowboy does not support natively QUIC and depends on quicer application to work correctly. To be clear, this is a BIG NO-NO for a deployment in production environment. The list of dependencies directly required by quicer is insane, it fetch many python-like modules and recompile OpenSSL from scratch (OpenSSL 3.1.7+quic, from an unmaintained and archived repository, with all security issues that could implies).

Anyway, the COWBOY_QUICER Erlang macro must be set to 1 to compile cowboy with HTTP/3 and QUIC support. Then, the rebar.config file will need few modifications. The configuration for the cowboy dependency must be overridden and the previous macro must be activated. The quicer depency is also required, because this is an experimental feature, cowboy does not include it. To test that, let reuse the buckaroo project created in a previous publication.

{erl_opts, [
  debug_info
]}.
{deps, [
  cowboy,
  quicer
]}.
{shell, [{apps, [buckaroo]}]}.
{overrides, [
  {add, cowboy, [
    {erl_opts, [
      {d, 'COWBOY_QUICER', 1}
    ]}
  ]}
]}.

A cleanup will be also required there with a full recompilation from scratch of all the dependencies.

$ rm -rf _build
$ rebar3 compile
...

In theory, after this step, cowboy should now be able to start a QUIC server and use HTTP/3. At least, an Erlang shell can be started without problem, and it seems buckaroo is running correctly.

$ rebar3 shell
===> Verifying dependencies...
===> Analyzing applications...
===> Compiling buckaroo
Erlang/OTP 29 [erts-17.0] [source] [64-bit] [smp:16:16] [ds:16:16:10] [async-threads:1] [jit:ns]

Eshell V17.0 (press Ctrl+G to abort, type help(). for help)
===> Booted cowlib
===> Booted ranch
===> Booted cowboy
===> Booted buckaroo
1>

A TLS certificate is required, we don't need to create a clean one, simply generating a self-signed with openssl req for now will do the job.

$ openssl req -x509 -newkey rsa:4096 \
  -keyout key.pem \
  -out cert.pem \
  -sha256 \
  -days 3650 \
  -nodes -subj \
  "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname"

If the certificate has been correctly created, quicer can be started via cowboy with the help of cowboy:start_quic/3 function. This function is not exposed by default and to have access to it, one must compile cowboy with COWBOY_QUIC macro enabled (what we configured previously). Anyway , to add this step, we can modify the buckaroo_cowboy module by creating a new function called start_quic/3. Most of the parameters will be reused from the normal way to start cowboy.

start_quic() ->
  application:ensure_all_started(quicer),
  cowboy:start_quic(
    name(),
    #{
      socket_opts => transport_options() ++ [
        {certfile, "cert.pem"},
        {keyfile, "key.pem"}
      ]
    },
    protocol_options()
  ).

Let start the application now.

$ rebar3 shell
===> Verifying dependencies...
===> Analyzing applications...
===> Compiling buckaroo
Erlang/OTP 29 [erts-17.0] [source] [64-bit] [smp:16:16] [ds:16:16:10] [async-threads:1] [jit:ns]

Eshell V17.0 (press Ctrl+G to abort, type help(). for help)
===> Booted cowlib
===> Booted ranch
===> Booted cowboy
===> Booted buckaroo
1> buckaroo_cowboy:start_quic().
{ok,#Ref<0.2047991422.1293549576.157826>}
2>

The service started... Okay, that's a good step but we still need to be sure it is listening on the right port and see if it's working correctly. Let use ss (or netstat if you are using another OS).

$ ss -nlpu sport 8081
State   Recv-Q  Send-Q   Local Address:Port   Peer Address:Port Process                                  
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=86))  
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=90))  
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=94))  
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=98))  
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=102)) 
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=106)) 
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=110)) 
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=114)) 
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=118)) 
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=122)) 
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=126)) 
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=130)) 
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=134)) 
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=138)) 
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=142)) 
UNCONN  0       0                    *:8081              *:*     users:(("beam.smp",pid=2784595,fd=146))

A QUIC service must listen on UDP, and this is the case. The output of ss command returns the what we are looking for, an application (beam.smp) listening to all interfaces on UDP/8082.

$ curl -kv --http3-only https://localhost:8081/; echo
* Host localhost:8081 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* HTTPS-RR: -
*   Trying [::1]:8081...
* SSL Trust: peer verification disabled
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384 / x25519 / RSASSA-PSS
* Server certificate:
*   subject: C=XX; ST=StateName; L=CityName; O=CompanyName; OU=CompanySectionName; CN=CommonNameOrHostname
*   start date: May 27 04:15:27 2026 GMT
*   expire date: May 24 04:15:27 2036 GMT
*   issuer: C=XX; ST=StateName; L=CityName; O=CompanyName; OU=CompanySectionName; CN=CommonNameOrHostname
*   Certificate level 0: Public key type RSA (4096/152 Bits/secBits), signed using sha256WithRSAEncryption
* OpenSSL verify result: 12
*  SSL certificate verification failed, continuing anyway!
* Established connection to localhost (::1 port 8081) from ::1 port 33253 
* using HTTP/3
* [HTTP/3] [0] OPENED stream for https://localhost:8081/
* [HTTP/3] [0] [:method: GET]
* [HTTP/3] [0] [:scheme: https]
* [HTTP/3] [0] [:authority: localhost:8081]
* [HTTP/3] [0] [:path: /]
* [HTTP/3] [0] [user-agent: curl/8.20.0]
* [HTTP/3] [0] [accept: */*]
> GET / HTTP/3
> Host: localhost:8081
> User-Agent: curl/8.20.0
> Accept: */*
> 
* Request completely sent off
< HTTP/3 200 
< content-length: 5
< content-type: text/plain
< date: Wed, 27 May 2026 12:49:14 GMT
< server: Cowboy
< 
* Connection #0 to host localhost:8081 left intact
hello

It looks good, cowboy returns the famous hello message and curl is correctly using HTTP/3.

Conclusion

I would really like to use HTTP/3 and QUIC in production with Erlang and cowboy, but I don't really think this is still a good time to use it. Many things must be improved, and based on the amount of dependencies required, it's a bit scary.

This project example can still be seen on niamtokik/buckaroo repository at Github.

Have fun!

Cover Image by Chris Liverani on Unsplash

OpenBSD 7.9 feedback: iwx powersave issue

Mathieu Kerjouan — Sat, 30 May 2026 08:00:00 +0000

A quick update regarding the last release of OpenBSD 7.9, I upgraded one of my old laptop (Lenovo Thinkpad AMD T14 gen1) and got a problem with the iwx driver (the one in charge of the wifi). During the startup I got those messages (visible in dmesg as well):

$ dmesg | grep iwx0
...
iwx0 at pci3 dev 0 function 0 "Intel Wi-Fi 6 AX200" rev 0x1a, msix
iwx0: hw rev 0x340, fw 77.30b1cbd8.0, address e0:d4:aa:bb:cc:dd
iwx0 at pci3 dev 0 function 0 "Intel Wi-Fi 6 AX200" rev 0x1a, msix
iwx0: could not read firmware iwx-cc-a0-77 (error 2)
iwx0: failed to load init firmware
iwx0: hw rev 0x340, fw 77.30b1cbd8.0, address e0:d4:aa:bb:cc:dd
iwx0 at pci3 dev 0 function 0 "Intel Wi-Fi 6 AX200" rev 0x1a, msix
iwx0: hw rev 0x340, fw 77.30b1cbd8.0, address e0:d4:aa:bb:cc:dd
iwx0: fatal firmware error
iwx0: fatal firmware error
iwx0: fatal firmware error

Well, my first action was to check if the firmware can be upgraded using fw_update.

$ doas fw_update

Nope. No new firmware. Let check if the bug is already known by the team and a syspatch has been released?

$ doas syspatch

Nothing at all, as expected (the errata page was empty).

Okay, let just quickly check the release note again:

Enabled 64-bit DMA transfers on aq(4), em(4), rge(4), re(4), iavf(4), ix(4), ixv(4), ixl(4), igc(4), ice(4) and iwx(4).

Added support for a 160 MHz window at 5 GHz and enabled it on iwx(4).

Enabled iwx(4) on i386.

Fixed iwx(4) issues related to roaming and PMF and firmware crypto keys.

Set the assoc ID field in iwx(4) firmware commands correctly.

Added support for BZ devices with WiFi 6e radio to iwx(4).

Made iwx(4) not load incomplete firmware images and report a proper error instead.

Added powersave support to iwx(4) and enable by default.

Added support for 160 MHz channel width to iwx(4).

Increased the VHT frame aggregation size limit from 64k to 1024k on iwx(4).

Aligned iwx(4) antenna patterns and STBC with iwlwifi.

Ah! The culprit could be the power saving enabled by default! I hope so... Because if it's not the case, I will need to upgrade to stable and I would like to avoid that on this laptop. Luckily, disabling the power saving is not complex, the -powersave flag needs to be added on this device, let put that in /etc/hostname.iwx0.

$ echo "-powersave" | doas tee /etc/hostname.iwx0

Now, we can restart the interface.

$ doas /etc/netstart iwx0

And... It works! No more error messages. The problem was the power saving. In short, if you are using a Intel Wi-Fi 6 AX200 device, on a Lenovo T14 AMD Gen1, the power saving does not work with the latest OpenBSD 7.9 version.

Unfortunately, the next day it was not working anymore. The firmware was still unhappy for some unknown reason. Let switch to debug mode, just to have an idea of the problem. Part of the dmesg has been removed to avoid leaking my personal network information.

$ doas ifconfig iwx0 debug
$ dmesg
iwx0: RUN -> INIT
iwx0: begin active scan
iwx0: INIT -> SCAN
iwx0: end active scan
...
iwx0: missed beacon threshold set to 25 beacons, beacon interval is 120 TU
iwx0: dumping device error log
iwx0: Start Error Log Dump:
iwx0: Status: 0x879, count: 6
iwx0: 0x00000071 | NMI_INTERRUPT_UMAC_FATAL    
iwx0: 008022F3 | trm_hw_status0
iwx0: 00000000 | trm_hw_status1
iwx0: 004F8F22 | branchlink2
iwx0: 00007FC0 | interruptlink1
iwx0: 00007FC0 | interruptlink2
iwx0: 00015050 | data1
iwx0: 00001000 | data2
iwx0: 00000000 | data3
iwx0: 00087FCC | beacon time
iwx0: 00378032 | tsf low
iwx0: 00000000 | tsf hi
iwx0: 00000000 | time gp1
iwx0: 0037DB02 | time gp2
iwx0: 00000001 | uCode revision type
iwx0: 0000004D | uCode version major
iwx0: 30B1CBD8 | uCode version minor
iwx0: 00000340 | hw version
iwx0: 18089000 | board version
iwx0: 0102001C | hcmd
iwx0: 00021000 | isr0
iwx0: 61040000 | isr1
iwx0: 18F00002 | isr2
iwx0: 00C3400D | isr3
iwx0: 00000000 | isr4
iwx0: 0101001C | last cmd Id
iwx0: 00015050 | wait_event
iwx0: 00000288 | l2p_control
iwx0: 00000000 | l2p_duration
iwx0: 000000BF | l2p_mhvalid
iwx0: 000000EF | l2p_addr_match
iwx0: 00000009 | lmpm_pmg_sel
iwx0: 00000000 | timestamp
iwx0: 00003050 | flow_handler
iwx0: Start UMAC Error Log Dump:
iwx0: Status: 0x879, count: 7
iwx0: 0x20101A0D | ADVANCED_SYSASSERT
iwx0: 0x00000000 | umac branchlink1
iwx0: 0x80455D7A | umac branchlink2
iwx0: 0x0106E0A4 | umac interruptlink1
iwx0: 0x00000000 | umac interruptlink2
iwx0: 0x00000005 | umac data1
iwx0: 0x00000001 | umac data2
iwx0: 0x00000001 | umac data3
iwx0: 0x0000004D | umac major
iwx0: 0x30B1CBD8 | umac minor
iwx0: 0x0037DAFC | frame pointer
iwx0: 0xC0886BC4 | stack pointer
iwx0: 0x001C050F | last host cmd
iwx0: 0x00000000 | isr status reg
driver status:
  tx ring  0: qid=0  cur=29  cur_hw=29  queued=1  
  tx ring  1: qid=1  cur=3   cur_hw=3   queued=1  
  tx ring  2: qid=2  cur=0   cur_hw=0   queued=0  
  tx ring  3: qid=3  cur=0   cur_hw=0   queued=0  
  tx ring  4: qid=4  cur=0   cur_hw=0   queued=0  
  tx ring  5: qid=5  cur=0   cur_hw=0   queued=0  
  tx ring  6: qid=6  cur=0   cur_hw=0   queued=0  
  tx ring  7: qid=7  cur=0   cur_hw=0   queued=0  
  tx ring  8: qid=8  cur=0   cur_hw=0   queued=0  
  tx ring  9: qid=9  cur=0   cur_hw=0   queued=0  
  rx ring: cur=51
  802.11 state RUN
iwx0: fatal firmware error

Hmm, while investigating, I also see the interface was crashing when it was using the 11a mode. Let force the driver to use 11n for example.

$ echo "mode 11n" | doas tee /etc/hostname.iwx0
$ doas sh /etc/netstart iwx0

The network is up again! Okay, I really think there is a bug somewhere in the iwx driver or with the firmware. I never had a similar issue with that in the past, so, I assume something has been upgraded there during OpenBSD 7.9 migration. Anyway, if the issue persist, I will try to find another solution and investigate a bit more.

Cover Image by Brice Cooper on Unsplash

HTTP Server in Erlang with Cowboy

Mathieu Kerjouan — Fri, 29 May 2026 08:00:00 +0000

Finally, a bit of Erlang! Instead of writing the same 101 introduction to this marvelous language, we will switch directly on the most used HTTP Web Server on this ecosystem: Cowboy. The goal will be to create a flexible module letting us configuring HTTP/1.1, HTTP/2, HTTP/3 and WebSocket easily. Why do I need that? For some of my local test, especially for Dart/Flutter.

Anyway, it's time to create a new fresh project to explain that, let call it Buckaroo.

Project Bootstrapping with rebar3

Just a quick reminder for the newcomers who never tried Erlang, below, the command to generate a new app project.

$ rebar3 new app name=buckaroo

All the magic will happen in the src/ directory but cowboy must be added in the dependencies list in rebar.config.

{erl_opts, [debug_info]}.
{deps, [cowboy]}.
{shell, [{apps, [buckaroo]}]}.

Let fetch everything.

$ rebar3 get-deps
$ rebar3 compile

Starting Cowboy

To make things easier, a dedicated module to manage cowboy called buckaroo_cowboy is created. And to avoid too much complexity, only 2 functions will be exported

start_link/0 to start the cowboy listener;
stop/0 to stop the cowboy listener.

-module(buckaroo_cowboy).
-export([start_link/0, stop/0]).

A cowboy listener needs a name, let create a function called name/0 to deal with that. It will return the listener name.

name() ->
  buckaroo_listener.

Now, the HTTP API routes are required, the cowboy routing documentation is complete and should be way enough to understand how to routes requests with cowboy. 2 routes will be created there, the default one (/) will be used for HTTP requests, and (/ws) for the WebSockets. In both case, the last element of the tuple passed by the router will be a map(), this value will be used as connection state.

routes() ->
  [
    {'_', [
      {"/", buckaroo_handler, #{}},
      {"/ws", buckaroo_websocket_handler, #{}}
    ]
  }].

The routes, then, must be compiled with the help of the cowboy_router:compile/1 function.

dispatch() ->
  cowboy_router:compile(
    routes()
  ).

A cowboy listener will also require 2 kinds of options, the transport options (TCP) and the protocol options (including HTTP and HTTP/2 options). In our case, only the listening port (TCP/8081) will be set.

transport_options() ->
  [
    {port, 8081}
  ].

The protocol options can be defined, in this case, only the routing will be configured via the dispatch key.

protocol_options() ->
  #{
    env => #{
      dispatch => dispatch()
    }
  }.

To start a cowboy listener, the (cowboy:start_clear/3)(https://ninenines.eu/docs/en/cowboy/2.15/manual/cowboy.start_clear/) function can be used. If a TLS certificate is configured, the cowboy:start_tls/3 must be used instead. The first argument is the name of the listener, the second the transport options and the last one the protocol options.

start_link() ->
  cowboy:start_clear(
    name(),
    transport_options(),
    protocol_options()
  ).

Finally, the stop() function can be created to help shutdown cowboy, using simply the name previously configured and with the cowboy:stop_listener/1 function.

stop() ->
    cowboy:stop_listener(name()).

A quick remark regarding my coding style. I like creating really small functions and call them in some part of the code. It can help to document but also to test the module. We will see that in another publication about finite state machines.

The final modification, is to add the cowboy listener in the supervision tree by editing src/buckaroo_sup.erl.

-module(buckaroo_sup).
-behavior(supervisor).
-export([start_link/0, init/1]).

start_link() ->
  supervisor:start_link({local, ?MODULE}, ?MODULE, []).

init(_) ->
  {ok, {supervisor_flags(), child_specs()}}.

supervisor_flags() ->
  #{
    strategy => one_for_all,
    intensity => 0,
    period => 1
  }.

child_specs() ->
  [
    #{
      id => buckaroo_cowboy,
      start => {buckaroo_cowboy, start_link, []}
    }
  ].

Now, the application can be started, for development and debug purpose only, it will be started with an Erlang shell.

$ rebar3 shell
===> Verifying dependencies...
===> Analyzing applications...
===> Compiling buckaroo
Erlang/OTP 29 [erts-17.0] [source] [64-bit] [smp:16:16] [ds:16:16:10] [async-threads:1] [jit:ns]

Eshell V17.0 (press Ctrl+G to abort, type help(). for help)
===> Booted cowlib
===> Booted ranch
===> Booted cowboy
===> Booted buckaroo

Well done, but it will not work correctly, because the handlers are missing... Let fix that in the next sections of this article.

Dealing with HTTP Requests

An handler can usually deal with HTTP requests but also with WebSocket ones. Let

-module(buckaroo_handler).
-export([init/2]).
-include_lib("kernel/include/logger.hrl").

init(Req, State) ->
  Reply = cowboy_req:reply(200,
    #{
      <<"content-type">> => <<"text/plain">>
    },
    <<"hello">>,
    Req
  ),
  {ok, Reply, State}.

The cowboy request object is the core data structure used by any handlers, here a quick view of its content when using curl locally.

#{
  pid => <0.1260.0>,
  port => 8081,
  scheme => <<"http">>,
  version => 'HTTP/1.1',
  path => <<"/">>,
  host => <<"localhost">>,
  peer => {{127,0,0,1},50986},
  bindings => #{},
  cert => undefined,
  headers => #{
    <<"accept">> => <<"*/*">>,
    <<"host">> => <<"localhost:8081">>,
    <<"user-agent">> => <<"curl/8.14.1">>
  },
  ref => buckaroo_listener,
  host_info => undefined,
  path_info => undefined,
  streamid => 1,
  method => <<"GET">>,
  body_length => 0,
  has_body => false,
  qs => <<>>,
  sock => {{127,0,0,1},8081}}
}.

As you can see, this is a simple map() containing specific keys. The value of those keys can be retrieved using Erlang pattern matching, or by using the cowboy functions helpers from the module cowboy_req. This data structure will be used to route the request and alter the final response, so, let check them one by one.

pid is the process id of the process in charge of the request;
port is the port from the listener and can also be extracted using cowboy_req:port/1 function;
scheme is the scheme using, usually http or https. This information can be obtained using cowboy_req:scheme/1 function as well;
version is the protocol version used, it can be HTTP/1.0, HTTP/1.1, HTTP/2 or HTTP/3. It can be extracted with the help of cowboy_req:version/1 function;
path represents the full path requested by the client, this value is more or less related to the routing defined when starting cowboy, it can be extracted using cowboy_req:path/1 function;
host represents the host name requested by the client, it is also a part of the routing configuration, this value can also be extracted using cowboy_req:host/1 function;
peer contains the IP address/port of the client, it can also be extracted using cowboy_req:peer/1 function;
bindings is set when the route is configured with pattern matching, if it was the case, the variables defined in the route would have been converted into bindings;
cert is set when a certificate is sent by the client, it can be extracted using cowboy_req:cert/1 function;
headers are the HTTP Headers sent by the client, an header value can be extracted using cowboy_req:header/2 or cowboy_req:header/3 functions;
ref (internal usage) stores the name of the listener;
host_info returns the routing pattern matching result, it can also be accessed using cowboy_req:host_info/1 function;
path_info returns the routing pattern matching result, it can also be extracted using cowboy_req:path_info/1 function;
streamid (internal usage) defines the stream id of the connection;
method defines the HTTP method used by the client for the request, it can also be retrieved using cowboy_req:method/1 function;
body_length defines the size of the data sent by the client in the HTTP body, the value of this key can be also fetched using cowboy_req:body_length/1 function;
has_body defines if the request contains a body or not. Mostly used with POST, PUT and other HTTP methods sending data. It can also be checked using cowboy_req:has_body/1 function;
qs is the raw query string, it should be parsed using uri_string:dissect_query/1 function or with your own method. The value can also be retrieved using cowboy_req:qs/1;
sock contains the IP address and port of the server, it can be extracted using cowboy_req:sock/1 function.

The handler is done, it's a really simple one, but just to check if it's working, we can use curl.

$ curl -kv http://localhost:8081/; echo
* Host localhost:8081 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* HTTPS-RR: -
*   Trying [::1]:8081...
* connect to ::1 port 8081 from ::1 port 48828 failed: Connection refused
*   Trying 127.0.0.1:8081...
* Established connection to localhost (127.0.0.1 port 8081) from 127.0.0.1 port 48800 
* using HTTP/1.x
> GET / HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/8.20.0
> Accept: */*
> 
* Request completely sent off
< HTTP/1.1 200 OK
< content-length: 5
< content-type: text/plain
< date: Wed, 27 May 2026 12:20:21 GMT
< server: Cowboy
< 
* Connection #0 to host localhost:8081 left intact
hello

Dealing with WebSockets

Cowboy can also managed WebSocket connections using websocket handlers. The idea is to create 4 callback functions, one for the HTTP request and three for the WebSocket events.

-module(buckaroo_websocket_handler).
-export([init/2]).
-export([websocket_init/1, websocket_handle/2, websocket_info/2]).
-include_lib("kernel/include/logger.hrl").

When a client wants to use WebSocket protocol, it will first send an HTTP request with some specific information, then the server will start the negotiation, this step, is mostly done in init/2 callback.

init(Req, State) ->
  WebSocketOpts = #{
    active_n => 1,
    compress => false,
    data_delivuery => stream_handlers,
    data_delivery_flow => 1,
    deflate_opts => #{},
    dynamic_buffer => {1024, 131_072},
    idle_timeout => 60_000,
    max_frame_size => 120_000,
    req_filter => fun(Req) -> Req end,
    validate_utf8 => true
  },
  ?LOG_DEBUG("~p:~p: ~p~n", [
    ?MODULE,
    ?FUNCTION_NAME,
    WebSocketOpts,
    Req
  ]),
  {cowboy_websocket, Req, State, WebSocketOpts}.

At the end of the negociation, the server can do some initialization state using the websocket_init/1 callback. In our case, the text event hey\n will send to the client by the server.

websocket_init(State) ->
  ?LOG_DEBUG("~p:~p: ~p~n", [?MODULE, ?FUNCTION_NAME]),
  {[{text, <<"hey\n">>}], State}.

To handle messages sent by the client, a websocket_handle/2 function must be created and exported by the module. The first argument received is a tuple containing the type of data (defined in the websocket_handle callback and also defined as cow_ws:frame() type), and its content. The second argument is the connection state.

websocket_handle(Frame = {text, Message}, State) ->
  ?LOG_DEBUG("~p:~p: ~p, ~p~n", [?MODULE, ?FUNCTION_NAME, Frame]),
  {[{text, Message}], State};
websocket_handle(Frame = {binary, Message}, State) ->
  ?LOG_DEBUG("~p:~p: ~p, ~p~n", [?MODULE, ?FUNCTION_NAME, Frame]),
  {[{binary, Message}], State};
websocket_handle(Frame, State) ->
  ?LOG_DEBUG("~p:~p: ~p, ~p~n", [?MODULE, ?FUNCTION_NAME, Frame]),
  {[Frame], State}.

The websocket handler is running in a process, and this process can receive message from another running process from the system. In this case, the message will be handled by websocket_info/2 function callback.

websocket_info(Event, State) ->
  ?LOG_DEBUG("~p:~p: ~p, ~p~n", [?MODULE, ?FUNCTION_NAME, Event]),
  {ok, State}.

Let check that with curl to see what will happen.

$ curl -N -T. --no-progress-meter -v ws://localhost:8081/ws
* Host localhost:8081 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
* HTTPS-RR: -
*   Trying [::1]:8081...
* connect to ::1 port 8081 from ::1 port 45396 failed: Connection refused
*   Trying 127.0.0.1:8081...
* Established connection to localhost (127.0.0.1 port 8081) from 127.0.0.1 port 43458 
* using HTTP/1.x
> GET /ws HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/8.20.0
> Accept: */*
> Upgrade: websocket
> Sec-WebSocket-Version: 13
> Sec-WebSocket-Key: +t+tuHiQUK6MMQySUqDGtQ==
> Connection: Upgrade
> 
* Request completely sent off
< HTTP/1.1 101 Switching Protocols
< connection: Upgrade
< date: Wed, 27 May 2026 12:21:53 GMT
< sec-websocket-accept: F87i2EOBLl+kwTQ3PCdZqjjcxuA=
< server: Cowboy
< upgrade: websocket
< 
* Received 101, Switching to WebSocket
* [WS] Received 101, switch to WebSocket
{ [5 bytes data]
hey

hello!
hello!
test1
test1
* upload completely sent off: 32 bytes

The websocket handler correctly acts as an echo server, it looks good!

Conclusion

It's always a pleasure to write Erlang code, even more after many weeks where I passed all my time learning Dart/Flutter. Erlang code is concise and efficient. Cowboy is following the same philosophy there, and give us a good idea how to manage requests.

This project example can be seen on niamokik/buckaroo repository at Github.

Have fun!

References and Resources

Cowboy Source Code on Github

Cover Image by JJ Ying on Unsplash

DEV Community: Mathieu Kerjouan

Sandbox#1: Flutter Application Design First Steps

Bootstrapping

Wireframe and Prototype

First Version

Conclusion

Encoding and Decoding JSON in Dart

Encoding

Decoding

Conclusion

Standalone HTTP Server with Relic in Dart

Cache Server

Global Variables

Singleton pattern

Multiton Pattern

Observer pattern (Observables)

Common Functions

Store

Session

Relic Handlers

Relic Middleware

Relic Routing

Application Entry Point

Testing

Conclusion

Interactive Shell with Dart

Conclusion

Bonus: devtools

Missing Libraries on OpenBSD

Tests and Coverage in Dart

Bootstrapping

Rock-Paper-Scissors Rules

Rock-Paper-Scissors Shapes

Test Reports

Test Coverage

Conclusion

Alternative Laptop Manufacturers

Entroware

Framework

GPD Technology

Juno Computers

Malibal

Minifree

Mnt Reform

Nitrokey

NovaCustom

Olimex

Pyra

Pinebook

Purism

Skikk

Slimbook

Starlabs

System76

Technoethical

Think Penguin

Tuxedo Computers

Vikings

Other Smaller projects/companies

GenBook RK3588

Novena

CrowPi2

Anyon_e

Loongson

Conclusion

Standalone HTTP Server in Elixir with Bandit

Bootstrapping

Starting Bandit

Anatomy of a Plug

Dealing with HTTP Requests

Dealing with WebSockets

HTTP/WebSockets Multi Protocol Endpoint

Plug Pipeline

Final Test

Conclusion

WebSocket and curl

HTTP/3 and QUIC in Erlang with Cowboy

Conclusion

OpenBSD 7.9 feedback: iwx powersave issue

HTTP Server in Erlang with Cowboy

Anatomy of a `Plug`