DEV Community: Mary 🇪🇺 🇷🇴 🇫🇷

Without This, It’s Not a Cloud

Mary 🇪🇺 🇷🇴 🇫🇷 — Wed, 23 Sep 2026 09:23:15 +0000

In the previous article, we saw how to simulate the network and nodes of a cloud with a relatively small amount of Linux networking.

But as we already said, a cloud is first and foremost software.

We are obviously not going to manually create and configure the network every time a new customer signs up.

To handle that, we need to build what is called a Control Plane.

The Control Plane

A cloud is usually divided into two categories: those with loaded guns, and those who dig...

No, wait. Wrong movie.

A cloud is usually divided into two main parts: the Control Plane and the Data Plane.

The Control Plane

The Control Plane is the entry point for requests made to the cloud, both user requests and requests coming from the system itself.

It is responsible for organizing and orchestrating actions across the cloud.

The Data Plane

The other part is where the actual resources and data live.

In our simplified model, the Data Plane is where we find our nodes, VMs, disks, networks, and workloads.

Right now, our cloud is still just a skeleton.

We have no actual workloads, and we do not even have real machines yet. Our nodes are currently simulated using isolated Linux environments, mainly network namespaces.

But that is already enough to start building a Control Plane capable of creating tenants, managing nodes, allocating resources, and deleting them when they are no longer needed.

The PandaCloud Project

We are going to create a C# project for our Control Plane.

It could obviously be written in almost any language, so if you want to implement yours in Java or Go, go ahead.

If you want to do it in JavaScript, leave this blog and never come back.

The Model

We will start by defining a few model classes representing:

a tenant
a node
the overall state of the cloud

The classes are fairly self-explanatory, so there is no need to spend too much time on them.

public class Tenant
{
    public string Name { get; set; } = string.Empty;
    public string BridgeName { get; set; } = string.Empty;
    public string Subnet { get; set; } = string.Empty;
    public string Gateway { get; set; } = string.Empty;
    public int NextHostAddress { get; set; } = 10;
}

public enum NodeState
{
    Available,
    Allocated
}

public class Node
{
    public string Name { get; set; } = string.Empty;
    public int CpuCores { get; set; }
    public NodeState State { get; set; } = NodeState.Available;
    public string? TenantName { get; set; } = null;
    public string? IpAddress { get; set; } = null;
}

public class CloudState
{
    public List<Tenant> Tenants { get; init; } = [];
    public List<Node> Nodes { get; init; } = [];
}

The next step is to actually manipulate the infrastructure.

We want to create nodes, create tenant networks, allocate nodes to tenants, release them, and eventually destroy them.

For now, everything runs on a single Linux system.

But later, the same Control Plane could manage resources through another infrastructure provider.

It could talk to Azure, libvirt, another cloud provider, or something entirely different.

At that point, instead of running Bash commands, the provider could call APIs, deploy ARM templates, use Terraform, or communicate with another infrastructure system.

The Infrastructure Provider

To keep things flexible, we will define an interface describing the infrastructure operations our Control Plane needs.

public interface IInfrastructureProvider
{
    Task CreateTenantNetworkAsync(Tenant tenant);
    Task DeleteTenantNetworkAsync(Tenant tenant);
    Task CreateNodeAsync(Node node);
    Task AttachNodeToTenantAsync(Node node, Tenant tenant, string ipAddress);
    Task ReleaseNodeAsync(Node node);
    Task DeleteNodeAsync(Node node);
}

The interface is fairly straightforward, but there is one important detail worth mentioning.

All of these methods return Task.

You could simply say this is good practice because we are executing external operations and do not want to block the Control Plane while waiting for them.

And that is true.

But cloud operations can eventually become much more complex than a simple network or shell call.

Creating, configuring, repairing or moving resources can sometimes take minutes, hours, or even longer.

So from the beginning, we should think about these operations asynchronously.

"Wait. I've created plenty of Azure resources before and it never took hours."

Well, congratulations. You have been lucky.

But the Control Plane does not only process direct customer requests.

It also receives requests from the cloud itself.

Those operations can involve several services, retries, dependencies and, in some cases, even human intervention.

For now, we are simply using asynchronous C# methods because our operations are still short-lived.

Later, these operations should be thought of as actual persistent workflows.

A Task is not a replacement for a durable workflow engine, but it already prevents us from designing the Control Plane around blocking operations.

For now, our infrastructure operations will execute shell commands.

So let's create a small helper class.

public sealed class ShellRunner
{
    public async Task RunAsync(string command)
    {
        Console.WriteLine($"> {command}");

        var startInfo = new ProcessStartInfo
        {
            FileName = "wsl.exe",
            UseShellExecute = false,
            RedirectStandardOutput = true,
            RedirectStandardError = true
        };

        startInfo.ArgumentList.Add("-u");
        startInfo.ArgumentList.Add("root");
        startInfo.ArgumentList.Add("--");
        startInfo.ArgumentList.Add("bash");
        startInfo.ArgumentList.Add("-lc");
        startInfo.ArgumentList.Add(command);

        using var process = Process.Start(startInfo)
            ?? throw new InvalidOperationException("Unable to start shell process.");

        var stdoutTask = process.StandardOutput.ReadToEndAsync();
        var stderrTask = process.StandardError.ReadToEndAsync();

        await process.WaitForExitAsync();

        Console.Write(await stdoutTask);

        if (process.ExitCode != 0)
            throw new InvalidOperationException(await stderrTask);
    }
}

This class is intentionally simplified for the article.

You can find the complete version in the PandaCloud repository:

https://github.com/MarieLePanda/PandaCloud

Now we can start building our infrastructure provider.

The Infrastructure

If you read the previous article carefully, we created Alice's network using something like this:

sudo ip link add pc-alice type bridge
sudo ip link set pc-alice up

We are going to reuse the same idea inside our Control Plane, but with one important difference.

What happens if Alice's network already exists?

Maybe the operation is retried.

Maybe the Control Plane restarted.

Maybe something failed halfway through the previous operation.

Whatever the reason, running infrastructure operations more than once must not randomly break the system.

A command executed a second time could fail or, depending on the operation, create duplicate resources.

So our infrastructure operations should be idempotent.

Running the same operation several times should lead to the same final state.

public async Task CreateTenantNetworkAsync(Tenant tenant)
{
    await _shellRunner.RunAsync(
        $"sudo ip link show {tenant.BridgeName} >/dev/null 2>&1 || " +
        $"sudo ip link add {tenant.BridgeName} type bridge");

    await _shellRunner.RunAsync(
        $"sudo ip link set {tenant.BridgeName} up");
}

The same applies to nodes.

Previously, we created them with:

sudo ip netns add node10

Now we simply make sure the namespace does not already exist before creating it.

public async Task CreateNodeAsync(Node node)
{
    await _shellRunner.RunAsync(
        $"if ! sudo ip netns list | grep -qw {node.Name}; then " +
        $"sudo ip netns add {node.Name}; " +
        $"fi");
}

The final operation we need for now is attaching a node to a tenant.

This part is slightly more complicated.

We need to connect the node to the tenant bridge using a veth pair, our virtual network cable.

And once again, we want the operation to be idempotent.

private static string ShortInterfaceName(string name)
{
    // Linux interface names are limited to 15 characters.
    // Enhance the method in the future to generate unique names.
    return name.Length <= 15 ? name : name[..15];
}

private static string GetHostInterfaceName(string nodeName)
{
    var hostVeth = ShortInterfaceName($"v-{nodeName}-h");
    return hostVeth;
}

private static string GetNodeInterfaceName(string nodeName)
{
    var nodeVeth = ShortInterfaceName($"v-{nodeName}-n");
    return nodeVeth;
}

public async Task AttachNodeToTenantAsync(
    Node node,
    Tenant tenant,
    string ipAddress)
{
    var hostVeth = GetHostInterfaceName(node.Name);
    var nodeVeth = GetNodeInterfaceName(node.Name);

    await _shellRunner.RunAsync(
        $"if ! sudo ip link show {hostVeth} >/dev/null 2>&1; then " +
        $"sudo ip link add {hostVeth} type veth peer name {nodeVeth} && " +
        $"sudo ip link set {nodeVeth} netns {node.Name}; " +
        $"fi");

    await _shellRunner.RunAsync(
        $"sudo ip link set {hostVeth} master {tenant.BridgeName}");

    await _shellRunner.RunAsync(
        $"sudo ip link set {hostVeth} up");

    await _shellRunner.RunAsync(
        $"sudo ip netns exec {node.Name} ip link set lo up");

    await _shellRunner.RunAsync(
        $"sudo ip netns exec {node.Name} ip link set {nodeVeth} up");

    await _shellRunner.RunAsync(
        $"sudo ip netns exec {node.Name} ip addr flush dev {nodeVeth}");

    await _shellRunner.RunAsync(
        $"sudo ip netns exec {node.Name} ip addr add {ipAddress}/24 dev {nodeVeth}");
}

Managing the Lifecycle

We can now create resources and attach nodes to tenant networks.

But creating things is only half the problem.

A node can be created, allocated to a tenant, released later, reassigned somewhere else, and eventually destroyed.

So we also need to manage the rest of its lifecycle.

Deleting a node is straightforward, but we still want the operation to succeed if the namespace has already disappeared.

public async Task DeleteNodeAsync(Node node)
{
    await _shellRunner.RunAsync(
        $"if sudo ip netns list | grep -qw {node.Name}; then " +
        $"sudo ip netns delete {node.Name}; " +
        $"fi");
}

The same principle applies when deleting a tenant network.

public async Task DeleteTenantNetworkAsync(Tenant tenant)
{
    await _shellRunner.RunAsync(
        $"if ip link show dev {tenant.BridgeName} >/dev/null 2>&1; then " +
        $"sudo ip link delete dev {tenant.BridgeName} type bridge; " +
        $"fi");
}

And finally, releasing a node means removing its host-side veth interface.

public async Task ReleaseNodeAsync(Node node)
{
    var hostInterface = GetHostInterfaceName(node.Name);

    await _shellRunner.RunAsync(
        $"if sudo ip link show dev {hostInterface} >/dev/null 2>&1; then " +
        $"sudo ip link delete dev {hostInterface}; " +
        $"fi");
}

So, are we done with the Control Plane?

No.

Actually, we haven't even started building it yet.

So far, we have created infrastructure operations that are reasonably safe to execute.

But there are still a lot of missing rules.

What happens to allocated resources when a tenant is deleted?

Can I allocate a node that is already assigned to someone else?

How do I decide which IP address should be assigned?

How much capacity is available?

That logic belongs in the service layer.

That is where our actual Control Plane starts.

The Real Control Plane

Our infrastructure functions will now be called by a service layer responsible for validating the requested operation before modifying the infrastructure.

We will start with tenant and node creation.

public async Task CreateTenantAsync(string name)
{
    if (_cloudState.Tenants.Any(t =>
        t.Name.Equals(name, StringComparison.OrdinalIgnoreCase)))
    {
        throw new Exception($"Tenant with name {name} already exists.");
    }

    string networkId = FindNextNetworkId(_cloudState).ToString();

    Tenant newTenant = new Tenant
    {
        Name = name,
        BridgeName = $"br-{name.ToLower()}",
        Subnet = $"10.{networkId}.0.0/24",
        Gateway = $"10.{networkId}.0.1",
    };

    await _infrastructureProvider.CreateTenantNetworkAsync(newTenant);

    _cloudState.Tenants.Add(newTenant);

    Console.WriteLine(
        $"Tenant {name} created with subnet {newTenant.Subnet} " +
        $"and gateway {newTenant.Gateway}.");
}

For now, .1 is simply reserved as the future gateway address in our model.

Routing will come later.

Node creation follows exactly the same idea.

public async Task CreateNodeAsync(string nodeName, int cpuCores)
{
    if (_cloudState.Nodes.Any(n =>
        n.Name.Equals(nodeName, StringComparison.OrdinalIgnoreCase)))
    {
        throw new Exception($"Node with name {nodeName} already exists.");
    }

    Node newNode = new Node
    {
        Name = nodeName,
        CpuCores = cpuCores,
    };

    await _infrastructureProvider.CreateNodeAsync(newNode);

    _cloudState.Nodes.Add(newNode);

    Console.WriteLine($"Node {nodeName} created.");
}

At this stage, CpuCores is only capacity metadata inside the Control Plane.

Our network namespace is not actually restricted to 12 or 6 CPUs.

Later, a provider based on real virtual machines, containers or cgroups could enforce that capacity.

Now comes the slightly more interesting part: allocating a node to a tenant.

In addition to validating the request, we also need to allocate an available IP address.

public async Task AllocateNodeAsync(string nodeName, string tenantName)
{
    Node? node = _cloudState.Nodes.FirstOrDefault(n =>
        n.Name.Equals(nodeName, StringComparison.OrdinalIgnoreCase));

    if (node == null)
        throw new Exception($"Node {nodeName} does not exist.");

    Tenant? tenant = _cloudState.Tenants.FirstOrDefault(t =>
        t.Name.Equals(tenantName, StringComparison.OrdinalIgnoreCase));

    if (tenant == null)
        throw new Exception($"Tenant {tenantName} does not exist.");

    if (node.State != NodeState.Available)
        throw new Exception($"Node {nodeName} is not available for allocation.");

    string networkId = tenant.Subnet.Split('.')[1];
    string ipAddress = $"10.{networkId}.0.{tenant.NextHostAddress}";

    tenant.NextHostAddress++;

    await _infrastructureProvider.AttachNodeToTenantAsync(
        node,
        tenant,
        ipAddress);

    node.TenantName = tenantName;
    node.IpAddress = ipAddress;
    node.State = NodeState.Allocated;

    Console.WriteLine(
        $"Node {nodeName} allocated to tenant {tenantName} " +
        $"with IP address {ipAddress}.");
}

I will skip the other service methods for releasing nodes, deleting them, and so on.

They follow the same pattern as what we have already seen.

As always, the complete code is available in the PandaCloud repository:

https://github.com/MarieLePanda/PandaCloud

Let's Test Our Control Plane

It is finally time to run it.

We still need one small piece: an entry point to call our Control Plane methods.

We could expose an HTTP API.

Eventually, we probably will.

But for now, let's keep things simple and use command-line arguments.

CloudState cloudState = new CloudState();

IInfrastructureProvider provider = new LinuxProvider();

ControlPlane controlPlane = new ControlPlane(cloudState, provider);

try
{
    switch (args)
    {
        case ["tenant", "create", var tenantName]:
            await controlPlane.CreateTenantAsync(tenantName);
            break;

        case ["tenant", "list"]:
            await controlPlane.ListTenantsAsync();
            break;

        case ["node", "create", var nodeName, var cpuCores]:
            await controlPlane.CreateNodeAsync(nodeName, int.Parse(cpuCores));
            break;

        case ["node", "allocate", var nodeName, var tenantName]:
            await controlPlane.AllocateNodeAsync(nodeName, tenantName);
            break;

        case ["node", "list"]:
            await controlPlane.ListNodesAsync();
            break;

        case ["node", "release", var nodeName]:
            await controlPlane.ReleaseNodeAsync(nodeName);
            break;

        case ["node", "delete", var nodeName]:
            await controlPlane.DeleteNodeAsync(nodeName);
            break;

        case ["capacity", "request", var tenantName, var cpuCores]:
            await controlPlane.RequestCapacity(tenantName, int.Parse(cpuCores));
            break;

        case ["reconcile"]:
            await controlPlane.ReconcileAsync();
            break;

        default:
            Console.Error.WriteLine("Unknown command.\n");
            PrintHelp();
            Environment.ExitCode = 1;
            break;
    }
}
catch (Exception ex)
{
    Console.ForegroundColor = ConsoleColor.Red;
    Console.Error.WriteLine($"Error: {ex.Message}");
    Console.ResetColor();
    Environment.ExitCode = 1;
}

And now we can run our first command:

dotnet run -- tenant list

No tenant.

Wait.

No tenant?

Where are Alice and Bob?

Until now, our resources were created directly through Bash.

Linux knows they exist.

Our Control Plane does not.

The CloudState represents what our Control Plane knows about the cloud, and right now that state only exists in memory.

That is not particularly useful for a console application that starts, executes one command, and immediately exits.

So we need persistence.

Remembering the State

For now, we will keep this extremely simple and save the state to a JSON file.

public class StateStore
{
    private readonly string _stateDirectory;
    private readonly string _stateFile;

    private readonly JsonSerializerOptions _jsonOptions = new()
    {
        WriteIndented = true,
        Converters = { new JsonStringEnumConverter() }
    };

    public StateStore()
    {
        _stateDirectory = Path.Combine(
            Environment.CurrentDirectory,
            ".pandacloud");

        _stateFile = Path.Combine(
            _stateDirectory,
            "state.json");
    }

    public async Task<CloudState> LoadAsync()
    {
        if (!File.Exists(_stateFile))
            return new CloudState();

        var json = await File.ReadAllTextAsync(_stateFile);

        return JsonSerializer.Deserialize<CloudState>(json, _jsonOptions)
            ?? new CloudState();
    }

    public async Task SaveAsync(CloudState state)
    {
        Directory.CreateDirectory(_stateDirectory);

        var json = JsonSerializer.Serialize(state, _jsonOptions);

        await File.WriteAllTextAsync(_stateFile, json);
    }
}

At startup, we load the current state.

After modifying the infrastructure, we save it again.

Would a real cloud store its entire Control Plane state in one JSON file?

Obviously not.

The state changes constantly, several operations can happen concurrently, and we eventually need stronger consistency guarantees.

But for PandaCloud at this stage, JSON is perfectly good enough.

It lets us understand the important part first.

The Control Plane needs memory.

Let's Actually Test It This Time

Now we finally have everything we need.

Let's create Alice.

PS C:\Users\lgirardin\source\repos\PandaCloud> dotnet run -- tenant create alice
> sudo ip link show br-alice >/dev/null 2>&1 || sudo ip link add br-alice type bridge
> sudo ip link set br-alice up
Tenant alice created with subnet 10.10.0.0/24 and gateway 10.10.0.1.

PS C:\Users\lgirardin\source\repos\PandaCloud> dotnet run -- tenant list
TENANT           NETWORK              BRIDGE
--------------------------------------------------------
alice            10.10.0.0/24         br-alice

It looks good.

But let's not blindly trust the Control Plane.

Let's ask Linux directly.

lgirardin@lgirardin-pc:~$ ip link show br-alice

22: br-alice: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default qlen 1000
    link/ether d2:5b:d8:9c:56:59 brd ff:ff:ff:ff:ff:ff

The bridge exists.

It is administratively UP, but operationally still DOWN because no active interface is connected to it yet.

Let's create a few nodes.

dotnet run -- node create Node25 12
dotnet run -- node create Node26 12
dotnet run -- node create Node27 6
dotnet run -- node create Node28 6

dotnet run -- node list

NODE             STATE        TENANT           IP               CPU
--------------------------------------------------------------------
Node25           Available    -                -                12
Node26           Available    -                -                12
Node27           Available    -                -                6
Node28           Available    -                -                6

Now let's allocate them to Alice.

PS C:\Users\lgirardin\source\repos\PandaCloud> dotnet run -- node allocate node25 alice

> if ! sudo ip link show v-Node25-h >/dev/null 2>&1; then sudo ip link add v-Node25-h type veth peer name v-Node25-n && sudo ip link set v-Node25-n netns Node25; fi
> sudo ip link set v-Node25-h master br-alice
> sudo ip link set v-Node25-h up
> sudo ip netns exec Node25 ip link set lo up
> sudo ip netns exec Node25 ip link set v-Node25-n up
> sudo ip netns exec Node25 ip addr flush dev v-Node25-n
> sudo ip netns exec Node25 ip addr add 10.10.0.10/24 dev v-Node25-n

