DEV Community: Mary 🇪🇺 🇷🇴 🇫🇷

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

PandApache version 3.4 est la !

Mary 🇪🇺 🇷🇴 🇫🇷 — Mon, 02 Dec 2024 12:58:16 +0000

Ça a mis un peu de temps (C’est ce qui arrive quand un dev backend travaille sur du front), mais ça y est, PandApache3.4 est disponible ! Release

Cette nouvelle version apporte beaucoup de nouveautés que nous allons voir ensemble maintenant.

Après la version 3.3, qui était très axée sur la partie administration, PandApache continue sur le chemin d’être un serveur web fait pour et par un SRE. Pas de fonctionnalités pour les utilisateurs finaux, mais juste pour nous, les administrateurs ! Au programme : télémétrie, monitoring et opérations d’administration simplifiées.

C’est parti !

Architecture modulaire

Pour un développement et une administration plus simples, le service PandApache3 est maintenant découpé en modules. Trois précisément au moment de cette version :

Le module Web
Le module Admin
Le module Télémétrie

Le module Web est tout simplement le cœur de PandApache, il s’agit du module qui sert à écouter sur le port 80, c’est le module qui permet de rediriger chaque requête HTTP vers la bonne ressource.

Le module Admin n’est pas nouveau, c’est toujours le deuxième service web qui tourne par défaut sur le port 4040 et qui permet d’exécuter des endpoints afin de réaliser des tâches d’administration, comme arrêter ou redémarrer le serveur.

Le module Télémétrie, lui, est nouveau. On en parlera un peu plus tard, mais c’est un module qui permet de recueillir en temps réel des informations sur votre système afin de s’assurer par exemple que votre système hôte a toujours assez de mémoire, assez de CPU, vérifier les écritures sur le disque, etc.

Cette nouvelle architecture est très importante pour plusieurs raisons :

Simplifier grandement le développement dans le futur grâce à cette approche plus modulaire.
Diagnostiquer des problèmes plus finement, notamment grâce aux logs séparés. Vous pouvez mettre le module Web en mode debug et garder les autres en mode info ou erreur pour ne pas polluer vos logs.
En cas de problème sur un module, il peut simplement être désactivé, tout en continuant à profiter des autres modules.

Ces modules sont indépendants et peuvent donc être activés ou désactivés comme vous le souhaitez.

En vrai, c’est un peu bête d’activer le module Télémétrie sans le module Admin par exemple, car vous n’aurez pas accès aux endpoints pour recueillir les infos de télémétrie. Et ça serait très bizarre de ne pas avoir de module Web sur un serveur web, mais après vous faites ce que vous voulez, hein.

Par contre, vous pouvez très bien n’avoir que le module Web, ou que le module Web et Admin. Les endpoints de télémétrie ne fonctionneront pas, mais le reste marchera sans problème.

Ils ont aussi leur propre fichier de log, ce qui permet un troubleshooting plus efficace, en plus d'avoir leur propre niveau de log.

Voici un exemple de la configuration des modules :

<Module Telemetry>
    ModuleLogLevel error
    enable true
    ModuleLogFile telemetry.log
</Module>
<Module Web>
    enable true
    ModuleLogLevel debug
    ModuleLogFile web.log
</Module>
<Module Admin>
    enable true
    ModuleLogFile admin.log
</Module>

Entre nous :

le serveur lui-même est visible comme un module, on peut donc avoir dans les logs des entrées qui viennent du module « Serveur ». C’est tout simplement le processus principal qui lance tous les autres modules et lui ne peut bien sûr pas être désactivé.

Toujours entre nous :

La télémétrie étant quelque chose de très spécifique à l’OS, mais aussi à la langue, elle ne fonctionne que sur Windows. Cependant, le gros du travail est fait pour pouvoir itérer sur cette première base de modules et permettre dans le futur un monitoring plus large sur les différents systèmes.

Télémétrie

