Hello les petits Biscuits !

Bienvenue sur la 44ème édition de Ruby Biscuit.
Vous êtes maintenant 612 abonnés 🥳

Vous lisez Ruby Biscuit, la newsletter Rails de Capsens. S’abonner gratuitement

Parenthèse sur notre virage IA

Chez Capsens, on n’écrit plus vraiment de code nous-mêmes. C’est Claude qui code, nous on fait de l’archi, on spec, on relit, on teste, on valide. Le résultat : environ x1,5 de productivité sur les développements qu’on réalise pour nos clients.
Ce n’est pas encore le mythique x3. On héberge des plateformes avec de gros flux financiers et des documents d’identité, la maintenabilité à long terme et la sécurité ne sont pas négociables pour nous. La relecture humaine et les tests ont un coût et on le sait. On travaille activement pour gagner en productivité sur ces sujets afin qu’ils ne limitent pas les gains de productivité. Notre nouveau directeur technique est à fond là-dessus.
On propose aujourd’hui cet accompagnement à d’autres équipes tech. Si vous cherchez à prendre ce virage avec une équipe qui l’a fait concrètement, on serait ravis d’en discuter.

Bonne lecture.

Chez l’un de nos clients qui propose une plateforme d’investissements en ligne, l’équipe commerciale travaille depuis Airtable. C’est leur outil au quotidien pour suivre les utilisateurs, les investissements et les mouvements financiers. Sauf que la donnée source, elle, vit dans l’app Rails. Il faut donc pousser les données de Rails vers Airtable et les garder à jour.

Au début, nous synchronisions un model. Puis deux. Puis cinq. Chaque model avait son propre worker, son serializer, sa transaction, ses specs. Six à huit fichiers à créer pour chaque nouveau model synchronisé. Vingt-quatre fichiers dédiés rien qu’à la sync. Et quand ça cassait, la synchronisation périodique repassait sans corriger le problème et les erreurs polluaient Appsignal, notre outil de monitoring.

Le vrai problème n’était pas le code existant. C’était la question : “combien de temps pour ajouter un sixième model ?” Réponse : une demi-journée, à câbler les callbacks, copier-coller la logique de digest, prier pour ne rien oublier.

Nous avons d’abord cherché des gems existantes. La plupart ciblaient un CRM spécifique (HubSpot, Salesforce) ou imposaient un couplage fort avec ActiveRecord. Rien qui colle à notre besoin : un système déclaratif, agnostique du CRM, capable de gérer les dépendances entre models.

Nous avons décidé d’écrire notre propre gem. L’idée de départ : rendre la sync CRM aussi simple qu’un has_many ou un validates. Déclarer dans le model ce que nous synchronisons, comment nous le transformons, et laisser la gem gérer le reste.

Quelques mois plus tard, nous avons Etlify, une gem Rails open source créée par Capsens. Le nom vient de l’acronyme ETL : Extract, Transform, Load. C’est exactement ce que fait la gem : extraire les données d’ActiveRecord, les transformer via un serializer, et les charger dans le CRM.

Ce que nous y avons gagné

Avant d’entrer dans le code, voici les chiffres mesurés sur notre migration :

L’architecture en 30 secondes

Etlify repose sur quatre briques, qui suivent la logique ETL.

Extract : la détection des stale records scanne périodiquement vos models pour détecter les records dont le digest a changé sans appel explicite, et relance leur synchronisation.

Transform : le serializer (appelé dictionary dans la gem) transforme un record ActiveRecord en Hash CRM-compatible. Un par model synchronisé.

Load : le synchronizer orchestre le chargement. Il calcule une empreinte SHA256 du payload. Si rien n’a changé, il passe. Sinon il appelle l’adapter (la couche HTTP vers le CRM) et stocke le résultat dans crm_synchronisations.

crm_sync! → Worker (async) → Synchronizer
  ├── sync_if → false ?        → :skipped
  ├── dependency manquante ?   → PendingSync → :buffered
  ├── digest identique ?       → :not_modified
  └── Serializer#to_h → Adapter#upsert! → :synced

Le worker, l’adapter et le synchronizer sont partagés entre tous les models. Vous n’écrivez que ce qui est spécifique : le serializer et la config.

Implémentation

Installation

Ajoutez la gem à votre Gemfile, avec faraday (HTTP), sidekiq-throttled (rate limiting) et sidekiq-unique-jobs (dédup des jobs) si ce n’est pas déjà fait :

gem "etlify", git: "git@github.com:CapSens/etlify.git", tag: "v0.9.3"

Puis :

bundle install

Avant de lancer les migrations, créez l’initializer pour que la gem soit configurée :

Ensuite, générez et lancez les migrations :

rails g etlify:migration create_crm_synchronisations
rails g etlify:migration create_etlify_pending_syncs
rails db:migrate

crm_synchronisations stocke pour chaque record synchronisé :

etlify_pending_syncs garde les syncs bloquées par une dépendance (nous y reviendrons).

L’adapter

La gem fournit le contrat. L’adapter, c’est vous qui l’écrivez. Voici le nôtre pour Airtable :

upsert! retourne le crm_id. delete! retourne un booléen. Les méthodes CRUD privées sont du Faraday classique (POST pour créer, PATCH pour mettre à jour, GET avec filterByFormula pour chercher un record existant).

Point important : la gem ne déclenche pas delete! sur after_destroy. Si vous supprimez un record en base, le record côté CRM reste. À vous de décider où et quand appeler delete! explicitement.

Pour un autre CRM, implémentez upsert!, delete! et le mapping d’erreurs dans handle_response. Le reste change, la mécanique reste la même.

La config YAML

Chaque model a son fichier YAML. L’idée c’est de découpler vos noms de champs des IDs Airtable. Un champ renommé côté CRM ? Vous changez le YAML, pas le code.

Déclarer un model synchronisable

Deux choses à ajouter au model : include Etlify::Model pour le DSL, et has_many :crm_synchronisations pour l’association polymorphique.

Le YAML est chargé au boot via la constante CONFIG_PATH du serializer, un seul endroit où le chemin est défini. crm_object_type reçoit le table ID. id_property sert à retrouver un record existant côté CRM.

Quatre options dans le DSL méritent que nous nous y arrêtions. Nous avons mis un moment à bien les cerner.

sync_dependencies: [:customer] est bloquant. Si le Customer n’a pas de crm_id, la sync est mise en attente. Un PendingSync est créé. Etlify déclenche la sync du Customer en cascade. Quand celui-ci sera sync, les syncs en attente seront exécutées.

dependencies: [:products] est non bloquant. Le serializer de l’Order inclut des données des Products (ex : leur nom, leur prix). Si un Product change, le digest SHA256 de l’Order change aussi au prochain calcul. Le cron de stale records détecte cette différence et re-sync l’Order automatiquement.

sync_if filtre les records éligibles. Si le lambda retourne false, le synchronizer retourne :skipped et ne touche pas au CRM. Attention : un record déjà synchronisé dont le sync_if retourne ensuite false ne sera ni re-sync ni supprimé côté CRM. Cela signifie que si un record change d’état (par exemple, il redevient non éligible), il restera tel quel côté CRM. Pour le retirer, appelez delete! explicitement. À utiliser avec discernement, sur des états réellement définitifs.

stale_scope restreint le scan du cron aux records concernés.

La cascade fonctionne en profondeur. Imaginez : Order → Customer → Company. Etlify met en attente et remonte la chaîne jusqu’à trouver un crm_id. Si ça vous rappelle les poupées russes, c’est normal.

Le serializer

Le serializer, c’est le fichier où vous décidez ce que le CRM voit de vos données. D’abord, la classe de base :

Le helpers/h donne accès aux helpers Rails (h.number_to_currency, h.truncate, etc.) directement dans vos serializers. Ça dépanne plus souvent qu’on ne le pense.

Puis le serializer du model :

Les clés du Hash retourné par to_h sont les field IDs Airtable, pas vos noms de colonnes. Un serializer par model synchronisé.

Le worker

Le model sait quoi, le serializer sait comment. Reste le transport. La gem fournit un Etlify::SyncJob par défaut. Ici nous le remplaçons par un worker Sidekiq avec throttling pour respecter les limites Airtable :

Le throttle :airtable_api doit être déclaré dans votre initializer Sidekiq :

Et la queue crm dans votre config :

Le worker a retry: false côté Sidekiq. Le synchronizer fait un seul essai par invocation : s’il échoue, il incrémente error_count dans crm_synchronisations et passe au suivant. Pas de retry en boucle, c’est le cron des stale records qui rattrape le coup au cycle suivant. Après 3 échecs consécutifs (configurable via max_sync_errors), le record est exclu du cron automatique. Il reste synchronisable manuellement via crm_sync!. Un appel réussi remet error_count à zéro.

En complément, un worker cron rattrape les records dont le digest a changé sans appel explicite :

Planifiez-le dans votre config/schedule.yml à la fréquence qui vous convient.

Déclencher la sync

Tout est en place. Pour synchroniser un record : order.crm_sync!(crm_name: :airtable). Un one-liner depuis vos services, transactions ou controllers. Nous l’appelons après un paiement validé, dans nos transactions de membership, dans les services d’onboarding. Le synchronizer gère le reste.

Migrer depuis un système legacy

Si vos models avaient une colonne airtable_id, ajoutez un fallback :

Les deux systèmes cohabitent. Vous migrez model par model.

Pour éviter de re-sync tous vos records via l’API, un rake task crée les CrmSynchronisation en masse à partir des airtable_id existants :

Le task stocke l’empreinte actuelle. Seuls les records modifiés après le backfill seront re-sync. Pas de flood API.

Tests

Pour vos tests, mockez les appels HTTP vers Airtable plutôt que de remplacer l’adapter. Cela permet de tester le vrai comportement de bout en bout, y compris votre handle_response et le mapping d’erreurs :

Puis testez vos serializers et le comportement de sync :

Etlify n’est pas limitée à Airtable. L’architecture par adapter permet de brancher n’importe quel CRM. La gem embarque un NullAdapter pour vos tests et le développement local. Si vous utilisez ActiveAdmin, les tables crm_synchronisations et etlify_pending_syncs se branchent très bien pour monitorer vos syncs et relancer les records en erreur.

Si vous synchronisez un CRM depuis Rails et que ça commence à devenir pénible, essayez-la. Nous aurions aimé l’avoir plus tôt.

La gem est open source : github.com/CapSens/etlify

— Benjamin, développeur chez Capsens

Bienvenue sur la 43ème édition de Ruby Biscuit.
Vous êtes maintenant 608 abonnés 🥳

Bonne lecture.

Vous lisez Ruby Biscuit, la newsletter Rails de Capsens. S'abonner gratuitement

Considérez le contrôleur suivant :

Il présente une faille de sécurité évidente : tout utilisateur de la plateforme peut trouver des messages privés qui ne lui sont pas destinés.

Considérez également cette URL :

/investments/38

Il expose une information sensible : un aperçu du nombre d’investissements, surtout si
l’utilisateur vient de créer le sien et a été dirigé vers InvestmentsController#show.

En ce qui concerne le premier exemple, je doute que vous écriviez du code créant une
telle faille de sécurité. Vous avez pris le réflexe d’écrire :

Nous ne maîtrisons cependant pas tout le legacy code d’une application, et ce genre de faille peut exister à notre insu et de façon moins évidente que dans l’exemple.

Quant au second exemple, il n’existe pas de modification facile à appliquer au contrôleur pour ne pas exposer l’identifiant séquentiel de l’investissement.

Les UUID peuvent résoudre ces deux problèmes en même temps. Voyons comment !

Que sont les UUID ?

UUID signifie universally unique identifiers. Les identifiants séquentiels traditionnels se
répètent d’une table de la base de données à une autre, ainsi que d’une application à une autre. Il y a un User avec l’identifiant 1 et un PrivateMessage avec l’identifiant 1. Les mêmes chiffres entiers qui augmentent un à un sont utilisés dans beaucoup d’applications. Au contraire, les UUID sont des identifiants uniques, non seulement d’une table de base de données à une autre, mais d’une application à une autre. Chacun représente un string entièrement unique, qui ne sera jamais répété.

Il y a plusieurs standards d’UUID, mais concentrons-nous sur celui établi par l’Internet
Engineering Task Force. Ce standard comporte neuf versions, qui utilisent plusieurs stratégies pour produire un string hexadécimal de 32 caractères universellement unique.

Quelles sont ces stratégies ?

I. Utiliser des combinaisons de namespaces hashés et uniques
II. Utiliser des timestamps allant parfois jusqu’aux 100 nanosecondes
III. Utiliser des caractères aléatoires
IV. Utiliser une combinaison de timestamps et de caractères aléatoires

En voici un exemple :

019bff1a-a80f-7bad-b4da-ea545f04972c

qui met en œuvre cette dernière stratégie.

Des neuf versions d’UUID, PostgreSQL n’en utilise que deux : les versions 4 et 7. La
version 4 des UUID est un string aléatoire disponible depuis la version 13 de PostgreSQL. La version 7 des UUID, qui combine un timestamp et des caractères aléatoires est disponible depuis la version 18 de PostgreSQL.

Le timestamp de la version 7 permet d’ordonner les objets par leur UUID, ce qui n’est
pas possible avec le string aléatoire de la version 4. C’est pour cette raison que la version 7 est préférable à la version 4 pour nos usages.

L’anatomie d’UUID version 7

Intéressons-nous de plus près à la version 7 des UUID. Notre UUID d’exemple comporte 32 caractères hexadécimaux, hors tirets :

to_i(16) convertit l’hexadécimal en nombre de millisecondes, que nous convertissons ensuite en secondes.

Après le timestamp, il y a un 7, qui est invariable et représente la version d’UUID. S’il
s’agissait d’un UUID version 4, il y aurait un 4.

Les autres valeurs sont aléatoires, à l’exception du V, qui représente le variant de l’UUID.
Ce variant permet de distinguer le standard des UUID de l’Internet Engineering Task Force des autres standards. L’Internet Engineering Task Force utilise quatre valeurs pour représenter ce variant : 8, 9, A et B, puisque ces valeurs, exprimées en binaire, commencent toujours par 10.

Dans notre exemple, il s’agit d’un B :

019bff1a-a80f-7bad-B4da-ea545f04972c

Cela nous laisse 18 caractères hexadécimaux aléatoires. Sans même prendre en compte le timestamp, la probabilité de trouver ces 18 caractères et le variant est 16 caractères hexadécimaux puissance 18 fois 4 variants.

Ce nombre de possibilités colossal rend l’UUID unique, impossible à deviner et donc
sécurisé.

Comment utiliser les UUID avec une base de données PostgreSQL ?

Maintenant que vous avez une compréhension théorique des UUID, regardons comment les utiliser dans une application Ruby on Rails avec PostgreSQL.

Les UUID en PostgreSQL sont des types de colonnes uuid, tout comme les identifiants
séquentiels ont le type bigint.

Même si nous avons une préférence pour le version 7 des UUID, regardons l’implémentation de ces deux versions.

Pour créer une nouvelle table avec un UUID v4, il suffit de faire :

Avec un UUID v7

Les clefs étrangères de l’une et de l’autre version doivent préciser le type uuid :

Revenons à nos exemples initiaux :

Même si l’on peut accéder à n’importe quel message privé en tapant l’identifiant du
message dans l’URL, il est impossible qu’un utilisateur malveillant puisse deviner l’identifiant d’un message privé qu’il n’est pas censé voir.

Considérez encore notre URL :

/investments/38

Avec un UUID, il devient

/investments/019bff1a-a80f-7bad-b4da-ea545f04972c

et le nombre d’investissements est désormais caché.

Ainsi, les UUID, qu’ils soient de la version 4 ou de la version 7, sécurisent votre
application depuis la base de données et obscurcissent des informations potentiellement sensibles.

— Andrew, développeur chez Capsens

Bienvenue sur la 42ème édition de Ruby Biscuit.
Vous êtes maintenant 610 abonnés 🥳

Annonce : On recrute ! Capsens cherche un·e dev backend Ruby on Rails confirmé·e à Lyon. Toutes les infos ici

Bonne lecture.

Je me souviens d’une époque pas si lointaine, quand j’ai commencé ce métier de développeur web, où écrire des tests automatiques, eh bien ça n’existait tout simplement pas ! À contrario, aujourd’hui, je ne connais plus personne qui n’en écrit pas. Alors pourquoi ? À quoi ça sert les tests ? Et comment maximiser leur efficacité en minimisant l’effort nécessaire pour les écrire ?

À quoi ça sert ?

Entre le monde d’avant les tests, et le monde d’après, une chose principalement est devenue beaucoup, beaucoup, plus facile : modifier son programme sans peur. Sans peur des effets de bord, sans avoir besoin de re-tester à la main toutes les fonctionnalités pour voir si on n’a pas introduit quelque part un bug inattendu. Sauf si vous pratiquez le TDD, les tests ne vous aident pas à développer. Mieux vaut jouer des scénarios à la main en local pour voir comment fonctionne ce que vous êtes en train de coder plutôt que d’écrire des tests. Les tests ne font pas non plus une bonne documentation. Mieux vaut écrire du code lisible et bien découpé, et vous n’aurez pas besoin de tests pour comprendre votre code. Les tests sont INDISPENSABLES pour une chose : vérifier que toutes les autres fonctionnalités de l’app fonctionnent toujours après votre passage. Et c’est donc pour cette raison qu’il faut écrire des tests; des tests qui répondent à cette problématique !

Écrire des tests qui évitent les régressions !

Dans la grande famille des tests, on peut différencier trois grands groupes : les tests dits “unitaires”, qui testent de très petits bouts de code (une seule méthode par exemple). Les tests dits “d’intégration”, qui testent plusieurs petits bouts de code en même temps (une méthode qui appelle une méthode qui appelle une méthode). Et finalement les tests dits “end to end”, qui simulent l’ensemble de l’application, en simulant directement les interactions de l’utilisateur.

Afin de prévenir les bugs en production, le mieux serait d’écrire des tests end to end. Ils testent toute la stack, tous les appels, tout ! Si un utilisateur en prod a un bug, un test end to end qui simule le même parcours l’aurait forcément vu (et donc évité). Sauf que les tests end to end c’est loooong et compliquéééé à écrire. Et c’est looooooong à exécuter aussi ! Franchement, quel développeur peut se permettre d’attendre une heure (ou plus) à chaque fois qu’il/elle lance un rspec ?

Les tests end-to-end ont clairement leur places dans votre suite de tests. En particulier pour les parties les plus sensibles ou les scénarios les plus communs de votre application. Mais ils ne constitueront pas la majorité de vos tests.

Pour cela, il nous reste donc deux prétendants à analyser, les tests unitaires et les tests d’intégrations. Lesquels sont les meilleurs pour repérer les bugs d’effets de bord ?

Lesquels sont les meilleurs ?

Imaginons que j’ai ces bouts de code dans mon appli Rails :

# app/models/user.rb
class User < ApplicationRecord
  def send_welcome_email
    UserMailer.welcome(self).deliver_later
  end
end

#app/controllers/users_controller.rb
class UsersController < ApplicationController
  def create
    @user = User.create(user_params)
    @user.send_welcome_email
  end

  def user_params
    params.require(:user).permit(:email)
  end
end

Et les tests unitaires qui vont avec :

# spec/models/user_spec.rb
RSpec.describe User do
  describe "after_create callback" do
    it "#send_welcome_email" do
      user = build(:user)

      expect(UserMailer).to receive(:welcome)

      user.send_welcome_email
    end
  end
end

# spec/controllers/users_controller_spec.rb
RSpec.describe UsersController do
  describe "POST #create" do
    it "sends an email" do
      user = instance_double(User)

      allow(User).to receive(:create).and_return(user)
      allow(user).to receive(:send_welcome_email)

      post :register, params: { email: "toto@email.fr" }

      expect(user).to have_received(:send_welcome_email)
    end
  end
end

Jusqu’ici tout va bien. Les tests sont verts, tout fonctionne normalement, je peux envoyer mon code en production sans inquiétude.