Node node25 allocated to tenant alice with IP address 10.10.0.10.

I'll let you do the other three.

Eventually, we should end up with:

PS C:\Users\lgirardin\source\repos\PandaCloud> dotnet run -- node list

NODE             STATE        TENANT           IP               CPU
--------------------------------------------------------------------
Node25           Allocated    alice            10.10.0.10       12
Node26           Allocated    alice            10.10.0.11       12
Node27           Allocated    alice            10.10.0.12       6
Node28           Allocated    alice            10.10.0.13       6

Again, this is what the Control Plane tells us.

Let's verify reality.

First, the network namespaces:

sudo ip netns list

Node28 (id: 12)
Node27 (id: 11)
Node26 (id: 10)
Node25 (id: 9)

Now let's check the tenant bridge.

ip link show br-alice

22: br-alice: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
    link/ether d2:5b:d8:9c:56:59 brd ff:ff:ff:ff:ff:ff

This time the bridge is operationally UP because active interfaces are connected to it.

Host Side

We can inspect the interfaces connected to the bridge:

ip link show master br-alice

or:

bridge link show

We should see our host-side veth interfaces:

24: v-Node25-h@if23: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br-alice state forwarding priority 32 cost 2
26: v-Node26-h@if25: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br-alice state forwarding priority 32 cost 2
28: v-Node27-h@if27: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br-alice state forwarding priority 32 cost 2
30: v-Node28-h@if29: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br-alice state forwarding priority 32 cost 2

Node Side

Now let's actually look inside Node25.

sudo ip netns exec Node25 ip addr show

Or only inspect its PandaCloud interface:

sudo ip netns exec Node25 ip addr show v-Node25-n

We can also inspect its routing table:

sudo ip netns exec Node25 ip route

And finally, let's verify that two nodes belonging to Alice can communicate with each other.

sudo ip netns exec Node25 ping -c 3 10.10.0.11

If everything is working properly, Node25 should be able to reach Node26 directly through br-alice.

And that brings us to the end of our Control Plane for now.

We could keep testing edge cases, but the important architecture is starting to appear.

We now have:

infrastructure operations
tenant networks
nodes
resource allocation
persistent state
idempotent operations
a service layer validating requests

But our Control Plane is still far from finished.

In the next part, we will start looking at capacity allocation.

Sans ça, pas de cloud

Mary 🇪🇺 🇷🇴 🇫🇷 — Wed, 23 Sep 2026 09:04:18 +0000

Dans notre dernier article, on a vu comment simplement simuler le réseau et les nœuds d’un cloud.

Mais nous l’avions dit (emoji avion), un cloud, c’est avant tout du logiciel. On ne va pas, dès qu’un nouveau client s’inscrit, aller créer et configurer nous-mêmes le réseau. Pour gérer cela, on va développer ce qu’on appelle un Control Plane.

Le Cloud

Le cloud se divise souvent en deux catégories : ceux qui ont le pistolet chargé, et ceux qui creusent… Non, attendez, ce n’est pas ça…

Le cloud se divise souvent en deux parties : le Control Plane et le Data Plane.

Le Control Plane

Il s’agit du point d’entrée des requêtes pour le cloud, aussi bien des requêtes utilisateurs que des requêtes du système. Il sert à organiser les actions sur le cloud.

Le Data Plane

L’autre partie est là où les données ou les ressources vivent. Le Data Plane, ce sont donc nos nœuds, nos VM, nos disques…

Actuellement, notre cloud est simplement un squelette. On n’a aucune donnée, on n’a même aucune machine, elles sont simplement simulées par des processus isolés au niveau réseau. Mais c’est suffisant pour commencer à créer un Control Plane pour gérer tout ça et permettre d’ajouter de nouveaux tenants, de modifier ceux qui existent et de les supprimer.

Le projet PandaCloud

On va créer un projet C# pour notre Control Plane. Il pourrait être écrit dans n’importe quel langage, donc si vous souhaitez le faire en Java ou Go, vous pouvez. Si vous souhaitez le faire en JavaScript, partez et ne revenez jamais ici.

Le modèle

Nous allons commencer par représenter nos classes de modèle, qui serviront à représenter :

un tenant ;
un nœud ;
l’état général de notre cloud.

Les classes vont être assez parlantes par elles-mêmes, donc inutile de passer trop de temps dessus, mais voici quand même les structures pour ne pas vous perdre :

public class Tenant
{
    public string Name { get; set; } = string.Empty;
    public string BridgeName { get; set; } = string.Empty;
    public string Subnet { get; set; } = string.Empty;
    public string Gateway { get; set; } = string.Empty;
    public int NextHostAddress { get; set; } = 10;
}

public enum NodeState
{
    Available,
    Allocated
}

public class Node
{
    public string Name { get; set; } = string.Empty;
    public int CpuCores { get; set; }
    public NodeState State { get; set; } = NodeState.Available;
    public string? TenantName { get; set; } = null;
    public string? IpAddress { get; set; } = null;
}

public class CloudState
{
    public List<Tenant> Tenants { get; init; } = [];
    public List<Node> Nodes { get; init; } = [];
}

La prochaine étape est de pouvoir gérer l’infrastructure pour créer des nœuds, les allouer à des tenants, etc.

Actuellement, bien sûr, tout cela est fait sur un seul Linux, mais dans le futur, le Control Plane pourrait très bien être utilisé pour gérer des ressources sur Azure ou un autre cloud provider. Dans ce cas, le Control Plane ne devrait plus exécuter du Bash, mais pourrait utiliser des templates ARM, du Terraform ou directement communiquer avec un autre système d’infrastructure.

L’infrastructure

On va donc rendre cela assez flexible en commençant par définir une interface avec les actions que l’on doit pouvoir effectuer :

public interface IInfrastructureProvider
{
    Task CreateTenantNetworkAsync(Tenant tenant);
    Task DeleteTenantNetworkAsync(Tenant tenant);
    Task CreateNodeAsync(Node node);
    Task AttachNodeToTenantAsync(Node node, Tenant tenant, string ipAddress);
    Task ReleaseNodeAsync(Node node);
    Task DeleteNodeAsync(Node node);
}

L’interface est, je pense, assez claire pour ne pas passer trop de temps à l’expliquer, mais il y a quand même quelque chose d’important à mentionner.

Vous voyez que toutes les fonctions sont des tâches asynchrones. On pourrait se dire que c’est simplement une bonne pratique : on va exécuter des appels externes, donc c’est normal de ne pas bloquer le Control Plane pendant leur exécution.

Mais dans le cloud, les opérations qui servent à créer, configurer ou modifier des ressources peuvent devenir bien plus complexes et plus longues que de simples appels réseau. Certaines peuvent durer plusieurs heures, voire plusieurs jours. Il faut donc, dès le départ, penser à une architecture asynchrone.

« Hey mais attends, moi j’ai déjà créé des ressources sur Azure et ça n’a jamais duré plus de quelques minutes avant de réussir ou d’échouer. »

Bon, alors déjà, tu as eu de la chance, félicitations.

Mais le Control Plane ne gère pas uniquement les demandes des clients, qui sont en effet généralement effectuées assez rapidement. Il peut aussi recevoir des requêtes du système, donc du cloud lui-même, et ces requêtes peuvent être plus complexes que simplement allumer une VM et l’affecter. Elles peuvent éventuellement même faire appel à des actions humaines.

Ce qu’il faut retenir ici, c’est que nous parlons de tâches asynchrones pour le moment, pour commencer simplement. Plus tard, il faudra plutôt voir ces opérations comme de vrais workflows persistants. Un simple Task ne remplacera pas ce mécanisme, mais il nous permet déjà de ne pas bloquer le Control Plane sur les opérations que nous exécutons aujourd’hui.

Ce que l’on va exécuter maintenant sera du shell, on va donc créer une classe pour simplifier l’exécution de nos commandes :

public sealed class ShellRunner
{
    public async Task RunAsync(string command)
    {
        Console.WriteLine($"> {command}");

        var startInfo = new ProcessStartInfo
        {
            FileName = "wsl.exe",
            UseShellExecute = false,
            RedirectStandardOutput = true,
            RedirectStandardError = true
        };

        startInfo.ArgumentList.Add("-u");
        startInfo.ArgumentList.Add("root");
        startInfo.ArgumentList.Add("--");
        startInfo.ArgumentList.Add("bash");
        startInfo.ArgumentList.Add("-lc");
        startInfo.ArgumentList.Add(command);

        using var process = Process.Start(startInfo)
            ?? throw new InvalidOperationException("Unable to start shell process.");

        var stdoutTask = process.StandardOutput.ReadToEndAsync();
        var stderrTask = process.StandardError.ReadToEndAsync();

        await process.WaitForExitAsync();

        Console.Write(await stdoutTask);

        if (process.ExitCode != 0)
            throw new InvalidOperationException(await stderrTask);
    }
}

La classe est légèrement simplifiée, mais elle devrait s’exécuter correctement. Vous pouvez trouver la version complète sur le GitHub de PandaCloud :

https://github.com/MarieLePanda/PandaCloud

Maintenant, on va construire notre infrastructure provider pour notre environnement.

L’infrastructure

Si vous avez lu correctement le précédent blog post, on avait créé un tenant de la façon suivante :

sudo ip link add pc-alice type bridge
sudo ip link set pc-alice up

Nous allons donc reprendre ces commandes dans notre Control Plane avec une légère modification, mais importante.

Que se passe-t-il si le tenant d’Alice existe déjà ? Peu importe la raison pour laquelle cette commande serait exécutée alors que le tenant existe déjà.

Rien de bon. Une commande rejouée peut provoquer une erreur ou, selon l’opération, créer un doublon. On va donc devoir rendre nos opérations idempotentes, c’est-à-dire faire en sorte que les exécuter plusieurs fois conduise au même état final.

public async Task CreateTenantNetworkAsync(Tenant tenant)
{
    await _shellRunner.RunAsync(
        $"sudo ip link show {tenant.BridgeName} >/dev/null 2>&1 || " +
        $"sudo ip link add {tenant.BridgeName} type bridge");

    await _shellRunner.RunAsync(
        $"sudo ip link set {tenant.BridgeName} up");
}

Même chose pour les nœuds, qui avaient été créés avec la commande :

sudo ip netns add node10

Là encore, il faut simplement être sûr que le nœud n’est pas déjà créé :

public async Task CreateNodeAsync(Node node)
{
    await _shellRunner.RunAsync(
        $"if ! sudo ip netns list | grep -qw {node.Name}; then " +
        $"sudo ip netns add {node.Name}; " +
        $"fi");
}

Dernière étape pour le moment, il faut attacher un nœud à un tenant.

Cette partie est un peu plus compliquée, car cela signifie attacher, avec un veth (nos câbles virtuels), notre nœud au réseau du tenant. Et, encore une fois, il faut le faire de manière idempotente.

private static string ShortInterfaceName(string name)
{
    // Linux interface names are limited to 15 characters.
    // Enhance the method in the future to generate unique names.
    return name.Length <= 15 ? name : name[..15];
}

private static string GetHostInterfaceName(string nodeName)
{
    var hostVeth = ShortInterfaceName($"v-{nodeName}-h");
    return hostVeth;
}

private static string GetNodeInterfaceName(string nodeName)
{
    var nodeVeth = ShortInterfaceName($"v-{nodeName}-n");
    return nodeVeth;
}

public async Task AttachNodeToTenantAsync(
    Node node,
    Tenant tenant,
    string ipAddress)
{
    var hostVeth = GetHostInterfaceName(node.Name);
    var nodeVeth = GetNodeInterfaceName(node.Name);

    await _shellRunner.RunAsync(
        $"if ! sudo ip link show {hostVeth} >/dev/null 2>&1; then " +
        $"sudo ip link add {hostVeth} type veth peer name {nodeVeth} && " +
        $"sudo ip link set {nodeVeth} netns {node.Name}; " +
        $"fi");

    await _shellRunner.RunAsync(
        $"sudo ip link set {hostVeth} master {tenant.BridgeName}");

    await _shellRunner.RunAsync(
        $"sudo ip link set {hostVeth} up");

    await _shellRunner.RunAsync(
        $"sudo ip netns exec {node.Name} ip link set lo up");

    await _shellRunner.RunAsync(
        $"sudo ip netns exec {node.Name} ip link set {nodeVeth} up");

    await _shellRunner.RunAsync(
        $"sudo ip netns exec {node.Name} ip addr flush dev {nodeVeth}");

    await _shellRunner.RunAsync(
        $"sudo ip netns exec {node.Name} ip addr add {ipAddress}/24 dev {nodeVeth}");
}

Gérer le cycle de vie

On peut créer nos ressources et les attacher, mais il est aussi nécessaire de penser à ce qui peut se passer plus tard.

En l’occurrence, un nœud peut être créé, ça c’est bon. Il est ensuite alloué à un tenant, c’est bon aussi. Mais il sera très probablement libéré dans le futur, pour être réassigné ailleurs, voire détruit.

La dernière fois, on s’était arrêté à cette partie. Il est donc temps de continuer et de voir comment gérer cela au niveau Linux, puis de l’implémenter de la même manière dans notre Control Plane.

public async Task DeleteNodeAsync(Node node)
{
    await _shellRunner.RunAsync(
        $"if sudo ip netns list | grep -qw {node.Name}; then " +
        $"sudo ip netns delete {node.Name}; " +
        $"fi");
}

Même principe pour supprimer le réseau d’un tenant :

public async Task DeleteTenantNetworkAsync(Tenant tenant)
{
    await _shellRunner.RunAsync(
        $"if ip link show dev {tenant.BridgeName} >/dev/null 2>&1; then " +
        $"sudo ip link delete dev {tenant.BridgeName} type bridge; " +
        $"fi");
}

Et enfin pour libérer un nœud de son réseau :

public async Task ReleaseNodeAsync(Node node)
{
    var hostInterface = GetHostInterfaceName(node.Name);

    await _shellRunner.RunAsync(
        $"if sudo ip link show dev {hostInterface} >/dev/null 2>&1; then " +
        $"sudo ip link delete dev {hostInterface}; " +
        $"fi");
}

Notre Control Plane est donc fini ?

Eh non, en fait, on n’a même pas commencé à le coder.

On a jusqu’à maintenant des opérations assez robustes pour gérer notre infrastructure, mais vous avez pu remarquer qu’il manque pas mal de vérifications.

Que se passe-t-il pour mes ressources quand le tenant est supprimé ? Comment puis-je demander une certaine capacité à mon tenant ?

Il manque en fait toute notre couche service, et c’est vraiment là que l’on va créer notre classe ControlPlane.

Le Control Plane, le vrai !

Toutes ces fonctions qui agissent sur l’infrastructure vont maintenant être appelées par une couche de service qui sera notre vrai Control Plane.

On va donc retrouver des fonctions similaires, mais avec cette fois-ci une validation métier avant que la commande soit réellement exécutée.

Encore une fois, les premières fonctions vont être la création de tenants et de nœuds :

public async Task CreateTenantAsync(string name)
{
    if (_cloudState.Tenants.Any(t =>
        t.Name.Equals(name, StringComparison.OrdinalIgnoreCase)))
    {
        throw new Exception($"Tenant with name {name} already exists.");
    }

    string networkId = FindNextNetworkId(_cloudState).ToString();

    Tenant newTenant = new Tenant
    {
        Name = name,
        BridgeName = $"br-{name.ToLower()}",
        Subnet = $"10.{networkId}.0.0/24",
        Gateway = $"10.{networkId}.0.1",
    };

    await _infrastructureProvider.CreateTenantNetworkAsync(newTenant);

    _cloudState.Tenants.Add(newTenant);

    Console.WriteLine(
        $"Tenant {name} created with subnet {newTenant.Subnet} " +
        $"and gateway {newTenant.Gateway}.");
}

Pour le moment, on réserve l’adresse .1 comme gateway dans notre modèle. Le routage sera ajouté plus tard.

La création d’un nœud suit la même logique :

public async Task CreateNodeAsync(string nodeName, int cpuCores)
{
    if (_cloudState.Nodes.Any(n =>
        n.Name.Equals(nodeName, StringComparison.OrdinalIgnoreCase)))
    {
        throw new Exception($"Node with name {nodeName} already exists.");
    }

    Node newNode = new Node
    {
        Name = nodeName,
        CpuCores = cpuCores,
    };

    await _infrastructureProvider.CreateNodeAsync(newNode);

    _cloudState.Nodes.Add(newNode);

    Console.WriteLine($"Node {nodeName} created.");
}

Ici, CpuCores représente pour le moment une capacité déclarée dans le Control Plane. Nos network namespaces ne limitent pas réellement le CPU. On implémentera plus tard un provider capable d’appliquer réellement cette capacité.

Une fois cela fait, il faut encore gérer ce qui est légèrement plus compliqué : l’allocation d’un nœud à un tenant.

C’est plus compliqué parce qu’en plus de vérifier les différentes conditions valides, il faut aussi donner à ce nœud une IP libre :

public async Task AllocateNodeAsync(string nodeName, string tenantName)
{
    Node? node = _cloudState.Nodes.FirstOrDefault(n =>
        n.Name.Equals(nodeName, StringComparison.OrdinalIgnoreCase));

    if (node == null)
        throw new Exception($"Node {nodeName} does not exist.");

    Tenant? tenant = _cloudState.Tenants.FirstOrDefault(t =>
        t.Name.Equals(tenantName, StringComparison.OrdinalIgnoreCase));

    if (tenant == null)
        throw new Exception($"Tenant {tenantName} does not exist.");

    if (node.State != NodeState.Available)
        throw new Exception($"Node {nodeName} is not available for allocation.");

    string networkId = tenant.Subnet.Split('.')[1];
    string ipAddress = $"10.{networkId}.0.{tenant.NextHostAddress}";

    tenant.NextHostAddress++;

    await _infrastructureProvider.AttachNodeToTenantAsync(
        node,
        tenant,
        ipAddress);

    node.TenantName = tenantName;
    node.IpAddress = ipAddress;
    node.State = NodeState.Allocated;

    Console.WriteLine(
        $"Node {nodeName} allocated to tenant {tenantName} " +
        $"with IP address {ipAddress}.");
}

Je vous passe le détail des autres fonctions qui servent à désallouer le nœud, le supprimer, etc. Cela ressemble beaucoup aux méthodes vues jusqu’ici, il y a donc peu d’intérêt à les détailler.

Encore une fois, elles sont disponibles sur le GitHub de PandaCloud :

https://github.com/MarieLePanda/PandaCloud

Testons notre Control Plane

Il est temps de voir notre Control Plane en action.

Pour cela, il manque néanmoins une brique : les points d’entrée permettant d’appeler ces fonctions. On pourrait créer un contrôleur pour recevoir des appels HTTP afin d’exécuter nos actions, mais on va rester simple en les exécutant via la ligne de commande, en passant des arguments.

CloudState cloudState = new CloudState();

IInfrastructureProvider provider = new LinuxProvider();

ControlPlane controlPlane = new ControlPlane(cloudState, provider);