Vous le savez, la télémétrie pour assurer la fiabilité d’un service est essentielle, aussi bien pour le service lui-même que pour son hôte. C’est pourquoi un nouveau endpoint /admin/monitor a vu le jour. Sous ce endpoint, vous allez pouvoir retrouver plusieurs métriques afin de vérifier le bon fonctionnement de votre service et de votre système. Retrouvez notamment les endpoints suivants :

/monitor/cpu
/monitor/availablememory
/monitor/diskread
/monitor/diskwrite
/monitor/diskqueue
/monitor/gcheapsize

Et d'autres encore.

Ces endpoints vous permettent de connaître en temps réel les valeurs de votre système correspondant à la métrique associée.

Voici par exemple le résultat du endpoint : http://127.0.0.1:4040/admin/monitor/cpu : 72,80516052246094. Correspondant à la valeur actuelle du CPU.

Bien sûr, cette métrique change à chaque fois. Voici par exemple 3 valeurs différentes obtenues à la suite :

72,80516052246094

64,66727752685547

55,4402359008789

Pour ne pas demander à votre système de monitoring de venir récupérer chaque nouvelle valeur chaque seconde. Il y a un dernier endpoint fonctionnant avec un paramètre: /monitor/metric.

Le paramètre name peut être utilisé avec les valeurs suivantes :

CpuUsagePercentage
AvailableMemoryMB
DiskReadBytesPerSecond
DiskWriteBytesPerSecond
DiskQueueLength
GCCollectionCount
GCHeapSizeBytes

Ce endpoint renverra, contrairement aux autres, une réponse au format JSON :

[{"Key":"2024-12-01T23:57:30.1295087+02:00","Value":57.67658710479736},
 {"Key":"2024-12-01T23:57:38.7241797+02:00","Value":59.110374450683594},
 {"Key":"2024-12-01T23:58:08.2192014+02:00","Value":62.357760747273765},
 {"Key":"2024-12-01T23:58:12.4449679+02:00","Value":54.44178104400635},
 {"Key":"2024-12-01T23:58:21.103619+02:00","Value":65.64530436197917},
 {"Key":"2024-12-01T23:58:21.1044157+02:00","Value":76.43288993835449},
 {"Key":"2024-12-01T23:58:29.665167+02:00","Value":64.24466037750244},
 {"Key":"2024-12-01T23:58:59.2308917+02:00","Value":74.4074338277181},
 {"Key":"2024-12-01T23:59:03.3638932+02:00","Value":78.21070289611816},
 {"Key":"2024-12-01T23:59:11.9931579+02:00","Value":73.42640749613444},
 {"Key":"2024-12-01T23:59:11.993631+02:00","Value":84.76824760437012},
 {"Key":"2024-12-01T23:59:20.7471495+02:00","Value":92.40722846984863},
 {"Key":"2024-12-01T23:59:29.3142203+02:00","Value":65.4045352935791}]

Cela permet d’obtenir plusieurs valeurs sur un temps plus long.

Entre nous :
chaque métrique est capturée toutes les 30 secondes en faisant une moyenne des valeurs obtenues, et les 10 dernières métriques vous sont renvoyées ensuite sous un format qui permet facilement de visualiser l'information sur un graphique.

La console d’administration

Souvenez-vous, lors de la précédente version, la 3.3, nous expliquions que des endpoints administratifs pouvaient être utilisés pour administrer facilement, de manière programmatique, un ou plusieurs services PandApache3, mais aussi pour construire une console d’administration si nous le souhaitions.

C’est désormais chose faite avec la version 3.4, bienvenue dans la console d’administration de PandApache !

Il n’y a rien de plus dur et chiant pour un dev backend que de faire une interface graphique, alors je remercie chaleureusement l’équipe d'AdminLTE pour leur template de console d’administration. C’est leur travail qui a été repris pour réaliser une console fonctionnelle et vous allez voir, que leur template envoie du pâté !

La console d’administration dispose, pour le moment, de 4 sous-sections :

Status :