Et puis, un beau jour, quelques mois plus tard, je crée une version “API” de la création d’utilisateurs, avec un twist :

# app/controllers/api/users_controller.rb
module API
  class UsersController < APIController
    def create
      @user = User.create(user_params)
      @user.send_welcome_email
    end

    def user_params
      params.require(:user).permit(:email, :role)
    end
  end
end

# app/models/user.rb
class User < ApplicationRecord
  validates :role, inclusion: {in: %w[admin customer], allow_blank: true}

  def send_welcome_email
    UserMailer.welcome(self).deliver_later if role == "customer"
  end
end

Mon API permet de gérer plusieurs “rôles”, les clients et les admins. Et forcément, je n’envoie pas d’emails aux admins, ils n’en ont pas besoin. Bon, maintenant il faut que je fasse mes tests unitaires. J’en rajoute un pour mon nouveau controller, et comme j’ai modifié le modèle bah je vais devoir modifier le test pour cette méthode.

# spec/controllers/users_controller_spec.rb
RSpec.describe API::UsersController do
  describe "POST #create" do
    it "sends an email" do
      user = instance_double(User)

      allow(User).to receive(:create).and_return(user)
      allow(user).to receive(:send_welcome_email)

      post :register, params: { email: "toto@email.fr", role: "customer" }

      expect(user).to have_received(:send_welcome_email)
    end
  end
end

# spec/models/user_spec.rb
RSpec.describe User do
  describe "after_create callback" do
    it "#send_welcome_email" do
      user = build(:user, role: "customer")

      expect(UserMailer).to receive(:welcome)

      user.send_welcome_email
    end
  end
end

Super chouette. J’ai fini mon code, tous les tests sont verts, je peux envoyer sereinement mon code en production…

Et là …

En fait, personne ne le remarque vraiment, et c’est grâce aux clients qui commencent à se plaindre au service client qu’on s’en rend compte : les utilisateurs qui s’inscrivent par la voie “classique” ne reçoivent plus l’email de bienvenue (qui contient plein d’infos importantes).

Et mon chef me demande pourquoi je ne m’en suis pas rendu compte avant alors même qu’on alloue 40% du temps à écrire des tests !

Si seulement j’avais écrit un test d’intégration plutôt qu’un test unitaire, par exemple :

# spec/controllers/users_controller_spec.rb
RSpec.describe UsersController do
  describe "POST #create" do
    it "sends an email" do
      expect {
        post "/users", params: { user: {email: "toto@email.fr"} }
      }.to change { ActionMailer::Base.deliveries.count }.by(1)
    end
  end
end

Celui-ci aurait raté quand j’ai introduit la notion de rôles. Parce qu’il n’a pas de mock. Parce les tests d’intégration évitent une grande partie des mocks, alors que les tests unitaires en utilisent beaucoup pour limiter le scope de ce qu’ils testent. Et que les mocks il faut les maintenir. Et que cette fois-ci j’ai oublié.

Premier point marqué en faveur des tests d’intégration. Continuons avec un deuxième exemple.

Le deuxième exemple ?

Mettons que j’ai un service :

# app/services/order_total.rb
class OrderTotal
  def initialize(order)
    @order = order
  end

  def call
    @order.items.sum(&:price)
  end
end

# spec/services/order_total_spec.rb
describe OrderTotal do
  it "returns the sum of item prices" do
    order = double(items: [
      double(price: 10),
      double(price: 20)
    ])

    expect(OrderTotal.new(order).call).to eq(30)
  end
end

Et un controller :

# app/controllers/orders_controller.rb
class OrdersController < ApplicationController
  def show
    order = Order.find(params[:id])
    total = OrderTotal.new(order).call

    render json: { total: total.to_i }
  end
end

# spec/controllers/orders_controller_spec.rb
describe OrdersController do
  it "returns the order total" do
    order = double(id: 1)
    allow(Order).to receive(:find).and_return(order)

    allow(OrderTotal).to receive_message_chain(:new, :call)
      .and_return(30)

    get :show, params: { id: 1 }

    expect(response.body).to include("30")
  end
end

Maintenant, notre app évolue et on doit rajouter le calcul de la TVA. Comme notre code est bien découpé, c’est facile, il suffit de modifier le service :

# app/services/order_total.rb
class OrderTotal
  def initialize(order)
    @order = order
  end

  def call
    {
      subtotal: subtotal,
      tax: tax,
      total: subtotal + tax
    }
  end

  private

  def subtotal
    @order.items.sum(&:price)
  end

  def tax
    subtotal * 0.2
  end
end

# spec/services/order_total_spec.rb
describe OrderTotal do
  it "returns a detailed total hash" do
    order = double(items: [
      double(price: 10),
      double(price: 20)
    ])

    result = OrderTotal.new(order).call

    expect(result[:total]).to eq(36)
  end
end

Et maintenant, deux options : soit on a écrit des tests unitaires, comme je l’ai fait dans cet exemple. Dans ce cas les tests sont tous verts, et je vais soit leur faire confiance et envoyer un bug en production, soit ne pas leur faire confiance et rechercher manuellement tous les endroits qui auraient pu être impactés par ma modif (et dans ce cas, j’ai le risque d’en oublier, et aussi, pourquoi je m’embête à écrire des tests ?).

Ou bien, j’ai écrit des tests d’intégration, comme celui-ci :

# spec/controllers/orders_controller_spec.rb
describe "GET /orders/:id" do
  it "returns the correct total" do
    order = create(:order)
    create(:item, order: order, price: 10)
    create(:item, order: order, price: 20)

    get "/orders/#{order.id}"

    json = JSON.parse(response.body)
    expect(json["total"]).to eq(36)
  end
end

Et le test serait devenu rouge. Et je me serai rendu compte que maintenant le service OrderTotal me renvoie un Hash, et que {}.to_i ça renvoie 0 !

Un second point pour les tests d’intégration, qui nous ont évité de grosses gouttes de sueur.

Comment écrire de bons tests d’intégration

Avant de conclure, j’aimerais attirer votre attention sur un point important : les tests d’intégration ne vous sauveront la mise que s’ils scénarisent toutes les variantes possibles du code.

Prenez cet exemple, j’ai des documents associés à mes utilisateurs, et un mécanisme d’autorisations qui limite l’accès d’un utilisateur à ses propres documents uniquement.

# app/models/document.rb
class Document < ApplicationRecord
  belongs_to :user
end

# app/policies/document_policy.rb
class DocumentPolicy
  def initialize(user, document)
    @user = user
    @document = document
  end

  def show?
    @document.public? || owner?
  end

  private

  def owner?
    @document.user_id = @user.id
  end
end

# app/controllers/documents_controller.rb
def show
  document = Document.find(params[:id])
  authorize document

  render json: document
end

Et le test d’intégration qui va avec :

# spec/controllers/documents_controller_spec.rb
describe "GET /documents/:id" do
  it "allows the owner to see the document" do
    user = create(:user)
    document = create(:document, user: user, public: false)

    sign_in user
    get "/documents/#{document.id}"

    expect(response).to have_http_status(:ok)
  end
end