try
{
    switch (args)
    {
        case ["tenant", "create", var tenantName]:
            await controlPlane.CreateTenantAsync(tenantName);
            break;

        case ["tenant", "list"]:
            await controlPlane.ListTenantsAsync();
            break;

        case ["node", "create", var nodeName, var cpuCores]:
            await controlPlane.CreateNodeAsync(nodeName, int.Parse(cpuCores));
            break;

        case ["node", "allocate", var nodeName, var tenantName]:
            await controlPlane.AllocateNodeAsync(nodeName, tenantName);
            break;

        case ["node", "list"]:
            await controlPlane.ListNodesAsync();
            break;

        case ["node", "release", var nodeName]:
            await controlPlane.ReleaseNodeAsync(nodeName);
            break;

        case ["node", "delete", var nodeName]:
            await controlPlane.DeleteNodeAsync(nodeName);
            break;

        case ["capacity", "request", var tenantName, var cpuCores]:
            await controlPlane.RequestCapacity(tenantName, int.Parse(cpuCores));
            break;

        case ["reconcile"]:
            await controlPlane.ReconcileAsync();
            break;

        default:
            Console.Error.WriteLine("Unknown command.\n");
            PrintHelp();
            Environment.ExitCode = 1;
            break;
    }
}
catch (Exception ex)
{
    Console.ForegroundColor = ConsoleColor.Red;
    Console.Error.WriteLine($"Error: {ex.Message}");
    Console.ResetColor();
    Environment.ExitCode = 1;
}

Et on va pouvoir commencer à lancer nos premières commandes, comme :

dotnet run -- tenant list

No tenant.

« Comment ça, no tenant ? Où sont Bob et Alice ? »

Eh oui, jusqu’à maintenant, nos ressources avaient été créées directement en Bash. Elles sont donc absentes du CloudState, qui garde justement en mémoire l’état de notre cloud.

D’ailleurs, jusqu’ici, le CloudState ne fonctionne qu’en mémoire. Ce n’est pas idéal, surtout pour une application console.

On va donc rapidement corriger cela en sauvegardant notre CloudState après chaque modification.

public class StateStore
{
    private readonly string _stateDirectory;
    private readonly string _stateFile;

    private readonly JsonSerializerOptions _jsonOptions = new()
    {
        WriteIndented = true,
        Converters = { new JsonStringEnumConverter() }
    };

    public StateStore()
    {
        _stateDirectory = Path.Combine(
            Environment.CurrentDirectory,
            ".pandacloud");

        _stateFile = Path.Combine(
            _stateDirectory,
            "state.json");
    }

    public async Task<CloudState> LoadAsync()
    {
        if (!File.Exists(_stateFile))
            return new CloudState();

        var json = await File.ReadAllTextAsync(_stateFile);

        return JsonSerializer.Deserialize<CloudState>(json, _jsonOptions)
            ?? new CloudState();
    }

    public async Task SaveAsync(CloudState state)
    {
        Directory.CreateDirectory(_stateDirectory);

        var json = JsonSerializer.Serialize(state, _jsonOptions);

        await File.WriteAllTextAsync(_stateFile, json);
    }
}

On va maintenant, à chaque exécution, charger l’état actuel et sauvegarder le nouvel état après chaque modification de notre infrastructure.

Sauvegarder l’état d’un cloud dans un fichier JSON n’est évidemment pas idéal, car c’est un état qui change constamment, mais à notre niveau c’est bien suffisant.

N’oubliez pas d’adapter le point d’entrée de votre Control Plane pour charger et sauvegarder l’état avec cette nouvelle classe. Le GitHub, toussa, toussa.

On teste pour de vrai cette fois

Allez, maintenant on a tout, on peut lancer.

Commençons par la création du tenant d’Alice :

PS C:\Users\lgirardin\source\repos\PandaCloud> dotnet run -- tenant create alice
> sudo ip link show br-alice >/dev/null 2>&1 || sudo ip link add br-alice type bridge
> sudo ip link set br-alice up
Tenant alice created with subnet 10.10.0.0/24 and gateway 10.10.0.1.

PS C:\Users\lgirardin\source\repos\PandaCloud> dotnet run -- tenant list
TENANT           NETWORK              BRIDGE
--------------------------------------------------------
alice            10.10.0.0/24         br-alice

Il semble bien créé, mais allons vérifier nous-mêmes sur la machine Linux plutôt que d’avoir une confiance aveugle dans le Data Plane :

lgirardin@lgirardin-pc:~$ ip link show br-alice

22: br-alice: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default qlen 1000
    link/ether d2:5b:d8:9c:56:59 brd ff:ff:ff:ff:ff:ff

Notre bridge a donc bien été créé. Il est administrativement UP, mais son état opérationnel est encore DOWN car aucune interface active n’y est encore attachée.

Commençons donc à créer des nœuds pour Alice :

dotnet run -- node create Node25 12
dotnet run -- node create Node26 12
dotnet run -- node create Node27 6
dotnet run -- node create Node28 6

dotnet run -- node list

NODE             STATE        TENANT           IP               CPU
--------------------------------------------------------------------
Node25           Available    -                -                12
Node26           Available    -                -                12
Node27           Available    -                -                6
Node28           Available    -                -                6

Il ne reste plus qu’à les allouer à Alice :

PS C:\Users\lgirardin\source\repos\PandaCloud> dotnet run -- node allocate node25 alice

> if ! sudo ip link show v-Node25-h >/dev/null 2>&1; then sudo ip link add v-Node25-h type veth peer name v-Node25-n && sudo ip link set v-Node25-n netns Node25; fi
> sudo ip link set v-Node25-h master br-alice
> sudo ip link set v-Node25-h up
> sudo ip netns exec Node25 ip link set lo up
> sudo ip netns exec Node25 ip link set v-Node25-n up
> sudo ip netns exec Node25 ip addr flush dev v-Node25-n
> sudo ip netns exec Node25 ip addr add 10.10.0.10/24 dev v-Node25-n

Node node25 allocated to tenant alice with IP address 10.10.0.10.

Voilà pour un, je vous laisse faire les autres ! Le but est d’arriver à ce résultat :

PS C:\Users\lgirardin\source\repos\PandaCloud> dotnet run -- node list

NODE             STATE        TENANT           IP               CPU
--------------------------------------------------------------------
Node25           Allocated    alice            10.10.0.10       12
Node26           Allocated    alice            10.10.0.11       12
Node27           Allocated    alice            10.10.0.12       6
Node28           Allocated    alice            10.10.0.13       6

Encore une fois, ici c’est l’état donné par le Control Plane, mais allons quand même vérifier directement sur notre machine Linux.

Les namespaces d’abord :

sudo ip netns list

Node28 (id: 12)
Node27 (id: 11)
Node26 (id: 10)
Node25 (id: 9)

On vérifie au passage que notre bridge, donc le réseau de notre tenant, est maintenant UP puisque des interfaces actives y sont attachées :

ip link show br-alice

22: br-alice: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
    link/ether d2:5b:d8:9c:56:59 brd ff:ff:ff:ff:ff:ff

Vérification côté host

On peut voir les interfaces veth attachées à notre bridge :

ip link show master br-alice

Ou utiliser directement :

bridge link show

On retrouve alors les interfaces côté host :

24: v-Node25-h@if23: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br-alice state forwarding priority 32 cost 2
26: v-Node26-h@if25: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br-alice state forwarding priority 32 cost 2
28: v-Node27-h@if27: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br-alice state forwarding priority 32 cost 2
30: v-Node28-h@if29: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br-alice state forwarding priority 32 cost 2

Vérification côté nœud

Pour regarder cette fois réellement à l’intérieur du namespace Node25 :

sudo ip netns exec Node25 ip addr show

On peut aussi regarder uniquement son interface réseau :

sudo ip netns exec Node25 ip addr show v-Node25-n

Et vérifier ses routes :

sudo ip netns exec Node25 ip route

Enfin, on peut vérifier que deux nœuds appartenant au même tenant communiquent bien entre eux :

sudo ip netns exec Node25 ping -c 3 10.10.0.11

Si tout fonctionne, Node25 doit pouvoir joindre Node26 directement via br-alice.

Nous arrivons au bout de notre Control Plane pour le moment. On peut continuer à tester les différents use cases, mais vous avez, je pense, compris la logique.

Notre Control Plane est cependant loin d’être terminé, et c’est ce que l’on verra dans une prochaine partie avec l’allocation de capacité !

Building your own cloud : The network

Mary 🇪🇺 🇷🇴 🇫🇷 — Thu, 17 Sep 2026 18:08:50 +0000

Build a Cloud at Home

“The cloud is just someone else’s computer.”

You’ve probably heard that sentence before. Maybe a little less in 2026, but barely 10 years ago it was one of the favorite lines of the anti-cloud crowd.

What this sentence basically means is that the cloud is just a provider giving you access to a machine so you don’t have to manage that machine yourself.

That was already a pretty reductive view 10 years ago, but can we really blame users for seeing little more than a virtual machine provider and therefore not really seeing the difference between what we call a Cloud Provider and a traditional hosting provider?

From a customer’s perspective, both can indeed be summarized as “someone else’s computer.”

So, 10 years later, maybe a little late, it’s time to explain simply what the cloud actually is.

And what better way to do that than to start building one?

The First Building Blocks

So where do we start?

We can begin by breaking our cloud down into three fairly fundamental building blocks. We’ll later use these to build services, and even other building blocks for more advanced services.

Those fundamentals are:

Logically isolated networks for each customer, with each customer representing a tenant.
Compute, meaning the resources on which our workloads will run, whether as VMs or something else.
Storage, which can mean disk space or object storage.

All of this is organized and orchestrated by a software layer we call the Control Plane.

“Yeah, but the cloud is hundreds, even thousands of machines. How am I supposed to build that at home?”

Don’t panic, my friend.

We’re not going to put a huge pile of computers on a network and start controlling their configuration and resource allocation remotely.

Well, you can if you want to, but we can simulate how a cloud works much more easily.

All we need is a Linux distribution and a little imagination to reproduce the concepts we want to explore.

Tenant Network Isolation

Let’s start with a simple problem.

Suppose we have two customers, Alice and Bob. Get used to Alice and Bob because they’re about to become your best friends.

They both share the same infrastructure.

How do we prevent Bob from accessing Alice’s network and vice versa?

The Network Namespace

You may have already heard some Kubernetes hipster tell you that Docker didn’t really invent anything with containers, it just used Linux Network Namespaces.

That’s not entirely wrong.

On Linux, a network namespace allows network resources used by processes to be isolated from a networking perspective.

As for Docker, we’ll get back to that another time.

In our simulation, we’re going to use each network namespace to represent a node placed inside its tenant’s network.

By node, we simply mean a resource that could represent a physical computer or a VM.

The Bridge

Another component that will be useful for simulating our cloud is the Linux bridge.

It will act as the virtual equivalent of a network switch.

We’ll use it to connect our customers’ nodes together.

Veth Pair

How do you connect a node to a network?

With a cable, obviously.

That will be the role of our Veth pair.

One side will be connected to our node, while the other side will be connected to our virtual switch.

There we go.

We now have the fundamental building blocks we need for our network.

First, let’s create our nodes, which will later be assigned to different tenants.

No need to create too many of them for now.

sudo ip netns add node10
sudo ip netns add node20
sudo ip netns add node30
sudo ip netns add node40

Then let’s create our switches.

sudo ip link add pc-alice type bridge
sudo ip link set pc-alice up

sudo ip link add pc-bob type bridge
sudo ip link set pc-bob up

Building Alice’s Network

To build Alice’s network, we need to connect Alice’s nodes to the same switch so they can communicate with each other, and only with each other.

So let’s create our first virtual cable.

sudo ip link add v-node10-h type veth peer name v-node10-n

sudo ip link set v-node10-n netns node10

sudo ip link set v-node10-h master pc-alice

sudo ip link set v-node10-h up

Then configure the subnet.

sudo ip netns exec node10 ip link set lo up

sudo ip netns exec node10 ip link set v-node10-n up

sudo ip netns exec node10 ip addr add 10.10.0.10/24 dev v-node10-n

We do exactly the same thing for the next node so we have two machines inside the same tenant.

sudo ip link add v-node20-h type veth peer name v-node20-n

sudo ip link set v-node20-n netns node20

sudo ip link set v-node20-h master pc-alice

sudo ip link set v-node20-h up

sudo ip netns exec node20 ip link set lo up

sudo ip netns exec node20 ip link set v-node20-n up

sudo ip netns exec node20 ip addr add 10.10.0.11/24 dev v-node20-n

Building Bob’s Network

One customer is nice, but we’ve never seen a Cloud Provider with only one customer.

So let’s not waste any time and do the same thing for Bob, who will own nodes 30 and 40.

sudo ip link add v-node30-h type veth peer name v-node30-n

sudo ip link set v-node30-n netns node30

sudo ip link set v-node30-h master pc-bob

sudo ip link set v-node30-h up

sudo ip netns exec node30 ip link set lo up

sudo ip netns exec node30 ip link set v-node30-n up

sudo ip netns exec node30 ip addr add 10.20.0.10/24 dev v-node30-n

sudo ip link add v-node40-h type veth peer name v-node40-n

sudo ip link set v-node40-n netns node40

sudo ip link set v-node40-h master pc-bob

sudo ip link set v-node40-h up

sudo ip netns exec node40 ip link set lo up

sudo ip netns exec node40 ip link set v-node40-n up

sudo ip netns exec node40 ip addr add 10.20.0.11/24 dev v-node40-n

The procedure is obviously identical.

And that repetition is actually important, because a large part of the challenge of cloud computing is being able to reproduce this kind of operation automatically, reliably, and at scale.

Testing Communication

Alright, now it’s time to check whether our networks actually work.

Alice’s nodes should be able to communicate with each other, and the same should be true for Bob.

But we also need to test isolation.

Our two customers must not be able to talk to each other.

Let’s ping node20 from node10, since both belong to Alice.

sudo ip netns exec node10 ping -c 3 10.10.0.11

PING 10.10.0.11 (10.10.0.11) 56(84) bytes of data.

64 bytes from 10.10.0.11: icmp_seq=1 ttl=64 time=16.0 ms
64 bytes from 10.10.0.11: icmp_seq=2 ttl=64 time=0.160 ms
64 bytes from 10.10.0.11: icmp_seq=3 ttl=64 time=0.103 ms

--- 10.10.0.11 ping statistics ---

3 packets transmitted, 3 received, 0% packet loss, time 2006ms

rtt min/avg/max/mdev = 0.103/5.437/16.048/7.503 ms

And let’s do the same thing from node30 to node40, which both belong to Bob.

sudo ip netns exec node30 ping -c 3 10.20.0.11

PING 10.20.0.11 (10.20.0.11) 56(84) bytes of data.

64 bytes from 10.20.0.11: icmp_seq=1 ttl=64 time=0.791 ms
64 bytes from 10.20.0.11: icmp_seq=2 ttl=64 time=0.241 ms
64 bytes from 10.20.0.11: icmp_seq=3 ttl=64 time=0.260 ms

--- 10.20.0.11 ping statistics ---

3 packets transmitted, 3 received, 0% packet loss, time 2029ms

rtt min/avg/max/mdev = 0.241/0.430/0.791/0.254 ms

On the other hand, Alice cannot communicate with Bob’s network.

sudo ip netns exec node10 ping -c 3 10.20.0.10

ping: connect: Network is unreachable

So we do indeed have a first form of isolation.

“Hey, wait a minute. You just created two networks that don’t communicate with each other. This is first-year networking stuff and you’re calling that cloud? Are you taking the piss? They can’t communicate simply because there’s no route! I do remember my networking classes, you know!”

The Route Test

Very good point.

Two distinct IP subnets need some form of routing mechanism to communicate.

So what happens if we try adding a route?

sudo ip netns exec node10 ip route add 10.20.0.0/24 dev v-node10-n

Now let’s look at the routing table.

sudo ip netns exec node10 ip route

10.10.0.0/24 dev v-node10-n proto kernel scope link src 10.10.0.10
10.20.0.0/24 dev v-node10-n scope link

There we go, we have a route.

Let’s test it.

sudo ip netns exec node10 ping -c 3 10.20.0.10

PING 10.20.0.10 (10.20.0.10) 56(84) bytes of data.

From 10.10.0.10 icmp_seq=1 Destination Host Unreachable
From 10.10.0.10 icmp_seq=2 Destination Host Unreachable
From 10.10.0.10 icmp_seq=3 Destination Host Unreachable

--- 10.20.0.10 ping statistics ---

3 packets transmitted, 0 received, +3 errors, 100% packet loss, time 2049ms

pipe 3

Well, nope.

Still not working.

This route does not actually create a path to Bob.

It simply tells Alice to consider the 10.20.0.0/24 network as directly reachable through its v-node10-n interface.

This time Alice knows which interface it should try to use to send its traffic.

The problem is now lower down, at Layer 2.

Node10 looks for 10.20.0.10 on its Ethernet network by sending an ARP request, but that request remains confined to the pc-alice bridge.

There is no Layer 2 path to pc-bob.

Our two networks are therefore properly isolated in our current architecture.

So is the cloud really just first-year networking?

Yes and no.

The networking part here is fairly basic, but cloud infrastructure does not need to be complicated by design.

Quite the opposite.

It becomes more complex as we progressively add more features, so whenever something can remain simple, let’s keep it simple.

The really interesting part starts when we automate the creation and management of this infrastructure at scale: creating new tenants, deleting old ones, changing their limits, allocating and deallocating nodes, moving resources around, and so on.

Continuously managing the state of thousands, or even millions, of elements is where things really start to become interesting.

And that software layer will be the subject of Part 2, because there’s a lot to talk about.

And a lot to code.

Construire son cloud - Le réseau

Mary 🇪🇺 🇷🇴 🇫🇷 — Thu, 17 Sep 2026 18:06:18 +0000

Construire un cloud chez soi

« Le cloud c’est juste l’ordinateur de quelqu’un d’autre ». Vous avez sans doute déjà entendu cette phrase, peut-être un peu moins en 2026, mais il y a à peine 10 ans de cela, c’était la phrase fétiche des anti-cloud.

Cette phrase signifie que le cloud c’est juste un fournisseur qui vous met à disposition une machine pour que vous n’ayez pas vous-même à vous occuper de cette machine.

C’était déjà réducteur il y a 10 ans, mais peut-on en vouloir aux utilisateurs de finalement ne voir qu’un fournisseur de machines virtuelles et donc de ne pas voir la différence entre ce qu’on appelle un Cloud Provider et un hébergeur classique ? C’est vrai que dans les deux cas on pourrait résumer ça, côté client, à « l’ordinateur de quelqu’un d’autre ».

10 ans après, un peu tard peut-être donc, il est temps d’expliquer simplement à tout le monde ce qu’est le cloud. Et pour cela quoi de mieux que de commencer à en construire un !

Les premiere briques

Alors par quoi commencer ? On peut commencer par découper notre cloud en trois briques assez fondamentales qui serviront ensuite à construire par-dessus des services, voire d’autres briques pour d’autres services.

Ces fondamentaux sont :

Des réseaux isolés logiquement pour chaque client, chaque client constituant un tenant.
Du calcul, c’est-à-dire les ressources sur lesquelles vont tourner nos workloads, sous forme de VM ou pas d’ailleurs.
Du stockage, qui peut être de l’espace disque ou même du stockage objet.

Le tout, organisé ou orchestré par une couche logicielle qu’on nomme le Control Plane !

« Oui mais le cloud c’est des centaines, voire des milliers de machines, comment je peux construire ça chez moi ? »

Pas de panique mon ami. Il n’est pas question ici de mettre des tas d’ordinateurs en réseau ensemble et de contrôler leur configuration ou leur distribution à distance.

Enfin, vous le pouvez si vous le souhaitez, mais on peut simuler le fonctionnement d'un cloud bien plus facilement.