Une page pour du troubleshooting rapide. Elle permet de connaître le statut de votre service, ainsi que d’avoir un bref historique des derniers logs, dont le format a d’ailleurs été retravaillé.

En plus de l’information du module qui emet les logs, vous avez également son thread ID. Toute la partie gestion de tache de PandApache a été revue.

Health :

Une page avec les métriques de PandApache. Comme vu dans la partie télémétrie, les métriques sont maintenant disponibles via API. Nous en avons donc fait un joli dashboard pour voir en temps réel ce qui se passe.

(Encore une fois, merci à AdminLTE pour leur travail qui a permis une intégration assez facile !)

Management :

Cette page permet d’effectuer des opérations sur le service PandApache3, et vous allez voir qu’il n’y a pas beaucoup de limites à ce que vous pouvez y faire !

Il y a bien sûr les opérations de base qui étaient déjà implémentées : Recharger la configuration, redémarrer le service ou l’arrêter.

Mais vous pouvez aussi maintenant avoir des scripts personnalisés exécutés directement par le service !

Les scripts exécutables sont ceux présents dans votre dossier admin. Nous listons tous les scripts PowerShell ou Shell selon la plateforme.

Vous pouvez, via un nouveau endpoint, les exécuter et obtenir le résultat du script.

Avant de faire une syncope en pensant qu’il est possible d’exécuter du code à distance, sachez que cette option est bien sûr désactivable dans la configuration. Mais les vrais savent à quel point c’est une fonctionnalité importante pour la bonne maintenance d’un service.

Configuration :

Enfin, la dernière page vous affiche la configuration actuelle au format JSON.

Bien que le fichier de configuration au format JSON ne soit pas encore implémenté, cela vous donne un avant-goût du futur : plus de formats de configuration supportés et une gestion de la configuration et de ses changements facilitée.

_Entre nous : _

L’exécution des scripts et leurs résultats est, pour le moment, synchrone. Ce n’est pas idéal, notamment car certains scripts peuvent être longs à s’exécuter. Un système asynchrone avec un task ID qui vous sera renvoyé pour connaître l’état de votre script va être proposé dans le futur, toujours pour faciliter au mieux l’administration du service.

Pour finir

C’était une présentation rapide des nouvelles fonctionnalités clés de PandApache 3.4. J’espère que ce tour d’horizon vous a plu. Cette nouvelle version vient avec, bien sûr, plein de changements non visibles (gestion des logs, gestion des threads, etc.), mais bien réels et qui seront le sujet de futurs articles de blog plus techniques, où nous nous concentrerons sur une problématique à la fois (sinon ce blog post serait beaucoup trop long !).

Comme pour toute nouvelle version, il faut s’attendre à quelques corrections mineures dans les prochains jours, lorsque de nouveaux problèmes seront détectés au fur et à mesure du déploiement sur différentes configurations.

Suivez mes aventures sur Bluesky @pykpyky.bsky.social pour rester informé de toutes les nouveautés. Vous pouvez également explorer le projet complet sur GitHub et me rejoindre pour des sessions de codage en direct sur Twitch pour des moments excitants et interactifs. À bientôt derrière l’écran !

Designing a scalable application with interfaces in C#

Mary 🇪🇺 🇷🇴 🇫🇷 — Wed, 13 Nov 2024 13:51:24 +0000

The PandApache3 web server is based on a modular architecture. But what does that mean in really?

The modules of a web server

If we consider the PandApache3 service as a "black box," we can still break it down into three main modules:

Web Module: Handles HTTP requests on port 80, providing access to the site hosted by PandApache3.
Admin Module: Provides a web interface for administering the PandApache service.
Telemetry Module: Used to collect and analyze data on the service's performance.

These modules work in synergy but can also be run independently, which is very convenient during development. For example, you can activate only the telemetry module for testing without being bothered by the other modules. This flexibility simplifies testing and speeds up development cycles.