Vous, cher lecteur, aurez peut-être vu le bug (dans la méthode DocumentPolicy#owner?, le développeur a confondu le symbole d’une assignation = avec le symbole d’une égalité ==), mais mon test d’intégration lui ne verra rien du tout. Pourquoi ? Parce que je ne teste que le “chemin heureux”, le cas où tout va bien. Pour bien faire, il FAUT que j’ajoute un test qui vérifie quand ça ne fonctionne pas :

# spec/controllers/documents_controller_spec.rb
describe "GET /documents/:id" do
  it "allows the owner to see the document" do
    user = create(:user)
    other_user = create(:user)
    document = create(:document, user: other_user, public: false)

    sign_in user
    get "/documents/#{document.id}"

    expect(response).to have_http_status(:forbidden)
  end
end

À cette condition seulement je peux me fier à mes tests d’intégration. C’est donc une nécessité absolue de vérifier et revérifier que vos tests d’intégration couvrent correctement tous les différents cas qui pourraient se produire. Faites relire vos tests, demandez au relecteur de se concentre particulièrement fort sur les tests, pour vérifier que vous n’avez rien laissé passer.

Vos tests ne sont utiles QUE si vous leur faites confiance. Et pour leur faire confiance, il faut qu’ils détectent les bugs, et qu’ils testent exhaustivement ce qui se passe dans votre code.

Les tests unitaires sont-ils utiles ?

À me lire, vous pourriez commencer par croire que les tests unitaires ne servent à rien. C’est bien normal car j’ai écrit cet article pour argumenter que les tests d’intégration sont plus intéressants que les tests unitaires.

Afin d’apporter un peu de nuance dans mon propos, discutons autour d’un exemple. Prenons le code suivant :

# app/controllers/subscriptions_controller.rb
def create
  @subscription = Subscription.new(subscription_params)
  
  CheckSubscriptionValidity.new(@subscription)
  SubmitSubscriptionToGoverment.new(@subscription)
  NotifySubscriptionHolder.new(@subscription)
  @subscription.save

  render @subscription
end

À votre avis, quelle suite de test sera la plus simple et rapide à écrire, relire et maintenir :

• Option A : Des tests unitaires pour chacun des trois services qui sont utilisés dans cette action, plus un ou deux tests d’intégration qui vérifient que l’ensemble fonctionne correctement.

• Option B : Des tests d’intégration uniquement, autant qu’il faut pour couvrir toutes les combinaisons possibles et imaginables.

Dans cette situation aucune des deux options ne se démarque vraiment. Vous pourriez choisir l’option A, je pourrais choisir l’option B, et nous aurions tous les deux raison.

Conclusion

Peu importe que vous écriviez des tests unitaires, d’intégration ou end-to-end, mais pour écrire de bons tests, ce que je veux vous dire c’est :

• Couvrez TOUS les scénarios

• Utilisez les tests qui simulent au plus près le comportement d’un utilisateur réel

• Autant que possible en prenant en compte les limitation de temps et de ressources dont vous disposez

Si vous faites cela, vous pourrez enfin modifier votre application sans peur, et arrêter d’’envoyer des bugs en production.

Outro

Et voilà ! Merci à tous d’avoir lu mon avis autour de la politique de tests dans une équipe technique. J’espère que j’ai su apporter des arguments convaincants et que cet article sera la source de nombreux débats à travers toutes les boîtes tech de France. Prenez soin de vos collègues et à bientôt !

— Thomas

Abonnez-vous maintenant

Bienvenue sur la 41ème édition de Ruby Biscuit.
Vous êtes maintenant 612 abonnés 🥳

Bonne lecture.

Créer une API Web simplement et rapidement

Ce mois-ci, nous allons plonger dans la création d’une API. Bien structurer son API est crucial pour votre application. Découvrez des techniques qui peuvent améliorer la maintenabilité et les performances de vos projets.

Partie théorique

Avant de nous lancer, faisons un bref rappel sur les APIs et leurs rôles dans une application web.

Une API web va exposer vos données à l’extérieur de l’application. Elle va permettre aussi de communiquer avec d’autres services web.

Il est considéré comme une bonne pratique de :

• versionner vos API,

• protéger leurs accès (authentification et doorkeeper),

• paginer leurs réponses (pagy),

• avoir une documentation (Rswag),

• respecter le format JSON Api et les formats ISO (jsonapi-serilizer).

Setup

Après ce bref rappel, passons à l’implémentation.

Tout d’abord, voici les gems que nous allons utiliser tout au long de cet article.

Dans cet article, je n’aborde pas l’authentification. Il existe plusieurs façons de la gérer, et cela pourrait faire l’objet d’un article à part. Il ne faut cependant pas l’oublier, sous peine d’exposer vos données à n’importe qui.

Nous allons maintenant créer un controleur parent pour les futurs contrôleurs d’API de l’application.

Il existe deux écoles pour nommer un contrôleur parent dans un namespace : BaseController ou ApplicationController. Ici, nous allons ici choisir ApplicationController.

Ensuite, je vais paginer mes ressources avec la gem Pagy. Par défaut, je choisis de renvoyer 50 ressources par appel API. On pourrait laisser aux utilisateurs la possibilité de changer cette valeur dans la payload, mais par soucis de simplicité on ne va pas le faire ici.

Implémentation pour le modèle Project

Comme dans de nombreuses applications web, nous avons un modèle Project. Commençons par créer un index pour les projets dans l’API.

Il faut donc ajouter une route dans le namespace api, puis dans le namespace v1.

Contrôleur Projects

Nous allons maintenant créer le contrôleur Projects.

Nous appliquons d’abord la pagination grâce à la méthode pagy() fournie par la gem. Elle reçoit comme premier argument nos ressources, puis la valeur de pagination.

Ensuite nous allons renvoyer un json qui contient nos données, des liens vers les pages (links) et quelques metadonnées conformément à la spec JSON API.

Serializer

Pour respecter le principe de responsabilité unique, nous générons donc le hash dans un Serializer avec la gem jsonapi-serializer. Sa mission est de transformer la donnée brute en un format clair et lisible. La gem va aussi respecter les spécifications de JSON API.

Format des données en général et des dates en particulier (avec le serializer)

Respectez la norme OpenAPI pour le format des données. Notamment pour les dates utilisez la méthode iso8601 .

Par exemple, le 13 mai 2025 devra s’écrire "2025-05-13" ou "2025-05-13T14:45:00+02:00".

Rendu

Voici un exemple d’un résultat d’une requête faite avec Postman sur l’endpoint http://localhost:3000/api/v1/projects (en changeant la pagination à 2)

Optimisation : Requête N+1

Attention aux requêtes N+1 dans vos contrôleurs !

Si votre Serializer utilise des données provenant d’autres tables, pensez à les inclure.

Tests

Assurez-vous de la fiabilité de votre code grâce à des tests.

Dans notre cas, nous allons écrire deux tests :

• un test du ProjectSerializer,

• un test de requêtes sur l’API.

Dans un premier temps, nous testons que le Serializer renvoie les bonnes données.

Pour le test d’API et la document nous allons utiliser Swagger mais nous verrons cela dans un prochain article

Conclusion

Et voilà, vous venez de construire une API simplement et rapidement.
Bonne année 2026 !

— Alexandre

Abonnez-vous maintenant

Bienvenue sur la 40ème édition de Ruby Biscuit.
Vous êtes maintenant 601 abonnés 🥳

Bonne lecture.

Booster votre productivité avec .irbrc

En tant que développeur RoR je passe ma vie avec un terminal ouvert. Il y a quelques années, je me suis aperçu que beaucoup trop souvent je tapais les mêmes choses dedans. Mais aujourd’hui c’est beaucoup moins vrai. Et je me suis dit qu’il était grand temps de vous faire part de mes petites astuces 😉

Le setup en 10 secondes

Plutôt que d’expliquer le problème, on va directement passer à la solution car c’est tellement rapide, d’ailleurs il ne reste plus que 7 secondes !

Et voilà! 🎉 Maintenant quand vous lancerez irb, vous aurez un joli message pour vous dire que votre .irbrc est chargé.

Je vous entends d’ici. “Mais moi je n’utilise jamais irb”. Mais est-ce que par hasard vous utilisez de temps en temps un petit rails console dit rails c pour les intimes ?
Car cela fonctionne aussi!

⚠️ Si jamais cela ne marche pas chez vous, c’est certainement que vous utilisez pry et non irb. Il suffit de créer un .pryrc avec ceci dedans et c’est réglé :

C’est parti pour le boost 🚀

Je vais vous donner quelques exemples que j’ai glané à droite et à gauche, ainsi que quelques uns perso.

Me

Dans quasi toutes les applications j’ai un model User et très souvent j’existe moi-même dans les utilisateurs.
Donc je me retrouve souvent à faire des :

Quand je reste quelques temps dans une entreprise, je finis par connaître mon id par cœur donc cela va un peu plus vite :

Mais maintenant j’ai cela dans mon .irbrc :

Donc dans mon terminal je peux faire: me.projects.last au lieu de User.find_by(email: ‘mon@email.com’).projects.last

Models

Cela m’arrive quelques fois d’être sur une application et d’avoir besoin de lister tous les models.

Avoir la liste des models en soi n’apporte pas beaucoup plus que de parcourir le dossier models, mais si je veux facilement lister tous les models qui ont le module Taggable je peux faire cela :

Mais c’est quoi ce ‘it’ ? 👉 Le paramètre”it” de Ruby 3.4

Ou lister tous les models qui ont une relation avec le model User :

Dans mon application dernièrement je voulais savoir s’il y avait des models qui avaient la colonne comment à nil. Mais je sais que j’ai plus de 10 models qui avaient une colonne comments. Pas de souci :

Multi-tenants

Kesako ? 👉 Gem Act At Tenant

Dans un projet j’ai du multi tenants. Lors d’une requête http pas de souci, mais en console, avant même de pouvoir faire quoique ce soit, je suis obligé de set le tenant.

À chaque fois je dois faire :

Et comme vous pouvez le voir la syntaxe est loooongue...
Mais maintenant j’ai ça :

Clear

Usage préféré :

tt et crtt

Dans cette exemple je travaille sur un service `MonServiceSurLequelJeTravaille`, qui a besoin d’une instance de `Project` toute neuve. Tant que je travaille sur ce service, je vais passer ma vie à écrire ces trois lignes dans mon terminal :

Afin de juste pouvoir faire un key up dans mon terminal pour relancer ma dernière commande, je préfère écrire ces trois lignes dans un fichier test.rb et dans mon terminal je ne fais qu’un load(’test.rb’)

(comme j’utilise cette astuce dans tous mes projets rails, je l’ai rajouté dans mon gitignore global)

J’imagine que vous trouverez aussi load(’test.rb’) beaucoup trop long à écrire, donc mon .irbrc s’est étoffé :

En réalité tt je ne l’utilise rarement car maintenant il y a la petite soeur :

lm

Mon problème: Je passe ma vie à oublier les noms de méthodes.

Par exemple:

• Je sais qu’il y a plein de méthodes qui jouent avec la case sur les strings.

• Quand j’ajoute une colonne firstname à mon user, il y a une bonne vingtaine de méthodes qui sont générées

Mais dans un cas comme dans l’autre, je n’ai pas la prétention (ni le désir) de toutes les connaître par cœur.

En ruby on peut faire cela :

Beaucoup trop long! 🤮 Du coup j’ai rajouté cela dans mon .irbrc

Et maintenant sur n’importe quel objet je peux faire .lm suivi par ce que je cherche. Donc si je reprends mon exemple :

Et ensuite ?

Moi j’utilise mon irb de cette façon, mais ce fichier est avant tout là pour configurer votre irb. Vous avez la main sur le prompt, les couleurs et autre. Il y a beaucoup d’article dessus, et personnelement je n’ai jamais ressenti le besoin de toucher cette configuration.

Pour ma part, je m’en sers de deux façons:

- Soit pour des choses que je tape très souvent, et où les taper en 3 lettres au lieu de 20 me fait gagner beaucoup de temps.

- Soit des choses où je sais que la syntaxe est compliquée, que je n’utilise pas très souvent, mais quand j’en ai besoin cela me fait gagner du temps de ne pas rechercher la syntaxe (ex: models ☝)

C’est donc à vous de voir ce que vous faites souvent dans une console! 😉

Un dernier exemple

Dans la dernière application que j’ai intégré, on a des variants (de produit) qui ont des codes-barres.

On passe notre vie à les voir sur l’interface, mais leur id n’apparait jamais dans l’url, car ils sont toujours visible sur la page d’une autre ressource. Or c’est souvent notre point d’entrée pour les debugs.

J’ai donc eu un nouveau besoin: Pouvoir chargé vite en mémoire un variant depuis un code-barres :

⚠ N’oubliez pas que lorsque vous surchargez des objets bas niveau, cela peut avoir des impacts. Vérifiez bien que les noms de méthodes sont disponibles !

Et voilà 🎉

— Joseph

Abonnez-vous maintenant

Hello les petits Biscuits !

Bienvenue sur la 39ème édition de Ruby Biscuit.
Vous êtes maintenant 600 abonnés 🥳

Bonne lecture !

Bonjour à tous ! Aujourd’hui nous allons voir comment implémenter une feature de plus en plus populaire et demandée pour améliorer la sécurité de nos comptes, le 2FA. C’est parti 👇🏻

Mise en place

Nous allons avoir besoin de devise-two-factor (à supposer que vous ayez devise sur votre plateforme bien entendu).

La version la plus récente de devise-two-factor (6.1.0 à l’heure où j’écris ces lignes) n’est pas destinée aux versions de Rails qui précèdent la 7.0. Nous allons voir ici l’implémentation avec une version de Rails plus ancienne, la 6.1.x. Pour cela nous allons devoir nous tourner vers la v4.x.

Nous verrons en fin d’article ce qu’il faut mettre en place pour les versions de Rails plus récentes.

Implémentation

• Déterminer sur quel modèle mettre en place le 2FA. Nous utiliserons la table users.

• Ajouter une config Devise à notre modèle User

• Lancer la migration pour ajouter les champs en ajoutant un default: false sur la colonne otp_required_for_login si vous voulez feature flaguer par utilisateur.

• Ajouter la durée de validité du code dans devise.rb :

• Enfin plus globalement, suivre la doc étape par étape est recommandée puisque cette dernière est très bien faite 👍

Nous allons désormais nous occuper de notre SessionsController et mettre en place nos conditions. On veut pouvoir require le two factor sous certaines conditions donc ajoutons cette logique avec 2 callbacks :

NB : si vous n’avez pas d’environnement de production cette configuration peut vous sembler inutile puisque vous souhaitez l’activer sans condition aucune.
Le require_no_authentication nous permet d’éviter un flash error de devise comme quoi nous sommes déjà connecté lors de l’authentification avec le 2FA.

Voilà pour la configuration globale de la gem !

Désormais nous allons ajouter notre logique métier et envoyer un mail avec un code de confirmation lorsque le 2FA est actif.

1ère étape :

La variable d’environnement 2FA_ENCRYPTION_KEY n’est pas là pour faire joli. La méthode generate_otp_secret de la gem sert à générer un secret sur l’objet visé. En effet, cela va générer des valeurs dans les champs que nous avons ajouté dans la migration. À savoir entre autre dans :

otp_secret, qui est trouvable dans la documentation, est obligatoire pour faire marcher le 2FA. Si vous tentez de vous connecter avec le two factor sans que votre utilisateur ai d’otp_secret alors vous aurez une 500.

Je vous conseille donc d’ajouter la ligne suivante à chaque création de User sur votre plateforme :

Si ensuite vous souhaitez feature flaguer par User vous pouvez ajouter 2 méthodes dans le modèle et les utiliser comme bon vous semble :

2ème étape :

Direction le SessionsController pour y ajouter du code :

Nous avons beaucoup de choses à décortiquer et nous allons regarder chaque étape de authenticate_with_two_factor pour comprendre.

• Tout d’abord si notre resource est vide nous voulons render le formulaire avec un message d’erreur.

• Ensuite nous allons vérifier si dans le cookie le param “remember me” (remember_2fa_id) est présent. Vous savez c’est la petite checkbox qui ressemble à ça habituellement 👇

Auquel cas si le mdp est correct, on ne redemandera pas de passer par une deuxième étape. Nous reviendrons sur cette histoire de cookie un peu plus tard.

• Sinon nous allons regarder si le param otp_attempt est présent. Il faut savoir que pour le 2FA nous avons 3 params obligatoires, l’email, le mdp et otp_attempt.
  Nous allons également checker si un param de session (otp_user_id) est présent (qu’on set par la suite), auquel cas nous consommons le token validate_and_consume_otp!, effaçons le param de session, enregistrons remember_2fa_id dans le cookie si l’utilisateur a coché la case et enfin l’authentifions.
  
  NB : la méthode validate_and_consume_otp! est trouvable dans la documentation.

• Dernière étape, créons un token de session qui nous servira pour le mail puis envoyons ce dernier. Néanmoins nous y ajoutons un lock pour ne pouvoir générer qu’un mail avec code unique par tranche horaire. C’est de la logique métier et non obligatoire, vous pouvez vous en passer.

• Si aucunes des conditions préalables n’ont été réunies cela signifie que le mdp est incorrect et nous affichons un message d’erreur.

Avec cela nous avons terminé la première étape du 2FA. Étape suivante, si je dois me connecter et rentrer un code de connexion alors j’ai besoin que l’on m’affiche un formulaire !

3ème étape :

Créer un fichier HTML (ici nous rentrons dans “users/sessions/two_factor”) pour y intégrer le formulaire. Libre à vous de choisir comment le présenter, mais cela peut ressembler à cela :

Une fois le mail reçu ainsi que le code qu’il contient (il vous faudra afficher current_otp à votre utilisateur) nous allons rentrer ce code et repasser dans le SessionController puisque le formulaire est une requête POST sur ce dernier.
Tout le chemin du authenticate_with_two_factor va donc être répété et vous pouvez désormais comprendre l’intérêt de remember_2fa_id. Si ce dernier était présent à la première étape alors nous ne serions pas passés par ce formulaire et le controller nous aurait redirigé.

Nous remarquons ici néanmoins le bouton “Renvoyer le code” et nous allons comprendre pourquoi nous avons mis en cache le otp_token :

C’est ici qu’intervient notre controller d’envoi de mail.

Pour éviter d’envoyer le mail à une mauvaise adresse nous allons vérifier que la valeur en cache est égale au param passé au controller, si tel est le cas on ajoute un lock (pour éviter le spam) et on envoie le mail, sinon on redirige.

Pour une meilleure expérience utilisateur, gérer cet envoi en AJAX est recommandé 👍

Tests

Pour les tests il y a beaucoup de cas à tester mais les plus globaux sont ceux-ci pour le SessionsController (n’hésitez pas à tester tous les cas) :

Et pour le SendOtpPasswordEmailsController :

En conclusion

Vous avez maintenant toutes les cartes en main pour mettre en oeuvre votre 2FA au sign in sur votre app ! Reste à décider, selon vos besoins et logiques métier, comment vous souhaitez organiser tout cela.
Pensez bien à tester tous les cas de figures que vos utilisateurs pourraient avoir envie d’essayer. Notre otp_user_id par exemple sert, entre autre, à conserver le bon id pour vérifier que si à l’étape du 2FA je fais un retour arrière et qu’ensuite je rentre une autre adresse mail (car je peux avoir 2 comptes différents), alors le mail s’envoie à la nouvelle adresse mail et non pas à l’ancienne !

Merci pour votre lecture et j’espère que l’article vous a plu 🚀

Bonus : ce qu’il faut faire pour Rails 7+

• Ajouter d’autres variables d’environnement

  

• La migration est différente.

• Retirer database_authenticatable de votre modèle puisque les 2 modules sont incompatibles. Cela se fait normalement tout seul avec la version 4.x.

Mais pour plus de précisions je vous invite à regarder la documentation.

— Stanislas

Abonnez-vous maintenant

Bienvenue sur la 38ème édition de Ruby Biscuit.
Vous êtes maintenant 598 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture.

Je suis développeur back-end chez Capsens, et dans le cadre d’une évaluation de la concurrence en matière d’IA, on m’a donné une semaine pour tester le plan Max de Claude Code. Mon objectif principal était de mesurer l’utilité réelle de cet outil dans notre contexte de développement, d’analyser ses performances et de déterminer s’il offrait des gains de temps notables. Ce test visait également à identifier ses forces et ses limitations, afin de mieux comprendre ce qu’il pourrait apporter à notre manière de concevoir des plateformes, en comparaison avec les outils que nous utilisons habituellement.

Disclaimer

Il me semble important de préciser d’emblée le contexte de ce test : nous n’avons pas consacré un temps considérable à l’optimisation du fichier de configuration CLAUDE.md, et nous utilisons cet outil pour développer des plateformes relativement complexes. Mon retour d’expérience ne prétend donc pas refléter le potentiel maximal de l’outil dans un environnement parfaitement configuré. Notre chercheuse en IA m’a également apporté son aide sur certains aspects, ce qui a probablement influencé positivement certains résultats. Ce retour reflète avant tout mon expérience personnelle dans ces conditions spécifiques d’utilisation.

Mes impressions

À mon sens, Claude Code est un outil jeune qui nécessite une adaptation par rapport à l’écriture de code traditionnelle.

De prime abord, j’ai trouvé l’expérience un peu déroutante, car il m’a fallu fournir des instructions extrêmement précises et bien structurées pour obtenir un résultat satisfaisant. En effet, j’ai constaté que l’outil semble moins tolérant aux imprécisions ou aux formulations vagues, ce qui m’a obligé à décrire les tâches de manière minutieuse et exhaustive. Ce besoin de précision m’a parfois donné l’impression de ralentir mon processus de développement, car je passais plus de temps à affiner les instructions qu’à écrire du code, ce qui m’a semblé être un contretemps en termes d’efficacité.

Dans mon expérience, l’outil a présenté des comportements parfois imprévisibles, tant dans le code généré que dans la gestion des dépendances. Parfois, il installait des dépendances sans aucune demande préalable, ce qui m’a surpris. J’ai également constaté qu’il n’hésitait pas à supprimer du code que je jugeais utile si cela semblait l’arranger. Cela m’a amené à être particulièrement vigilant concernant les solutions proposées, car j’ai appris qu’il était indispensable de toujours vérifier ce qui avait été modifié ou ajouté avant de l’intégrer.

J’ai trouvé l’expérience utilisateur de Claude Code franchement mauvaise. J’ai constamment eu l’impression de faire de la relecture de code d’un développeur junior. De plus, l’intégration avec le terminal m’a semblé usante et rébarbative. Cependant, l’intégration avec VS Code a légèrement amélioré mon expérience en facilitant la gestion du code et en offrant une interface plus familière. Cela m’a notamment permis une meilleure navigation et une prise en charge plus fluide des suggestions de code. Toutefois, j’ai trouvé que cette intégration restait limitée et ne compensait pas entièrement les lacunes de l’outil, notamment en termes de réactivité.

Points positifs

1. Bonne compréhension du contexte back-end

D’après mon expérience, Claude Code démontre une bonne capacité à comprendre le contexte global back-end de l’application. J’ai remarqué qu’il comprend bien comment Ruby on Rails fonctionne et qu’il arrive donc facilement à naviguer à travers l’application pour faire les modifications. Néanmoins, bien que Claude Code soit généralement capable de naviguer efficacement dans la partie back-end, j’ai observé que son comportement peut parfois être moins prévisible. Il m’est arrivé qu’il nécessite un peu plus de contexte ou d’ajustements pour comprendre pleinement certaines spécificités du projet. En ce qui concerne le front, j’ai constaté que l’outil a encore des limitations dans sa capacité à naviguer de manière autonome dans les fichiers nécessaires. Cela dit, je pense qu’il est possible que ces limitations puissent être atténuées avec un paramétrage plus fin du fichier de configuration CLAUDE.md .

2. Potentiel pour l’automatisation

J’ai identifié que l’outil montre un fort potentiel pour :

• La création de tests unitaires avec une couverture de 100%

• La génération de tests d’intégration

• La création de données complètes de seed pour les bases de données

3. Potentiel pour les traductions

À mes yeux, Claude Code est très bon dans la gestion des traductions. J’ai constaté qu’il maîtrise bien la syntaxe YAML et propose des traductions relativement pertinentes. En configurant le fichier CLAUDE.md , j’ai pu automatiser l’ensemble du processus : remplacement automatique des textes en dur par des appels I18n.t() , génération des clés selon les conventions de nommage, et création des fichiers de locale. Cette automatisation a considérablement réduit le risque d’oublis lors de l’ajout de nouvelles fonctionnalités.

Points négatifs

1. Processus chronophage

J’ai observé que :

• La génération de code peut être longue et fastidieuse (autour de 20 s par réponse)

• Plus le contexte est important, plus le temps de génération augmente

• L’outil nécessite des instructions très détaillées, ce qui réduit selon moi le gain de temps de développement

2. Comportements non maîtrisés

J’ai remarqué une tendance à :

• Installer des dépendances non demandées

• Nécessiter une vigilance constante de ma part sur les actions automatisées

• Introduire des bugs nécessitant des corrections

• Prendre en compte le CLAUDE.md de manière aléatoire

Exemple concret que j’ai rencontré : un test échoue en raison de l’absence d’une gem. Plutôt que de me proposer de l’installer, il tente de contourner le problème. Je lui demande donc d’installer cette gem, ce qu’il fait, puis il relance les tests qui échouent à nouveau, car il n’a fait qu’installer la gem sans l’intégrer dans le fichier. Au lieu d’examiner comment utiliser la gem, il me propose à nouveau la première solution de contournement.

3. Efficacité questionnée

De mon point de vue :

• La qualité du code n’est généralement pas meilleure en comparaison avec du code que je produis moi-même

• Le gain de temps n’est pas systématique

• Claude Code peut même ralentir mon processus dans certains cas, par exemple :

  • Lorsqu’il génère du code imprécis ou incomplet, nécessitant des corrections manuelles supplémentaires

  • Lorsqu’il nécessite un paramétrage fin et complexe, comme dans le cas de la configuration des dépendances ou des fichiers I18n

  • Lorsqu’il faut lui fournir des instructions très détaillées, ce qui me prend plus de temps que d’écrire directement le code moi-même

4. Nécessité de vérifications constantes

J’ai constaté :

• L’importance cruciale de demander l’écriture de tests pour l’auto-correction

• Le besoin de superviser toutes les modifications apportées

• Le risque d’erreurs nécessitant une révision manuelle

Exemple concret que j’ai vécu : j’avais un problème de configuration du gestionnaire d’assets Sprocket. Plutôt que d’essayer de corriger le problème de manière traditionnelle, il m’a proposé de réécrire directement Sprocket.

5. Fatigue intellectuelle et risque de validation automatique

J’ai expérimenté une forme particulière de fatigue cognitive avec l’utilisation prolongée de l’outil. Passer des heures à relire et valider du code généré automatiquement crée chez moi une lassitude qui peut conduire à des validations hâtives. Je trouve cela particulièrement dangereux car cela me pousse à accepter des solutions médiocres ou inappropriées simplement par épuisement mental.

Conclusion

Selon mon expérience, Claude Code est une technologie émergente avec un bon potentiel, mais qui nécessite encore de nombreuses améliorations. J’ai trouvé que l’outil est particulièrement prometteur pour l’automatisation des tâches répétitives comme la création de tests et la génération de code standardisé.

Mes recommandations :

1. Utilisation ciblée : Je recommande de privilégier Claude Code pour la génération de tests, de seeds et de code répétitif plutôt que pour le développement principal.

2. Expérience utilisateur : D’après mon expérience, il vaut mieux privilégier l’intégration VS Code qui, bien que limitée, offre une expérience légèrement plus confortable que le terminal.

3. Approche progressive : Je suggère de commencer par des tâches simples et d’augmenter progressivement la complexité.

4. Supervision active : Selon moi, il est essentiel de maintenir une vigilance constante sur le code généré et de systématiquement demander des tests. Je déconseille également de généraliser cet outil chez les développeurs juniors.

5. Vision stratégique : Je considère Claude Code comme un assistant permettant d’explorer des solutions plus ambitieuses plutôt qu’un simple accélérateur de productivité.

En conclusion, de mon point de vue, Claude Code n’est pas encore un remplacement du développement traditionnel, mais plutôt un complément qui, bien utilisé, peut enrichir le processus de développement et permettre d’atteindre des objectifs plus ambitieux.

J’ai le sentiment que l’utilisation excessive de cet outil risque de créer une perte de la connaissance globale de la plateforme. Un développeur qui ne comprend pas intimement son code devient selon moi dépendant de l’outil et perd sa capacité à intervenir efficacement en cas de problème complexe ou d’évolution de l’application.

De plus, il me semble important de noter que le coût financier (abonnements, utilisation API) et écologique (consommation énergétique des modèles IA) reste élevé par rapport aux gains de productivité que j’ai pu constater.

Son adoption doit être réfléchie et progressive, en gardant à l’esprit que l’objectif n’est pas nécessairement de coder plus vite, mais de pouvoir aller plus loin dans les réalisations techniques.

— Jérôme, développeur back-end RoR chez Capsens

Abonnez-vous maintenant

Temps de lecture : 6 minutes

Hello les petits Biscuits !

Bienvenue sur la 37ème édition de Ruby Biscuit.
Vous êtes maintenant 595 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture.

Une brève introduction au typage en Ruby

Ajouter des types à un langage dynamique comme Ruby, mais pourquoi ?

Quand on y réfléchit, c'est une idée moins surprenante qu'il paraît.
Après tout, c'est ce que propose Typescript, avec le succès qu'on connaît aujourd'hui.
Saviez-vous d'ailleurs qu'une majorité de développeurs utilise désormais TypeScript plutôt que JavaScript ? ¹
La tendance est claire : l'ajout d'un système de types à un langage dynamique suscite un engouement certain.

Après tout, qui ne voudrait pas d'un monde où undefined method 'machin' for nil:NilClass ne serait plus qu'un lointain souvenir ?

Notre objectif dans cet article n'est pas de vous donner un cours magistral sur les systèmes de types, mais plutôt de faire un état de l'art de ce que Ruby propose aujourd'hui.
Alors accrochez-vous : on entre sur un terrain expérimental, parfois instable, mais plutôt excitant pour l'avenir de Ruby !

Le rôle central du duck typing

Avant de rentrer dans le vif du sujet avec un exemple de code, il est important de rappeler un pilier de Ruby : le duck typing.

If it walks like a duck and it quacks like a duck, then it must be a duck.

« Duck typing » : une technique qui consiste à ne pas se soucier de la classe exacte d'un objet, du moment qu'il répond aux méthodes attendues.

Magritte n'aurait probablement pas apprécié.

Prenons un exemple.
En Ruby, puts n'exige pas que l'argument soit une String. Il suffit que l'objet réponde à la méthode #to_s. C'est du duck typing pur !

Ce n'est donc pas la classe qui compte, mais l'ensemble des méthodes auxquelles un objet répond.
Autrement dit, son "interface".

Dans un code Ruby classique, ces interfaces sont implicites : on suppose que tel objet a telle méthode, mais rien ne l'indique clairement.
Cela fonctionne très bien... jusqu'au moment où un bug se glisse, parce qu'un objet ne répond pas à la méthode attendue.

Vous voyez déjà où on va en venir : un système de types permet de formaliser ces attentes.
Il ne s'agit plus seulement de supposer qu'un objet a une méthode, mais bien de le déclarer de manière explicite.

Avant de pouvoir formaliser nos interfaces, il nous faut un moyen de les décrire.

Écrire des types avec RBS

Ruby 3.0 a introduit un système de signatures de types appelé RBS (Ruby Signature).
RBS est un langage de description de types qui permet de définir les types des classes, des modules et des méthodes Ruby.

Il permet d'écrire des fichiers de signatures .rbs contenant les définitions des classes, modules, méthodes, variables d'instance, constantes, etc., ainsi que leurs types.
L'idée est de séparer les annotations de type du code Ruby lui-même : au lieu d'ajouter des annotations en ligne dans les fichiers .rb, on écrit des fichiers .rbs à côté.

Un fichier RBS ressemble à du Ruby simplifié, où les corps de méthodes sont remplacés par des signatures de type. Par exemple, si on a la classe Ruby suivante :

class Duck
  def quark
    puts "Quark"
  end
end

On peut écrire la signature correspondante dans un fichier duck.rbs :

class Duck
  def quark: () -> void
end

Bien sûr, qui dit système de types dit aussi vérification de types (type checking).
C'est ici qu'entre en jeu steep.

Un exemple concret avec Steep (et RBS)

Steep est un vérificateur de types (ou type checker), créé par Soutaro Matsumoto, fortement impliqué dans la communauté Ruby 3.
Contrairement à Sorbet, Steep n'introduit aucune annotation dans le code Ruby : il s'appuie uniquement sur les fichiers de signature (RBS) pour analyser le code.

Matz, le créateur de Ruby, en est ravi : son langage reste ainsi préservé !

L'intégration de Steep dans un nouveau projet Ruby est relativement simple.
Steep permet également de s'appuyer sur des définitions de types maintenues par la communauté, comme celles de gem_rbs_collection.

bundle add steep --group=development
bundle exec steep init

La commande steep init génère un fichier de configuration, le Steepfile, à la racine du projet.
Dans ce Steepfile, on spécifie :

• quels répertoires de code analyser (généralement lib/ ou app/ pour un projet Rails) ;

• où se trouvent les signatures (par convention, dans sig/) ;

• quelles librairies standards ou gems inclure (Steep sait charger les RBS de la stdlib et de gem_rbs_collection, par exemple).

L'intégration de Steep dans un projet existant semble plus complexe : il faut en effet définir les signatures pour tous les fichiers avant d'obtenir un système fonctionnel.
De plus, rien ne garantit la présence de types pour les gems utilisées dans ce projet même si avec gem_rbs_collection, les principales gems (comme Rails, par exemple) sont bien typées : liste.

Voici un exemple simplifié de Steepfile :

target :app do
  check 'app'
  signature 'sig'
  # je vous recommande cette option qui permet de relever toutes les incohérences de type
  configure_code_diagnostics(Steep::Diagnostic::Ruby.all_error)
end

Et le code d'une petite app :

class Fish
  def swim
    "Le poisson nage dans l'eau."
  end
end

class Duck
  def speak
    "coin coin"
  end
end

class Cat
  def speak
    "meow"
  end
end

class SpeakService
  def initialize(animals)
    @animals = animals
  end

  def call
    animal = @animals.sample
    puts "The #{animal.class} says: #{animal.speak}"
  end
end

animals = [Duck.new, Cat.new] # le poisson n'est pas dans la liste des animaux

SpeakService.new(animals).call

Cette application fonctionne parfaitement grâce au duck typing !

Mais voilà, des années plus tard, on demande une nouvelle fonctionnalité : ajouter le poisson dans la liste des animaux.
La classe Fish était déjà présente dans la codebase depuis longtemps, et elle est probablement utilisée ailleurs dans le code.
Naturellement, le développeur chargé d’implémenter cette fonctionnalité ne pensera pas forcément à vérifier si Fish possède bien toutes les méthodes nécessaires.

# ...

animals = [Duck.new, Cat.new, Fish.new]

SpeakService.new(animals).call

Et là, c'est la catastrophe : l'app plante aléatoirement en production parce que le poisson n'a pas de méthode speak.
C'est précisément dans ce genre de situation que le typage statique peut nous sauver la mise ! En définissant des contrats clairs pour nos objets, on s'assure qu'ils répondent bien aux méthodes attendues — et on évite ainsi ce type de problème en production.

On aurait pu définir les types ainsi dès le début :

# sig/duck.rbs
class Duck
  include _Speakable
end

# sig/cat.rbs
class Cat
  include _Speakable
end

# sig/fish.rbs
class Fish
  def swim: () -> String
end

# sig/speakable.rbs
interface _Speakable
  def speak: () -> String
end
type speakable_object = _Speakable & Object # une astuce pour que les speakables répondent également à #class

# sig/speak_service.rbs
class SpeakService
  @animals: Array[speakable_object]

  def initialize: (Array[speakable_object] animals) -> void
  def call: () -> void
end

Note : Il est possible de générer des types inférés (avec rbs prototype), par exemple pour générer la signature de la classe Fish.
rbs prototype rb lib/fish.rb > sig/fish.rbs

On lance la commande steep check (ou mieux, la CI s'en occupe) :

Ce n'est pas très clair, mais on comprend à peu près que Fish ne satisfait pas l'interface _Speakable.
On ajuste donc le type.

class Fish
  include _Speakable
  def swim: () -> String
end

On peut vérifier que le type est correct en lançant steep check à nouveau.

Super, les types sont bons ! Mais il reste une erreur sur l'implémentation de la class Fish.
Corrigeons cela en ajoutant une méthode speak à la class Fish.

class Fish
  def swim
    "The fish swims gracefully."
  end

  def speak
    "Blub blub"
  end
end

Et pour se convaincre que tout marche bien : steep check.

Plutôt fastidieux, tous ces allers-retours entre la console et le code.
Heureusement, il est possible d'accéder à ces erreurs directement depuis VSCode, grâce aux extensions steep et ruby-lsp.

Cerise sur le gâteau, on peut également sauter à la définition des types.
Je vous recommande de le configurer dans VS Code, sinon la navigation entre les fichiers est un peu contraignante.

Encore une dernière astuce pour les utilisateurs de Copilot : il faut reconnaître qu'il est franchement aux fraises concernant RBS.
Le langage est probablement trop récent et les modèles manquent sans doute d'exemples.

Cependant, il suffit d'ajouter un petit lien vers la doc de la syntaxe RBS dans votre .copilot-instructions.md, et il devient un expert !

Le lien : https://github.com/ruby/rbs/blob/master/docs/syntax.md

Pour conclure

Le potentiel de Steep et RBS pour l’écosystème Ruby est considérable.
Ces outils permettent aux développeurs de détecter et corriger des erreurs potentielles bien avant la production, renforçant ainsi la qualité et la robustesse de leurs applications.

Cependant, Steep n’est pas encore totalement prêt pour une utilisation à grande échelle :

• La documentation reste incomplète

• Il est difficile de l’adopter progressivement dans un projet existant

• Toutes les fonctionnalités de Ruby ne sont pas encore supportées

• RBS est encore jeune et susceptible d'évoluer

Malgré ces limites, je recommande vivement de l’expérimenter sur un petit projet : l’usage combiné de Steep et RBS est très prometteur.
L’intégration avec ruby-lsp fonctionne remarquablement bien et rend l’expérience particulièrement agréable.

Pour la première fois en 15 ans de développement Ruby, j’ai écrit une API complète sans aucun problème de typage.
Cette API Rack de prise de rendez-vous (plusieurs centaines de lignes de code) a été développée avec :

• des tests unitaires et d’intégration avec rspec

• du typage au runtime avec dry-struct

• et, évidemment, du typage statique avec steep

Cette application, qui n’avait jamais été exécutée en environnement local, a été déployée dans notre environnement de staging sans la moindre erreur.
Il n’y a eu aucun grain de sable dans les rouages : toutes ses composantes se sont intégrées sans problème 🎉.

Chez Syadem, nous utilisons beaucoup l’injection de dépendances.
Or, il est facile de mal injecter ou d’oublier une dépendance.
Cette fois, Steep m’a rattrapé dès le développement, évitant ainsi ces erreurs particulièrement frustrantes.

1. https://2024.stateofjs.com/en-US/usage/#js_ts_balance ↩

— Mathieu, CTO de Syadem

Abonnez-vous maintenant

Bienvenue sur la 36ème édition de Ruby Biscuit.
Vous êtes maintenant 591 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture.

Chez Capsens, j’ai récemment dû créer un dashboard affichant des données agrégées provenant de plusieurs tables : nombre de contributions, montants collectés, statut des projets, etc. La requête SQL sous-jacente était assez lourde et utilisée à plusieurs endroits de l’application. J’en ai donc profité pour tester les vues SQL, une solution qui permet d’améliorer significativement les performances de la requête.

Une vue SQL, c’est un peu comme une « fausse table » : elle ne stocke pas directement des données, mais mémorise une requête SQL complexe pour qu’on puisse l’utiliser comme si c’était une table classique. Super pratique pour éviter les répétitions et simplifier la logique métier dans vos requêtes !

Dans cet article, je vous propose de découvrir ces fameuses vues SQL, comment les utiliser (notamment avec la gem Scenic) et quelles sont leurs limites.

Les deux types de vues SQL :

Il existe deux types de vues SQL : les vues non matérialisées (classiques) et les vues matérialisées. Voyons la différence :

1. Les vues non matérialisées (classiques)

Ce sont juste des requêtes sauvegardées qui sont recalculées chaque fois que vous y accèdez.

Avantages :

• Simplifient ton code Ruby en évitant les requêtes complexes répétitives.

• Centralisent la logique SQL.

Inconvénients :

• Peuvent être lentes car recalculées à chaque consultation.

Quand choisir une vue non matérialisée ? 🚦

Vous pouvez envisager une vue non matérialisée quand :

• Les requêtes SQL sont modérément complexes et fréquemment utilisées.

• Les données doivent toujours être à jour en temps réel (par exemple, si vous affichez un stock de produits en temps réel dans un dashboard).

• Vous voulez centraliser la logique SQL afin de garder un code plus clair, cohérent et maintenable.

Exemple pratique avec Scenic, l’ami des vues SQL dans Rails 🚙

Scenic est une gem Ruby qui simplifie considérablement la gestion des views SQL dans Rails, qu'elles soient matérialisées ou non. Elle permet une intégration propre et lisible dans ton application Rails, avec une gestion native des migrations.

Créer une vue non matérialisée :

rails generate scenic:view active_users

Cette commande génère automatiquement :

• Un fichier SQL : db/views/active_users_v01.sql

• Une migration pour créer ta vue

Exemple du fichier SQL :

SELECT users.*
FROM users
WHERE users.active = true
ORDER BY users.created_at DESC;

Migration Rails générée :

class CreateActiveUsers < ActiveRecord::Migration[7.0]
  def change
    create_view :active_users
  end
end

On peut même associer un model à cette vue ! Et donc y stocker nos méthodes, scopes et même les associations !

class ActiveUser < ApplicationRecord
  self.table_name = 'active_users'

  scope :recent, -> { order(created_at: :desc) }
end

2. Les vues matérialisées

Elles sauvegardent les résultats physiquement dans la base de données et doivent être rafraîchies régulièrement ou sur demande.

Avantages :

• Beaucoup plus rapides, surtout pour les requêtes lourdes.

• Réduisent la charge sur la base de données.

Inconvénients :

• Prennent plus d’espace de stockage.

• Peuvent afficher des données légèrement périmées si elles ne sont pas rafraîchies fréquemment.

Quand choisir une vue matérialisée ? 🚦

Vous pouvez envisager une vue matérialisée quand :

• Vous avez as des requêtes très coûteuses que vous utilisez souvent (rapports, statistiques, etc.).

• Les données n’ont pas besoin d'être mises à jour en temps réel.

Exemple pratique (toujours avec Scenic 🚙) :

Créer une vue matérialisée :

rails generate scenic:view latest_orders --materialized

Cette commande génère automatiquement :

• Un fichier SQL : db/views/latest_orders_v01.sql

• Une migration pour créer ta vue

Exemple du fichier SQL :

SELECT orders.*, users.email AS user_email
FROM orders
JOIN users ON users.id = orders.user_id
ORDER BY orders.created_at DESC
LIMIT 100;

Migration Rails générée :

class CreateLatestOrders < ActiveRecord::Migration[7.0]
  def change
    create_view :latest_orders, materialized: true
  end
end

Modèle associé à cette vue :

class LatestOrder < ApplicationRecord
  self.primary_key = :id
  self.table_name = 'latest_orders'

  belongs_to :user, foreign_key: :user_id

  scope :recent, -> { order(created_at: :desc) }

  def self.refresh
    Scenic.database.refresh_materialized_view(table_name, concurrently: true)
  end
end

Important : si vous voulez rafraîchir la vue sans bloquer ton application (concurrently: true), il faut impérativement ajouter un index unique :

class AddIndexToLatestOrders < ActiveRecord::Migration[7.0]
  def change
    add_index :latest_orders, :id, unique: true
  end
end

Attention ! L’option concurrently: true exige PostgreSQL ≥ 9.4 et un index unique.

Versionner une vue SQL avec Scenic 🔄

Si vous souhaitez faire évoluer ta vue existante, Scenic permet facilement de gérer différentes versions :

rails generate scenic:view latest_orders --materialized --replace

Cette commande génère une nouvelle version du fichier SQL (latest_orders_v02.sql) ainsi qu'une migration adaptée.

Bonus : Tester tes vues SQL 🧪

Voici comment vous pouvez tester facilement votre vue SQL avec RSpec par exemple :

# spec/models/latest_order_spec.rb
require 'rails_helper'

RSpec.describe LatestOrder, type: :model do
  describe '.recent' do
    subject { described_class.recent }

    let(:user) { create(:user) }
    let!(:order1) { create(:order, user: user, created_at: 1.day.ago) }
    let!(:order2) { create(:order, user: user, created_at: 1.hour.ago) }

    it 'returns orders ordered by created_at: :desc' do
      described_class.refresh # obligatoire pour une vue matérialisée
      expect(subject.pluck(:id)).to eq(
        [order2.id, order1.id]
      )
    end
  end
end

Voilà ! Vous connaissez maintenant les bonnes pratiques des vues SQL avec Rails, comment les versionner et même comment les tester facilement. À vous de jouer avec Scenic ! 🚀

— Christopher

Abonnez-vous maintenant

Hello les petits Biscuits !

Bienvenue sur la 35ème édition de Ruby Biscuit.
Vous êtes maintenant 593 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture !

Chez Capsens, nous sommes régulièrement amené à synchroniser des CRM : Hubspot, Salesforce, PipeDrive, Zoho, Brevo, Airtable, etc.

Tous ces CRM implémentent un système de rate limit pour protéger leur infrastructure d'un trop grand nombre de requêtes. Souvent ce dernier se situe aux alentours de 10 requêtes par seconde (Brevo, Hubspot, Airtable).

Lorsqu'il est nécessaire que la synchronisation soit faite en se basant sur des événements, il faut penser à gérer le rate limit pour s'assurer de ne pas le dépasser même en cas de pic de charge.

No no José ! rescue l'erreur 429 ("Too Many Requests") et retry plus tard n'est pas une solution suffisante.

Création du job

Dans la mesure du possible, nous essayons de toujours prioriser l'utilisation de Sidekiq lorsqu'il s'agit d'une API. Pour cet article, nous allons prendre l'exemple d'un CRM quelconque avec lequel nous avons besoin de synchroniser les utilisateurs. La synchronisation devra se faire suite à des événements particuliers :

• inscription

• investissement signé

• investissement payé

• investissement annulé

• ...

Nous allons donc créer un job Sidekiq idempotent qui prendra en paramètre l'ID de l'un de nos utilisateurs en base de données et s'occupera de mettre à jour le contact dans le CRM s'il existe ou de le créer si ce n'est pas le cas avec une liste de champs définie que nous appellerons "dictionnaire".

Afin d'économiser des requêtes au CRM, nous allons implémenter une sorte de clé d'idempotence qui va nous permettre de ne pas effectuer de requête de MAJ ou création du contact au CRM dans le cas où les informations que nous avons envoyé la dernière fois sont identiques. Nous pourrions nous baser sur le timestamp de la resource à synchroniser mais bien souvent les informations à envoyer proviennent de mutliples tables en BDD et la gestion deviendrait bien trop complexe (même en utilisant des touch).

Dans ce contexte, il est donc plus simple et fiable de générer le dictionnaire et créer une signature unique à partir de celui-ci : un digest avec la méthode .hexdigest fournie par Digest::SHA256 et de stocker celle-ci sur l'utilisateur en cas de synchronisation afin de pouvoir la comparer lors du prochain passage.

En informatique, une fonction de hashage ou digest est un résumé court et unique d’un ensemble de données, obtenu en appliquant une fonction de hachage (hash). Il sert souvent à vérifier l’intégrité ou l’authenticité des données, car toute modification du contenu d’origine modifie aussi le digest.

Voici un exemple concret :

Commençons par créer notre Service qui va encapsuler la logique :

Pour le besoin de l'article, nous avons créer un PORO (Pure Old Ruby Object) très simple afin de ne pas avoir de dépendances à des libs mais chez Capsens nous utilisons normalement des DryMonads.

Créons le fichier de tests associé :

Il ne reste plus qu'à créer notre worker Sidekiq qui va appeler notre monad :

et la suite de tests associée :

Cependant la situation actuelle pose un problème, imaginons que la plateforme subisse un pic de traffic accru dû à un passage télévision, nous avons un évènement (entre autres) déclenché par l'inscription d'un utilisateur. Si nous avons 10 000 utilisateur qui s'inscrivent sur une période de 15 minutes, cela ferait donc une moyenne de 11 inscrits par seconde, nous dépasserions le rate limit de notre CRM.

Utilisation de Sidekiq Throttled

Dans ce genre de cas où l'on souhaite limiter la fréquence ou la concurrence d'une tâche au cours du temps, Sidekiq Throttled est généralement notre ami chez Capsens.

C'est une gem Ruby qui ajoute des mécanismes de throttling (limitation) pour Sidekiq, permettant de contrôler simultanément la concurrence des jobs et leur fréquence d’exécution (rate‑limiting).

Elle fournit une configuration simple via sidekiq_throttle, avec des stratégies telles que concurrency (nombre max de jobs concurrents) et threshold (nombre max de jobs dans une période donnée.

Cette dernière est assez simple à configurer, il faut bien sûr ajouter la gem dans le Gemfile puis modifier le fichier de config Sidekiq :

Notez les lignes 18 à 22 où l'on ajoute un Sidekiq::Throttled::Registry , ce dernier nous permet de configurer une limitation pour un ensemble de job plutôt que pour un seul job. C'est très pratique puisqu'il est fort probable que nous implémentions de nouveau job qui vont effectuer des requêtes à notre CRM (supprimer un user, synchroniser d'autres ressources, déclencher des mails). De cette manière, nous nous assurons que tous les jobs qui effectuent des requêtes soient limités de la même manière.

Enfin, notez aussi que même si le rate limit du CRM est de 10 requêtes par seconde, je prend de la marge en limitant à 5 car d'autres parties prenantes effectuent probablement des requêtes au CRM ou parce qu'il est probable que certains de mes futurs jobs effectuent plus d'une requête en s'exécutant.

Maintenant que Sidekiq Throttled est configuré, il ne reste plus qu'à l'implémenter dans notre job :

Désormais vous n'avez plus besoin de vous inquiétez du rate limit, celui-ci est géré à la fois par notre job mais surtout par la limitation fournie par Sidekiq Throttled. Vous pouvez même implémenter une cron pour programmer la synchronisation d'utilisateur en batch sans vous inquiétez de quoi que ce soit. Gardez cependant en tête que cette implémentation permet de préserver le CRM grâce au digest et au throttling mais elle ne préserve pas votre serveur qui lui va travailler dans tous les cas pour générer le digest et le comparer à celui de l'utilisateur afin d'éviter toute requête superflue au CRM.

— Ismaël

Abonnez-vous maintenant

Bienvenue sur la 34ème édition de Ruby Biscuit.
Vous êtes maintenant 585 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture

Active Storage Versus Shrine: le match

Ce mois-ci, nous abordons la gestion des fichiers dans Ruby on Rails, une fonctionnalité indispensable pour que vos utilisateurs puissent téléverser (uploader) des photos, des vidéos ou des documents PDF. Découvrez deux gems populaires utilisées dans la communauté: ActiveStorage et Shrine.

Partie Théorique

Avant de nous lancer, faisons un bref rappel sur ce que font ces gems :

1. Télécharger des fichiers depuis un navigateur vers un service de stockage de fichiers

2. Faire le lien entre ces fichiers et vos instances Active Record

Que ce soit pour Shrine ou Active Storage, l'installation se fait très facilement. Pour les 2 gems, vous trouverez la plupart des réponses à vos questions dans la documentation et en particulier comment les installer.

TL;DR

Les différences entre Shrine et Active Storage sont généralement mineures, mais votre choix dépendra surtout de votre usage :

• Si vous gérez principalement un seul fichier par modèle, Shrine offre une approche plus flexible et explicite

• Si vous devez gérer plusieurs fichiers par modèle ou que vous souhaitez une solution prête à l’emploi et intégrée à Rails, Active Storage sera souvent plus pratique.

Base de données

Pour commencer, je voudrais attaquer la comparaison par le prisme de la base de données. Quelles sont les différences d'architecture et qu'est-ce que ça implique sur les migrations par exemple ?

Avec Shrine, c'est simple, chaque nouveau fichier nécessite une migration sur le modèle.

class AddCoverPictureToProjects < ActiveRecord::Migration
  def change
    add_column :projects, :cover_picture_data, :text
  end
end

Ensuite on va mettre à jour notre modèle

class Project < ApplicationRecord
  include ImageUploader::Attachment(:cover_picture)
end

Pour Active Storage, c'est encore plus simple, on va créer 2 tables au début et puis c'est tout:

• active_storage_blobs

• active_storage_attachments

Ensuite, il suffira de mettre à jour son modèle à chaque fois qu'on veut lier un nouveau fichier à un modèle.

class Project < ApplicationRecord
  has_one_attached :cover_picture
end

Sous cette simplicité apparente se cache une réalité bien plus complexe. Par exemple, quand on appelle la photo dans la vue, voici ce que fait AST sous le capot :

• Il cherche dans la table active_storage_attachments

  • record_type: "Project"

  • record_id: 1

  • name : "cover_picture"

• Ensuite il va chercher dans la table active_storage_blobs

• Enfin il génère l'URL

Vous voyez venir le problème. En appelant une image (ou un document) dans un index, on obtient non pas une N+1 mais bel et bien une 2N + 1 ! Alors que sur Shrine, il n'y a aucune requête SQL supplémentaire.

Pour la petite histoire, j'ai déjà travaillé sur une page d'accueil avec 160 requêtes SQL pour aller récupérer et afficher des images ! Un simple includes a résolu le problème

Avec notre exemple d'aujourd'hui, et une syntaxe plus moderne, ça donnerait ça dans le controller.

@projects = Project.with_attached_cover_picture

Un des avantages avec l'architecture d'AST, c'est qu'on peut facilement ajouter plusieurs fichiers dans notre modèle. Par exemple pour ajouter des photos à un projet :

class Project < ApplicationRecord
  has_many_attached :photos
end

Alors que dans Shrine, ça passe forcément par créer un nouveau modèle.

class Photo < ApplicationRecord
  belongs_to :project
  include ImageUploader::Attachment(:file)
end

class Project < ApplicationRecord
  has_many :photos
end

Les formulaires

Quand un utilisateur a plusieurs photos à ajouter sur un projet dans un formulaire, ce qui est pratique de pouvoir les sélectionner toutes ensemble.

Pour AST, il suffit simplement d'ajouter ça à votre formulaire dans la vue

<%= form.file_field :photos, multiple: true %>

Ensuite dans le controller

class ProjectsController < ApplicationController
  def create
    @project = Project.new(project_params)
    if @project.save
      redirect_to project_path(@project)
    else
      render :new
    end
  end

  private

  def project_params
    params.require(:project).permit(photos: [])
  end
end

Ce fut ma plus grosse frustration en passant de AST à Shrine que de ne pas pouvoir faire ça aussi simplement .

Pour avoir l'équivalent, j'ai dû rajouter quelques lignes de code dans le modèle

class Photo < ApplicationRecord
  belongs_to :project
  include ImageUploader::Attachment(:file)
end

class Project < ApplicationRecord
  has_many :photos
  accepts_nested_attributes_for :photos
  attr_accessor :new_photos

  def new_photos=(files)
    files.each do |file|
      photos.build(file: file)
    end
  end
end

Et maintenant dans ma vue je peux utiliser ça

<%= f.file_field :new_photos, multiple: true %>

Dans le controller il faut juste mettre à jour cette ligne

params.require(:project).permit(new_photos: [])

Mon plus gros bug (à cause du polymorphisme)

La flexibilité qu'amène le polymorphisme sur AST vient avec son lot de piège. Ça a causé une des plus grosses frayeurs de code.

Après avoir changé le nom d'un modèle pour une refacto, je pousse mon code en production, et là surprise, tous les fichiers avaient disparu !

L'explication peut paraitre simple à posteriori mais sur le moment je n'y avais pas pensé. Je vous explique : dans la table active_storage_attachments la colonne record_type qui stocke le nom du modèle doit être mise à jour en même temps que le changement de nom du modèle.

Il n y'a aucune vérification, ni de la base de données, ni de l'application, que le record (combinaison record_id et record_type) existe bel et bien. C'est uniquement sur vos petites épaules que reposent la concordance des noms. Alors que sur Shrine, il n'y a besoin de rien faire.

Tests

Une autre erreur qui m'est arrivé sur AST, c'est d'oublier de supprimer les fichiers après les tests. On se retrouve en local avec une taille projet qui augmente de manière exponentielle et fait saturer le disque dur. En faisant une analyse rapide (avec la commande $ du), je me suis vite rendu compte que mon dossier tmp/storage faisait plusieurs giga octet.

Pourtant, c'est bien marqué dans la documentation !!! (RTFM)

Voici la solution pour Rspec

config.after(:suite) do
  path = "#{Rails.root}/tmp/storage"
  if Dir.exist?(path)
    FileUtils.remove_dir(path)
  end
end

J'ai une petite préférence pour ce que fait Shrine qui permet de mettre les fichiers dans la RAM. C'est plus rapide et plus simple à gérer 😃

Shrine.storages[:store] = Shrine::Storage::Memory.new

Les variantes (AST) ou dérivatives (Shrine)

Ce sont des images modifiées à une taille spécifique pour avoir des images plus légères ou qui s'insèrent facilement dans du code html. Les 2 utilisent image_magick ou vips. Attention pour les 2 gems aussi, la génération des images se fait côté back-end ce qui peut considérablement ralentir votre serveur. L'avantage de AST c'est que si vous définissez vos variantes dans le modèle, elles sont créées dans un background Job.

Conclusion : Comparaison n'est pas raison

Comme souvent en informatique, quand on veut comparer, la réponse va être : "ça dépend du contexte". Pour une application de logistique, qui doit récupérer beaucoup de photos par commande pour vérifier le bon déroulement d'une livraison (mon précédent job), AST sera plus adapté. En revanche, pour une application qui a une image par projet et quelques PDF à sauvegarder, Shrine convient très bien.

Il faut juste avoir conscience qu'avec AST, il faudra faire attention aux N+1 au risque de ralentir votre application. Sur Shrine, il est plus rare de voir des requêtes SQL incontrollées.

Enfin AST étant nativement dans Rails, il est plus rassurant sur le long-terme mais pas forcément plus simple à maintenir.

— Alexandre

Abonnez-vous maintenant

Hello les petits Biscuits !

Bienvenue sur la 33ème édition de Ruby Biscuit.
Vous êtes maintenant 583 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture.

🚀 Construire un Dockerfile Rails de production : mon approche DevOps

Je l’avoue, je suis un peu maniaque des coûts et des temps de build : je déteste qu’une image devienne obèse, ou qu’un build s’éternise… surtout quand je pourrais déjà boire un café ☕️ ! Pour tous mes projets Rails, j’ai mis au point un Dockerfile unique, rapide et léger.

Dans cet article, je vous partage mes astuces (et mes petites manies 😜) : comment j’en suis arrivé là, et surtout pourquoi j’ai fait chaque choix.

💖 Pourquoi j’aime chouchouter mon Dockerfile Rails

Le Dockerfile, c’est souvent le parent pauvre du projet, mais c’est le cœur de votre environnement d’exécution. Le négliger, c’est un peu comme oublier d’ajouter du sel dans une recette : ça peut vite tourner au désastre ! Une mauvaise config peut entraîner :

• 📦 Des images trop lourdes (bonjour les téléchargements interminables)

• 🐌 Des builds qui traînent (adieu la productivité)

• 🔓 Des secrets exposés (le cauchemar)

• 🚨 Des failles de sécurité (panique à bord)

J’ai donc décidé de rendre ce fichier maintenable, sécurisé et réutilisable sur tous mes projets.

🔧 Un Dockerfile tout-terrain pour tous les projets

Pour éviter de dupliquer un Dockerfile par projet, j’ai introduit plusieurs ARG :

Cette paramétrisation permet de :

1. Choisir dynamiquement la version de Ruby et de Debian ;

2. Installer, si nécessaire, des paquets spécifiques à un projet ;

3. Adapter l’environnement Rails et Node sans modifier le Dockerfile.

Par exemple, je peux lancer :

et obtenir une image taillée sur mesure.

🏗️ Image de base et dépendances communes

Dans l’étape base, j’installe les dépendances système partagées par tous les projets :

Pourquoi ces paquets ?

• libjemalloc2 améliore la gestion mémoire de Ruby ;

• libpq5 est nécessaire au client PostgreSQL ;

• shared-mime-info, file et less sont utiles pour les scripts et diagnostics.

Grâce aux --mount=type=cache, les index APT sont mis en cache, accélérant les builds suivants.

Configuration Ruby et mise à jour de Rubygems

Avant tout build applicatif, je définis des variables d’environnement et je mets à jour Rubygems pour bénéficier des dernières améliorations :

Astuce : Prévoir toujours un RAILS_ENV explicite garantit des builds reproductibles.

🛠️ Étape 1 : production-builder

L’étape production-builder regroupe l’installation des outils et la compilation :

1. Outils de compilation

Ces paquets sont essentiels à la compilation :

• build-essential : compilateurs C/C++ pour les extensions Ruby ;

• libssl-dev, libyaml-dev, libz-dev… : dépendances fréquentes des gems natives ;

• git : pour les gems hébergées sur Git.

2. Node.js et Yarn

Cette étape prépare la compilation des assets front-end avec Webpacker ou Sprockets.

3. Gems avec Bundler

Pour profiter du cache Docker et éviter de réinstaller les gems inutilement :

Docker invalide cette couche seulement si Gemfile ou Gemfile.lock changent, ce qui rend les rebuilds beaucoup plus rapides.

4. Faux secrets et assets

Le .env factice permet de satisfaire Rails sans exposer de vrais secrets ; qui sont injectés au runtime.

🎯 Étape 2 : production

L’étape finale construit l’image de prod en mode minimal :

Node.js facultatif

Je peux choisir de conserver Node.js pour debug ou m’en passer pour alléger l’image.

Copie des artefacts

Seuls les gems et les assets précompilés sont repris, tout le reste reste dans l’étape builder.

Sécurité et droits

Exécuter l’app en non-root limite les risques en cas de faille.

Exposition et lancement

Cette dernière ligne reste simple et claire pour démarrer le serveur Rails.

✂️ Un .dockerignore chirurgical

Chaque ligne compte pour alléger le contexte :

# dossiers systèmes et dev
.git/
.bundle/
node_modules/

# logs et tmp
log/
tmp/

# secrets et configs locales
.env*
config/master.key

# assets compilés
public/assets
public/packs

Ce .dockerignore empêche de copier tout ce qui n’est pas nécessaire au build.

📦 Un système de CI centralisé

J’ai centralisé Dockerfile, .dockerignore, database.yml.template et .env factice dans un repo CI. Ce dossier est copié dans chaque projet pour garantir une cohérence et faciliter les mises à jour.

Dockerfile complet

Voir le Dockerfile complet

Pour aller plus loin

Docker

• Documentation officielle :

https://docs.docker.com/

• Guide multi-stage : https://docs.docker.com/build/building/multi-stage/

Sécurité

• Bonnes pratiques : https://docs.docker.com/develop/security-best-practices/

• Trivy : https://github.com/aquasecurity/trivy

Performance

• BuildKit : https://docs.docker.com/build/buildkit/

Ce Dockerfile m’a permis de gagner en rapidité, en légèreté et en sécurité. J’espère qu’il vous servira autant qu’il m’accompagne au quotidien !

— Quentin

Abonnez-vous maintenant

Bienvenue sur la 32ème édition de Ruby Biscuit.
Vous êtes maintenant 581 abonnés 🥳

Ruby Biscuit, c’est aussi votre meilleur allié pour trouver un job !

🎯 En ce moment, nous recherchons 5 profils Ruby confirmé·es ou intermédiaires pour des postes au sein de notre réseau.
Écrivez-nous ou postulez directement sur le site !

Bonne lecture ❤️

Crée des partials robustes et maintenables avec les strict locals

Lorsque nos vues deviennent complexes ou grandes, ou que des parties doivent être réutilisées ailleurs dans notre application, un découpage en partial s'impose.

Nous avons souvent besoin d'accéder à des variables dans ces partials et il n'est pas rare d'utiliser des variables d'instance qui viennent de notre action de controller car elles sont faciles d'accès partout dans nos vues et dans nos partials, peu importe le niveau d'imbrication. Wait ... est ce que pratique rime avec maintenable ? 🤔

L'aspect négatif de cette méthode est qu'elle rend nos partials très dépendantes de nos actions de controller : si une autre vue souhaite utiliser notre partial, l'action de controller qui lui est associée devra implémenter cette variable d'instance, sans que ça ait vraiment forcément du sens dans le contexte de cette action.
Pire, si ce controller implémente déjà une variable d'instance du même nom, on pourrait se retrouver à utiliser dans notre partial une variable erronée dans ce contexte sans le savoir.

Chez Capsens nous avons pris la décision d'interdire l'utilisation des variables d'instance dans nos partials pour privilégier l'utilisation systématique des locals.

Cela a l'avantage de faciliter la lecture des partials, on sait exactement d'où viennent nos variables et nos partials deviennent auto-suffisantes : il suffit de passer les bonnes variables en paramètres pour l'utiliser : moins de magie, moins d'indirection et des tests plus faciles à écrire.

Afin de rendre nos partials robustes et de s'assurer qu'on n'oublie pas de leur passer telle ou telle variable, Rails nous met à disposition un outil très pratique : les strict locals.

Cette notation permet de déclarer quelles sont les variables que notre partial accepte et lesquelles sont obligatoires ou optionnelles. En cas de variable manquante, ou en trop, notre partial levera une erreur automatiquement. Elle prend la forme d'un "commentaire magique", avec une syntaxe spécifique dans lequel nous allons lister les paramètres de notre partial.

Exemple :

Dans cet exemple notre partial prend deux valeurs : une subscription, obligatoire (la partial va donc lever une exception si jamais on ne lui passe pas cette valeur) et une autre display_rate qui est passée optionnellement et sera par default à true.

N'oubliez pas d'aller jeter un coup d'oeil à la doc !

BONUS - Tests des partials

Nous avons pris l'habitude de tester unitairement nos partials afin de s'assurer que nos vues ne génèrent pas d'erreurs, ce qui évite des tests de requêtes lourds, compliqués, avec des tonnes de contexte selon les conditions d'affichage des éléments dans la vue associée. L'utilisation des locals et des strict locals par rapport aux variables d'instances nous permet de simplifier le setup de nos tests : on peut passer simplement nos variables en paramètre de notre partial plutôt que de devoir tricher pour créer des variables d'instances et un faux controller.

Avec RSpec, ajouter ces lignes dans le fichier spec/rails_helper.rb permettra d'accéder aux méthodes de helper de Devise pour, par exemple, avoir un utilisateur connecté dans notre test :

config.include Devise::Test::ControllerHelpers, type: :view
config.include Devise::Test::IntegrationHelpers, type: :view

Exemple d'un test unitaire de partial :

— Eliot

Abonnez-vous maintenant

Bienvenue sur la 31ème édition de Ruby Biscuit.
Vous êtes maintenant 575 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture.

ActiveRecord : Éviter les pièges de performance en production

Récemment, en ajoutant une fonctionnalité de génération d’échéancier à l’une de nos applications Rails, je me suis retrouvée face à un problème de performance.

Notre système fonctionne ainsi : un projet est publié, des investisseurs y investissent et en retour, ils perçoivent un remboursement avec un taux d’intérêt. Du crowdfunding globalement. Pour aider les administrateurs à organiser ces remboursements, nous devons générer un échéancier pour chaque investisseur, souvent étalé sur plusieurs mois, voire plusieurs années.

Pour vous donner une idée, dans mon cas, il s'agissait d’environ 5 000 investisseurs, chacun ayant un échéancier sur 30 mois, soit un total de 150 000 échéances à calculer et générer.

J’ai donc codé ma fonctionnalité tranquillement, testé son bon fonctionnement, puis ouvert ma pull request (merge request sur GitLab) en attendant sa relecture.

Tout allait bien jusqu'à ce que mon relecteur pose la question qui fâche : "Tu as testé ton script avec des volumes similaires à ceux de la production ?"

La réponse était évidente : "Non."

Je m’y mets donc… et là, catastrophe. Mon service met plusieurs minutes à s’exécuter. C’est interminable. Pourtant, j’avais fait attention à la performance… du moins c’est ce que je croyais.

Il faut donc remettre les mains dans le cambouis. C’est parti !

Si vous voulez suivre en détail la suite de l’article, vous pouvez cloner ce repo :
👉 https://github.com/CapSens/ruby-biscuit-active-record-performance.git
Il contient une version ultra simplifiée de notre problématique du jour.

Notre domaine étant le crowdfunding, certaines logiques métier peuvent vous être inconnues. Voici quelques éléments essentiels pour ne pas vous perdre :

• Un échéancier doit pouvoir être généré ou regénéré à tout moment. Avant d’en générer un nouveau, il est donc essentiel de supprimer l’ancien.

• Un projet est géré par un porteur de projet, qui doit rembourser ses investisseurs en répartissant une somme précise incluant des intérêts, selon un nombre d’échéances défini contractuellement. Ces échéances sont appelées borrower_terms.

• Les échéances perçues par les investisseurs (les remboursements qu’ils reçoivent) sont quant à elles appelées lender_terms.

Mise en place d'un script de benchmark

Un benchmark est un test qui permet de mesurer la rapidité et l'efficacité de notre code.
Il existe différents outils pour cela, plus ou moins puissants selon les besoins. L’important est de choisir celui qui s’adapte le mieux à votre cas d’usage.

Ma démarche à été la suivante :

1. Mettre en place un script de benchmark simple, que je pourrais relancer après chaque modification du code.

2. Tester différentes optimisations pour gagner en performance et identifier des quick wins.

Pour notre script de benchmark, nous avons décidé d’implémenter deux méthodes :

• benchmark_memory : utilise la gem benchmark_memory pour évaluer la quantité de mémoire utilisée par notre code et détecter les fuites mémoire (ce qui n’est pas libéré).

• benchmark_time : une méthode custom qui mesure le temps d’exécution du code.

Ces deux méthodes prennent en paramètre : le nombre de souscriptions et le nombre d’échéances souhaitées

À chaque appel de ces méthodes :

1. Un jeu de données est généré.

2. Deux générateurs d’échéanciers sont lancés :

• L’un avec la version initiale du code

• L’autre avec la version améliorée
  Cela permet d’observer les gains de performance sans modifier le code originel.

1. Tout cela s’exécute dans une transaction Active Record, ce qui permet de revenir facilement à l’état initial après chaque test.

Dans le repo, vous trouverez le script de benchmark ici : app/scripts/test_script.rb.

Et voici le code de génération de l’échéancier :

Spoiler alert : J'ai réussi à diviser le temps d'exécution par ~ 6 et la mémoire utilisée par ~ 3.

Ci dessous quelques exemples de benchmark fait durant l'optimisation :

Ici on peut voir qu'entre le code originel et la version améliorée on a diminué presque par 6 le temps en millisecondes

Ici dans le premier exemple on divise par 3 la taille de la mémoire et le nombre d'objets en mémoire

Pas mal non ? Allons voir ce que j'ai modifié !

Les améliorations

1. destroy_all vs delete_all

2. includes or not includes

3. find_each vs each

4. activerecord-import

Mesurer le temps d’exécution global, c’est bien, mais comprendre quels morceaux du code sont les plus lents, c’est mieux. C’est en analysant l’exécution étape par étape que l’on identifie où les améliorations sont nécessaires.

Une bonne pratique à adopter est d'ajouter des messages de debug aux différentes étapes de votre script. Cela permet d’observer quelles parties prennent le plus de temps et ou des optimisations sont possibles.

1️⃣ destroy_all vs delete_all

J’ai commencé par ajouter un message de debug qui m’indiquait à chaque fois qu’une échéance était générée. À ma grande surprise, j’ai attendu plusieurs minutes avant que la toute première échéance apparaisse.

Le problème : un destroy_all trop gourmand

En y regardant de plus près, j’ai compris pourquoi. Avant de générer les nouvelles échéances, mon script supprimait les anciennes avec destroy_all.

Supprimer 150 000 échéances avec destroy_all déclenchait les callbacks Rails sur chaque suppression. Même si chaque suppression ne prenait que 0.001 seconde, cela représentait déjà 150 secondes d’attente avant même de commencer à générer de nouvelles échéances 😮‍💨.

En remplaçant destroy_all par delete_all, j’ai drastiquement réduit le nombre de requêtes SQL. On est passé de 150 000 requêtes à une seule.

Attention : destroy_all reste utile lorsque vous avez besoin de déclencher des callbacks de suppression, notamment pour gérer les objets associés. Ce n’est donc pas une méthode à systématiquement remplacer par delete_all, mais dans mon cas, l’optimisation était pertinente.

2️⃣ includes or not includes

Lorsque l'on manipule un grand nombre de données, il est essentiel de bien gérer le chargement des ressources. Sinon, on risque de multiplier inutilement les requêtes SQL, ce qui peut rapidement dégrader les performances.

Le problème : N+1

Prenons un extrait de la version non optimisée du code :

Dans un premier temps, on récupère les souscriptions avec find_each, qui charge les données par batchs de 1 000, ce qui est déjà une bonne pratique.

Mais ensuite, pour chaque souscription, on récupère la dernière échéance via subscription.lender_terms.last, ce qui génère une requête supplémentaire par souscription.

Si on a 5 000 souscriptions, on se retrouve donc avec :

• 5 requêtes pour charger les souscriptions (find_each traite 1 000 éléments à la fois)

• 5 000 requêtes pour récupérer les échéances

Soit un total de 5005 requêtes SQL...

Comment arranger ça ? En utilisant includes(:lender_terms), on demande à Active Record de récupérer les échéances en une seule requête par batch :

Nous avons maintenant : 5 requêtes avec le find_each (5*1000) + 1 requêtes par batch pour récupérer les échéances, soit 10 requêtes SQL contre 10 000 dans la version initiale 😵.

3️⃣ find_each vs each

Reprenons notre exemple project.subscriptions.find_each, si on remplace le find_each par un each on se retrouve à charger en mémoire un array avec 5 000 objets ruby, ça fait beaucoup pas vrai ?

En utilisant find_each, par défaut on aura des batchs de 1 000 donc on chargera en mémoire que 1 000 objets ruby. Ce qui est déjà correcte, surtout dans notre cas ou ca ne nécessitera que 5 requêtes au total.

C'est génial, on l'utilise partout alors ! ...Pas vraiment si on regarde le bout de code suivant

borrower_terms = project.borrower_terms

project.subscriptions.find_each do |subscription|
  previous_investor_term = subscription.lender_terms.last
  current_investor_term = nil
  
  borrower_terms.find_each do |borrower_term| # <--
  end
end

Vous ne le voyez peut-être pas mais c'est contre productif à la ligne borrower_terms.find_each. Pourquoi ?

La variable borrower_terms est déjà récupéré plus haut et elle sera la même pour l'itération de chaque souscription, le problème c'est que le find_each déclenche une nouvelle requête SQL à chaque fois alors que la donnée n'a pas changé. On fait donc plusieurs fois 5*1000 requêtes, au lieu de le faire 1 seul fois.
La solution ici est simple, utilisé .each qui nous permet d'itérer sans faire de requête supplémentaire car les ressources sont déjà chargées.

A savoir : find_each permet de faire des batch mais supprime également toute notion d'ordre dans la requête initiale. Il est important de l'avoir en tête et de ne pas l'utiliser si l'ordre de vos resources est important.

4️⃣ activerecord-import

activerecord-import est une superbe gem qui nous permet de créer plusieurs ressources en une seule requête. Je vous invite à y jeter un oeil si vous manipulez beaucoup de données ou que vous faîtes beaucoup de migrations.

Pas besoin d'explication très détaillée, avec plus de 150 000 échéances à créer, ça ne peut qu'améliorer la performance de notre code. Si on revient en arrière sur le premier point concernant la suppression des échéances c'est un peu le même principe, pourquoi s'embêter à faire autant de requêtes qu'il y a de ressources alors qu'on pourrait le faire en faire une seule.

Pour conclure j'ajouterai à tout cela, qu'il est important, dans cette méthode de test avec un benchmark, de ne pas sous estimer le temps d'affichage des logs. Pour se rapprocher du temps réel d'exécution il faudra penser à retirer les logs, vous pouvez le faire facilement avec la commande ActiveRecord::Base.logger = nil

La performance dans une application est un sujet passionnant et très très vaste. Bien qu'il soit toujours important de bien connaitre son outil de travail pour éviter certains écueils, il faut aussi garder en tête que plus on avance dans l'optimisation plus le rapport temps passé / gain est faible. Heureusement pour nous, la communauté Ruby est très active sur le sujet et beaucoup de recherches sont menées, notamment chez Shopify pour améliorer les performances de notre langage préféré.

Internet regorge d'articles sur ces travaux alors si vous avez les reins solides n'hésitez pas à vous plonger dans le sujet.

Une liste d'outils interéssants pour optimiser vos applications

ActiveRecord :

• Importer des records en masse : https://github.com/zdennis/activerecord-import

• Traquer les N+1 : https://github.com/flyerhzm/bullet

Mémoire / CPU :

• Profiler ruby : https://github.com/tmm1/stackprof

• Similaire au module Benchmark mais pour la mémoire : https://github.com/michaelherold/benchmark-memory

• Un benchmark mémoire un peu plus complet fait par thoughtbot : https://github.com/SamSaffron/memory_profiler

RSpec :

• Une boite à outil pour améliorer la performance de votre suite de test : https://github.com/test-prof/test-prof

— David & Quentin

Abonnez-vous maintenant

• Remplir un template PDF avec Pdftk. par Stanislas

Temps de lecture : 5 minutes

Hello les petits Biscuits !

Bienvenue sur la 30ème édition de Ruby Biscuit.
Vous êtes maintenant 555 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture.

Remplir un template PDF avec Pdftk

Bonjour à tous ! Ce mois-ci nous allons voir comment remplir dynamiquement un template PDF, c'est parti 👇🏻

Mise en place

Nous allons avoir besoin d'installer pdftk sur notre machine, sur lequel se base la gem pdf_forms

Étapes :
1. Installation de pdftk et pdf_forms
2. Configuration à mettre en place
3. Comprendre comment assigner les variables sur le PDF
4. Création d'un dictionary pour assigner les variables
5. Génération du PDF

Pré-requis : Doc PDF avec variables assignées.

1) Installation de pdftk et pdf_forms

→ Installer pdftk sur sa machine avec

brew install pdftk-java 

Pourquoi suffixer avec java ? Parce homebrew nous le conseille sur Mac à partir du M1 .
⚠️ Par défaut homebrew va vouloir faire un update général, pour éviter cela et se prémunir de conflits potentiels on va pouvoir préfixer avec HOMEBREW_NO_AUTO_UPDATE=1.

HOMEBREW_NO_AUTO_UPDATE=1 brew install pdftk-java

→ Mettre pdf-forms dans le Gemfile et bundle install

2) Configuration à mettre en place