Nous allons simplement avoir besoin d’une distribution Linux et d’un peu d’imagination pour simuler de façon correcte ce que l’on souhaite représenter.

L’isolation réseau des tenants

Commençons par un problème simple à résoudre. Si nous avons deux clients, que l’on nommera Alice et Bob (habituez-vous à Alice et Bob car ils vont devenir vos meilleurs amis), sur une même infrastructure, comment éviter que Bob puisse aller chez Alice et vice-versa ?

Le Network Namespace

Vous avez peut-être déjà entendu ce terme par des Kubernetes hipsters disant que Docker n’avait rien inventé avec les containers, qu’ils ont juste utilisé des Network Namespaces.

C’est pas totalement faux. En effet, sous Linux, un network namespace permet d’isoler d’un point de vue réseau les ressources utilisées par des processus. Pour Docker, on verra ça une prochaine fois.

Dans notre simulation, nous allons utiliser chaque network namespace pour représenter un nœud placé dans le réseau de son tenant.

Par nœud, on entend ici une ressource qui peut être un ordinateur ou une VM.

Le bridge

Un autre composant qui va nous être utile pour simuler notre cloud va être le bridge, qui jouera l’équivalent virtuel de notre switch.

On va donc pouvoir connecter les nœuds de nos clients à leur switch.

Veth pair

Comment on connecte un nœud à un réseau ? Avec un câble évidemment.

Cela va être le rôle de notre Veth pair qui sera branchée d’un côté à notre nœud, de l’autre à notre switch.

Voilà, on a nos briques fondamentales pour faire du réseau. On va donc pouvoir commencer à construire notre infrastructure.

D’abord, la création de nos nœuds qui seront affectés à différents tenants. Inutile d’en créer beaucoup pour le moment.

sudo ip netns add node10
sudo ip netns add node20
sudo ip netns add node30
sudo ip netns add node40

Puis la création de nos switchs.

sudo ip link add pc-alice type bridge
sudo ip link set pc-alice up

sudo ip link add pc-bob type bridge
sudo ip link set pc-bob up

Construire le réseau d’Alice

Pour construire le réseau d’Alice, il faut donc connecter les nœuds d’Alice au même switch afin qu’ils puissent communiquer entre eux et seulement entre eux.

On va donc créer notre premier câble virtuel.

sudo ip link add v-node10-h type veth peer name v-node10-n

sudo ip link set v-node10-n netns node10

sudo ip link set v-node10-h master pc-alice

sudo ip link set v-node10-h up

Puis configurer le sous-réseau.

sudo ip netns exec node10 ip link set lo up

sudo ip netns exec node10 ip link set v-node10-n up

sudo ip netns exec node10 ip addr add 10.10.0.10/24 dev v-node10-n

On fait exactement pareil sur le nœud suivant pour avoir deux machines sur le même tenant.

sudo ip link add v-node20-h type veth peer name v-node20-n

sudo ip link set v-node20-n netns node20

sudo ip link set v-node20-h master pc-alice

sudo ip link set v-node20-h up

sudo ip netns exec node20 ip link set lo up

sudo ip netns exec node20 ip link set v-node20-n up

sudo ip netns exec node20 ip addr add 10.10.0.11/24 dev v-node20-n

Construire le réseau de Bob

Un client c’est bien, mais on n’a jamais vu un Cloud Provider avec un seul client.

Donc ne perdons pas de temps et faisons la même chose avec notre client Bob, qui aura lui les nœuds 30 et 40.

sudo ip link add v-node30-h type veth peer name v-node30-n

sudo ip link set v-node30-n netns node30

sudo ip link set v-node30-h master pc-bob

sudo ip link set v-node30-h up

sudo ip netns exec node30 ip link set lo up

sudo ip netns exec node30 ip link set v-node30-n up

sudo ip netns exec node30 ip addr add 10.20.0.10/24 dev v-node30-n

sudo ip link add v-node40-h type veth peer name v-node40-n

sudo ip link set v-node40-n netns node40

sudo ip link set v-node40-h master pc-bob

sudo ip link set v-node40-h up

sudo ip netns exec node40 ip link set lo up

sudo ip netns exec node40 ip link set v-node40-n up

sudo ip netns exec node40 ip addr add 10.20.0.11/24 dev v-node40-n

La procédure est bien sûr identique et c’est très important, car une grande partie du défi du cloud consiste justement à être capable de reproduire automatiquement ce genre d’opérations à grande échelle.

Testons la communication

Bien, maintenant il est temps de voir si nos réseaux sont fonctionnels, donc si les nœuds d’Alice peuvent communiquer entre eux, et même chose du côté de Bob.

Mais aussi de tester l’isolation. Nos deux clients ne doivent pas pouvoir se parler.

On va donc exécuter un ping du node10 vers le node20, qui appartiennent tous les deux à Alice.

sudo ip netns exec node10 ping -c 3 10.10.0.11

PING 10.10.0.11 (10.10.0.11) 56(84) bytes of data.

64 bytes from 10.10.0.11: icmp_seq=1 ttl=64 time=16.0 ms
64 bytes from 10.10.0.11: icmp_seq=2 ttl=64 time=0.160 ms
64 bytes from 10.10.0.11: icmp_seq=3 ttl=64 time=0.103 ms

--- 10.10.0.11 ping statistics ---

3 packets transmitted, 3 received, 0% packet loss, time 2006ms

rtt min/avg/max/mdev = 0.103/5.437/16.048/7.503 ms

Et la même chose du node30 au node40, qui appartiennent à Bob.

sudo ip netns exec node30 ping -c 3 10.20.0.11

PING 10.20.0.11 (10.20.0.11) 56(84) bytes of data.

64 bytes from 10.20.0.11: icmp_seq=1 ttl=64 time=0.791 ms
64 bytes from 10.20.0.11: icmp_seq=2 ttl=64 time=0.241 ms
64 bytes from 10.20.0.11: icmp_seq=3 ttl=64 time=0.260 ms

--- 10.20.0.11 ping statistics ---

3 packets transmitted, 3 received, 0% packet loss, time 2029ms

rtt min/avg/max/mdev = 0.241/0.430/0.791/0.254 ms

Par contre, il est impossible pour Alice ou Bob de communiquer avec l’autre réseau.

sudo ip netns exec node10 ping -c 3 10.20.0.10

ping: connect: Network is unreachable

Nous avons donc bien une première forme d’isolation.

« Hey mais attends, là on a juste créé deux réseaux qui ne communiquent pas, c’est niveau première année de BTS et tu appelles ça du cloud ? Est-ce que tu ne te foutrais pas un peu de notre gueule ? Là ça ne communique pas juste parce que ça n’a pas de route ! Je me rappelle quand même de mes cours ! »

Le test de la route

Très bonne remarque.

Deux sous-réseaux IP distincts ont besoin d’un mécanisme de routage pour communiquer.

Alors que se passe-t-il quand on tente d’ajouter une route ?

sudo ip netns exec node10 ip route add 10.20.0.0/24 dev v-node10-n

Puis regardons la table de routage :

sudo ip netns exec node10 ip route

10.10.0.0/24 dev v-node10-n proto kernel scope link src 10.10.0.10
10.20.0.0/24 dev v-node10-n scope link

Voilà, on a une route. Testons !

sudo ip netns exec node10 ping -c 3 10.20.0.10

PING 10.20.0.10 (10.20.0.10) 56(84) bytes of data.

From 10.10.0.10 icmp_seq=1 Destination Host Unreachable
From 10.10.0.10 icmp_seq=2 Destination Host Unreachable
From 10.10.0.10 icmp_seq=3 Destination Host Unreachable

--- 10.20.0.10 ping statistics ---

3 packets transmitted, 0 received, +3 errors, 100% packet loss, time 2049ms

pipe 3

Ah bah non, toujours pas.

Cette route ne crée pas réellement de chemin vers Bob. Elle dit simplement à Alice de considérer le réseau 10.20.0.0/24 comme directement accessible via son interface v-node10-n.

Cette fois Alice sait donc bien par quelle interface essayer d’envoyer son trafic.

Le problème est maintenant plus bas, au niveau de la couche 2.

Node10 cherche 10.20.0.10 sur son réseau Ethernet en envoyant une requête ARP, mais cette requête reste confinée au bridge pc-alice.

Il n’existe aucun chemin de couche 2 vers pc-bob.

Nos deux réseaux sont donc bien isolés dans notre architecture actuelle.

Alors le cloud, c’est juste du réseau de première année ?

Oui et non.

En effet, la partie réseau ici est assez basique, mais le cloud n’a pas besoin d’être compliqué dans son architecture.

Bien au contraire, il va se complexifier ensuite de façon intrinsèque et au fur et a mesure, donc quand des choses peuvent être gardées simples, gardons-les.

C’est quand on va commencer à automatiser la création et la gestion de cette infrastructure à grande échelle que va commencer à ressembler à un cloud : création de nouveaux tenants, suppression des anciens, modification de leurs limites, allocation et désallocation de nœuds, déplacement des ressources, etc.

Gérer en permanence l’état de milliers, voire de millions d’éléments, c’est là que les choses commencent vraiment à devenir intéressantes.

Et cette partie logicielle sera justement le sujet de la partie 2, car il y a beaucoup à dire.

Et à coder.

Understood and implement the scoring algo BM 25

Mary 🇪🇺 🇷🇴 🇫🇷 — Mon, 23 Jun 2025 19:16:11 +0000

As an SRE, I often have to look for information in logs—a lot of logs, a ton of information, across many files. And generally, whether you're on the internet or just on your own computer, you're facing the same problem: you need to find information buried in an ever-growing pile of documents.

That brings us to a key problem: when I search for the word Panda on my computer, which file should come up first? The most recent one? No—the most relevant one! And figuring out whether a document is relevant to a search query is today’s topic.

Grab a seat, get yourself a coffee, tea, or hot chocolate. Let’s go!

Today's problem can be summarized like this: for any search, I want to assign a relevance score to my documents. The first document returned should be the one with the highest score!

Before we begin: a quick note. This article contains some mathematical formulas. Don’t worry—we’ll go through everything step by step, and I’ll explain things clearly so they’re easy to understand.

We'll start with a small list of documents that will guide us through this discussion.

Here they are:

Doc 1: “A panda is a black and white animal”
Doc 2: “The dog is white”
Doc 3: “The cat is black”
Doc 4: “The panda is neither a cat nor a dog”
Doc 5: “The red panda is red”
Doc 6: “Black is black, there's really no more hope I’m in the dark, I find it hard to believe Black is black, it's never too late Black is black, I still have hope Black is black, I still have hope Black is black, I still have hope”

This is a simple test set, but it already helps us see the problem with scoring.

Let’s start intuitively: if I search for the word “black”, which document is the most relevant? Among documents 1, 3, and 6?

Not easy, right?

Before We Go Further: Some Definitions

Token

Our documents—and even our search queries—aren’t made of “words,” but what we’ll refer to as tokens.

In this blog post, a word = a token. So nothing really changes, but since we’ll use the term token throughout the article, better clarify it now.

For example, document 1 contains the following tokens:
“A”, “panda”, “is”, “a”, “black”, “and”, “white”

Inverted Index

When we search for the word black in our documents, we don’t open them one by one to see if the word is inside.

Before any search happens, our application must index the documents—scan through them to extract the tokens in each. During this step, we build what’s called an inverted index.

An inverted index is a dictionary where:

The key is a token
The value is a list of documents that contain that token

For example, our inverted index might include keys like:
“the”, “panda”, “is”, “a”, “animal”, “black”, “and”, “white”, “dog”, “cat”, …
The key “panda” is associated with documents 1, 4, and 5.
The key “black” is associated with documents 1, 3, and 6.
And so on.

Here’s a quick look at the classes we’ll be working with.

First, the Document class:

public class Document
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string Path { get; set; }
    public string Content { get; set; }
    public int Length { get; set; }
    public List<string> ContentTokens { get; set; }
    public List<string> TitleTokens { get; set; }
    public DateTime IndexedAt { get; set; } = DateTime.UtcNow;
}

And the search result, via the SearchResult class:

public class SearchResult
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string Path { get; set; }
    public string ContentSnippet { get; set; }
    public double Score { get; set; }
    public DateTime IndexedAt { get; set; }
}

Our final output will be a list of SearchResult objects.

Scoring Algorithm – Simple and Basic

A basic first approach is to count how many times a token appears in the document.
If I search for the token “black”, it appears once in doc1, once in doc3, and 11 times in doc6.

Let’s assign a score of 1 for each occurrence of the token. This is very easy to do in C# with LINQ:

public int GetScore(string token, Document doc)
{
    int score = 0;
    var tokens = Tokenize(content);
    score = doc.ContentTokens.Count(t => t == token.ToLowerInvariant());
    return score;
}

Here, we’re counting how many times the token from our query appears in the document.

So we’ll get a score of:

1 for documents 1 and 3
11 for document 6

Alright… But beyond the fact that token count may not be the best metric, we quickly hit another issue.

If my query is “cat”, “black”, then doc6 will still score 11, even though doc3— which contains both tokens—only scores 2.

And doc3 actually contains both query tokens! So intuitively, it should be considered more relevant!

To fix this first issue, we could add a boost to the score if the document contains all the tokens in the query.
But more importantly, we might want to reduce the impact of a token that appears many times in the same document.

Should a document that contains the token “black” 50 times have a score twice as high as one that contains it 25 times?
Probably not. It should be ahead, yes—but not by that much!

Also, documents 1 and 3 both have a score of 1 for the token “black”, and there's no way to break the tie with this simple method.

An Improved Version of the Scoring Function

We can modify our scoring function to:

Calculate the score for all query tokens
Limit the impact a single token can have on the final score
Boost results that match multiple tokens

public int GetScore(List<string> queryTokens, Document doc)
{
    int totalScore = 0;
    int matchToken = 0;

    foreach (var token in queryTokens)
    {
        int score = doc.ContentTokens.Count(t => t == token.ToLowerInvariant());
        if (score > 5)
            score = 5;

        if (score > 0)
            matchToken++;

        totalScore += score;
    }

    totalScore += matchToken * 10;
    return totalScore;
}

From now on, a token can no longer influence the score beyond 5.
And the document score gains 10 points per token found in the query.

Let’s do a new test with the query “cat”, “black”:
Matching documents are: 1, 3, 4, and 6.

Documents 1 and 4, which each contain only one token, will have a score of 11: 1 point for token frequency, and 10 points for matching a token in the query.
Document 3 will have a score of 22: 2 points for the presence of “cat” and “black”, and 20 points for matching 2 tokens in the query.
Document 6 will have 15 points: 5 points for the frequency of the token “black” (capped at 5), and 10 points for matching 1 token.

Final result:

Doc 3 → 22 points
Doc 6 → 15 points
Doc 1 and Doc 4 → 11 points

We’ve solved our first two problems… but we can do better!

Here, the real issue is the limit of 5.
It’s not so much the value “5” that’s problematic, but the fact that we have a linear score increase that suddenly stops at an arbitrary limit.

Diminishing Returns

To solve this problem, we won’t impose a fixed limit beyond which the frequency of a term no longer yields points, but instead apply diminishing returns. For example, the first occurrence is worth 1, the second 0.95, the third 0.92, etc.
Here is the formula we’ll use:

For example, using a decay value of 0.97 with the query “black”.

For a document with a frequency of the token “black” equal to 6, we get the following result:

The difference here is not striking (we would have had 6 before, now we have 5.4). But let’s calculate the frequency score with a token that appears even more:

For 20:

For 50:

For 100:

We now have a way to differentiate between two documents that don’t have the same number of occurrences of a token, without overly favoring a document that contains this token a very large number of times.

The impact of the term on the score decreases progressively.
We therefore get a non-linear progression, and avoid arbitrarily stopping the point at which a token’s frequency no longer has an effect.

public double GetScore(List<string> queryTokens, string content, double decay = 0.97)
{
    double totalScore = 0;
    int matchToken = 0;

    foreach (var token in queryTokens)
    {
        int frequency = doc.ContentTokens.Count(t => t == token.ToLowerInvariant());

        if (frequency > 0)
            matchToken++;

        double freqScore = (1 - Math.Pow(decay, frequency)) / (1 - decay);

        totalScore += freqScore;
    }

    if (matchToken == queryTokens.Count)
        matchToken *= 2;

    totalScore += matchToken * 10;

    return totalScore;
}

But can we do better? Or rather: what other problems might still arise?

Let’s try the following query: “the”, “animal”
If we base ourselves only on the frequency score (and we can, since no document matches both tokens, so the boost from the number of matched tokens will have no effect here), the documents containing the token “the” will all have the same score:

doc2 – 1
doc3 – 1
doc5 – 1
doc6 – 1

For the token “animal”, which appears only once in document 1, it will also receive a score of 1.

We therefore once again end up with a lack of discrimination between the documents. One might think that, since each term appears only once in each document, we can’t do better… But that’s wrong!
There is a difference: their frequency across the entire document set, not just within a single document.

The word “the” appears in almost every document, whereas “animal” appears in only one.

So there is a rarity difference — and we can take advantage of that.

TF-IDF

Until now, we have only calculated what is called TF (Term Frequency), which is the frequency of a token in a document. It is now time to include in our score the Inverse Document Frequency (IDF), to measure the rarity of a word across all documents.

The idea is that the rarer a word is, the more informative it is. Which is exactly the case here: the token “the”, present everywhere, doesn’t help refine the result.

To calculate our IDF, we will use the following formula:

Where t is the token, N the total number of documents in our corpus, and nt the number of documents containing this token.

Let’s calculate the IDF of “the”:

Then of “animal”:

And let’s use this IDF in our score calculation, now called TF-IDF (the multiplication of TF by IDF):
Since our TF is still equal to 1 here, the calculation is simplified: we only keep the IDF value.

The document scores for our query are now:

doc1 – 0.778
doc2 – 0.079
doc3 – 0.079
doc4 – 0.079
doc5 – 0.079
doc6 – 0.079

And if we had another document containing just the two tokens, it would rank first with a score of 0.857.

Notice that we no longer even need to artificially boost the score based on the number of matched tokens in the query — a boost which was arbitrary. And that’s much better!

We have the formula, now let’s move on to the code:

public double GetScore(List<string> queryTokens, Document doc, double decay = 0.97)
{
    double totalScore = 0;

    foreach (var token in queryTokens)
    {
        int frequency = doc.ContentTokens.Count(t => t == token.ToLowerInvariant());
        if (frequency == 0)
            continue;

        int df = ReversedIndex[token].Count;
        double idf = Math.Log((double)Documents.Count / (1 + df));

        double tf = (1 - Math.Pow(decay, frequency)) / (1 - decay);
        double tfidf = tf * idf;

        totalScore += tfidf;
    }

    return totalScore;
}

The frequency calculation doesn’t change: we simply retrieve the frequency of documents containing the token (df), thanks to our inverted index, which already contains this information.

The total number of documents is also already known at indexing time.

So we have our IDF, our TF, and therefore the final document score!

But… can we do even better?
Let’s look at the current limitations (even though we’re already doing pretty well).
One of the problems comes from TF: as we’ve seen, it can increase very quickly and skew the score.

At first, we implemented a saturation limit to prevent this. A limit that, normally, is not included in classic TF-IDF.

But despite this, the algorithm actually favors long documents (via TF), even though a long document is not necessarily more relevant.
Moreover, we have few parameters to tweak our results (except decay, which is also not present in the base version).

It’s therefore time to move on to a new algorithm: BM25.

Best Match 25