This architecture also makes future improvements much easier. For instance, if I want to add a new feature to the server, I just need to write a new module. Thanks to this approach, the new module can easily integrate into the rest of the code without disrupting existing modules.

Simplified integration with interfaces

To standardize each module's behavior, PandApache3 uses a C# interface called IModule. Let’s look at what an interface brings in practice.

An interface in C# is a contract that defines a series of methods without implementing them. By imposing a common framework, it ensures that all modules have the same basic functionality while allowing each module to customize its behavior.

Here is the IModule interface used in PandApache3:

public interface IModule
{
    Task StartAsync();
    Task RunAsync();
    Task StopAsync();
    bool isEnable();
}

Each module must be able to start, run, and stop. The isEnable() method checks if the module is activated based on the service configuration. By implementing this interface, each module ensures it adheres to this structure.

Example implementation for the telemetry module:

public class TelemetryModule : IModule
{
    public async Task StartAsync()
    {
        // Initialize data collection
    }

    public async Task RunAsync()
    {
        // Continuously collect telemetry metrics
    }

    public async Task StopAsync()
    {
        // Stop data collection
    }

    public bool isEnable()
    {
        // Check if the module is enabled
        return ModuleInfo.isEnable;
    }
}

The telemetry module, like the web or admin module, uses this interface to implement its own features.

Using polymorphism

Now that we’ve defined an interface and classes that implement it, how do we manage them uniformly? This is where polymorphism comes in.

Polymorphism is a programming concept that allows different classes to be used in the same way. By using the IModule interface, PandApache3 can handle all modules uniformly, regardless of their actual type.

In the main server class, modules are initialized and then stored in a dictionary of type IModule:

public Dictionary<ModuleType, IModule> Modules = new Dictionary<ModuleType, IModule>();

// Module initialization
TelemetryModule telemetryModule = new TelemetryModule(telemetryTaskScheduler);
ConnectionManagerModule webModule = new ConnectionManagerModule(ModuleType.Web, Pipelines["web"], webTaskScheduler);
ConnectionManagerModule adminModule = new ConnectionManagerModule(ModuleType.Admin, Pipelines["admin"], adminTaskScheduler);

Modules.Add(ModuleType.Telemetry, telemetryModule);
Modules.Add(ModuleType.Web, webModule);
Modules.Add(ModuleType.Admin, adminModule);

// Keep only the modules enabled in the configuration
foreach (var moduleKey in Modules.Keys.ToList())
{
    if (!Modules[moduleKey].isEnable())
    {
        ExecutionContext.Current.Logger.LogWarning($"Module {moduleKey} disabled");
        Modules.Remove(moduleKey);
    }
}

Although the modules are created as TelemetryModule or ConnectionManagerModule objects, they are stored as IModule objects. This way, we can manage them uniformly without needing to know their specific types.

Starting and running modules

The server uses a loop to start all the activated modules, thanks to polymorphism. Here’s what it looks like:

foreach (var moduleName in Modules.Keys)
{
    await Modules[moduleName].StartAsync();
}

Using IModule allows starting, running, and stopping each module in the same loop, regardless of the module’s type. For example, to run all the modules:

List<Task> tasks = new List<Task>();
foreach (var moduleName in Modules.Keys)
{
    tasks.Add(Task.Run(() => Modules[moduleName].RunAsync()));
}

await Task.WhenAll(tasks);

And to stop them:

foreach (var moduleName in Modules.Keys)
{
    await Modules[moduleName].StopAsync();
}

Adding a new module

Thanks to this modular architecture, adding a new module to PandApache3 is simple: just write a new class that implements IModule. The interface sets the framework, ensuring easy and consistent integration.

Interfaces play a crucial role throughout PandApache3. For example, all middlewares follow the IMiddleware interface, allowing them to run in sequence. Components such as the socket, logger, file manager, and even configuration manager also use interfaces, making the code more flexible and easier to test.

With this modular approach and intelligent use of interfaces, PandApache3 becomes an extensible and maintainable web server, ready to evolve with new features without requiring significant changes to the existing codebase.