À mettre dans application.rb 👇

Se créer un petit poro dans le dossier qui vous arrange à l'interieur de app/ pour qu'il soit autoloadé.

3) Comprendre comment assigner les variables sur le PDF

Maintenant qu'on a fait la mise en place et qu'on a un PDF vide, comment va-t-on pouvoir dire qu'on veut telle donnée à tel endroit ?
Tout se passe dans la configuration du PDF, et plus précisément dans la partie "Préparer un formulaire" sur Adobe Acrobat (ou bien sejda, voir fin de l'article).

Une fois que vous avez créé votre champ, accédez aux "propriétés" de ce dernier :

→ Pour les champs string pas trop de soucis de ce côté là, vous pouvez les appeler comme vous voulez. Par exemple profile_type, civility, toto, etc. Attention tout de même à ne pas avoir de doublon.

→ En revanche pour les checkboxes soyez attentifs. Même si l'on peut également les appeler comme on le souhaite, first_checkbox par exemple, vous allez devoir renseigner une "valeur d'exportation". Cette dernière déterminera si la checkbox est cochée ou non. Dans l'exemple suivant, j'ai choisi 1. En d'autres termes, une autre valeur que 1 n'aura aucun effet.

4) Création d'un dictionary pour assigner les variables

Maintenant qu'on a configuré les champs dans le PDF il va falloir les remplir, et pour cela on va se créer un dictionary nous permettre d'extraire la logique de mise en forme des données dans un objet dont c'est la seule responsabilité et qui sera très facilement testable. Celui-ci va nous renvoyer un hash que l'on pourra utiliser pour la génération du document.