Best Match 25 is the 25ᵗʰ version of the algorithm meant to slightly address the problems of TF-IDF.

First, here is its formula:

No need to run away—if you’ve made it this far, you have all the tools in hand to understand it, and we’ll go through it together.

We already know the IDF, so no issue there. Let’s instead focus on what replaces the TF.

Let’s start with the numerator:

f(t,d) is the frequency of term t in document d.
k1 +1 is a way to control saturation, exactly like our decay earlier.

The smaller k1 is, the faster the saturation happens, which will reduce the impact of each additional token present in the document in a non-linear way.

For the denominator, we again find our term frequency and the variable k1 for saturation, along with a normalization factor related to the document length.

|d| is the actual length of the document (number of tokens it contains).
avgdl is the average length of our indexed documents.
b is a parameter that adjusts the importance of the normalization.

So, when a document is longer than average, its score will tend to decrease. On the other hand, a short document will see its score increase more quickly.

Let’s look at this with an example. Let’s reuse our list of documents and exclude document 6, which was very long. We’ll search for the token “black”.

Let’s start by defining our parameters k and b.

k1 will be 1.5
b will be 0.75

(these are fairly common values for these parameters).

Let’s also compute the average length of our documents, which is: 8 + 4 + 4 + 9 + 5, i.e., 30. Divided by the number of documents (5), we get an average length of 6.

So avgdl equals 6.

The token “black” appears in doc1 and doc3, with an IDF of 0.916.
Let’s start by calculating the score for document 1. Its length |d| is 8.

Let’s plug in the values in the numerator: term frequency in the document is 1, k1 is 1.5. We already know the IDF. So we get:

Or:

In the denominator, we can also replace known values (tf and k1):

We know the average document length and the current document length, so we can replace |d| and avgdl:

Or:

b is known, it is 0.75:

So we get:

A final score of 0.796 for document 1.
What about document 3?

Document 3 is very similar: the term frequency is still 1, and the IDF is the same. The only part that changes is the document length, which instead of being 8 out of 6, is 4 out of 6.

A final score of 1.077 for our document 3 — a better score than document 1!

A lot of calculations were needed to demonstrate how BM25 works, but since the operations are quite simple, they’re actually very easy to translate into code:

public double GetScore(List<string> queryTokens,  Document doc)
{
    double tfWeight = 1.5;
    double docLengthPenalty = 0.75;
    double score = 0;
    double avgDocLength = Documents.Average(doc => doc.Key.Length);

    foreach (var token in queryTokens)
    {
        int tf = doc.ContentTokens.Count(t => t == token.ToLowerInvariant());

        if (tf == 0 || !ReversedIndex.ContainsKey(token))
            continue;

        int df = ReversedIndex[token].Count;
        double idf = Math.Log((double)Documents.Count / (1 + df));

        double norm;

        norm = (tf * (tfWeight + 1)) /
                (tf + tfWeight * (1 - docLengthPenalty + docLengthPenalty * (doc.Content.Length / avgDocLength)));

        score += idf * norm;
    }

    return score;
}

Congratulations, you now know how to calculate a relevance score for a piece of content and return the best document to your user first.

Of course, other parameters can be considered, like tokens found in the title, the document’s modification date, or even its location.

Here, we focused on the content of a document, but this algorithm can be adapted and extended with other fields like the title, date, etc.

Comprendre et implémenter l'algo de score BM25

Mary 🇪🇺 🇷🇴 🇫🇷 — Tue, 17 Jun 2025 17:53:52 +0000

En tant que SRE, je dois souvent chercher des informations dans des logs, des tas de logs, beaucoup d’informations, dans beaucoup de fichier. Et en règle générale, que ce soit sur internet ou même sur votre ordinateur, vous êtes confronté au même problème. Vous devez chercher de l’information dans des documents qui s’accumulent de plus en plus.

On a là une problématique : quand je cherche le mot Panda sur mon ordinateur, quel fichier est-il censé me remonter en premier ? Le plus récent ? Non, le plus pertinent ! Et savoir si un document est pertinent par rapport à une recherche est le sujet du jour.

Installez-vous, prenez un café, un thé ou un chocolat chaud. C’est parti !

La problématique du jour peut être formalisée comme ceci : pour une recherche, je veux un score de pertinence lié à mes documents, et le premier document qui sortira de ma recherche sera celui avec le plus gros score !

Avant de commencer, un petit mot : cet article contient plusieurs formules mathématiques. Pas de panique, on va traverser ça ensemble étape par étape, et je vais tout expliquer clairement pour que ce soit simple à comprendre.

On va commencer avec une petite liste de documents pour nous accompagner tout au long.
C’est parti pour les présentations :

Doc 1 : « Un panda est un animal blanc et noir »
Doc 2 : « Le chien est blanc »
Doc 3 : « Le chat est noir »
Doc 4 : « Le panda n'est ni un chat ni un chien »
Doc 5 : « Le panda roux est roux »
Doc 6 :« Noir c'est noir, il n'y a vraiment plus d'espoir Je suis dans le noir, j'ai du mal à croire Noir c'est noir, il n'est jamais trop tard Noir c'est noir, il me reste l'espoir Noir c'est noir, il me reste l'espoir Noir c'est noir, il me reste l'espoir »

C’est un jeu de test assez simple, mais qui permet déjà de voir un peu le problème du scoring.

Commençons de façon intuitive : si je cherche le mot « noir », quel document est le plus pertinent ? Entre les documents 1, 3 et 6 ?

Pas facile hein ?

Avant d’entrer un peu plus dans la problématique, posons quelques définitions.

Token
Nos documents, et même notre recherche, ne sont pas composés de "mots", mais de ce qu’on va appeler des tokens.
Pour ce blog post, un mot = un token. Donc pas de gros changement, mais comme on va utiliser le mot token tout au long de l’article, autant le dire dès maintenant.
Par exemple, le doc 1 contient les tokens suivants :
[« Un », « panda », « est », « un », « animal », « blanc », « et », « noir »]

Index inversé
Quand on cherche le mot noir dans nos documents, on ne va pas les ouvrir un par un pour voir si le mot est dedans.
Avant toute recherche, notre application doit indexer les documents : les parcourir pour extraire les tokens présents dans chacun. Pendant cette étape, on construit ce qu’on appelle un index inversé.
Un index inversé, est un dictionnaire où :

La clé, est un token
La valeur associée, est la liste des documents qui contiennent ce token

Par exemple, notre index inversé contient les tokens/clés :
« le », « panda », « est », « un », « animal », « noir », « et », « blanc », « chien », « chat », …
La clé « panda », est associée aux documents 1, 4 et 5.
La clé « noir », est associée aux documents 1, 3 et 6.
Et ainsi de suite.

Voyons aussi un léger aperçu des classes que nous allons manipuler.

Nous avons en premier la classe Document:

public class Document
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string Path { get; set; }
    public string Content { get; set; }
    public int Length { get; set; }
    public List<string> ContentTokens { get; set; }
    public List<string> TitleTokens { get; set; }
    public DateTime IndexedAt { get; set; } = DateTime.UtcNow;
}

Et le résultat de notre recherche, via la classe SearchResult:

public class SearchResult
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string Path { get; set; }
    public string ContentSnippet { get; set; }
    public double Score { get; set; }
    public DateTime IndexedAt { get; set; }
}

Notre résultat final est donc une liste d’objets SearchResult.

Algorithme de score, simple, basique

Une première façon de faire que l’on pourrait imaginer, c’est de compter le nombre de fois qu’un token apparaît dans le document. Si je cherche le token « noir », il apparaît une fois dans le doc1, une fois dans le doc3 et 11 fois dans le doc6.
Donnons donc un score de 1 à chaque fois que le token est présent. Cela se fait très facilement en C# avec LINQ :

public int GetScore(string token, Document doc)
{
    int score = 0;
    var tokens = Tokenize(content);
    score = doc.ContentTokens.Count(t => t == token.ToLowerInvariant());
    return score;
}

Ici, nous comptons le nombre de fois où un token de notre requête est présent dans le document.

On aura donc un score de 1 pour les documents 1 et 3, et un score de 11 pour le document 6.

Bon… mis à part que le nombre de tokens n’est pas forcément un bon indicateur, on va vite se rendre compte d'un autre problème. Si ma requête est « chat », « noir », le document 6 aura toujours un score de 11, alors que le document 3, qui contient les deux tokens, n’aura qu’un score de 2.

Alors qu’il contient les deux tokens de ma requête ! Il est donc logiquement, pour nous, plus pertinent !

Pour régler ce premier problème, on peut ajouter un boost au score final quand un document contient tous les tokens.
Mais surtout, on peut tenter de réduire l’impact d’un token qui apparaît plusieurs fois dans un document.

Est-ce qu’un document qui contient 50 fois le token « noir » doit avoir un score deux fois supérieur à un document qui contient 25 fois le même token ?
Probablement pas. Être devant, oui, mais pas autant !

Et puis, les documents 1 et 3 ont le même score (1) pour le token « noir ».
Nous n'avons aucun moyen de les départager avec cette simple méthode.

Une version améliorée de la fonction de score

On peut modifier notre fonction de score pour :

Calculer le score pour tous les tokens de la requête
Limiter l’impact qu’un seul token peut avoir sur le score final
Booster les résultats qui matchent plusieurs tokens

public int GetScore(List<string> queryTokens, Document doc)
{
    int totalScore = 0;
    int matchToken = 0;

    foreach (var token in queryTokens)
    {
        int score = doc.ContentTokens.Count(t => t == token.ToLowerInvariant());
        if (score > 5)
            score = 5;

        if (score > 0)
            matchToken++;

        totalScore += score;
    }

    totalScore += matchToken * 10;
    return totalScore;
}

Désormais, un token ne peut plus influencer le score au-delà de 5.
Et le score du document gagne 10 points par token trouvé dans la requête.

Faisons un nouvel essai avec la requête « chat », « noir » :
Les documents correspondants sont : 1, 3, 4 et 6.

Les documents 1 et 4, qui ne contiennent qu’un seul token chacun, auront un score de 11 : 1 point pour la fréquence du token, et 10 points car ils matchent un token présent dans la requête.
Le document 3 aura un score de 22 : 2 points pour la présence de « chat » et « noir », et 20 points pour avoir matché 2 tokens de la requête.
Le document 6 aura 15 points : 5 points pour la fréquence du token « noir » (limitée à 5), et 10 points pour avoir matché 1 token.

Résultat final :

Doc 3 → 22 points
Doc 6 → 15 points
Doc 1 et Doc 4 → 11 points

On a réglé nos deux premiers problèmes… mais on peut faire mieux !

Ici, le vrai problème, c’est la limite à 5.
Ce n’est pas tant la valeur "5" qui pose problème, mais le fait qu’on a une augmentation linéaire du score qui s’arrête brutalement à une limite arbitraire.

Les rendements décroissants

Pour régler ce problème, on ne va pas instaurer une limite fixe au-delà de laquelle la fréquence d’un terme ne rapporte plus de points, mais plutôt un rendement décroissant. Par exemple, la première occurrence vaut 1, la deuxième 0.95, la troisième 0.92, etc.
Voici la formule que l’on va utiliser :

Par exemple, utilisons une valeur de decay à 0.97, pour la requête « noir ».

Pour un document qui aurai une fréquence du token « noir » de 6, obtient le résultat suivant :

La différence n’est ici pas flagrante (on aurai eu 6 avant, on a 5.4 maintenant). Mais calculons le score de fréquence avec un token qui apparaîtrait encore plus :

Pour 20 :

Pour 50 :

Pour 100 :

On a donc bien un moyen de différencier deux documents qui n’auraient pas le même nombre d’occurrences d’un token, sans pour autant favoriser exagérément un document qui contient ce token un très grand nombre de fois.

L’impact du terme sur le score diminue progressivement.
On obtient donc une évolution non linéaire, et on évite d’arrêter arbitrairement le moment où la fréquence d’un token cesse d’avoir un effet.

public double GetScore(List<string> queryTokens, string content, double decay = 0.97)
{
    double totalScore = 0;
    int matchToken = 0;

    foreach (var token in queryTokens)
    {
        int frequency = doc.ContentTokens.Count(t => t == token.ToLowerInvariant());

        if (frequency > 0)
            matchToken++;

        double freqScore = (1 - Math.Pow(decay, frequency)) / (1 - decay);

        totalScore += freqScore;
    }

    if (matchToken == queryTokens.Count)
        matchToken *= 2;

    totalScore += matchToken * 10;

    return totalScore;
}

Mais est-ce qu’on peut faire mieux ? Ou plutôt : quels autres problèmes pouvons-nous encore avoir ?

Faisons la requête suivante : « le », « animal »
Si on se base uniquement sur le score de fréquence (et on peut le faire, car aucun document ne matche les deux tokens, donc le boost donné par le nombre de tokens matchés n’aura ici aucun effet), les documents contenant le token « le » auront tous le même score :

doc2 – 1
doc3 – 1
doc5 – 1
doc6 - 1

Pour le token « animal », qui n’est présent qu’une seule fois dans le document 1, il obtiendra également un score de 1.

On se retrouve donc encore une fois avec un manque de discrimination entre les documents. On pourrait penser que, comme chaque terme n’apparaît qu’une fois dans chaque document, on ne peut pas mieux faire... Mais c’est faux !
Il existe une différence : leur fréquence dans l’ensemble des documents, pas juste dans un document.

Le mot « le » apparaît dans presque tous les documents, alors que « animal» n’apparaît que dans un seul.

Il y a donc une différence de rareté — et cette rareté, on peut l’exploiter.

TF-IDF

Jusqu’à présent, nous avons uniquement calculé ce qu’on appelle le TF (Term Frequency), c’est-à-dire la fréquence d’un token dans un document. Il est maintenant temps d’inclure dans notre score le Inverse Document Frequency (IDF), pour mesurer la rareté d’un mot dans l’ensemble des documents.

L’idée est de se dire que plus un mot est rare, plus il est informatif. Ce qui est exactement le cas ici : le token « le», présent partout, n’aide pas à affiner le résultat.

Pour calculer notre IDF, nous allons utiliser la formule suivante :

Où t est le token, N le nombre total de documents dans notre corpus, et nt le nombre de documents qui contiennent ce token.

Calculons l’IDF de « le » :

Puis de « animal » :

Et utilisons cette IDF dans notre calcul de score, qui s’appelle désormais TF-IDF (la multiplication de TF par IDF) :
Vu que notre TF est toujours égal à 1 ici, le calcul est simplifié : on garde uniquement la valeur de l’IDF.
Les scores des documents pour notre requête sont donc maintenant :
doc1 – 0.778
doc2 – 0.079
doc3 – 0.079
doc4 – 0.079
doc5 – 0.079
doc6 – 0.079

Et si on avait un autre document ne contenant que les 2 tokens il se placerait en 1er position avec le score de 0.857

Remarquez qu’on n’a même plus besoin de booster artificiellement le score en fonction du nombre de tokens matchés dans la requête — un boost qui était arbitraire. Et c’est beaucoup mieux !

On a la formule, passons maintenant au code :

public double GetScore(List<string> queryTokens, Document doc, double decay = 0.97)
{
    double totalScore = 0;

    foreach (var token in queryTokens)
    {
        int frequency = doc.ContentTokens.Count(t => t == token.ToLowerInvariant());
        if (frequency == 0)
            continue;

        int df = ReversedIndex[token].Count;
        double idf = Math.Log((double)Documents.Count / (1 + df));

        double tf = (1 - Math.Pow(decay, frequency)) / (1 - decay);
        double tfidf = tf * idf;

        totalScore += tfidf;
    }

    return totalScore;
}

Le calcul de fréquence ne change pas : on récupère simplement la fréquence des documents contenant le token (df), grâce à notre index inversé, qui contient déjà cette information.

Le nombre total de documents est lui aussi déjà connu au moment de l’indexation.

On a donc notre IDF, notre TF, et donc le score final du document !

Mais… est-ce qu’on peut faire encore mieux ?
Voyons les limites actuelles (même si on est déjà pas mal).
Un des problèmes vient du TF : comme on l’a vu, il peut augmenter très vite et biaiser le score.

Dans un premier temps, on avait mis en place une limite de saturation pour éviter ça. Limite qui, normalement, n’est pas prévue dans le TF-IDF classique.

Mais malgré ça, cet algorithme favorise en réalité les documents longs (via le TF), alors qu’un document long n’est pas forcément plus pertinent.
De plus, on a peu de paramètres sur lesquels jouer pour fine-tuner un peu nos résultats (à part le decay, qui n’est pas non plus présent dans la version de base).

Il est donc temps de passer à un nouvel algorithme : BM25.

Best Match 25

Best Match 25 est la 25ᵉ version de l'algorithme censé combler un peu les problèmes du TF-IDF.

Voici d’abord sa formule :

Inutile de partir en courant, si vous êtes arrivé jusqu’ici, vous avez toutes les cartes en main pour la comprendre, et on va voir ça ensemble.

L’IDF, on le connaît déjà, aucun problème donc. On va plutôt regarder ce qui vient remplacer le TF.

Commençons par le numérateur :

f(t,d) est la fréquence du terme t dans le document d.
k1 +1 est un moyen de contrôler la saturation, exactement comme notre decay plus haut.

Plus k1 est petit, plus la saturation est rapide, ce qui réduira de façon non linéaire l’impact de chaque nouveau token présent dans le document.

Pour le dénominateur, on retrouve encore notre fréquence et notre variable k1 pour la saturation, ainsi qu’un facteur de normalisation lié à la longueur du document.

|d| est la longueur actuelle du document (le nombre de tokens qu’il contient).
avgdl est la longueur moyenne de nos documents indexés
b est un paramètre qui sert à ajuster l’importance de la normalisation.

Quand nous avons un document qui est donc plus long que la moyenne, le score aura donc tendance à diminuer. Au contraire, un document court verra son score progresser plus rapidement.

Voyons ça avec un exemple. Reprenons notre liste de documents, et excluons le document 6 qui était très long. Et cherchons le token « noir ».

Commençons par définir nos paramètres k1 et b.

k1 sera 1.5
b sera 0.75

(ce sont des valeurs assez communes pour ces paramètres).

Calculons aussi la longueur moyenne de nos documents qui est : 8 + 4 + 4 + 9 + 5, soit 30. Divisé par le nombre de documents (5), ça nous donne une longueur moyenne de 6.

avgdl est donc égal à 6.

Le token « noir » est présent dans doc1 et doc3, avec un IDF de 0.916.
Commençons par calculer le score du document 1. Sa longueur |d| est de 8.

Commençons par remplacer les valeurs du numérateur : la fréquence du terme dans le document est de 1, la valeur de k1 est de 1.5. On connaît aussi déjà l’IDF. On a donc :

Ou :

Au dénominateur, on peut aussi facilement remplacer les valeurs déjà connues (tf et k1) :

On connaît la longueur moyenne des documents et la longueur du document actuel, on peut donc remplacer |d| et avgdl :

Ou :

b est connu, il est de 0.75 :

On a donc :

Un score final donc de 0.796 pour le document 1. Qu’en est-il du document 3 ?

Le document 3 est très similaire : la fréquence du terme est toujours de 1 et l’IDF est le même. La seule partie qui change est bien sûr la longueur du document, qui au lieu d’être de 8 sur 6, est de 4 sur 6.

Un score final de 1.077 pour notre document 3. Un meilleur score que notre document 1 !

Beaucoup de calculs ont été nécessaires pour démontrer comment marche BM25, mais les opérations étant assez simples, elles sont en fait très faciles à traduire en code :