I hope this article helped you better understand the concrete and essential role of interfaces 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!

Concevoir une application évolutif avec des Interfaces en C#

Mary 🇪🇺 🇷🇴 🇫🇷 — Wed, 13 Nov 2024 13:43:34 +0000

Le serveur web PandApache3 est basé sur une architecture modulaire. Mais qu'est-ce que cela signifie concrètement ?

Les modules d'un serveur web

Si l’on considère le service PandApache3 comme une "boîte noire," on peut néanmoins le diviser en trois modules principaux :

Module Web : Il permet de traiter les requêtes HTTP sur le port 80, donnant accès au site hébergé par PandApache3.
Module Admin : Il offre une interface web pour administrer le service PandApache.
Module Télémetrie : Il est utilisé pour collecter et analyser des données sur le fonctionnement du service.

Ces modules fonctionnent en synergie, mais peuvent également être exécutés indépendamment, ce qui est très pratique lors du développement. Par exemple, on peut activer uniquement le module de télémétrie pour le tester, sans être gêné par les autres modules. Cette flexibilité simplifie les tests et accélère les cycles de développement.

Adopter cette architecture facilite aussi grandement les améliorations futures. Par exemple, si je souhaite ajouter une nouvelle fonctionnalité au serveur, je n’ai qu’à écrire un nouveau module. Grâce à cette approche, le nouveau module peut facilement s’intégrer dans le reste du code sans perturber les modules existants.

Intégration facilitée avec les interfaces

Pour standardiser le comportement de chaque module, PandApache3 utilise une interface C# appelée IModule. Voyons ce qu’une interface apporte en pratique.

Une interface en C# est un contrat qui définit une série de méthodes sans les implémenter. En imposant un cadre commun, elle garantit que tous les modules possèdent les mêmes fonctionnalités de base, tout en permettant à chaque module de personnaliser son comportement.

Voici l’interface IModule utilisée dans PandApache3 :


public interface IModule 

{ 

    Task StartAsync(); 

    Task RunAsync(); 

    Task StopAsync(); 

    bool isEnable(); 

}

Chaque module doit être capable de démarrer, fonctionner et s'arrêter. La méthode isEnable() sert a vérifier, si le module est activé selon la configuration du service. En implémentant cette interface, chaque module s’assure de respecter cette structure.

Exemple d'implémentation pour le module de télémétrie :


public class TelemetryModule : IModule 

{ 

    public async Task StartAsync() 

    { 

        // Initialiser la collecte de données 

    } 



    public async Task RunAsync() 

    { 

        // Collecte en continue des métriques de télémétrie 

    } 



    public async Task StopAsync() 

    { 

        // Arrêter la collecte de données 

    } 



    public bool isEnable() 

    { 

        // Vérifier si le module est activé 

        return ModuleInfo.isEnable; 

    } 

}

Le module de télémétrie, comme le module web ou admin, utilise cette interface pour implémenter ses propres fonctionnalités.

Utilisation du polymorphisme

Maintenant que nous avons défini une interface et des classes qui l’implémentente, comment les gérer de manière uniforme ? C'est ici que le polymorphisme intervient.

Le polymorphisme est un concept de programmation qui permet d'utiliser différentes classes de manière identique. En utilisant l’interface IModule, PandApache3 peut traiter tous les modules de manière uniforme, indépendamment de leur type réel.

Dans la classe principale du serveur, les modules sont initialisés puis stockés dans un dictionnaire de type IModule :


public Dictionary<ModuleType, IModule> Modules = new Dictionary<ModuleType, IModule>(); 



// Initialisation des modules 

TelemetryModule telemetryModule = new TelemetryModule(telemetryTaskScheduler); 

ConnectionManagerModule webModule = new ConnectionManagerModule(ModuleType.Web, Pipelines["web"], webTaskScheduler); 