Si l'on reprend les champs précédemment cités cela donnera :

Maintenant si l'on est pas certain du nom des champs ou bien que l'on souhaite vérifier leurs noms dans notre document, nous pouvons exécuter les commandes suivantes :

pdftk = PdfForms.new
pdftk.get_field_names(mon_document.download)

Ce qui va nous retourner un array avec le nom des champs présents dans le PDF :

["profile_type",
"civility",
"toto",
"first_checkbox"]

Pratique pour éviter les confusions !

5) Génération du PDF

Tout est en place, il ne reste plus qu'à générer notre document et l'enregistrer en db. Vous pouvez vous créer un service comme suit :

Plus que le fichier de test :

NB : La version originale de pdftk est obsolète sur Linux en raison de sa dépendance à GCJ et a été retirée de plusieurs dépôts. En alternative, pdftk-java, une réécriture en Java, est activement maintenu et compatible avec les distributions modernes.

Tada 🚀

Quelques resources :

• La gem pdf-forms où l'on peut trouver quelques calls à faire à pdftk

• Sejda pour créer/nommer des champs et se passer de Adobe Acrobat

— Stanislas

Abonnez-vous maintenant

• Encapsule tes dictionnaires dans des classes dédiées par Mélanie

Temps de lecture : 5 minutes