public double GetScore(List<string> queryTokens,  Document doc)
{
    double tfWeight = 1.5;
    double docLengthPenalty = 0.75;
    double score = 0;
    double avgDocLength = Documents.Average(doc => doc.Key.Length);

    foreach (var token in queryTokens)
    {
        int tf = doc.ContentTokens.Count(t => t == token.ToLowerInvariant());

        if (tf == 0 || !ReversedIndex.ContainsKey(token))
            continue;

        int df = ReversedIndex[token].Count;
        double idf = Math.Log((double)Documents.Count / (1 + df));

        double norm;

        norm = (tf * (tfWeight + 1)) /
                (tf + tfWeight * (1 - docLengthPenalty + docLengthPenalty * (doc.Content.Length / avgDocLength)));

        score += idf * norm;
    }

    return score;
}

Bravo, vous savez maintenant comment calculer un score de pertinence sur un contenu et renvoyer en premier le meilleur document à votre utilisateur.
Bien sûr, d’autres paramètres peuvent être pris en compte, comme les tokens trouvés dans le titre, la date de modification du document ou même sa localisation.

Ici, nous nous sommes concentrés sur le contenu d'un document, mais cet algorithme peut être adapté et complété avec la d’autres champs comme le titre, la date, etc.

SDK Playground: Who Are You Blocking on BlueSky?

Mary 🇪🇺 🇷🇴 🇫🇷 — Wed, 07 May 2025 08:16:46 +0000

Most services — including social networks — offer APIs that allow third-party programs or tech-savvy users to perform actions that would normally be manual and tedious, all through code.

Let’s imagine I’m blocking people on BlueSky, and I want to know if another account has blocked the same people as I have. I would need to:

Retrieve my own block list
Retrieve the block list of the other account
And for each name, check if it's present in both lists.

It’s not impossible to do — at least on BlueSky, since everything is public. But it’s a massive pain.

Another example: imagine I want to block everyone who liked a post (say, because it’s a post praising Kubernetes and I don’t like Kubernetes).

Here’s what I’d have to do:

Find the post
Retrieve the list of people who liked it
Block them one by one

Let’s not lie to ourselves — that’s boring as hell to do!

Especially since not all services are created equal when it comes to APIs. Between Twitter’s ridiculous pricing (yes, I still call it Twitter — what are you gonna do, Elon?), LinkedIn’s extreme restrictions, or Yammer’s complete lack of documentation, we could write an entire article just about different API designs.

There are still a few good students when it comes to APIs, and BlueSky is one of them. Mainly because their web app is built on top of their own API — which definitely helps keep things clean.

But no matter how clean BlueSky’s API is, it’s still an API — a REST API, which means a web protocol. REST APIs are great: they can be used with pretty much any language (even Bash, which tells you a lot!)

Still, between handling async calls and HTTP response codes that are longer than your holiday shopping list, it can be... annoying to manage cleanly.

That’s where SDKs come in. SDKs are libraries for your language that make it easier to work with a service.

For BlueSky, you’ve got TypeScript and Python SDKs, for example (and honestly, I get the point of a Python SDK — but TypeScript? Web devs are already weird enough, they’re used to hitting REST APIs manually anyway).

But if you're coding in something else, like Java or C#, you’ll have no choice but to manage those REST calls yourself.

Fortunately, my fellow C# developers, no worries — we’re going to look at how to solve these problems in C#!

Hello World

First things first: we need a SDK!
Good news — there’s one available on NuGet called ATbluePandaSDK, which lets you easily interact with BlueSky in C#.

To install it, just use your NuGet package manager or run this command:

dotnet add package ATbluePandaSDK --version 0.1.2

Before diving into a complex use case, let’s start with something simple and classic: a little Hello World.

Open up your project called ConsoleApp1 — because we’re not here to waste time naming things.

Here’s a small snippet to get started:

using ATPandaSDK;
using ATPandaSDK.Models.Auth;

Console.WriteLine("Hello, World!");

ATPClient client = new ATPClient();
AuthRequest authRequest = new AuthRequest("handle.bsky.social", "password");
BskyAuthUser authUser = client.Authenticate(authRequest);

client.CreatePost("Hello world from ATbluePandaSDK version 0.1.2");

If you run this code, you’ll see “Hello, World!” in your console.
But the real magic happens on your BlueSky account — you should now see something like this:

The code is short, but let’s break it down:

We start by creating a ATPClient object. This is the core class of the SDK — everything you want to do on BlueSky goes through this client.

But to actually do things, we need to log in. For that, we create an AuthRequest object with your handle and password.

“But to do things, we need to log in” — Well, not entirely true. Some endpoints don’t require authentication, but posting — and most things we’ll want to do — definitely does.

We then call the Authenticate method on the ATPClient, passing in our AuthRequest. This returns a BskyAuthUser object — that’s you, your identity on BlueSky. It contains key info like your DID, handle, and most importantly, your token — which you'll use to make further API calls without having to re-enter your password.

Never share this token with anyone!

Finally, we use CreatePost to publish our message. It just takes the text you want to post.

Notice we didn’t explicitly pass in the BskyAuthUser. We could have, but the ATPClient keeps it in memory after authentication — so you can skip that in future calls.

Congrats! You just posted your first Hello World using the BlueSky C# SDK.
Feeling emotional? Hold on — this is just the beginning!

A Real Use Case

Alright, you’ve tested the first features of the SDK to make sure everything is working fine. Posting on BlueSky via your IDE is very cool, but it’s probably less user-friendly than doing it through the web app. So let’s go a bit further with our very first example: finding out which accounts are blocked by both you and another user.

What’s the point of this? I don’t know—maybe a future Tinder-like app will match people based on the percentage of users they’ve both blocked!

Let’s start by retrieving your own list of blocked users and printing their names:

using ATbluePandaSDK.Models.Account;
using ATPandaSDK;
using ATPandaSDK.Models.Auth;

ATPClient client = new ATPClient();
AuthRequest authRequest = new AuthRequest("handle.bsky.social", "password");
BskyAuthUser authUser = client.Authenticate(authRequest);
List<Block> listOfUsersBlocked = client.GetBlocks();
foreach (Block b in listOfUsersBlocked)
{
    Console.WriteLine(b.displayName);
}

This code gives me the following output:

Of course, you’ll see your own blocked users, but don’t be shy about sharing your list—it’s public anyway!

Note: these are the people you personally blocked—those blocked through moderation lists won’t appear here!

Let’s walk through the code from the login step!

With our client, we call the GetBlocks function, which returns a list of blocked users (tough luck for them!) — this function runs for the currently authenticated user, so just you, and only you!

We loop through the list, and among the attributes of the Block object, we have the displayName (there’s more info, but it’s not useful for now).

Is Block a User?
Yes, there's also a User object that contains more information, but Block has most of the user-related data, so you can easily convert a Block to a User if needed!

Next step: get the list of people blocked by someone else!

For this, we’ll need two more client functions:

using ATbluePandaSDK.Models.Account;
using ATPandaSDK;
using ATPandaSDK.Models.Auth;

ATPClient client = new ATPClient();
AuthRequest authRequest = new AuthRequest("handle.bsky.social", "password");
BskyAuthUser authUser = client.Authenticate(authRequest);

List<Block> listOfUsersBlocked = client.GetBlocks();

User actor = client.GetUserProfil("otherhandle.bsky.social");
List<Records> otherListOfUsersBlocked = client.GetAccountsBlocked(actor, cursor: true);

This time, we need an actor (which is a User object).
There are many ways to get one—here we used the GetUserProfil function, which retrieves full user info. You can pass either a DID or a handle as a parameter.

So now we have two lists: one of Block (the users you blocked) and one of Record (a bit of a catch-all term in BlueSky — but in our case, also blocked users!).

We won’t go into detail here about what a Record is—this post is already too long!

We now have two lists that we can easily cross-reference—thankfully, we’re using C# and not Bash!

using ATbluePandaSDK.Models;
using ATbluePandaSDK.Models.Account;
using ATPandaSDK;
using ATPandaSDK.Models.Auth;

ATPClient client = new ATPClient();
AuthRequest authRequest = new AuthRequest("handle.bsky.social", "password");
BskyAuthUser authUser = client.Authenticate(authRequest);

List<Block> listOfUsersBlocked = client.GetBlocks();

User actor = client.GetUserProfil("otherhandle.bsky.social");
List<Records> otherListOfUsersBlocked = client.GetAccountsBlocked(actor, cursor: true);

foreach (Block b in listOfUsersBlocked)
{
    foreach (Records r in otherListOfUsersBlocked)
    {
        if (b.did.Equals(r.Value.Subject))
        {
            try
            {
                User userBlocked = client.GetUserProfil(b.did);
                Console.WriteLine(userBlocked.DisplayName);
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
            }
        }
    }
}

Here’s my output:

As you can see, the list is shorter than before (which makes sense—we just did a kind of inner join!). Again, your output will likely be different.

Be careful: the GetAccountsBlocked call can take a while if the user has a long block list.
You’ll notice that this function accepts a cursor argument set to true — this means multiple requests may be required to handle pagination, which can take time depending on how many pages there are.

Conclusion

Did you enjoy this blog post? Let me know by liking my hello world post! Now that you’ve got the SDK, it’s super easy:

using ATPandaSDK;
using ATPandaSDK.Models.Auth;
using ATPandaSDK.Models.Feed;

ATPClient client = new ATPClient();
AuthRequest authRequest = new AuthRequest("handle.bsky.social", "password");
BskyAuthUser authUser = client.Authenticate(authRequest);
BskyTimeline timeline = client.GetAuthorTimeline();
BskyThread helloWorld = client.GetPostThread("at://did:plc:6rujkdwb4mzzplqzccqmui2h/app.bsky.feed.post/3lojdtvoqb52g");
client.LikePost(helloWorld.thread.post);

And if you want to go further, many other features are already available in the SDK:

Like/unlike, follow/unfollow, block/unblock, mute/unmute, and full access to all your timelines.

SDK BlueSky : Utiliser C# pour comprendre les blocages entre utilisateurs

Mary 🇪🇺 🇷🇴 🇫🇷 — Wed, 07 May 2025 07:52:07 +0000

La plus part des services, réseaux sociaux compris, on des API disponibles pour permettre à des programmes tiers ou des utilisateurs avertis d’effectuer des actions, normalement manuelles et fastidieuses, grâce à du code.

Imaginons, que je bloque des gens sur BlueSky, et j’aimerais savoir si un autre compte a bloqué les mêmes comptes que moi. Je dois :

Prendre ma liste de personnes bloquées
Prendre la liste des personnes bloquées par l’autre compte
Et pour chaque nom vérifier s’il est présent dans les deux listes.

C’est pas impossible à faire, sur BlueSky en tous cas car tout est public. Mais c’est extrêmement chiant.