ConnectionManagerModule adminModule = new ConnectionManagerModule(ModuleType.Admin, Pipelines["admin"], adminTaskScheduler); 



Modules.Add(ModuleType.Telemetry, telemetryModule); 

Modules.Add(ModuleType.Web, webModule); 

Modules.Add(ModuleType.Admin, adminModule); 



// Garder seulement les modules activés dans la configuration 

foreach (var moduleKey in Modules.Keys.ToList()) 

{ 

    if (!Modules[moduleKey].isEnable()) 

    { 

        ExecutionContext.Current.Logger.LogWarning($"Module {moduleKey} désactivé"); 

        Modules.Remove(moduleKey); 

    } 

}

Les modules, bien que créés sous forme d'objets TelemetryModule ou ConnectionManagerModule, sont stockés sous forme de IModule. Ainsi, nous pouvons les gérer de manière uniforme, sans avoir à connaître leur type spécifique.

Démarrage et exécution des modules

Le serveur utilise une boucle pour démarrer tous les modules activés, grâce au polymorphisme. Voici à quoi cela ressemble :


foreach (var moduleName in Modules.Keys) 

{ 

    await Modules[moduleName].StartAsync(); 

}

L’utilisation de IModule permet de démarrer, exécuter et arrêter chaque module dans une même boucle, sans se soucier du type de chaque module. Par exemple, pour exécuter tous les modules :


List<Task> tasks = new List<Task>(); 

foreach (var moduleName in Modules.Keys) 

{ 

    tasks.Add(Task.Run(() => Modules[moduleName].RunAsync())); 

} 



await Task.WhenAll(tasks);

Et pour les arrêter :


foreach (var moduleName in Modules.Keys) 

{ 

    await Modules[moduleName].StopAsync(); 

}

Ajouter un nouveau module

Grâce à cette architecture modulaire, ajouter un nouveau module à PandApache3 est simple : il suffit d’écrire une nouvelle classe qui implémente IModule. L'interface impose le cadre, ce qui garantit une intégration facile et cohérente.

Les interfaces jouent un rôle essentiel dans tout PandApache3. Par exemple, tous les middlewares suivent l’interface IMiddleware, ce qui permet de les exécuter en chaîne. Des composants comme le socket, le logger, le gestionnaire de fichier et même le gestionnaire de configuration utilisent également des interfaces, rendant le code plus flexible et facile à tester.

Avec cette approche modulaire et l'utilisation intelligente des interfaces, PandApache3 devient un serveur web extensible et maintenable, prêt à évoluer avec de nouvelles fonctionnalités sans nécessiter de changements importants dans la base de code existante.

J’espère que cet article vous aura aidé à mieux comprendre le rôle concret et essentiel des interfaces 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 !

Networking: The Essential Asset for Finding a Job

Mary 🇪🇺 🇷🇴 🇫🇷 — Mon, 21 Oct 2024 13:28:42 +0000

"Dear network..."

You've probably seen posts on social media starting with this phrase. Often on LinkedIn, sometimes on Twitter, and surely on other networks too. It’s the common opener for reaching out to people we know in the professional world, which isn’t called "Contacts" or "Friends," but "Network."

Not long ago, I happened to come across someone mocking those who use this method, pointing out that their GitHub was empty and they didn’t even have a portfolio. Embarrassing!

In the world of development and tech, it’s true, developers are often advised to build a solid portfolio and maintain projects on GitHub when job hunting. These elements are often presented as pillars of professional success.

That’s what's supposed to help you land a job.

However...

Let’s not beat around the bush. I disagree.

The Myth of the Portfolio and Git Projects

Sure, having a well-designed portfolio and visible Git projects is advantageous. They showcase your skills, achievements, and your ability to work on concrete projects.

However, these tools are not enough to land you a job, and in more than 93%* of cases, they don’t even help at all!

Job hunting is much more complex than having an up-to-date Git and often depends on factors other than technical skills (like luck).

The Power of Networking