Hello les petits Biscuits ! Bonne et heureuse année à tous, prenez soins de vous ❤️

Bienvenue sur la 29ème édition de Ruby Biscuit.
Vous êtes maintenant 546 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture

Dans les applications Rails, il est courant de travailler avec des API : que ça soit pour créer des documents à signer, intégrer un prestataire de paiement, envoyer des informations à un site vitrine ou encore utiliser l’API de Google Maps pour la géolocalisation. Dans la plupart des cas, cela implique de transmettre à ces API des hashes (dictionnaires) de paramètres, plus ou moins longs. Chaque valeur de ces dictionnaires doit impérativement respecter le format attendu par l’API, sans quoi une erreur est vite arrivée.

Chez Capsens, nous avons récemment décidé d’améliorer notre manière de gérer ces dictionnaires pour réduire des erreurs fréquentes de formatage. Comment ? En les encapsulants dans des fichiers dédiés.

Cette pratique, en apparence anodine, rend le code plus lisible, plus réutilisable et surtout plus facilement testable. Dans cet article, je vais vous présenter notre méthode et tenter de vous convaincre de l’adopter vous aussi.

Pour illustrer mon propos, nous allons prendre comme exemple un service qui crée un document au format PDF à l'aide de l'API Doclift. Ce document correspond à un contrat généré après une souscription financière à un projet.

Doclift est une API qui permet la génération dynamique de vos documents PDF.
Vous créez vos templates de document directement sur l'app Doclift (entièrement codée en RoR), vous y ajoutez des variables et via l'API vous envoyez le contenu des variables. Pratique !
Vous trouverez son fonctionnement détaillé ici : https://www.doclift.io/how-it-works

Voici la V1 de notre service :

Ici on constate donc qu'il y a beaucoup de paramètre à envoyer pour la génération de notre document. Le format des variables étant pré-défini dans Doclift lors de la création du template, il est essentiel de le respecter à la lettre avant d'envoyer le dictionnaire. On retrouve certaines méthodes spécifiques au formatage des données, qui ne sont utiles que dans ce contexte.

Les tests associés :

Inconvénient d'avoir son dictionnaire directement dans son service :

• Trop de responsabilités pour le service

• On ne teste pas les dictionnaires alors qu'ils sont la cause de bcp d'erreurs. Erreurs qui peuvent être critiques en fonction du moment où se fait la génération du document. Au milieu d'un flow de souscription dans notre cas.

• Dictionnaire non réutilisable

Bien sûr, nous pourrions améliorer nos tests et tester davantage notre dictionnaire ici, mais cela alourdirait les tests de notre service, tout comme la création du hash alourdit déjà ce dernier. Cela ne résoudrait pas non plus le problème de réutilisabilité. Si demain nous devons gérer un second template de contrat avec seulement quelques variantes mais des paramètres globalement similaires, il serait bien plus intéressant de ne pas tout réécrire.

Alors comment avons nous amélioré notre code

Vous remarquerez en particulier :

Doclift::SubscriptionDictionary.new(
  @subscription
).to_h

Les tests :

• Ceux du service pourraient rester les mêmes

• Test du dictionnaire :

Il est maintenant facile de tester son dictionnaire et en prime, avec différents contextes.

Nous avons donc une solution :

• Facilement testable et maintenable

• Qui allége le service

• Réutilisable

Bien sûr si vous utilisez une gem comme Draper pour avoir des décorateurs sur votre application, il est tout à fait possible de créer des décorateurs plutôt que des dictionnaires !

Au mois prochain !

— Mélanie

Abonnez-vous maintenant

• Sécuriser vos Webhooks en Ruby on Rails par François

Temps de lecture : 5 minutes

Hello les petits Biscuits !

Bienvenue sur la 28ème édition de Ruby Biscuit.
Vous êtes maintenant 540 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture.

Sécuriser vos Webhooks en Ruby on Rails

Dans le développement d’applications web, les webhooks sont un mécanisme courant pour recevoir des notifications externes sur des événements spécifiques. Par exemple, une application peut recevoir un webhook de service tiers de signature électronique pour l'informer lorsqu'un document a été signé. Cependant, sans mesures de sécurité appropriées, les webhooks peuvent être exploités, exposant ainsi votre application à des risques de sécurité.

Dans cet article, nous allons passer en revue un certain nombre de techniques disponibles pour sécuriser les webhooks. Ensuite nous verrons une mise en pratique avec les webhooks de Dropbox Sign. Nous verrons comment mettre en pratique trois techniques pour sécuriser les webhooks dans une application Ruby on Rails : la vérification des adresses IP, l'utilisation d'un secret partagé (HMAC), et les strong parameters pour filtrer les données entrantes. Ces pratiques garantiront que seules les requêtes authentiques et sécurisées seront traitées par votre application. Enfin nous verrons comment tester ces 3 mesures de sécurité avec Rspec.

Comprendre les Méthodes de Sécurisation des Webhooks

Avant d'entrer dans l'implémentation, voyons quelques méthodes disponibles pour la sécurisation des webhooks :

1. Appeler le service : Même lorsqu'ils sont sécurisés, les webhooks ne sont pas adaptés pour transmettre des informations sensibles. Une façon de sécurisé l’utilisation des webhooks est de seulement les utiliser pour être informé d’un événement pour une ressource et ensuite d’appeler le service externe via une API pour connaitre l’état de cette ressource. (voir exemple dans la section suivante)

2. Vérification des IPs : Restreindre l’accès aux webhooks uniquement à certaines adresses IP. Cela permet de s’assurer que les requêtes proviennent d’une source autorisée, comme un service tiers de confiance (Dropbox Sign dans cet exemple).

3. Vérification du Secret (HMAC) : Un secret partagé ou un HMAC (Hash-based Message Authentication Code) permet de valider que la requête n'a pas été altérée et qu'elle provient bien de la source prévue.

4. Strong Parameters : Filtrer les données entrantes pour s'assurer qu'elles correspondent aux attentes et éviter les injections de données non désirées ou malveillantes.

5. Timestamp pour prévenir les attaques par rejeu (Replay Attacks) : En incluant un timestamp dans la requête du webhook, vous pouvez vérifier que l'événement n'est pas ancien et qu'il n'a pas été rejoué. Si l'horodatage dépasse un certain seuil (par exemple, 5 minutes), la requête est rejetée.

6. Chiffrement des données envoyées : Chiffrer les données transmises via les webhooks, notamment lorsqu'elles contiennent des informations sensibles, garantit que seules les parties autorisées peuvent les lire. Cela peut être réalisé avec HTTPS ou en chiffrant manuellement les payloads.

7. Utiliser HTTPS et la vérification SSL : GitHub vérifie les certificats SSL lors de la transmission des webhooks et il est fortement recommandé de laisser cette vérification activée. Cela attenue les risques d’écoutes clandestines (eavesdropping) et les attaques de l'intercepteur (man-in-the-middle MITM), où un attaquant peut intercepter et modifier la donnée avant de la transmettre.

Voir plus sur Introduction to Webhook Security - Docs

Appeler le service tiers après reception du webhook

Comme mentionné dans la section précédente, les webhooks ne sont pas la méthode de communication la plus sécurisée et les données transférées sont sensibles (exemple les données bancaires). Par conséquent, certains fournisseurs de service comme Swan n'utilisent pas de webhooks pour envoyer des informations sensibles qui nécessitent une authentification pour être affichées. Le webhook inclut uniquement une notification indiquant qu'un événement s'est produit et une id de ressource afin de pouvoir la retrouver. Il faut ensuite utiliser l'API pour obtenir les informations. On peut visualiser cela dans le graphique ci dessous :

Sécurisation grâce aux fonctionnalités fournies

Tous les fournisseurs de service tiers mettant à disposition des webhooks ne fournissent pas de mesures de sécurité, mais beaucoup le font. Les contrôles de sécurité mis à disposition par le fournisseur de webhook permettent de valider l'authenticité des échanges et à empêcher leur falsification. Cependant, la plupart des fournisseurs n'exigent pas de la part des applications consommants leur service qu'elles utilisent la sécurité qu'ils fournissent. C'est aux développeurs de lire la documentation du webhook du fournisseur pour savoir quelles options sont disponibles, les comprendre, puis les mettre en œuvre.

Implémentation en Ruby on Rails

Dans cet exemple, nous allons implémenter un contrôleur webhook pour Dropbox Sign, avec les trois couches de sécurité suivantes : la vérification d'IP, le HMAC, et les strong parameters.

Code du Contrôleur

Explications :

• Vérification d'IP : Le filtre verify_ip_address s'assure que la requête provient bien des IPs autorisées définies dans la constante ALLOWED_IPS.

• Vérification HMAC : La méthode verify_secret utilise un secret (clé API) pour vérifier la signature de la requête. Cela garantit que la requête provient bien de Dropbox Sign et qu'elle n'a pas été modifiée.

• Strong Parameters : Nous utilisons webhook_payload pour filtrer et limiter les données aux seuls paramètres attendus, ce qui empêche l'injection de données non désirées.

Voir la documentation de Dropbox Sign pour plus de détail : Events Walkthrough | Dropbox Sign for Developers

Rspec tests

Il est important de tester les vérifications, notamment pour s’assurer que seules les IPs autorisées et les requêtes valides sont acceptées.

Voici un exemple de tests :

Ce que fait ce test :

• Il simule lorsque tout va bien.

• Il simule des requêtes venant d’une IP autorisée et d’une IP non autorisée.

  • Si l'IP est autorisée, le webhook est traité avec succès.

  • Si l'IP n'est pas autorisée, une réponse "not found" est renvoyée, empêchant la requête d'être traitée.

• Il simule des requêtes avec un secret valide et invalide.

  • Si le secret est valide, le webhook est traité avec succès.

  • Si le secret n’est pas valide, une réponse "not found" est renvoyée, empêchant la requête d'être traitée.

Conclusion

La sécurisation des webhooks est cruciale pour protéger vos applications contre les attaques et les abus. En combinant la vérification des adresses IP, l’utilisation de secrets partagés et le filtrage des paramètres, vous vous assurez que seules les requêtes authentiques et sûres sont traitées par votre application.

Repo associé : https://github.com/francoisedumas/basic_app_esbuild

Pour aller plus loin

Vous trouverez sur ma chaine YouTube de nombreux sujet technique que j’explore et explique. Kokori Kodo

— François