Autre exemple. Imaginez que je veuille bloquer toutes les personnes qui ont liké un post (Parce que par exemple c’est un post qui vante les mérites de Kubernetes et que je n'aime pas Kubernetes)

Je dois pour ça :

Prendre le post
Voir la liste des personnes qui ont liké le post
Bloquer une à une les personnes

Hey, on va pas se mentir, c’est chiant comme la pluie à faire !

Surtout que tous les services ne se valent pas en termes d’API. Pricing excessif à la Twitter (Oui je dis toujours Twitter, tu vas faire quoi Elon ?), extrêmement restrictif à la LinkedIn ou juste parfois non documenté à la Yammer, on pourrait faire un article entier dédié aux différents designs des API.

Il existe quand même des bons élèves, à propos des APIs, on peut parler de BlueSky. Bon élève principalement car leur application web est basée sur leur propre API. Ce qui aide pas mal à avoir une API propre.

Mais aussi propre soit l’API BlueSky, ça reste une API, une API REST. Donc un protocole Web. C’est très bien les API REST, ça peut être utilisé par n’importe quel langage (Bash y arrive c’est pour vous dire !)

Sauf qu'entre les appels asynchrones à gérer et les codes de réponses HTTP qui sont plus longs qu’une liste de courses de fin d’année, ça peut être… embêtant à gérer… proprement.

Pour masquer l’utilisation des API il est donc possible d’utiliser des SDK. Les SDK sont des bibliothèques pour votre langage qui facilitent l’utilisation d’un service.

Pour BlueSky vous avez par exemple des SDK TypeScript ou Python (Alors autant je vois l’utilité d’un SDK Python, autant TypeScript, c’est déjà des gens chelous qui font du web, je pense qu’ils ont l’habitude de faire des appels sur des API REST)

Si par contre vous codez avec autre chose comme du Java ou du C#, vous n’aurez pas le choix que de gérer vos appels REST vous-même.

Heureusement, mes sharpistes, pour vous pas de galère, on va voir ici comment résoudre nos problèmes en C# !

Hello World

Première chose : il nous faut donc un SDK !
Ça tombe bien, sur Nuggets on peut trouver un SDK nommé ATbluePandaSDK, ce SDK permet d’interagir simplement avec BlueSky en C#.

Pour l’installer, rien de plus simple : allez dans votre gestionnaire de packages Nugget ou exécutez la commande :

dotnet add package ATbluePandaSDK --version 0.1.2

Avant de faire notre use cases super complexe, on va tester quelque chose de simple et basique : un petit Hello World.

On ouvre notre projet ConsoleApp1 car on n’est pas là pour donner des noms à nos projets, on n’a pas le temps.

Commençons avec ce code assez simple :

using ATPandaSDK;
using ATPandaSDK.Models.Auth;

Console.WriteLine("Hello, World!");

ATPClient client = new ATPClient();
AuthRequest authRequest = new AuthRequest("handle.bsky.social", "password");
BskyAuthUser authUser = client.Authenticate(authRequest);

client.CreatePost("Hello world from ATbluePandaSDK version 0.1.2");

Si vous exécutez ce code, vous devriez avoir juste une sortie console disant "Hello world".
Mais là où vous devriez regarder, c’est maintenant sur votre compte BlueSky : vous devriez voir quelque chose comme ceci :

Le code est court, mais on va quand même l’expliquer :

On commence par créer un objet client de type ATPClient. Ce client, c’est vraiment la classe la plus importante du SDK : tout ce que vous voulez faire sur BlueSky est fait grâce à ce client.

Mais pour faire des trucs, on doit commencer par se connecter. Pour cela, on va créer un objet AuthRequest qui reçoit en paramètre votre handle et votre mot de passe.

"Mais pour faire des trucs, on doit commencer par se connecter" En fait c'est faux, tous les endpoints ne demandent pas une authentification, mais le post en l’occurrence — et d’autres que l’on va utiliser — le nécessitent.

Puis on s’authentifie via la méthode Authenticate du client ATP qui prend en paramètre notre AuthRequest précédemment créé, et qui va nous renvoyer un objet BskyAuthUser.
Cet objet, c’est vous, votre identité. Il contient vos informations principales comme votre DID, votre handle, mais aussi — et surtout — votre token, qui va permettre d’utiliser d’autres endpoints de l’API BlueSky sans redonner votre mot de passe.

Ne le donnez à personne !

Finalement, on crée notre post via la fonction CreatePost, qui prend en paramètre le texte que l’on souhaite poster.

Notez qu’on n’a pas utilisé le BskyAuthUser. On aurait pu, mais le client ATP le garde en mémoire, et vous pouvez donc l’omettre pour vos prochaines actions.

Bravo ! Vous avez fait votre Hello World avec le SDK C# de BlueSky.
Ému ? Attendez, c’est pas fini !

Un vrai use case

Ok, vous avez pu tester les premières fonctionnalités du SDK pour vous assurer que tout marche correctement. Sauf que poster sur BlueSky via votre IDE, c’est très cool, mais c’est, je pense, moins user friendly que via l’application web. Alors allons ensemble un peu plus loin avec notre tout premier exemple : connaître les comptes bloqués par moi-même et un autre utilisateur.

À quoi cela peut bien servir ? Je ne sais pas, peut-être un futur Tinder qui vous proposera des matchs via une compatibilité basée sur votre pourcentage en commun de gens bloqués !

Commençons par récupérer notre propre liste des gens qu’on a bloqués et afficher leur nom :

using ATbluePandaSDK.Models.Account;
using ATPandaSDK;
using ATPandaSDK.Models.Auth;

ATPClient client = new ATPClient();
AuthRequest authRequest = new AuthRequest("handle.bsky.social", "password");
BskyAuthUser authUser = client.Authenticate(authRequest);
List<Block> listOfUsersBlocked = client.GetBlocks();
foreach (Block b in listOfUsersBlocked)
{
    Console.WriteLine(b.displayName);
}

Ce code donnera pour moi cette sortie :

Pour vous bien sûr, il s’agira de vos propres gens bloqués, mais n’ayez pas honte de partager votre liste, de toute façon c’est public !

Notez que ce sont les gens que vous avez bloqués personnellement, les gens bloqués via des listes de modération ne sont pas affichés ici !

Reprenons ensemble le code à partir de la connexion !

Avec notre client, nous appelons la fonction GetBlocks qui retourne une liste de personnes bloquées (Pas de chance pour eux !) — cette fonction s’exécute pour l’utilisateur connecté, donc nous-même, et uniquement nous-même !

On parcourt cette liste, et dans les différents attributs de notre objet Block, nous avons par exemple le displayName (on a d’autres infos, mais pas utiles pour le moment).

Est-ce que Block est un User ?
Oui, il existe un objet User qui a beaucoup plus d’informations, mais Block a la majorité des informations d’un utilisateur, vous pouvez donc passer facilement d’un objet Block à un objet User si vous le souhaitez !

Prochaine étape : obtenir la liste des personnes bloquées par quelqu’un d’autre !

Pour ça, on va devoir utiliser deux autres fonctions du client :

using ATbluePandaSDK.Models.Account;
using ATPandaSDK;
using ATPandaSDK.Models.Auth;

ATPClient client = new ATPClient();
AuthRequest authRequest = new AuthRequest("handle.bsky.social", "password");
BskyAuthUser authUser = client.Authenticate(authRequest);

List<Block> listOfUsersBlocked = client.GetBlocks();

User actor = client.GetUserProfil("otherhandle.bsky.social");
List<Records> otherListOfUsersBlocked = client.GetAccountsBlocked(actor, cursor: true);

Il va nous falloir cette fois un acteur (qui est un objet User).
On peut l’obtenir de plein de manières. Ici, on a utilisé la fonction GetUserProfil qui permet d’obtenir toutes les informations d’un utilisateur. Vous pouvez passer en paramètre de cette fonction un DID ou un handle.

On a donc maintenant deux listes : une de Block (les utilisateurs que l’on a bloqués), et une de Record (qui est un terme un peu valise chez BlueSky — mais dans notre cas, ce sont aussi des gens bloqués !).

On ne rentrera pas dans le détail ici de ce qu’est un Record, ce blog post est déjà beaucoup trop long !

Nous avons donc deux listes, que nous pouvons maintenant croiser facilement car nous sommes en C# et pas en Bash !

using ATbluePandaSDK.Models;
using ATbluePandaSDK.Models.Account;
using ATPandaSDK;
using ATPandaSDK.Models.Auth;

ATPClient client = new ATPClient();
AuthRequest authRequest = new AuthRequest("handle.bsky.social", "password");
BskyAuthUser authUser = client.Authenticate(authRequest);

List<Block> listOfUsersBlocked = client.GetBlocks();

User actor = client.GetUserProfil("otherhandle.bsky.social");
List<Records> otherListOfUsersBlocked = client.GetAccountsBlocked(actor, cursor: true);

foreach (Block b in listOfUsersBlocked)
{
    foreach (Records r in otherListOfUsersBlocked)
    {
        if (b.did.Equals(r.Value.Subject))
        {
            try
            {
                User userBlocked = client.GetUserProfil(b.did);
                Console.WriteLine(userBlocked.DisplayName);
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
            }
        }
    }
}

Voici ma sortie :

On voit que la liste est plus courte qu’avant (c’est normal, c’est une sorte de inner join que nous avons fait !). Encore une fois, la sortie sera pour vous sans doute différente.

Attention, l’instruction GetAccountsBlocked peut être longue si la personne a une longue liste de blocages.
Vous voyez en effet que cette fonction a l’argument cursor à true — cela veut dire qu’on doit faire plusieurs requêtes pour gérer la pagination, et cela peut prendre du temps selon le nombre de pages.

Conclusion

Vous avez aimé ce blog post ? N’hésitez pas à le faire savoir en likant mon post hello world. Maintenant que vous avez un SDK, rien de plus simple :

using ATPandaSDK;
using ATPandaSDK.Models.Auth;
using ATPandaSDK.Models.Feed;

ATPClient client = new ATPClient();
AuthRequest authRequest = new AuthRequest("handle.bsky.social", "password");
BskyAuthUser authUser = client.Authenticate(authRequest);
BskyTimeline timeline = client.GetAuthorTimeline();
BskyThread helloWorld = client.GetPostThread("at://did:plc:6rujkdwb4mzzplqzccqmui2h/app.bsky.feed.post/3lojdtvoqb52g");
client.LikePost(helloWorld.thread.post);

Et si vous souhaitez aller plus loin, il y a plein d'autres fonctions déjà disponibles dans le SDK :

Le like/unlike, mais aussi le follow/unfollow, block/unblock, mute/unmute et l’accès à toutes vos timelines.

AsyncLocal share information between class

Mary 🇪🇺 🇷🇴 🇫🇷 — Mon, 09 Dec 2024 13:21:48 +0000

When you write logs in an application, you likely have a dedicated class (or even a singleton instance) that handles the writing of these logs and that you use throughout your code. This mechanism is usually simple and straightforward. But if you take a look at how the logger is used in PandApache, you might be a bit surprised by this line:

ExecutionContext.Current.Logger.LogInfo($"Admin server listening on {ServerConfiguration.Instance.ServerIP}:{ServerConfiguration.Instance.AdminPort}");

Output:

12/09/2024 12:26:48  - Module: Admin      - Thread ID: 1  - INFO       - Admin server listening on 0.0.0.0:4040

Before explaining this line, let’s take a step back to understand how we got here.

How does PandApache work?

When PandApache is running, you have several elements in play:

The Service: the main program itself.
Modules: each module creates a new task, as they run concurrently.
Subtasks: some modules may start their own subtasks depending on the action they are performing.

The goal is to make each module as independent and configurable as possible. Therefore, each module should have:

Its own logger: this allows you to know which log was written by which module, while applying specific logging rules (different levels, different files, etc.).
Its own task scheduler: so as not to monopolize all the resources and to leave enough for others.

How to manage the correct logger in each module?

There are several ways to ensure that each module uses the correct logger (and the correct task scheduler, but we’ll set that aside for now). One solution would be to pass the appropriate logger as a parameter to each method, or to use dependency injection. This could look like:

Logger loggerAdmin = new Logger(configAdmin);
Logger loggerWeb = new Logger(configWeb);

Module moduleAdmin = new Module(loggerAdmin);
Module moduleWeb = new Module(loggerWeb);

This approach is not ideal. Why? Because each sub-function would need to access the correct logger, either by passing it explicitly as a parameter or through dependency injection, which can quickly become cumbersome and redundant.

Let’s take an example in a module:

Module{
    public Logger LoggerAdmin;

    Foo() {
        LoggerAdmin.LogInfo("Here");
        RandomObject.Bar(LoggerAdmin);
    }
}

RandomObject{ 

    Bar(Logger logger) {
        logger.LogInfo("There");
    }
}

You could also opt for a solution with static objects that return the correct logger, which would give:

Foo() {
    LoggerAdmin.LogInfo("Here");
}

Bar() {
    LoggerAdmin.LogInfo("There");
}

But this solution has two major problems:

Manually choosing the correct logger: For every function or class, you have to decide which logger to use. And if a function changes context (for example, from the Web module to the Admin module), you constantly need to adapt this choice. This lacks flexibility and increases the risk of bugs.
Handling multiple instances: The Web and Admin modules are actually two instances of the same module, but running the same code. How do you ensure each instance has its own logger without specifying it in every call?

The real challenge is to find a way to automatically retrieve the correct logger (or any other module-specific object) without having to specify it each time and without using specific parameters. This object must be determined based on the module that is currently running, and not manually at each function call.

With that in mind, how could you solve this problem more elegantly? Leave a comment to share your approach and explain how you would handle dependency injection in this context, particularly for module-specific objects like the logger.

Virtual Logger

To fully understand the final solution, it's important to have the desired logs in mind. Here are the PandApache logs:

12/09/2024 12:33:25  - Module: Server     - Thread ID: 1  - WARNING    - Module Telemetry disabled
12/09/2024 12:33:25  - Module: Server     - Thread ID: 1  - INFO       - PandApache3 is starting
12/09/2024 12:33:25  - Module: Web        - Thread ID: 1  - INFO       - Starting Connection manager module
12/09/2024 12:33:25  - Module: Web        - Thread ID: 1  - INFO       - Web server listening on 0.0.0.0:8080
12/09/2024 12:33:25  - Module: Admin      - Thread ID: 1  - INFO       - Starting Connection manager module
12/09/2024 12:33:25  - Module: Admin      - Thread ID: 1  - INFO       - Admin server listening on 0.0.0.0:4040
12/09/2024 12:33:25  - Module: default    - Thread ID: 1  - INFO       - PandApache3 process id:3738
12/09/2024 12:33:25  - Module: default    - Thread ID: 1  - INFO       - PandApache3 process name:dotnet
12/09/2024 12:33:25  - Module: Server     - Thread ID: 1  - INFO       - PandApache3 is up and running!
12/09/2024 12:33:25  - Module: Web        - Thread ID: 6  - INFO       - Running Connection manager module
12/09/2024 12:33:28  - Module: Web        - Thread ID: 6  - INFO       - Client connected
12/09/2024 12:33:28  - Module: Web        - Thread ID: 12 - INFO       - Reading query string parameter
12/09/2024 12:33:28  - Module: Web        - Thread ID: 13 - INFO       - LoggerMiddleware invoked
12/09/2024 12:33:28  - Module: Web        - Thread ID: 13 - INFO       - Log Request
12/09/2024 12:33:28  - Module: Web        - Thread ID: 13 - INFO       - [12/09/2024 10:33:28] GET /
12/09/2024 12:33:28  - Module: Web        - Thread ID: 14 - INFO       - Log Response
12/09/2024 12:33:28  - Module: Web        - Thread ID: 14 - INFO       - [12/09/2024 10:33:28] Response status code: 200
12/09/2024 12:33:28  - Module: Web        - Thread ID: 14 - INFO       - client Closed
12/09/2024 12:33:28  - Module: Web        - Thread ID: 6  - INFO       - Client connected
12/09/2024 12:33:28  - Module: Web        - Thread ID: 13 - INFO       - Reading query string parameter

These logs show typical information, but two elements that change regularly and are very important are the module and thread ID.

To understand how we got to these logs, it's logical to first look at the components of a PandApache module, particularly its properties. Here are the properties of the ConnectionManager module, which is the class instantiated for both the Web and Admin modules:

public TcpListener Listener { get; set; }
public TaskFactory TaskFactory { get; }
public ModuleConfiguration ModuleInfo { get; set; }
public ModuleType ModuleType { get; set; }
private static AsyncLocal<ModuleConfiguration> _current = new AsyncLocal<ModuleConfiguration>();
public CancellationTokenSource _cancellationTokenSource { get; } = new CancellationTokenSource();
private ConcurrentDictionary<Guid, ISocketWrapper> _clients { get; } = new ConcurrentDictionary<Guid, ISocketWrapper>();
private ConcurrentDictionary<Guid, ISocketWrapper> _clientsRejected = new ConcurrentDictionary<Guid, ISocketWrapper>();
private Func<HttpContext, Task> _pipeline;
private TaskScheduler _taskScheduler;

The properties that will interest us are:

public ModuleConfiguration ModuleInfo { get; set; }
private TaskScheduler _taskScheduler;

The TaskScheduler is quite simple, although we have re-implemented our own TaskScheduler for a few modifications. It's an inheritance of the default class, so it functions in a similar way.

The ModuleConfiguration, however, is an original class that looks like this:

public class ModuleConfiguration
{
    private TaskScheduler _taskScheduler;
    public ModuleType Type;
    public string Name;
    public bool isEnable;
    public TaskFactory TaskFactory { get; }
    public VirtualLogger Logger;

    public ModuleConfiguration(string name)
    {
        Name = name;
        Type = moduleType;
        Logger = new VirtualLogger(name);
    }
}

We can see the TaskScheduler again, but we also have a VirtualLogger that takes a name as a parameter.

A VirtualLogger behaves exactly like the normal PandApache logger. In fact, both the VirtualLogger and Logger classes implement the ILogger interface.

The difference is that the VirtualLogger sends its log to the Logger, and the Logger sends the log to the system (either the console or a file).

So, we have modules running in their own tasks, each containing the two instances of objects that we want to use in very specific execution contexts. We now have all the components in place for what we want to achieve. Let's see how this works.

Between us

One might say that a VirtualLogger is an unnecessary abstraction here. We could easily use the original Logger class with different instances, just like we do with the VirtualLogger. This is true, but there are other benefits to using the VirtualLogger that haven't been explained here. What you need to take away is that the VirtualLogger is not just there to have independent loggers, but primarily to separate the action of logging information and the action of distributing it, whether to the console or to a file. We’ll explore this in a future blog post.

Execution Context

Let’s revisit the line to execute the logger from earlier.

ExecutionContext.Current.Logger.LogInfo($"Admin server listening on {ServerConfiguration.Instance.ServerIP}:{ServerConfiguration.Instance.AdminPort}");

It’s time to talk about the ExecutionContext object. It’s a simple class that contains just a static field for easy access everywhere. Here it is:

public static class ExecutionContext
{
    private static AsyncLocal<ModuleConfiguration> _current = new AsyncLocal<ModuleConfiguration>();

    public static ModuleConfiguration Current
    {
        get => _current.Value;
        set => _current.Value = value;
    }
}

The special feature of this class is the type of _current, which is an AsyncLocal<ModuleConfiguration>. This ensures that _current has a distinct value across different execution contexts, meaning, across tasks.

Each module, at startup, assigns its ModuleInfo object to the _current field of its execution context:

ExecutionContext.Current = ModuleInfo;

When, within the module, the line:

ExecutionContext.Current.Logger.LogInfo("Starting Connection manager module");

Output:

12/09/2024 12:26:48  - Module: Web        - Thread ID: 1  - INFO       - Starting Connection manager module

is used, the correct logger for the module is indeed used.

Here are the two log outputs from the same line, generated by two modules (Web and Admin):

Output:

12/09/2024 12:26:48  - Module: Web        - Thread ID: 1  - INFO       - Starting Connection manager module
12/09/2024 12:26:48  - Module: Web        - Thread ID: 1  - INFO       - Web server listening on 0.0.0.0:8080
12/09/2024 12:26:48  - Module: Admin      - Thread ID: 1  - INFO       - Starting Connection manager module
12/09/2024 12:26:48  - Module: Admin      - Thread ID: 1  - INFO       - Admin server listening on 0.0.0.0:4040

When a module launches another task, like the Web module accepting a connection to process a request:

await AcceptConnectionsAsync(client);

We theoretically change context, as we are now in a sub-task of the main task. However, the value of the AsyncLocal property is automatically inherited, which means that in the AcceptConnectionsAsync function, when we use the logger via ExecutionContext:

ExecutionContext.Current.Logger.LogInfo($"Client connected");

Output:

12/09/2024 12:33:45  - Module: Admin      - Thread ID: 9  - INFO       - Client connected

We still have the correct ModuleInfo configured.

Finally

All of this allows us to do a lot within PandApache. For the loggers, even though each VirtualLogger differs very little (only the module name stored directly in the logger varies from one VirtualLogger to another), we still benefit from transparency and logical isolation when using them, as well as consistency and standardization when writing logs.

The TaskScheduler, which we’ve spoken little about because it’s less visual but functions exactly like the logger, once again allows us, in a very transparent way, to launch new tasks within our module. It enforces rules, especially regarding the number of custom threads. This ensures, for example, that the telemetry module, which is not a critical module, doesn’t consume too many resources (one thread for telemetry is sufficient, depending on the number of metrics you wish to capture).

On the other hand, if your web module no longer has enough resources to handle a new request, you’ll be quite frustrated. Ultimately, this shared execution context enables a finer resource management approach.

I hope this article helped you better understand the AsyncLocal in C#. If you’re interested in this language, know that the PandApache3 code is available on GitHub and live on Twitch. Feel free to follow the journey!

AsyncLocal pour le partage d'informations entre classes

Mary 🇪🇺 🇷🇴 🇫🇷 — Mon, 09 Dec 2024 12:59:38 +0000

Quand vous écrivez des logs dans une application, vous avez sûrement une classe dédiée (voire une instance singleton) qui gère l’écriture de ces logs et que vous utilisez partout dans votre code. Ce mécanisme est généralement simple et direct. Mais si vous jetez un œil à la façon dont on utilise le logger dans PandApache, vous pourriez être un peu surpris par cette ligne :

ExecutionContext.Current.Logger.LogInfo($"Admin server listening on {ServerConfiguration.Instance.ServerIP}:{ServerConfiguration.Instance.AdminPort}");

Sortie:

12/09/2024 12:26:48  - Module: Admin      - Thread ID: 1  - INFO       - Admin server listening on 0.0.0.0:4040

Avant d'expliquer cette ligne, prenons un peu de recul pour comprendre comment on en est arrivé là.

Comment PandApache fonctionne?

Lorsque PandApache est en cours d'exécution, vous avez plusieurs éléments en jeu :

Le Service : c'est le programme principal lui-même.
Les modules : chaque module crée une nouvelle tâche, car ils s’exécutent simultanément.
Les sous-tâches : certains modules peuvent démarrer leurs propres sous-tâches en fonction de l'action qu'ils effectuent.

L'objectif est de rendre chaque module le plus indépendant et configurable possible. Ainsi, chaque module doit posséder :

Son propre logger : cela permet de savoir quel log a été écrit par quel module, tout en appliquant des règles de log spécifiques (niveaux différents, fichiers différents, etc.).
Son propre task scheduler : pour ne pas monopoliser toutes les ressources et laisser suffisamment pour les autres

comment gérer le bon logger dans chaque module ?

Il existe plusieurs façons de s'assurer que chaque module utilise le bon logger (et le bon task scheduler, mais on va le laisser de coté pour le moment). Une solution serait de passer le logger approprié en paramètre à chaque méthode, ou d'utiliser l'injection de dépendance. Cela pourrait ressembler à ceci :

Logger loggerAdmin = new Logger(configAdmin);
Logger loggerWeb = new Logger(configWeb);

Module moduleAdmin = new Module(loggerAdmin);
Module moduleWeb = new Module(loggerWeb);

Cette approche n'est pas idéale. Pourquoi ? Parce qu'il faudrait que chaque sous-fonction puisse accéder au logger approprié, soit en le passant explicitement en paramètre, soit par injection de dépendance, ce qui peut rapidement devenir lourd et redondant.

Prenons un exemple dans un module :


Module{
    public Logger LoggerAdmin;

    Foo() {
        LoggerAdmin.LogInfo("Here");
        RandomObject.Bar(LoggerAdmin);
    }

}

RandomObject{ 

    Bar(Logger logger) {
        logger.LogInfo("There");
    }
}

On pourrait aussi opter pour une solution avec des objets statiques qui renverraient le bon logger, ce qui donnerait :

Foo() {
    LoggerAdmin.LogInfo("Here");
}

Bar() {
    LoggerAdmin.LogInfo("There");
}

Mais cette solution présente deux problèmes majeurs :

Choisir manuellement le bon logger : À chaque fonction ou classe, il faut décider quel logger utiliser. Et si une fonction change de contexte (par exemple, du module Web au module Admin), il faut constamment adapter ce choix. Cela manque de flexibilité et augmente les risques de bugs.
La gestion des instances multiples : Les modules Web et Admin sont en réalité deux instances du même module, mais qui exécutent le même code. Comment faire en sorte que chaque instance ait son propre logger sans avoir à le spécifier à chaque appel ?

Le véritable défi est de trouver un moyen de récupérer automatiquement le bon logger (ou tout autre objet spécifique au module) sans avoir à le préciser chaque fois et sans passer par des paramètres spécifiques. Ce bon objet doit être déterminé en fonction du module qui est actuellement en cours d’exécution, et non de manière manuelle à chaque appel de fonction.

Dans cette optique, comment pourriez-vous résoudre ce problème de manière plus élégante ? Laissez un commentaire pour partager votre approche et expliquer comment vous géreriez l’injection de dépendances dans ce contexte, en particulier pour des objets spécifiques à chaque module comme le logger.

Virtual Logger

Pour bien imaginer la solution finale, avoir les logs souhaités en tête est important. Voici les logs de PandApache :

12/09/2024 12:33:25  - Module: Server     - Thread ID: 1  - WARNING    - Module Telemetry disabled
12/09/2024 12:33:25  - Module: Server     - Thread ID: 1  - INFO       - PandApache3 is starting
12/09/2024 12:33:25  - Module: Web        - Thread ID: 1  - INFO       - Starting Connection manager module
12/09/2024 12:33:25  - Module: Web        - Thread ID: 1  - INFO       - Web server listening on 0.0.0.0:8080
12/09/2024 12:33:25  - Module: Admin      - Thread ID: 1  - INFO       - Starting Connection manager module
12/09/2024 12:33:25  - Module: Admin      - Thread ID: 1  - INFO       - Admin server listening on 0.0.0.0:4040
12/09/2024 12:33:25  - Module: default    - Thread ID: 1  - INFO       - PandApache3 process id:3738
12/09/2024 12:33:25  - Module: default    - Thread ID: 1  - INFO       - PandApache3 process name:dotnet
12/09/2024 12:33:25  - Module: Server     - Thread ID: 1  - INFO       - PandApache3 is up and running!
12/09/2024 12:33:25  - Module: Web        - Thread ID: 6  - INFO       - Running Connection manager module
12/09/2024 12:33:28  - Module: Web        - Thread ID: 6  - INFO       - Client connected
12/09/2024 12:33:28  - Module: Web        - Thread ID: 12 - INFO       - Reading query string parameter
12/09/2024 12:33:28  - Module: Web        - Thread ID: 13 - INFO       - LoggerMiddleware invoked
12/09/2024 12:33:28  - Module: Web        - Thread ID: 13 - INFO       - Log Request
12/09/2024 12:33:28  - Module: Web        - Thread ID: 13 - INFO       - [12/09/2024 10:33:28] GET /
12/09/2024 12:33:28  - Module: Web        - Thread ID: 14 - INFO       - Log Response
12/09/2024 12:33:28  - Module: Web        - Thread ID: 14 - INFO       - [12/09/2024 10:33:28] Response status code: 200
12/09/2024 12:33:28  - Module: Web        - Thread ID: 14 - INFO       -  client Closed
12/09/2024 12:33:28  - Module: Web        - Thread ID: 6  - INFO       - Client connected
12/09/2024 12:33:28  - Module: Web        - Thread ID: 13 - INFO       - Reading query string parameter

On y voit des informations classiques, mais deux éléments qui changent de façon régulière et qui sont très importants : le module et le thread ID.

Pour comprendre comment on en arrive à ces logs, le plus logique est sans doute de commencer par regarder de quoi est composé un module de PandApache, notamment ses propriétés. Voici les propriétés du module ConnectionManager, qui est la classe instanciée pour le module Web et Admin :

public TcpListener Listener { get; set; }
public TaskFactory TaskFactory { get; }
public ModuleConfiguration ModuleInfo { get; set; }
public ModuleType ModuleType { get; set; }
private static AsyncLocal<ModuleConfiguration> _current = new AsyncLocal<ModuleConfiguration>();
public CancellationTokenSource _cancellationTokenSource { get; } = new CancellationTokenSource();
private ConcurrentDictionary<Guid, ISocketWrapper> _clients { get; } = new ConcurrentDictionary<Guid, ISocketWrapper>();
private ConcurrentDictionary<Guid, ISocketWrapper> _clientsRejected = new ConcurrentDictionary<Guid, ISocketWrapper>();
private Func<HttpContext, Task> _pipeline;
private TaskScheduler _taskScheduler;

Les propriétés qui vont nous intéresser en particulier sont :

public ModuleConfiguration ModuleInfo { get; set; }
private TaskScheduler _taskScheduler;

Le TaskScheduler est plutôt simple, même si nous avons réimplémenté notre propre TaskScheduler pour quelques modifications. C’est un héritage de la classe par défaut et donc fonctionne globalement de la même manière.

ModuleConfiguration, quant à elle, est une classe originale que voici :

public class ModuleConfiguration
{
    private TaskScheduler _taskScheduler;
    public ModuleType Type;
    public string Name;
    public bool isEnable;
    public TaskFactory TaskFactory { get; }
    public VirtualLogger Logger;

    public ModuleConfiguration(string name)
    {
        Name = name;
        Type = moduleType;
        Logger = new VirtualLogger(name);
    }
}

On retrouve notre TaskScheduler, mais nous avons aussi un VirtualLogger qui prend en paramètre un nom.

Un VirtualLogger est exactement comme le logger normal de PandApache. D’ailleurs, la classe VirtualLogger et Logger implémentent tous deux l’interface ILogger.

La différence est que le VirtualLogger envoie son log au Logger, et ce dernier envoie son log au système (Console ou fichier).

Nous avons donc des modules qui s’exécutent chacun dans leur propre tâche et qui contiennent nos deux instances d’objets que l’on souhaite utiliser dans des contextes d’exécution bien précis. Nous avons tous les éléments mis en place pour ce que nous souhaitons faire, il suffit de voir ensemble comment cela fonctionne.

Entre nous

On pourrait se dire qu’un VirtualLogger est une abstraction inutile ici. On pourrait très bien utiliser directement la classe Logger originelle avec plusieurs instances différentes, exactement comme ce que l’on fait avec le VirtualLogger. C’est certes vrai, mais il y a d'autres avantages au VirtualLogger qui n’ont pas été expliqués ici. Ce qu’il faut retenir, c’est que le VirtualLogger n’est pas là uniquement pour avoir des loggers indépendants, mais surtout pour séparer l’action de logger une information et l’action de la distribuer, que ce soit à la console ou dans un fichier. On explorera cela dans un prochain billet de blog.

Le Contexte d'Exécution

Reprenons la ligne pour exécuter le logger du début.

ExecutionContext.Current.Logger.LogInfo($"Admin server listening on {ServerConfiguration.Instance.ServerIP}:{ServerConfiguration.Instance.AdminPort}");

Il est temps de parler de l’objet ExecutionContext. Il s’agit d’une classe simple qui ne contient qu’un champ statique pour être appelé de partout facilement. La voici :

public static class ExecutionContext
{
    private static AsyncLocal<ModuleConfiguration> _current = new AsyncLocal<ModuleConfiguration>();

    public static ModuleConfiguration Current
    {
        get => _current.Value;
        set => _current.Value = value;
    }
}

La particularité de cette classe est le type de _current, qui est un AsyncLocal<ModuleConfiguration>. Cela nous permet de garantir une valeur distincte de _current dans les différents contextes d'exécution, autrement dit, dans les tâches.

Chaque module, au démarrage, assigne à la variable _current de son contexte d'exécution l’objet ModuleInfo :

ExecutionContext.Current = ModuleInfo;

Quand, dans le module, la ligne :

ExecutionContext.Current.Logger.LogInfo("Starting Connection manager module");

Sortie:

12/09/2024 12:26:48  - Module: Web        - Thread ID: 1  - INFO       - Starting Connection manager module

est utilisée, c’est donc bien le bon logger qui est utilisé, celui du module.

D'ailleurs voici les 2 sorties de log de cette même ligne généré par 2 modules (Web et Admin)

Sortie:

12/09/2024 12:26:48  - Module: Web        - Thread ID: 1  - INFO       - Starting Connection manager module
12/09/2024 12:26:48  - Module: Web        - Thread ID: 1  - INFO       - Web server listening on 0.0.0.0:8080
12/09/2024 12:26:48  - Module: Admin      - Thread ID: 1  - INFO       - Starting Connection manager module
12/09/2024 12:26:48  - Module: Admin      - Thread ID: 1  - INFO       - Admin server listening on 0.0.0.0:4040

Quand un module lance une autre tâche, comme le module Web qui accepte une connexion pour traiter la requête :

await AcceptConnectionsAsync(client);

On change théoriquement de contexte, on est dans une sous-tâche de la tâche principale. Cependant, la valeur de la propriété AsyncLocal est automatiquement héritée, ce qui fait que dans la fonction AcceptConnectionsAsync, quand on utilise le logger via ExecutionContext :

ExecutionContext.Current.Logger.LogInfo($"Client connected");

sortie:

12/09/2024 12:33:45  - Module: Admin      - Thread ID: 9  - INFO       - Client connected

Nous avons toujours le bon ModuleInfo configuré.

Finalement

Tout ceci nous permet beaucoup de choses dans PandApache. Pour les loggers, même si chaque VirtualLogger diffère très peu (seul le nom du module stocké directement dans le logger diffère d’un VirtualLogger à l’autre), nous avons quand même l’avantage de la transparence et de l’isolation logique au moment de l’utilisation, ainsi que de la cohérence et de la standardisation au moment de l’écriture.

Le TaskScheduler, dont nous avons très peu parlé car moins visuel, mais qui fonctionne exactement comme le logger, nous permet encore une fois de façon très transparente de lancer de nouvelles tâches dans notre module, en ayant des règles notamment au niveau du nombre de threads personnalisés. Ainsi, on peut s’assurer que le module télémetrie, qui n’est pas un module vital, n’utilise pas trop de ressources (un thread pour la télémetrie est, par exemple, suffisant selon le nombre de métriques que vous souhaitez capturer).

Au contraire, si votre module web n’a plus assez de ressources pour gérer une nouvelle requête, vous allez être très contrarié. C’est donc une gestion des ressources plus fine qui peut être effectuée au final grâce à ce contexte d’exécution partagé.

J’espère que cet article vous aura aidé à mieux comprendre l'utilisation de AsyncLocal en C#. Si ce langage vous intéresse, sachez que le code de PandApache3 est disponible sur GitHub et en live sur Twitch. N’hésitez pas à suivre l’aventure !

Code in music: What the piano can teach you about programming

Mary 🇪🇺 🇷🇴 🇫🇷 — Tue, 03 Dec 2024 12:36:15 +0000

The holiday season is here!

Like every year in December, there are two things you just can’t escape:

Advent of Code if you’re a programmer.
*ingle Bell Rock if you step into a shopping mall.

That’s just how it is—I don’t make the rules.

Advent of Code is all about programming puzzles, kind of like what you find year-round on LeetCode. Its stated goal is to make you a "better programmer." And I do mean programmer, not developer.

So, how do you become better at programming? Should you be grinding LeetCode every day? I’ve never had to implement a merge sort at work, so do I really need to learn it?

Whoa, slow down!

Speaking of which, did you know that piano means "slowly" in Italian? Perfect segue, because before we dive into programming, let’s talk about piano. Don’t leave just yet—it’ll be worth it.

Playing the Piano

When I’m not behind a computer keyboard, you can probably find me behind a piano (keyboard, piano, computer—you see the connection? Alright, got it).

And funnily enough, learning piano offers a lot of parallels to programming.

What does playing the piano involve? It’s not about memorizing the name or sound of every single key. (You generally know where C is. From there, based on your hand position relative to C, you know what notes to play. But you don’t necessarily need to know exactly where A and B are, for example.)

Playing the piano means hitting the right notes in the right rhythm. It’s really a combination of the two. If you play random notes, you’re just making noise, not music.

If you hit the right notes but leave 10 seconds of silence between each, you don’t have music either—there’s no rhythm.

To improve these two skills, there are various exercises. For hitting the right notes, you might play very slow-ly, ignoring rhythm entirely. The goal is to figure out: the note to read on the sheet music and the finger to use to play it. Sometimes your hands will need to move, so you also practice repositioning them. To build muscle memory, you play several notes or melodies slowly—very slow-ly.

For rhythm, you play simple notes or sequences. The goal isn’t to play a melody but to hit the notes within the allotted time.

As you improve, the exercises become harder, but the ultimate aim remains the same: to eventually play a piece by combining note accuracy and speed to maintain rhythm.

When you’re at an intermediate level and play a piece for the first time, if it’s simple (a children’s tune, for example), you can play it almost perfectly on the first try or with minimal practice.

But if you attempt something more challenging (jazz, for instance), you’ll need to do more exercises for note accuracy and rhythm specific to that piece.

Another interesting point: you can learn to play a demanding piece, not touch it for a few months, and then try again. You’ll probably be terrible on your first attempt, but you’ll quickly regain your footing and play it perfectly without redoing the entire learning process.

If you want to improve at piano, you’ll also need to step out of your comfort zone. You can stick to children’s tunes your entire life, but that won’t help you play jazz later without practice. You need to play different styles, of varying difficulty, and with diverse rhythms.

In summary, to learn piano, you need to:

Practice various exercises to improve the different skills required for playing music.
Play diverse pieces with increasing difficulty.
Occasionally revisit older pieces to quickly regain your footing and strengthen your muscle memory.

And Programming?

Well, it’s the same.

That's it, thank you for your time, see you next soon!

And Programming?

Well, it’s the same.

Puzzles like LeetCode are like little melodies. To solve them, you need to use the right data structures and algorithms (the equivalent of piano notes) and do so within the given time limit (our rhythm).

If you’re tackling a LeetCode puzzle involving a merge sort for the first time, you should start by learning—outside of the puzzle—what a merge sort is, how it works, and how to code it. Slow-ly. Then, you can try solving the puzzle within the time limit. At first, you might exceed the limit, but with practice, you’ll hit the right rhythm.

Once you’ve nailed that exercise (the right algorithm, at the right speed), you can explore other puzzles—other melodies. Some will be similar, others not. Increase the difficulty to progress, but don’t expect to succeed on the first try. That’s not the goal.

Revisit them a few months later (for a project or an interview). You’ll find that while your implementation might be a bit slow at first, you’ll quickly regain your footing and solve the puzzle within the time limit again.

I’m a Pianist, Not a Musician; I’m a Programmer, Not a Developer

Now, do coding puzzles make you a better programmer? If you do them regularly, probably yes. But do they make you a better developer? Not really, because that’s not the same thing.

If I play piano, I can play Jingle Bell Rock at home without issue. Great, I have a good time, and it adds a festive vibe. But playing piano doesn’t teach me to:

Compose my own music.
Play with other instruments.
Perform in an orchestra...

In short, lots of things. Playing piano doesn’t necessarily make me a musician. I’m a pianist—a hobbyist pianist, and that’s perfectly fine.

Likewise, being good at programming doesn’t make you a developer (the profession). It doesn’t teach you to structure your code, write documentation, or do many other things engineers need. It simply teaches you to solve programming puzzles.

Sure, some problems might be reusable in a professional setting (I work with tree traversals like DFS and BFS quite often, for instance), but that’s anecdotal compared to everything else I do on the job.

Happy holidays! If you’ve got Jingle Bell Rock stuck in your head now, you’re welcome. 🎄

Code en musique: Ce que le Piano peut vous apprendre sur la programmation

Mary 🇪🇺 🇷🇴 🇫🇷 — Tue, 03 Dec 2024 12:00:16 +0000

La période de fête arrive, comme chaque année en décembre, vous ne pouvez pas échapper à deux choses :

L’AventOfCode si vous êtes développeur.
Jingle Bell Rock si vous allez dans un centre commercial.

C’est comme ça, ce n’est pas moi qui fais les règles.

L’AventOfCode, ce sont des puzzles de programmation, un peu comme ce qu’on peut retrouver toute l’année sur LeetCode. Le but affiché est de devenir un « meilleur programmeur ». Et je dis bien programmeur, pas développeur.

Alors, comment devenir meilleur en programmation ? Est-ce que je dois faire du LeetCode tous les jours ? Je n’ai jamais eu à réimplémenter un merge sort au boulot, dois-je vraiment apprendre à le faire ?

WOW, doucement !

Tiens, d’ailleurs, vous savez que piano veut dire doucement en italien ? Ça tombe bien, avant de parler de programmation, on va parler de piano. Mais restez, ça va être bien.

Jouer du piano

Quand je ne suis pas derrière un clavier d’ordinateur, vous pouvez sans doute me trouver derrière un piano (clavier, piano, ordinateur, vous l’avez ? Ok, vous l’avez).

Et figurez-vous qu’en apprenant le piano, on peut faire pas mal de comparaisons avec la programmation.

Jouer du piano, qu’est-ce que c’est ? Ce n’est pas connaître le nom ou le son de chaque touche par cœur. (On sait en général où se trouve le do. Ensuite, par la position des mains par rapport à la note do, on sait quelle note jouer. Mais on n’est pas obligé de savoir exactement où se trouvent le la et le si, par exemple).

Jouer du piano, c’est réussir à enchaîner les bonnes notes, dans le bon rythme. C’est vraiment la combinaison des deux. Si vous enchaînez plein de notes aléatoires, vous faites du bruit, mais pas de la musique.

Si vous enchaînez les bonnes notes, mais qu’il y a 10 secondes de silence entre chaque, on n’a pas de musique non plus, car il n’y a pas de rythme.

Pour travailler ces deux compétences, on a plusieurs exercices. Pour les bonnes notes, on va, par exemple, jouer très len-te-ment, hors rythme donc, car le but est d’identifier : la note à lire sur la partition et le doigt à utiliser pour jouer cette note. Sachant que parfois, les mains se déplacent, il faut donc aussi s’entraîner à repositionner ces mains. Pour obtenir cette mémoire musculaire, on va jouer plusieurs notes ou mélodies de façon lente, voire très len-te.

Pour travailler le rythme, on va jouer des notes ou des enchaînements simples. Car le but n’est pas tant de jouer une mélodie que de jouer des notes dans le temps imparti.

Et bien sûr, plus on progresse, plus les exercices deviennent difficiles, mais le but final est toujours le même : être prêt, à un moment, pour jouer une musique en combinant justesse des notes et rapidité pour garder le rythme.

Quand vous avez un niveau moyen au piano, et que vous jouez pour la première fois une musique, si elle est facile (une comptine pour enfants, par exemple), vous pourrez la jouer quasiment parfaitement du premier coup ou avec très peu d’entraînement.

À l’inverse, si vous essayez une musique plus complexe (du jazz, par exemple), vous allez devoir faire plus d’exercices de justesse des notes et de rythme en lien avec cette musique en particulier.

Autre fait intéressant : vous pouvez apprendre à jouer une musique exigeante, ne plus y toucher pendant quelques mois et tenter de la jouer à nouveau. Vous serez probablement très mauvais au premier essai, mais très vite, vous retrouverez vos marques et serez capable de la rejouer parfaitement sans refaire toute la phase d’apprentissage.

Si vous voulez progresser au piano, vous allez aussi devoir sortir de votre zone de confort. Vous pouvez jouer des comptines pour enfants toute votre vie, mais cela ne vous aidera pas à jouer du jazz ensuite sans entraînement. Il faut donc jouer différents styles, de différents niveaux, avec des rythmes variés.

Bref, pour apprendre à jouer du piano, vous devez :

Faire différents exercices pour améliorer les différentes compétences nécessaires pour jouer de la musique.
Jouer des morceaux variés avec une difficulté crescendo.
Rejouer de temps en temps des musiques pour reprendre vos marques rapidement et travailler votre mémoire musculaire.

Et la programmation dans tout cela ?

Eh bien, pareil.

Voila, merci de m'avoir lu, a la semaine prochaine

Et la programmation dans tout cela ?

Les puzzles type LeetCode, par exemple, sont de petites mélodies. Pour les réussir, il faut à chaque fois utiliser les bonnes structures de données et les bons algorithmes (c’est l’équivalent des notes de piano), et le faire dans le temps imparti (c’est notre rythme).

Si vous vous lancez pour la première fois sur un LeetCode qui demande d’effectuer un merge sort, vous devriez d’abord, hors puzzle, aller apprendre ce qu’est un merge sort, comment il fonctionne, comment le coder. Len-te-ment. Ensuite, vous pouvez tenter de le faire le puzzle dans le temps imparti. Peut-être qu’au début, vous serez hors délai, mais à force d’entraînement, vous aurez le bon rythme.

Une fois cet exercice réussi (le bon algo, dans le bon temps), vous pouvez aller explorer d’autres puzzles, d’autres mélodies. Certains seront proches, d’autres moins. Augmentez la difficulté pour progresser, mais ne vous attendez pas à les réussir du premier coup. Ce n’est pas l’objectif.

Revenez dessus quelques mois plus tard (pour un projet ou pour un entretien). Vous verrez que, même si l’implémentation sera un peu plus longue au début, vous reprendrez très vite vos marques et réussirez le puzzle dans le temps imparti, très rapidement.

Je suis pianiste, pas musicien ; je suis programmeur, pas développeur

Maintenant, est-ce que les puzzles de code aident à devenir un meilleur programmeur ? Si vous en faites régulièrement, oui, sûrement. Mais est-ce que cela fait de vous un meilleur développeur ? Pas vraiment, car ce n’est pas la même chose.

Si je joue du piano, je peux jouer Jingle Bell Rock chez moi sans problème. Super, je passe du bon temps, et ça ajoute à l’atmosphère un parfum de fête. Cependant, jouer du piano ne m’apprend pas à :

Écrire mes propres musiques.
Jouer avec d’autres instruments.
Jouer dans un orchestre…

Bref, plein de choses. Jouer du piano ne fait pas forcément de moi un musicien. Je suis pianiste, pianiste amateur, c’est tout, et c’est déjà très bien.

Eh bien, être fort en programmation, c’est pareil. Ça ne vous apprend pas à être développeur (le métier). Ça ne vous apprend pas à structurer votre code, à écrire de la documentation ou à faire plein d’autres choses dont un ingénieur a besoin. Cela vous apprend seulement à résoudre des puzzles de programmation.

Alors oui, parfois ces problèmes peuvent être réutilisés dans un cadre professionnel (je parcours très souvent des arbres au boulot, par exemple, avec du DFS, du BFS), mais ça reste plutôt anecdotique par rapport à toutes les autres parties de mon job.

Joyeuse fête, si vous avez Jingle Bell dans la tête, c'est normal