The reality is that job hunting rarely comes down to technical skills alone. More often than not, it’s about being seen in the right place at the right time, and this is frequently made possible by a strong network.
Having a network means maximizing your chances of finding hidden opportunities (those that aren’t necessarily posted on job platforms).

When I was a kid, my mother was unemployed. One day, while we were at the mall with my dad (probably to buy a Nintendo 64 game), we stopped at a café. My dad, who truly embodies the guy with zero academic skills, started chatting with a man sitting next to us, just because he’s a talker. He explained that my mother was looking for a job in logistics. By chance, this man had positions available and gave my dad his number. That’s how my mom found a job.

In my own professional journey, I have countless similar examples, and if you ask around, you’ll find plenty more:

My first internship: Thanks to my school network/my IT teacher
My second internship: Through a guy I met during the first one, and two of my classmates got the same internship thanks to me.
Guess who else did an internship there years later? My little brother.
Apprenticeship: Found because my mom knew someone finishing their apprenticeship, so a spot opened up.
Fifth-year project: Validated thanks to a client... who was in my network.
First job at Microsoft: Job link posted by a classmate on Slack.
Last year, two people also joined Microsoft because they were in my network.

Network, network, network!!!

These examples (and I’ve got plenty more) show that networking can open doors that skills alone cannot. Meeting the right people and getting a recommendation often makes the difference between getting hired or not, getting an interview or not, and even knowing about a job opening or not.

Networking: A Valuable Investment

Investing time and effort into developing your network is a far more valuable strategy than focusing solely on improving your portfolio and GitHub. This isn’t about bullshit or neglecting skills, but rather understanding how the job market truly works.

Having a network doesn’t mean that skills don’t matter. On the contrary, it’s essential to keep developing your skills and working on personal projects. However, your network is the tool that will help you showcase those skills and get noticed by the right people.

No one’s going to say, "Yes, I saw your GitHub, and I’m really impressed by blah blah blah." Sorry, you need to put yourself out there; no one’s going to find you on a nerd site.

As for founders or startup entrepreneurs with genius disruptive methods who recruit through GitHub, you can spot them right away. If someone tells you they were impressed by your GitHub, even though it hasn’t been active for 5 years? Offers you a C++ gig because you did a Hello_world 15 years ago? That’s simply a sourcing method used, most of the time, in a very, very sloppy way.

Proving Your Skills

Yes, technically, you can "prove" "skills" through your GitHub, but no one actually uses it for that. Why?

First of all, companies like procedures, something standard that can be applied to everyone. Not everyone has a GitHub; the majority of developers stop using it after their studies. The ones you see actively using it are the minority. And skill tests are designed for the majority (10 years in tech, countless interviews, and I’ve been asked for my GitHub once, I think).

And I’m not calling you a liar, honestly. But having a project on GitHub isn’t really a reliable proof of competence.

Young developers are often advised to work on projects and put them on GitHub, but that’s not for landing a job. After finishing any classroom, even a long one, even a five-year degree, we have tons of gaps. In short, we’re terrible! You need to keep practicing, a lot, to stand out from the crowd and refine your expertise.

If you’ve done a Master’s in Computer Science like me, it’s likely that 51%* of the courses won’t be useful post-graduation. And that’s normal, education covers all domains, but a Java developer won’t get much experience out of their Python courses. So, they need to keep digging into the Java environment, and this happens through projects.

GitHub is a site for your projects, for managing your projects, it’s not a CV, and thank goodness! (A CV is a whole different story, but that’s for another time).

In conclusion, although portfolios and Git projects are important tools for improving skills, their usefulness for landing a job is negligible. Your network is the most valuable asset. It multiplies your chances of finding opportunities and meeting the right people at the right time. Investing in and cultivating your network will pay off more than spending all your time perfecting your GitHub’s look.

Build your network, nurture your relationships, and be open to opportunities that may come through these connections. That’s how you’ll truly advance in your professional career.

*Statistic pulled from the Wet Finger Institute.