Abonnez-vous maintenant

Temps de lecture : 10 minutes

Hello les petits Biscuits !

Bienvenue sur la 27ème édition de Ruby Biscuit.
Vous êtes maintenant 540 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture.

En finir avec les PDF infectés au js

En mai 2024, une faille majeure a été découverte dans la bibliothèque PDF.js, utilisée par de très nombreux iframes pour permettre la visualisation et la prévisualisation de fichiers PDF dans une page web. Cette faille permettait d'injecter du code javascript dans une FontMatrix qui n'était pas censée en accueillir et ensuite de s'assurer de son exécution lors de l'interprétation du fichier par un lecteur. Ce type de faille est une porte d'entrée pour des attaques de type XSS, bien qu'elle n'en permette pas une seule.

Le cross-site scripting (abrégé XSS) est un type de faille de sécurité des sites web permettant d'injecter du contenu dans une page, provoquant ainsi des actions sur les navigateurs web visitant la page. Il est par exemple possible de voler la session en récupérant les cookies.

Les CVE concernant l'exécution arbitraire de javascript via des fichiers PDF dans des pages web sont nombreuses, et il y a aussi des multitudes de formes d'exécution de javascript volontairement permises par le format PDF. Celles-ci sont généralement bloquées par le navigateur mais il y a des exceptions.

Aujourd'hui nous allons apprendre comment nous en débarrasser. Après avoir lu cet article, vous saurez comment implémenter un sanitizer en ruby qui vous protège durablement de la CVE de mai 2024 et d'autres types d'injections au js. Vous serez également solidement armés pour réagir efficacement et rapidement à la prochaine CVE de ce style et capables de :

• Comprendre sur quoi se base la CVE

• Adapter votre sanitizer

• Créer vos propres fichiers infectés pour le tester

I - Introduction, les actions javascripts et les fontmatrix

Entre la création du format PDF en 1992 où seulement 12 types d'objets étaient autorisés et sa dernière mise à jour en 2009 qui en compte plus de 70, de nombreuses fonctionnalités ont été ajoutées. Et avec elles beaucoup de vulnérabilités.

Une partie non négligeable de ces vulnérabilités et dangers ont été introduits en même temps que les scripts javascript.

La plupart de ces scripts ne seront pas malveillants : widgets, liens dynamiques, actions sympathiques et variées au clic d'un bouton ou dès l'ouverture d'un fichier : le javascript a été admis pour améliorer et enrichir l'expérience utilisateur.

D'autres le seront probablement, c'est le cas des PDF écrits pour contenir du javascript de sorte à exploiter la CVE de mai 2024.

Je vais vous montrer comment écrire un script ruby qui sanitise les fichiers PDF pour leur enlever les éléments javascripts légitimes ou illégitimes.

Mais avant il y a quelques pré-requis nécessaires :

• Une compréhension globale du format PDF

• Une connaissance des emplacements et des formes que le javascript peut occuper dans un PDF

• Des fichiers PDF "infectés" pour tester nos scripts

Nous allons obtenir tout cela en créant ensemble et de toute pièce un fichier PDF infecté au javascript (inoffensif bien sûr) !

II - Créons un fichier corrompu

Nous allons dans cette partie écrire à la main, de A à Z, un fichier PDF. Le javascript pouvant se trouver dans de très nombreuses sections d'un PDF, je montrerai pour chaque section dans un premier temps la version saine et dépourvue de javascript, puis la version infectée.

Cependant, il est impossible de présenter l'ensemble des objets liés à des actions javascript en un seul article tant ceux-ci sont nombreux. La norme PDF 32000-1:2008 ou PDF 1.7 décrit de façon exhaustive ces objets si cela vous intéresse (page 422).

Pour chaque section, les fragments de code PDF en version saine présentés dans l'article, une fois assemblés, formeront un fichier PDF valide et non corrompu.
Si vous souhaitez créer vous même votre PDF infecté, il faudra adapter les offsets de la table des références (je vous expliquerai tout ça en détail le moment venu).

Speedrun

Si vous souhaitez speedrun la lecture de cet article, et n'en sortir qu'un script de sanitisation et des fichiers de payload pour le tester, vous pouvez sauter directement à la partie suivante où vous trouverez les deux.

Je ne vous conseille cependant de ne pas faire cela, l'intérêt de coder votre propre sanitizer étant de pouvoir l'adapter rapidement à toute nouvelle CVE permettant une exécution de javascript dans un pdf via des moyens détournés. Cela peut être plus compliqué sans une vague compréhension du format PDF et des objets javascript.

Le format général

Une façon de se représenter un fichier PDF serait de dire qu'il contient globalement 3 sections :

• L'en-tête qui annonce le format et la version (très court)

• Le corps qui abrite le contenu (ou charge utile) du PDF

• La fin de fichier qui regroupe la table des références, le trailer et le marqueur de fin de fichier : des éléments utiles à la bonne interprétation du document mais n'ajoutant généralement pas de contenu à proprement parler.

Nous allons remplir ce guide progressivement dans cette partie.

En tête

Un PDF commence directement par une section d'en-tête. L'en tête précise le format : PDF, la version : 1.3 et quelques caractères binaires pour annoncer que le fichier sera encodé en binaire.

Le fichier que nous allons écrire étant constitué de très peu d'objets, il sera valide et lisible avec n'importe quelle version et par n'importe quel lecteur PDF (si vous souhaitez écrire la version contenant du JS à la main, utilisez une version récente comme la 1.8 ou au minimum postérieure à 1.2).

Corps

Le corps regroupe tout le contenu d'un PDF : c'est une suite d'objets indirects. Ces objets peuvent être de types variés. Cependant certains types d'objets sont nécessaires à l'élaboration d'un PDF valide minimal.

Afin de comprendre le format du corps, quelques définitions s'imposent à ce sujet.

Le corps d'un fichier PDF est constitué d'une série d'objets indirects.

Les objets indirects sont composés d'un numéro d'objet (un identifiant), d'un numéro de génération (qui commence à 0 et s'incrémente si l'objet est dupliqué).

Puis obj [Contenu objet] endobj

1 0 obj
[CONTENT]
endobj

Un objet indirect peut être vu comme un contenant pour un ou plusieurs objet directs.

Les objets directs (ou objets) sont des structures de données basiques, qui peuvent souvent être directement traduites vers un type d'objet primitif en Ruby (tableaux, booléens, dictionnaires, chaîne de caractères, entiers, objet nul, ...).

La plupart des objets directs de ce document seront des dictionnaires.

Les dictionnaires sont des séquences de clés et valeurs entourés de << et >>. Chaque clés type sa valeur. Les clés sont toutes des names objects (au format /Name).

Les éléments simples que vous voyez à l'écran lorsque vous visualisez un PDF sont en fait constitués d'une multitudes d'objets qui sont imbriqués et/ou qui se référencent. Les dictionnaires par exemple sont souvent imbriqués à de nombreux niveaux.

Les objets indirects peuvent se référencer les uns les autres. Une référence est un type d'objet. Elle se compose des numéros d'objet et de génération de l'objet référencé suivis du caractère R.

Ainsi, un objet indirect défini de la façon suivante :

2 0 obj
[Contenu]
endobj

Pourra être référencé (avant ou après sa définition dans le document) par : 2 0 R.

Ne pas confondre objet direct et indirect

Dans un fichier PDF, les objets peuvent être représentés de manière directe ou indirecte. Un objet direct est intégré directement dans le document et est souvent trouvé comme valeur d'une clé dans un dictionnaire ou comme élément dans un tableau. Il est accessible immédiatement sans référence externe. En revanche, un objet indirect est référencé par un identifiant unique (composé d'un numéro d'objet et d'un numéro de génération), ce qui permet au lecteur PDF de retrouver sa valeur en consultant d’autres parties du fichier. Les objets indirects facilitent la réutilisation et l'organisation des données dans un PDF en permettant de pointer vers un objet unique depuis plusieurs endroits.

Passons à la pratique.

Le catalogue

Le premier objet indirect contenu dans le corps est ici le catalogue. C'est l'objet racine du document. C'est un dictionnaire qui référence l'objet liste des pages.

Il peut contenir d'autres types d'objets. Il peut notamment contenir des actions javascript légitimes ou non.

Les actions javascript

Une action javascript est en réalité une série d'objets et peut prendre de multiples formes. Ici, action javascript désigne les différents types d'objets qui référencent une exécution de javascript (côté navigateur) conforme au format PDF et à son contenu. Ils correspondent à des utilisations non détournées de différents types d'objets. Ces objets peuvent être imbriqués.

Elles peuvent être contenues dans un dictionnaire de type /Action ou /OpenAction. La première est généralement attachée à une interaction de l'utilisateur comme un clic, la seconde s'exécute dès l'ouverture du document (pratique).

Ces objets peuvent aussi être définis indépendamment, les deux premiers sont alors simplement des dictionnaires qui référencent les suivants. L'objet /JS est contenu dans un objet indirect et contient directement le code à exécuter.

Retour au catalogue

Le catalogue peut contenir des actions javascript.

Ou les référencer.

Liste des pages

La liste des pages est un dictionnaire qui liste les références des pages (ses enfants) dans un tableau. Ici le tableau contient une seule entrée puisque le PDF que l'on écrit contient une seule page.

Les tableaux sont ouverts et fermés par [ et ], les différentes entrées sont séparées par des espaces.

S'il y avait plusieurs pages, les références seraient séparées par un simple espace : [ 3 0 R 4 0 R ]...

Page 1

Chaque page définit dans un dictionnaire Page les ressources nécessaires à son affichage : une police. La page référence aussi son contenu : ici l'objet identifié par la référence 4 0 R.

• On peut y trouver des scripts ou des références à des scripts

• Les polices peuvent être entièrement définies dans le PDF ou utiliser celles installées sur les ordinateurs (dans le premier cas, cela pourrait causer des problèmes d'affichage selon le lecteur)

Le stream

Dans un fichier PDF, un stream est un type d’objet utilisé pour stocker des données volumineuses ou complexes, comme des images, du texte formaté ou des informations graphiques. Il est délimité par les mots clés stream et endstream. Les streams permettent d’inclure des contenus plus longs ou compressés dans le fichier PDF, rendant ce type de données plus facile à gérer et à stocker de manière efficace.

Un stream commence généralement par une déclaration de ses propriétés dans un dictionnaire précédant le mot stream. Ce dictionnaire contient des informations essentielles, comme la longueur du stream (en octets) et, le cas échéant, la méthode de compression utilisée (par exemple, FlateDecode pour une compression zlib/deflate).

Voici un exemple simplifié d’un objet stream dans un fichier PDF (ici, aucune compression n'a été appliquée) :

Cet objet stream contient simplement du texte formaté à afficher.

Le texte est inséré entre les tags BT (Begin Text) et ET (End Text).

La première lignée définit la police : F1 (définie plus tôt) et la taille : 100 grâce au tag Tf (text font).

La deuxième ligne indique les coordonnées grâce au tag de dessin Td (text draw).

La dernière affiche le texte grâce à l'opérateur Tj (show text).

Les FontMatrix

Une FontMatrix est une matrice de transformation associée aux polices de caractères. Elle permet d'appliquer des transformations géométriques comme la mise à l'échelle, la rotation, la translation ou le cisaillement aux glyphes (caractères) d'une police avant leur affichage. Dans une FontMatrix, six valeurs numériques définissent ces transformations, offrant un contrôle précis sur la présentation des textes.

Dans un fichier PDF, les FontMatrix sont généralement des entrées dans un dictionnaire qui définit une police et un formatage.

La CVE-2024-4367

La faille découverte en mai 2024 exploite une faiblesse dans la gestion des FontMatrix par la bibliothèque PDF.js, permettant l’injection et l'exécution de code JavaScript malveillant.

Les valeurs contenues dans la FontMatrix étaient interprétées par PDF.js et évaluées pour afficher correctement la police. Si elles étaient remplacées par du code javascript, celui-ci était donc évalué.

Ce cas de figure sera traité de façon légèrement différente par le sanitizer : contrairement aux autres objets évoqués permettant des actions javascript, les FontMatrix n'ont en théorie, aucun rapport avec l'exécution de javascript. Elles peuvent donc être présentes dans de nombreux PDF sans qu'il ne soit pertinent de les supprimer.

Au lieu de retirer toutes les FontMatrix, nous testerons qu'elles sont au format correct (6 chiffres). Si elles ne le sont pas (si elles contiennent des caractères non numériques), elles seront retirées.

Fin de fichier

Le reste d'un fichier PDF contient des objets qui sont utiles pour permettre la lecture du fichier.

La table des références

La table des références (ou xref table) dans un fichier PDF est une structure qui répertorie les positions de tous les objets indirects en indiquant leurs décalages en octets par rapport au début du fichier.

La table des références est annoncée par le mot xref et doit commencer par une ligne contenant deux nombres séparés par un espace, représentant le numéro d'objet du premier objet de cette sous-section et le nombre d'entrées dans la sous-section.

xref 
0 5 

Ici, la table des références contient les objets indirects de 0 à 4.

Chaque ligne de la table des références fait 20 octets et contient :

nnnnnnnnnn ggggg m eol

• nnnnnnnnnn : l'offset en octet sur 10 chiffres de l'objet à partir du début du fichier

• ggggg : le numéro de génération de l'objet sur 5 chiffres (à 65535 pour un objet libre)

• m : un mot clé sur une lettre qui indique si l'objet est libre (f) ou utilisé (n)

• eol : un marqueur de fin de ligne sur deux caractères

La table des références permet au lecteur PDF de localiser rapidement chaque objet sans devoir analyser l'ensemble du fichier. Placée vers la fin du document, cette table est essentielle pour que le lecteur puisse interpréter le document correctement et efficacement.

La table commence par un objet nul. Cet objet commence à l'offset 0. Comme il n'est pas utilisé son numéro de génération est à 65535 par convention, et le mot clé est f.

Les objets suivants sont les différents objets définis plus tôt, on ajoute pour chacun leur offset en octet depuis le début du fichier, leur numéro de génération, puis un n pour annoncé qu'ils sont utilisés.

Attention : Bien qu'elle s'appelle table des références, c'est techniquement une table de pointeurs.

Dans un PDF, une référence et un pointeur jouent des rôles distincts pour organiser et structurer les données.

Une référence est utilisée pour relier les objets entre eux au sein du fichier. Par exemple, un objet peut contenir une référence vers un autre objet indirect (identifié par un numéro d'objet et de génération, suivi de "R"), indiquant que son contenu est à rechercher ailleurs dans le document.

Un pointeur, quant à lui, indique une position précise dans le fichier PDF. Il est souvent employé dans la table des références (ou xref table) et dans le trailer pour diriger le lecteur PDF vers le début de chaque objet indirect. Le pointeur aide le lecteur à retrouver rapidement les éléments sans avoir à parcourir tout le fichier.

Ainsi, la référence est une relation logique entre objets, tandis que le pointeur est une adresse précise dans le fichier.

Le trailer

Les PDF doivent être lus en partant de la fin, c'est notamment le cas parce que le trailer, dernière section d'un fichier PDF, est le point d'entrée pour les lecteurs : il permet de trouver rapidement la table des références et l'emplacement de certains objets spéciaux.

Le trailer est un dictionnaire qui contient au moins deux entrées indispensables :

• Une paire clé valeur /Root qui référence le catalogue.

• Une paire clé valeur /Size qui annonce la taille de la table des références.

Enfin, le trailer contient également un pointeur vers la table des référence : le point d'entrée pour le lecteur qui interprétera le fichier.

Le marqueur de fin de fichier

La dernière ligne du fichier doit contenir uniquement le marqueur de fin de fichier, %%EOF.

Résumons

Et voilà ! Nous avons désormais construit un PDF infecté au js de toute pièce. Mais ça fait beaucoup d'informations. Voici quelques schémas pour résumer les différents objets et les relations qui les lient.

Les références

Les pointeurs

D'autres objets divers

Si de nombreux types d'objets peuvent être le point d'entrée à l'exécution de javascript, la plupart auront besoin d'un objet /JS qui contient le code. Supprimer cet objet s'il est présent permet donc de neutraliser de nombreux chemins d'exécution.

III - Maintenant, on nettoie tout ça

Notre PDF corrompu est prêt à servir de payload pour tester l'algorithme de nettoyage que nous allons coder.
L'algorithme est plutôt simple à réaliser : on fait la liste des types d'objets qui peuvent contenir du JS susceptible d'être exécuté et on les "désactive".

Donc, si on résume, deux cas de figure ont été abordés dans cet article :

• Ceux qui sont normalement désactivés 99% du temps et qui sont conformes à ce qui est prévu par le format : ceux-ci reposent généralement sur un objet /JS. Supprimer la paire clé-valeur /JS - code

• Les FontMatrix, dont on peut vérifier simplement qu'elles sont au format attendu et les supprimer si ce n'est pas le cas

HexaPDF

J'ai fait le choix de la gem HexaPDF pour coder mon sanitizer. Celle-ci est très bien codée et très utile pour les manipulations de PDF.

J'utilise pour l'exemple la gem Stringio pour gérer la sortie du document traité en mémoire plutôt que d'écrire directement sur le disque. C'est un choix qui m'a permis de simplifier l'intégration de ce sanitizer à mon application Rails.

Je présente ici un squelette simple pour le sanitizer, comme un script ruby indépendant afin de présenter la logique. Je vous laisse décider des détails d'implémentation.

On commence par importer les dépendances :

require 'hexapdf'
require 'stringio'

Puis, on crée une classe qui servira de sanitizer, avec un peu de setup :

class Sanitizer
  attr_reader :file_to_sanitize, :result

  def initialize(file_to_sanitize)
    @file_to_sanitize = file_to_sanitize
    @result = { success: false, edited: false }
  end

  def call
    open_pdf
    sanitize_file
    save_pdf
    @result
  end

    def open_pdf
    unless @file_to_sanitize && File.exist?(@file_to_sanitize) && File.extname(@file_to_sanitize).downcase == '.pdf'
      print("File #{@file_to_sanitize} not found or not a PDF file\n")
      exit(1)
    end

    @file = HexaPDF::Document.open(@file_to_sanitize)
  end

Parcours du fichier

Il est ensuite possible de parcourir l'ensemble des objets contenus dans le PDF très simplement :

On vérifie si les objets rencontrés sont des dictionnaires, si c'est le cas, on appelle une fonction de nettoyage sur l'objet. HexaPDF gère de nombreux aspects de la logique de suppression : création d'un fichier en mémoire sans les objets supprimés, ajustement des offsets dans la table des références, etc. Ce qui permet de supprimer simplement des objets sans rentre le PDF invalide.

  def sanitize_file
    @file.each do |obj|
      next unless obj.value.is_a?(Hash)

      sanitize_object(obj)
    end
  end

La méthode sanitize_object(obj) délègue ensuite la responsabilité d'analyser et nettoyer les objets dictionnaires rencontrés aux méthodes appropriées :

• Les FontMatrix corrompues (remove_font_matrix)

• Les actions javascript, notamment l'objet /JS (remove_js)

On écrira une dernière fonction qui parcourt récursivement les éventuels dictionnaires imbriqués pour s'assurer de nettoyer l'ensemble du document.

  def sanitize_object(obj)
    remove_font_matrix(obj) if obj[:Type] == :Font && (obj.key?(:FontMatrix) && corrupt_font_matrix?(obj))

    remove_js(obj) if obj.key?(:JS)

    clean_nested_dictionary(obj) if obj.is_a?(HexaPDF::Dictionary)
  end

Les actions javascript

  def remove_js(obj)
    print("Removing JS from object #{obj.oid}\n")
    obj.delete(:JS)
    @result[:edited] = true
  end

Les FontMatrix

Une première méthode cherche la façon dont la FontMatrix est insérée dans le dictionnaire de police (celle ci peut varier) puis on vérifie que la matrice ne contient que des valeurs numériques.

  def corrupt_font_matrix?(obj)
    font_matrix = obj[:FontMatrix].respond_to?(:value) ?              obj[:FontMatrix].value : obj[:FontMatrix]
    font_matrix.any? { |n| !n.is_a?(Numeric) }
  end

Si ce n'est pas le cas, on supprime complètement la matrice : puisqu'elle est corrompue, elle n'est pas utile.

  def remove_font_matrix(obj)
    print("Removing corrupt FontMatrix from object #{obj.oid}\n")
    obj.delete(:FontMatrix)
    @result[:edited] = true
  end

Le cas des dictionnaires imbriqués

Afin de nettoyer le code javascript même s'il est contenu dans une série de dictionnaires imbriqués, on écrit simplement une méthode récursive qui vérifie et nettoie les entrées d'un dictionnaires, et le contenu des entrées qui sont des tableaux.

  def clean_nested_dictionary(dictionary)
    return unless dictionary.is_a?(HexaPDF::Dictionary)

    dictionary.each do |key, value|
      if value.is_a?(HexaPDF::Dictionary)
        sanitize_object(value)
        clean_nested_dictionary(value)
      end

      next unless value.is_a?(Array)

      value.each do |v|
        next unless v.is_a?(HexaPDF::Dictionary)

        sanitize_object(v)
        clean_nested_dictionary(v)
      end
    end
  end

Le nettoyage est terminé !

On enregistre le fichier PDF s'il a été modifié, et on met à jour le hash de résultat du sanitizer.

  def save_pdf
    return unless @result[:edited]

    @io = StringIO.new
    @file.write(@io, optimize: false, validate: false)
    @io.rewind
    @result[:output_data] = @io.string
    @result[:success] = true
  end

Je fais un petit main rapidement pour tester le sanitizer :

if __FILE__ == $0
  if ARGV.empty?
    puts 'Please provide the path to a PDF file to sanitize.'
    exit
  end

  file_to_sanitize = ARGV[0]
  sanitize = Sanitizer.new(file_to_sanitize)
  result = sanitize.call

  if result[:success]
    File.open('sanitized_output.pdf', 'wb') { |f| f.write(result[:output_data]) }
    puts "PDF sanitized successfully and saved as 'sanitized_output.pdf'."
  else
    puts 'PDF sanitization failed.'
  end
end

Je lance ça sur un fichier PDF contenant des actions JS et une FontMatrix corrompue :

Et j'obtiens un fichier PDF qui ne contient plus aucun code javascript. Il existe des reliques, comme cet objet indirect Javascript :

9 0 obj
<<
/S/JavaScript
>>
endobj

Ce pendant, la section /JS avec le code associé à l'action JavaScript ont été supprimés, il n'y a donc plus aucun risque d'exécution de code.

Quelques remarques pour la fin

L'exemple que nous avons vu ici est un cas de PDF extrêmement simple. En réalité un simple Hello World généré par un générateur de PDF moyen serait bien plus lourd et constitué de nombreux objets plus complexes.

Par exemple, nous avons fait appel dans notre document à la police Arial installée sur votre ordinateur, mais un Hello World en Arial généré par google docs contiendrait l'intégralité de la police afin de s'assurer que le PDF soit visualisé de façon exacte par n'importe quel ordinateur, même s'il n'a pas cette police installée.

Le format PDF permet d’inclure de nombreuses formes d'actions JavaScript qui n'ont pu être présentées en totalité dans cet article. Il est important de noter que ces actions sont destinées à être interprétées par des lecteurs PDF spécialisés (comme Adobe Acrobat).

Les navigateurs web ne permettent généralement pas cette exécution, et l’interprétation est propre à chaque bibliothèque ou lecteur de PDF.

Liens utiles :

A propos de cet article :

• Le fichier minimal décrit dans cet article (sans js)

• Un fichier avec différents types d'action JS

• La POC de la CVE-2024-4367

• Et le code du sanitizer présenté dans cet article

Le format PDF :

• Let's write a pdf file : vulgarisation du format et de la syntaxe

• Norme 32000-1:2008 ou PDF 1.7 : explications détaillées sur le format PDF

Les exploitations de PDF :

• PDF files payload for pentesting : github avec différents fichiers PDF contenant du JS

• Portable Data exFiltration: XSS for PDFs : aller plus loin sur les attaques XSS et les PDF

• JS2PDFInjector

— Ines

Abonnez-vous maintenant

Au programme aujourd’hui :

• Protéger sans ralentir : tests optimisés avec Rack Attack par Ines

Temps de lecture : 10 minutes

Hello les petits Biscuits !

Bienvenue sur la 26ème édition de Ruby Biscuit.
Vous êtes maintenant 530 abonnés 🥳

Maintenant Ruby biscuit, c’est aussi votre meilleur allié pour recruter des devs Ruby !
Si vous n’avez pas encore rejoint le club, RDV sur https://recrutement.rubybiscuit.fr

Bonne lecture.

Protéger sans ralentir : tests optimisés avec Rack Attack

En tant que développeuse junior, lorsque j'ai tenté d'implémenter Rack Attack et surtout d'accélérer les tests que j'avais rédigés, l'expérience s'est révélée être un véritable casse-tête. Il y a très peu d'informations là-dessus sur internet et j'ai eu du mal à comprendre certains aspects de l'utilisation du cache de Rack Attack afin de pouvoir les mocker*. J'ai souhaité écrire un article sur le sujet pour vous épargner ces difficultés.

* Mock : En programmation orientée objet, les mocks sont des objets simulés qui reproduisent le comportement d'objets réels de manière contrôlée.

Rack Attack est une gem en Ruby qui implémente un middleware. Elle est particulièrement utile pour protéger les applications Ruby en Rails contre certaines attaques :

• par force brute : un attaquant essaye chaque combinaison possible de mot de passe pour un nom d'utilisateur/email, afin d'obtenir l'accès au service ciblé

• par bourrage d'identifiants (credential stuffing) : un attaquant tente une liste d'identifiants compromis récupérés dans des fuites de données, toujours dans l'objectif d'accéder au service ciblé

• par déni de service (Denial of Service) : un attaquant submerge votre service de requêtes jusqu'à ce que le traffic normal ne puisse être traité

Rack Attack se positionne entre votre application et les requêtes HTTP brutes que celles-ci reçoit, et vous permet d'intercepter celles ci : définir des règles de limitation de requêtes, bloquer les IP suspectes ou abusives et même mettre en place des listes blanches et noires. Rack Attack utilise moins de ressources par requête que votre application Rails, ce qui lui permet de ne pas ralentir les requêtes tout en les filtrant.

Aujourd'hui, nous allons voir :

• Un exemple simple de configuration Rack Attack

• Des tests basiques

• Une explication détaillée des interactions de Rack Attack avec le cache

• Des tests ultra-rapides, indépendants du nombre de requêtes autorisées

• Quelques recommendations pour utiliser Rack Attack

Configuration

Pour simplifier cette configuration, nous allons nous concentrer sur les envois de formulaires publics, c'est-à-dire les requêtes POST où un formulaire est généralement envoyé au serveur.

En effet, c'est en spammant le formulaire de login qu'une attaque par force brute peut être menée, et lors d'une attaque de type Denial of Service (DoS), les requêtes POST sont bien plus coûteuses pour le serveur que les requêtes GET, puisqu'il ne s'agit pas seulement de répondre à une demande, mais aussi de traiter les données reçues.

Installation

Ajouter la gem au Gemfile :

gem 'rack-attack'

Ensuite, exécutez la commande suivante pour installer la gem :

bundle install 

Configuration Rack Attack

Si vous n'avez jamais utilisé Rack Attack, pas de panique, on va détailler tout ça.

Créer la classe Rack::Attack

Paramètres

On définit tout d'abord les paramètres du filtre dans l'initializer :

Note : Dans cet article, j'utilise une limite de tentatives très basse pour simplifier les explications. Je recommande d'utiliser en réalité une limite bien moins sévère : 50 tentatives en une minute par exemple.

Sélecteurs

Les sélecteurs sont les caractéristiques des requêtes qui passeront par les filtres. Ils déterminent quelles seront les requêtes concernées par les limitations.

Puis on choisit le ou les sélecteurs. Nous sélectionnons donc la méthode : POST et le chemin : PUBLIC_PATHS_POST, on obtient le sélecteur suivant :

Dans cet exemple, seules les requêtes vers l'un des chemins spécifiés et avec pour méthode post, seront limitées. Les requêtes avec pour méthode get ne seront pas affectées.

Note : il existe de nombreux autres sélecteurs possibles (params, url, user-agent, content_length, body...). Vous trouverez ici la liste des clés utilisables pour request.env et ici leur implémentation (et traduction) par Rack.

Filtre

Avec notre nom, nos paramètres et nos sélecteurs nous pouvons construire le filtre par lequel passeront les requêtes choisies.

Blocklist

Lorsque, pour une ip donnée, l’utilisateur atteint MAX_ATTEMPTS_POST requêtes POST durant OBSERVATION_TIME_POST sur l’ensemble (ou une partie) des PUBLICS_PATH_POST, nous souhaitons qu’il soit bloqué de l’ensemble de l’application : nous plaçons donc notre filtre dans une blocklist inconditionnelle.

Note : Il est possible de n’appliquer le blocage qu’à certains types de requêtes de même que pour les filtres.

Un second filtre pour l'exemple

Pour l’exemple et afin de mieux comprendre le fonctionnement de Rack Attack, nous allons définir un autre filtre sur les requêtes GET sur des chemins publics, défini avant le filtre sur les requêtes post dans notre fichier de configuration (cela aura son importance pour la suite).

Réponse personnalisée

Il est possible de définir une réponse HTTP personnalisée pour les requêtes bloquées, la réponse par défaut étant un 403 (Forbidden) pour les blocklists et 429 (Too many requests) pour les throttles.

J'ai fait le choix dans cette configuration d'un code 503 sans corps pour une raison très simple. Le code 503 est habituellement utilisé par une plateforme pour signifier qu'elle est hors-service et ne peut traiter les requêtes entrantes. C'est une façon de simuler un crash suite à une éventuelle attaque par DoS (un peu comme un opossum qui feindrait la mort pour décourager un prédateur peu minutieux).

Tester la configuration

Maintenant qu'on a correctement configuré Rack Attack, testons ce que l'on a implémenté.

L'idée est de vérifier que les IPs sont bien bloquées après un certain nombre de tentatives, puis que le déblocage se fait correctement une fois le délai de bannissement écoulé.

Nous commencerons par des tests simples et fonctionnels mais lents, puis nous verrons comment les améliorer.

Tests triviaux

Première approche des tests de Rack Attack

Limites des tests triviaux

De tels tests fonctionnent, et permettent effectivement de vérifier que la configuration Rack Attack a été correctement réalisée. Cependant, leur durée dépend du nombre de requêtes autorisées par chaque filtre, puisqu’il faut en simuler autant pour observer le blocage.

Ces tests peuvent donc s’avérer très longs lorsque l’on souhaite utiliser des périodes d’observation plus longues avec des nombres de tentatives maximales pour un filtre élevées ou lorsqu’il y a plusieurs filtres à tester (jusqu’à 15 secondes pour un seul filtre testé avec 100 requêtes GET autorisées sur un ordinateur relativement puissant).

De la même façon, le succès du test dépend dans ce contexte de la vitesse d'exécution de l'environnement où le test est lancé. Si les requêtes mettent trop de temps à s'exécuter on peut ne jamais atteindre la limite durant le temps d'observation. Et si l'on souhaite également autoriser beaucoup de requêtes sur une très courte période, le blocage est pratiquement impossible à tester : il est très difficile d'envoyer un nombre élevé de requêtes en une période très courte avec les helper fournis par RSpec (ou rack-test).

Nous allons donc voir comment les appels au cache sont faits afin de mocker le nombre de requêtes qui nous intéresse (voire directement un blocage) et rendre ainsi le temps de test indépendant du nombre de requêtes autorisées pour chaque filtre.

Comprendre les appels au cache

RackAttack utilise le cache pour stocker des informations sur les requêtes effectuées par les utilisateurs ou les adresses IP afin d'optimiser les performances et d'appliquer des règles de limitation en coûtant peu de ressources.

Afin d'illustrer les appels au cache effectués par Rack Attack pour surveiller le traffic et bloquer les clients abusifs, nous allons jouer un petit scénario. Mais d'abord, un petit point sur les clés du cache.

Génération des clés du cache

Nous observerons dans notre scénario deux types de clés utilisées par Rack Attack pour communiquer avec le cache.

Clés de blocklist

Les clés des blocklists permettent de vérifier (dans notre cas) qu'une ip donnée a été marquée dans le cache comme appartenant à une blocklist.

Clés de compteur (ou clés de filtre)

Les clés de compteur permettent à Rack Attack de garder la trace du nombre de requêtes concernées par le filtre (et donc sélectionnées par le discriminant) réalisées pour une ip durant le temps d'observation.

Elle contient notamment une clé timestamp. Cette clé est calculée au moment où la première requête pour une ip durant la période d'observation est reçue :

clé timestamp = date et heure de la première requête / durée d'observation

La clé timestamp est donc propre à une ip, et à une période d'observation.

Comprendre les interactions avec le cache

Imaginons un petit scénario pour illustrer les appels au cache de Rack Attack.

Un jeune bot naïf et malveillant accède à votre plateforme dans l'intention de récupérer les identifiants de vos utilisateurs grâce à une attaque par force brute. Il arrive sur le chemin "/sign_in", et en moins d'une seconde, tente 11 combinaisons différentes nom d'utilisateur - mot de passe. Au bout de la 11 ème, une page d'erreur s'affiche.

Le jeune bot est stoppé net : la plateforme semble hors-service. Il rentre bredouille. Pourtant, il y a actuellement de nombreux humains disciplinés qui y surfent en toute tranquillité. Comment est-ce possible ? Rembobinons.

Première requête

Lorsque la première requête est reçue par l'application (et interceptée par Rack Attack), Rack Attack consulte tout d'abord les blocklists. Il les consulte dans l'ordre dans lequel elles ont été définies dans l'initializer.

Souvenez vous : on avait défini dans notre configuration un filtre et une blocklist sur public-get avant celui sur public-post (dans l'initializer). Étants définis avant, ils seront consultés en premier, tout au long de ce scénario.

Les blocklists sont consultées et aucune entrée ne correspond à l'ip de notre bot malveillant, la requête sera donc autorisée, mais il faut quand même suivre le nombre de requêtes.

Après avoir consulté les blocklists, Rack Attack identifie que la requête correspond à celles filtrées par le filtre public-post : il consulte donc le compteur associé.

Cette fois encore, aucune entrée ne correspond à notre bot malveillant. Rack Attack génère donc un timestamp, puis ajoute une entrée qui contient l'ip du bot malveillant (1.2.3.4) :

[READ] Key: rack::attack:allow2ban:ban:public-get:1.2.3.4, Result: nil
[READ] Key: rack::attack:allow2ban:ban:public-post:1.2.3.4, Result: nil
[READ] Key: rack::attack:14376799:allow2ban:count:public-post:1.2.3.4, Result: nil
[WRITE] Key: rack::attack:14376799:allow2ban:count:public-post:1.2.3.4, Value: 1, Expires in: 19 seconds

La clé timestamp sera ensuite conservée et utilisée pour suivre les requêtes de cette ip (qui satisfont le discriminant du filtre), jusqu’à la fin du temps d’observation.

Requêtes suivantes n < 10

Notre jeune bot naïf et malveillant ne le sait pas, mais il est désormais fiché. Il continue, en toute innocence, à spammer notre page de login, et rien ne semble sortir de l'ordinaire. Pourtant il est surveillé de près.

Lorsqu'une nouvelle requête est envoyée, Rack Attack commence également par consulter toutes les blocklists concernées, celles-ci ne contiennent toujours pas l'ip correspondante : le jeune bot peut continuer à spammer le login (pour le moment).

À chacune de ses tentatives, après la lecture des blocklists, le compteur de public-post est incrémenté, mais il n'atteint pas encore la valeur seuil attendue.

[READ] Key: rack::attack:14376799:allow2ban:count:public-post:1.2.3.4, Result: 2
[WRITE] Key: rack::attack:14376799:allow2ban:count:public-post:1.2.3.4, Value: 3, Expires in: 92 seconds

10ème requête : la dernière pour notre jeune bot

Lors de la dixième tentative, les blocklists sont à nouveaux consultées et ne contiennent toujours pas l'ip recherchée et laissent donc passer de nouveau cette requête. Finiront t'elles par servir à quelque chose ?

Puis, le compteur de public-post est consulté : il renvoie 9. Il est alors incrémenté pour atteindre 10 : le maximum autorisé. C'est à ce moment que les choses tournent mal pour le jeune bot malveillant. Un nouvel appel en écriture au cache est effectué : cette fois-ci, non pas au compteur, mais bien à la blocklist de public-post. Une entrée contenant son ip y est inscrite et sera conservée durant le BAN_TIME défini plus haut.

[WRITE] Key: rack::attack:allow2ban:ban:public-post:1.2.3.4, Value: 1, Expires in: 600 seconds

Note : Les clés de compteur servent exclusivement à suivre le nombre de requêtes durant une période d'observation. La lecture d'une valeur supérieure ou égale à n-1 déclenchera l'écriture d'un bannissement qui bloquera les requêtes suivantes. Mais la lecture seule du compteur, même si elle renvoie un nombre de requêtes supérieur à celui autorisé, ne permet pas de bloquer une requête.

11ème requête :

Lors de la réception de cette dernière requête, Rack Attack consulte les blocklists : il consulte la blocklist de public-get sans succès puis il consulte la blocklist de public-post : cette fois-ci, il y trouve l'ip correspondante. Rack Attack ne prend même pas la peine de lire le compteur : cette fois-ci c'est cuit pour notre jeune bot, la requête ne passera pas. Rack Attack envoie un simple code HTTP 503.

Rappelez-vous, notre jeune bot malveillant est aussi naïf : il pense que la plateforme est hors-service, et s'arrête là. Il s'en va chercher une nouvelle victime.

Note : Dès que Rack Attack reçoit une réponse positive d'une blocklist, il refuse la requête et s'arrête là. Si l'ip du bot avait été dans la blocklist de public-get, la blocklist de public-post n'aurait même pas été consultée pour cette requête.

On peut également remarquer que le compteur n'est pas consulté pour cette requête : il n'est d'ailleurs jamais bloquant. Peu importe la valeur renvoyée par le compteur, la requête ne sera pas bloquée sans écriture dans la blocklist.

Tests rapides : simuler les appels au cache

Maintenant que nous avons compris la façon dont Rack Attack traque et banni les requêtes abusives, nous pouvons mocker les appels et écritures du cache des requêtes et vérifier que le blocage (et le déblocage) sont correctement réalisés par Rack Attack.

Au lieu de simuler l’entièreté du processus, nous allons simplement nous insérer au niveau de la n-eme requête, et faire croire à Rack Attack qu’il s’agit bien de la n-ème requête et non de la première.

Simuler n - 1 requêtes, envoyer réellement la n-ème et observer le blocage

Nous allons mocker un appel au cache en lecture : au lieu de renvoyer nil (pas de requête observée) nous souhaitons qu'il renvoie 9 (déjà n-1 requêtes observées) et expect les appels au cache en écriture et leurs conséquences dans nos tests. Les blocklists étant vides à ce stade, il n’est pas nécessaire de les mocker, elles renverront le résultat attendu.

Note : Cependant, étant donné que nous mockons un appel au cache avec des arguments spécifiques, il faut également expect un appel au cache aux blocklist et demander d’appeler l’original pour ne pas avoir de message d’erreur.

Ensuite on envoie la (pseudo) 10ème requête, celle-ci déclenche le bannissement. On envoie la 11ème et on vérifie que l’on est banni.

Une fois implémenté, voilà le résultat :

Simuler un blocage, observer le déblocage

C'est bon, on sait désormais que Rack Attack bloque correctement les requêtes abusives. Il ne reste plus qu'à vérifier que le déblocage est correctement effectué après BAN_TIME, et on a terminé.

Ce que l'on souhaite maintenant, c'est s'insérer après la n-ème tentative et le déclenchement du blocage.

On implémente cette logique :

On ajoute le setup et on obtient nos tests finaux :